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'],
+ },
+});

.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'],
+ },
+});

.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'],
+ },
+});

.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'],
+ },
+});

.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'],
+ },
+});

.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'],
+ },
+});

.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'],
+ },
+});

.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'],
+ },
+});