@eocrm/design-system 0.0.0-stage → 0.6.17

package/src/components/DropdownMenu/DropdownMenu.tokens.scss

@@ -0,0 +1,88 @@
+// DropdownMenu.tokens.scss — Component-scoped tokens for <DropdownMenu>. Each token defaults to the primitive the SCSS used before this migration. Covers the floating panel surface, per-item hover/checked/danger states, separator, group label, indicator, and submenu trigger.
+@use '../Badge/Badge.tokens';
+
+:root {
+  // Panel surface
+  --dropdown-menu-bg: var(--color-bg);
+  --dropdown-menu-border-color: var(--color-border);
+  --dropdown-menu-radius: var(--radius-md);
+  --dropdown-menu-shadow: var(--shadow-md);
+  --dropdown-menu-padding: var(--space-1);
+  --dropdown-menu-gap: var(--space-0);
+  --dropdown-menu-min-width: var(--size-dropdown-min-width);
+  --dropdown-menu-z: var(--z-dropdown);
+
+  // Entrance transition. Note: the `opacity: var(--opacity-hidden)` reference
+  // inside @starting-style is kept as the primitive directly — a unit test
+  // pins that exact substring (DropdownMenu.test.tsx → "animation hook"
+  // contract). Re-routing it through a component token would break the test.
+  --dropdown-menu-transition: var(--transition-base);
+
+  // Item
+  --dropdown-menu-item-gap: var(--space-2);
+  --dropdown-menu-item-padding-y: var(--space-1);
+  --dropdown-menu-item-padding-x: var(--space-2);
+  --dropdown-menu-item-radius: var(--radius-sm);
+  --dropdown-menu-item-font-size: var(--font-size-md);
+  --dropdown-menu-item-line-height: var(--line-height-normal);
+  --dropdown-menu-item-fg: var(--color-fg);
+  --dropdown-menu-item-bg-hover: var(--color-bg-muted);
+  --dropdown-menu-item-fg-disabled: var(--color-fg-disabled);
+
+  // Item — danger tone
+  --dropdown-menu-item-fg-danger: var(--color-danger);
+  --dropdown-menu-item-bg-danger-hover: var(--color-bg-danger-subtle);
+
+  // Item — checked state (accent-tinted with left accent)
+  --dropdown-menu-item-bg-checked: var(--color-accent-subtle-bg);
+  --dropdown-menu-item-fg-checked: var(--color-fg);
+  --dropdown-menu-item-accent-checked: var(--color-accent);
+  --dropdown-menu-item-accent-width-checked: var(--border-width-emphasis);
+
+  // Icon slot
+  --dropdown-menu-icon-size: var(--space-4);
+  --dropdown-menu-icon-fg: var(--color-fg-subtle);
+
+  // Shortcut label. It is real text in the a11y tree, so 1.4.3 applies, and
+  // it's painted inside .item with no hover override, so it inherits
+  // --dropdown-menu-item-bg-hover (--color-bg-muted) on hover. #511: was
+  // --color-fg-subtle, which fails there; --color-fg-muted clears it, same as
+  // --dropdown-menu-meta-fg below.
+  // @contrast --color-fg-muted on --color-bg-muted = 5.10:1 light
+  // @contrast --color-fg-muted on --color-bg-muted = 5.60:1 dark
+  --dropdown-menu-shortcut-fg: var(--color-fg-muted);
+  --dropdown-menu-shortcut-font-size: var(--font-size-sm);
+  --dropdown-menu-shortcut-padding-left: var(--space-3);
+
+  // Meta label (trailing secondary text about the item itself — a region
+  // code, a count, a Badge). Deliberately NOT the shortcut treatment: the
+  // shortcut slot is free to evolve into key caps without repainting meta.
+  --dropdown-menu-meta-fg: var(--color-fg-muted);
+  --dropdown-menu-meta-font-size: var(--font-size-xs);
+  --dropdown-menu-meta-padding-left: var(--space-2);
+
+  // Separator
+  --dropdown-menu-separator-height: var(--space-2);
+  --dropdown-menu-separator-color: var(--color-border);
+
+  // Group
+  --dropdown-menu-group-padding-block: var(--space-1);
+
+  // Group label
+  --dropdown-menu-label-padding-y: var(--space-1);
+  --dropdown-menu-label-padding-x: var(--space-2);
+  --dropdown-menu-label-font-size: var(--font-size-xs);
+  --dropdown-menu-label-font-weight: var(--font-weight-semibold);
+  --dropdown-menu-label-letter-spacing: var(--letter-spacing-caps);
+  --dropdown-menu-label-fg: var(--color-fg-subtle);
+
+  // Indicator slot
+  --dropdown-menu-indicator-size: var(--size-dropdown-indicator);
+
+  // Submenu trigger
+  --dropdown-menu-sub-chevron-font-size: var(--font-size-md);
+  --dropdown-menu-sub-chevron-line-height: var(--line-height-none);
+  --dropdown-menu-sub-chevron-fg: var(--color-fg-subtle);
+  --dropdown-menu-sub-chevron-padding-left: var(--space-2);
+  --dropdown-menu-sub-trigger-bg-open: var(--color-bg-muted);
+}

