@primitiv-ui/react 0.1.38 → 0.1.40

package/dist/ContextMenu/ContextMenu.js

@@ -0,0 +1,1005 @@
+"use client";
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useContext, useCallback, 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 { useControllableState } from "../hooks/index.js";
+import { Slot, composeEventHandlers } from "../Slot/index.js";
+import { ContextMenuContext, useContextMenuContext, } from "./ContextMenuContext.js";
+import { ContextMenuContentContext } from "./ContextMenuContentContext.js";
+import { ContextMenuGroupContext } from "./ContextMenuGroupContext.js";
+import { ContextMenuItemIndicatorContext } from "./ContextMenuItemIndicatorContext.js";
+import { ContextMenuRadioGroupContext } from "./ContextMenuRadioGroupContext.js";
+import { ContextMenuSubContext, useContextMenuSubContext, } from "./ContextMenuSubContext.js";
+import { MENUITEM_SELECTOR, TYPEAHEAD_RESET_MS } from "./constants.js";
+/**
+ * The root of a ContextMenu — owns the open state and the position the
+ * menu should open at, 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 ContextMenuRootProps.defaultOpen | `defaultOpen`}
+ *   (or omit it to start closed). The component owns and updates the open
+ *   state internally. Optional {@link ContextMenuRootProps.onOpenChange | `onOpenChange`}
+ *   observes transitions.
+ * - **Controlled** — pass {@link ContextMenuRootProps.open | `open`} *and*
+ *   {@link ContextMenuRootProps.onOpenChange | `onOpenChange`} together. The
+ *   parent owns the state; the component defers every transition back through
+ *   the callback.
+ *
+ * **Reading direction.** Pass {@link ContextMenuRootProps.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"`.
+ *
+ * Renders no DOM of its own — no extended host element — it is purely a
+ * context provider around its `children`.
+ *
+ * @example Uncontrolled
+ * ```tsx
+ * <ContextMenu.Root>
+ *   <ContextMenu.Trigger>
+ *     <div className="canvas">Right-click here</div>
+ *   </ContextMenu.Trigger>
+ *   <ContextMenu.Content>
+ *     <ContextMenu.Item onSelect={paste}>Paste</ContextMenu.Item>
+ *   </ContextMenu.Content>
+ * </ContextMenu.Root>
+ * ```
+ *
+ * @example Controlled
+ * ```tsx
+ * const [open, setOpen] = useState(false);
+ *
+ * <ContextMenu.Root open={open} onOpenChange={setOpen}>
+ *   ...
+ * </ContextMenu.Root>
+ * ```
+ */
+export function ContextMenuRoot({ defaultOpen = false, open: controlledOpen, onOpenChange, dir, children, }) {
+    const contentId = useId();
+    const triggerRef = useRef(null);
+    const [position, setPosition] = useState(null);
+    const inheritedDir = useDirection();
+    const resolvedDir = dir ?? inheritedDir;
+    const [open, setOpenBase] = useControllableState(controlledOpen, defaultOpen, onOpenChange);
+    const openRef = useRef(open);
+    useEffect(() => {
+        openRef.current = open;
+    });
+    const setOpen = useCallback((next) => {
+        if (openRef.current === next)
+            return;
+        openRef.current = next;
+        setOpenBase(next);
+    }, [setOpenBase]);
+    const contextValue = useMemo(() => ({
+        open,
+        setOpen,
+        position,
+        setPosition,
+        contentId,
+        triggerRef,
+        dir: resolvedDir,
+    }), [open, setOpen, position, contentId, resolvedDir]);
+    return (_jsx(ContextMenuContext.Provider, { value: contextValue, children: children }));
+}
+/** @internal */
+ContextMenuRoot.displayName = "ContextMenuRoot";
+/**
+ * Returns a callback that closes any direct-child sub-menu registered with
+ * the enclosing Content / SubContent. Items invoke this on mouseEnter so
+ * hovering a sibling dismisses an open sub, mirroring the keyboard contract.
+ */
+function useCloseSiblingSub() {
+    const content = useContext(ContextMenuContentContext);
+    return () => content?.closeOpenSubRef.current?.();
+}
+/**
+ * The area that responds to right-click. Renders a `<span>` by default
+ * (a non-button host so the wrapped content keeps its native semantics);
+ * pass `asChild` to render any element.
+ *
+ * When the user opens the platform context menu over this element (via
+ * right-click, long-press on touch, or the keyboard context-menu key),
+ * the native menu is suppressed and the ContextMenu opens, positioned at
+ * the pointer.
+ *
+ * A `disabled` Trigger ignores the gesture entirely, letting the native
+ * browser menu through. `data-disabled=""` and `data-state="closed"` are
+ * exposed for styling.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example Default `<span>` host
+ * ```tsx
+ * <ContextMenu.Trigger>
+ *   <div className="canvas">Right-click anywhere</div>
+ * </ContextMenu.Trigger>
+ * ```
+ *
+ * @example asChild — attach the gesture to any element
+ * ```tsx
+ * <ContextMenu.Trigger asChild>
+ *   <ImageCard src="..." alt="..." />
+ * </ContextMenu.Trigger>
+ * ```
+ */
+export function ContextMenuTrigger({ children, onContextMenu, asChild = false, disabled, ...rest }) {
+    const { setOpen, setPosition, triggerRef } = useContextMenuContext();
+    const handleContextMenu = (event) => {
+        if (disabled)
+            return;
+        event.preventDefault();
+        setPosition({ x: event.clientX, y: event.clientY });
+        setOpen(true);
+    };
+    const triggerProps = {
+        ...rest,
+        ref: triggerRef,
+        "data-disabled": disabled ? "" : undefined,
+        "data-state": disabled ? undefined : "closed",
+        onContextMenu: composeEventHandlers(onContextMenu, handleContextMenu),
+    };
+    if (asChild) {
+        return _jsx(Slot, { ...triggerProps, children: children });
+    }
+    return _jsx("span", { ...triggerProps, children: children });
+}
+/** @internal */
+ContextMenuTrigger.displayName = "ContextMenuTrigger";
+/**
+ * The menu panel rendered with the native HTML
+ * [Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API)
+ * in **manual** mode (`popover="manual"`) — no portal, no floating-ui. The
+ * browser still layers the menu via the top layer, but the component owns
+ * the close flow rather than the browser's light-dismiss algorithm.
+ *
+ * Manual mode is required because the right-click gesture's pointerdown
+ * fires before the popover exists; with `popover="auto"`, the browser
+ * treats the matching pointerup as an outside click and closes the menu
+ * the instant the user releases the button. Outside-click close and
+ * Escape are handled explicitly here instead.
+ *
+ * Renders a `<menu role="menu">` positioned at the pointer coordinates
+ * captured when the Trigger fired its `contextmenu` event. The cursor
+ * position is exposed twice on the element style: as explicit `left` /
+ * `top` insets (so the menu renders at the cursor with zero consumer
+ * CSS), and as `--primitiv-context-menu-x` / `--primitiv-context-menu-y`
+ * custom properties so consumer CSS can write `@position-try` fallbacks
+ * that flip the menu to the opposite side when it would overflow the
+ * viewport. Pass `asChild` to render any element with menu semantics.
+ *
+ * **Focus & keyboard.** On open, focus moves to the first enabled item.
+ * `ArrowDown` / `ArrowUp` move between items (wrapping), `Home` / `End`
+ * jump to the first / last, `Enter` / `Space` activate the focused item,
+ * `Escape` closes and returns focus to the Trigger, and any printable
+ * character starts a typeahead search (accumulated within a 500 ms window;
+ * repeating a character cycles items sharing that first letter). Disabled
+ * items are skipped throughout. `data-state="open" | "closed"` is exposed
+ * for state-driven styling.
+ *
+ * @extends HTMLMenuElement
+ *
+ * @example
+ * ```tsx
+ * <ContextMenu.Content>
+ *   <ContextMenu.Item onSelect={cut}>Cut</ContextMenu.Item>
+ *   <ContextMenu.Item onSelect={copy}>Copy</ContextMenu.Item>
+ *   <ContextMenu.Separator />
+ *   <ContextMenu.Item disabled>Archive</ContextMenu.Item>
+ * </ContextMenu.Content>
+ * ```
+ */
+export function ContextMenuContent({ children, style, onKeyDown, asChild = false, ...rest }) {
+    const { open, setOpen, position, contentId, triggerRef } = useContextMenuContext();
+    const menuRef = useRef(null);
+    const typeaheadRef = useRef({
+        query: "",
+        timer: null,
+    });
+    useEffect(() => {
+        const menu = menuRef.current;
+        if (open) {
+            menu.showPopover();
+            if (!menu.contains(document.activeElement)) {
+                const firstItem = menu.querySelector(MENUITEM_SELECTOR);
+                firstItem?.focus();
+            }
+        }
+        else {
+            try {
+                menu.hidePopover();
+            }
+            catch {
+                // already hidden — no-op
+            }
+        }
+    }, [open]);
+    useEffect(() => {
+        const menu = menuRef.current;
+        const handleToggle = (event) => {
+            if (event.newState === "closed")
+                setOpen(false);
+        };
+        menu.addEventListener("toggle", handleToggle);
+        return () => menu.removeEventListener("toggle", handleToggle);
+    }, [setOpen]);
+    useEffect(() => {
+        if (!open)
+            return;
+        const handleClick = (event) => {
+            const target = event.target;
+            if (triggerRef.current?.contains(target))
+                return;
+            if (target.closest?.("[popover]"))
+                return;
+            setOpen(false);
+        };
+        document.addEventListener("click", handleClick);
+        return () => document.removeEventListener("click", handleClick);
+    }, [open, setOpen, triggerRef]);
+    const handleKeyDown = (event) => {
+        const menu = menuRef.current;
+        const focused = document.activeElement;
+        const scope = focused?.closest("[popover]") ?? menu;
+        const items = Array.from(scope.querySelectorAll(MENUITEM_SELECTOR)).filter((el) => el.closest("[popover]") === scope);
+        if (items.length === 0)
+            return;
+        const currentIndex = items.indexOf(document.activeElement);
+        let nextIndex = null;
+        if (event.key === "ArrowDown") {
+            nextIndex = (currentIndex + 1) % items.length;
+        }
+        else if (event.key === "ArrowUp") {
+            nextIndex = currentIndex <= 0 ? items.length - 1 : currentIndex - 1;
+        }
+        else if (event.key === "Home") {
+            nextIndex = 0;
+        }
+        else if (event.key === "End") {
+            nextIndex = items.length - 1;
+        }
+        if (nextIndex !== null) {
+            event.preventDefault();
+            items[nextIndex].focus();
+            return;
+        }
+        if (event.key === "Enter" || event.key === " ") {
+            if (currentIndex < 0)
+                return;
+            event.preventDefault();
+            items[currentIndex].click();
+            return;
+        }
+        if (event.key === "Escape") {
+            event.preventDefault();
+            setOpen(false);
+            triggerRef.current?.focus();
+            return;
+        }
+        if (event.key.length === 1 && event.key !== " ") {
+            const state = typeaheadRef.current;
+            if (state.timer !== null)
+                window.clearTimeout(state.timer);
+            state.query = (state.query + event.key).toLowerCase();
+            state.timer = window.setTimeout(() => {
+                state.query = "";
+                state.timer = null;
+            }, TYPEAHEAD_RESET_MS);
+            const isRepeat = state.query.length > 1 &&
+                state.query.split("").every((c) => c === state.query[0]);
+            const searchQuery = isRepeat ? state.query[0] : state.query;
+            const startIndex = currentIndex < 0 ? 0 : currentIndex;
+            const offset = searchQuery.length === 1 || isRepeat ? 1 : 0;
+            for (let i = 0; i < items.length; i++) {
+                const index = (startIndex + offset + i) % items.length;
+                const text = items[index].textContent.trim().toLowerCase();
+                if (text.startsWith(searchQuery)) {
+                    event.preventDefault();
+                    items[index].focus();
+                    return;
+                }
+            }
+        }
+    };
+    // Both `left`/`top` and `--primitiv-context-menu-x`/`-y` are set: the
+    // explicit insets position the menu at the cursor by default, and the
+    // custom properties let consumer CSS write `@position-try` fallbacks
+    // that flip the menu (e.g. `right: calc(100vw - var(--primitiv-context-menu-x))`)
+    // when the primary position would overflow the viewport.
+    const positionedStyle = position
+        ? {
+            position: "fixed",
+            left: position.x,
+            top: position.y,
+            margin: 0,
+            "--primitiv-context-menu-x": `${position.x}px`,
+            "--primitiv-context-menu-y": `${position.y}px`,
+            ...style,
+        }
+        : style;
+    const closeOpenSubRef = useRef(null);
+    const contentContextValue = useMemo(() => ({ closeOpenSubRef }), []);
+    // Cascade-close: when our own popover closes, also close any registered
+    // direct-child sub so its state doesn't leak into the next open. Without
+    // this, clicking an item inside a SubContent closes Root but leaves the
+    // child Sub.open=true, which then briefly drives a stale popover render
+    // the next time the menu opens. Each SubContent runs the same cascade
+    // against its own child sub, so the chain unwinds bottom-up.
+    useEffect(() => {
+        if (!open)
+            closeOpenSubRef.current?.();
+    }, [open]);
+    const contentProps = {
+        ...rest,
+        ref: menuRef,
+        id: contentId,
+        role: "menu",
+        // Manual mode: the right-click gesture's pointerdown fires before the
+        // popover opens, so popover="auto"'s light-dismiss algorithm treats
+        // the matching pointerup as an outside click and closes the menu the
+        // instant the user releases the button. We close on outside click
+        // (document listener below) and Escape (key handler) ourselves.
+        popover: "manual",
+        "data-state": (open ? "open" : "closed"),
+        style: positionedStyle,
+        onKeyDown: composeEventHandlers(onKeyDown, handleKeyDown),
+    };
+    return (_jsx(ContextMenuContentContext.Provider, { value: contentContextValue, children: asChild ? (_jsx(Slot, { ...contentProps, children: children })) : (_jsx("menu", { ...contentProps, children: children })) }));
+}
+/** @internal */
+ContextMenuContent.displayName = "ContextMenuContent";
+/**
+ * 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 ContextMenuItemProps.onSelect | `onSelect`} with a cancellable
+ * `Event`. The menu auto-closes after selection; call
+ * `event.preventDefault()` inside `onSelect` to keep it open.
+ *
+ * Disabled items receive `aria-disabled="true"` and no-op on activation;
+ * arrow navigation and typeahead skip them. `data-highlighted=""` is
+ * present while the pointer hovers the item.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <ContextMenu.Item onSelect={() => rename()}>Rename</ContextMenu.Item>
+ * <ContextMenu.Item disabled>Archive (coming soon)</ContextMenu.Item>
+ * ```
+ *
+ * @example asChild — render a link with menuitem semantics
+ * ```tsx
+ * <ContextMenu.Item asChild>
+ *   <a href="/rename">Rename</a>
+ * </ContextMenu.Item>
+ * ```
+ */
+export function ContextMenuItem({ children, onClick, onSelect, disabled, asChild = false, ...rest }) {
+    const { setOpen } = useContextMenuContext();
+    const closeSiblingSub = useCloseSiblingSub();
+    const [highlighted, setHighlighted] = useState(false);
+    const handleClick = () => {
+        if (disabled)
+            return;
+        const event = new Event("contextmenu.select", { cancelable: true });
+        onSelect?.(event);
+        if (!event.defaultPrevented) {
+            setOpen(false);
+        }
+    };
+    const itemProps = {
+        ...rest,
+        role: "menuitem",
+        tabIndex: -1,
+        "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)),
+    };
+    if (asChild) {
+        return _jsx(Slot, { ...itemProps, children: children });
+    }
+    return _jsx("li", { ...itemProps, children: children });
+}
+/** @internal */
+ContextMenuItem.displayName = "ContextMenuItem";
+/**
+ * A visual separator between groups of items. Renders a `<li role="separator">`
+ * by default. Non-interactive — skipped by focus, arrow navigation, and
+ * typeahead.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <ContextMenu.Item>Copy</ContextMenu.Item>
+ * <ContextMenu.Separator />
+ * <ContextMenu.Item>Delete</ContextMenu.Item>
+ * ```
+ */
+export function ContextMenuSeparator({ asChild = false, children, ...rest }) {
+    const separatorProps = { ...rest, role: "separator" };
+    if (asChild) {
+        return _jsx(Slot, { ...separatorProps, children: children });
+    }
+    return _jsx("li", { ...separatorProps });
+}
+/** @internal */
+ContextMenuSeparator.displayName = "ContextMenuSeparator";
+/**
+ * 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 ContextMenuLabel |
+ * `ContextMenu.Label`}, wired automatically via `aria-labelledby`.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <ContextMenu.Group>
+ *   <ContextMenu.Label>Edit</ContextMenu.Label>
+ *   <ContextMenu.Item>Undo</ContextMenu.Item>
+ *   <ContextMenu.Item>Redo</ContextMenu.Item>
+ * </ContextMenu.Group>
+ * ```
+ */
+export function ContextMenuGroup({ children, asChild = false, ...rest }) {
+    const labelId = useId();
+    const contextValue = useMemo(() => ({ labelId }), [labelId]);
+    const groupProps = {
+        ...rest,
+        role: "group",
+        "aria-labelledby": labelId,
+    };
+    return (_jsx(ContextMenuGroupContext.Provider, { value: contextValue, children: asChild ? (_jsx(Slot, { ...groupProps, children: children })) : (_jsx("li", { ...groupProps, children: _jsx("ul", { role: "none", children: children }) })) }));
+}
+/** @internal */
+ContextMenuGroup.displayName = "ContextMenuGroup";
+/**
+ * A non-interactive label, typically used inside a {@link ContextMenuGroup |
+ * `ContextMenu.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. A caller-supplied `id` takes
+ * precedence over the auto-generated one.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <ContextMenu.Group>
+ *   <ContextMenu.Label>View</ContextMenu.Label>
+ *   <ContextMenu.CheckboxItem>Show grid</ContextMenu.CheckboxItem>
+ * </ContextMenu.Group>
+ * ```
+ */
+export function ContextMenuLabel({ id, children, asChild = false, ...rest }) {
+    const group = useContext(ContextMenuGroupContext);
+    const labelProps = { ...rest, id: id ?? group?.labelId };
+    if (asChild) {
+        return _jsx(Slot, { ...labelProps, children: children });
+    }
+    return _jsx("li", { ...labelProps, children: children });
+}
+/** @internal */
+ContextMenuLabel.displayName = "ContextMenuLabel";
+/**
+ * A toggleable menu item. Renders a `<li role="menuitemcheckbox">` with
+ * `aria-checked` reflecting the current state. 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.
+ *
+ * Activation (click) toggles the checked state, then fires
+ * {@link ContextMenuCheckboxItemProps.onSelect | `onSelect`} with a
+ * cancellable `Event`. Call `event.preventDefault()` to keep the menu open.
+ *
+ * Supports both state modes: uncontrolled via
+ * {@link ContextMenuCheckboxItemUncontrolledProps.defaultChecked | `defaultChecked`},
+ * or controlled via
+ * {@link ContextMenuCheckboxItemControlledProps.checked | `checked`} +
+ * {@link ContextMenuCheckboxItemControlledProps.onCheckedChange | `onCheckedChange`}.
+ * Render a {@link ContextMenuItemIndicator | `ContextMenu.ItemIndicator`}
+ * inside it for the visible mark.
+ *
+ * Disabled items receive `aria-disabled="true"` and no-op on activation.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example Uncontrolled, with an indicator
+ * ```tsx
+ * <ContextMenu.CheckboxItem defaultChecked>
+ *   <ContextMenu.ItemIndicator><CheckIcon /></ContextMenu.ItemIndicator>
+ *   Show grid
+ * </ContextMenu.CheckboxItem>
+ * ```
+ *
+ * @example Controlled, kept open for rapid toggling
+ * ```tsx
+ * <ContextMenu.CheckboxItem
+ *   checked={showRuler}
+ *   onCheckedChange={setShowRuler}
+ *   onSelect={(event) => event.preventDefault()}
+ * >
+ *   Show ruler
+ * </ContextMenu.CheckboxItem>
+ * ```
+ */
+export function ContextMenuCheckboxItem({ children, onClick, onSelect, disabled, defaultChecked, checked: controlledChecked, onCheckedChange, asChild = false, ...rest }) {
+    const { setOpen } = useContextMenuContext();
+    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("contextmenu.select", { cancelable: true });
+        onSelect?.(event);
+        if (!event.defaultPrevented) {
+            setOpen(false);
+        }
+    };
+    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(ContextMenuItemIndicatorContext.Provider, { value: indicatorContextValue, children: content }));
+}
+/** @internal */
+ContextMenuCheckboxItem.displayName = "ContextMenuCheckboxItem";
+/**
+ * The visible mark (usually a checkmark) rendered inside a
+ * {@link ContextMenuCheckboxItem | `ContextMenu.CheckboxItem`} (or radio item).
+ * Must be a descendant of one; rendering it anywhere else throws a
+ * descriptive error.
+ *
+ * Renders a `<span>` by default. Exposes `data-state` reflecting the parent
+ * item's live state: `"checked"`, `"unchecked"`, or `"indeterminate"`.
+ *
+ * By default the indicator unmounts when its parent is unchecked. Pass
+ * {@link ContextMenuItemIndicatorProps.forceMount | `forceMount`} to keep
+ * the DOM node mounted in both states for animation use cases.
+ *
+ * @extends HTMLSpanElement
+ *
+ * @example Compose onto an icon
+ * ```tsx
+ * <ContextMenu.CheckboxItem checked={bookmarked} onCheckedChange={setBookmarked}>
+ *   <ContextMenu.ItemIndicator asChild>
+ *     <CheckIcon aria-hidden />
+ *   </ContextMenu.ItemIndicator>
+ *   Bookmark
+ * </ContextMenu.CheckboxItem>
+ * ```
+ *
+ * @example forceMount for CSS-driven transitions
+ * ```tsx
+ * <ContextMenu.ItemIndicator forceMount>
+ *   <CheckIcon />
+ * </ContextMenu.ItemIndicator>
+ * ```
+ */
+export function ContextMenuItemIndicator({ children, asChild = false, forceMount = false, ...rest }) {
+    const context = useContext(ContextMenuItemIndicatorContext);
+    if (!context) {
+        throw new Error("ContextMenu.ItemIndicator must be rendered inside a <ContextMenu.CheckboxItem> or <ContextMenu.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 */
+ContextMenuItemIndicator.displayName = "ContextMenuItemIndicator";
+/**
+ * A single-selection group of menu items. Children must be
+ * {@link ContextMenuRadioItem | `ContextMenu.RadioItem`} elements. Renders a
+ * `<li role="group">` wrapping `<ul role="none">`.
+ *
+ * Owns the selected value: uncontrolled via
+ * {@link ContextMenuRadioGroupUncontrolledProps.defaultValue | `defaultValue`},
+ * or controlled via
+ * {@link ContextMenuRadioGroupControlledProps.value | `value`} +
+ * {@link ContextMenuRadioGroupControlledProps.onValueChange | `onValueChange`}.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <ContextMenu.RadioGroup defaultValue="system">
+ *   <ContextMenu.RadioItem value="light">Light</ContextMenu.RadioItem>
+ *   <ContextMenu.RadioItem value="dark">Dark</ContextMenu.RadioItem>
+ *   <ContextMenu.RadioItem value="system">Match system</ContextMenu.RadioItem>
+ * </ContextMenu.RadioGroup>
+ * ```
+ */
+export function ContextMenuRadioGroup({ 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(ContextMenuRadioGroupContext.Provider, { value: contextValue, children: asChild ? (_jsx(Slot, { ...groupProps, children: children })) : (_jsx("li", { ...groupProps, children: _jsx("ul", { role: "none", children: children }) })) }));
+}
+/** @internal */
+ContextMenuRadioGroup.displayName = "ContextMenuRadioGroup";
+/**
+ * A single radio choice. Must be rendered inside a {@link ContextMenuRadioGroup |
+ * `ContextMenu.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.
+ *
+ * Activation (click) selects this item, updating the group's value, then fires
+ * {@link ContextMenuRadioItemProps.onSelect | `onSelect`} with a cancellable
+ * `Event`. Call `event.preventDefault()` to keep the menu open.
+ *
+ * Disabled items receive `aria-disabled="true"` and no-op on activation.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <ContextMenu.RadioItem value="dark">
+ *   <ContextMenu.ItemIndicator><DotIcon /></ContextMenu.ItemIndicator>
+ *   Dark
+ * </ContextMenu.RadioItem>
+ * ```
+ */
+export function ContextMenuRadioItem({ children, onClick, onSelect, disabled, value: itemValue, asChild = false, ...rest }) {
+    const { setOpen } = useContextMenuContext();
+    const closeSiblingSub = useCloseSiblingSub();
+    const [highlighted, setHighlighted] = useState(false);
+    const group = useContext(ContextMenuRadioGroupContext);
+    if (!group) {
+        throw new Error("ContextMenu.RadioItem must be rendered inside a <ContextMenu.RadioGroup>.");
+    }
+    const checked = group.value === itemValue;
+    const handleClick = () => {
+        if (disabled)
+            return;
+        group.select(itemValue);
+        const event = new Event("contextmenu.select", { cancelable: true });
+        onSelect?.(event);
+        if (!event.defaultPrevented) {
+            setOpen(false);
+        }
+    };
+    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(ContextMenuItemIndicatorContext.Provider, { value: indicatorContextValue, children: content }));
+}
+/** @internal */
+ContextMenuRadioItem.displayName = "ContextMenuRadioItem";
+/**
+ * A submenu boundary. Wrap a {@link ContextMenuSubTrigger | `ContextMenu.SubTrigger`}
+ * and its {@link ContextMenuSubContent | `ContextMenu.SubContent`} in a
+ * `ContextMenu.Sub` to establish an independent open state for the nested
+ * menu. Supports uncontrolled (`defaultOpen`) and controlled (`open` +
+ * `onOpenChange`) modes.
+ *
+ * Renders no DOM of its own — no extended host element — it is purely a
+ * context boundary around the SubTrigger / SubContent pair.
+ *
+ * @example
+ * ```tsx
+ * <ContextMenu.Sub>
+ *   <ContextMenu.SubTrigger>Share</ContextMenu.SubTrigger>
+ *   <ContextMenu.SubContent>
+ *     <ContextMenu.Item>Email</ContextMenu.Item>
+ *     <ContextMenu.Item>Copy link</ContextMenu.Item>
+ *   </ContextMenu.SubContent>
+ * </ContextMenu.Sub>
+ * ```
+ */
+export function ContextMenuSub({ defaultOpen, open: controlledOpen, onOpenChange, children, }) {
+    const contentId = useId();
+    const triggerRef = useRef(null);
+    const [open, setOpenBase] = useControllableState(controlledOpen, defaultOpen ?? false, onOpenChange);
+    const openRef = useRef(open);
+    useEffect(() => {
+        openRef.current = open;
+    });
+    const setOpen = useCallback((next) => {
+        if (openRef.current === next)
+            return;
+        openRef.current = next;
+        setOpenBase(next);
+    }, [setOpenBase]);
+    const contextValue = useMemo(() => ({ open, setOpen, contentId, triggerRef }), [open, setOpen, contentId]);
+    // Register with the enclosing Content/SubContent so sibling items can close
+    // this sub on hover (mirroring the keyboard behaviour where focus returning
+    // to the parent dismisses it). If another sibling sub is already
+    // registered as open, close it first so a hover-to-open transition onto our
+    // SubTrigger supplants the prior sub rather than stacking it.
+    const parentContent = useContext(ContextMenuContentContext);
+    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(ContextMenuSubContext.Provider, { value: contextValue, children: children }));
+}
+/** @internal */
+ContextMenuSub.displayName = "ContextMenuSub";
+/**
+ * The submenu trigger. Must be rendered inside a {@link ContextMenuSub |
+ * `ContextMenu.Sub`}.
+ *
+ * Renders a `<li role="menuitem">` with `aria-haspopup="menu"`,
+ * `aria-expanded`, and `aria-controls` wiring it to the sibling
+ * {@link ContextMenuSubContent | `ContextMenu.SubContent`}.
+ *
+ * Opens the submenu on click, the inline-forward arrow key, or pointer
+ * hover. The open key follows the resolved reading direction —
+ * `ArrowRight` in `"ltr"`, `ArrowLeft` in `"rtl"`. Disabled triggers
+ * ignore both click and the open arrow key. `data-highlighted=""` is
+ * present while hovered or while its submenu is open.
+ *
+ * @extends HTMLLIElement
+ *
+ * @example
+ * ```tsx
+ * <ContextMenu.Sub>
+ *   <ContextMenu.SubTrigger>More tools</ContextMenu.SubTrigger>
+ *   <ContextMenu.SubContent>...</ContextMenu.SubContent>
+ * </ContextMenu.Sub>
+ * ```
+ */
+export function ContextMenuSubTrigger({ children, onClick, onKeyDown, disabled, asChild = false, ...rest }) {
+    const sub = useContextMenuSubContext();
+    const { dir } = useContextMenuContext();
+    const openKey = dir === "rtl" ? "ArrowLeft" : "ArrowRight";
+    const closeSiblingSub = useCloseSiblingSub();
+    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);
+            closeSiblingSub();
+            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 */
+ContextMenuSubTrigger.displayName = "ContextMenuSubTrigger";
+/**
+ * The submenu panel. Must be rendered inside a {@link ContextMenuSub |
+ * `ContextMenu.Sub`}.
+ *
+ * Renders a `<menu role="menu" popover="auto">` by default. When the submenu
+ * opens, focus moves to its first enabled item. The inline-backward arrow
+ * key closes the submenu and returns focus to the SubTrigger —
+ * `ArrowLeft` in `"ltr"`, `ArrowRight` in `"rtl"`.
+ *
+ * Unlike {@link ContextMenuContent | `ContextMenu.Content`}, the submenu
+ * panel uses `popover="auto"` — it is opened programmatically and nests
+ * inside the already-open manual root popover.
+ *
+ * @extends HTMLMenuElement
+ *
+ * @example
+ * ```tsx
+ * <ContextMenu.SubContent>
+ *   <ContextMenu.Item>Email</ContextMenu.Item>
+ *   <ContextMenu.Item>Copy link</ContextMenu.Item>
+ * </ContextMenu.SubContent>
+ * ```
+ */
+export function ContextMenuSubContent({ children, onKeyDown, asChild = false, ...rest }) {
+    const sub = useContextMenuSubContext();
+    const { dir } = useContextMenuContext();
+    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 }), []);
+    // Cascade-close — see the matching effect on ContextMenuContent.
+    useEffect(() => {
+        if (!sub.open)
+            closeOpenSubRef.current?.();
+    }, [sub.open]);
+    const subContentProps = {
+        ...rest,
+        ref: menuRef,
+        id: sub.contentId,
+        role: "menu",
+        popover: "auto",
+        onKeyDown: composeEventHandlers(onKeyDown, handleKeyDown),
+    };
+    return (_jsx(ContextMenuContentContext.Provider, { value: contentContextValue, children: asChild ? (_jsx(Slot, { ...subContentProps, children: children })) : (_jsx("menu", { ...subContentProps, children: children })) }));
+}
+/** @internal */
+ContextMenuSubContent.displayName = "ContextMenuSubContent";
+/**
+ * Headless, accessible **ContextMenu** — a compound component implementing the
+ * [WAI-ARIA menu pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu/) opened
+ * by a right-click (or long-press) on its trigger, with submenus, checkbox and
+ * radio items, groups, labels and separators. Zero styles ship.
+ *
+ * `ContextMenu` is both callable (it is an alias of
+ * {@link ContextMenuRoot | `ContextMenu.Root`}) and carries its
+ * sub-components as static properties. Prefer the namespaced form in
+ * application code for readability and grep-ability:
+ *
+ * - {@link ContextMenuRoot | `ContextMenu.Root`} — open-state owner and direction provider (no DOM).
+ * - {@link ContextMenuTrigger | `ContextMenu.Trigger`} — the right-click target (`<span>`).
+ * - {@link ContextMenuContent | `ContextMenu.Content`} — the `role="menu"` popover panel.
+ * - {@link ContextMenuItem | `ContextMenu.Item`} — a `role="menuitem"` row.
+ * - {@link ContextMenuCheckboxItem | `ContextMenu.CheckboxItem`} — a tri-state `role="menuitemcheckbox"`.
+ * - {@link ContextMenuRadioGroup | `ContextMenu.RadioGroup`} — single-selection container.
+ * - {@link ContextMenuRadioItem | `ContextMenu.RadioItem`} — a `role="menuitemradio"` choice.
+ * - {@link ContextMenuItemIndicator | `ContextMenu.ItemIndicator`} — the checked-state mark.
+ * - {@link ContextMenuGroup | `ContextMenu.Group`} — a `role="group"` of related items.
+ * - {@link ContextMenuLabel | `ContextMenu.Label`} — a non-interactive group caption.
+ * - {@link ContextMenuSeparator | `ContextMenu.Separator`} — a `role="separator"` divider.
+ * - {@link ContextMenuSub | `ContextMenu.Sub`} — a submenu boundary (no DOM).
+ * - {@link ContextMenuSubTrigger | `ContextMenu.SubTrigger`} — opens a submenu.
+ * - {@link ContextMenuSubContent | `ContextMenu.SubContent`} — the submenu panel.
+ *
+ * @example Minimal usage
+ * ```tsx
+ * import { ContextMenu } from "@primitiv-ui/react";
+ *
+ * <ContextMenu.Root>
+ *   <ContextMenu.Trigger>
+ *     <div className="canvas">Right-click anywhere</div>
+ *   </ContextMenu.Trigger>
+ *   <ContextMenu.Content>
+ *     <ContextMenu.Item onSelect={paste}>Paste</ContextMenu.Item>
+ *     <ContextMenu.Separator />
+ *     <ContextMenu.Item disabled>Archive</ContextMenu.Item>
+ *   </ContextMenu.Content>
+ * </ContextMenu.Root>
+ * ```
+ *
+ * @see {@link ContextMenuRoot} for state modes and reading direction.
+ * @see {@link ContextMenuContent} for the popover, positioning, and keyboard model.
+ * @see {@link ContextMenuCheckboxItem} and {@link ContextMenuRadioGroup} for stateful items.
+ * @see {@link ContextMenuSub} for submenus.
+ */
+const ContextMenuCompound = Object.assign(ContextMenuRoot, {
+    Root: ContextMenuRoot,
+    Trigger: ContextMenuTrigger,
+    Content: ContextMenuContent,
+    Item: ContextMenuItem,
+    Separator: ContextMenuSeparator,
+    Group: ContextMenuGroup,
+    Label: ContextMenuLabel,
+    CheckboxItem: ContextMenuCheckboxItem,
+    ItemIndicator: ContextMenuItemIndicator,
+    RadioGroup: ContextMenuRadioGroup,
+    RadioItem: ContextMenuRadioItem,
+    Sub: ContextMenuSub,
+    SubTrigger: ContextMenuSubTrigger,
+    SubContent: ContextMenuSubContent,
+});
+/** @internal */
+ContextMenuCompound.displayName = "ContextMenu";
+export { ContextMenuCompound as ContextMenu };