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

.changeset/calm-maps-work.md

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

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

@@ -0,0 +1,74 @@
+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,
+    } 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

@@ -53,6 +53,7 @@ import {
   UserOrganizationInvitation,
   Web3Wallet,
 } from './internal';
+import { OrganizationCreationDefaults } from './OrganizationCreationDefaults';
 
 export class User extends BaseResource implements UserResource {
   pathRoot = '/me';
@@ -275,6 +276,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

@@ -344,6 +344,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;
@@ -356,6 +359,7 @@ const createOrganizationSettingsFixtureHelpers = (environment: EnvironmentJSON)
     withOrganizationDomains,
     withForceOrganizationSelection,
     withOrganizationSlug,
+    withOrganizationCreationDefaults,
   };
 };
 

packages/localizations/src/en-US.ts

@@ -884,6 +884,10 @@ export const enUS: LocalizationResource = {
       actionLink: 'Sign out',
       actionText: 'Signed in as {{identifier}}',
     },
+    alerts: {
+      organizationAlreadyExists:
+        'An organization already exists for the detected company name and {{email}}. Join by invitation.',
+    },
   },
   taskResetPassword: {
     formButtonPrimary: 'Reset Password',

packages/shared/src/types/index.ts

@@ -13,6 +13,7 @@ export type * from './customPages';
 export type * from './deletedObject';
 export type * from './devtools';
 export type * from './displayConfig';
+export type * from './elementIds';
 export type * from './emailAddress';
 export type * from './enterpriseAccount';
 export type * from './environment';
@@ -32,6 +33,7 @@ export type * from './localization';
 export type * from './multiDomain';
 export type * from './oauth';
 export type * from './organization';
+export type * from './organizationCreationDefaults';
 export type * from './organizationDomain';
 export type * from './organizationInvitation';
 export type * from './organizationMembership';
@@ -49,7 +51,6 @@ export type * from './protectConfig';
 export type * from './redirects';
 export type * from './resource';
 export type * from './role';
-export type * from './elementIds';
 export type * from './router';
 /**
  * TODO @revamp-hooks: Drop this in the next major release.

packages/shared/src/types/localization.ts

@@ -1314,6 +1314,9 @@ export type __internal_LocalizationResource = {
       title: LocalizationValue;
       subtitle: LocalizationValue;
     };
+    alerts: {
+      organizationAlreadyExists: LocalizationValue<'email'>;
+    };
   };
   taskResetPassword: {
     title: LocalizationValue;

packages/shared/src/types/organizationCreationDefaults.ts

@@ -0,0 +1,34 @@
+import type { ClerkResourceJSON } from './json';
+import type { ClerkResource } from './resource';
+
+export type OrganizationCreationAdvisoryType = 'organization_already_exists';
+
+export type OrganizationCreationAdvisorySeverity = 'warning';
+
+export interface OrganizationCreationDefaultsJSON extends ClerkResourceJSON {
+  advisory: {
+    code: OrganizationCreationAdvisoryType;
+    severity: OrganizationCreationAdvisorySeverity;
+    meta: Record<string, string>;
+  } | null;
+  form: {
+    name: string;
+    slug: string;
+    logo: string | null;
+    blur_hash: string | null;
+  };
+}
+
+export interface OrganizationCreationDefaultsResource extends ClerkResource {
+  advisory: {
+    code: OrganizationCreationAdvisoryType;
+    severity: OrganizationCreationAdvisorySeverity;
+    meta: Record<string, string>;
+  } | null;
+  form: {
+    name: string;
+    slug: string;
+    logo: string | null;
+    blurHash: string | null;
+  };
+}

packages/shared/src/types/organizationSettings.ts

@@ -20,6 +20,9 @@ export interface OrganizationSettingsJSON extends ClerkResourceJSON {
   slug: {
     disabled: boolean;
   };
+  organization_creation_defaults: {
+    enabled: boolean;
+  };
 }
 
 export interface OrganizationSettingsResource extends ClerkResource {
@@ -37,5 +40,8 @@ export interface OrganizationSettingsResource extends ClerkResource {
   slug: {
     disabled: boolean;
   };
+  organizationCreationDefaults: {
+    enabled: boolean;
+  };
   __internal_toSnapshot: () => OrganizationSettingsJSONSnapshot;
 }

packages/shared/src/types/snapshots.ts

@@ -28,6 +28,7 @@ import type {
   VerificationJSON,
   Web3WalletJSON,
 } from './json';
+import type { OrganizationCreationDefaultsJSON } from './organizationCreationDefaults';
 import type { OrganizationSettingsJSON } from './organizationSettings';
 import type { ProtectConfigJSON } from './protectConfig';
 import type { SignInJSON } from './signIn';
@@ -143,6 +144,8 @@ export type OrganizationMembershipJSONSnapshot = OrganizationMembershipJSON;
 
 export type OrganizationSettingsJSONSnapshot = OrganizationSettingsJSON;
 
+export type OrganizationCreationDefaultsJSONSnapshot = OrganizationCreationDefaultsJSON;
+
 export type PasskeyJSONSnapshot = Override<PasskeyJSON, { verification: VerificationJSONSnapshot | null }>;
 
 export type PhoneNumberJSONSnapshot = Override<

packages/shared/src/types/user.ts

@@ -7,6 +7,7 @@ import type { ExternalAccountResource } from './externalAccount';
 import type { ImageResource } from './image';
 import type { UserJSON } from './json';
 import type { OAuthScope } from './oauth';
+import type { OrganizationCreationDefaultsResource } from './organizationCreationDefaults';
 import type { OrganizationInvitationStatus } from './organizationInvitation';
 import type { OrganizationMembershipResource } from './organizationMembership';
 import type { OrganizationSuggestionResource, OrganizationSuggestionStatus } from './organizationSuggestion';
@@ -115,6 +116,7 @@ export interface UserResource extends ClerkResource, BillingPayerMethods {
   getOrganizationSuggestions: (
     params?: GetUserOrganizationSuggestionsParams,
   ) => Promise<ClerkPaginatedResponse<OrganizationSuggestionResource>>;
+  getOrganizationCreationDefaults: () => Promise<OrganizationCreationDefaultsResource>;
   leaveOrganization: (organizationId: string) => Promise<DeletedObjectResource>;
   createTOTP: () => Promise<TOTPResource>;
   verifyTOTP: (params: VerifyTOTPParams) => Promise<TOTPResource>;

packages/ui/src/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}
           />
         }