package/src/components/DropdownMenu/DropdownMenu.tsx

@@ -0,0 +1,43 @@
+import { DropdownMenuRoot } from './Root';
+import { Trigger } from './Trigger';
+import { Content } from './Content';
+import { Item, Separator } from './Item';
+import { Group, Label } from './Group';
+import { ItemIndicator } from './ItemIndicator';
+import { CheckboxItem } from './CheckboxItem';
+import { RadioGroup, RadioItem } from './Radio';
+import { Sub, SubTrigger, SubContent } from './Sub';
+
+export type { DropdownMenuProps } from './Root';
+export type { DropdownMenuTriggerProps } from './Trigger';
+export type { DropdownMenuContentProps, DropdownMenuSide, DropdownMenuAlign } from './Content';
+export type {
+  DropdownMenuItemProps,
+  DropdownMenuItemTone,
+  DropdownMenuSeparatorProps,
+} from './Item';
+export type { DropdownMenuGroupProps, DropdownMenuLabelProps } from './Group';
+export type { DropdownMenuItemIndicatorProps } from './ItemIndicator';
+export type { DropdownMenuCheckboxItemProps } from './CheckboxItem';
+export type { DropdownMenuRadioGroupProps, DropdownMenuRadioItemProps } from './Radio';
+export type {
+  DropdownMenuSubProps,
+  DropdownMenuSubTriggerProps,
+  DropdownMenuSubContentProps,
+} from './Sub';
+
+export const DropdownMenu = Object.assign(DropdownMenuRoot, {
+  Trigger,
+  Content,
+  Item,
+  Separator,
+  Group,
+  Label,
+  ItemIndicator,
+  CheckboxItem,
+  RadioGroup,
+  RadioItem,
+  Sub,
+  SubTrigger,
+  SubContent,
+});

package/src/components/DropdownMenu/Group.tsx

