feat(ui): connect the Mosaic UserButton and its custom UserProfile pages

.changeset/mosaic-user-button-integration.md

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

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

@@ -302,19 +302,29 @@ describe('Mosaic SubmitButton spin delay', () => {
     expect(atoms(spinner()).length).toBeLessThan(hidden.length);
   });
 
-  // A consumer who already knows the action is slow has nothing to gain by waiting.
+  // A consumer who already knows the action is slow has nothing to gain by waiting: there is no
+  // delay left to outlast, so the spinner shows in the render that starts the action rather than a
+  // timer's.
   it('lets the consumer opt out of the delay', () => {
-    render(
+    const { rerender } = render(
       <SubmitButton
         isPending
-        spinDelay={{ delay: 0 }}
+        spinDelay={{ delay: 1000 }}
       >
         Save
       </SubmitButton>,
     );
     const hidden = atoms(spinner());
 
-    advance(0);
+    rerender(
+      <SubmitButton
+        isPending
+        spinDelay={{ delay: 0 }}
+      >
+        Save
+      </SubmitButton>,
+    );
+
     expect(atoms(spinner()).length).toBeLessThan(hidden.length);
   });
 

packages/ui/src/mosaic/hooks/__tests__/useSpinDelay.test.ts

@@ -76,6 +76,27 @@ describe('useSpinDelay', () => {
     expect(result.current).toBeNull();
   });
 
+  // Direct feedback on a click has nothing to debounce, so a zero delay must not cost a timer's
+  // worth of render passes before the spinner appears.
+  it('surfaces the value in the same pass when there is no delay to wait out', async () => {
+    const { result, rerender } = render(null, { delay: 0, minDuration: 200 });
+    await act(() => rerender({ value: 'a' }));
+
+    expect(result.current).toBe('a');
+  });
+
+  it('still holds a zero-delay value for minDuration', async () => {
+    const { result, rerender } = render(null, { delay: 0, minDuration: 200 });
+    await act(() => rerender({ value: 'a' }));
+    await act(() => rerender({ value: null }));
+
+    await advance(199);
+    expect(result.current).toBe('a');
+
+    await advance(1);
+    expect(result.current).toBeNull();
+  });
+
   it('swaps to a new value immediately when one replaces another mid-show', async () => {
     const { result, rerender } = render(null, { delay: 500, minDuration: 200 });
     await act(() => rerender({ value: 'a' }));

packages/ui/src/mosaic/hooks/useSpinDelay.ts

@@ -1,7 +1,7 @@
 import { useEffect, useRef, useState } from 'react';
 
 export interface SpinDelayOptions {
-  /** Wait this long before showing the value, so quick actions never flash a spinner. */
+  /** Wait this long before showing the value, so quick actions never flash a spinner. `0` shows it straight away. */
   delay?: number;
   /** Once shown, keep the value up at least this long, so the spinner never flickers off. */
   minDuration?: number;
@@ -25,11 +25,17 @@ export function useSpinDelay<T>(value: T | null, options: SpinDelayOptions = {})
   const shownAt = useRef(0);
 
   useEffect(() => {
-    // Nothing showing yet: arm a timer so the value only surfaces if it outlasts `delay`.
+    // Nothing showing yet: arm a timer so the value only surfaces if it outlasts `delay`. With no
+    // delay there is nothing to outlast, so it surfaces in this pass rather than a timer's.
     if (shown === null) {
       if (value === null) {
         return;
       }
+      if (delay <= 0) {
+        shownAt.current = Date.now();
+        setShown(value);
+        return;
+      }
       const timer = setTimeout(() => {
         shownAt.current = Date.now();
         setShown(value);

packages/ui/src/mosaic/user-button/__tests__/user-button.controller.test.tsx

@@ -1,4 +1,5 @@
 import type * as SharedReact from '@clerk/shared/react';
+import type { CustomPage } from '@clerk/shared/types';
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
@@ -183,8 +184,8 @@ afterEach(() => {
   vi.clearAllMocks();
 });
 
-function Harness(options: UserButtonControllerOptions = {}) {
-  const c = useUserButtonController(options);
+function Harness({ customPages, ...options }: UserButtonControllerOptions & { customPages?: CustomPage[] } = {}) {
+  const c = useUserButtonController(options, customPages);
   if (c.status !== 'ready') {
     return <output data-testid='status'>{c.status}</output>;
   }
@@ -633,6 +634,26 @@ describe('useUserButtonController', () => {
     expect(openOrganizationProfile).toHaveBeenCalledWith({ getContainer });
   });
 
+  // Custom pages are bridged into this DOM-callback form by the container, since it is the layer
+  // that can render their portals. All the controller owes them is a ride to the modal.
+  it('hands the profile modal the custom pages it was given', () => {
+    const customPages = [
+      {
+        label: 'Terms',
+        url: 'terms',
+        mount: vi.fn(),
+        unmount: vi.fn(),
+        mountIcon: vi.fn(),
+        unmountIcon: vi.fn(),
+      },
+    ];
+    render(<Harness customPages={customPages} />);
+
+    fireEvent.click(screen.getByText('manage-account'));
+
+    expect(openUserProfile).toHaveBeenCalledWith({ getContainer, customPages });
+  });
+
   // A URL is the whole opt-in: passing one means navigation, with no mode to remember to pass
   // alongside it. The two are resolved apart, so routing one profile leaves the other a modal.
   it('navigates to a profile URL when one is given, and only for that profile', () => {