feat(mosaic): animate contact list rows in the user profile

Emails and phone numbers in the account section keep the order they were
first shown in while the panel is mounted. A new row expands into the
list and a removed row collapses out of it, each as a grid slot whose
track transitions between 1fr and 0fr with the content fading inside a
clip layer anchored to the top. Setting a primary moves the badge, which
enters and exits on the motion rules, rather than the rows.

A set-primary request marks its row busy; once it outlasts a short delay
the rows ride the shared loading wave and the badge change waits for the
pulse to end. Under reduced motion every change is a cut.

Adds usePresenceList and useStableOrder to the primitives.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>

Author: maxyinger

.changeset/contact-list-rows.md

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

.claude/skills/mosaic/references/motion.md

@@ -326,6 +326,55 @@ nothing. The surface keeps its fade and pins the scale (inline text has none to
 and its entrance delay goes to `instant` as well: it exists to wait for the row, and
 a row that has snapped open leaves nothing to wait for.
 
+### Rows in a list
+
+The contact rows in the user profile (`user-profile-contact-list-row.view.tsx`) adopt
+the recipe for a `<ul>` whose rows come and go. What differs from the banner:
+
+- **The slot is the `<li>`.** `grid-template-rows` on the list item, the clip layer
+  inside it (`grid-row: 1 / span 2`, `min-height: 0`, no padding), and the real row
+  rendered as a `div` through `Section.Item`'s `render`. `usePresenceList` keeps a
+  removed row mounted, in place and `inert`, until its collapse ends.
+- **The entering track starts from `@starting-style`**, not `data-starting-style`
+  (StyleX 0.19 compiles the key). The attribute is released from a passive effect a
+  frame after commit, and a track that starts a frame late is visible when another
+  row is collapsing at the same time. Keep the hook's inline `transition: none` off
+  the slot, and apply the `@starting-style` variant only to rows mounted after the
+  list's first render, or the list expands from nothing on load.
+- **One duration and one curve both ways**: `--cl-duration-slower` on
+  `--cl-ease-in-out`. A list can collapse one row while another expands, and the
+  card's height is the sum of the tracks, so the two must be mirror images every
+  frame. The banner's split (`--cl-ease-enter` open, in-out close) is for a single
+  row that never overlaps another.
+- **Anchored to the start, faded at the bottom.** The row's top border is the list's
+  separator, so the content sits at the top of the clip and the border is there from
+  the first frame to the last in both directions; the moving edge is the bottom one,
+  under a static `mask-image` the height of the row's bottom padding, so at rest it
+  touches nothing. The border rule is the slot's own (`:first-child` has none), since
+  `Section.Item`'s sibling-marker rule cannot see across the slots.
+- **Content fade and scale live on the row's children** (a marker on the row,
+  `stylex.when.ancestor` on `Section.Content` and `Section.Actions`), never on the
+  row itself: opacity on the row would fade its border too. Timing is the recipe's:
+  enter after `slow`, at `base`; exit at once, at `fast`.
+- **Reduced motion is a cut in one commit.** Every transition off, every value at
+  rest, and the slot `display: none` as soon as it carries `data-closed`. Without
+  that rule the incoming row mounts a commit before the outgoing one is unmounted and
+  both show for a frame.
+
+**Rows do not reorder.** While the list is mounted it keeps the order it was first
+shown in (`useStableOrder`): a new row is appended, a removed row drops out, and a
+row the model now sorts elsewhere stays put. Setting a primary therefore moves the
+badge, which enters and exits on the ordinary rules (`base` in on `--cl-ease-enter`
+with `scale(0.9 → 1)` on `--cl-ease-default`, `fast` out on `--cl-ease-exit`),
+rather than moving rows past each other. A reorder was built and dropped: a row
+that collapses in one place and expands in another reads as a swap, not travel.
+
+**A pending request pulses the live rows.** A set-primary request marks its row
+busy at once; once it outlasts `useSpinDelay`'s 150ms, every row's content takes
+`skeletonStyles.wave` with a `useSkeletonWave` ref, so the rows ride the same wave
+as a loading skeleton would, and the badge change is held until the pulse has shown
+for its 400ms minimum.
+
 ## Color and state changes (hover, press)
 
 A state change on an element that is already there and stays there — background,

