feat(headless): add Menu primitive

packages/headless/package.json

@@ -25,6 +25,10 @@
  "import": "./dist/primitives/select/index.js",
  "types": "./dist/primitives/select/index.d.ts"
  },
+ "./menu": {
+ "import": "./dist/primitives/menu/index.js",
+ "types": "./dist/primitives/menu/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/menu/README.md

@@ -0,0 +1,157 @@
+# Menu
+
+A dropdown menu with keyboard navigation, typeahead, and nested submenu support. Handles ARIA roles, safe hover zones for submenus, and tree-level close-on-click.
+
+## When to Use
+
+- Action menus, context menus, dropdown menus attached to a button trigger.
+- When you need nested submenus with safe pointer zones between trigger and submenu.
+- Prefer Menu over Popover when the content is a list of actions/commands rather than arbitrary content.
+
+## Usage
+
+```tsx
+import { Menu } from '@/primitives/menu';
+
+<Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item
+ label='Edit'
+ onClick={() => handleEdit()}
+ />
+ <Menu.Item
+ label='Duplicate'
+ onClick={() => handleDuplicate()}
+ />
+ <Menu.Separator />
+ <Menu.Item
+ label='Delete'
+ onClick={() => handleDelete()}
+ />
+ </Menu.Popup>
+ </Menu.Positioner>
+</Menu.Root>;
+```
+
+### Nested Submenus
+
+Nest a `<Menu.Root>` inside a parent `<Menu.Root>` — the nested trigger automatically renders as a `menuitem` and opens on hover with a safe polygon zone.
+
+```tsx
+<Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Edit' />
+ <Menu.Root>
+ <Menu.Trigger>Share</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Copy Link' />
+ <Menu.Item label='Email' />
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Menu.Popup>
+ </Menu.Positioner>
+</Menu.Root>
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Menu.Root
+ open={open}
+ onOpenChange={setOpen}
+>
+ {/* ... */}
+</Menu.Root>;
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| ----------------- | --------------- | -------------------------------------- |
+| `Menu.Root` | — | Root context provider |
+| `Menu.Trigger` | `<button>` | Opens/closes the menu |
+| `Menu.Portal` | — | Portals children (accepts `root` prop) |
+| `Menu.Positioner` | `<div>` | Floating positioned container |
+| `Menu.Popup` | `<div>` | Visual wrapper for menu items |
+| `Menu.Item` | `<button>` | A menu action item |
+| `Menu.Separator` | `<div>` | Visual divider between items |
+| `Menu.Arrow` | `<svg>` | Optional floating arrow |
+
+## Props
+
+### `Menu.Root`
+
+| Prop | Type | Default | Description |
+| -------------- | ------------------------- | ------------------------------------------------- | ---------------------------------- |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `placement` | `Placement` | `"bottom-start"` (root), `"right-start"` (nested) | Floating UI placement |
+| `sideOffset` | `number` | `4` (root), `0` (nested) | Gap between trigger and popup (px) |
+
+### `Menu.Item`
+
+| Prop | Type | Default | Description |
+| -------------- | --------- | ------------ | ------------------------------------------------------ |
+| `label` | `string` | **required** | Item text, also used for typeahead matching |
+| `disabled` | `boolean` | — | Prevents click handler, keeps item focusable |
+| `closeOnClick` | `boolean` | `true` | Whether clicking this item closes the entire menu tree |
+
+### `Menu.Trigger`, `Menu.Positioner`, `Menu.Popup`, `Menu.Separator`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Menu.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard Navigation
+
+| Key | Action |
+| ----------------- | -------------------------------------- |
+| `ArrowDown` | Move to next item |
+| `ArrowUp` | Move to previous item |
+| `ArrowRight` | Open nested submenu |
+| `ArrowLeft` | Close nested submenu, return to parent |
+| `Enter` / `Space` | Activate the focused item |
+| `Escape` | Close the current menu level |
+| Type a character | Jump to matching item (typeahead) |
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ----------------- | ------------------------------------ |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"menu-item"`) |
+| `data-cl-open` / `data-cl-closed` | Trigger | Menu open state |
+| `data-cl-active` | Item | Keyboard-focused item |
+| `data-cl-disabled` | Item | Disabled item |
+| `data-cl-side` | Positioner, Arrow | Resolved placement side |
+
+## Nested Menu Behavior
+
+- Nested menus open on hover (75ms delay) with a `safePolygon` safe zone.
+- Only one sibling submenu can be open at a time.
+- Clicking any item with `closeOnClick={true}` (default) closes the entire menu tree via a tree event.
+- `Escape` closes the innermost menu first, bubbling up through the tree.
+
+## Important Notes
+
+- **No built-in animations.** The positioner simply mounts/unmounts. Use `data-cl-open`/`data-cl-closed` for CSS-driven transitions.
+- **Disabled items use `aria-disabled`, not `disabled`.** They remain focusable for keyboard users.
+- **`label` is required on `Menu.Item`** — it drives typeahead matching. Disabled items are excluded from typeahead.
+
+## ARIA
+
+- Popup: `role="menu"`
+- Item: `role="menuitem"`, `aria-disabled`
+- Separator: `role="separator"`
+- Trigger: `aria-expanded`, `aria-haspopup="menu"`, `aria-controls`
+- Nested trigger: `role="menuitem"` (instead of button)

packages/headless/src/primitives/menu/index.ts

