@primitiv-ui/react 0.1.38 → 0.1.39

package/src/ContextMenu/ContextMenu.tsx

@@ -1,1296 +0,0 @@
-import {
-  useContext,
-  useCallback,
-  useEffect,
-  useId,
-  useMemo,
-  useRef,
-  useState,
-} from "react";
-import type { ReactElement } from "react";
-
-import { useCheckboxRoot } from "../Checkbox/hooks/index.ts";
-import { useDirection } from "../DirectionProvider/index.ts";
-import { useRadioGroupRoot } from "../RadioGroup/hooks/index.ts";
-import { useControllableState } from "../hooks/index.ts";
-import { Slot, composeEventHandlers } from "../Slot/index.ts";
-
-import {
-  ContextMenuContext,
-  ContextMenuPosition,
-  useContextMenuContext,
-} from "./ContextMenuContext";
-import { ContextMenuContentContext } from "./ContextMenuContentContext";
-import { ContextMenuGroupContext } from "./ContextMenuGroupContext";
-import { ContextMenuItemIndicatorContext } from "./ContextMenuItemIndicatorContext";
-import { ContextMenuRadioGroupContext } from "./ContextMenuRadioGroupContext";
-import {
-  ContextMenuSubContext,
-  useContextMenuSubContext,
-} from "./ContextMenuSubContext";
-import {
-  ContextMenuCheckboxItemProps,
-  ContextMenuContentProps,
-  ContextMenuGroupProps,
-  ContextMenuItemIndicatorProps,
-  ContextMenuItemProps,
-  ContextMenuLabelProps,
-  ContextMenuRadioGroupProps,
-  ContextMenuRadioItemProps,
-  ContextMenuRootProps,
-  ContextMenuSeparatorProps,
-  ContextMenuSubContentProps,
-  ContextMenuSubProps,
-  ContextMenuSubTriggerProps,
-  ContextMenuTriggerProps,
-} from "./types";
-import { MENUITEM_SELECTOR, TYPEAHEAD_RESET_MS } from "./constants";
-
-/**
- * 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,
-}: ContextMenuRootProps): ReactElement {
-  const contentId = useId();
-  const triggerRef = useRef<HTMLElement | null>(null);
-  const [position, setPosition] = useState<ContextMenuPosition | null>(null);
-  const inheritedDir = useDirection();
-  const resolvedDir = dir ?? inheritedDir;
-  const [open, setOpenBase] = useControllableState<boolean>(
-    controlledOpen,
-    defaultOpen,
-    onOpenChange,
-  );
-  const openRef = useRef(open);
-  useEffect(() => {
-    openRef.current = open;
-  });
-
-  const setOpen = useCallback(
-    (next: boolean) => {
-      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 (
-    <ContextMenuContext.Provider value={contextValue}>
-      {children}
-    </ContextMenuContext.Provider>
-  );
-}
-
-/** @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
-}: ContextMenuTriggerProps): ReactElement {
-  const { setOpen, setPosition, triggerRef } = useContextMenuContext();
-
-  const handleContextMenu = (event: React.MouseEvent<HTMLElement>) => {
-    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" as const),
-    onContextMenu: composeEventHandlers(onContextMenu, handleContextMenu),
-  };
-
-  if (asChild) {
-    return <Slot {...triggerProps}>{children}</Slot>;
-  }
-
-  return <span {...triggerProps}>{children}</span>;
-}
-
-/** @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
-}: ContextMenuContentProps): ReactElement {
-  const { open, setOpen, position, contentId, triggerRef } =
-    useContextMenuContext();
-  const menuRef = useRef<HTMLMenuElement | null>(null);
-  const typeaheadRef = useRef<{ query: string; timer: number | null }>({
-    query: "",
-    timer: null,
-  });
-
-  useEffect(() => {
-    const menu = menuRef.current!;
-    if (open) {
-      menu.showPopover();
-      if (!menu.contains(document.activeElement)) {
-        const firstItem = menu.querySelector<HTMLElement>(MENUITEM_SELECTOR);
-        firstItem?.focus();
-      }
-    } else {
-      try {
-        menu.hidePopover();
-      } catch {
-        // already hidden — no-op
-      }
-    }
-  }, [open]);
-
-  useEffect(() => {
-    const menu = menuRef.current!;
-    const handleToggle = (event: Event) => {
-      if ((event as ToggleEvent).newState === "closed") setOpen(false);
-    };
-    menu.addEventListener("toggle", handleToggle);
-    return () => menu.removeEventListener("toggle", handleToggle);
-  }, [setOpen]);
-
-  useEffect(() => {
-    if (!open) return;
-    const handleClick = (event: MouseEvent) => {
-      const target = event.target as Element;
-      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: React.KeyboardEvent<HTMLMenuElement>) => {
-    const menu = menuRef.current!;
-    const focused = document.activeElement as HTMLElement | null;
-    const scope = (focused?.closest("[popover]") as HTMLElement | null) ?? menu;
-    const items = Array.from(
-      scope.querySelectorAll<HTMLElement>(MENUITEM_SELECTOR),
-    ).filter((el) => el.closest("[popover]") === scope);
-    if (items.length === 0) return;
-    const currentIndex = items.indexOf(document.activeElement as HTMLElement);
-
-    let nextIndex: number | null = 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" as const,
-        left: position.x,
-        top: position.y,
-        margin: 0,
-        "--primitiv-context-menu-x": `${position.x}px`,
-        "--primitiv-context-menu-y": `${position.y}px`,
-        ...style,
-      } as React.CSSProperties)
-    : style;
-
-  const closeOpenSubRef = useRef<(() => void) | null>(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" as const,
-    // 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" as const,
-    "data-state": (open ? "open" : "closed") as "open" | "closed",
-    style: positionedStyle,
-    onKeyDown: composeEventHandlers(onKeyDown, handleKeyDown),
-  };
-
-  return (
-    <ContextMenuContentContext.Provider value={contentContextValue}>
-      {asChild ? (
-        <Slot {...contentProps}>{children}</Slot>
-      ) : (
-        <menu {...contentProps}>{children}</menu>
-      )}
-    </ContextMenuContentContext.Provider>
-  );
-}
-
-/** @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
-}: ContextMenuItemProps): ReactElement {
-  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" as const,
-    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 <Slot {...itemProps}>{children}</Slot>;
-  }
-
-  return <li {...itemProps}>{children}</li>;
-}
-
-/** @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
-}: ContextMenuSeparatorProps): ReactElement {
-  const separatorProps = { ...rest, role: "separator" as const };
-
-  if (asChild) {
-    return <Slot {...separatorProps}>{children}</Slot>;
-  }
-
-  return <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
-}: ContextMenuGroupProps): ReactElement {
-  const labelId = useId();
-  const contextValue = useMemo(() => ({ labelId }), [labelId]);
-  const groupProps = {
-    ...rest,
-    role: "group" as const,
-    "aria-labelledby": labelId,
-  };
-
-  return (
-    <ContextMenuGroupContext.Provider value={contextValue}>
-      {asChild ? (
-        <Slot {...groupProps}>{children}</Slot>
-      ) : (
-        <li {...groupProps}>
-          <ul role="none">{children}</ul>
-        </li>
-      )}
-    </ContextMenuGroupContext.Provider>
-  );
-}
-
-/** @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
-}: ContextMenuLabelProps): ReactElement {
-  const group = useContext(ContextMenuGroupContext);
-  const labelProps = { ...rest, id: id ?? group?.labelId };
-
-  if (asChild) {
-    return <Slot {...labelProps}>{children}</Slot>;
-  }
-
-  return <li {...labelProps}>{children}</li>;
-}
-
-/** @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
-}: ContextMenuCheckboxItemProps): ReactElement {
-  const { setOpen } = useContextMenuContext();
-  const closeSiblingSub = useCloseSiblingSub();
-  const [highlighted, setHighlighted] = useState(false);
-  const { checked, toggle } = useCheckboxRoot({
-    defaultChecked,
-    checked: controlledChecked,
-    onCheckedChange,
-  });
-  const ariaChecked: "mixed" | "true" | "false" =
-    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" as const,
-    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 ? (
-    <Slot {...itemProps}>{children}</Slot>
-  ) : (
-    <li {...itemProps}>{children}</li>
-  );
-
-  return (
-    <ContextMenuItemIndicatorContext.Provider value={indicatorContextValue}>
-      {content}
-    </ContextMenuItemIndicatorContext.Provider>
-  );
-}
-
-/** @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
-}: ContextMenuItemIndicatorProps): ReactElement | null {
-  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 <Slot {...indicatorProps}>{children}</Slot>;
-  }
-
-  return <span {...indicatorProps}>{children}</span>;
-}
-
-/** @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
-}: ContextMenuRadioGroupProps): ReactElement {
-  const { value, select } = useRadioGroupRoot({
-    defaultValue,
-    value: controlledValue,
-    onValueChange,
-  });
-  const contextValue = useMemo(() => ({ value, select }), [value, select]);
-  const groupProps = { ...rest, role: "group" as const };
-
-  return (
-    <ContextMenuRadioGroupContext.Provider value={contextValue}>
-      {asChild ? (
-        <Slot {...groupProps}>{children}</Slot>
-      ) : (
-        <li {...groupProps}>
-          <ul role="none">{children}</ul>
-        </li>
-      )}
-    </ContextMenuRadioGroupContext.Provider>
-  );
-}
-
-/** @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
-}: ContextMenuRadioItemProps): ReactElement {
-  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" as const,
-    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 ? (
-    <Slot {...itemProps}>{children}</Slot>
-  ) : (
-    <li {...itemProps}>{children}</li>
-  );
-
-  return (
-    <ContextMenuItemIndicatorContext.Provider value={indicatorContextValue}>
-      {content}
-    </ContextMenuItemIndicatorContext.Provider>
-  );
-}
-
-/** @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,
-}: ContextMenuSubProps): ReactElement {
-  const contentId = useId();
-  const triggerRef = useRef<HTMLLIElement | null>(null);
-  const [open, setOpenBase] = useControllableState<boolean>(
-    controlledOpen,
-    defaultOpen ?? false,
-    onOpenChange,
-  );
-  const openRef = useRef(open);
-  useEffect(() => {
-    openRef.current = open;
-  });
-  const setOpen = useCallback(
-    (next: boolean) => {
-      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 (
-    <ContextMenuSubContext.Provider value={contextValue}>
-      {children}
-    </ContextMenuSubContext.Provider>
-  );
-}
-
-/** @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
-}: ContextMenuSubTriggerProps): ReactElement {
-  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: React.KeyboardEvent<HTMLLIElement>) => {
-    if (disabled) return;
-    if (event.key !== openKey) return;
-    event.preventDefault();
-    event.stopPropagation();
-    sub.setOpen(true);
-  };
-  const subTriggerProps = {
-    ...rest,
-    ref: sub.triggerRef,
-    role: "menuitem" as const,
-    tabIndex: -1,
-    "aria-haspopup": "menu" as const,
-    "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 <Slot {...subTriggerProps}>{children}</Slot>;
-  }
-  return <li {...subTriggerProps}>{children}</li>;
-}
-
-/** @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
-}: ContextMenuSubContentProps): ReactElement {
-  const sub = useContextMenuSubContext();
-  const { dir } = useContextMenuContext();
-  const closeKey = dir === "rtl" ? "ArrowRight" : "ArrowLeft";
-  const menuRef = useRef<HTMLMenuElement | null>(null);
-
-  useEffect(() => {
-    const menu = menuRef.current!;
-    if (sub.open) {
-      menu.showPopover();
-      const firstItem = menu.querySelector<HTMLElement>(MENUITEM_SELECTOR);
-      firstItem?.focus();
-    } else {
-      try {
-        menu.hidePopover();
-      } catch {
-        // already hidden — no-op
-      }
-    }
-  }, [sub.open]);
-
-  useEffect(() => {
-    const menu = menuRef.current!;
-    const handleToggle = (event: Event) => {
-      if ((event as ToggleEvent).newState === "closed") sub.setOpen(false);
-    };
-    menu.addEventListener("toggle", handleToggle);
-    return () => menu.removeEventListener("toggle", handleToggle);
-  }, [sub.setOpen]);
-
-  const handleKeyDown = (event: React.KeyboardEvent<HTMLMenuElement>) => {
-    if (event.key !== closeKey) return;
-    event.preventDefault();
-    event.stopPropagation();
-    sub.setOpen(false);
-    sub.triggerRef.current?.focus();
-  };
-
-  const closeOpenSubRef = useRef<(() => void) | null>(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" as const,
-    popover: "auto" as const,
-    onKeyDown: composeEventHandlers(onKeyDown, handleKeyDown),
-  };
-
-  return (
-    <ContextMenuContentContext.Provider value={contentContextValue}>
-      {asChild ? (
-        <Slot {...subContentProps}>{children}</Slot>
-      ) : (
-        <menu {...subContentProps}>{children}</menu>
-      )}
-    </ContextMenuContentContext.Provider>
-  );
-}
-
-/** @internal */
-ContextMenuSubContent.displayName = "ContextMenuSubContent";
-
-/** Type of the {@link ContextMenu} compound: the root callable plus its attached sub-components. */
-export type TContextMenuCompound = typeof ContextMenuRoot & {
-  Root: typeof ContextMenuRoot;
-  Trigger: typeof ContextMenuTrigger;
-  Content: typeof ContextMenuContent;
-  Item: typeof ContextMenuItem;
-  Separator: typeof ContextMenuSeparator;
-  Group: typeof ContextMenuGroup;
-  Label: typeof ContextMenuLabel;
-  CheckboxItem: typeof ContextMenuCheckboxItem;
-  ItemIndicator: typeof ContextMenuItemIndicator;
-  RadioGroup: typeof ContextMenuRadioGroup;
-  RadioItem: typeof ContextMenuRadioItem;
-  Sub: typeof ContextMenuSub;
-  SubTrigger: typeof ContextMenuSubTrigger;
-  SubContent: typeof 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: TContextMenuCompound = 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 };