feat(clerk-js,shared,localizations): Surface organization creation defaults

.changeset/three-impalas-push.md

@@ -0,0 +1,7 @@
+---
+'@clerk/localizations': minor
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+Surface organization creation defaults with prefilled form fields and advisory warnings

packages/clerk-js/bundlewatch.config.json

@@ -1,11 +1,11 @@
 {
   "files": [
-    { "path": "./dist/clerk.js", "maxSize": "924KB" },
+    { "path": "./dist/clerk.js", "maxSize": "928KB" },
     { "path": "./dist/clerk.browser.js", "maxSize": "87KB" },
     { "path": "./dist/clerk.legacy.browser.js", "maxSize": "129KB" },
     { "path": "./dist/clerk.headless*.js", "maxSize": "66KB" },
     { "path": "./dist/ui-common*.js", "maxSize": "123KB" },
-    { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "123KB" },
+    { "path": "./dist/ui-common*.legacy.*.js", "maxSize": "126KB" },
     { "path": "./dist/vendors*.js", "maxSize": "50KB" },
     { "path": "./dist/coinbase*.js", "maxSize": "38KB" },
     { "path": "./dist/stripe-vendors*.js", "maxSize": "1KB" },

packages/clerk-js/src/core/resources/OrganizationCreationDefaults.ts

@@ -0,0 +1,80 @@
+import type {
+  OrganizationCreationAdvisorySeverity,
+  OrganizationCreationAdvisoryType,
+  OrganizationCreationDefaultsJSON,
+  OrganizationCreationDefaultsJSONSnapshot,
+  OrganizationCreationDefaultsResource,
+} from '@clerk/shared/types';
+
+import { BaseResource } from './internal';
+
+export class OrganizationCreationDefaults extends BaseResource implements OrganizationCreationDefaultsResource {
+  advisory: {
+    code: OrganizationCreationAdvisoryType;
+    severity: OrganizationCreationAdvisorySeverity;
+    meta: Record<string, string>;
+  } | null = null;
+  form: {
+    name: string;
+    slug: string;
+    logo: string | null;
+    blurHash: string | null;
+  } = {
+    name: '',
+    slug: '',
+    logo: null,
+    blurHash: null,
+  };
+
+  public constructor(data: OrganizationCreationDefaultsJSON | OrganizationCreationDefaultsJSONSnapshot | null = null) {
+    super();
+    this.fromJSON(data);
+  }
+
+  protected fromJSON(data: OrganizationCreationDefaultsJSON | OrganizationCreationDefaultsJSONSnapshot | null): this {
+    if (!data) {
+      return this;
+    }
+
+    if (data.advisory) {
+      this.advisory = this.withDefault(data.advisory, this.advisory ?? null);
+    }
+
+    if (data.form) {
+      this.form.name = this.withDefault(data.form.name, this.form.name);
+      this.form.slug = this.withDefault(data.form.slug, this.form.slug);
+      this.form.logo = this.withDefault(data.form.logo, this.form.logo);
+      this.form.blurHash = this.withDefault(data.form.blur_hash, this.form.blurHash);
+    }
+
+    return this;
+  }
+
+  static async retrieve(): Promise<OrganizationCreationDefaultsResource> {
+    return await BaseResource._fetch({
+      path: '/me/organization_creation_defaults',
+      method: 'GET',
+    }).then(res => {
+      const data = res?.response as unknown as OrganizationCreationDefaultsJSON;
+      return new OrganizationCreationDefaults(data);
+    });
+  }
+
+  public __internal_toSnapshot(): OrganizationCreationDefaultsJSONSnapshot {
+    return {
+      advisory: this.advisory
+        ? {
+            code: this.advisory.code,
+            meta: this.advisory.meta,
+            severity: this.advisory.severity,
+          }
+        : null,
+      form: {
+        name: this.form.name,
+        slug: this.form.slug,
+        logo: this.form.logo,
+        blur_hash: this.form.blurHash,
+      },
+    } as unknown as OrganizationCreationDefaultsJSONSnapshot;
+  }
+}

packages/clerk-js/src/core/resources/OrganizationSettings.ts

@@ -23,6 +23,11 @@ export class OrganizationSettings extends BaseResource implements OrganizationSe
   } = {
     disabled: false,
   };
+  organizationCreationDefaults: {
+    enabled: boolean;
+  } = {
+    enabled: false,
+  };
   enabled: boolean = false;
   maxAllowedMemberships: number = 1;
   forceOrganizationSelection!: boolean;
@@ -51,6 +56,13 @@ export class OrganizationSettings extends BaseResource implements OrganizationSe
       this.slug.disabled = this.withDefault(data.slug.disabled, this.slug.disabled);
     }
 