@@ -0,0 +1,76 @@
+import { forwardRef, useContext, useId, type HTMLAttributes, type ReactNode } from 'react';
+import clsx from 'clsx';
+import styles from './DropdownMenu.module.scss';
+import { GroupContext } from './context';
+import { sanitizeId } from '../_internal/refs';
+
+/**
+ * Props for `<DropdownMenu.Group>`.
+ *
+ * Extends all standard `div` HTML attributes so consumers can attach
+ * `data-*`, `className`, event handlers, etc.
+ */
+export interface DropdownMenuGroupProps extends HTMLAttributes<HTMLDivElement> {
+  /** Menu items (and optionally a `<DropdownMenu.Label>`) to include in the group. */
+  children: ReactNode;
+}
+
+/**
+ * Accessible grouping wrapper for related menu items, labelled by a `DropdownMenu.Label` inside it.
+ * @see docs/components/DropdownMenu.md
+ */
+export const Group = forwardRef<HTMLDivElement, DropdownMenuGroupProps>(function Group(
+  { children, className, ...rest },
+  ref,
+) {
+  const reactId = useId();
+  const labelId = `dropdown-menu-label-${sanitizeId(reactId)}`;
+  return (
+    <GroupContext.Provider value={{ labelId }}>
+      {/* {...rest} first so role and aria-labelledby always win */}
+      <div
+        {...rest}
+        ref={ref}
+        role="group"
+        aria-labelledby={labelId}
+        className={clsx(styles.group, className)}
+      >
+        {children}
+      </div>
+    </GroupContext.Provider>
+  );
+});
+
+/**
+ * Props for `<DropdownMenu.Label>`.
+ *
+ * Extends all standard `div` HTML attributes. When rendered inside a
+ * `<DropdownMenu.Group>`, the component controls the `id` attribute to
+ * satisfy the `aria-labelledby` contract — a consumer-supplied `id` is
+ * used only when outside a Group.
+ */
+export interface DropdownMenuLabelProps extends HTMLAttributes<HTMLDivElement> {
+  /** The label text content. */
+  children: ReactNode;
+}
+
+/**
+ * Non-interactive section heading inside a `DropdownMenu.Content`.
+ * @see docs/components/DropdownMenu.md
+ */
+
+export const Label = forwardRef<HTMLDivElement, DropdownMenuLabelProps>(function Label(
+  { children, className, id: idProp, ...rest },
+  ref,
+) {
+  const groupCtx = useContext(GroupContext);
+  // If inside a Group, use the group's label id so aria-labelledby resolves.
+  // Otherwise leave id as the consumer's (or undefined).
+  const id = idProp ?? groupCtx?.labelId;
+  return (
+    // {...rest} first so the resolved id (consumer prop ?? GroupContext) always wins.
+    <div {...rest} ref={ref} id={id} className={clsx(styles.label, className)}>
+      {children}
+    </div>
+  );
+});

package/src/components/DropdownMenu/Item.tsx

