feat(ui,headless): switch accounts from a flyout in the Mosaic UserButton

.changeset/mosaic-user-button-switch-accounts-flyout.md

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

packages/headless/src/primitives/menu/menu-root.tsx

@@ -28,19 +28,30 @@ import { useControllableState } from '../../hooks/use-controllable-state';
 import { useReturnFocus } from '../../hooks/use-return-focus';
 import { useTransition } from '../../hooks/use-transition';
 import { cssVars } from '../../utils/css-vars';
+import { resolveSideOffset, type SideOffset } from '../../utils/side-offset';
 import { MenuContext, type MenuContextValue } from './menu-context';
 
 export interface MenuProps {
   open?: boolean;
   defaultOpen?: boolean;
   onOpenChange?: (open: boolean) => void;
   placement?: Placement;
-  sideOffset?: number;
+  /**
+   * The gap between the trigger and the menu, in px. `{ x, y }` gives the horizontal and vertical
+   * placements a gap each, for a menu that can flip between the two axes.
+   */
+  sideOffset?: SideOffset;
+  /**
+   * Where the menu goes when `placement` does not fit, in the order it tries them. Defaults to the
+   * opposite side. A menu opened from inside another floating surface wants this: the opposite side
+   * is that surface, so it has to be given somewhere else to land.
+   */
+  fallbackPlacements?: Placement[];
   children: ReactNode;
 }
 
 function MenuInner(props: MenuProps) {
-  const { placement: placementProp, sideOffset, children } = props;
+  const { placement: placementProp, sideOffset, fallbackPlacements, children } = props;
 
   const parentContext = useContext(MenuContext);
   const tree = useFloatingTree();
@@ -74,11 +85,11 @@ function MenuInner(props: MenuProps) {
     onOpenChange: setOpen,
     placement: resolvedPlacement,
     middleware: [
-      offset({
-        mainAxis: resolvedOffset,
+      offset(state => ({
+        mainAxis: resolveSideOffset(resolvedOffset, state.placement),
         alignmentAxis: isNested ? -4 : 0,
-      }),
-      flip(),
+      })),
+      flip({ fallbackPlacements }),
       shift({ padding: 5 }),
       arrow({ element: arrowRef }),
       cssVars({ sideOffset: resolvedOffset }),

packages/headless/src/utils/css-vars.ts

@@ -1,5 +1,7 @@
 import { detectOverflow, type Middleware } from '@floating-ui/react';
 
+import { resolveSideOffset, type SideOffset } from './side-offset';
+
 /**
  * Positioning middleware that sets CSS custom properties on the floating element:
  *
@@ -12,13 +14,13 @@ import { detectOverflow, type Middleware } from '@floating-ui/react';
  *
  * Place **after** `arrow()` so arrow position data is available for transform-origin.
  */
-export function cssVars(opts?: { sideOffset?: number }): Middleware {
+export function cssVars(opts?: { sideOffset?: SideOffset }): Middleware {
   return {
     name: 'cssVars',
     async fn(state) {
       const { elements, rects, middlewareData, placement } = state;
       const style = elements.floating.style;
-      const sideOffset = opts?.sideOffset ?? 0;
+      const sideOffset = resolveSideOffset(opts?.sideOffset ?? 0, placement);
 
       // Anchor dimensions
       style.setProperty('--cl-anchor-width', `${rects.reference.width}px`);

packages/headless/src/utils/index.ts

@@ -2,6 +2,7 @@ export { cssVars } from './css-vars';
 export { Freeze, type FreezeProps } from './freeze';
 export { isKeyboardEvent, isKeyboardOpen } from './interaction-modality';
 export { resetLayoutStyles } from './reset-layout-styles';
+export { resolveSideOffset, type SideOffset } from './side-offset';
 export {
   type ComponentProps,
   type DefaultProps,

packages/headless/src/utils/side-offset.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+
+import { resolveSideOffset } from './side-offset';
+
+describe('resolveSideOffset', () => {
+  it('takes one number for every placement', () => {
+    expect(resolveSideOffset(8, 'top-start')).toBe(8);
+    expect(resolveSideOffset(8, 'right')).toBe(8);
+  });
+
+  it('takes x on a horizontal placement and y on a vertical one', () => {
+    const offset = { x: 16, y: 8 };
+
+    expect(resolveSideOffset(offset, 'right-start')).toBe(16);
+    expect(resolveSideOffset(offset, 'left-end')).toBe(16);
+    expect(resolveSideOffset(offset, 'top-start')).toBe(8);
+    expect(resolveSideOffset(offset, 'bottom')).toBe(8);
+  });
+});

packages/headless/src/utils/side-offset.ts

@@ -0,0 +1,17 @@
+import type { Placement } from '@floating-ui/react';
+
+/**
+ * The gap between a floating element and what it is anchored to, in px. One number covers every
+ * placement. `{ x, y }` gives the horizontal and vertical sides a gap each, which a surface that can
+ * flip between the two axes wants: what it has to clear sideways is not what it has to clear above.
+ */
+export type SideOffset = number | { x: number; y: number };
+
+/** Picks the gap the placement's own axis asks for. */
+export function resolveSideOffset(offset: SideOffset, placement: Placement): number {
+  if (typeof offset === 'number') {
+    return offset;
+  }
+  const side = placement.split('-')[0];
+  return side === 'left' || side === 'right' ? offset.x : offset.y;
+}

packages/swingset/src/stories/menu.component.mdx

@@ -23,31 +23,38 @@ import { Menu } from '@clerk/ui/mosaic/components/menu';
 
 <Menu.Root>
   <Menu.Trigger />
-  <Menu.Content>
+  <Menu.Popup>
     <Menu.Item label='Add workspace'>
-      <Icon name='plus' />
-      Add workspace
+      <Menu.Media>
+        <Icon name='plus' />
+      </Menu.Media>
+      <Menu.Label>Add workspace</Menu.Label>
     </Menu.Item>
     <Menu.Item
       label='Sign out'
       onClick={signOut}
     >
-      <Icon name='log-out' />
-      Sign out
+      <Menu.Media>
+        <Icon name='log-out' />
+      </Menu.Media>
+      <Menu.Label>Sign out</Menu.Label>
     </Menu.Item>
     <Menu.Item
       label='Delete user'
       color='negative'
       onClick={deleteUser}
     >
-      <Icon name='close' />
-      Delete user
+      <Menu.Media>
+        <Icon name='close' />
+      </Menu.Media>
+      <Menu.Label>Delete user</Menu.Label>
     </Menu.Item>
-  </Menu.Content>
+  </Menu.Popup>
 </Menu.Root>;
 ```
 
-`Menu.Content` composes the portal, positioner, and popup, so items are the only children you write.
+`Menu.Popup` renders the portal and the floating positioner itself — neither is a part you compose
+— so items are the only children you write.
 
 ### Trigger
 
@@ -63,21 +70,80 @@ props (ARIA attributes, click and keyboard handlers) to spread.
 
 ### Items
 
-`label` drives typeahead and is used as the visible text when `children` is omitted. Render an icon
-and text together as children. Use `color='negative'` for destructive actions; the color is
-inherited by the children. `disabled` items are skipped by keyboard navigation and their `onClick`
-never fires. Activating an item closes the menu; pass `closeOnClick={false}` to keep it open.
+`label` names the item for typeahead and for assistive technology. What the row shows is composed
+from `Menu.Media` and `Menu.Label`, and those children are required: text dropped straight into the
+item is not a flex child the row can size, so it neither lines up with the other rows nor
+truncates. A row with nothing to lead it is `Menu.Label` alone. Use
+`color='negative'` for destructive actions; the color is inherited by the children. `disabled` items
+are skipped by keyboard navigation and their `onClick` never fires. Activating an item closes the
+menu; pass `closeOnClick={false}` to keep it open.
 
 ```tsx
+<Menu.Item
+  label='Revoke'
+  color='negative'
+>
+  <Menu.Label>Revoke</Menu.Label>
+</Menu.Item>
+
 <Menu.Item
   label='Delete'
   color='negative'
 >
-  <Icon name='close' />
-  Delete
+  <Menu.Media>
+    <Icon name='close' />
+  </Menu.Media>
+  <Menu.Label>Delete</Menu.Label>
 </Menu.Item>
 ```
 
+### Media
+
+`Menu.Media` is a square leading column that centers whatever it holds — an icon, an image, an
+avatar. Items that lead with marks of differing widths need it: without it each row sets its own
+text start, and the labels no longer line up. Leave it empty on an item that leads with nothing and
+that row keeps the column. It renders a `span`, since the item it sits in is a button.
+
+`size` is the column's width: `sm` (the default) fits an icon or an avatar, `xs` a bare glyph. The
+row has no height of its own, so it takes whatever the media asks for. That makes the size a
+per-menu decision rather than a per-item one: give every item in one menu the same value, or their
+text no longer starts on one line.
+
+```tsx
+<Menu.Media size='xs'>
+  <Icon name='check' />
+</Menu.Media>
+```
+
+### Label
+
+`Menu.Label` takes the space between the media and whatever trails it, and truncates its text to one
+line. Items whose text is a name — an account, a workspace — need it most: a long name would widen
+the menu instead of ellipsing. It is also what pushes a trailing mark to the end of the row. Use it
+for every composed item, so rows built from parts all read the same.
+
+The two together are the whole of a row that leads with an avatar and trails with a check:
+
+```tsx
+<Menu.Item label='colin@clerk.dev'>
+  <Menu.Media>
+    <Avatar.Root
+      shape='circle'
+      size='fit'
+    >
+      <Avatar.Fallback>C</Avatar.Fallback>
+    </Avatar.Root>
+  </Menu.Media>
+  <Menu.Label>colin@clerk.dev</Menu.Label>
+  <Icon name='check' size='sm' />
+</Menu.Item>
+```
+
+<Story
+  name='Accounts'
+  storyModule={MenuStories}
+/>
+
 ### Placement
 
 `Menu.Root` takes `placement` and `sideOffset`; the popup flips and shifts automatically to stay in
@@ -92,6 +158,22 @@ view, and its `max-height` tracks the available space so long menus scroll rathe
 </Menu.Root>;
 ```
 
+`sideOffset` also takes `{ x, y }`, one gap per axis, for a menu that can flip between the two: what
+it has to clear sideways is not what it has to clear above. `fallbackPlacements` names where it goes
+when `placement` does not fit, in the order it tries them, instead of the opposite side. A menu
+opened from inside another floating surface wants both — the opposite side is that surface, so it
+has to be given somewhere else to land.
+
+```tsx
+<Menu.Root
+  placement='right-start'
+  sideOffset={{ x: 16, y: 8 }}
+  fallbackPlacements={['left-start', 'top-start', 'bottom-start']}
+>
+  …
+</Menu.Root>;
+```
+
 ### Controlled
 
 ```tsx
@@ -107,13 +189,15 @@ const [open, setOpen] = useState(false);
 
 ## Parts
 
-| Part             | Slot                             | Description                                                           |
-| ---------------- | -------------------------------- | --------------------------------------------------------------------- |
-| `Menu.Root`      | —                                | State provider; owns open/close, placement, and keyboard navigation.  |
-| `Menu.Trigger`   | `menu-trigger`                   | Opens the menu. Defaults to a square ghost `Button` with an ellipsis. |
-| `Menu.Content`   | `menu-positioner` / `menu-popup` | Portals, positions, and renders the popup surface.                    |
-| `Menu.Item`      | `menu-item`                      | A single action whose content is composed through children.           |
-| `Menu.Separator` | `menu-separator`                 | Full-bleed divider between groups of items.                           |
+| Part             | Slot                             | Description                                                                     |
+| ---------------- | -------------------------------- | ------------------------------------------------------------------------------- |
+| `Menu.Root`      | —                                | State provider; owns open/close, placement, and keyboard navigation.            |
+| `Menu.Trigger`   | `menu-trigger`                   | Opens the menu. Defaults to a square ghost `Button` with an ellipsis.           |
+| `Menu.Popup`     | `menu-positioner` / `menu-popup` | Portals, positions, and renders the popup surface.                              |
+| `Menu.Item`      | `menu-item`                      | A single action whose content is composed through children.                     |
+| `Menu.Media`     | `menu-media`                     | Square leading column that centers an item's icon, image, or avatar.            |
+| `Menu.Label`     | `menu-label`                     | The item's text. Fills the row between media and trailing marks, and truncates. |
+| `Menu.Separator` | `menu-separator`                 | Full-bleed divider between groups of items.                                     |
 
 ## Styling
 

packages/swingset/src/stories/menu.component.stories.tsx

@@ -1,3 +1,4 @@
+import { Avatar } from '@clerk/ui/mosaic/components/avatar';
 import { Icon } from '@clerk/ui/mosaic/components/icon';
 import { Menu } from '@clerk/ui/mosaic/components/menu';
 
@@ -17,23 +18,66 @@ export function Default() {
   return (
     <Menu.Root>
       <Menu.Trigger />
-      <Menu.Content>
+      <Menu.Popup>
         <Menu.Item label='Add workspace'>
-          <Icon name='plus' />
-          Add workspace
+          <Menu.Media>
+            <Icon name='plus' />
+          </Menu.Media>
+          <Menu.Label>Add workspace</Menu.Label>
         </Menu.Item>
         <Menu.Item label='Sign out'>
-          <Icon name='log-out' />
-          Sign out
+          <Menu.Media>
+            <Icon name='log-out' />
+          </Menu.Media>
+          <Menu.Label>Sign out</Menu.Label>
         </Menu.Item>
         <Menu.Item
           label='Delete user'
           color='negative'
         >
-          <Icon name='close' />
-          Delete user
+          <Menu.Media>
+            <Icon name='close' />
+          </Menu.Media>
+          <Menu.Label>Delete user</Menu.Label>
         </Menu.Item>
-      </Menu.Content>
+      </Menu.Popup>
+    </Menu.Root>
+  );
+}
+
+const accounts = [
+  { active: true, identifier: 'colin@clerk.dev', initial: 'C' },
+  { active: false, identifier: 'braden.wiggins@a-very-long-domain.example', initial: 'B' },
+];
+
+export function Accounts() {
+  return (
+    <Menu.Root>
+      <Menu.Trigger>Switch account</Menu.Trigger>
+      <Menu.Popup>
+        {accounts.map(account => (
+          <Menu.Item
+            key={account.identifier}
+            label={account.identifier}
+          >
+            <Menu.Media>
+              <Avatar.Root
+                shape='circle'
+                size='fit'
+              >
+                <Avatar.Fallback>{account.initial}</Avatar.Fallback>
+              </Avatar.Root>
+            </Menu.Media>
+            <Menu.Label>{account.identifier}</Menu.Label>
+            {account.active ? (
+              <Icon
+                name='check'
+                size='sm'
+              />
+            ) : null}
+          </Menu.Item>
+        ))}
+      </Menu.Popup>
     </Menu.Root>
   );
 }