feat(mosaic): hold the backup codes menu open while regeneration starts

austincalvelage · Oct 28, 2026 · Oct 26, 2026 · Oct 26, 2026 · Oct 27, 2026 · Oct 27, 2026
commit c566a90f46a395c39f259899b5058102872ce62c
diff --git a/.changeset/mfa-backup-codes-pending-menu.md b/.changeset/mfa-backup-codes-pending-menu.md
@@ -0,0 +1,2 @@
+---
+---
---
---
+---
+'@clerk/mosaic': patch
+---
+
+Keep the backup-code regeneration menu open while regeneration is pending.
---
---
+---
+'@clerk/mosaic': patch
+---
+
+Keep the backup-code regeneration menu open while regeneration is pending.
diff --git a/packages/mosaic/docs/controllers.md b/packages/mosaic/docs/controllers.md
@@ -104,6 +104,14 @@ section. The dialog opens once `visible` is true, so it skips the loading card,
 dismissal only while the controller has a cancel callback. Return focus with the hook's
 `lastKey`, which outlives the run, unlike `pendingKey`.
 
+For a direct action in `ActionMenu`, derive its `progress` from the pending
+action and whether its dialog is open. Pass `idle` before activation, `pending`
+while the request or verification preparation is running, and `handoff` when the
+dialog becomes visible. The menu keeps its selected item and trailing spinner
+visible while pending, disables its actions, and blocks dismissal until handoff
+or settlement. Ordinary failures close the menu and use the section's existing
+error. Actions without `progress` still close immediately.
+
 A single open boolean earns nothing. A two-state machine with one event is a
 boolean spelled long. `useUserProfileEditUsernameController` holds `isOpen` in
 `useState` and hands the async part to `useForm`:

diff --git a/packages/mosaic/src/components/action-menu/action-menu.test.tsx b/packages/mosaic/src/components/action-menu/action-menu.test.tsx
@@ -1,4 +1,4 @@
-import { render, screen } from '@testing-library/react';
+import { render, screen, waitFor } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
 import { describe, expect, it, vi } from 'vitest';
 
@@ -37,6 +37,18 @@ describe('Mosaic ActionMenu', () => {
 
     expect(onClick).toHaveBeenCalledOnce();
   });