@@ -0,0 +1,148 @@
+import {
+  forwardRef,
+  useId,
+  useLayoutEffect,
+  useRef,
+  type HTMLAttributes,
+  type MouseEvent,
+  type ReactNode,
+} from 'react';
+import clsx from 'clsx';
+import { useDropdownMenuContext } from './context';
+import { mergeRefs } from '../_internal/refs';
+import styles from './DropdownMenu.module.scss';
+
+/** Item color treatment. */
+export type DropdownMenuItemTone = 'default' | 'danger';
+
+export interface DropdownMenuItemProps extends Omit<HTMLAttributes<HTMLDivElement>, 'onSelect'> {
+  /** Called when the item is activated (click or Enter/Space). The consumer performs the action. */
+  onSelect: () => void;
+  /**
+   * Visual tone.
+   * - `'default'` — normal action.
+   * - `'danger'` — destructive (Delete, Revoke, Remove). Reserve for irreversible operations.
+   */
+  tone?: DropdownMenuItemTone;
+  /** Leading icon. Rendered in a fixed-size slot so labels stay aligned across items. */
+  icon?: ReactNode;
+  /** Trailing shortcut hint (e.g. `'⌘D'`). Visual cue only — does NOT register a global key handler. */
+  shortcut?: string;
+  /**
+   * Trailing secondary content *about the item itself* — a region code, a
+   * count, a `<Badge>`. Distinct from `shortcut`, which is a keyboard hint
+   * and is styled (and free to evolve) as one.
+   *
+   * `ReactNode`, so a Badge or Dot can go here. It is NOT `aria-hidden`, so
+   * it joins the item's accessible name ("demo RU" rather than a second
+   * identical "demo") — which is the point when the label alone is
+   * ambiguous. It is a prop, not a child, so it stays out of the typeahead
+   * label; type-to-select still matches the pure label text.
+   *
+   * Renders before `shortcut` when both are present, keeping the keyboard
+   * hint rightmost.
+   */
+  meta?: ReactNode;
+  /** Disabled items are skipped by keyboard nav, dimmed, and don't fire `onSelect` on click. */
+  disabled?: boolean;
+  /**
+   * Whether to close the menu after `onSelect` fires. Defaults to `true`.
+   *
+   * Set to `false` when this item is wrapped in a Popover/ConfirmationPopover
+   * trigger — the trigger will open its panel on this click; closing the
+   * menu would unmount the popover before the user could interact with it.
+   * The menu can be dismissed separately (Escape or outside-click).
+   */
+  closeOnSelect?: boolean;
+}
+
+/**
+ * A selectable menu item that fires `onSelect` on activation.
+ * @see docs/components/DropdownMenu.md
+ */
+export const Item = forwardRef<HTMLDivElement, DropdownMenuItemProps>(function Item(
+  {
+    onSelect,
+    tone = 'default',
+    icon,
+    shortcut,
+    meta,
+    disabled = false,
+    closeOnSelect = true,
+    className,
+    children,
+    onClick: consumerOnClick,
+    ...rest
+  },
+  forwardedRef,
+) {
+  const ctx = useDropdownMenuContext('Item');
+  const itemRef = useRef<HTMLDivElement | null>(null);
+  const id = useId();
+
+  // String children become the typeahead label. Non-string fall back to '';
+  // typeahead won't match those, which is acceptable.
+  const label = typeof children === 'string' ? children : '';
+
+  // useLayoutEffect (not useEffect) so item registration completes BEFORE
+  // Content's parent useLayoutEffect runs to set activeIndex on open.
+  useLayoutEffect(() => {
+    return ctx.registerItem({ id, ref: itemRef, disabled, label });
+  }, [ctx, id, disabled, label]);
+
+  const index = ctx.itemsRef.current.findIndex((x) => x.id === id);
+  const isActive = index !== -1 && index === ctx.activeIndex;
+
+  const handleClick = (e: MouseEvent<HTMLDivElement>) => {
+    if (disabled) return;
+    // Run consumer's onClick first (e.g., injected by <Popover.Trigger> when
+    // this Item is wrapped as a popover trigger). Consumer can call
+    // `e.preventDefault()` to short-circuit the default onSelect+closeAll;
+    // otherwise we proceed.
+    consumerOnClick?.(e);
+    if (e.defaultPrevented) return;
+    onSelect();
+    if (closeOnSelect) ctx.closeAll();
+  };
+
+  return (
+    // {...rest} first so consumer-supplied props don't override the menuitem
+    // ARIA contract (role/tabIndex/aria-disabled) or our event wiring.
+    // onClick is owned by Item — we chain the consumer's onClick inside
+    // handleClick instead of letting {...rest} spread it (it would be
+    // overridden anyway by the explicit onClick below).
+    <div
+      {...rest}
+      ref={mergeRefs<HTMLDivElement>(itemRef, forwardedRef)}
+      role="menuitem"
+      tabIndex={isActive ? 0 : -1}
+      aria-disabled={disabled || undefined}
+      data-tone={tone}
+      className={clsx(styles.item, className)}
+      onClick={handleClick}
+    >
+      {icon !== undefined && <span className={styles.icon}>{icon}</span>}
+      <span className={styles.itemLabel}>{children}</span>
+      {meta !== undefined && <span className={styles.meta}>{meta}</span>}
+      {shortcut !== undefined && <span className={styles.shortcut}>{shortcut}</span>}
+    </div>
+  );
+});
+
+/** Visual divider between groups of items. Decorative — `role="separator"`. */
+export interface DropdownMenuSeparatorProps extends HTMLAttributes<HTMLDivElement> {}
+
+/**
+ * Decorative visual divider between groups of items (`role="separator"`, not focusable).
+ * @see docs/components/DropdownMenu.md
+ */
+export const Separator = forwardRef<HTMLDivElement, DropdownMenuSeparatorProps>(function Separator(
+  { className, ...rest },
+  ref,
+) {
+  return (
+    // {...rest} last; Separator is decorative and a consumer is free to
+    // override role/className for their own grouping conventions.
+    <div ref={ref} role="separator" className={clsx(styles.separator, className)} {...rest} />
+  );
+});

package/src/components/DropdownMenu/ItemIndicator.tsx

