feat(ui): add Mosaic Menu component

.changeset/mosaic-menu.md

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

.changeset/tidy-menus-wave.md

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

packages/swingset/src/components/DocsViewer.tsx

@@ -37,6 +37,7 @@ const docModules: Record<string, Record<string, React.ComponentType>> = {
     dialog: dynamic(() => import('../stories/dialog.component.mdx')),
     heading: dynamic(() => import('../stories/heading.mdx')),
     icon: dynamic(() => import('../stories/icon.mdx')),
+    menu: dynamic(() => import('../stories/menu.component.mdx')),
     tabs: dynamic(() => import('../stories/tabs.component.mdx')),
     text: dynamic(() => import('../stories/text.mdx')),
   },

packages/swingset/src/lib/registry.ts

@@ -52,6 +52,7 @@ import {
   Interactive as ItemInteractive,
   meta as itemMeta,
 } from '../stories/item.stories';
+import { Default as MenuComponentDefault, meta as menuComponentMeta } from '../stories/menu.component.stories';
 import { meta as menuMeta } from '../stories/menu.stories';
 import {
   Default as OrganizationProfileDefault,
@@ -169,6 +170,8 @@ const headingModule: StoryModule = {
   Colors: HeadingColors,
 };
 
+const menuComponentModule: StoryModule = { meta: menuComponentMeta, Default: MenuComponentDefault };
+
 const tabsComponentModule: StoryModule = { meta: tabsComponentMeta, Default: TabsComponentDefault };
 
 const textModule: StoryModule = { meta: textMeta, Default: TextDefault, Sizes: TextSizes, Colors: TextColors };
@@ -221,6 +224,7 @@ export const registry: StoryModule[] = [
   dialogComponentModule,
   headingModule,
   iconModule,
+  menuComponentModule,
   tabsComponentModule,
   textModule,
   // Primitives — alphabetical within the group.

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

@@ -0,0 +1,138 @@
+import * as MenuStories from './menu.component.stories';
+
+# Menu
+
+The Mosaic `Menu` — the styled Mosaic component composed from the `@clerk/headless` menu primitive
+and themed with StyleX. It inherits the primitive's positioning, typeahead, roving keyboard
+navigation, and ARIA wiring, and adds the trigger, popup surface, and item styling.
+
+## Example
+
+Click the trigger, then use the arrow keys or type to move between items.
+
+<Story
+  name='Default'
+  storyModule={MenuStories}
+/>
+
+## Usage
+
+```tsx
+import { Icon } from '@clerk/ui/mosaic/components/icon';
+import { Menu } from '@clerk/ui/mosaic/components/menu';
+
+<Menu.Root>
+  <Menu.Trigger />
+  <Menu.Content>
+    <Menu.Item label='Add workspace'>
+      <Icon name='plus' />
+      Add workspace
+    </Menu.Item>
+    <Menu.Item
+      label='Sign out'
+      onClick={signOut}
+    >
+      <Icon name='log-out' />
+      Sign out
+    </Menu.Item>
+    <Menu.Item
+      label='Delete user'
+      color='negative'
+      onClick={deleteUser}
+    >
+      <Icon name='close' />
+      Delete user
+    </Menu.Item>
+  </Menu.Content>
+</Menu.Root>;
+```
+
+`Menu.Content` composes the portal, positioner, and popup, so items are the only children you write.
+
+### Trigger
+
+With no children, `Menu.Trigger` renders a square ghost `Button` holding an ellipsis glyph. Pass
+children for a labelled trigger, or `render` to supply your own element — it receives the computed
+props (ARIA attributes, click and keyboard handlers) to spread.
+
+```tsx
+<Menu.Trigger>Actions</Menu.Trigger>
+
+<Menu.Trigger render={props => <Avatar {...props} />} />
+```
+
+### 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.
+
+```tsx
+<Menu.Item
+  label='Delete'
+  color='negative'
+>
+  <Icon name='close' />
+  Delete
+</Menu.Item>
+```
+
+### Placement
+
+`Menu.Root` takes `placement` and `sideOffset`; the popup flips and shifts automatically to stay in
+view, and its `max-height` tracks the available space so long menus scroll rather than overflow.
+
+```tsx
+<Menu.Root
+  placement='bottom-end'
+  sideOffset={8}
+>
+  …
+</Menu.Root>;
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Menu.Root
+  open={open}
+  onOpenChange={setOpen}
+>
+  …
+</Menu.Root>;
+```
+
+## 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.                           |
+
+## Styling
+
+Unlike the slot-recipe components, the Mosaic menu is themed with **StyleX**. Each styled part
+carries a stable `.cl-<slot>` class (the slots above) alongside the StyleX atoms. Consumers never
+target the hashed atomic classes — override by targeting the `.cl-*` slot from a CSS layer that wins
+over `@clerk/ui/styles.css`:
+
+```css
+@import '@clerk/ui/styles.css' layer(components);
+
+@layer overrides {
+  .cl-menu-popup {
+    border-radius: 20px;
+  }
+}
+```
+
+The popup's enter/exit transition is driven off its own `data-starting-style` /`data-ending-style`
+attributes and is disabled under `prefers-reduced-motion: reduce`. Item hover state is gated behind
+`@media (hover: hover)`, and the keyboard-active item is styled off `data-active`, so pointer and
+keyboard highlighting stay in sync.

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

@@ -0,0 +1,40 @@
+/** @jsxImportSource @emotion/react */
+import { Icon } from '@clerk/ui/mosaic/components/icon';
+import { Menu } from '@clerk/ui/mosaic/components/menu';
+
+import type { StoryMeta } from '@/lib/types';
+
+// Exposes this file's own source (via the `?raw` webpack rule) so each `<Story>` example
+// renders a code footer with its function's source. See `StoryModule.__source`.
+export { default as __source } from './menu.component.stories?raw';
+
+export const meta: StoryMeta = {
+  group: 'Components',
+  title: 'Menu',
+  source: 'packages/ui/src/mosaic/components/menu/menu.tsx',
+};
+
+export function Default() {
+  return (
+    <Menu.Root>
+      <Menu.Trigger />
+      <Menu.Content>
+        <Menu.Item label='Add workspace'>
+          <Icon name='plus' />
+          Add workspace
+        </Menu.Item>
+        <Menu.Item label='Sign out'>
+          <Icon name='log-out' />
+          Sign out
+        </Menu.Item>
+        <Menu.Item
+          label='Delete user'
+          color='negative'
+        >
+          <Icon name='close' />
+          Delete user
+        </Menu.Item>
+      </Menu.Content>
+    </Menu.Root>
+  );
+}

packages/ui/src/mosaic/components/menu/index.ts

@@ -0,0 +1,2 @@
+export { Menu, MenuContent, MenuItem, MenuSeparator, MenuTrigger } from './menu';
+export type { MenuContentProps, MenuItemProps, MenuProps, MenuSeparatorProps, MenuTriggerProps } from './menu';

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

@@ -0,0 +1,115 @@
+import * as stylex from '@stylexjs/stylex';
+
+import { colorVars, fontWeightVars, radiusVars, space, typeScaleVars } from '../../tokens.stylex';
+
+export const styles = stylex.create({
+  // Positioning is applied inline by the headless positioner; this only clears the
+  // focus outline it receives. No z-index: the portalled, fixed positioner already
+  // paints above page content, and consumers own their own stacking order.
+  positioner: {
+    outline: 'none',
+  },
+
+  popup: {
+    borderRadius: radiusVars['--cl-radius-element'],
+    gap: space['0.5'],
+    outline: 'none',
+    paddingBlock: space['0.5'],
+    paddingInline: space['0.5'],
+    backgroundColor: colorVars['--cl-color-card'],
+    boxShadow: `0 12px 12px -7px oklch(0.2046 0 0 / 12%),
+                0 24px 24px -10px oklch(0.2046 0 0 / 4%),
+                0 0 0 1px oklch(0.2046 0 0 / 4%)`,
+    boxSizing: 'border-box',
+    color: colorVars['--cl-color-card-foreground'],
+    display: 'flex',
+    flexDirection: 'column',
+    opacity: {
+      default: 1,
+      ':is([data-ending-style])': 0,
+      ':is([data-starting-style])': 0,
+    },
+    scale: {
+      default: 1,
+      ':is([data-ending-style])': 0.96,
+      ':is([data-starting-style])': 0.96,
+    },
+    // `--cl-transform-origin` is set on the positioner by the headless `cssVars`
+    // middleware, so the popup scales out of the edge nearest its trigger.
+    transformOrigin: 'var(--cl-transform-origin)',
+    transitionDuration: {
+      default: '150ms',
+      '@media (prefers-reduced-motion: reduce)': '0.01ms',
+    },
+    transitionProperty: 'opacity, scale',
+    transitionTimingFunction: 'ease-out',
+    maxHeight: 'var(--cl-available-height)',
+    minWidth: '12.5rem',
+    overflowY: 'auto',
+  },
+
+  item: {
+    borderRadius: '0.375rem',
+    borderStyle: 'none',
+    gap: space['1'],
+    outline: 'none',
+    paddingBlock: space['1'],
+    paddingInline: space['2'],
+    alignItems: 'center',
+    backgroundColor: {
+      default: 'transparent',
+      ':is([data-active])': `color-mix(in oklab, ${colorVars['--cl-color-neutral']} 4%, transparent)`,
+      '@media (hover: hover)': {
+        ':hover': `color-mix(in oklab, ${colorVars['--cl-color-neutral']} 4%, transparent)`,
+      },
+    },
+    boxSizing: 'border-box',
+    color: 'inherit',
+    cursor: { default: 'pointer', ':is([data-disabled])': 'not-allowed' },
+    display: 'flex',
+    fontFamily: 'inherit',
+    fontSize: typeScaleVars['--cl-text-sm-size'],
+    fontWeight: fontWeightVars['--cl-font-medium'],
+    lineHeight: typeScaleVars['--cl-text-sm-leading'],
+    opacity: { default: 1, ':is([data-disabled])': 0.5 },
+    position: 'relative',
+    textAlign: 'start',
+    transitionDuration: {
+      default: '150ms',
+      '@media (prefers-reduced-motion: reduce)': '0.01ms',
+    },
+    transitionProperty: 'background-color',
+    height: space['7'],
+    width: '100%',
+    '::before': {
+      insetBlock: `calc(-1 * ${space['0.5']})`,
+      insetInline: `calc(-1 * ${space['0.5']})`,
+      content: '""',
+      position: 'absolute',
+    },
+  },
+
+  itemNegative: {
+    backgroundColor: {
+      default: 'transparent',
+      ':is([data-active])': `color-mix(in oklab, ${colorVars['--cl-color-negative']} 8%, transparent)`,
+      '@media (hover: hover)': {
+        ':hover': `color-mix(in oklab, ${colorVars['--cl-color-negative']} 8%, transparent)`,
+      },
+    },
+    color: colorVars['--cl-color-negative'],
+  },
+
+  separator: {
+    // Full-bleed across the popup: cancel the popup's inline padding.
+    marginBlock: space['0.5'],
+    marginInline: `calc(-1 * ${space['0.5']})`,
+    backgroundColor: colorVars['--cl-color-border'],
+    blockSize: '1px',
+  },
+
+  triggerIcon: {
+    height: space['4'],
+    width: space['4'],
+  },
+});