+  it('closes a progress action that settles before pending renders', async () => {
+    const onClick = vi.fn();
+    const user = userEvent.setup();
+    renderMenu([{ label: 'Make default', progress: 'idle', onClick }]);
+
+    await user.click(screen.getByRole('button', { name: 'Manage passkey' }));
+    await user.click(await screen.findByRole('menuitem', { name: 'Make default' }));
+
+    expect(onClick).toHaveBeenCalledOnce();
+    await waitFor(() => expect(screen.queryByRole('menu')).not.toBeInTheDocument());
+  });
+
   it('keeps a disabled trigger focusable without allowing pointer or keyboard activation', async () => {
     const onClick = vi.fn();
     render(

diff --git a/packages/mosaic/src/components/action-menu/action-menu.tsx b/packages/mosaic/src/components/action-menu/action-menu.tsx
@@ -1,14 +1,17 @@
-import type { Ref } from 'react';
+import { type Ref, useState } from 'react';
 
+import { useSpinDelay } from '../../hooks/use-spin-delay';
 import type { IconComponent } from '../../icons/glyph';
 import { Icon } from '../icon';
 import { Menu } from '../menu';
+import { Spinner } from '../spinner';
 
 export interface ActionMenuAction {
   label: string;
   color?: 'neutral' | 'negative';
   icon?: IconComponent;
   onClick: () => void;
+  progress?: 'idle' | 'pending' | 'handoff';
 }
 
 export interface ActionMenuProps {
@@ -20,12 +23,31 @@ export interface ActionMenuProps {
 }
 
 export function ActionMenu({ label, actions, triggerRef, disabled, focusableWhenDisabled }: ActionMenuProps) {
+  const [open, setOpen] = useState(false);
+  const [activated, setActivated] = useState(false);
+  const pending = actions.some(action => action.progress === 'pending');
+  const handoff = actions.some(action => action.progress === 'handoff');
+  const showSpinner = useSpinDelay(pending ? true : null);
+
+  if (activated && !pending) {
+    setActivated(false);
+    setOpen(false);
+  }
+
   if (actions.length === 0) {
     return null;
   }
 
   return (
-    <Menu.Root placement='bottom-end'>
+    <Menu.Root
+      placement='bottom-end'
+      open={open && !handoff}
+      onOpenChange={nextOpen => {
+        if (!pending && !handoff) {
+          setOpen(nextOpen);
+        }
+      }}
+    >
       <Menu.Trigger
         ref={triggerRef}
         aria-label={label}
@@ -38,15 +60,30 @@ export function ActionMenu({ label, actions, triggerRef, disabled, focusableWhen
             key={action.label}
             color={action.color}
             label={action.label}
-            onClick={action.onClick}
-            disabled={disabled}
+            onClick={() => {
+              if (action.progress !== undefined) {
+                setActivated(true);
+              }
+              action.onClick();
+            }}
+            closeOnClick={action.progress === undefined}
+            aria-busy={action.progress === 'pending' || undefined}
+            disabled={disabled || pending || handoff}
           >
             {action.icon ? (
               <Menu.Media>
                 <Icon glyph={action.icon} />
               </Menu.Media>
             ) : null}
             <Menu.Label>{action.label}</Menu.Label>
+            {action.progress === 'pending' && showSpinner ? (
+              <Spinner
+                size='sm'
+                role='progressbar'
+                aria-hidden={undefined}
+                aria-label={action.label}
+              />
+            ) : null}
           </Menu.Item>
         ))}
       </Menu.Popup>

diff --git a/...r-profile/user-profile-mfa-section/__tests__/user-profile-mfa-management.feature.test.tsx b/...r-profile/user-profile-mfa-section/__tests__/user-profile-mfa-management.feature.test.tsx
@@ -406,6 +406,49 @@ describe('User profile MFA management', () => {
     expect(fapi.mfa.backupCodeCreations).toBe(1);
   });
 
+  it('holds the menu open with a spinner on Regenerate until the backup codes are ready', async () => {
+    await renderMfa(
+      fapiUser({ id: 'user_1', totp_enabled: true, backup_code_enabled: true, two_factor_enabled: true }),
+      mfaEnvironment(),
+    );
+    const generate = holdRequests('post', '/v1/me/backup_codes/');
+    const user = userEvent.setup();
+
+    try {
+      await regenerate(user);
+      await waitFor(() => expect(generate.requests).toHaveLength(1));
+      expect(screen.getByRole('menu')).toBeVisible();
+      expect(screen.getByRole('menuitem', { name: 'Regenerate' })).toHaveAttribute('aria-busy', 'true');
+      expect(await screen.findByRole('progressbar', { name: 'Regenerate' })).toBeVisible();
+      expect(screen.queryByRole('dialog')).toBeNull();
+    } finally {
+      generate.release();
+    }
+
+    const list = await screen.findByRole('list', { name: 'Backup codes' });
+    expect(within(list).getAllByRole('listitem')).toHaveLength(10);
+    await waitFor(() => expect(screen.queryByRole('menu')).toBeNull());
+  });
+
+  it('holds the Regenerate menu item until session verification opens', async () => {
+    await renderBackupCodesNeedingReverification();
+    const start = holdRequests('post', '/v1/client/sessions/:id/verify');
+    const user = userEvent.setup();
+
+    try {
+      await regenerate(user);
+      await waitFor(() => expect(start.requests).toHaveLength(1));
+      expect(screen.getByRole('menu')).toBeVisible();
+      expect(screen.getByRole('menuitem', { name: 'Regenerate' })).toHaveAttribute('aria-busy', 'true');
+      expect(screen.queryByText('Enter your current password to continue')).toBeNull();
+    } finally {
+      start.release();
+    }
+
+    expect(await screen.findByText('Enter your current password to continue')).toBeVisible();
+    await waitFor(() => expect(screen.queryByRole('menu')).toBeNull());
+  });
+
   async function renderBackupCodesNeedingReverification() {
     const fapi = await renderMfa(
       fapiUser({ id: 'user_1', totp_enabled: true, backup_code_enabled: true, two_factor_enabled: true }),

diff --git a/...s/mosaic/src/features/user-profile/user-profile-mfa-section/user-profile-mfa-row.view.tsx b/...s/mosaic/src/features/user-profile/user-profile-mfa-section/user-profile-mfa-row.view.tsx
@@ -15,7 +15,8 @@ export function UserProfileMfaRowView({
   onRemove,
   onSetDefault,
   onRegenerateBackupCodes,
-}: Pick<UserProfileMfaSectionViewProps, 'onRegenerateBackupCodes'> & {
+  regenerateProgress,
+}: Pick<UserProfileMfaSectionViewProps, 'onRegenerateBackupCodes' | 'regenerateProgress'> & {
   method: UserProfileMfaMethod;
   triggerRef?: Ref<HTMLButtonElement>;
   onRemove?: () => void;
@@ -37,7 +38,7 @@ export function UserProfileMfaRowView({
 
   if (method.type === 'backup-codes') {
     if (onRegenerateBackupCodes) {
-      actions.push({ label: m.regenerate, onClick: onRegenerateBackupCodes });
+      actions.push({ label: m.regenerate, onClick: onRegenerateBackupCodes, progress: regenerateProgress });
     }
   } else if (onRemove && method.canRemove !== false) {
     actions.push({ label: m.remove, color: 'negative', onClick: onRemove });

diff --git a/...src/features/user-profile/user-profile-mfa-section/user-profile-mfa-section.controller.ts b/...src/features/user-profile/user-profile-mfa-section/user-profile-mfa-section.controller.ts
@@ -588,6 +588,7 @@ export function useUserProfileMfaController(model: ReadyModel) {
     methods: [...model.methods],
     addableMethods: model.addableMethods,
     onRegenerateBackupCodes: model.generateBackupCodes ? generateBackupCodes : undefined,
+    regenerateProgress: context.pending === 'generate' ? (dialogOpen ? 'handoff' : 'pending') : 'idle',
     regenerateError: flow.kind === 'closed' && flow.error ? errorText(flow.error) : undefined,
     onRemove: model.remove,
     onSetDefault: model.setDefault,

diff --git a/...saic/src/features/user-profile/user-profile-mfa-section/user-profile-mfa-section.view.tsx b/...saic/src/features/user-profile/user-profile-mfa-section/user-profile-mfa-section.view.tsx
@@ -3,6 +3,7 @@ import type { ReactNode, Ref } from 'react';
 
 import { Confirmation } from '../../../blocks/confirmation';
 import { ReverificationDialog } from '../../../blocks/reverification';
+import type { ActionMenuAction } from '../../../components/action-menu';
 import { Section } from '../../../components/section';
 import { fill, type MosaicMessages, useMessages } from '../../../localization';
 import type { ReverificationController } from '../../reverification';
@@ -22,6 +23,7 @@ export interface UserProfileMfaSectionViewProps {
   addControl?: ReactNode;
   onAdd?: (type: UserProfileMfaAddableMethod) => void;
   onRegenerateBackupCodes?: () => void;
+  regenerateProgress?: ActionMenuAction['progress'];
   regenerateError?: string;
   onRemove?: (id: string) => void | Promise<void>;
   onSetDefault?: (id: string) => void | Promise<void>;
@@ -36,6 +38,7 @@ export function UserProfileMfaSectionView({
   addControl,
   onAdd,
   onRegenerateBackupCodes,
+  regenerateProgress,
   regenerateError,
   onRemove,
   onSetDefault,
@@ -83,6 +86,7 @@ export function UserProfileMfaSectionView({
             onRemove={controller.remove ? () => controller.openRemoval(method) : undefined}
             onSetDefault={controller.setDefault}
             onRegenerateBackupCodes={onRegenerateBackupCodes}
+            regenerateProgress={regenerateProgress}
           />
         ))}
       </UserProfileSecurityList>