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

.changeset/mfa-backup-codes-pending-menu.md

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

packages/mosaic/docs/controllers.md

@@ -104,6 +104,15 @@ 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`, opt in with `status: 'idle'`. Set it to
+`'pending'` while its request runs and no dialog is open yet. Update the status
+in the click event, since the menu closes on the next render unless an action
+is pending. The menu reserves room for a spinner, disables its actions, and
+blocks dismissal while pending. It closes when the status returns to `'idle'`,
+whether a dialog opened or the request settled. Leave `status` undefined for
+ordinary actions that close through the menu's native click behavior. Ordinary
+failures use the section's existing error.
+
 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`:

packages/mosaic/src/components/action-menu/action-menu.test.tsx

@@ -1,5 +1,6 @@
-import { render, screen } from '@testing-library/react';
+import { act, fireEvent, render, screen, waitFor, within } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
+import { useState } from 'react';
 import { describe, expect, it, vi } from 'vitest';
 
 import { Pen } from '../../icons/glyphs/pen';
@@ -17,6 +18,27 @@ function renderMenu(actions: Parameters<typeof ActionMenu>[0]['actions']) {
   );
 }
 
+function AsyncMenu({ onRemove = () => undefined }: { onRemove?: () => void }) {
+  const [status, setStatus] = useState<'idle' | 'pending'>('idle');
+  return (
+    <MosaicProvider>
+      <ActionMenu
+        label='Manage passkey'
+        actions={[
+          { label: 'Regenerate', status, onClick: () => setStatus('pending') },
+          { label: 'Remove', onClick: onRemove },
+        ]}
+      />
+      <button
+        type='button'
+        onClick={() => setStatus('idle')}
+      >
+        Finish request
+      </button>
+    </MosaicProvider>
+  );
+}
+
 describe('Mosaic ActionMenu', () => {
   it('renders nothing when there are no actions', () => {
     renderMenu([]);
@@ -37,6 +59,66 @@ describe('Mosaic ActionMenu', () => {
 
     expect(onClick).toHaveBeenCalledOnce();
   });
+  it('closes after an action that does not report pending', async () => {
+    const onClick = vi.fn();
+    const user = userEvent.setup();
+    renderMenu([{ label: 'Make default', 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 an opted-in action open while pending and closes immediately when it settles', async () => {
+    const user = userEvent.setup();
+    const onRemove = vi.fn();
+    render(<AsyncMenu onRemove={onRemove} />);
+    await user.click(screen.getByRole('button', { name: 'Manage passkey' }));
+    await user.click(await screen.findByRole('menuitem', { name: 'Regenerate' }));
+    const menu = screen.getByRole('menu');
+    expect(within(menu).getByRole('menuitem', { name: 'Regenerate' })).toHaveAttribute('aria-busy', 'true');
+    expect(within(menu).getByRole('menuitem', { name: 'Remove' })).toHaveAttribute('aria-disabled', 'true');
+    await user.click(within(menu).getByRole('menuitem', { name: 'Remove' }));
+    expect(onRemove).not.toHaveBeenCalled();
+    await user.keyboard('{Escape}');
+    expect(screen.getByRole('menu')).toBeInTheDocument();
+    await user.click(document.body);
+    expect(screen.getByRole('menu')).toBeInTheDocument();
+    await user.click(screen.getByRole('button', { name: 'Finish request' }));
+    await waitFor(() => expect(screen.queryByRole('menu')).not.toBeInTheDocument());
+  });
+
+  it('reserves an indicator immediately and delays its named spinner', async () => {
+    const user = userEvent.setup();
+    render(<AsyncMenu />);
+    await user.click(screen.getByRole('button', { name: 'Manage passkey' }));
+    const item = await screen.findByRole('menuitem', { name: 'Regenerate' });
+    expect(item.querySelector('.cl-menu-indicator')).toBeInTheDocument();
+    vi.useFakeTimers();
+    try {
+      fireEvent.click(item);
+      expect(screen.queryByRole('progressbar', { name: 'Regenerate' })).not.toBeInTheDocument();
+      await act(() => vi.advanceTimersByTime(149));
+      expect(screen.queryByRole('progressbar', { name: 'Regenerate' })).not.toBeInTheDocument();
+      await act(() => vi.advanceTimersByTime(1));
+      expect(screen.getByRole('progressbar', { name: 'Regenerate' })).toBeInTheDocument();
+      fireEvent.click(screen.getByRole('button', { name: 'Finish request' }));
+      expect(screen.queryByRole('menu')).not.toBeInTheDocument();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it('closes an opted-in action that hands off before becoming pending', async () => {
+    const user = userEvent.setup();
+    renderMenu([{ label: 'Open dialog', status: 'idle', onClick: () => undefined }]);
+    await user.click(screen.getByRole('button', { name: 'Manage passkey' }));
+    await user.click(await screen.findByRole('menuitem', { name: 'Open dialog' }));
+    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(

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;
+  status?: 'idle' | 'pending';
 }
 
 export interface ActionMenuProps {
@@ -20,12 +23,30 @@ 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.status === 'pending');
+  const showSpinner = useSpinDelay(pending ? true : null, { minDuration: 0 });
+
+  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}
+      onOpenChange={nextOpen => {
+        if (!pending) {
+          setOpen(nextOpen);
+        }
+      }}
+    >
       <Menu.Trigger
         ref={triggerRef}
         aria-label={label}
@@ -38,15 +59,32 @@ 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.status !== undefined) {
+                setActivated(true);
+              }
+              action.onClick();
+            }}
+            closeOnClick={action.status === undefined}
+            aria-busy={action.status === 'pending' || undefined}
+            disabled={disabled || pending}
           >
             {action.icon ? (
               <Menu.Media>
                 <Icon glyph={action.icon} />
               </Menu.Media>
             ) : null}
             <Menu.Label>{action.label}</Menu.Label>
+            {action.status !== undefined ? (
+              <Menu.Indicator>
+                {action.status === 'pending' && showSpinner ? (
+                  <Spinner
+                    size='sm'
+                    label={action.label}
+                  />
+                ) : null}
+              </Menu.Indicator>
+            ) : null}
           </Menu.Item>
         ))}
       </Menu.Popup>

packages/mosaic/src/components/button/submit-button.tsx

@@ -96,15 +96,7 @@ export const SubmitButton = React.forwardRef<HTMLButtonElement, SubmitButtonProp
       </span>
       {isPending || showPending ? (
         <Spinner
-          // The indicator has to be in the accessibility tree the moment the button goes
-          // pending, so it opts out of `Spinner`'s decorative default and carries an
-          // indeterminate progressbar role. It is named in its own right rather than folded
-          // into the button's name: `progressbar` is a range role, so the name computation
-          // takes its value — absent, since it is indeterminate — over its label, and a
-          // descendant one contributes nothing to the button above it.
-          role='progressbar'
-          aria-hidden={undefined}
-          aria-label={pendingLabel}
+          label={pendingLabel}
           size={spinnerSizes[size]}
           xstyle={[styles.spinner, !showPending && styles.spinnerHidden]}
         />

packages/mosaic/src/components/menu/menu.styles.ts

@@ -160,6 +160,17 @@ export const label = stylex.create({
   },
 });
 
+export const indicator = stylex.create({
+  base: {
+    alignItems: 'center',
+    aspectRatio: '1/1',
+    display: 'flex',
+    flexShrink: 0,
+    justifyContent: 'center',
+    width: space['4'],
+  },
+});
+
 export const separator = stylex.create({
   base: {
     // Full-bleed across the popup: cancel the viewport's inline padding.

packages/mosaic/src/components/menu/menu.tsx

@@ -167,11 +167,27 @@ export const MenuLabel = React.forwardRef<HTMLSpanElement, MenuLabelProps>(funct
   });
 });
 
+export type MenuIndicatorProps = MosaicComponentProps<'span'>;
+
+export const MenuIndicator = React.forwardRef<HTMLSpanElement, MenuIndicatorProps>(function MosaicMenuIndicator(
+  { render, xstyle, ...rest },
+  ref,
+) {
+  return useRender({
+    defaultTagName: 'span',
+    render,
+    ref,
+    props: {
+      ...mergeStyleProps(themeProps('menu-indicator'), stylex.props(reset.base, slots.indicator.base, xstyle), rest),
+    },
+  });
+});
+
 export interface MenuItemProps extends Omit<PrimitiveMenuItemProps, 'className' | 'style'>, MosaicStyleProps {
   /** Semantic color of the action. */
   color?: 'neutral' | 'negative';
   /**
-   * The row's content, composed from `Menu.Media` and `Menu.Label`. Required, and text goes in
+   * The row's content, composed from `Menu.Media`, `Menu.Label` and `Menu.Indicator`. Required, and text goes in
    * `Menu.Label` rather than straight in here: a bare text node is not a flex item the row can
    * size, so it neither lines up with the other rows nor truncates.
    */
@@ -227,5 +243,6 @@ export const Menu = {
   Item: MenuItem,
   Media: MenuMedia,
   Label: MenuLabel,
+  Indicator: MenuIndicator,
   Separator: MenuSeparator,
 };

packages/mosaic/src/components/spinner/spinner.test.tsx

@@ -1,5 +1,5 @@
 import * as stylex from '@stylexjs/stylex';
-import { render } from '@testing-library/react';
+import { render, screen } from '@testing-library/react';
 import React from 'react';
 import { describe, expect, it } from 'vitest';
 
@@ -20,6 +20,13 @@ describe('Mosaic Spinner', () => {
     expect(el).toHaveAttribute('aria-hidden', 'true');
   });
 
+  it('announces a labeled spinner as an indeterminate progressbar', () => {
+    render(<Spinner label='Regenerating backup codes' />);
+    const progress = screen.getByRole('progressbar', { name: 'Regenerating backup codes' });
+    expect(progress).not.toHaveAttribute('aria-hidden');
+    expect(progress).not.toHaveAttribute('aria-valuenow');
+  });
+
   it('applies the default size when none is passed', () => {
     const { container } = render(<Spinner />);
     expect(spinner(container)).toHaveAttribute('data-size', 'md');

packages/mosaic/src/components/spinner/spinner.tsx

@@ -7,11 +7,11 @@ import { sizes, styles } from './spinner.styles';
 
 export type SpinnerProps = MosaicElementProps<'span'> & {
   size?: 'sm' | 'md';
+  label?: string;
 };
 
 /**
- * Indeterminate loading spinner. Decorative (`aria-hidden`) — pair it with a disabled control or an
- * `aria-busy` container so assistive tech is informed of the pending state.
+ * Indeterminate loading spinner. Decorative by default; pass `label` to announce progress.
  *
  * @example
  * // Default (md), sized to match a `md` Icon
@@ -22,13 +22,15 @@ export type SpinnerProps = MosaicElementProps<'span'> & {
  * <Spinner size='sm' />
  */
 export const Spinner = React.forwardRef<HTMLSpanElement, SpinnerProps>(function MosaicSpinner(
-  { size = 'md', xstyle, ...rest },
+  { size = 'md', label, xstyle, ...rest },
   ref,
 ) {
   return (
     <span
       ref={ref}
-      aria-hidden
+      role={label ? 'progressbar' : undefined}
+      aria-label={label}
+      aria-hidden={label ? undefined : true}
       {...mergeStyleProps(themeProps('spinner', { size }), stylex.props(styles.base, sizes[size], xstyle), rest)}
     />
   );

packages/mosaic/src/features/switcher/switcher.view.tsx

@@ -197,9 +197,7 @@ function PendingSpinner() {
   const m = useSwitcherMessages();
   return (
     <Spinner
-      role='progressbar'
-      aria-hidden={undefined}
-      aria-label={m.organizations.pending}
+      label={m.organizations.pending}
       size='sm'
     />
   );

packages/mosaic/src/features/user-profile/__tests__/user-profile-security-panel.view.test.tsx

@@ -268,7 +268,7 @@ describe('UserProfileSecurityPanelView', () => {
     const backupOnlyView = renderView(
       <UserProfileMfaSectionView
         methods={[backupCodes]}
-        onRegenerateBackupCodes={onRegenerateBackupCodes}
+        regenerate={{ onClick: onRegenerateBackupCodes, status: 'idle' }}
         onRemove={onRemove}
       />,
     );
@@ -280,7 +280,7 @@ describe('UserProfileSecurityPanelView', () => {
     renderView(
       <UserProfileMfaSectionView
         methods={[{ id: 'sms_1', type: 'sms' }, backupCodes]}
-        onRegenerateBackupCodes={onRegenerateBackupCodes}
+        regenerate={{ onClick: onRegenerateBackupCodes, status: 'idle' }}
         onRemove={onRemove}
       />,
     );