feat(ui): add profile email verification and management flows

.changeset/tidy-emails-confirm.md

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

packages/swingset/src/lib/registry.ts

@@ -188,8 +188,13 @@ import {
   Overlay as UserProfileOverlay,
 } from '../stories/user-profile.stories';
 import {
+  AddEmailFails as UserProfileAccountSectionAddEmailFails,
   AddPhoneFails as UserProfileAccountSectionAddPhoneFails,
   Default as UserProfileAccountSectionDefault,
+  EmailLinkResendFails as UserProfileAccountSectionEmailLinkResendFails,
+  EmailLinkVerification as UserProfileAccountSectionEmailLinkVerification,
+  EmailSsoConnectFails as UserProfileAccountSectionEmailSsoConnectFails,
+  EmailSsoVerification as UserProfileAccountSectionEmailSsoVerification,
   meta as userProfileAccountSectionMeta,
   MultipleAccounts as UserProfileAccountSectionMultipleAccounts,
 } from '../stories/user-profile-account-section.stories';
@@ -469,6 +474,11 @@ const userProfileAccountSectionModule: StoryModule = {
   Default: UserProfileAccountSectionDefault,
   MultipleAccounts: UserProfileAccountSectionMultipleAccounts,
   AddPhoneFails: UserProfileAccountSectionAddPhoneFails,
+  AddEmailFails: UserProfileAccountSectionAddEmailFails,
+  EmailLinkVerification: UserProfileAccountSectionEmailLinkVerification,
+  EmailLinkResendFails: UserProfileAccountSectionEmailLinkResendFails,
+  EmailSsoVerification: UserProfileAccountSectionEmailSsoVerification,
+  EmailSsoConnectFails: UserProfileAccountSectionEmailSsoConnectFails,
 };
 const userProfileProfilePanelModule: StoryModule = {
   meta: userProfileProfilePanelMeta,

packages/swingset/src/stories/fixtures/user-profile-add-email.ts

@@ -0,0 +1,28 @@
+import type { UserProfileAccountSectionViewProps } from '@clerk/ui/mosaic/user-profile/user-profile-account-section/user-profile-account-section.view';
+import type { UserProfileAddEmailDialogProps } from '@clerk/ui/mosaic/user-profile/user-profile-account-section/user-profile-add-email.dialog';
+
+interface FixtureOptions {
+  failAt?: UserProfileAddEmailDialogProps['step'];
+  onVerified?: (emailAddress: string) => void;
+}
+
+export function createUserProfileAddEmailFixture({ failAt, onVerified }: FixtureOptions = {}): Pick<
+  UserProfileAccountSectionViewProps,
+  'onSendEmailCode' | 'onVerifyEmailCode'
+> {
+  return {
+    onSendEmailCode: async () => {
+      await new Promise(resolve => setTimeout(resolve, 700));
+      if (failAt === 'email') {
+        throw new Error('We couldn’t send a code. Try again.');
+      }
+    },
+    onVerifyEmailCode: async (emailAddress, code) => {
+      await new Promise(resolve => setTimeout(resolve, 700));
+      if (failAt === 'verify' || code === '000000') {
+        throw new Error('That code is incorrect. Try again.');
+      }
+      onVerified?.(emailAddress);
+    },
+  };
+}

packages/swingset/src/stories/fixtures/user-profile-verify-email-link.ts

@@ -0,0 +1,47 @@
+import { useEffect, useState } from 'react';
+
+export function useUserProfileVerifyEmailLinkFixture({ failResend = false } = {}) {
+  const [open, setOpen] = useState(false);
+  const [resendSeconds, setResendSeconds] = useState(12);
+  const [isResending, setIsResending] = useState(false);
+  const [errorMessage, setErrorMessage] = useState<string>();
+
+  useEffect(() => {
+    if (!open) {
+      return;
+    }
+    if (isResending) {
+      const timer = setTimeout(() => {
+        setIsResending(false);
+        if (failResend) {
+          setErrorMessage('Unable to send the verification link. Try again.');
+        } else {
+          setResendSeconds(12);
+        }
+      }, 700);
+      return () => clearTimeout(timer);
+    }
+    if (resendSeconds > 0) {
+      const timer = setTimeout(() => setResendSeconds(seconds => seconds - 1), 1000);
+      return () => clearTimeout(timer);
+    }
+  }, [open, isResending, resendSeconds, failResend]);
+
+  return {
+    open,
+    emailAddress: 'example@email.com',
+    resendSeconds,
+    isResending,
+    errorMessage,
+    onOpenChange: (value: boolean) => {
+      setOpen(value);
+      setResendSeconds(12);
+      setIsResending(false);
+      setErrorMessage(undefined);
+    },
+    onResend: () => {
+      setErrorMessage(undefined);
+      setIsResending(true);
+    },
+  };
+}

packages/swingset/src/stories/fixtures/user-profile-verify-email-sso.ts

@@ -0,0 +1,43 @@
+import { useEffect, useState } from 'react';
+
+export function useUserProfileVerifyEmailSsoFixture({ failConnect = false } = {}) {
+  const [open, setOpen] = useState(false);
+  const [isConnecting, setIsConnecting] = useState(false);
+  const [errorMessage, setErrorMessage] = useState<string>();
+
+  useEffect(() => {
+    if (!isConnecting) {
+      return;
+    }
+    const timer = setTimeout(() => {
+      setIsConnecting(false);
+      if (failConnect) {
+        setErrorMessage('Unable to connect to Okta. Try again.');
+      } else {
+        setOpen(false);
+      }
+    }, 1200);
+    return () => clearTimeout(timer);
+  }, [isConnecting, failConnect]);
+
+  return {
+    open,
+    emailAddress: 'example@email.com',
+    connection: {
+      provider: 'Okta SSO',
+      domain: 'acme.co',
+      iconUrl: 'https://img.clerk.com/static/okta.svg',
+    },
+    isConnecting,
+    errorMessage,
+    onOpenChange: (value: boolean) => {
+      setOpen(value);
+      setIsConnecting(false);
+      setErrorMessage(undefined);
+    },
+    onConnect: () => {
+      setErrorMessage(undefined);
+      setIsConnecting(true);
+    },
+  };
+}

packages/swingset/src/stories/fixtures/user-profile.ts

@@ -13,12 +13,13 @@ import type {
 import { useMemo, useState } from 'react';
 
 import { usePreviewImage } from './use-preview-image';
+import { createUserProfileAddEmailFixture } from './user-profile-add-email';
 import { createUserProfileAddPhoneFixture } from './user-profile-add-phone';
 import { useUserProfileEditNameFixture } from './user-profile-edit-name';
 import { useUserProfileEditUsernameFixture } from './user-profile-edit-username';
 
 export interface UserProfileFixtureOptions {
-  /** Replaces the default "append an address" behaviour, e.g. to open a real prompt. */
+  /** Replaces the default OTP flow, e.g. for a custom dialog example. */
   onAddEmail?: () => void;
 }
 
@@ -111,6 +112,9 @@ export function useUserProfileFixture({ onAddEmail }: UserProfileFixtureOptions
 
   const addEmail = (value: string) =>
     setEmails(current => [...current, { id: `email_${Date.now()}`, value, isVerified: false }]);
+  const emailFlow = createUserProfileAddEmailFixture({
+    onVerified: value => setEmails(current => [...current, { id: `email_${Date.now()}`, value, isVerified: true }]),
+  });
 
   const pages: UserProfileViewProps['pages'] = {
     account: {
@@ -121,7 +125,9 @@ export function useUserProfileFixture({ onAddEmail }: UserProfileFixtureOptions
       imageUrl,
       emails,
       phones,
-      onAddEmail: onAddEmail ?? (() => addEmail(`preston+${emails.length}@clerk.dev`)),
+      onAddEmail,
+      onSendEmailCode: onAddEmail ? undefined : emailFlow.onSendEmailCode,
+      onVerifyEmailCode: onAddEmail ? undefined : emailFlow.onVerifyEmailCode,
       ...createUserProfileAddPhoneFixture({
         onVerified: value => setPhones(current => [...current, { id: `phone_${Date.now()}`, value, isVerified: true }]),
       }),

packages/swingset/src/stories/user-profile-account-section.mdx

@@ -21,6 +21,10 @@ Entering or pasting six digits submits automatically. Use `000000` to see an inc
 
 ## Multiple accounts
 
+**Add email** opens email entry followed by a six-digit verification code. Resend is available after
+the countdown. In this preview, `000000` shows an incorrect-code error; another six-digit code adds
+the verified address.
+
 <Story
   name='MultipleAccounts'
   storyModule={Stories}
@@ -30,6 +34,10 @@ Entering or pasting six digits submits automatically. Use `000000` to see an inc
     { name: 'Button', href: '/components/button', layer: 'Components' },
     { name: 'Badge', href: '/components/badge', layer: 'Components' },
     { name: 'Icon', href: '/components/icon', layer: 'Components' },
+    { name: 'Dialog', href: '/components/dialog', layer: 'Components' },
+    { name: 'Card', href: '/components/card', layer: 'Components' },
+    { name: 'Flow', href: '/components/flow', layer: 'Components' },
+    { name: 'Otp', href: '/components/otp', layer: 'Components' },
   ]}
 />
 
@@ -38,3 +46,56 @@ Entering or pasting six digits submits automatically. Use `000000` to see an inc
 Add a phone number to see a failed send request while keeping the entered number.
 
 <Story name='AddPhoneFails' storyModule={Stories} />
+
+## Email verification error
+
+This example rejects every verification attempt so the error remains visible and the user can retry.
+
+<Story name='AddEmailFails' storyModule={Stories} />
+
+## Email-link verification
+
+The profile uses OTP. This separate view displays an email-link verification in progress, with a
+resend countdown and Cancel. Its caller supplies the address, pending state, errors, and callbacks.
+
+<Story
+  name='EmailLinkVerification'
+  storyModule={Stories}
+  composition={[
+    { name: 'Dialog', href: '/components/dialog', layer: 'Components' },
+    { name: 'Card', href: '/components/card', layer: 'Components' },
+    { name: 'Spinner', href: '/components/spinner', layer: 'Components' },
+    { name: 'Button', href: '/components/button', layer: 'Components' },
+  ]}
+/>
+
+### Resend error
+
+After the countdown, resend to see the supplied error message.
+
+<Story name='EmailLinkResendFails' storyModule={Stories} />
+
+## Enterprise SSO verification
+
+When an email matches an enterprise SSO connection, this view presents the provider and a Connect
+action. The option composes `Item` with the shared provider icon, label, description, and button.
+The caller supplies the connection, pending state, errors, and callback. In this preview, Connect
+simulates completion and closes the dialog.
+
+<Story
+  name='EmailSsoVerification'
+  storyModule={Stories}
+  composition={[
+    { name: 'Dialog', href: '/components/dialog', layer: 'Components' },
+    { name: 'Card', href: '/components/card', layer: 'Components' },
+    { name: 'Item', href: '/components/item', layer: 'Components' },
+    { name: 'IconFrame', href: '/components/icon-frame', layer: 'Components' },
+    { name: 'Button', href: '/components/button', layer: 'Components' },
+  ]}
+/>
+
+### Connection error
+
+Connect to see the supplied error message. The user can retry or cancel.
+
+<Story name='EmailSsoConnectFails' storyModule={Stories} />