feat(ui): add OrganizationProfileDomainsSection mosaic component

.changeset/mosaic-domains-section.md

@@ -0,0 +1,2 @@
+---
+---

packages/swingset/src/components/DocsViewer.tsx

@@ -17,6 +17,9 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
     'organization-profile-profile-section': dynamic(
       () => import('../stories/organization-profile-profile-section.mdx'),
     ),
+    'organization-profile-domains-section': dynamic(
+      () => import('../stories/organization-profile-domains-section.mdx'),
+    ),
     'organization-profile-leave-section': dynamic(() => import('../stories/organization-profile-leave-section.mdx')),
     'organization-profile-delete-section': dynamic(() => import('../stories/organization-profile-delete-section.mdx')),
   },

packages/swingset/src/lib/registry.ts

@@ -46,6 +46,10 @@ import {
   Default as OrganizationProfileDeleteSectionDefault,
   meta as organizationProfileDeleteSectionMeta,
 } from '../stories/organization-profile-delete-section.stories';
+import {
+  Default as OrganizationProfileDomainsSectionDefault,
+  meta as organizationProfileDomainsSectionMeta,
+} from '../stories/organization-profile-domains-section.stories';
 import {
   Default as OrganizationProfileGeneralPanelDefault,
   meta as organizationProfileGeneralPanelMeta,
@@ -87,6 +91,10 @@ const organizationProfileProfileSectionModule: StoryModule = {
   meta: organizationProfileProfileSectionMeta,
   Default: OrganizationProfileProfileSectionDefault,
 };
+const organizationProfileDomainsSectionModule: StoryModule = {
+  meta: organizationProfileDomainsSectionMeta,
+  Default: OrganizationProfileDomainsSectionDefault,
+};
 const organizationProfileModule: StoryModule = { meta: organizationProfileMeta, Default: OrganizationProfileDefault };
 const organizationProfileGeneralPanelModule: StoryModule = {
   meta: organizationProfileGeneralPanelMeta,
@@ -148,6 +156,7 @@ export const registry: StoryModule[] = [
   organizationProfileGeneralPanelModule,
   organizationProfileApiKeysPanelModule,
   organizationProfileProfileSectionModule,
+  organizationProfileDomainsSectionModule,
   organizationProfileLeaveSectionModule,
   organizationProfileDeleteSectionModule,
   // Blocks

packages/swingset/src/stories/organization-profile-domains-section.mdx

@@ -0,0 +1,18 @@
+import * as OrganizationProfileDomainsSectionStories from './organization-profile-domains-section.stories';
+
+# Organization Profile Domains Section
+
+Manages an organization's domains — lists them, adds and verifies new ones, edits a verified
+domain's enrollment mode, and removes them. It owns each flow's state (three machines) and wires
+the list, the add/verify wizard, the enrollment editor, and the remove confirmation together.
+
+<Story
+  name='Default'
+  storyModule={OrganizationProfileDomainsSectionStories}
+  composition={[
+    { name: 'Button', href: '/components/button', layer: 'Components' },
+    { name: 'Dialog', href: '/components/dialog', layer: 'Components' },
+    { name: 'Input', href: '/components/input', layer: 'Components' },
+    { name: 'Text', href: '/components/text', layer: 'Components' },
+  ]}
+/>

packages/swingset/src/stories/organization-profile-domains-section.stories.tsx

@@ -0,0 +1,113 @@
+/** @jsxImportSource @emotion/react */
+import type { OrganizationDomainResource } from '@clerk/shared/types';
+import { useMachine } from '@clerk/ui/mosaic/machine/useMachine';
+import type { OrganizationProfileEnrollmentOption } from '@clerk/ui/mosaic/organization/organization-profile-domains-section.controller';
+import { OrganizationProfileDomainsSectionView } from '@clerk/ui/mosaic/organization/organization-profile-domains-section.view';
+import { organizationProfileDomainsSectionAddVerifyMachine } from '@clerk/ui/mosaic/organization/organization-profile-domains-section-add-verify.machine';
+import { organizationProfileDomainsSectionEnrollmentMachine } from '@clerk/ui/mosaic/organization/organization-profile-domains-section-enrollment.machine';
+import { organizationProfileDomainsSectionRemoveMachine } from '@clerk/ui/mosaic/organization/organization-profile-domains-section-remove.machine';
+
+import type { StoryMeta } from '@/lib/types';
+
+export const meta: StoryMeta = {
+  group: 'Organization',
+  title: 'OrganizationProfileDomainsSection',
+  source: 'packages/ui/src/mosaic/organization/organization-profile-domains-section.tsx',
+};
+
+// Demo async deps: resolve after a short delay so the loading/saving states are visible.
+const delay = () => new Promise<void>(resolve => setTimeout(resolve, 600));
+
+const ENROLLMENT_OPTIONS: OrganizationProfileEnrollmentOption[] = [
+  {
+    value: 'manual_invitation',
+    label: 'No automatic enrollment',
+    description: 'Users can only be invited manually to the organization.',
+  },
+  {
+    value: 'automatic_invitation',
+    label: 'Automatic invitations',
+    description: 'Users are automatically invited to join the organization when they sign up and can join anytime.',
+  },
+  {
+    value: 'automatic_suggestion',
+    label: 'Automatic suggestions',
+    description: 'Users receive a suggestion to request to join, but must be approved by an admin.',
+  },
+];
+
+// The view reads only id/name/verification/enrollmentMode/pending counts, so a partial fixture
+// is enough. The cast is confined to these swingset demo fixtures.
+const demoDomains = [
+  {
+    id: 'dmn_1',
+    name: 'acme.com',
+    enrollmentMode: 'automatic_invitation',
+    verification: { status: 'verified' },
+    totalPendingInvitations: 3,
+    totalPendingSuggestions: 1,
+  },
+  {
+    id: 'dmn_2',
+    name: 'acme.dev',
+    enrollmentMode: 'manual_invitation',
+    verification: { status: 'unverified' },
+    totalPendingInvitations: 0,
+    totalPendingSuggestions: 0,
+  },
+] as unknown as OrganizationDomainResource[];
+
+export function Default() {
+  const [addVerifySnapshot, sendAddVerify] = useMachine(organizationProfileDomainsSectionAddVerifyMachine, {
+    context: {
+      createDomain: async (name: string) => {
+        await delay();
+        return { id: 'dmn_new', name, verified: false };
+      },
+      prepareVerification: async () => {
+        await delay();
+      },
+      attemptVerification: async () => {
+        await delay();
+        return { verified: true };
+      },
+      updateEnrollmentMode: async () => {
+        await delay();
+      },
+    },
+  });
+
+  const [enrollmentSnapshot, sendEnrollment, enrollmentActor] = useMachine(
+    organizationProfileDomainsSectionEnrollmentMachine,
+    {
+      context: {
+        updateEnrollmentMode: async () => {
+          await delay();
+        },
+      },
+    },
+  );
+
+  const [removeSnapshot, sendRemove] = useMachine(organizationProfileDomainsSectionRemoveMachine, {
+    context: {
+      deleteDomain: async () => {
+        await delay();
+      },
+    },
+  });
+
+  return (
+    <OrganizationProfileDomainsSectionView
+      canManage
+      list={{ data: demoDomains, isLoading: false, hasNextPage: false, fetchNext: () => {} }}
+      enrollmentOptions={ENROLLMENT_OPTIONS}
+      addVerify={{ snapshot: addVerifySnapshot, send: sendAddVerify }}
+      enrollment={{
+        snapshot: enrollmentSnapshot,
+        send: sendEnrollment,
+        canSubmit: enrollmentActor.can({ type: 'SUBMIT' }),
+      }}
+      remove={{ snapshot: removeSnapshot, send: sendRemove }}
+    />
+  );
+}

packages/swingset/src/stories/organization-profile-general-panel.stories.tsx

@@ -4,6 +4,7 @@ import { OrganizationProfileGeneralPanelView } from '@clerk/ui/mosaic/organizati
 import type { StoryMeta } from '@/lib/types';
 
 import { Default as OrganizationProfileDeleteSectionDemo } from './organization-profile-delete-section.stories';
+import { Default as OrganizationProfileDomainsSectionDemo } from './organization-profile-domains-section.stories';
 import { Default as OrganizationProfileLeaveSectionDemo } from './organization-profile-leave-section.stories';
 import { Default as OrganizationProfileProfileSectionDemo } from './organization-profile-profile-section.stories';
 
@@ -17,6 +18,7 @@ export function Default() {
   return (
     <OrganizationProfileGeneralPanelView
       profile={<OrganizationProfileProfileSectionDemo />}
+      domains={<OrganizationProfileDomainsSectionDemo />}
       leaveOrganization={<OrganizationProfileLeaveSectionDemo />}
       deleteOrganization={<OrganizationProfileDeleteSectionDemo />}
     />

packages/ui/src/mosaic/organization/__tests__/organization-profile-domains-section-add-verify.machine.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, it, vi } from 'vitest';
+
+import { createActor } from '../../machine/createActor';
+import { tick } from '../../machines/__tests__/test-utils';
+import type { OrganizationProfileDomainsSectionAddVerifyContext } from '../organization-profile-domains-section-add-verify.machine';
+import { organizationProfileDomainsSectionAddVerifyMachine } from '../organization-profile-domains-section-add-verify.machine';
+
+function start(overrides: Partial<OrganizationProfileDomainsSectionAddVerifyContext> = {}) {
+  const createDomain = vi.fn(() => Promise.resolve({ id: 'dmn_1', name: 'clerk.com', verified: false }));
+  const prepareVerification = vi.fn(() => Promise.resolve());
+  const attemptVerification = vi.fn(() => Promise.resolve({ verified: true }));
+  const updateEnrollmentMode = vi.fn(() => Promise.resolve());
+  const actor = createActor(organizationProfileDomainsSectionAddVerifyMachine, {
+    context: { createDomain, prepareVerification, attemptVerification, updateEnrollmentMode, ...overrides },
+  });
+  actor.start();
+  return { actor, createDomain, prepareVerification, attemptVerification, updateEnrollmentMode };
+}
+
+describe('organizationProfileDomainsSectionAddVerifyMachine', () => {
+  it('OPEN_ADD starts at the name step', () => {
+    const { actor } = start();
+    actor.send({ type: 'OPEN_ADD' });
+    expect(actor.getSnapshot().value).toBe('enteringName');
+  });
+
+  it('guards the name step until a name is entered', () => {
+    const { actor } = start();
+    actor.send({ type: 'OPEN_ADD' });
+    expect(actor.can({ type: 'SUBMIT_NAME' })).toBe(false);
+    actor.send({ type: 'TYPE_NAME', value: 'clerk.com' });
+    expect(actor.can({ type: 'SUBMIT_NAME' })).toBe(true);
+  });
+
+  it('creates the domain, then moves to the email step when not yet verified', async () => {
+    const { actor, createDomain } = start();
+    actor.send({ type: 'OPEN_ADD' });
+    actor.send({ type: 'TYPE_NAME', value: 'clerk.com' });
+    actor.send({ type: 'SUBMIT_NAME' });
+
+    expect(actor.getSnapshot().value).toBe('creating');
+    expect(createDomain).toHaveBeenCalledWith('clerk.com');
+
+    await tick();
+
+    expect(actor.getSnapshot().value).toBe('enteringEmail');
+    expect(actor.getSnapshot().context.domainId).toBe('dmn_1');
+    expect(actor.getSnapshot().context.domainName).toBe('clerk.com');
+  });
+
+  it('skips straight to enrollment when the created domain is already verified', async () => {
+    const createDomain = vi.fn(() => Promise.resolve({ id: 'dmn_1', name: 'clerk.com', verified: true }));
+    const { actor } = start({ createDomain });
+    actor.send({ type: 'OPEN_ADD' });
+    actor.send({ type: 'TYPE_NAME', value: 'clerk.com' });
+    actor.send({ type: 'SUBMIT_NAME' });
+
+    await tick();
+
+    expect(actor.getSnapshot().value).toBe('selectingEnrollment');
+  });
+
+  it('OPEN_VERIFY enters at the email step for an existing domain', () => {
+    const { actor } = start();
+    actor.send({ type: 'OPEN_VERIFY', domain: { id: 'dmn_9', name: 'clerk.dev' } });
+    expect(actor.getSnapshot().value).toBe('enteringEmail');
+    expect(actor.getSnapshot().context.domainId).toBe('dmn_9');
+    expect(actor.getSnapshot().context.domainName).toBe('clerk.dev');
+  });
+
+  it('prepares verification with the affiliation email built from the local part and domain', async () => {
+    const { actor, prepareVerification } = start();
+    actor.send({ type: 'OPEN_VERIFY', domain: { id: 'dmn_9', name: 'clerk.dev' } });
+    actor.send({ type: 'TYPE_EMAIL', value: 'alex' });
+    actor.send({ type: 'SUBMIT_EMAIL' });
+
+    expect(actor.getSnapshot().value).toBe('preparing');
+    expect(prepareVerification).toHaveBeenCalledWith({ domainId: 'dmn_9', affiliationEmailAddress: 'alex@clerk.dev' });
+
+    await tick();
+
+    expect(actor.getSnapshot().value).toBe('enteringCode');
+  });
+
+  it('attempts verification and moves to enrollment on success', async () => {
+    const { actor, attemptVerification } = start();
+    actor.send({ type: 'OPEN_VERIFY', domain: { id: 'dmn_9', name: 'clerk.dev' } });
+    actor.send({ type: 'TYPE_EMAIL', value: 'alex' });
+    actor.send({ type: 'SUBMIT_EMAIL' });
+    await tick();
+    actor.send({ type: 'TYPE_CODE', value: '424242' });
+    actor.send({ type: 'SUBMIT_CODE' });
+
+    expect(actor.getSnapshot().value).toBe('attempting');
+    expect(attemptVerification).toHaveBeenCalledWith({ domainId: 'dmn_9', code: '424242' });
+
+    await tick();
+
+    expect(actor.getSnapshot().value).toBe('selectingEnrollment');
+  });
+
+  it('surfaces an error and stays on the code step when the attempt does not verify', async () => {
+    const attemptVerification = vi.fn(() => Promise.resolve({ verified: false }));
+    const { actor } = start({ attemptVerification });
+    actor.send({ type: 'OPEN_VERIFY', domain: { id: 'dmn_9', name: 'clerk.dev' } });
+    actor.send({ type: 'TYPE_EMAIL', value: 'alex' });
+    actor.send({ type: 'SUBMIT_EMAIL' });
+    await tick();
+    actor.send({ type: 'TYPE_CODE', value: '424242' });
+    actor.send({ type: 'SUBMIT_CODE' });
+    await tick();
+
+    expect(actor.getSnapshot().value).toBe('enteringCode');
+    expect(actor.getSnapshot().context.error).not.toBeNull();
+  });
+
+  it('resends by re-preparing verification from the code step', async () => {
+    const { actor, prepareVerification } = start();
+    actor.send({ type: 'OPEN_VERIFY', domain: { id: 'dmn_9', name: 'clerk.dev' } });
+    actor.send({ type: 'TYPE_EMAIL', value: 'alex' });
+    actor.send({ type: 'SUBMIT_EMAIL' });
+    await tick();
+    expect(actor.getSnapshot().value).toBe('enteringCode');
+
+    actor.send({ type: 'RESEND' });
+    expect(actor.getSnapshot().value).toBe('preparing');
+    await tick();
+    expect(actor.getSnapshot().value).toBe('enteringCode');
+    expect(prepareVerification).toHaveBeenCalledTimes(2);
+  });
+
+  it('goes back to the email step from the code step', async () => {
+    const { actor } = start();
+    actor.send({ type: 'OPEN_VERIFY', domain: { id: 'dmn_9', name: 'clerk.dev' } });
+    actor.send({ type: 'TYPE_EMAIL', value: 'alex' });
+    actor.send({ type: 'SUBMIT_EMAIL' });
+    await tick();
+
+    actor.send({ type: 'BACK' });
+    expect(actor.getSnapshot().value).toBe('enteringEmail');
+  });
+
+  it('saves the selected enrollment mode and closes', async () => {
+    const { actor, updateEnrollmentMode } = start();
+    actor.send({ type: 'OPEN_VERIFY', domain: { id: 'dmn_9', name: 'clerk.dev' } });
+    actor.send({ type: 'TYPE_EMAIL', value: 'alex' });
+    actor.send({ type: 'SUBMIT_EMAIL' });
+    await tick();
+    actor.send({ type: 'TYPE_CODE', value: '424242' });
+    actor.send({ type: 'SUBMIT_CODE' });
+    await tick();
+
+    expect(actor.getSnapshot().value).toBe('selectingEnrollment');
+    expect(actor.can({ type: 'SUBMIT_ENROLLMENT' })).toBe(false);
+
+    actor.send({ type: 'SELECT_MODE', value: 'automatic_invitation' });
+    actor.send({ type: 'SUBMIT_ENROLLMENT' });
+
+    expect(actor.getSnapshot().value).toBe('savingEnrollment');
+    expect(updateEnrollmentMode).toHaveBeenCalledWith({
+      domainId: 'dmn_9',
+      enrollmentMode: 'automatic_invitation',
+      deletePending: false,
+    });
+
+    await tick();
+    expect(actor.getSnapshot().value).toBe('closed');
+  });
+
+  it('surfaces an error and stays on the name step when create fails', async () => {
+    const createDomain = vi.fn(() => Promise.reject(new Error('taken')));
+    const { actor } = start({ createDomain });
+    actor.send({ type: 'OPEN_ADD' });
+    actor.send({ type: 'TYPE_NAME', value: 'clerk.com' });
+    actor.send({ type: 'SUBMIT_NAME' });
+    await tick();
+
+    expect(actor.getSnapshot().value).toBe('enteringName');
+    expect(actor.getSnapshot().context.error).toBe('taken');
+  });
+
+  it('cancels back to closed', () => {
+    const { actor } = start();
+    actor.send({ type: 'OPEN_ADD' });
+    actor.send({ type: 'CANCEL' });
+    expect(actor.getSnapshot().value).toBe('closed');
+  });
+});