@@ -0,0 +1,12 @@
+export * as Menu from './parts';
+
+export type {
+ MenuArrowProps,
+ MenuItemProps,
+ MenuPopupProps,
+ MenuPortalProps,
+ MenuPositionerProps,
+ MenuProps,
+ MenuSeparatorProps,
+ MenuTriggerProps,
+} from './parts';

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

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { useMenuContext } from './menu-context';
+
+export interface MenuArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function MenuArrow(props: MenuArrowProps) {
+ const { floatingContext, arrowRef, placement } = useMenuContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='menu-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/menu/menu-context.ts

@@ -0,0 +1,40 @@
+import type {
+ ExtendedRefs,
+ FloatingContext,
+ Placement,
+ ReferenceType,
+ UseInteractionsReturn,
+} from '@floating-ui/react';
+import { type CSSProperties, createContext, useContext } from 'react';
+import type { TransitionProps } from '../../hooks/use-transition';
+
+export interface MenuContextValue {
+ open: boolean;
+ floatingContext: FloatingContext;
+ refs: ExtendedRefs<ReferenceType>;
+ floatingStyles: CSSProperties;
+ placement: Placement;
+ getReferenceProps: UseInteractionsReturn['getReferenceProps'];
+ getFloatingProps: UseInteractionsReturn['getFloatingProps'];
+ getItemProps: UseInteractionsReturn['getItemProps'];
+ activeIndex: number | null;
+ setActiveIndex: React.Dispatch<React.SetStateAction<number | null>>;
+ elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
+ labelsRef: React.MutableRefObject<Array<string | null>>;
+ arrowRef: React.MutableRefObject<SVGSVGElement | null>;
+ popupRef: React.RefObject<HTMLDivElement | null>;
+ isNested: boolean;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+ parentContext: MenuContextValue | null;
+}
+
+export const MenuContext = createContext<MenuContextValue | null>(null);
+
+export function useMenuContext() {
+ const ctx = useContext(MenuContext);
+ if (!ctx) {
+ throw new Error('Menu compound components must be used within <Menu>');
+ }
+ return ctx;
+}

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

@@ -0,0 +1,52 @@
+'use client';
+
+import { useFloatingTree, useListItem } from '@floating-ui/react';
+import React from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useMenuContext } from './menu-context';
+
+export interface MenuItemProps extends ComponentProps<'button'> {
+ label: string;
+ disabled?: boolean;
+ closeOnClick?: boolean;
+}
+
+export function MenuItem(props: MenuItemProps) {
+ const { render, label, disabled, closeOnClick = true, ...otherProps } = props;
+ const { activeIndex, getItemProps } = useMenuContext();
+ const tree = useFloatingTree();
+ const item = useListItem({ label: disabled ? null : label });
+ const isActive = item.index === activeIndex;
+
+ const state = {
+ active: isActive,
+ disabled: !!disabled,
+ };
+
+ const defaultProps = {
+ 'data-cl-slot': 'menu-item',
+ type: 'button' as const,
+ ref: item.ref,
+ role: 'menuitem' as const,
+ tabIndex: isActive ? 0 : -1,
+ ...(disabled && { 'aria-disabled': true as const }),
+ ...(getItemProps({
+ onClick() {
+ if (!disabled && closeOnClick) {
+ tree?.events.emit('click');
+ }
+ },
+ }) as React.ComponentPropsWithRef<'button'>),
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ state,
+ stateAttributesMapping: {
+ active: (v: boolean) => (v ? { 'data-cl-active': '' } : null),
+ disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+ },
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

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

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useMenuContext } from './menu-context';
+
+export interface MenuPopupProps extends ComponentProps<'div'> {}
+
+export function MenuPopup(props: MenuPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = useMenuContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'menu-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

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

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { useMenuContext } from './menu-context';
+
+export interface MenuPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function MenuPortal(props: MenuPortalProps) {
+ const { mounted } = useMenuContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/package.json

@@ -25,6 +25,10 @@
  "import": "./dist/primitives/select/index.js",
  "types": "./dist/primitives/select/index.d.ts"
  },
+ "./menu": {
+ "import": "./dist/primitives/menu/index.js",
+ "types": "./dist/primitives/menu/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/menu/README.md

@@ -0,0 +1,157 @@
+# Menu
+
+A dropdown menu with keyboard navigation, typeahead, and nested submenu support. Handles ARIA roles, safe hover zones for submenus, and tree-level close-on-click.
+
+## When to Use
+
+- Action menus, context menus, dropdown menus attached to a button trigger.
+- When you need nested submenus with safe pointer zones between trigger and submenu.
+- Prefer Menu over Popover when the content is a list of actions/commands rather than arbitrary content.
+
+## Usage
+
+```tsx
+import { Menu } from '@/primitives/menu';
+
+<Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item
+ label='Edit'
+ onClick={() => handleEdit()}
+ />
+ <Menu.Item
+ label='Duplicate'
+ onClick={() => handleDuplicate()}
+ />
+ <Menu.Separator />
+ <Menu.Item
+ label='Delete'
+ onClick={() => handleDelete()}
+ />
+ </Menu.Popup>
+ </Menu.Positioner>
+</Menu.Root>;
+```
+
+### Nested Submenus
+
+Nest a `<Menu.Root>` inside a parent `<Menu.Root>` — the nested trigger automatically renders as a `menuitem` and opens on hover with a safe polygon zone.
+
+```tsx
+<Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Edit' />
+ <Menu.Root>
+ <Menu.Trigger>Share</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Copy Link' />
+ <Menu.Item label='Email' />
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Menu.Popup>
+ </Menu.Positioner>
+</Menu.Root>
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Menu.Root
+ open={open}
+ onOpenChange={setOpen}
+>
+ {/* ... */}
+</Menu.Root>;
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| ----------------- | --------------- | -------------------------------------- |
+| `Menu.Root` | — | Root context provider |
+| `Menu.Trigger` | `<button>` | Opens/closes the menu |
+| `Menu.Portal` | — | Portals children (accepts `root` prop) |
+| `Menu.Positioner` | `<div>` | Floating positioned container |
+| `Menu.Popup` | `<div>` | Visual wrapper for menu items |
+| `Menu.Item` | `<button>` | A menu action item |
+| `Menu.Separator` | `<div>` | Visual divider between items |
+| `Menu.Arrow` | `<svg>` | Optional floating arrow |
+
+## Props
+
+### `Menu.Root`
+
+| Prop | Type | Default | Description |
+| -------------- | ------------------------- | ------------------------------------------------- | ---------------------------------- |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `placement` | `Placement` | `"bottom-start"` (root), `"right-start"` (nested) | Floating UI placement |
+| `sideOffset` | `number` | `4` (root), `0` (nested) | Gap between trigger and popup (px) |
+
+### `Menu.Item`
+
+| Prop | Type | Default | Description |
+| -------------- | --------- | ------------ | ------------------------------------------------------ |
+| `label` | `string` | **required** | Item text, also used for typeahead matching |
+| `disabled` | `boolean` | — | Prevents click handler, keeps item focusable |
+| `closeOnClick` | `boolean` | `true` | Whether clicking this item closes the entire menu tree |
+
+### `Menu.Trigger`, `Menu.Positioner`, `Menu.Popup`, `Menu.Separator`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Menu.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard Navigation
+
+| Key | Action |
+| ----------------- | -------------------------------------- |
+| `ArrowDown` | Move to next item |
+| `ArrowUp` | Move to previous item |
+| `ArrowRight` | Open nested submenu |
+| `ArrowLeft` | Close nested submenu, return to parent |
+| `Enter` / `Space` | Activate the focused item |
+| `Escape` | Close the current menu level |
+| Type a character | Jump to matching item (typeahead) |
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ----------------- | ------------------------------------ |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"menu-item"`) |
+| `data-cl-open` / `data-cl-closed` | Trigger | Menu open state |
+| `data-cl-active` | Item | Keyboard-focused item |
+| `data-cl-disabled` | Item | Disabled item |
+| `data-cl-side` | Positioner, Arrow | Resolved placement side |
+
+## Nested Menu Behavior
+
+- Nested menus open on hover (75ms delay) with a `safePolygon` safe zone.
+- Only one sibling submenu can be open at a time.
+- Clicking any item with `closeOnClick={true}` (default) closes the entire menu tree via a tree event.
+- `Escape` closes the innermost menu first, bubbling up through the tree.
+
+## Important Notes
+
+- **No built-in animations.** The positioner simply mounts/unmounts. Use `data-cl-open`/`data-cl-closed` for CSS-driven transitions.
+- **Disabled items use `aria-disabled`, not `disabled`.** They remain focusable for keyboard users.
+- **`label` is required on `Menu.Item`** — it drives typeahead matching. Disabled items are excluded from typeahead.
+
+## ARIA
+
+- Popup: `role="menu"`
+- Item: `role="menuitem"`, `aria-disabled`
+- Separator: `role="separator"`
+- Trigger: `aria-expanded`, `aria-haspopup="menu"`, `aria-controls`
+- Nested trigger: `role="menuitem"` (instead of button)

packages/headless/src/primitives/menu/index.ts

@@ -0,0 +1,12 @@
+export * as Menu from './parts';
+
+export type {
+ MenuArrowProps,
+ MenuItemProps,
+ MenuPopupProps,
+ MenuPortalProps,
+ MenuPositionerProps,
+ MenuProps,
+ MenuSeparatorProps,
+ MenuTriggerProps,
+} from './parts';

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

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { useMenuContext } from './menu-context';
+
+export interface MenuArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function MenuArrow(props: MenuArrowProps) {
+ const { floatingContext, arrowRef, placement } = useMenuContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='menu-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/menu/menu-context.ts

@@ -0,0 +1,40 @@
+import type {
+ ExtendedRefs,
+ FloatingContext,
+ Placement,
+ ReferenceType,
+ UseInteractionsReturn,
+} from '@floating-ui/react';
+import { type CSSProperties, createContext, useContext } from 'react';
+import type { TransitionProps } from '../../hooks/use-transition';
+
+export interface MenuContextValue {
+ open: boolean;
+ floatingContext: FloatingContext;
+ refs: ExtendedRefs<ReferenceType>;
+ floatingStyles: CSSProperties;
+ placement: Placement;
+ getReferenceProps: UseInteractionsReturn['getReferenceProps'];
+ getFloatingProps: UseInteractionsReturn['getFloatingProps'];
+ getItemProps: UseInteractionsReturn['getItemProps'];
+ activeIndex: number | null;
+ setActiveIndex: React.Dispatch<React.SetStateAction<number | null>>;
+ elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
+ labelsRef: React.MutableRefObject<Array<string | null>>;
+ arrowRef: React.MutableRefObject<SVGSVGElement | null>;
+ popupRef: React.RefObject<HTMLDivElement | null>;
+ isNested: boolean;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+ parentContext: MenuContextValue | null;
+}
+
+export const MenuContext = createContext<MenuContextValue | null>(null);
+
+export function useMenuContext() {
+ const ctx = useContext(MenuContext);
+ if (!ctx) {
+ throw new Error('Menu compound components must be used within <Menu>');
+ }
+ return ctx;
+}

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

@@ -0,0 +1,52 @@
+'use client';
+
+import { useFloatingTree, useListItem } from '@floating-ui/react';
+import React from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useMenuContext } from './menu-context';
+
+export interface MenuItemProps extends ComponentProps<'button'> {
+ label: string;
+ disabled?: boolean;
+ closeOnClick?: boolean;
+}
+
+export function MenuItem(props: MenuItemProps) {
+ const { render, label, disabled, closeOnClick = true, ...otherProps } = props;
+ const { activeIndex, getItemProps } = useMenuContext();
+ const tree = useFloatingTree();
+ const item = useListItem({ label: disabled ? null : label });
+ const isActive = item.index === activeIndex;
+
+ const state = {
+ active: isActive,
+ disabled: !!disabled,
+ };
+
+ const defaultProps = {
+ 'data-cl-slot': 'menu-item',
+ type: 'button' as const,
+ ref: item.ref,
+ role: 'menuitem' as const,
+ tabIndex: isActive ? 0 : -1,
+ ...(disabled && { 'aria-disabled': true as const }),
+ ...(getItemProps({
+ onClick() {
+ if (!disabled && closeOnClick) {
+ tree?.events.emit('click');
+ }
+ },
+ }) as React.ComponentPropsWithRef<'button'>),
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ state,
+ stateAttributesMapping: {
+ active: (v: boolean) => (v ? { 'data-cl-active': '' } : null),
+ disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+ },
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

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

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useMenuContext } from './menu-context';
+
+export interface MenuPopupProps extends ComponentProps<'div'> {}
+
+export function MenuPopup(props: MenuPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = useMenuContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'menu-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

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

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { useMenuContext } from './menu-context';
+
+export interface MenuPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function MenuPortal(props: MenuPortalProps) {
+ const { mounted } = useMenuContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/package.json

@@ -25,6 +25,10 @@
  "import": "./dist/primitives/select/index.js",
  "types": "./dist/primitives/select/index.d.ts"
  },
+ "./menu": {
+ "import": "./dist/primitives/menu/index.js",
+ "types": "./dist/primitives/menu/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/menu/README.md

@@ -0,0 +1,157 @@
+# Menu
+
+A dropdown menu with keyboard navigation, typeahead, and nested submenu support. Handles ARIA roles, safe hover zones for submenus, and tree-level close-on-click.
+
+## When to Use
+
+- Action menus, context menus, dropdown menus attached to a button trigger.
+- When you need nested submenus with safe pointer zones between trigger and submenu.
+- Prefer Menu over Popover when the content is a list of actions/commands rather than arbitrary content.
+
+## Usage
+
+```tsx
+import { Menu } from '@/primitives/menu';
+
+<Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item
+ label='Edit'
+ onClick={() => handleEdit()}
+ />
+ <Menu.Item
+ label='Duplicate'
+ onClick={() => handleDuplicate()}
+ />
+ <Menu.Separator />
+ <Menu.Item
+ label='Delete'
+ onClick={() => handleDelete()}
+ />
+ </Menu.Popup>
+ </Menu.Positioner>
+</Menu.Root>;
+```
+
+### Nested Submenus
+
+Nest a `<Menu.Root>` inside a parent `<Menu.Root>` — the nested trigger automatically renders as a `menuitem` and opens on hover with a safe polygon zone.
+
+```tsx
+<Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Edit' />
+ <Menu.Root>
+ <Menu.Trigger>Share</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Copy Link' />
+ <Menu.Item label='Email' />
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Menu.Popup>
+ </Menu.Positioner>
+</Menu.Root>
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Menu.Root
+ open={open}
+ onOpenChange={setOpen}
+>
+ {/* ... */}
+</Menu.Root>;
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| ----------------- | --------------- | -------------------------------------- |
+| `Menu.Root` | — | Root context provider |
+| `Menu.Trigger` | `<button>` | Opens/closes the menu |
+| `Menu.Portal` | — | Portals children (accepts `root` prop) |
+| `Menu.Positioner` | `<div>` | Floating positioned container |
+| `Menu.Popup` | `<div>` | Visual wrapper for menu items |
+| `Menu.Item` | `<button>` | A menu action item |
+| `Menu.Separator` | `<div>` | Visual divider between items |
+| `Menu.Arrow` | `<svg>` | Optional floating arrow |
+
+## Props
+
+### `Menu.Root`
+
+| Prop | Type | Default | Description |
+| -------------- | ------------------------- | ------------------------------------------------- | ---------------------------------- |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `placement` | `Placement` | `"bottom-start"` (root), `"right-start"` (nested) | Floating UI placement |
+| `sideOffset` | `number` | `4` (root), `0` (nested) | Gap between trigger and popup (px) |
+
+### `Menu.Item`
+
+| Prop | Type | Default | Description |
+| -------------- | --------- | ------------ | ------------------------------------------------------ |
+| `label` | `string` | **required** | Item text, also used for typeahead matching |
+| `disabled` | `boolean` | — | Prevents click handler, keeps item focusable |
+| `closeOnClick` | `boolean` | `true` | Whether clicking this item closes the entire menu tree |
+
+### `Menu.Trigger`, `Menu.Positioner`, `Menu.Popup`, `Menu.Separator`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Menu.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard Navigation
+
+| Key | Action |
+| ----------------- | -------------------------------------- |
+| `ArrowDown` | Move to next item |
+| `ArrowUp` | Move to previous item |
+| `ArrowRight` | Open nested submenu |
+| `ArrowLeft` | Close nested submenu, return to parent |
+| `Enter` / `Space` | Activate the focused item |
+| `Escape` | Close the current menu level |
+| Type a character | Jump to matching item (typeahead) |
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ----------------- | ------------------------------------ |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"menu-item"`) |
+| `data-cl-open` / `data-cl-closed` | Trigger | Menu open state |
+| `data-cl-active` | Item | Keyboard-focused item |
+| `data-cl-disabled` | Item | Disabled item |
+| `data-cl-side` | Positioner, Arrow | Resolved placement side |
+
+## Nested Menu Behavior
+
+- Nested menus open on hover (75ms delay) with a `safePolygon` safe zone.
+- Only one sibling submenu can be open at a time.
+- Clicking any item with `closeOnClick={true}` (default) closes the entire menu tree via a tree event.
+- `Escape` closes the innermost menu first, bubbling up through the tree.
+
+## Important Notes
+
+- **No built-in animations.** The positioner simply mounts/unmounts. Use `data-cl-open`/`data-cl-closed` for CSS-driven transitions.
+- **Disabled items use `aria-disabled`, not `disabled`.** They remain focusable for keyboard users.
+- **`label` is required on `Menu.Item`** — it drives typeahead matching. Disabled items are excluded from typeahead.
+
+## ARIA
+
+- Popup: `role="menu"`
+- Item: `role="menuitem"`, `aria-disabled`
+- Separator: `role="separator"`
+- Trigger: `aria-expanded`, `aria-haspopup="menu"`, `aria-controls`
+- Nested trigger: `role="menuitem"` (instead of button)

packages/headless/src/primitives/menu/index.ts

@@ -0,0 +1,12 @@
+export * as Menu from './parts';
+
+export type {
+ MenuArrowProps,
+ MenuItemProps,
+ MenuPopupProps,
+ MenuPortalProps,
+ MenuPositionerProps,
+ MenuProps,
+ MenuSeparatorProps,
+ MenuTriggerProps,
+} from './parts';

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

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { useMenuContext } from './menu-context';
+
+export interface MenuArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function MenuArrow(props: MenuArrowProps) {
+ const { floatingContext, arrowRef, placement } = useMenuContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='menu-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/menu/menu-context.ts

@@ -0,0 +1,40 @@
+import type {
+ ExtendedRefs,
+ FloatingContext,
+ Placement,
+ ReferenceType,
+ UseInteractionsReturn,
+} from '@floating-ui/react';
+import { type CSSProperties, createContext, useContext } from 'react';
+import type { TransitionProps } from '../../hooks/use-transition';
+
+export interface MenuContextValue {
+ open: boolean;
+ floatingContext: FloatingContext;
+ refs: ExtendedRefs<ReferenceType>;
+ floatingStyles: CSSProperties;
+ placement: Placement;
+ getReferenceProps: UseInteractionsReturn['getReferenceProps'];
+ getFloatingProps: UseInteractionsReturn['getFloatingProps'];
+ getItemProps: UseInteractionsReturn['getItemProps'];
+ activeIndex: number | null;
+ setActiveIndex: React.Dispatch<React.SetStateAction<number | null>>;
+ elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
+ labelsRef: React.MutableRefObject<Array<string | null>>;
+ arrowRef: React.MutableRefObject<SVGSVGElement | null>;
+ popupRef: React.RefObject<HTMLDivElement | null>;
+ isNested: boolean;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+ parentContext: MenuContextValue | null;
+}
+
+export const MenuContext = createContext<MenuContextValue | null>(null);
+
+export function useMenuContext() {
+ const ctx = useContext(MenuContext);
+ if (!ctx) {
+ throw new Error('Menu compound components must be used within <Menu>');
+ }
+ return ctx;
+}

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

@@ -0,0 +1,52 @@
+'use client';
+
+import { useFloatingTree, useListItem } from '@floating-ui/react';
+import React from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useMenuContext } from './menu-context';
+
+export interface MenuItemProps extends ComponentProps<'button'> {
+ label: string;
+ disabled?: boolean;
+ closeOnClick?: boolean;
+}
+
+export function MenuItem(props: MenuItemProps) {
+ const { render, label, disabled, closeOnClick = true, ...otherProps } = props;
+ const { activeIndex, getItemProps } = useMenuContext();
+ const tree = useFloatingTree();
+ const item = useListItem({ label: disabled ? null : label });
+ const isActive = item.index === activeIndex;
+
+ const state = {
+ active: isActive,
+ disabled: !!disabled,
+ };
+
+ const defaultProps = {
+ 'data-cl-slot': 'menu-item',
+ type: 'button' as const,
+ ref: item.ref,
+ role: 'menuitem' as const,
+ tabIndex: isActive ? 0 : -1,
+ ...(disabled && { 'aria-disabled': true as const }),
+ ...(getItemProps({
+ onClick() {
+ if (!disabled && closeOnClick) {
+ tree?.events.emit('click');
+ }
+ },
+ }) as React.ComponentPropsWithRef<'button'>),
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ state,
+ stateAttributesMapping: {
+ active: (v: boolean) => (v ? { 'data-cl-active': '' } : null),
+ disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+ },
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

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

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useMenuContext } from './menu-context';
+
+export interface MenuPopupProps extends ComponentProps<'div'> {}
+
+export function MenuPopup(props: MenuPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = useMenuContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'menu-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

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

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { useMenuContext } from './menu-context';
+
+export interface MenuPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function MenuPortal(props: MenuPortalProps) {
+ const { mounted } = useMenuContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/package.json

@@ -25,6 +25,10 @@
  "import": "./dist/primitives/select/index.js",
  "types": "./dist/primitives/select/index.d.ts"
  },
+ "./menu": {
+ "import": "./dist/primitives/menu/index.js",
+ "types": "./dist/primitives/menu/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/menu/README.md

@@ -0,0 +1,157 @@
+# Menu
+
+A dropdown menu with keyboard navigation, typeahead, and nested submenu support. Handles ARIA roles, safe hover zones for submenus, and tree-level close-on-click.
+
+## When to Use
+
+- Action menus, context menus, dropdown menus attached to a button trigger.
+- When you need nested submenus with safe pointer zones between trigger and submenu.
+- Prefer Menu over Popover when the content is a list of actions/commands rather than arbitrary content.
+
+## Usage
+
+```tsx
+import { Menu } from '@/primitives/menu';
+
+<Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item
+ label='Edit'
+ onClick={() => handleEdit()}
+ />
+ <Menu.Item
+ label='Duplicate'
+ onClick={() => handleDuplicate()}
+ />
+ <Menu.Separator />
+ <Menu.Item
+ label='Delete'
+ onClick={() => handleDelete()}
+ />
+ </Menu.Popup>
+ </Menu.Positioner>
+</Menu.Root>;
+```
+
+### Nested Submenus
+
+Nest a `<Menu.Root>` inside a parent `<Menu.Root>` — the nested trigger automatically renders as a `menuitem` and opens on hover with a safe polygon zone.
+
+```tsx
+<Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Edit' />
+ <Menu.Root>
+ <Menu.Trigger>Share</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Copy Link' />
+ <Menu.Item label='Email' />
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Menu.Popup>
+ </Menu.Positioner>
+</Menu.Root>
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Menu.Root
+ open={open}
+ onOpenChange={setOpen}
+>
+ {/* ... */}
+</Menu.Root>;
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| ----------------- | --------------- | -------------------------------------- |
+| `Menu.Root` | — | Root context provider |
+| `Menu.Trigger` | `<button>` | Opens/closes the menu |
+| `Menu.Portal` | — | Portals children (accepts `root` prop) |
+| `Menu.Positioner` | `<div>` | Floating positioned container |
+| `Menu.Popup` | `<div>` | Visual wrapper for menu items |
+| `Menu.Item` | `<button>` | A menu action item |
+| `Menu.Separator` | `<div>` | Visual divider between items |
+| `Menu.Arrow` | `<svg>` | Optional floating arrow |
+
+## Props
+
+### `Menu.Root`
+
+| Prop | Type | Default | Description |
+| -------------- | ------------------------- | ------------------------------------------------- | ---------------------------------- |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `placement` | `Placement` | `"bottom-start"` (root), `"right-start"` (nested) | Floating UI placement |
+| `sideOffset` | `number` | `4` (root), `0` (nested) | Gap between trigger and popup (px) |
+
+### `Menu.Item`
+
+| Prop | Type | Default | Description |
+| -------------- | --------- | ------------ | ------------------------------------------------------ |
+| `label` | `string` | **required** | Item text, also used for typeahead matching |
+| `disabled` | `boolean` | — | Prevents click handler, keeps item focusable |
+| `closeOnClick` | `boolean` | `true` | Whether clicking this item closes the entire menu tree |
+
+### `Menu.Trigger`, `Menu.Positioner`, `Menu.Popup`, `Menu.Separator`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Menu.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard Navigation
+
+| Key | Action |
+| ----------------- | -------------------------------------- |
+| `ArrowDown` | Move to next item |
+| `ArrowUp` | Move to previous item |
+| `ArrowRight` | Open nested submenu |
+| `ArrowLeft` | Close nested submenu, return to parent |
+| `Enter` / `Space` | Activate the focused item |
+| `Escape` | Close the current menu level |
+| Type a character | Jump to matching item (typeahead) |
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ----------------- | ------------------------------------ |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"menu-item"`) |
+| `data-cl-open` / `data-cl-closed` | Trigger | Menu open state |
+| `data-cl-active` | Item | Keyboard-focused item |
+| `data-cl-disabled` | Item | Disabled item |
+| `data-cl-side` | Positioner, Arrow | Resolved placement side |
+
+## Nested Menu Behavior
+
+- Nested menus open on hover (75ms delay) with a `safePolygon` safe zone.
+- Only one sibling submenu can be open at a time.
+- Clicking any item with `closeOnClick={true}` (default) closes the entire menu tree via a tree event.
+- `Escape` closes the innermost menu first, bubbling up through the tree.
+
+## Important Notes
+
+- **No built-in animations.** The positioner simply mounts/unmounts. Use `data-cl-open`/`data-cl-closed` for CSS-driven transitions.
+- **Disabled items use `aria-disabled`, not `disabled`.** They remain focusable for keyboard users.
+- **`label` is required on `Menu.Item`** — it drives typeahead matching. Disabled items are excluded from typeahead.
+
+## ARIA
+
+- Popup: `role="menu"`
+- Item: `role="menuitem"`, `aria-disabled`
+- Separator: `role="separator"`
+- Trigger: `aria-expanded`, `aria-haspopup="menu"`, `aria-controls`
+- Nested trigger: `role="menuitem"` (instead of button)

packages/headless/src/primitives/menu/index.ts

@@ -0,0 +1,12 @@
+export * as Menu from './parts';
+
+export type {
+ MenuArrowProps,
+ MenuItemProps,
+ MenuPopupProps,
+ MenuPortalProps,
+ MenuPositionerProps,
+ MenuProps,
+ MenuSeparatorProps,
+ MenuTriggerProps,
+} from './parts';

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

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { useMenuContext } from './menu-context';
+
+export interface MenuArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function MenuArrow(props: MenuArrowProps) {
+ const { floatingContext, arrowRef, placement } = useMenuContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='menu-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/menu/menu-context.ts

@@ -0,0 +1,40 @@
+import type {
+ ExtendedRefs,
+ FloatingContext,
+ Placement,
+ ReferenceType,
+ UseInteractionsReturn,
+} from '@floating-ui/react';
+import { type CSSProperties, createContext, useContext } from 'react';
+import type { TransitionProps } from '../../hooks/use-transition';
+
+export interface MenuContextValue {
+ open: boolean;
+ floatingContext: FloatingContext;
+ refs: ExtendedRefs<ReferenceType>;
+ floatingStyles: CSSProperties;
+ placement: Placement;
+ getReferenceProps: UseInteractionsReturn['getReferenceProps'];
+ getFloatingProps: UseInteractionsReturn['getFloatingProps'];
+ getItemProps: UseInteractionsReturn['getItemProps'];
+ activeIndex: number | null;
+ setActiveIndex: React.Dispatch<React.SetStateAction<number | null>>;
+ elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
+ labelsRef: React.MutableRefObject<Array<string | null>>;
+ arrowRef: React.MutableRefObject<SVGSVGElement | null>;
+ popupRef: React.RefObject<HTMLDivElement | null>;
+ isNested: boolean;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+ parentContext: MenuContextValue | null;
+}
+
+export const MenuContext = createContext<MenuContextValue | null>(null);
+
+export function useMenuContext() {
+ const ctx = useContext(MenuContext);
+ if (!ctx) {
+ throw new Error('Menu compound components must be used within <Menu>');
+ }
+ return ctx;
+}

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

@@ -0,0 +1,52 @@
+'use client';
+
+import { useFloatingTree, useListItem } from '@floating-ui/react';
+import React from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useMenuContext } from './menu-context';
+
+export interface MenuItemProps extends ComponentProps<'button'> {
+ label: string;
+ disabled?: boolean;
+ closeOnClick?: boolean;
+}
+
+export function MenuItem(props: MenuItemProps) {
+ const { render, label, disabled, closeOnClick = true, ...otherProps } = props;
+ const { activeIndex, getItemProps } = useMenuContext();
+ const tree = useFloatingTree();
+ const item = useListItem({ label: disabled ? null : label });
+ const isActive = item.index === activeIndex;
+
+ const state = {
+ active: isActive,
+ disabled: !!disabled,
+ };
+
+ const defaultProps = {
+ 'data-cl-slot': 'menu-item',
+ type: 'button' as const,
+ ref: item.ref,
+ role: 'menuitem' as const,
+ tabIndex: isActive ? 0 : -1,
+ ...(disabled && { 'aria-disabled': true as const }),
+ ...(getItemProps({
+ onClick() {
+ if (!disabled && closeOnClick) {
+ tree?.events.emit('click');
+ }
+ },
+ }) as React.ComponentPropsWithRef<'button'>),
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ state,
+ stateAttributesMapping: {
+ active: (v: boolean) => (v ? { 'data-cl-active': '' } : null),
+ disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+ },
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

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

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useMenuContext } from './menu-context';
+
+export interface MenuPopupProps extends ComponentProps<'div'> {}
+
+export function MenuPopup(props: MenuPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = useMenuContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'menu-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

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

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { useMenuContext } from './menu-context';
+
+export interface MenuPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function MenuPortal(props: MenuPortalProps) {
+ const { mounted } = useMenuContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/package.json

@@ -25,6 +25,10 @@
  "import": "./dist/primitives/select/index.js",
  "types": "./dist/primitives/select/index.d.ts"
  },
+ "./menu": {
+ "import": "./dist/primitives/menu/index.js",
+ "types": "./dist/primitives/menu/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/menu/README.md

@@ -0,0 +1,157 @@
+# Menu
+
+A dropdown menu with keyboard navigation, typeahead, and nested submenu support. Handles ARIA roles, safe hover zones for submenus, and tree-level close-on-click.
+
+## When to Use
+
+- Action menus, context menus, dropdown menus attached to a button trigger.
+- When you need nested submenus with safe pointer zones between trigger and submenu.
+- Prefer Menu over Popover when the content is a list of actions/commands rather than arbitrary content.
+
+## Usage
+
+```tsx
+import { Menu } from '@/primitives/menu';
+
+<Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item
+ label='Edit'
+ onClick={() => handleEdit()}
+ />
+ <Menu.Item
+ label='Duplicate'
+ onClick={() => handleDuplicate()}
+ />
+ <Menu.Separator />
+ <Menu.Item
+ label='Delete'
+ onClick={() => handleDelete()}
+ />
+ </Menu.Popup>
+ </Menu.Positioner>
+</Menu.Root>;
+```
+
+### Nested Submenus
+
+Nest a `<Menu.Root>` inside a parent `<Menu.Root>` — the nested trigger automatically renders as a `menuitem` and opens on hover with a safe polygon zone.
+
+```tsx
+<Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Edit' />
+ <Menu.Root>
+ <Menu.Trigger>Share</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Copy Link' />
+ <Menu.Item label='Email' />
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Menu.Popup>
+ </Menu.Positioner>
+</Menu.Root>
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Menu.Root
+ open={open}
+ onOpenChange={setOpen}
+>
+ {/* ... */}
+</Menu.Root>;
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| ----------------- | --------------- | -------------------------------------- |
+| `Menu.Root` | — | Root context provider |
+| `Menu.Trigger` | `<button>` | Opens/closes the menu |
+| `Menu.Portal` | — | Portals children (accepts `root` prop) |
+| `Menu.Positioner` | `<div>` | Floating positioned container |
+| `Menu.Popup` | `<div>` | Visual wrapper for menu items |
+| `Menu.Item` | `<button>` | A menu action item |
+| `Menu.Separator` | `<div>` | Visual divider between items |
+| `Menu.Arrow` | `<svg>` | Optional floating arrow |
+
+## Props
+
+### `Menu.Root`
+
+| Prop | Type | Default | Description |
+| -------------- | ------------------------- | ------------------------------------------------- | ---------------------------------- |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `placement` | `Placement` | `"bottom-start"` (root), `"right-start"` (nested) | Floating UI placement |
+| `sideOffset` | `number` | `4` (root), `0` (nested) | Gap between trigger and popup (px) |
+
+### `Menu.Item`
+
+| Prop | Type | Default | Description |
+| -------------- | --------- | ------------ | ------------------------------------------------------ |
+| `label` | `string` | **required** | Item text, also used for typeahead matching |
+| `disabled` | `boolean` | — | Prevents click handler, keeps item focusable |
+| `closeOnClick` | `boolean` | `true` | Whether clicking this item closes the entire menu tree |
+
+### `Menu.Trigger`, `Menu.Positioner`, `Menu.Popup`, `Menu.Separator`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Menu.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard Navigation
+
+| Key | Action |
+| ----------------- | -------------------------------------- |
+| `ArrowDown` | Move to next item |
+| `ArrowUp` | Move to previous item |
+| `ArrowRight` | Open nested submenu |
+| `ArrowLeft` | Close nested submenu, return to parent |
+| `Enter` / `Space` | Activate the focused item |
+| `Escape` | Close the current menu level |
+| Type a character | Jump to matching item (typeahead) |
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ----------------- | ------------------------------------ |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"menu-item"`) |
+| `data-cl-open` / `data-cl-closed` | Trigger | Menu open state |
+| `data-cl-active` | Item | Keyboard-focused item |
+| `data-cl-disabled` | Item | Disabled item |
+| `data-cl-side` | Positioner, Arrow | Resolved placement side |
+
+## Nested Menu Behavior
+
+- Nested menus open on hover (75ms delay) with a `safePolygon` safe zone.
+- Only one sibling submenu can be open at a time.
+- Clicking any item with `closeOnClick={true}` (default) closes the entire menu tree via a tree event.
+- `Escape` closes the innermost menu first, bubbling up through the tree.
+
+## Important Notes
+
+- **No built-in animations.** The positioner simply mounts/unmounts. Use `data-cl-open`/`data-cl-closed` for CSS-driven transitions.
+- **Disabled items use `aria-disabled`, not `disabled`.** They remain focusable for keyboard users.
+- **`label` is required on `Menu.Item`** — it drives typeahead matching. Disabled items are excluded from typeahead.
+
+## ARIA
+
+- Popup: `role="menu"`
+- Item: `role="menuitem"`, `aria-disabled`
+- Separator: `role="separator"`
+- Trigger: `aria-expanded`, `aria-haspopup="menu"`, `aria-controls`
+- Nested trigger: `role="menuitem"` (instead of button)

packages/headless/src/primitives/menu/index.ts

@@ -0,0 +1,12 @@
+export * as Menu from './parts';
+
+export type {
+ MenuArrowProps,
+ MenuItemProps,
+ MenuPopupProps,
+ MenuPortalProps,
+ MenuPositionerProps,
+ MenuProps,
+ MenuSeparatorProps,
+ MenuTriggerProps,
+} from './parts';

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

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { useMenuContext } from './menu-context';
+
+export interface MenuArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function MenuArrow(props: MenuArrowProps) {
+ const { floatingContext, arrowRef, placement } = useMenuContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='menu-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/menu/menu-context.ts

@@ -0,0 +1,40 @@
+import type {
+ ExtendedRefs,
+ FloatingContext,
+ Placement,
+ ReferenceType,
+ UseInteractionsReturn,
+} from '@floating-ui/react';
+import { type CSSProperties, createContext, useContext } from 'react';
+import type { TransitionProps } from '../../hooks/use-transition';
+
+export interface MenuContextValue {
+ open: boolean;
+ floatingContext: FloatingContext;
+ refs: ExtendedRefs<ReferenceType>;
+ floatingStyles: CSSProperties;
+ placement: Placement;
+ getReferenceProps: UseInteractionsReturn['getReferenceProps'];
+ getFloatingProps: UseInteractionsReturn['getFloatingProps'];
+ getItemProps: UseInteractionsReturn['getItemProps'];
+ activeIndex: number | null;
+ setActiveIndex: React.Dispatch<React.SetStateAction<number | null>>;
+ elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
+ labelsRef: React.MutableRefObject<Array<string | null>>;
+ arrowRef: React.MutableRefObject<SVGSVGElement | null>;
+ popupRef: React.RefObject<HTMLDivElement | null>;
+ isNested: boolean;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+ parentContext: MenuContextValue | null;
+}
+
+export const MenuContext = createContext<MenuContextValue | null>(null);
+
+export function useMenuContext() {
+ const ctx = useContext(MenuContext);
+ if (!ctx) {
+ throw new Error('Menu compound components must be used within <Menu>');
+ }
+ return ctx;
+}

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

@@ -0,0 +1,52 @@
+'use client';
+
+import { useFloatingTree, useListItem } from '@floating-ui/react';
+import React from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useMenuContext } from './menu-context';
+
+export interface MenuItemProps extends ComponentProps<'button'> {
+ label: string;
+ disabled?: boolean;
+ closeOnClick?: boolean;
+}
+
+export function MenuItem(props: MenuItemProps) {
+ const { render, label, disabled, closeOnClick = true, ...otherProps } = props;
+ const { activeIndex, getItemProps } = useMenuContext();
+ const tree = useFloatingTree();
+ const item = useListItem({ label: disabled ? null : label });
+ const isActive = item.index === activeIndex;
+
+ const state = {
+ active: isActive,
+ disabled: !!disabled,
+ };
+
+ const defaultProps = {
+ 'data-cl-slot': 'menu-item',
+ type: 'button' as const,
+ ref: item.ref,
+ role: 'menuitem' as const,
+ tabIndex: isActive ? 0 : -1,
+ ...(disabled && { 'aria-disabled': true as const }),
+ ...(getItemProps({
+ onClick() {
+ if (!disabled && closeOnClick) {
+ tree?.events.emit('click');
+ }
+ },
+ }) as React.ComponentPropsWithRef<'button'>),
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ state,
+ stateAttributesMapping: {
+ active: (v: boolean) => (v ? { 'data-cl-active': '' } : null),
+ disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+ },
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

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

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useMenuContext } from './menu-context';
+
+export interface MenuPopupProps extends ComponentProps<'div'> {}
+
+export function MenuPopup(props: MenuPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = useMenuContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'menu-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

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

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { useMenuContext } from './menu-context';
+
+export interface MenuPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function MenuPortal(props: MenuPortalProps) {
+ const { mounted } = useMenuContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/package.json

@@ -25,6 +25,10 @@
  "import": "./dist/primitives/select/index.js",
  "types": "./dist/primitives/select/index.d.ts"
  },
+ "./menu": {
+ "import": "./dist/primitives/menu/index.js",
+ "types": "./dist/primitives/menu/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/menu/README.md

@@ -0,0 +1,157 @@
+# Menu
+
+A dropdown menu with keyboard navigation, typeahead, and nested submenu support. Handles ARIA roles, safe hover zones for submenus, and tree-level close-on-click.
+
+## When to Use
+
+- Action menus, context menus, dropdown menus attached to a button trigger.
+- When you need nested submenus with safe pointer zones between trigger and submenu.
+- Prefer Menu over Popover when the content is a list of actions/commands rather than arbitrary content.
+
+## Usage
+
+```tsx
+import { Menu } from '@/primitives/menu';
+
+<Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item
+ label='Edit'
+ onClick={() => handleEdit()}
+ />
+ <Menu.Item
+ label='Duplicate'
+ onClick={() => handleDuplicate()}
+ />
+ <Menu.Separator />
+ <Menu.Item
+ label='Delete'
+ onClick={() => handleDelete()}
+ />
+ </Menu.Popup>
+ </Menu.Positioner>
+</Menu.Root>;
+```
+
+### Nested Submenus
+
+Nest a `<Menu.Root>` inside a parent `<Menu.Root>` — the nested trigger automatically renders as a `menuitem` and opens on hover with a safe polygon zone.
+
+```tsx
+<Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Edit' />
+ <Menu.Root>
+ <Menu.Trigger>Share</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Copy Link' />
+ <Menu.Item label='Email' />
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Menu.Popup>
+ </Menu.Positioner>
+</Menu.Root>
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Menu.Root
+ open={open}
+ onOpenChange={setOpen}
+>
+ {/* ... */}
+</Menu.Root>;
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| ----------------- | --------------- | -------------------------------------- |
+| `Menu.Root` | — | Root context provider |
+| `Menu.Trigger` | `<button>` | Opens/closes the menu |
+| `Menu.Portal` | — | Portals children (accepts `root` prop) |
+| `Menu.Positioner` | `<div>` | Floating positioned container |
+| `Menu.Popup` | `<div>` | Visual wrapper for menu items |
+| `Menu.Item` | `<button>` | A menu action item |
+| `Menu.Separator` | `<div>` | Visual divider between items |
+| `Menu.Arrow` | `<svg>` | Optional floating arrow |
+
+## Props
+
+### `Menu.Root`
+
+| Prop | Type | Default | Description |
+| -------------- | ------------------------- | ------------------------------------------------- | ---------------------------------- |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `placement` | `Placement` | `"bottom-start"` (root), `"right-start"` (nested) | Floating UI placement |
+| `sideOffset` | `number` | `4` (root), `0` (nested) | Gap between trigger and popup (px) |
+
+### `Menu.Item`
+
+| Prop | Type | Default | Description |
+| -------------- | --------- | ------------ | ------------------------------------------------------ |
+| `label` | `string` | **required** | Item text, also used for typeahead matching |
+| `disabled` | `boolean` | — | Prevents click handler, keeps item focusable |
+| `closeOnClick` | `boolean` | `true` | Whether clicking this item closes the entire menu tree |
+
+### `Menu.Trigger`, `Menu.Positioner`, `Menu.Popup`, `Menu.Separator`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Menu.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard Navigation
+
+| Key | Action |
+| ----------------- | -------------------------------------- |
+| `ArrowDown` | Move to next item |
+| `ArrowUp` | Move to previous item |
+| `ArrowRight` | Open nested submenu |
+| `ArrowLeft` | Close nested submenu, return to parent |
+| `Enter` / `Space` | Activate the focused item |
+| `Escape` | Close the current menu level |
+| Type a character | Jump to matching item (typeahead) |
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ----------------- | ------------------------------------ |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"menu-item"`) |
+| `data-cl-open` / `data-cl-closed` | Trigger | Menu open state |
+| `data-cl-active` | Item | Keyboard-focused item |
+| `data-cl-disabled` | Item | Disabled item |
+| `data-cl-side` | Positioner, Arrow | Resolved placement side |
+
+## Nested Menu Behavior
+
+- Nested menus open on hover (75ms delay) with a `safePolygon` safe zone.
+- Only one sibling submenu can be open at a time.
+- Clicking any item with `closeOnClick={true}` (default) closes the entire menu tree via a tree event.
+- `Escape` closes the innermost menu first, bubbling up through the tree.
+
+## Important Notes
+
+- **No built-in animations.** The positioner simply mounts/unmounts. Use `data-cl-open`/`data-cl-closed` for CSS-driven transitions.
+- **Disabled items use `aria-disabled`, not `disabled`.** They remain focusable for keyboard users.
+- **`label` is required on `Menu.Item`** — it drives typeahead matching. Disabled items are excluded from typeahead.
+
+## ARIA
+
+- Popup: `role="menu"`
+- Item: `role="menuitem"`, `aria-disabled`
+- Separator: `role="separator"`
+- Trigger: `aria-expanded`, `aria-haspopup="menu"`, `aria-controls`
+- Nested trigger: `role="menuitem"` (instead of button)

packages/headless/src/primitives/menu/index.ts

@@ -0,0 +1,12 @@
+export * as Menu from './parts';
+
+export type {
+ MenuArrowProps,
+ MenuItemProps,
+ MenuPopupProps,
+ MenuPortalProps,
+ MenuPositionerProps,
+ MenuProps,
+ MenuSeparatorProps,
+ MenuTriggerProps,
+} from './parts';

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

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { useMenuContext } from './menu-context';
+
+export interface MenuArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function MenuArrow(props: MenuArrowProps) {
+ const { floatingContext, arrowRef, placement } = useMenuContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='menu-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/menu/menu-context.ts

@@ -0,0 +1,40 @@
+import type {
+ ExtendedRefs,
+ FloatingContext,
+ Placement,
+ ReferenceType,
+ UseInteractionsReturn,
+} from '@floating-ui/react';
+import { type CSSProperties, createContext, useContext } from 'react';
+import type { TransitionProps } from '../../hooks/use-transition';
+
+export interface MenuContextValue {
+ open: boolean;
+ floatingContext: FloatingContext;
+ refs: ExtendedRefs<ReferenceType>;
+ floatingStyles: CSSProperties;
+ placement: Placement;
+ getReferenceProps: UseInteractionsReturn['getReferenceProps'];
+ getFloatingProps: UseInteractionsReturn['getFloatingProps'];
+ getItemProps: UseInteractionsReturn['getItemProps'];
+ activeIndex: number | null;
+ setActiveIndex: React.Dispatch<React.SetStateAction<number | null>>;
+ elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
+ labelsRef: React.MutableRefObject<Array<string | null>>;
+ arrowRef: React.MutableRefObject<SVGSVGElement | null>;
+ popupRef: React.RefObject<HTMLDivElement | null>;
+ isNested: boolean;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+ parentContext: MenuContextValue | null;
+}
+
+export const MenuContext = createContext<MenuContextValue | null>(null);
+
+export function useMenuContext() {
+ const ctx = useContext(MenuContext);
+ if (!ctx) {
+ throw new Error('Menu compound components must be used within <Menu>');
+ }
+ return ctx;
+}

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

@@ -0,0 +1,52 @@
+'use client';
+
+import { useFloatingTree, useListItem } from '@floating-ui/react';
+import React from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useMenuContext } from './menu-context';
+
+export interface MenuItemProps extends ComponentProps<'button'> {
+ label: string;
+ disabled?: boolean;
+ closeOnClick?: boolean;
+}
+
+export function MenuItem(props: MenuItemProps) {
+ const { render, label, disabled, closeOnClick = true, ...otherProps } = props;
+ const { activeIndex, getItemProps } = useMenuContext();
+ const tree = useFloatingTree();
+ const item = useListItem({ label: disabled ? null : label });
+ const isActive = item.index === activeIndex;
+
+ const state = {
+ active: isActive,
+ disabled: !!disabled,
+ };
+
+ const defaultProps = {
+ 'data-cl-slot': 'menu-item',
+ type: 'button' as const,
+ ref: item.ref,
+ role: 'menuitem' as const,
+ tabIndex: isActive ? 0 : -1,
+ ...(disabled && { 'aria-disabled': true as const }),
+ ...(getItemProps({
+ onClick() {
+ if (!disabled && closeOnClick) {
+ tree?.events.emit('click');
+ }
+ },
+ }) as React.ComponentPropsWithRef<'button'>),
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ state,
+ stateAttributesMapping: {
+ active: (v: boolean) => (v ? { 'data-cl-active': '' } : null),
+ disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+ },
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

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

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useMenuContext } from './menu-context';
+
+export interface MenuPopupProps extends ComponentProps<'div'> {}
+
+export function MenuPopup(props: MenuPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = useMenuContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'menu-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

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

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { useMenuContext } from './menu-context';
+
+export interface MenuPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function MenuPortal(props: MenuPortalProps) {
+ const { mounted } = useMenuContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/package.json

@@ -25,6 +25,10 @@
  "import": "./dist/primitives/select/index.js",
  "types": "./dist/primitives/select/index.d.ts"
  },
+ "./menu": {
+ "import": "./dist/primitives/menu/index.js",
+ "types": "./dist/primitives/menu/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/menu/README.md

@@ -0,0 +1,157 @@
+# Menu
+
+A dropdown menu with keyboard navigation, typeahead, and nested submenu support. Handles ARIA roles, safe hover zones for submenus, and tree-level close-on-click.
+
+## When to Use
+
+- Action menus, context menus, dropdown menus attached to a button trigger.
+- When you need nested submenus with safe pointer zones between trigger and submenu.
+- Prefer Menu over Popover when the content is a list of actions/commands rather than arbitrary content.
+
+## Usage
+
+```tsx
+import { Menu } from '@/primitives/menu';
+
+<Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item
+ label='Edit'
+ onClick={() => handleEdit()}
+ />
+ <Menu.Item
+ label='Duplicate'
+ onClick={() => handleDuplicate()}
+ />
+ <Menu.Separator />
+ <Menu.Item
+ label='Delete'
+ onClick={() => handleDelete()}
+ />
+ </Menu.Popup>
+ </Menu.Positioner>
+</Menu.Root>;
+```
+
+### Nested Submenus
+
+Nest a `<Menu.Root>` inside a parent `<Menu.Root>` — the nested trigger automatically renders as a `menuitem` and opens on hover with a safe polygon zone.
+
+```tsx
+<Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Edit' />
+ <Menu.Root>
+ <Menu.Trigger>Share</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Copy Link' />
+ <Menu.Item label='Email' />
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Menu.Popup>
+ </Menu.Positioner>
+</Menu.Root>
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Menu.Root
+ open={open}
+ onOpenChange={setOpen}
+>
+ {/* ... */}
+</Menu.Root>;
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| ----------------- | --------------- | -------------------------------------- |
+| `Menu.Root` | — | Root context provider |
+| `Menu.Trigger` | `<button>` | Opens/closes the menu |
+| `Menu.Portal` | — | Portals children (accepts `root` prop) |
+| `Menu.Positioner` | `<div>` | Floating positioned container |
+| `Menu.Popup` | `<div>` | Visual wrapper for menu items |
+| `Menu.Item` | `<button>` | A menu action item |
+| `Menu.Separator` | `<div>` | Visual divider between items |
+| `Menu.Arrow` | `<svg>` | Optional floating arrow |
+
+## Props
+
+### `Menu.Root`
+
+| Prop | Type | Default | Description |
+| -------------- | ------------------------- | ------------------------------------------------- | ---------------------------------- |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `placement` | `Placement` | `"bottom-start"` (root), `"right-start"` (nested) | Floating UI placement |
+| `sideOffset` | `number` | `4` (root), `0` (nested) | Gap between trigger and popup (px) |
+
+### `Menu.Item`
+
+| Prop | Type | Default | Description |
+| -------------- | --------- | ------------ | ------------------------------------------------------ |
+| `label` | `string` | **required** | Item text, also used for typeahead matching |
+| `disabled` | `boolean` | — | Prevents click handler, keeps item focusable |
+| `closeOnClick` | `boolean` | `true` | Whether clicking this item closes the entire menu tree |
+
+### `Menu.Trigger`, `Menu.Positioner`, `Menu.Popup`, `Menu.Separator`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Menu.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard Navigation
+
+| Key | Action |
+| ----------------- | -------------------------------------- |
+| `ArrowDown` | Move to next item |
+| `ArrowUp` | Move to previous item |
+| `ArrowRight` | Open nested submenu |
+| `ArrowLeft` | Close nested submenu, return to parent |
+| `Enter` / `Space` | Activate the focused item |
+| `Escape` | Close the current menu level |
+| Type a character | Jump to matching item (typeahead) |
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ----------------- | ------------------------------------ |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"menu-item"`) |
+| `data-cl-open` / `data-cl-closed` | Trigger | Menu open state |
+| `data-cl-active` | Item | Keyboard-focused item |
+| `data-cl-disabled` | Item | Disabled item |
+| `data-cl-side` | Positioner, Arrow | Resolved placement side |
+
+## Nested Menu Behavior
+
+- Nested menus open on hover (75ms delay) with a `safePolygon` safe zone.
+- Only one sibling submenu can be open at a time.
+- Clicking any item with `closeOnClick={true}` (default) closes the entire menu tree via a tree event.
+- `Escape` closes the innermost menu first, bubbling up through the tree.
+
+## Important Notes
+
+- **No built-in animations.** The positioner simply mounts/unmounts. Use `data-cl-open`/`data-cl-closed` for CSS-driven transitions.
+- **Disabled items use `aria-disabled`, not `disabled`.** They remain focusable for keyboard users.
+- **`label` is required on `Menu.Item`** — it drives typeahead matching. Disabled items are excluded from typeahead.
+
+## ARIA
+
+- Popup: `role="menu"`
+- Item: `role="menuitem"`, `aria-disabled`
+- Separator: `role="separator"`
+- Trigger: `aria-expanded`, `aria-haspopup="menu"`, `aria-controls`
+- Nested trigger: `role="menuitem"` (instead of button)

packages/headless/src/primitives/menu/index.ts

@@ -0,0 +1,12 @@
+export * as Menu from './parts';
+
+export type {
+ MenuArrowProps,
+ MenuItemProps,
+ MenuPopupProps,
+ MenuPortalProps,
+ MenuPositionerProps,
+ MenuProps,
+ MenuSeparatorProps,
+ MenuTriggerProps,
+} from './parts';

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

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { useMenuContext } from './menu-context';
+
+export interface MenuArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function MenuArrow(props: MenuArrowProps) {
+ const { floatingContext, arrowRef, placement } = useMenuContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='menu-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/menu/menu-context.ts

@@ -0,0 +1,40 @@
+import type {
+ ExtendedRefs,
+ FloatingContext,
+ Placement,
+ ReferenceType,
+ UseInteractionsReturn,
+} from '@floating-ui/react';
+import { type CSSProperties, createContext, useContext } from 'react';
+import type { TransitionProps } from '../../hooks/use-transition';
+
+export interface MenuContextValue {
+ open: boolean;
+ floatingContext: FloatingContext;
+ refs: ExtendedRefs<ReferenceType>;
+ floatingStyles: CSSProperties;
+ placement: Placement;
+ getReferenceProps: UseInteractionsReturn['getReferenceProps'];
+ getFloatingProps: UseInteractionsReturn['getFloatingProps'];
+ getItemProps: UseInteractionsReturn['getItemProps'];
+ activeIndex: number | null;
+ setActiveIndex: React.Dispatch<React.SetStateAction<number | null>>;
+ elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
+ labelsRef: React.MutableRefObject<Array<string | null>>;
+ arrowRef: React.MutableRefObject<SVGSVGElement | null>;
+ popupRef: React.RefObject<HTMLDivElement | null>;
+ isNested: boolean;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+ parentContext: MenuContextValue | null;
+}
+
+export const MenuContext = createContext<MenuContextValue | null>(null);
+
+export function useMenuContext() {
+ const ctx = useContext(MenuContext);
+ if (!ctx) {
+ throw new Error('Menu compound components must be used within <Menu>');
+ }
+ return ctx;
+}

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

@@ -0,0 +1,52 @@
+'use client';
+
+import { useFloatingTree, useListItem } from '@floating-ui/react';
+import React from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useMenuContext } from './menu-context';
+
+export interface MenuItemProps extends ComponentProps<'button'> {
+ label: string;
+ disabled?: boolean;
+ closeOnClick?: boolean;
+}
+
+export function MenuItem(props: MenuItemProps) {
+ const { render, label, disabled, closeOnClick = true, ...otherProps } = props;
+ const { activeIndex, getItemProps } = useMenuContext();
+ const tree = useFloatingTree();
+ const item = useListItem({ label: disabled ? null : label });
+ const isActive = item.index === activeIndex;
+
+ const state = {
+ active: isActive,
+ disabled: !!disabled,
+ };
+
+ const defaultProps = {
+ 'data-cl-slot': 'menu-item',
+ type: 'button' as const,
+ ref: item.ref,
+ role: 'menuitem' as const,
+ tabIndex: isActive ? 0 : -1,
+ ...(disabled && { 'aria-disabled': true as const }),
+ ...(getItemProps({
+ onClick() {
+ if (!disabled && closeOnClick) {
+ tree?.events.emit('click');
+ }
+ },
+ }) as React.ComponentPropsWithRef<'button'>),
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ state,
+ stateAttributesMapping: {
+ active: (v: boolean) => (v ? { 'data-cl-active': '' } : null),
+ disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+ },
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

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

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useMenuContext } from './menu-context';
+
+export interface MenuPopupProps extends ComponentProps<'div'> {}
+
+export function MenuPopup(props: MenuPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = useMenuContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'menu-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

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

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { useMenuContext } from './menu-context';
+
+export interface MenuPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function MenuPortal(props: MenuPortalProps) {
+ const { mounted } = useMenuContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}

packages/headless/package.json

@@ -25,6 +25,10 @@
  "import": "./dist/primitives/select/index.js",
  "types": "./dist/primitives/select/index.d.ts"
  },
+ "./menu": {
+ "import": "./dist/primitives/menu/index.js",
+ "types": "./dist/primitives/menu/index.d.ts"
+ },
  "./dialog": {
  "import": "./dist/primitives/dialog/index.js",
  "types": "./dist/primitives/dialog/index.d.ts"

packages/headless/src/primitives/menu/README.md

@@ -0,0 +1,157 @@
+# Menu
+
+A dropdown menu with keyboard navigation, typeahead, and nested submenu support. Handles ARIA roles, safe hover zones for submenus, and tree-level close-on-click.
+
+## When to Use
+
+- Action menus, context menus, dropdown menus attached to a button trigger.
+- When you need nested submenus with safe pointer zones between trigger and submenu.
+- Prefer Menu over Popover when the content is a list of actions/commands rather than arbitrary content.
+
+## Usage
+
+```tsx
+import { Menu } from '@/primitives/menu';
+
+<Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item
+ label='Edit'
+ onClick={() => handleEdit()}
+ />
+ <Menu.Item
+ label='Duplicate'
+ onClick={() => handleDuplicate()}
+ />
+ <Menu.Separator />
+ <Menu.Item
+ label='Delete'
+ onClick={() => handleDelete()}
+ />
+ </Menu.Popup>
+ </Menu.Positioner>
+</Menu.Root>;
+```
+
+### Nested Submenus
+
+Nest a `<Menu.Root>` inside a parent `<Menu.Root>` — the nested trigger automatically renders as a `menuitem` and opens on hover with a safe polygon zone.
+
+```tsx
+<Menu.Root>
+ <Menu.Trigger>Actions</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Edit' />
+ <Menu.Root>
+ <Menu.Trigger>Share</Menu.Trigger>
+ <Menu.Positioner>
+ <Menu.Popup>
+ <Menu.Item label='Copy Link' />
+ <Menu.Item label='Email' />
+ </Menu.Popup>
+ </Menu.Positioner>
+ </Menu.Root>
+ </Menu.Popup>
+ </Menu.Positioner>
+</Menu.Root>
+```
+
+### Controlled
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<Menu.Root
+ open={open}
+ onOpenChange={setOpen}
+>
+ {/* ... */}
+</Menu.Root>;
+```
+
+## Parts
+
+| Part | Default Element | Description |
+| ----------------- | --------------- | -------------------------------------- |
+| `Menu.Root` | — | Root context provider |
+| `Menu.Trigger` | `<button>` | Opens/closes the menu |
+| `Menu.Portal` | — | Portals children (accepts `root` prop) |
+| `Menu.Positioner` | `<div>` | Floating positioned container |
+| `Menu.Popup` | `<div>` | Visual wrapper for menu items |
+| `Menu.Item` | `<button>` | A menu action item |
+| `Menu.Separator` | `<div>` | Visual divider between items |
+| `Menu.Arrow` | `<svg>` | Optional floating arrow |
+
+## Props
+
+### `Menu.Root`
+
+| Prop | Type | Default | Description |
+| -------------- | ------------------------- | ------------------------------------------------- | ---------------------------------- |
+| `open` | `boolean` | — | Controlled open state |
+| `defaultOpen` | `boolean` | `false` | Initial open state (uncontrolled) |
+| `onOpenChange` | `(open: boolean) => void` | — | Called when open state changes |
+| `placement` | `Placement` | `"bottom-start"` (root), `"right-start"` (nested) | Floating UI placement |
+| `sideOffset` | `number` | `4` (root), `0` (nested) | Gap between trigger and popup (px) |
+
+### `Menu.Item`
+
+| Prop | Type | Default | Description |
+| -------------- | --------- | ------------ | ------------------------------------------------------ |
+| `label` | `string` | **required** | Item text, also used for typeahead matching |
+| `disabled` | `boolean` | — | Prevents click handler, keeps item focusable |
+| `closeOnClick` | `boolean` | `true` | Whether clicking this item closes the entire menu tree |
+
+### `Menu.Trigger`, `Menu.Positioner`, `Menu.Popup`, `Menu.Separator`
+
+No additional props beyond standard HTML attributes and the `render` prop.
+
+### `Menu.Arrow`
+
+Accepts all `FloatingArrow` props. `ref` and `context` are injected automatically.
+
+## Keyboard Navigation
+
+| Key | Action |
+| ----------------- | -------------------------------------- |
+| `ArrowDown` | Move to next item |
+| `ArrowUp` | Move to previous item |
+| `ArrowRight` | Open nested submenu |
+| `ArrowLeft` | Close nested submenu, return to parent |
+| `Enter` / `Space` | Activate the focused item |
+| `Escape` | Close the current menu level |
+| Type a character | Jump to matching item (typeahead) |
+
+## Data Attributes
+
+| Attribute | Applies To | Description |
+| --------------------------------- | ----------------- | ------------------------------------ |
+| `data-cl-slot` | All parts | Part identifier (e.g. `"menu-item"`) |
+| `data-cl-open` / `data-cl-closed` | Trigger | Menu open state |
+| `data-cl-active` | Item | Keyboard-focused item |
+| `data-cl-disabled` | Item | Disabled item |
+| `data-cl-side` | Positioner, Arrow | Resolved placement side |
+
+## Nested Menu Behavior
+
+- Nested menus open on hover (75ms delay) with a `safePolygon` safe zone.
+- Only one sibling submenu can be open at a time.
+- Clicking any item with `closeOnClick={true}` (default) closes the entire menu tree via a tree event.
+- `Escape` closes the innermost menu first, bubbling up through the tree.
+
+## Important Notes
+
+- **No built-in animations.** The positioner simply mounts/unmounts. Use `data-cl-open`/`data-cl-closed` for CSS-driven transitions.
+- **Disabled items use `aria-disabled`, not `disabled`.** They remain focusable for keyboard users.
+- **`label` is required on `Menu.Item`** — it drives typeahead matching. Disabled items are excluded from typeahead.
+
+## ARIA
+
+- Popup: `role="menu"`
+- Item: `role="menuitem"`, `aria-disabled`
+- Separator: `role="separator"`
+- Trigger: `aria-expanded`, `aria-haspopup="menu"`, `aria-controls`
+- Nested trigger: `role="menuitem"` (instead of button)

packages/headless/src/primitives/menu/index.ts

@@ -0,0 +1,12 @@
+export * as Menu from './parts';
+
+export type {
+ MenuArrowProps,
+ MenuItemProps,
+ MenuPopupProps,
+ MenuPortalProps,
+ MenuPositionerProps,
+ MenuProps,
+ MenuSeparatorProps,
+ MenuTriggerProps,
+} from './parts';

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

@@ -0,0 +1,22 @@
+'use client';
+
+import { FloatingArrow } from '@floating-ui/react';
+import React from 'react';
+import { useMenuContext } from './menu-context';
+
+export interface MenuArrowProps extends React.ComponentPropsWithRef<typeof FloatingArrow> {}
+
+export function MenuArrow(props: MenuArrowProps) {
+ const { floatingContext, arrowRef, placement } = useMenuContext();
+ const side = placement.split('-')[0];
+
+ return (
+ <FloatingArrow
+ data-cl-slot='menu-arrow'
+ data-cl-side={side}
+ {...props}
+ ref={arrowRef}
+ context={floatingContext}
+ />
+ );
+}

packages/headless/src/primitives/menu/menu-context.ts

@@ -0,0 +1,40 @@
+import type {
+ ExtendedRefs,
+ FloatingContext,
+ Placement,
+ ReferenceType,
+ UseInteractionsReturn,
+} from '@floating-ui/react';
+import { type CSSProperties, createContext, useContext } from 'react';
+import type { TransitionProps } from '../../hooks/use-transition';
+
+export interface MenuContextValue {
+ open: boolean;
+ floatingContext: FloatingContext;
+ refs: ExtendedRefs<ReferenceType>;
+ floatingStyles: CSSProperties;
+ placement: Placement;
+ getReferenceProps: UseInteractionsReturn['getReferenceProps'];
+ getFloatingProps: UseInteractionsReturn['getFloatingProps'];
+ getItemProps: UseInteractionsReturn['getItemProps'];
+ activeIndex: number | null;
+ setActiveIndex: React.Dispatch<React.SetStateAction<number | null>>;
+ elementsRef: React.MutableRefObject<Array<HTMLElement | null>>;
+ labelsRef: React.MutableRefObject<Array<string | null>>;
+ arrowRef: React.MutableRefObject<SVGSVGElement | null>;
+ popupRef: React.RefObject<HTMLDivElement | null>;
+ isNested: boolean;
+ mounted: boolean;
+ transitionProps: TransitionProps;
+ parentContext: MenuContextValue | null;
+}
+
+export const MenuContext = createContext<MenuContextValue | null>(null);
+
+export function useMenuContext() {
+ const ctx = useContext(MenuContext);
+ if (!ctx) {
+ throw new Error('Menu compound components must be used within <Menu>');
+ }
+ return ctx;
+}

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

@@ -0,0 +1,52 @@
+'use client';
+
+import { useFloatingTree, useListItem } from '@floating-ui/react';
+import React from 'react';
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useMenuContext } from './menu-context';
+
+export interface MenuItemProps extends ComponentProps<'button'> {
+ label: string;
+ disabled?: boolean;
+ closeOnClick?: boolean;
+}
+
+export function MenuItem(props: MenuItemProps) {
+ const { render, label, disabled, closeOnClick = true, ...otherProps } = props;
+ const { activeIndex, getItemProps } = useMenuContext();
+ const tree = useFloatingTree();
+ const item = useListItem({ label: disabled ? null : label });
+ const isActive = item.index === activeIndex;
+
+ const state = {
+ active: isActive,
+ disabled: !!disabled,
+ };
+
+ const defaultProps = {
+ 'data-cl-slot': 'menu-item',
+ type: 'button' as const,
+ ref: item.ref,
+ role: 'menuitem' as const,
+ tabIndex: isActive ? 0 : -1,
+ ...(disabled && { 'aria-disabled': true as const }),
+ ...(getItemProps({
+ onClick() {
+ if (!disabled && closeOnClick) {
+ tree?.events.emit('click');
+ }
+ },
+ }) as React.ComponentPropsWithRef<'button'>),
+ };
+
+ return renderElement({
+ defaultTagName: 'button',
+ render,
+ state,
+ stateAttributesMapping: {
+ active: (v: boolean) => (v ? { 'data-cl-active': '' } : null),
+ disabled: (v: boolean) => (v ? { 'data-cl-disabled': '' } : null),
+ },
+ props: mergeProps<'button'>(defaultProps, otherProps),
+ });
+}

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

@@ -0,0 +1,23 @@
+'use client';
+
+import { type ComponentProps, mergeProps, renderElement } from '../../utils/render-element';
+import { useMenuContext } from './menu-context';
+
+export interface MenuPopupProps extends ComponentProps<'div'> {}
+
+export function MenuPopup(props: MenuPopupProps) {
+ const { render, ...otherProps } = props;
+ const { popupRef, transitionProps } = useMenuContext();
+
+ const defaultProps = {
+ 'data-cl-slot': 'menu-popup',
+ ref: popupRef,
+ ...transitionProps,
+ };
+
+ return renderElement({
+ defaultTagName: 'div',
+ render,
+ props: mergeProps<'div'>(defaultProps, otherProps),
+ });
+}

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

@@ -0,0 +1,16 @@
+'use client';
+
+import { FloatingPortal } from '@floating-ui/react';
+import type { ReactNode } from 'react';
+import { useMenuContext } from './menu-context';
+
+export interface MenuPortalProps {
+ children: ReactNode;
+ root?: HTMLElement | null | React.RefObject<HTMLElement | null>;
+}
+
+export function MenuPortal(props: MenuPortalProps) {
+ const { mounted } = useMenuContext();
+ if (!mounted) return null;
+ return <FloatingPortal root={props.root}>{props.children}</FloatingPortal>;
+}