@@ -0,0 +1,30 @@
+import { forwardRef, type HTMLAttributes, type ReactNode } from 'react';
+
+/**
+ * Props for `<DropdownMenu.ItemIndicator>`.
+ *
+ * Extends standard `span` HTML attributes so consumers can apply
+ * `className`, `style`, `data-*`, etc. to the indicator wrapper.
+ */
+export interface DropdownMenuItemIndicatorProps extends HTMLAttributes<HTMLSpanElement> {
+  /**
+   * Indicator content (icon, custom glyph, animated element) to render in the
+   * parent item's indicator slot. The parent — CheckboxItem or RadioItem —
+   * decides when this is rendered based on its own `checked` state.
+   */
+  children?: ReactNode;
+}
+
+/**
+ * Marker for adding a custom indicator glyph alongside the tinted checked state of a `CheckboxItem` or `RadioItem`.
+ * @see docs/components/DropdownMenu.md
+ */
+export const ItemIndicator = forwardRef<HTMLSpanElement, DropdownMenuItemIndicatorProps>(
+  function ItemIndicator({ children, ...rest }, ref) {
+    return (
+      <span ref={ref} {...rest}>
+        {children}
+      </span>
+    );
+  },
+);

package/src/components/DropdownMenu/Radio.tsx

@@ -0,0 +1,178 @@
+import {
+  Children,
+  forwardRef,
+  isValidElement,
+  useId,
+  useLayoutEffect,
+  useRef,
+  type HTMLAttributes,
+  type MouseEvent,
+  type ReactNode,
+} from 'react';
+import clsx from 'clsx';
+import styles from './DropdownMenu.module.scss';
+import { RadioGroupContext, useDropdownMenuContext, useRadioGroupContext } from './context';
+import { mergeRefs } from '../_internal/refs';
+import { ItemIndicator } from './ItemIndicator';
+
+/**
+ * Props for `<DropdownMenu.RadioGroup>`.
+ *
+ * Extends standard `div` HTML attributes. `value` and `onValueChange` drive
+ * the controlled selection; they are also distributed to child `RadioItem`s
+ * via context, so no prop-drilling is required.
+ */
+export interface DropdownMenuRadioGroupProps extends HTMLAttributes<HTMLDivElement> {
+  /** The currently-selected value. Must match the `value` prop of one of the child RadioItems. */
+  value: string;
+  /** Called with the new value when a `<DropdownMenu.RadioItem>` is activated. */
+  onValueChange: (value: string) => void;
+  /** `<DropdownMenu.RadioItem>` children (and optionally `<DropdownMenu.Label>`). */
+  children: ReactNode;
+}
+
+/**
+ * Mutually exclusive selection group of `RadioItem`s, rendered as `role="radiogroup"`.
+ * @see docs/components/DropdownMenu.md
+ */
+export const RadioGroup = forwardRef<HTMLDivElement, DropdownMenuRadioGroupProps>(
+  function RadioGroup({ value, onValueChange, className, children, ...rest }, ref) {
+    return (
+      <RadioGroupContext.Provider value={{ value, onValueChange }}>
+        {/* {...rest} first so consumer props don't override role="radiogroup" */}
+        <div {...rest} ref={ref} role="radiogroup" className={clsx(styles.group, className)}>
+          {children}
+        </div>
+      </RadioGroupContext.Provider>
+    );
+  },
+);
+
+/**
+ * Props for `<DropdownMenu.RadioItem>`.
+ *
+ * Extends standard `div` HTML attributes, omitting `onSelect` (selection is
+ * communicated via the parent `RadioGroup`'s `onValueChange`). The ARIA
+ * contract attributes (`role`, `aria-checked`, `aria-disabled`) are always
+ * set by the component.
+ */
+export interface DropdownMenuRadioItemProps extends Omit<
+  HTMLAttributes<HTMLDivElement>,
+  'onSelect'
+> {
+  /** The value this item represents. Activating sets the parent RadioGroup's value to this. */
+  value: string;
+  /**
+   * Whether activating closes the entire menu chain. Defaults to `true` —
+   * radio selection IS the action; the menu's job is done once a value is chosen.
+   * Set to `false` for preview-style selection where the menu stays open.
+   */
+  closeOnSelect?: boolean;
+  /** Disabled items don't fire `onValueChange`, are skipped by keyboard nav, and render dimmed. */
+  disabled?: boolean;
+  /**
+   * Leading icon, rendered in a fixed-size slot before the label (parity with
+   * `<DropdownMenu.Item icon>`). Prefer this over inlining an icon into
+   * `children`: typeahead derives its match string from the string children, so
+   * an inlined leading icon leaves the JSX whitespace `" "` as the first string
+   * child and breaks first-letter type-to-select. Passing the icon here keeps
+   * the typeahead label the pure label string. Mark the glyph `aria-hidden`.
+   */
+  icon?: ReactNode;
+  /** Optional trailing shortcut hint (e.g. `'⌘N'`). Visual cue only — does NOT register a global key handler. */
+  shortcut?: string;
+  /**
+   * Trailing secondary content *about the item itself* — a region code, a
+   * count, a `<Badge>`. Distinct from `shortcut`, which is a keyboard hint
+   * and is styled (and free to evolve) as one.
+   *
+   * `ReactNode`, so a Badge or Dot can go here. It is NOT `aria-hidden`, so
+   * it joins the item's accessible name ("demo RU" rather than a second
+   * identical "demo") — which is the point when the label alone is
+   * ambiguous. It is a prop, not a child, so it stays out of the typeahead
+   * label; type-to-select still matches the pure label text.
+   *
+   * Renders before `shortcut` when both are present, keeping the keyboard
+   * hint rightmost.
+   */
+  meta?: ReactNode;
+  /**
+   * Item content. May include a `<DropdownMenu.ItemIndicator>` as a direct
+   * child to provide a custom indicator glyph.
+   */
+  children: ReactNode;
+}
+
+/**
+ * Single radio item (`role="menuitemradio"`) inside a `RadioGroup`; closes the menu on select by default.
+ * @see docs/components/DropdownMenu.md
+ */
+export const RadioItem = forwardRef<HTMLDivElement, DropdownMenuRadioItemProps>(function RadioItem(
+  {
+    value,
+    closeOnSelect = true,
+    disabled = false,
+    icon,
+    shortcut,
+    meta,
+    className,
+    children,
+    ...rest
+  },
+  forwardedRef,
+) {
+  const ctx = useDropdownMenuContext('RadioItem');
+  const groupCtx = useRadioGroupContext('RadioItem');
+  const itemRef = useRef<HTMLDivElement | null>(null);
+  const id = useId();
+
+  const checked = groupCtx.value === value;
+
+  // Extract any ItemIndicator from direct children.
+  const childrenArray = Children.toArray(children);
+  const indicator = childrenArray.find((c) => isValidElement(c) && c.type === ItemIndicator);
+  const labelContent = childrenArray.filter((c) => c !== indicator);
+  const labelText = labelContent.find((c): c is string => typeof c === 'string') ?? '';
+
+  useLayoutEffect(() => {
+    return ctx.registerItem({ id, ref: itemRef, disabled, label: labelText });
+  }, [ctx, id, disabled, labelText]);
+
+  const index = ctx.itemsRef.current.findIndex((x) => x.id === id);
+  const isActive = index !== -1 && index === ctx.activeIndex;
+
+  const handleClick = (_e: MouseEvent) => {
+    if (disabled) return;
+    groupCtx.onValueChange(value);
+    if (closeOnSelect) {
+      ctx.closeAll();
+    }
+  };
+
+  return (
+    // {...rest} first so consumer props don't override the menuitemradio ARIA contract.
+    <div
+      {...rest}
+      ref={mergeRefs<HTMLDivElement>(itemRef, forwardedRef)}
+      role="menuitemradio"
+      tabIndex={isActive ? 0 : -1}
+      aria-checked={checked}
+      aria-disabled={disabled || undefined}
+      className={clsx(styles.item, className)}
+      onClick={handleClick}
+    >
+      {/* Indicator slot only rendered when a custom ItemIndicator is provided.
+          Default checked state is conveyed via the row's tinted background +
+          left accent (.item[aria-checked='true'] in SCSS). */}
+      {indicator && (
+        <span aria-hidden="true" className={styles.indicatorSlot}>
+          {checked && indicator}
+        </span>
+      )}
+      {icon !== undefined && <span className={styles.icon}>{icon}</span>}
+      <span className={styles.itemLabel}>{labelContent}</span>
+      {meta !== undefined && <span className={styles.meta}>{meta}</span>}
+      {shortcut !== undefined && <span className={styles.shortcut}>{shortcut}</span>}
+    </div>
+  );
+});

