feat(js,ui): mount and render the directory sync setup flow

.changeset/dir-sync-self-serve-wiring.md

@@ -1,6 +1,7 @@
 ---
 '@clerk/clerk-js': minor
 '@clerk/localizations': minor
+'@clerk/react': minor
 '@clerk/shared': minor
 '@clerk/ui': minor
 ---

packages/clerk-js/bundlewatch.config.json

@@ -1,7 +1,7 @@
 {
   "files": [
-    { "path": "./dist/clerk.js", "maxSize": "553KB" },
-    { "path": "./dist/clerk.browser.js", "maxSize": "79.5KB" },
+    { "path": "./dist/clerk.js", "maxSize": "554KB" },
+    { "path": "./dist/clerk.browser.js", "maxSize": "81KB" },
     { "path": "./dist/clerk.legacy.browser.js", "maxSize": "122KB" },
     { "path": "./dist/clerk.no-rhc.js", "maxSize": "320KB" },
     { "path": "./dist/clerk.native.js", "maxSize": "79KB" },

packages/clerk-js/sandbox/app.ts

@@ -34,6 +34,7 @@ const AVAILABLE_COMPONENTS = [
   'pricingTable',
   'apiKeys',
   'configureSSO',
+  'configureDirectorySync',
   'oauthConsent',
   'oauthDeviceVerification',
   'taskChooseOrganization',
@@ -154,6 +155,7 @@ const componentControls: Record<AvailableComponent, ComponentPropsControl> = {
   pricingTable: buildComponentControls('pricingTable'),
   apiKeys: buildComponentControls('apiKeys'),
   configureSSO: buildComponentControls('configureSSO'),
+  configureDirectorySync: buildComponentControls('configureDirectorySync'),
   oauthConsent: buildComponentControls('oauthConsent'),
   oauthDeviceVerification: buildComponentControls('oauthDeviceVerification'),
   taskChooseOrganization: buildComponentControls('taskChooseOrganization'),
@@ -431,6 +433,10 @@ void (async () => {
       mount: '__internal_mountOAuthDeviceVerification',
       component: 'oauthDeviceVerification',
     },
+    '/configure-directory-sync': {
+      mount: '__internal_mountConfigureDirectorySync',
+      component: 'configureDirectorySync',
+    },
     '/task-choose-organization': {
       mount: 'mountTaskChooseOrganization',
       component: 'taskChooseOrganization',

packages/clerk-js/sandbox/template.html

@@ -313,6 +313,11 @@
             label="Configure SSO"
             component="<ConfigureSSO />"
           ></nav-link>
+          <nav-link
+            href="/configure-directory-sync"
+            label="Configure Directory Sync"
+            component="<ConfigureDirectorySync />"
+          ></nav-link>
           <nav-link
             href="/open-invite-members"
             label="Open invite members"

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

@@ -16,6 +16,7 @@ import {
   disabledEmailAddressAttribute,
   disabledOrganizationAPIKeysFeature,
   disabledOrganizationsFeature,
+  disabledSelfServeDirectorySyncFeature,
   disabledSelfServeSSOFeature,
   disabledUserAPIKeysFeature,
   isSignedInAndSingleSessionModeEnabled,
@@ -1712,6 +1713,76 @@ export class Clerk implements ClerkInterface {
     void this.#clerkUI?.then(ui => ui.ensureMounted()).then(controls => controls.unmountComponent({ node }));
   };
 
+  /**
+   * Mount the Directory Sync onboarding component at the target element.
+   * Directory Sync rides on the self-serve SSO gates: it provisions through
+   * the organization's SSO connection, so the same preconditions apply.
+   *
+   * @param targetNode Target to mount the ConfigureDirectorySync component.
+   * @param props Configuration parameters.
+   * @hidden
+   */
+  public __internal_mountConfigureDirectorySync = (node: HTMLDivElement, props?: ConfigureSSOProps) => {
+    const { isEnabled: isOrganizationsEnabled } = this.__internal_attemptToEnableEnvironmentSetting({
+      for: 'organizations',
+      caller: 'ConfigureDirectorySync',
+      onClose: () => {
+        throw new ClerkRuntimeError(warnings.cannotRenderAnyOrganizationComponent('ConfigureDirectorySync'), {
+          code: CANNOT_RENDER_ORGANIZATIONS_DISABLED_ERROR_CODE,
+        });
+      },
+    });
+
+    if (!isOrganizationsEnabled) {
+      return;
+    }
+
+    const userExists = !noUserExists(this);
+    if (noOrganizationExists(this) && userExists) {
+      if (this.#instanceType === 'development') {
+        throw new ClerkRuntimeError(warnings.createCannotRenderComponentWhenOrgDoesNotExist('ConfigureDirectorySync'), {
+          code: CANNOT_RENDER_ORGANIZATION_MISSING_ERROR_CODE,
+        });
+      }
+      return;
+    }
+
+    if (disabledSelfServeDirectorySyncFeature(this, this.environment)) {
+      if (this.#instanceType === 'development') {
+        throw new ClerkRuntimeError(warnings.cannotRenderConfigureDirectorySyncComponentWhenDisabled, {
+          code: CANNOT_RENDER_SELF_SERVE_SSO_DISABLED_ERROR_CODE,
+        });
+      }
+      return;
+    }
+
+    this.assertComponentsReady(this.#clerkUI);
+    const component = 'ConfigureDirectorySync';
+    void this.#clerkUI
+      .then(ui => ui.ensureMounted({ preloadHint: component }))
+      .then(controls =>
+        controls.mountComponent({
+          name: component,
+          appearanceKey: 'configureSSO',
+          node,
+          props,
+        }),
+      );
+
+    this.telemetry?.record(eventPrebuiltComponentMounted(component, props));
+  };
+
+  /**
+   * Unmount the Directory Sync onboarding component from the target element.
+   * If there is no component mounted at the target node, results in a noop.
+   *
+   * @param targetNode Target node to unmount the ConfigureDirectorySync component from.
+   * @hidden
+   */
+  public __internal_unmountConfigureDirectorySync = (node: HTMLDivElement) => {
+    void this.#clerkUI?.then(ui => ui.ensureMounted()).then(controls => controls.unmountComponent({ node }));
+  };
+
   public mountTaskChooseOrganization = (node: HTMLDivElement, props?: TaskChooseOrganizationProps) => {
     const { isEnabled: isOrganizationsEnabled } = this.__internal_attemptToEnableEnvironmentSetting({
       for: 'organizations',

packages/react/src/isomorphicClerk.ts

@@ -166,6 +166,7 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
   private premountPricingTableNodes = new Map<HTMLDivElement, PricingTableProps | undefined>();
   private premountAPIKeysNodes = new Map<HTMLDivElement, APIKeysProps | undefined>();
   private premountConfigureSSONodes = new Map<HTMLDivElement, ConfigureSSOProps | undefined>();
+  private premountConfigureDirectorySyncNodes = new Map<HTMLDivElement, ConfigureSSOProps | undefined>();
   private premountOAuthConsentNodes = new Map<HTMLDivElement, __internal_OAuthConsentProps | undefined>();
   private premountOAuthDeviceVerificationNodes = new Map<HTMLDivElement, OAuthDeviceVerificationProps | undefined>();
   private premountTaskChooseOrganizationNodes = new Map<HTMLDivElement, TaskChooseOrganizationProps | undefined>();
@@ -801,6 +802,10 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
       clerkjs.__internal_mountConfigureSSO(node, props);
     });
 
+    this.premountConfigureDirectorySyncNodes.forEach((props, node) => {
+      clerkjs.__internal_mountConfigureDirectorySync(node, props);
+    });
+
     this.premountOAuthConsentNodes.forEach((props, node) => {
       clerkjs.__internal_mountOAuthConsent(node, props);
     });
@@ -1387,6 +1392,22 @@ export class IsomorphicClerk implements IsomorphicLoadedClerk {
     }
   };
 
+  __internal_mountConfigureDirectorySync = (node: HTMLDivElement, props?: ConfigureSSOProps): void => {
+    if (this.clerkjs && this.loaded) {
+      this.clerkjs.__internal_mountConfigureDirectorySync(node, props);
+    } else {
+      this.premountConfigureDirectorySyncNodes.set(node, props);
+    }
+  };
+
+  __internal_unmountConfigureDirectorySync = (node: HTMLDivElement): void => {
+    if (this.clerkjs && this.loaded) {
+      this.clerkjs.__internal_unmountConfigureDirectorySync(node);
+    } else {
+      this.premountConfigureDirectorySyncNodes.delete(node);
+    }
+  };
+
   __internal_mountOAuthConsent = (node: HTMLDivElement, props?: OAuthConsentProps) => {
     if (this.clerkjs && this.loaded) {
       this.clerkjs.__internal_mountOAuthConsent(node, props);

packages/shared/src/internal/clerk-js/componentGuards.ts

@@ -50,6 +50,13 @@ export const disabledSelfServeSSOFeature: ComponentGuard = (clerk, environment)
   return !environment?.userSettings.enterpriseSSO.self_serve_sso || !clerk.organization?.selfServeSSOEnabled;
 };
 
+export const disabledSelfServeDirectorySyncFeature: ComponentGuard = (clerk, environment) => {
+  return (
+    disabledSelfServeSSOFeature(clerk, environment) ||
+    !environment?.userSettings.enterpriseSSO.self_serve_directory_sync
+  );
+};
+
 export const disabledEmailAddressAttribute: ComponentGuard = (_, environment) => {
   return !environment?.userSettings.attributes.email_address?.enabled;
 };

packages/shared/src/internal/clerk-js/warnings.ts

@@ -12,15 +12,16 @@ const createMessageForDisabledOrganizations = (
     | 'OrganizationList'
     | 'CreateOrganization'
     | 'TaskChooseOrganization'
-    | 'ConfigureSSO',
+    | 'ConfigureSSO'
+    | 'ConfigureDirectorySync',
 ) => {
   return formatWarning(
     `The <${componentName}/> cannot be rendered when the feature is turned off. Visit 'dashboard.clerk.com' to enable the feature. Since the feature is turned off, this is no-op.`,
   );
 };
 
 const createCannotRenderComponentWhenOrgDoesNotExist = (
-  componentName: 'OrganizationProfile' | 'InviteMembers' | 'ConfigureSSO',
+  componentName: 'OrganizationProfile' | 'InviteMembers' | 'ConfigureSSO' | 'ConfigureDirectorySync',
 ) => {
   return formatWarning(
     `<${componentName}/> cannot render unless an organization is active. Since no organization is currently active, this is no-op.`,
@@ -88,6 +89,8 @@ const warnings = {
     '<ConfigureSSO/> cannot render unless a user is signed in. Since no user is signed in, this is no-op.',
   cannotRenderConfigureSSOComponentWhenDisabled:
     'The <ConfigureSSO/> component cannot be rendered when self-serve SSO is disabled. Visit `https://dashboard.clerk.com` to enable the feature. Since self-serve SSO is disabled, this is no-op.',
+  cannotRenderConfigureDirectorySyncComponentWhenDisabled:
+    'The <ConfigureDirectorySync/> component cannot be rendered when self-serve Directory Sync is disabled. Since self-serve Directory Sync is disabled, this is no-op.',
   cannotRenderConfigureSSOComponentWhenEmailAddressDisabled:
     'The <ConfigureSSO/> component cannot be rendered when email addresses are disabled on the instance. Visit `https://dashboard.clerk.com` to enable email addresses. Since email addresses are disabled, this is no-op.',
 };

packages/shared/src/types/clerk.ts

@@ -816,6 +816,24 @@ export interface Clerk {
    */
   __internal_unmountConfigureSSO: (targetNode: HTMLDivElement) => void;
 
+  /**
+   * Mount a configure Directory Sync component at the target element.
+   *
+   * @param targetNode - Target to mount the ConfigureDirectorySync component.
+   * @param props - Configuration parameters.
+   * @hidden
+   */
+  __internal_mountConfigureDirectorySync: (targetNode: HTMLDivElement, props?: ConfigureSSOProps) => void;
+
+  /**
+   * Unmount a configure Directory Sync component from the target element.
+   * If there is no component mounted at the target node, results in a noop.
+   *
+   * @param targetNode - Target node to unmount the ConfigureDirectorySync component from.
+   * @hidden
+   */
+  __internal_unmountConfigureDirectorySync: (targetNode: HTMLDivElement) => void;
+
   /**
    * Mounts a OAuth consent component at the target element.
    *
@@ -1984,6 +2002,7 @@ export type __internal_AttemptToEnableEnvironmentSettingParams = {
     | 'CreateOrganization'
     | 'TaskChooseOrganization'
     | 'ConfigureSSO'
+    | 'ConfigureDirectorySync'
     | 'useOrganizationList'
     | 'useOrganization';
   onClose?: () => void;

packages/shared/src/types/elementIds.ts

@@ -63,6 +63,7 @@ export type ProfileSectionId =
   | 'subscriptionsList'
   | 'paymentMethods'
   | 'sso'
+  | 'directorySync'
   | 'ssoStatus'
   | 'enableSso'
   | 'ssoDomain'

packages/shared/src/types/localization.ts

@@ -1206,6 +1206,24 @@ export type __internal_LocalizationResource = {
         tooltip__noRole: LocalizationValue;
         tooltipLabel: LocalizationValue;
       };
+      directorySyncSection: {
+        title: LocalizationValue;
+        badge__unconfigured: LocalizationValue;
+        badge__ssoRequired: LocalizationValue;
+        badge__active: LocalizationValue;
+        badge__inactive: LocalizationValue;
+        description: LocalizationValue;
+        primaryButton__startConfiguration: LocalizationValue;
+        menuAction__edit: LocalizationValue;
+        menuAction__activate: LocalizationValue;
+        menuAction__deactivate: LocalizationValue;
+        menuAction__remove: LocalizationValue;
+        removeDialog: {
+          title: LocalizationValue;
+          subtitle: LocalizationValue;
+          confirmButton: LocalizationValue;
+        };
+      };
     };
     membersPage: {
       detailsTitle__emptyRow: LocalizationValue;

packages/ui/src/components/ConfigureDirectorySync/ConfigureDirectorySync.tsx

@@ -0,0 +1,48 @@
+import type { ConfigureSSOProps } from '@clerk/shared/types';
+import React from 'react';
+
+import { withCoreUserGuard } from '@/contexts';
+import { Flow } from '@/customizables';
+import { withCardStateProvider } from '@/elements/contexts';
+import { ProfileCard } from '@/elements/ProfileCard';
+import { Route, Switch } from '@/router';
+
+import { ConfigureSSOProtect } from '../ConfigureSSO/ConfigureSSO';
+import { ConfigureDirectorySyncWizard } from './ConfigureDirectorySyncWizard';
+import { DirectorySyncNavbar } from './DirectorySyncNavbar';
+
+/**
+ * Standalone host for the Directory Sync onboarding wizard, mirroring
+ * ConfigureSSO's shell. Reuses the configureSSO flow id/appearance until the
+ * flow gets its own appearance surface.
+ */
+const ConfigureDirectorySyncInternal = (): JSX.Element => {
+  return (
+    <Flow.Root flow='configureSSO'>
+      <Switch>
+        <Route>
+          <AuthenticatedContent />
+        </Route>
+      </Switch>
+    </Flow.Root>
+  );
+};
+
+const AuthenticatedContent = withCoreUserGuard(() => {
+  const contentRef = React.useRef<HTMLDivElement>(null);
+
+  return (
+    <ProfileCard.Root
+      sx={t => ({ display: 'grid', gridTemplateColumns: '1fr 3fr', height: t.sizes.$176, overflow: 'hidden' })}
+    >
+      <DirectorySyncNavbar contentRef={contentRef}>
+        <ConfigureSSOProtect>
+          <ConfigureDirectorySyncWizard />
+        </ConfigureSSOProtect>
+      </DirectorySyncNavbar>
+    </ProfileCard.Root>
+  );
+});
+
+export const ConfigureDirectorySync: React.ComponentType<ConfigureSSOProps> =
+  withCardStateProvider(ConfigureDirectorySyncInternal);