packages/mosaic/src/features/user-profile/__tests__/user-profile-contact-list-row.view.test.tsx

@@ -1,10 +1,23 @@
-import { render, screen } from '@testing-library/react';
+import { createDeferredPromise } from '@clerk/shared/utils';
+import { act, render, screen } from '@testing-library/react';
 import userEvent from '@testing-library/user-event';
-import { describe, expect, it, vi } from 'vitest';
+import { afterEach, describe, expect, it, vi } from 'vitest';
 
 import { UserProfileContactListRowView } from '../user-profile-account-section/user-profile-contact-list-row.view';
 
+type Animated = { getAnimations?: () => Animation[] };
+
+function holdExits() {
+  const exit = createDeferredPromise();
+  (Element.prototype as Animated).getAnimations = () => [{ finished: exit.promise } as Animation];
+  return exit;
+}
+
 describe('UserProfileContactListRowView', () => {
+  afterEach(() => {
+    delete (Element.prototype as Animated).getAnimations;
+  });
+
   it.each(['email', 'phone'] as const)('hides the menu when no %s action applies', kind => {
     const onVerify = vi.fn();
     const onSetPrimary = vi.fn();
@@ -40,4 +53,94 @@ describe('UserProfileContactListRowView', () => {
     await user.click(screen.getByRole('menuitem', { name: 'Remove phone number' }));
     expect(onRemove).toHaveBeenCalledExactlyOnceWith('contact_1');
   });
+
+  it('keeps a removed item inert in place until its exit finishes', async () => {
+    const exit = holdExits();
+    const items = [
+      { id: 'contact_1', value: 'first@example.com' },
+      { id: 'contact_2', value: 'second@example.com' },
+      { id: 'contact_3', value: 'third@example.com' },
+    ];
+    const { rerender } = render(
+      <UserProfileContactListRowView
+        kind='email'
+        label='Emails'
+        items={items}
+      />,
+    );
+
+    rerender(
+      <UserProfileContactListRowView
+        kind='email'
+        label='Emails'
+        items={items.filter(item => item.id !== 'contact_2')}
+      />,
+    );
+
+    const slot = screen.getByText('second@example.com').closest('li');
+    expect(slot).toHaveAttribute('data-ending-style');
+    expect(slot).toHaveAttribute('inert');
+    expect(slot).toHaveAttribute('aria-hidden', 'true');
+    expect(slot?.previousElementSibling).toHaveTextContent('first@example.com');
+    expect(slot?.nextElementSibling).toHaveTextContent('third@example.com');
+
+    await act(async () => {
+      exit.resolve();
+      await exit.promise;
+    });
+    expect(screen.queryByText('second@example.com')).not.toBeInTheDocument();
+  });
+
+  it('shows the empty state while the last item exits', () => {
+    holdExits();
+    const { rerender } = render(
+      <UserProfileContactListRowView
+        kind='phone'
+        label='Phones'
+        items={[{ id: 'contact_1', value: '+1 (801) 555-0100' }]}
+      />,
+    );
+
+    rerender(
+      <UserProfileContactListRowView
+        kind='phone'
+        label='Phones'
+        items={[]}
+      />,
+    );
+
+    expect(screen.getByText('+1 (801) 555-0100').closest('li')).toHaveAttribute('data-ending-style');
+    expect(screen.getByText('No phone numbers added')).toBeInTheDocument();
+  });
+
+  it('transitions the primary badge out when another item becomes primary', () => {
+    holdExits();
+    const items = [
+      { id: 'contact_1', value: 'first@example.com', isDefault: true, isVerified: true },
+      { id: 'contact_2', value: 'second@example.com', isVerified: true },
+    ];
+    const { rerender } = render(
+      <UserProfileContactListRowView
+        kind='email'
+        label='Emails'
+        items={items}
+      />,
+    );
+
+    rerender(
+      <UserProfileContactListRowView
+        kind='email'
+        label='Emails'
+        items={[
+          { ...items[0], isDefault: false },
+          { ...items[1], isDefault: true },
+        ]}
+      />,
+    );
+
+    const badges = screen.getAllByText('Primary').map(label => label.closest('.cl-badge'));
+    expect(badges).toHaveLength(2);
+    expect(badges[0]).toHaveAttribute('data-ending-style');
+    expect(badges[1]).toHaveAttribute('data-starting-style');
+  });
 });

packages/mosaic/src/features/user-profile/__tests__/user-profile-email-actions.test.tsx

@@ -24,6 +24,68 @@ function renderEmail(overrides: Partial<UserProfileAccountSectionViewProps> = {}
 }
 
 describe('email actions', () => {
+  it('marks the email busy while it is being set as primary', async () => {
+    const user = userEvent.setup();
+    const request = createDeferredPromise();
+    const onSetPrimaryEmail = vi.fn().mockReturnValue(request.promise);
+    renderEmail({ onSetPrimaryEmail });
+    const row = screen.getByText('test@example.com').closest('.cl-section-item');
+
+    await user.click(screen.getByRole('button', { name: 'Manage test@example.com' }));
+    await user.click(screen.getByRole('menuitem', { name: 'Set as primary' }));
+    expect(row).toHaveAttribute('aria-busy', 'true');
+    expect(row).toHaveAttribute('data-pending');
+
+    await act(async () => {
+      request.resolve();
+      await request.promise;
+    });
+    expect(row).not.toHaveAttribute('aria-busy');
+    expect(row).not.toHaveAttribute('data-pending');
+  });
+
+  it('keeps the list order when the primary changes, and holds the badge while the pulse shows', async () => {
+    const user = userEvent.setup();
+    const order = () =>
+      screen.getAllByRole('button', { name: /^Manage / }).map(button => button.getAttribute('aria-label'));
+    const primary = () => screen.getByText('Primary').closest('.cl-section-item')?.textContent;
+    function Example() {
+      const [emails, setEmails] = useState([
+        { id: 'email_1', value: 'first@example.com', isDefault: true, isVerified: true },
+        { id: 'email_2', value: 'second@example.com', isVerified: true },
+      ]);
+      return (
+        <MosaicProvider>
+          <UserProfileAccountSectionView
+            allowMultipleAccounts
+            name='Test'
+            username='test'
+            phones={[]}
+            emails={emails}
+            onRemoveEmail={vi.fn()}
+            onSetPrimaryEmail={async id => {
+              await new Promise(resolve => setTimeout(resolve, 200));
+              setEmails(current =>
+                [...current]
+                  .map(email => ({ ...email, isDefault: email.id === id }))
+                  .sort((a, b) => Number(b.isDefault) - Number(a.isDefault)),
+              );
+            }}
+          />
+        </MosaicProvider>
+      );
+    }
+    render(<Example />);
+    await user.click(screen.getByRole('button', { name: 'Manage second@example.com' }));
+    await user.click(screen.getByRole('menuitem', { name: 'Set as primary' }));
+
+    await act(() => new Promise(resolve => setTimeout(resolve, 250)));
+    expect(primary()).toContain('first@example.com');
+
+    await waitFor(() => expect(primary()).toContain('second@example.com'), { timeout: 1500 });
+    expect(order()).toEqual(['Manage first@example.com', 'Manage second@example.com']);
+  });
+
   it('returns focus to the email menu after opening with the keyboard and canceling with Escape', async () => {
     const user = userEvent.setup();
     const onRemoveEmail = vi.fn();

packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.markers.stylex.ts

@@ -0,0 +1,4 @@
+import * as stylex from '@stylexjs/stylex';
+
+export const contactSlotMarker = stylex.defineMarker();
+export const contactItemMarker = stylex.defineMarker();

packages/mosaic/src/features/user-profile/user-profile-account-section/user-profile-account-section.styles.ts

@@ -0,0 +1,103 @@
+import * as stylex from '@stylexjs/stylex';
+
+import { durationVars, easingVars, space } from '../../../tokens.stylex';
+import { contactItemMarker, contactSlotMarker } from './user-profile-account-section.markers.stylex';
+
+export const styles = stylex.create({
+  contactSlot: {
+    display: {
+      default: 'grid',
+      '@media (prefers-reduced-motion: reduce)': { default: 'grid', ':where([data-closed])': 'none' },
+    },
+    gridTemplateRows: {
+      default: '1fr',
+      ':where([data-ending-style])': '0fr',
+    },
+    transitionDuration: durationVars['--cl-duration-slower'],
+    transitionProperty: {
+      default: 'grid-template-rows',
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+    transitionTimingFunction: easingVars['--cl-ease-in-out'],
+  },
+  contactSlotAppear: {
+    gridTemplateRows: {
+      '@starting-style': '0fr',
+      default: '1fr',
+      ':where([data-ending-style])': '0fr',
+    },
+  },
+  contactClip: {
+    overflow: 'clip',
+    alignContent: 'start',
+    display: 'grid',
+    gridRowEnd: 'span 2',
+    gridRowStart: '1',
+    maskImage: `linear-gradient(to top, transparent, black ${space['4']})`,
+    minHeight: 0,
+  },
+  contactItem: {
+    borderBlockStartWidth: {
+      default: '1px',
+      [stylex.when.ancestor(':where(:first-child)', contactSlotMarker)]: '0px',
+    },
+  },
+  contactFade: {
+    opacity: {
+      default: 1,
+      [stylex.when.ancestor(':where([data-starting-style], [data-ending-style])', contactItemMarker)]: 0,
+      '@media (prefers-reduced-motion: reduce)': {
+        default: 1,
+        [stylex.when.ancestor(':where([data-starting-style], [data-ending-style])', contactItemMarker)]: 1,
+      },
+    },
+    transform: {
+      default: 'scale(1)',
+      [stylex.when.ancestor(':where([data-starting-style], [data-ending-style])', contactItemMarker)]: 'scale(0.98)',
+      '@media (prefers-reduced-motion: reduce)': {
+        default: 'scale(1)',
+        [stylex.when.ancestor(':where([data-starting-style], [data-ending-style])', contactItemMarker)]: 'scale(1)',
+      },
+    },
+    transformOrigin: 'left',
+    transitionDelay: {
+      default: durationVars['--cl-duration-slow'],
+      [stylex.when.ancestor(':where([data-ending-style])', contactItemMarker)]: durationVars['--cl-duration-instant'],
+    },
+    transitionDuration: {
+      default: durationVars['--cl-duration-base'],
+      [stylex.when.ancestor(':where([data-ending-style])', contactItemMarker)]: durationVars['--cl-duration-fast'],
+    },
+    transitionProperty: {
+      default: 'opacity, transform',
+      '@media (prefers-reduced-motion: reduce)': 'none',
+    },
+    transitionTimingFunction: {
+      default: `${easingVars['--cl-ease-enter']}, ${easingVars['--cl-ease-default']}`,
+      [stylex.when.ancestor(':where([data-ending-style])', contactItemMarker)]: easingVars['--cl-ease-exit'],
+    },
+  },
+  primaryBadge: {
+    opacity: { default: 1, ':where([data-starting-style], [data-ending-style])': 0 },
+    transform: {
+      default: 'scale(1)',
+      ':where([data-starting-style], [data-ending-style])': 'scale(0.9)',
+      '@media (prefers-reduced-motion: reduce)': {
+        default: 'scale(1)',
+        ':where([data-starting-style], [data-ending-style])': 'scale(1)',
+      },
+    },
+    transitionDuration: {
+      default: durationVars['--cl-duration-base'],
+      ':where([data-ending-style])': durationVars['--cl-duration-fast'],
+    },
+    transitionProperty: {
+      default: 'opacity, transform',
+      '@media (prefers-reduced-motion: reduce)': 'opacity',
+    },
+    transitionTimingFunction: {
+      default: `${easingVars['--cl-ease-enter']}, ${easingVars['--cl-ease-default']}`,
+      ':where([data-ending-style])': easingVars['--cl-ease-exit'],
+    },
+  },
+});