package/src/components/DropdownMenu/Root.tsx

@@ -0,0 +1,100 @@
+import { useCallback, useEffect, useId, useRef, useState, type ReactNode } from 'react';
+import { DropdownMenuContext, type DropdownMenuContextValue, type RegisteredItem } from './context';
+import { sanitizeId } from '../_internal/refs';
+import { useFloatingSurface, useInOverlay } from '../_internal/overlay';
+
+export interface DropdownMenuProps {
+  /** Must contain exactly one `<DropdownMenu.Trigger>` and one `<DropdownMenu.Content>`. */
+  children: ReactNode;
+  /**
+   * Controlled open state. Provide alongside `onOpenChange` to drive open
+   * externally. Omit both to let DropdownMenu own its own state (the common
+   * case).
+   */
+  open?: boolean;
+  /** Fired whenever DropdownMenu wants to change open state. Required when `open` is provided. */
+  onOpenChange?: (open: boolean) => void;
+  /** Default open state for uncontrolled usage. Defaults to `false`. */
+  defaultOpen?: boolean;
+}
+
+/**
+ * Action menu that opens from a trigger button, implementing the WAI-ARIA menu pattern.
+ * @see docs/components/DropdownMenu.md
+ */
+export function DropdownMenuRoot({
+  children,
+  open: controlledOpen,
+  onOpenChange,
+  defaultOpen = false,
+}: DropdownMenuProps) {
+  const isControlled = controlledOpen !== undefined;
+  const [uncontrolledOpen, setUncontrolledOpen] = useState(defaultOpen);
+  const open = isControlled ? (controlledOpen as boolean) : uncontrolledOpen;
+
+  const setOpen = useCallback(
+    (next: boolean) => {
+      onOpenChange?.(next);
+      if (!isControlled) setUncontrolledOpen(next);
+    },
+    [isControlled, onOpenChange],
+  );
+
+  const triggerRef = useRef<HTMLElement | null>(null);
+  const inOverlay = useInOverlay(triggerRef, open);
+  // #274: hosts yield Escape while the menu (any level) is open — the
+  // menu's own capture listeners peel one level per press instead. The id lets
+  // Content defer to a DEEPER surface (e.g. a popover from an item) (#280).
+  const floatingId = useFloatingSurface(open);
+  const reactId = useId();
+  const contentId = `dropdown-menu-${sanitizeId(reactId)}`;
+
+  const [openIntent, setOpenIntent] = useState<'first' | 'last' | null>(null);
+
+  const itemsRef = useRef<RegisteredItem[]>([]);
+  const [activeIndex, setActiveIndex] = useState<number>(-1);
+
+  const registerItem = useCallback((item: RegisteredItem) => {
+    if (!itemsRef.current.some((x) => x.id === item.id)) {
+      itemsRef.current.push(item);
+    }
+    return () => {
+      itemsRef.current = itemsRef.current.filter((x) => x.id !== item.id);
+    };
+  }, []);
+
+  // Reset registry indicator when menu closes. The registry array itself is
+  // cleared by item unmount cleanups.
+  useEffect(() => {
+    if (!open) {
+      setActiveIndex(-1);
+    }
+  }, [open]);
+
+  const closeAll = useCallback(() => {
+    setOpen(false);
+    // preventScroll: focus() on the trigger after close shouldn't trigger
+    // browser auto-scroll if the page happens to be scrolled (trigger is
+    // already visible since the user just interacted with it).
+    triggerRef.current?.focus({ preventScroll: true });
+  }, [setOpen]);
+
+  const value: DropdownMenuContextValue = {
+    open,
+    setOpen,
+    triggerRef,
+    contentId,
+    openIntent,
+    setOpenIntent,
+    registerItem,
+    itemsRef,
+    activeIndex,
+    setActiveIndex,
+    closeAll,
+    depth: 0,
+    inOverlay,
+    floatingId,
+  };
+
+  return <DropdownMenuContext.Provider value={value}>{children}</DropdownMenuContext.Provider>;
+}