@primitiv-ui/react 0.1.37 → 0.1.39

package/dist/Dropdown/Dropdown.js

@@ -0,0 +1,745 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useContext, useEffect, useId, useMemo, useRef, useState } from "react";
+import { useCheckboxRoot } from "../Checkbox/hooks/index.js";
+import { useDirection } from "../DirectionProvider/index.js";
+import { useRadioGroupRoot } from "../RadioGroup/hooks/index.js";
+import { composeEventHandlers, Slot } from "../Slot/index.js";
+import { DropdownContext } from "./DropdownContext.js";
+import { DropdownContentContext } from "./DropdownContentContext.js";
+import { DropdownGroupContext } from "./DropdownGroupContext.js";
+import { DropdownItemIndicatorContext } from "./DropdownItemIndicatorContext.js";
+import { DropdownRadioGroupContext } from "./DropdownRadioGroupContext.js";
+import { DropdownSubContext } from "./DropdownSubContext.js";
+import { useCloseSiblingSub, useDropdownContent, useDropdownContext, useDropdownGroup, useDropdownItem, useDropdownLabel, useDropdownRoot, useDropdownSubContext, useDropdownTrigger, } from "./hooks/index.js";
+import { MENUITEM_SELECTOR } from "./constants.js";
+/**
+ * The root of a Dropdown menu — owns the open state and provides context to
+ * descendants. Renders no DOM of its own; it is a context boundary.
+ *
+ * Supports two state modes, statically discriminated at the type level so
+ * only one shape is accepted by TypeScript:
+ *
+ * - **Uncontrolled** — pass {@link DropdownRootProps.defaultOpen | `defaultOpen`}
+ *   (or omit it to start closed). The component owns and updates the open
+ *   state internally. Optional {@link DropdownRootProps.onOpenChange | `onOpenChange`}
+ *   observes transitions.
+ * - **Controlled** — pass {@link DropdownRootProps.open | `open`} *and*
+ *   {@link DropdownRootProps.onOpenChange | `onOpenChange`} together. The
+ *   parent owns the state; the component defers every transition back through
+ *   the callback.
+ *
+ * Only user-driven transitions (trigger clicks, Escape, selection) invoke
+ * `onOpenChange`. External state flips made by the parent do not.
+ *
+ * **Reading direction.** Pass {@link DropdownRootProps.dir | `dir`} to set
+ * `"ltr"` or `"rtl"`, which inverts the submenu open / close arrow keys
+ * (`ArrowRight` ↔ `ArrowLeft`). When omitted, the component reads the
+ * inherited {@link DirectionProvider} value, falling back to `"ltr"`.
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <Dropdown.Root>
+ *   <Dropdown.Trigger>Options</Dropdown.Trigger>
+ *   <Dropdown.Content>
+ *     <Dropdown.Item>Rename</Dropdown.Item>
+ *     <Dropdown.Item>Delete</Dropdown.Item>
+ *   </Dropdown.Content>
+ * </Dropdown.Root>
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [open, setOpen] = useState(false);
+ *
+ * <Dropdown.Root open={open} onOpenChange={setOpen}>
+ *   ...
+ * </Dropdown.Root>
+ * ```
+ */
+export function DropdownRoot({ defaultOpen, open, onOpenChange, dir, children, }) {
+    const inheritedDir = useDirection();
+    const { contextValue } = useDropdownRoot({
+        defaultOpen,
+        open,
+        onOpenChange,
+        dir: dir ?? inheritedDir,
+    });
+    return (_jsx(DropdownContext.Provider, { value: contextValue, children: children }));
+}
+/** @internal */
+DropdownRoot.displayName = "DropdownRoot";
+/**
+ * The menu button. Toggles the Dropdown open/closed on click and exposes
+ * the ARIA contract for WAI-ARIA Menu Button: `aria-haspopup="menu"`,
+ * `aria-expanded` reflecting the open state, and `aria-controls` pointing
+ * at the content's id.
+ *
+ * Renders a `<button type="button">` by default. Pass `asChild` to render
+ * the composed child element instead (e.g. a link, or a custom button
+ * component). All ARIA attributes and event handlers are merged onto the
+ * child following the {@link Slot} composition rules.
+ *
+ * @extends HTMLButtonElement
+ *
+ * @example With an anchor via `asChild`
+ * ```tsx
+ * <Dropdown.Trigger asChild>
+ *   <a href="#options">Options</a>
+ * </Dropdown.Trigger>
+ * ```
+ */
+export function DropdownTrigger({ children, onClick, asChild = false, ...rest }) {
+    const { triggerProps } = useDropdownTrigger({ onClick, restProps: rest });
+    if (asChild) {
+        return _jsx(Slot, { ...triggerProps, children: children });
+    }
+    return (_jsx("button", { type: "button", ...triggerProps, children: children }));
+}
+/** @internal */
+DropdownTrigger.displayName = "DropdownTrigger";
+/**
+ * The menu panel rendered with the native HTML
+ * [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API)
+ * (`popover="auto"`) — no portal, no floating-ui. The browser manages
+ * layering via the top layer and dispatches a light-dismiss on outside
+ * click and Escape in the light-dismiss flow.
+ *
+ * Renders a `<menu role="menu">` by default; pass `asChild` to render
+ * any element with menu semantics.
+ *
+ * **Keyboard interaction.** While the menu is open:
+ *
+ * | Key                     | Behaviour                                          |
+ * | ----------------------- | -------------------------------------------------- |
+ * | `ArrowDown` / `ArrowUp` | Move focus to next / previous item (wraps)         |
+ * | `Home` / `End`          | Jump to first / last item                          |
+ * | `Enter` / `Space`       | Activate the focused item                          |
+ * | `Escape`                | Close the menu and return focus to the trigger     |
+ * | any printable character | Typeahead — focuses the next item matching prefix  |
+ *
+ * Typeahead accumulates keystrokes within a 500 ms window; pressing the
+ * same character repeatedly cycles through items that share that first
+ * letter. Disabled items are skipped during arrow navigation and typeahead.
+ *
+ * Arrow navigation is scoped to the popover that currently holds focus —
+ * a {@link DropdownSubContent | `Dropdown.SubContent`} rendered inside
+ * this menu does not pull its items into the parent's navigation cycle,
+ * so `ArrowDown` past a {@link DropdownSubTrigger | `Dropdown.SubTrigger`}
+ * lands on the next sibling item in the parent rather than getting
+ * stuck on a non-focusable item inside a closed sub-popover.
+ *
+ * @extends HTMLMenuElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.Content>
+ *   <Dropdown.Item onSelect={rename}>Rename</Dropdown.Item>
+ *   <Dropdown.Separator />
+ *   <Dropdown.Item onSelect={remove}>Delete</Dropdown.Item>
+ * </Dropdown.Content>
+ * ```
+ */
+export function DropdownContent({ children, onKeyDown, asChild = false, ...rest }) {
+    const { contentContextValue, contentProps } = useDropdownContent({
+        onKeyDown,
+        restProps: rest,
+    });
+    return (_jsx(DropdownContentContext.Provider, { value: contentContextValue, children: asChild ? (_jsx(Slot, { ...contentProps, children: children })) : (_jsx("menu", { ...contentProps, children: children })) }));
+}
+/** @internal */
+DropdownContent.displayName = "DropdownContent";
+/**
+ * A standard menu item. Renders a `<li role="menuitem">` by default; pass
+ * `asChild` to render any element with menuitem semantics.
+ *
+ * Clicking the item (or pressing Enter / Space while focused) fires
+ * {@link DropdownItemProps.onSelect | `onSelect`} with a cancellable
+ * `Event`. The menu auto-closes after selection; call
+ * `event.preventDefault()` inside `onSelect` to keep it open — useful
+ * for actions that perform in-place mutations (e.g. copying to clipboard).
+ *
+ * Disabled items receive `aria-disabled="true"` and are skipped by arrow
+ * navigation, typeahead, and activation handlers.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example Keep the menu open after selecting
+ * ```tsx
+ * <Dropdown.Item onSelect={(event) => {
+ *   copyToClipboard();
+ *   event.preventDefault();
+ * }}>
+ *   Copy link
+ * </Dropdown.Item>
+ * ```
+ */
+export function DropdownItem({ children, onClick, onSelect, disabled, asChild = false, ...rest }) {
+    const { itemProps } = useDropdownItem({
+        disabled,
+        onClick,
+        onSelect,
+        restProps: rest,
+    });
+    if (asChild) {
+        return _jsx(Slot, { ...itemProps, children: children });
+    }
+    return _jsx("li", { ...itemProps, children: children });
+}
+/** @internal */
+DropdownItem.displayName = "DropdownItem";
+/**
+ * A visual separator between groups of items. Renders a `<li role="separator">`
+ * by default; pass `asChild` to render any element with separator semantics.
+ * Non-interactive — skipped by focus, arrow navigation, and typeahead.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.Item>Cut</Dropdown.Item>
+ * <Dropdown.Separator />
+ * <Dropdown.Item>Paste</Dropdown.Item>
+ * ```
+ */
+export function DropdownSeparator({ asChild = false, children, ...rest }) {
+    const separatorProps = { ...rest, role: "separator" };
+    if (asChild) {
+        return _jsx(Slot, { ...separatorProps, children: children });
+    }
+    return _jsx("li", { ...separatorProps });
+}
+/** @internal */
+DropdownSeparator.displayName = "DropdownSeparator";
+/**
+ * A semantic grouping of related items. Renders as a `<li role="group">`
+ * wrapping an inner `<ul role="none">`, or — with `asChild` — a single
+ * grouping element composed onto the provided child.
+ *
+ * Generates a stable id for its accompanying {@link DropdownLabel | `Dropdown.Label`},
+ * wired automatically via `aria-labelledby`. Nest a `Dropdown.Label` as the
+ * first child to provide the accessible name; screen readers will announce
+ * the group when arrowing into it.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.Group>
+ *   <Dropdown.Label>Sort by</Dropdown.Label>
+ *   <Dropdown.Item>Name</Dropdown.Item>
+ *   <Dropdown.Item>Date</Dropdown.Item>
+ * </Dropdown.Group>
+ * ```
+ */
+export function DropdownGroup({ children, asChild = false, ...rest }) {
+    const { contextValue, groupProps } = useDropdownGroup({ restProps: rest });
+    return (_jsx(DropdownGroupContext.Provider, { value: contextValue, children: asChild ? (_jsx(Slot, { ...groupProps, children: children })) : (_jsx("li", { ...groupProps, children: _jsx("ul", { role: "none", children: children }) })) }));
+}
+/** @internal */
+DropdownGroup.displayName = "DropdownGroup";
+/**
+ * A non-interactive label, typically used inside a {@link DropdownGroup |
+ * `Dropdown.Group`} to give that group an accessible name. When nested in
+ * a group, the label's `id` is auto-wired to the group's `aria-labelledby`
+ * — consumers don't need to thread ids manually.
+ *
+ * Renders a `<li>` by default; pass `asChild` to render any element. A
+ * caller-supplied `id` takes precedence over the auto-generated one.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.Group>
+ *   <Dropdown.Label>Actions</Dropdown.Label>
+ *   <Dropdown.Item>Duplicate</Dropdown.Item>
+ * </Dropdown.Group>
+ * ```
+ */
+export function DropdownLabel({ id, children, asChild = false, ...rest }) {
+    const { labelProps } = useDropdownLabel({ id, restProps: rest });
+    if (asChild) {
+        return _jsx(Slot, { ...labelProps, children: children });
+    }
+    return _jsx("li", { ...labelProps, children: children });
+}
+/** @internal */
+DropdownLabel.displayName = "DropdownLabel";
+/**
+ * A toggleable menu item. Renders a `<li role="menuitemcheckbox">` with
+ * `aria-checked` reflecting the current state. `asChild` is supported.
+ *
+ * Supports a WAI-ARIA tri-state: `true`, `false`, or `"indeterminate"`
+ * (encoded as `aria-checked="mixed"`). An indeterminate item resolves to
+ * `true` on the next activation, matching the native `<input type="checkbox">`
+ * behaviour.
+ *
+ * State modes are discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass `defaultChecked` (or omit to start unchecked).
+ *   Optional `onCheckedChange` observes toggles.
+ * - **Controlled** — pass `checked` *and* `onCheckedChange` together.
+ *
+ * Activation (click / Enter / Space) toggles the checked state, then
+ * fires {@link DropdownCheckboxItemProps.onSelect | `onSelect`} with a
+ * cancellable `Event`. Call `event.preventDefault()` to keep the menu
+ * open — useful for rapidly toggling multiple checkboxes.
+ *
+ * Nest a {@link DropdownItemIndicator | `Dropdown.ItemIndicator`} to
+ * render the visible check mark; it reads its parent's state from
+ * context and exposes `data-state` for styling.
+ *
+ * Disabled items receive `aria-disabled="true"` and no-op on activation.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example Controlled checkbox item
+ * ```tsx
+ * <Dropdown.CheckboxItem checked={showGrid} onCheckedChange={setShowGrid}>
+ *   <Dropdown.ItemIndicator>
+ *     <CheckIcon />
+ *   </Dropdown.ItemIndicator>
+ *   Show grid
+ * </Dropdown.CheckboxItem>
+ * ```
+ */
+export function DropdownCheckboxItem({ children, onClick, onSelect, disabled, defaultChecked, checked: controlledChecked, onCheckedChange, asChild = false, ...rest }) {
+    const { setOpen, triggerRef } = useDropdownContext();
+    const closeSiblingSub = useCloseSiblingSub();
+    const [highlighted, setHighlighted] = useState(false);
+    const { checked, toggle } = useCheckboxRoot({
+        defaultChecked,
+        checked: controlledChecked,
+        onCheckedChange,
+    });
+    const ariaChecked = checked === "indeterminate" ? "mixed" : checked ? "true" : "false";
+    const handleClick = () => {
+        if (disabled)
+            return;
+        toggle();
+        const event = new Event("dropdown.select", { cancelable: true });
+        onSelect?.(event);
+        if (!event.defaultPrevented) {
+            setOpen(false);
+            triggerRef.current?.focus();
+        }
+    };
+    const itemProps = {
+        ...rest,
+        role: "menuitemcheckbox",
+        tabIndex: -1,
+        "aria-checked": ariaChecked,
+        "aria-disabled": disabled || undefined,
+        "data-highlighted": highlighted ? "" : undefined,
+        onClick: composeEventHandlers(onClick, handleClick),
+        onMouseEnter: composeEventHandlers(rest.onMouseEnter, () => {
+            setHighlighted(true);
+            closeSiblingSub();
+        }),
+        onMouseLeave: composeEventHandlers(rest.onMouseLeave, () => setHighlighted(false)),
+    };
+    const indicatorContextValue = useMemo(() => ({ checked }), [checked]);
+    const content = asChild ? (_jsx(Slot, { ...itemProps, children: children })) : (_jsx("li", { ...itemProps, children: children }));
+    return (_jsx(DropdownItemIndicatorContext.Provider, { value: indicatorContextValue, children: content }));
+}
+/** @internal */
+DropdownCheckboxItem.displayName = "DropdownCheckboxItem";
+/**
+ * A single-selection group of menu items. Children must be
+ * {@link DropdownRadioItem | `Dropdown.RadioItem`} elements. Renders a
+ * `<li role="group">` wrapping `<ul role="none">`, or — with `asChild` —
+ * composes onto the provided child.
+ *
+ * State modes are discriminated at the type level:
+ *
+ * - **Uncontrolled** — pass `defaultValue` (or omit for no initial selection).
+ *   Optional `onValueChange` observes selections.
+ * - **Controlled** — pass `value` *and* `onValueChange` together.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.RadioGroup value={sort} onValueChange={setSort}>
+ *   <Dropdown.RadioItem value="name">
+ *     <Dropdown.ItemIndicator>•</Dropdown.ItemIndicator>
+ *     Name
+ *   </Dropdown.RadioItem>
+ *   <Dropdown.RadioItem value="date">
+ *     <Dropdown.ItemIndicator>•</Dropdown.ItemIndicator>
+ *     Date
+ *   </Dropdown.RadioItem>
+ * </Dropdown.RadioGroup>
+ * ```
+ */
+export function DropdownRadioGroup({ defaultValue, value: controlledValue, onValueChange, children, asChild = false, ...rest }) {
+    const { value, select } = useRadioGroupRoot({
+        defaultValue,
+        value: controlledValue,
+        onValueChange,
+    });
+    const contextValue = useMemo(() => ({ value, select }), [value, select]);
+    const groupProps = { ...rest, role: "group" };
+    return (_jsx(DropdownRadioGroupContext.Provider, { value: contextValue, children: asChild ? (_jsx(Slot, { ...groupProps, children: children })) : (_jsx("li", { ...groupProps, children: _jsx("ul", { role: "none", children: children }) })) }));
+}
+/** @internal */
+DropdownRadioGroup.displayName = "DropdownRadioGroup";
+/**
+ * A single radio choice. Must be rendered inside a
+ * {@link DropdownRadioGroup | `Dropdown.RadioGroup`}; rendering it outside
+ * one throws a descriptive error.
+ *
+ * Renders a `<li role="menuitemradio">` with `aria-checked` reflecting
+ * whether this item's `value` matches the group's active value. `asChild`
+ * is supported.
+ *
+ * Activation (click / Enter / Space) selects this item, updating the
+ * group's value, then fires {@link DropdownRadioItemProps.onSelect |
+ * `onSelect`} with a cancellable `Event`. Call `event.preventDefault()`
+ * to keep the menu open.
+ *
+ * Nest a {@link DropdownItemIndicator | `Dropdown.ItemIndicator`} to
+ * render the visible bullet; it reads its parent's state from context
+ * and exposes `data-state` for styling.
+ *
+ * Disabled items receive `aria-disabled="true"` and no-op on activation.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.RadioItem value="compact">
+ *   <Dropdown.ItemIndicator>•</Dropdown.ItemIndicator>
+ *   Compact
+ * </Dropdown.RadioItem>
+ * ```
+ */
+export function DropdownRadioItem({ children, onClick, onSelect, disabled, value: itemValue, asChild = false, ...rest }) {
+    const { setOpen, triggerRef } = useDropdownContext();
+    const closeSiblingSub = useCloseSiblingSub();
+    const [highlighted, setHighlighted] = useState(false);
+    const group = useContext(DropdownRadioGroupContext);
+    if (!group) {
+        throw new Error("Dropdown.RadioItem must be rendered inside a <Dropdown.RadioGroup>.");
+    }
+    const checked = group.value === itemValue;
+    const handleClick = () => {
+        if (disabled)
+            return;
+        group.select(itemValue);
+        const event = new Event("dropdown.select", { cancelable: true });
+        onSelect?.(event);
+        if (!event.defaultPrevented) {
+            setOpen(false);
+            triggerRef.current?.focus();
+        }
+    };
+    const itemProps = {
+        ...rest,
+        role: "menuitemradio",
+        tabIndex: -1,
+        "aria-checked": checked,
+        "aria-disabled": disabled || undefined,
+        "data-highlighted": highlighted ? "" : undefined,
+        onClick: composeEventHandlers(onClick, handleClick),
+        onMouseEnter: composeEventHandlers(rest.onMouseEnter, () => {
+            setHighlighted(true);
+            closeSiblingSub();
+        }),
+        onMouseLeave: composeEventHandlers(rest.onMouseLeave, () => setHighlighted(false)),
+    };
+    const indicatorContextValue = useMemo(() => ({ checked }), [checked]);
+    const content = asChild ? (_jsx(Slot, { ...itemProps, children: children })) : (_jsx("li", { ...itemProps, children: children }));
+    return (_jsx(DropdownItemIndicatorContext.Provider, { value: indicatorContextValue, children: content }));
+}
+/** @internal */
+DropdownRadioItem.displayName = "DropdownRadioItem";
+/**
+ * The visible mark (usually a checkmark or a bullet) rendered inside a
+ * {@link DropdownCheckboxItem | `Dropdown.CheckboxItem`} or
+ * {@link DropdownRadioItem | `Dropdown.RadioItem`}. Must be a descendant
+ * of one of those; rendering it anywhere else throws a descriptive error.
+ *
+ * Renders a `<span>` by default; pass `asChild` to compose onto any
+ * element (commonly an SVG icon). Exposes `data-state` reflecting the
+ * parent item's live state: `"checked"`, `"unchecked"`, or
+ * `"indeterminate"` — the last being reachable only through a tri-state
+ * `Dropdown.CheckboxItem`.
+ *
+ * By default the indicator unmounts when its parent is unchecked. Pass
+ * {@link DropdownItemIndicatorProps.forceMount | `forceMount`} to keep
+ * the DOM node mounted in both states, which is handy when animating the
+ * indicator in and out via CSS transitions or a React animation library.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.CheckboxItem checked={showBookmarks} onCheckedChange={setShowBookmarks}>
+ *   <Dropdown.ItemIndicator>
+ *     <CheckIcon />
+ *   </Dropdown.ItemIndicator>
+ *   Show bookmarks
+ * </Dropdown.CheckboxItem>
+ * ```
+ */
+export function DropdownItemIndicator({ children, asChild = false, forceMount = false, ...rest }) {
+    const context = useContext(DropdownItemIndicatorContext);
+    if (!context) {
+        throw new Error("Dropdown.ItemIndicator must be rendered inside a <Dropdown.CheckboxItem> or <Dropdown.RadioItem>.");
+    }
+    const { checked } = context;
+    const dataState = checked === "indeterminate"
+        ? "indeterminate"
+        : checked
+            ? "checked"
+            : "unchecked";
+    if (!forceMount && checked === false)
+        return null;
+    const indicatorProps = { ...rest, "data-state": dataState };
+    if (asChild) {
+        return _jsx(Slot, { ...indicatorProps, children: children });
+    }
+    return _jsx("span", { ...indicatorProps, children: children });
+}
+/** @internal */
+DropdownItemIndicator.displayName = "DropdownItemIndicator";
+/**
+ * A submenu boundary. Wrap a {@link DropdownSubTrigger | `Dropdown.SubTrigger`}
+ * and its {@link DropdownSubContent | `Dropdown.SubContent`} in a
+ * `Dropdown.Sub` to establish an independent open state for the nested menu.
+ *
+ * Supports uncontrolled (`defaultOpen`) and controlled (`open` +
+ * `onOpenChange`) modes, discriminated at the type level — same contract
+ * as {@link DropdownRoot | `Dropdown.Root`}.
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.Root>
+ *   <Dropdown.Trigger>File</Dropdown.Trigger>
+ *   <Dropdown.Content>
+ *     <Dropdown.Sub>
+ *       <Dropdown.SubTrigger>Open Recent</Dropdown.SubTrigger>
+ *       <Dropdown.SubContent>
+ *         <Dropdown.Item>Project A</Dropdown.Item>
+ *         <Dropdown.Item>Project B</Dropdown.Item>
+ *       </Dropdown.SubContent>
+ *     </Dropdown.Sub>
+ *   </Dropdown.Content>
+ * </Dropdown.Root>
+ * ```
+ */
+export function DropdownSub({ defaultOpen, open: controlledOpen, onOpenChange, children, }) {
+    const { open, setOpen } = useDropdownRoot({
+        defaultOpen,
+        open: controlledOpen,
+        onOpenChange,
+    });
+    const contentId = useId();
+    const triggerRef = useRef(null);
+    const contextValue = useMemo(() => ({ open, setOpen, contentId, triggerRef }), [open, setOpen, contentId]);
+    // Register with the enclosing Content so sibling items can close this sub
+    // on hover (mirroring the keyboard behaviour where returning focus to the
+    // parent menu dismisses the sub). If another sibling sub is already
+    // registered as open, close it first — a hover-to-open transition onto
+    // our SubTrigger should supplant the prior sub, not stack it.
+    const parentContent = useContext(DropdownContentContext);
+    useEffect(() => {
+        if (!open || !parentContent)
+            return;
+        const close = () => setOpen(false);
+        const prev = parentContent.closeOpenSubRef.current;
+        if (prev && prev !== close)
+            prev();
+        parentContent.closeOpenSubRef.current = close;
+        return () => {
+            if (parentContent.closeOpenSubRef.current === close) {
+                parentContent.closeOpenSubRef.current = null;
+            }
+        };
+    }, [open, parentContent, setOpen]);
+    return (_jsx(DropdownSubContext.Provider, { value: contextValue, children: children }));
+}
+/** @internal */
+DropdownSub.displayName = "DropdownSub";
+/**
+ * The submenu trigger. Must be rendered inside a {@link DropdownSub |
+ * `Dropdown.Sub`}; rendering it outside one throws a descriptive error.
+ *
+ * Renders a `<li role="menuitem">` with `aria-haspopup="menu"`,
+ * `aria-expanded`, and `aria-controls` wiring it to the sibling
+ * {@link DropdownSubContent | `Dropdown.SubContent`}. `asChild` is supported.
+ *
+ * Opens the submenu on click, the inline-forward arrow key, or pointer
+ * hover; all other keys bubble to the parent {@link DropdownContent |
+ * `Dropdown.Content`} so its roving focus and typeahead continue to work
+ * while a submenu is in play. The open key follows the resolved reading
+ * direction — `ArrowRight` in `"ltr"`, `ArrowLeft` in `"rtl"`. Hovering
+ * onto a sibling item in the parent menu closes the submenu — mirroring
+ * the keyboard contract where focus returning to the parent dismisses it.
+ *
+ * Disabled triggers receive `aria-disabled="true"` and ignore both click
+ * and the open arrow key.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.Sub>
+ *   <Dropdown.SubTrigger>Share</Dropdown.SubTrigger>
+ *   <Dropdown.SubContent>
+ *     <Dropdown.Item>Email link</Dropdown.Item>
+ *   </Dropdown.SubContent>
+ * </Dropdown.Sub>
+ * ```
+ */
+export function DropdownSubTrigger({ children, onClick, onKeyDown, disabled, asChild = false, ...rest }) {
+    const sub = useDropdownSubContext();
+    const { dir } = useDropdownContext();
+    const openKey = dir === "rtl" ? "ArrowLeft" : "ArrowRight";
+    const [hovered, setHovered] = useState(false);
+    const toggle = () => {
+        if (disabled)
+            return;
+        sub.setOpen(true);
+    };
+    const handleKeyDown = (event) => {
+        if (disabled)
+            return;
+        if (event.key !== openKey)
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        sub.setOpen(true);
+    };
+    const subTriggerProps = {
+        ...rest,
+        ref: sub.triggerRef,
+        role: "menuitem",
+        tabIndex: -1,
+        "aria-haspopup": "menu",
+        "aria-expanded": sub.open,
+        "aria-controls": sub.contentId,
+        "aria-disabled": disabled || undefined,
+        "data-highlighted": hovered || sub.open ? "" : undefined,
+        onClick: composeEventHandlers(onClick, toggle),
+        onKeyDown: composeEventHandlers(onKeyDown, handleKeyDown),
+        onMouseEnter: composeEventHandlers(rest.onMouseEnter, () => {
+            setHovered(true);
+            if (!disabled)
+                sub.setOpen(true);
+        }),
+        onMouseLeave: composeEventHandlers(rest.onMouseLeave, () => setHovered(false)),
+    };
+    if (asChild) {
+        return _jsx(Slot, { ...subTriggerProps, children: children });
+    }
+    return _jsx("li", { ...subTriggerProps, children: children });
+}
+/** @internal */
+DropdownSubTrigger.displayName = "DropdownSubTrigger";
+/**
+ * The submenu panel. Must be rendered inside a {@link DropdownSub |
+ * `Dropdown.Sub`}; rendering it outside one throws a descriptive error.
+ *
+ * Renders a `<menu role="menu" popover="auto">` by default; pass `asChild`
+ * to render any element with menu semantics. When the submenu opens, focus
+ * moves to its first enabled item.
+ *
+ * Presses of the inline-backward arrow key close the submenu and return
+ * focus to the {@link DropdownSubTrigger | `Dropdown.SubTrigger`} —
+ * `ArrowLeft` in `"ltr"`, `ArrowRight` in `"rtl"`. All other keys bubble
+ * to the parent {@link DropdownContent | `Dropdown.Content`} so arrow
+ * navigation and typeahead apply to the submenu's items.
+ *
+ * @extends HTMLMenuElement
+ *
+ * @example
+ * ```tsx
+ * <Dropdown.SubContent>
+ *   <Dropdown.Item>Project A</Dropdown.Item>
+ *   <Dropdown.Item>Project B</Dropdown.Item>
+ * </Dropdown.SubContent>
+ * ```
+ */
+export function DropdownSubContent({ children, onKeyDown, asChild = false, ...rest }) {
+    const sub = useDropdownSubContext();
+    const { dir } = useDropdownContext();
+    const closeKey = dir === "rtl" ? "ArrowRight" : "ArrowLeft";
+    const menuRef = useRef(null);
+    useEffect(() => {
+        const menu = menuRef.current;
+        if (sub.open) {
+            menu.showPopover();
+            const firstItem = menu.querySelector(MENUITEM_SELECTOR);
+            firstItem?.focus();
+        }
+        else {
+            try {
+                menu.hidePopover();
+            }
+            catch {
+                // already hidden — no-op
+            }
+        }
+    }, [sub.open]);
+    useEffect(() => {
+        const menu = menuRef.current;
+        const handleToggle = (event) => {
+            if (event.newState === "closed")
+                sub.setOpen(false);
+        };
+        menu.addEventListener("toggle", handleToggle);
+        return () => menu.removeEventListener("toggle", handleToggle);
+    }, [sub.setOpen]);
+    const handleKeyDown = (event) => {
+        if (event.key !== closeKey)
+            return;
+        event.preventDefault();
+        event.stopPropagation();
+        sub.setOpen(false);
+        sub.triggerRef.current?.focus();
+    };
+    const closeOpenSubRef = useRef(null);
+    const contentContextValue = useMemo(() => ({ closeOpenSubRef }), []);
+    const subContentProps = {
+        ...rest,
+        ref: menuRef,
+        id: sub.contentId,
+        role: "menu",
+        popover: "auto",
+        onKeyDown: composeEventHandlers(onKeyDown, handleKeyDown),
+    };
+    return (_jsx(DropdownContentContext.Provider, { value: contentContextValue, children: asChild ? (_jsx(Slot, { ...subContentProps, children: children })) : (_jsx("menu", { ...subContentProps, children: children })) }));
+}
+/** @internal */
+DropdownSubContent.displayName = "DropdownSubContent";
+/**
+ * Headless, accessible **Dropdown** menu — a compound component implementing the
+ * [WAI-ARIA menu-button pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu-button/)
+ * with submenus, checkbox and radio items, groups, labels and separators. Zero
+ * styles ship.
+ *
+ * The default export is the `Root`; sub-components are attached as static
+ * properties (`Dropdown.Trigger`, `Dropdown.Content`, ...).
+ */
+const DropdownCompound = Object.assign(DropdownRoot, {
+    Root: DropdownRoot,
+    Trigger: DropdownTrigger,
+    Content: DropdownContent,
+    Item: DropdownItem,
+    Separator: DropdownSeparator,
+    Group: DropdownGroup,
+    Label: DropdownLabel,
+    CheckboxItem: DropdownCheckboxItem,
+    RadioGroup: DropdownRadioGroup,
+    RadioItem: DropdownRadioItem,
+    ItemIndicator: DropdownItemIndicator,
+    Sub: DropdownSub,
+    SubTrigger: DropdownSubTrigger,
+    SubContent: DropdownSubContent,
+});
+/** @internal */
+DropdownCompound.displayName = "Dropdown";
+export { DropdownCompound as Dropdown };