+    if (data.organization_creation_defaults) {
+      this.organizationCreationDefaults.enabled = this.withDefault(
+        data.organization_creation_defaults.enabled,
+        this.organizationCreationDefaults.enabled,
+      );
+    }
+
     this.enabled = this.withDefault(data.enabled, this.enabled);
     this.maxAllowedMemberships = this.withDefault(data.max_allowed_memberships, this.maxAllowedMemberships);
     this.forceOrganizationSelection = this.withDefault(

packages/clerk-js/src/core/resources/User.ts

@@ -55,6 +55,7 @@ import {
   UserOrganizationInvitation,
   Web3Wallet,
 } from './internal';
+import { OrganizationCreationDefaults } from './OrganizationCreationDefaults';
 
 export class User extends BaseResource implements UserResource {
   pathRoot = '/me';
@@ -280,6 +281,8 @@ export class User extends BaseResource implements UserResource {
   getOrganizationMemberships: GetOrganizationMemberships = retrieveMembership =>
     OrganizationMembership.retrieve(retrieveMembership);
 
+  getOrganizationCreationDefaults = () => OrganizationCreationDefaults.retrieve();
+
   leaveOrganization = async (organizationId: string): Promise<DeletedObjectResource> => {
     const json = (
       await BaseResource._fetch<DeletedObjectJSON>({

packages/clerk-js/src/test/fixture-helpers.ts

@@ -346,6 +346,9 @@ const createOrganizationSettingsFixtureHelpers = (environment: EnvironmentJSON)
   const withOrganizationSlug = (enabled = false) => {
     os.slug.disabled = !enabled;
   };
+  const withOrganizationCreationDefaults = (enabled = false) => {
+    os.organization_creation_defaults.enabled = enabled;
+  };
 
   const withOrganizationDomains = (modes?: OrganizationEnrollmentMode[], defaultRole?: string) => {
     os.domains.enabled = true;
@@ -358,6 +361,7 @@ const createOrganizationSettingsFixtureHelpers = (environment: EnvironmentJSON)
     withOrganizationDomains,
     withForceOrganizationSelection,
     withOrganizationSlug,
+    withOrganizationCreationDefaults,
   };
 };
 

packages/clerk-js/src/test/fixtures.ts

@@ -92,6 +92,9 @@ const createBaseOrganizationSettings = (): OrganizationSettingsJSON => {
     slug: {
       disabled: true,
     },
+    organization_creation_defaults: {
+      enabled: false,
+    },
   } as unknown as OrganizationSettingsJSON;
 };
 

packages/clerk-js/src/ui/components/OrganizationProfile/OrganizationProfileAvatarUploader.tsx

@@ -8,9 +8,13 @@ import { Col, descriptors, Text } from '../../customizables';
 import { localizationKeys } from '../../localization';
 
 export const OrganizationProfileAvatarUploader = (
-  props: Omit<AvatarUploaderProps, 'avatarPreview' | 'title'> & { organization: Partial<OrganizationResource> },
+  props: Omit<AvatarUploaderProps, 'avatarPreview' | 'title'> & {
+    organization: Partial<OrganizationResource>;
+    /** Shows a loading spinner while the image is loading */
+    showLoadingSpinner?: boolean;
+  },
 ) => {
-  const { organization, ...rest } = props;
+  const { organization, showLoadingSpinner, ...rest } = props;
 
   return (
     <Col elementDescriptor={descriptors.organizationAvatarUploaderContainer}>
@@ -28,6 +32,7 @@ export const OrganizationProfileAvatarUploader = (
         avatarPreview={
           <OrganizationAvatar
             size={theme => theme.sizes.$16}
+            showLoadingSpinner={showLoadingSpinner}
             {...organization}
           />
         }

packages/clerk-js/src/ui/components/SessionTasks/tasks/TaskChooseOrganization/CreateOrganizationScreen.tsx

@@ -1,22 +1,28 @@
 import { useOrganizationList } from '@clerk/shared/react';
-import type { CreateOrganizationParams } from '@clerk/shared/types';
+import type { CreateOrganizationParams, OrganizationCreationDefaultsResource } from '@clerk/shared/types';
+import { useState } from 'react';
 
+import { OrganizationProfileAvatarUploader } from '@/ui/components/OrganizationProfile/OrganizationProfileAvatarUploader';
 import { useEnvironment } from '@/ui/contexts';
 import { useSessionTasksContext, useTaskChooseOrganizationContext } from '@/ui/contexts/components/SessionTasks';
-import { localizationKeys } from '@/ui/customizables';
+import { Icon, localizationKeys } from '@/ui/customizables';
 import { useCardState } from '@/ui/elements/contexts';
 import { Form } from '@/ui/elements/Form';
 import { FormButtonContainer } from '@/ui/elements/FormButtons';
 import { FormContainer } from '@/ui/elements/FormContainer';
 import { Header } from '@/ui/elements/Header';
+import { IconButton } from '@/ui/elements/IconButton';
+import { Upload } from '@/ui/icons';
 import { createSlug } from '@/ui/utils/createSlug';
 import { handleError } from '@/ui/utils/errorHandler';
 import { useFormControl } from '@/ui/utils/useFormControl';
 
 import { organizationListParams } from '../../../OrganizationSwitcher/utils';
+import { OrganizationCreationDefaultsAlert } from './OrganizationCreationDefaultsAlert';
 
 type CreateOrganizationScreenProps = {
   onCancel?: () => void;
+  organizationCreationDefaults?: OrganizationCreationDefaultsResource | null;
 };
 
 export const CreateOrganizationScreen = (props: CreateOrganizationScreenProps) => {
@@ -27,13 +33,14 @@ export const CreateOrganizationScreen = (props: CreateOrganizationScreenProps) =
     userMemberships: organizationListParams.userMemberships,
   });
   const { organizationSettings } = useEnvironment();
+  const [file, setFile] = useState<File | null>();
 
-  const nameField = useFormControl('name', '', {
+  const nameField = useFormControl('name', props.organizationCreationDefaults?.form?.name ?? '', {
     type: 'text',
     label: localizationKeys('taskChooseOrganization.createOrganization.formFieldLabel__name'),
     placeholder: localizationKeys('taskChooseOrganization.createOrganization.formFieldInputPlaceholder__name'),
   });
-  const slugField = useFormControl('slug', '', {
+  const slugField = useFormControl('slug', props.organizationCreationDefaults?.form?.slug ?? '', {
     type: 'text',
     label: localizationKeys('taskChooseOrganization.createOrganization.formFieldLabel__slug'),
     placeholder: localizationKeys('taskChooseOrganization.createOrganization.formFieldInputPlaceholder__slug'),
@@ -57,6 +64,15 @@ export const CreateOrganizationScreen = (props: CreateOrganizationScreenProps) =
 
       const organization = await createOrganization(createOrgParams);
 
+      if (file) {
+        await organization.setLogo({ file });
+      } else if (defaultLogoUrl) {
+        const response = await fetch(defaultLogoUrl);
+        const blob = await response.blob();
+        const logoFile = new File([blob], 'logo', { type: blob.type });
+        await organization.setLogo({ file: logoFile });
+      }
+
       await setActive({
         organization,
         navigate: async ({ session }) => {
@@ -77,7 +93,13 @@ export const CreateOrganizationScreen = (props: CreateOrganizationScreenProps) =
     slugField.setValue(val);
   };
 
+  const onAvatarRemove = () => {
+    card.setIdle();
+    return setFile(null);
+  };
+
   const isSubmitButtonDisabled = !nameField.value || !isLoaded;
+  const defaultLogoUrl = file === undefined ? props.organizationCreationDefaults?.form?.logo : undefined;
 
   return (
     <>
@@ -90,6 +112,44 @@ export const CreateOrganizationScreen = (props: CreateOrganizationScreenProps) =
       </Header.Root>
       <FormContainer sx={t => ({ padding: `${t.space.$none} ${t.space.$10} ${t.space.$8}` })}>
         <Form.Root onSubmit={onSubmit}>
+          <OrganizationCreationDefaultsAlert organizationCreationDefaults={props.organizationCreationDefaults} />
+          <OrganizationProfileAvatarUploader
+            organization={{ name: nameField.value, imageUrl: defaultLogoUrl ?? undefined }}
+            onAvatarChange={async file => await setFile(file)}
+            onAvatarRemove={file || defaultLogoUrl ? onAvatarRemove : null}
+            showLoadingSpinner={!!defaultLogoUrl}
+            avatarPreviewPlaceholder={
+              <IconButton
+                variant='ghost'
+                aria-label='Upload organization logo'
+                icon={
+                  <Icon
+                    size='md'
+                    icon={Upload}
+                    sx={t => ({
+                      color: t.colors.$colorMutedForeground,
+                      transitionDuration: t.transitionDuration.$controls,
+                    })}
+                  />
+                }
+                sx={t => ({
+                  width: t.sizes.$16,
+                  height: t.sizes.$16,
+                  borderRadius: t.radii.$md,
+                  borderWidth: t.borderWidths.$normal,
+                  borderStyle: t.borderStyles.$dashed,
+                  borderColor: t.colors.$borderAlpha200,
+                  backgroundColor: t.colors.$neutralAlpha50,
+                  ':hover': {
+                    backgroundColor: t.colors.$neutralAlpha50,
+                    svg: {
+                      transform: 'scale(1.2)',
+                    },
+                  },
+                })}
+              />
+            }
+          />
           <Form.ControlRow elementId={nameField.id}>
             <Form.PlainInput
               {...nameField.props}

packages/clerk-js/src/ui/components/SessionTasks/tasks/TaskChooseOrganization/OrganizationCreationDefaultsAlert.tsx

@@ -0,0 +1,41 @@
+import type { OrganizationCreationDefaultsResource } from '@clerk/shared/types';
+
+import { localizationKeys, Text } from '@/ui/customizables';
+import { Alert } from '@/ui/primitives';
+
+export function OrganizationCreationDefaultsAlert({
+  organizationCreationDefaults,
+}: {
+  organizationCreationDefaults?: OrganizationCreationDefaultsResource | null;
+}) {
+  const localizationKey = advisoryToLocalizationKey(organizationCreationDefaults?.advisory);
+  if (!localizationKey) {
+    return null;
+  }
+
+  return (
+    <Alert colorScheme='warning'>
+      <Text
+        colorScheme='warning'
+        localizationKey={localizationKey}
+        variant='caption'
+      />
+    </Alert>
+  );
+}
+
+const advisoryToLocalizationKey = (advisory?: OrganizationCreationDefaultsResource['advisory']) => {
+  if (!advisory) {
+    return null;
+  }
+
+  switch (advisory.code) {
+    case 'organization_already_exists':
+      return localizationKeys('taskChooseOrganization.alerts.organizationAlreadyExists', {
+        organizationDomain: advisory.meta.organization_domain,
+        organizationName: advisory.meta.organization_name,
+      });
+    default:
+      return null;
+  }
+};