@primitiv-ui/react 0.1.0

package/src/ContextMenu/ContextMenuContentContext.ts

@@ -0,0 +1,15 @@
+import { createContext, RefObject } from "react";
+
+/**
+ * Content-scoped context provided by {@link ContextMenuContent} and
+ * {@link ContextMenuSubContent}. Holds a ref to a single "currently open
+ * direct-child sub" close callback so that sibling items can dismiss the
+ * open sub on hover, mirroring the keyboard contract (focus returning to
+ * the parent menu closes the sub).
+ */
+export type ContextMenuContentContextValue = {
+  closeOpenSubRef: RefObject<(() => void) | null>;
+};
+
+export const ContextMenuContentContext =
+  createContext<ContextMenuContentContextValue | null>(null);

package/src/ContextMenu/ContextMenuContext.ts

@@ -0,0 +1,21 @@
+import { RefObject } from "react";
+
+import { Direction } from "../DirectionProvider";
+import { createStrictContext } from "../utils";
+
+export type ContextMenuPosition = { x: number; y: number };
+
+export type ContextMenuContextValue = {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  position: ContextMenuPosition | null;
+  setPosition: (position: ContextMenuPosition | null) => void;
+  contentId: string;
+  triggerRef: RefObject<HTMLElement | null>;
+  dir: Direction;
+};
+
+export const [ContextMenuContext, useContextMenuContext] =
+  createStrictContext<ContextMenuContextValue>(
+    "ContextMenu sub-components must be rendered inside a <ContextMenu.Root>.",
+  );

package/src/ContextMenu/ContextMenuGroupContext.ts

@@ -0,0 +1,8 @@
+import { createContext } from "react";
+
+export type ContextMenuGroupContextValue = {
+  labelId: string;
+};
+
+export const ContextMenuGroupContext =
+  createContext<ContextMenuGroupContextValue | null>(null);

package/src/ContextMenu/ContextMenuItemIndicatorContext.ts

@@ -0,0 +1,8 @@
+import { createContext } from "react";
+
+export type ContextMenuItemIndicatorContextValue = {
+  checked: boolean | "indeterminate";
+};
+
+export const ContextMenuItemIndicatorContext =
+  createContext<ContextMenuItemIndicatorContextValue | null>(null);

package/src/ContextMenu/ContextMenuRadioGroupContext.ts

@@ -0,0 +1,9 @@
+import { createContext } from "react";
+
+export type ContextMenuRadioGroupContextValue = {
+  value: string | undefined;
+  select: (value: string) => void;
+};
+
+export const ContextMenuRadioGroupContext =
+  createContext<ContextMenuRadioGroupContextValue | null>(null);

package/src/ContextMenu/ContextMenuSubContext.ts

@@ -0,0 +1,15 @@
+import { RefObject } from "react";
+
+import { createStrictContext } from "../utils";
+
+export type ContextMenuSubContextValue = {
+  open: boolean;
+  setOpen: (open: boolean) => void;
+  contentId: string;
+  triggerRef: RefObject<HTMLLIElement | null>;
+};
+
+export const [ContextMenuSubContext, useContextMenuSubContext] =
+  createStrictContext<ContextMenuSubContextValue>(
+    "ContextMenu.SubTrigger and ContextMenu.SubContent must be rendered inside a <ContextMenu.Sub>.",
+  );

package/src/ContextMenu/README.md

@@ -0,0 +1,275 @@
+# ContextMenu
+
+A compound component implementing the
+[WAI-ARIA Menu pattern](https://www.w3.org/WAI/ARIA/apg/patterns/menu/)
+for right-click / long-press / context-key menus, layered on top of the
+native HTML
+[Popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API).
+No portal, no floating-ui — the browser handles layering via the top
+layer, and the component handles close on outside click / Escape.
+
+```tsx
+import { ContextMenu } from "@primitiv-ui/react";
+
+<ContextMenu.Root>
+  <ContextMenu.Trigger>
+    <div className="canvas">Right-click anywhere on this canvas</div>
+  </ContextMenu.Trigger>
+  <ContextMenu.Content>
+    <ContextMenu.Item onSelect={() => paste()}>Paste</ContextMenu.Item>
+    <ContextMenu.Item onSelect={() => duplicate()}>Duplicate</ContextMenu.Item>
+    <ContextMenu.Separator />
+    <ContextMenu.Item disabled>Archive</ContextMenu.Item>
+  </ContextMenu.Content>
+</ContextMenu.Root>;
+```
+
+## Sub-components
+
+| Export                      | Role                 | Notes                                                                                |
+| --------------------------- | -------------------- | ------------------------------------------------------------------------------------ |
+| `ContextMenu.Root`          | State owner          | Uncontrolled (`defaultOpen`) or controlled (`open` + `onOpenChange`)                 |
+| `ContextMenu.Trigger`       | Right-click target   | Renders `<span>`; intercepts `contextmenu`, suppresses the native menu               |
+| `ContextMenu.Content`       | `menu`               | Native `popover="manual"`, positioned at the cursor; arrow keys, typeahead, Escape   |
+| `ContextMenu.Item`          | `menuitem`           | Activatable row with `onSelect` escape hatch                                         |
+| `ContextMenu.CheckboxItem`  | `menuitemcheckbox`   | Tri-state toggle (`true` / `false` / `"indeterminate"`)                              |
+| `ContextMenu.RadioGroup`    | `group`              | Single-selection container for `RadioItem`s                                          |
+| `ContextMenu.RadioItem`     | `menuitemradio`      | Must live inside a `RadioGroup`                                                      |
+| `ContextMenu.ItemIndicator` | —                    | Icon slot inside a `CheckboxItem` / `RadioItem`; exposes `data-state` + `forceMount` |
+| `ContextMenu.Label`         | —                    | Non-interactive label; auto-wired to the enclosing `Group` via `aria-labelledby`     |
+| `ContextMenu.Group`         | `group`              | Semantic grouping for related items                                                  |
+| `ContextMenu.Separator`     | `separator`          | Visual divider; skipped by focus and typeahead                                       |
+| `ContextMenu.Sub`           | State owner          | Submenu boundary; same state modes as `Root`                                         |
+| `ContextMenu.SubTrigger`    | `menuitem`           | Opens the submenu on click, hover, or the inline-forward arrow (`ArrowRight` LTR / `ArrowLeft` RTL) |
+| `ContextMenu.SubContent`    | `menu`               | Submenu panel; the inline-backward arrow (`ArrowLeft` LTR / `ArrowRight` RTL) closes it and returns focus to the trigger |
+
+All sub-components that render an element accept `asChild` to compose
+their ARIA and behaviour onto a caller-supplied child.
+
+## Opening
+
+The Trigger listens for the DOM `contextmenu` event on its rendered
+element, calls `preventDefault()` to suppress the platform menu, and
+opens the Content positioned at the pointer coordinates via
+`position: fixed`.
+
+By default, Trigger renders a `<span>` wrapping its children — a
+neutral host that doesn't disturb the wrapped content's semantics. Pass
+`asChild` to attach the right-click behaviour to any element (a `<div>`
+canvas, a list row, an image, etc.).
+
+```tsx
+<ContextMenu.Trigger asChild>
+  <ImageCard src="…" alt="…" />
+</ContextMenu.Trigger>
+```
+
+A disabled Trigger ignores `contextmenu` entirely, letting the native
+browser menu through.
+
+## Keyboard interaction
+
+| Key                     | Behaviour                                         |
+| ----------------------- | ------------------------------------------------- |
+| `ArrowDown` / `ArrowUp` | Move focus to next / previous item (wraps)        |
+| `Home` / `End`          | Jump to first / last enabled 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 |
+| `ArrowRight`            | Open a focused submenu (`SubTrigger`, LTR) / close the submenu (inside `SubContent`, RTL) |
+| `ArrowLeft`             | Close the current submenu (inside `SubContent`, LTR) / open a focused submenu (`SubTrigger`, RTL) |
+
+Typeahead accumulates keystrokes within a 500 ms window; pressing the
+same character repeatedly cycles through items sharing that first letter.
+Disabled items are skipped by arrow navigation, typeahead, and activation.
+
+## Reading direction
+
+Pass `dir="ltr"` or `dir="rtl"` on `ContextMenu.Root` to invert the
+submenu open / close arrow keys. When omitted, the component reads the
+inherited `DirectionProvider` value, falling back to `"ltr"`:
+
+```tsx
+<DirectionProvider dir="rtl">
+  <ContextMenu.Root>{/* submenus now open on ArrowLeft */}</ContextMenu.Root>
+</DirectionProvider>
+```
+
+An explicit `dir` prop on `ContextMenu.Root` always wins over the
+inherited value. The reading direction only affects keyboard handling —
+submenu visual placement is the consumer's CSS concern (the workbench
+example uses logical positioning + `position-try-fallbacks: flip-inline`
+so subs reflow automatically in RTL).
+
+## State modes
+
+- **Uncontrolled** — pass `defaultOpen` (or omit to start closed). Optional
+  `onOpenChange` observes user-driven transitions.
+- **Controlled** — pass `open` and `onOpenChange` together.
+
+`ContextMenu.Sub` follows the same contract for its own open state.
+
+External flips of the controlled `open` prop do **not** invoke
+`onOpenChange` — only user-driven transitions (right-click, Escape,
+selection, outside click) do.
+
+`ContextMenu.CheckboxItem` and `ContextMenu.RadioGroup` each expose the
+same uncontrolled / controlled split for their `checked` / `value` state.
+
+## The `onSelect` escape hatch
+
+Every activatable item (`Item`, `CheckboxItem`, `RadioItem`) fires
+`onSelect` with a cancellable `Event` on activation. By default the menu
+auto-closes; call `event.preventDefault()` to keep it open — useful for
+rapidly toggling multiple checkboxes, or running an action whose outcome
+is shown inline in the menu.
+
+```tsx
+<ContextMenu.CheckboxItem
+  onSelect={(event) => event.preventDefault()}
+  onCheckedChange={setGridVisible}
+>
+  Show grid
+</ContextMenu.CheckboxItem>
+```
+
+## Disabled items
+
+Disabled items receive `aria-disabled="true"` rather than the native
+`disabled` attribute, so they remain visible to assistive technology but
+no-op on activation. Arrow navigation and typeahead skip them.
+
+```tsx
+<ContextMenu.Item disabled>Archive (coming soon)</ContextMenu.Item>
+```
+
+A disabled `SubTrigger` refuses to open on both click and the
+inline-forward arrow key.
+
+## Checkbox and radio items
+
+```tsx
+<ContextMenu.Content>
+  <ContextMenu.Label>View</ContextMenu.Label>
+  <ContextMenu.CheckboxItem defaultChecked>Show grid</ContextMenu.CheckboxItem>
+  <ContextMenu.CheckboxItem>Show ruler</ContextMenu.CheckboxItem>
+  <ContextMenu.Separator />
+  <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>
+</ContextMenu.Content>
+```
+
+`CheckboxItem` supports a tri-state: `true`, `false`, or `"indeterminate"`
+(which renders as `aria-checked="mixed"`). An indeterminate item resolves
+to `true` on the next activation.
+
+### `ItemIndicator`
+
+Render the visible mark inside the item via `ContextMenu.ItemIndicator`.
+It defaults to a `<span>`, supports `asChild` so consumers can compose
+onto an SVG icon, and exposes `data-state` for styling:
+
+```tsx
+<ContextMenu.CheckboxItem
+  checked={showBookmarks}
+  onCheckedChange={setShowBookmarks}
+>
+  <ContextMenu.ItemIndicator>
+    <CheckIcon />
+  </ContextMenu.ItemIndicator>
+  Show bookmarks
+</ContextMenu.CheckboxItem>
+```
+
+| `data-state`      | When                                                                                |
+| ----------------- | ----------------------------------------------------------------------------------- |
+| `"checked"`       | Parent `CheckboxItem` is `true`, or parent `RadioItem` is the group's current value |
+| `"unchecked"`     | Parent is `false` (only reachable when `forceMount` is set — see below)             |
+| `"indeterminate"` | Parent `CheckboxItem` is `"indeterminate"`                                          |
+
+By default the indicator **unmounts** when its parent is unchecked. Pass
+`forceMount` to keep the DOM node in both states so CSS transitions or a
+React animation library can drive the visual state off `data-state`.
+
+Rendering `ContextMenu.ItemIndicator` outside a `CheckboxItem` or
+`RadioItem` throws a descriptive error.
+
+## Submenus
+
+```tsx
+<ContextMenu.Content>
+  <ContextMenu.Item>Cut</ContextMenu.Item>
+  <ContextMenu.Sub>
+    <ContextMenu.SubTrigger>Share</ContextMenu.SubTrigger>
+    <ContextMenu.SubContent>
+      <ContextMenu.Item>Email</ContextMenu.Item>
+      <ContextMenu.Item>Copy link</ContextMenu.Item>
+    </ContextMenu.SubContent>
+  </ContextMenu.Sub>
+</ContextMenu.Content>
+```
+
+Open a submenu with the inline-forward arrow key (`ArrowRight` in LTR,
+`ArrowLeft` in RTL), a click on the trigger, or pointer hover; close it
+with the inline-backward arrow or by selecting an item. Focus returns to
+the `SubTrigger` when the submenu closes.
+
+## Groups and labels
+
+```tsx
+<ContextMenu.Content>
+  <ContextMenu.Group>
+    <ContextMenu.Label>Edit</ContextMenu.Label>
+    <ContextMenu.Item>Undo</ContextMenu.Item>
+    <ContextMenu.Item>Redo</ContextMenu.Item>
+  </ContextMenu.Group>
+</ContextMenu.Content>
+```
+
+Nesting a `ContextMenu.Label` inside a `ContextMenu.Group` wires the
+group's `aria-labelledby` to the label automatically.
+
+## `asChild` composition
+
+Every rendering sub-component accepts `asChild` to compose its
+ARIA attributes, event handlers, and ref onto a caller-supplied child:
+
+```tsx
+<ContextMenu.Trigger asChild>
+  <div className="canvas">Right-click here</div>
+</ContextMenu.Trigger>
+
+<ContextMenu.Item asChild>
+  <a href="/rename">Rename</a>
+</ContextMenu.Item>
+```
+
+## Styling hooks
+
+```css
+/* Open state on the menu panel */
+[role="menu"][data-state="open"] {
+  animation: fade-in 120ms ease-out;
+}
+
+/* Highlighted item — pointer focus */
+[role="menuitem"][data-highlighted],
+[role="menuitemcheckbox"][data-highlighted],
+[role="menuitemradio"][data-highlighted] {
+  background: rgba(0 0 0 / 0.06);
+  outline: none;
+}
+
+/* Disabled items */
+[aria-disabled="true"] {
+  opacity: 0.5;
+  pointer-events: none;
+}
+```
+
+`data-state="open" | "closed"` is present on the Content for state-driven
+styling. `data-highlighted` is present on `Item`, `CheckboxItem`,
+`RadioItem`, and `SubTrigger` while the item has pointer focus.

package/src/ContextMenu/__tests__/ContextMenu.asChild.test.tsx

@@ -0,0 +1,186 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+
+import { ContextMenu } from "../ContextMenu";
+
+describe("ContextMenu asChild", () => {
+  it("delegates Trigger to the child element via asChild", () => {
+    // Arrange & Act
+    render(
+      <ContextMenu.Root>
+        <ContextMenu.Trigger asChild>
+          <div data-testid="custom-trigger">Area</div>
+        </ContextMenu.Trigger>
+        <ContextMenu.Content>
+          <ContextMenu.Item>Rename</ContextMenu.Item>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+
+    // Assert
+    const trigger = screen.getByTestId("custom-trigger");
+    expect(trigger.tagName).toBe("DIV");
+  });
+
+  it("delegates Content to the child element via asChild", () => {
+    // Arrange & Act
+    render(
+      <ContextMenu.Root defaultOpen>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content asChild>
+          <div data-testid="custom-content">
+            <ContextMenu.Item>Rename</ContextMenu.Item>
+          </div>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+
+    // Assert
+    const content = screen.getByTestId("custom-content");
+    expect(content.tagName).toBe("DIV");
+    expect(content).toHaveAttribute("role", "menu");
+    expect(content).toHaveAttribute("popover", "manual");
+  });
+
+  it("delegates Item to the child element and auto-closes on click", () => {
+    // Arrange
+    const onSelect = vi.fn();
+    const onOpenChange = vi.fn();
+    render(
+      <ContextMenu.Root defaultOpen onOpenChange={onOpenChange}>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content>
+          <ContextMenu.Item asChild onSelect={onSelect}>
+            <a href="#rename" data-testid="custom-item">
+              Rename
+            </a>
+          </ContextMenu.Item>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+    const item = screen.getByTestId("custom-item");
+    expect(item.tagName).toBe("A");
+    expect(item).toHaveAttribute("role", "menuitem");
+
+    // Act
+    fireEvent.click(item);
+
+    // Assert
+    expect(onSelect).toHaveBeenCalledOnce();
+    expect(onOpenChange).toHaveBeenCalledWith(false);
+  });
+
+  it("delegates Separator to the child element via asChild", () => {
+    // Arrange & Act
+    render(
+      <ContextMenu.Root defaultOpen>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content>
+          <ContextMenu.Item>Rename</ContextMenu.Item>
+          <ContextMenu.Separator asChild>
+            <hr data-testid="custom-separator" />
+          </ContextMenu.Separator>
+          <ContextMenu.Item>Delete</ContextMenu.Item>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+
+    // Assert
+    const separator = screen.getByTestId("custom-separator");
+    expect(separator.tagName).toBe("HR");
+    expect(separator).toHaveAttribute("role", "separator");
+  });
+
+  it("delegates Group and Label to the child elements via asChild", () => {
+    // Arrange & Act
+    render(
+      <ContextMenu.Root defaultOpen>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content>
+          <ContextMenu.Group asChild>
+            <section data-testid="custom-group">
+              <ContextMenu.Label asChild>
+                <h2 data-testid="custom-label">Actions</h2>
+              </ContextMenu.Label>
+              <ContextMenu.Item>Rename</ContextMenu.Item>
+            </section>
+          </ContextMenu.Group>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("custom-group").tagName).toBe("SECTION");
+    expect(screen.getByTestId("custom-label").tagName).toBe("H2");
+  });
+
+  it("delegates CheckboxItem and ItemIndicator to the child elements via asChild", () => {
+    // Arrange & Act
+    render(
+      <ContextMenu.Root defaultOpen>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content>
+          <ContextMenu.CheckboxItem asChild defaultChecked>
+            <a href="#grid" data-testid="custom-check">
+              <ContextMenu.ItemIndicator asChild>
+                <svg data-testid="custom-indicator" />
+              </ContextMenu.ItemIndicator>
+              Show grid
+            </a>
+          </ContextMenu.CheckboxItem>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+
+    // Assert
+    const check = screen.getByTestId("custom-check");
+    expect(check.tagName).toBe("A");
+    expect(check).toHaveAttribute("role", "menuitemcheckbox");
+    const indicator = screen.getByTestId("custom-indicator");
+    expect(indicator.tagName).toBe("svg");
+    expect(indicator).toHaveAttribute("data-state", "checked");
+  });
+
+  it("delegates RadioGroup, RadioItem, Sub, SubTrigger, and SubContent via asChild", () => {
+    // Arrange & Act
+    render(
+      <ContextMenu.Root defaultOpen>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content>
+          <ContextMenu.RadioGroup asChild defaultValue="a">
+            <section data-testid="custom-rg">
+              <ContextMenu.RadioItem asChild value="a">
+                <a href="#a" data-testid="custom-ri">
+                  Alpha
+                </a>
+              </ContextMenu.RadioItem>
+            </section>
+          </ContextMenu.RadioGroup>
+          <ContextMenu.Sub defaultOpen>
+            <ContextMenu.SubTrigger asChild>
+              <a href="#more" data-testid="custom-st">
+                More
+              </a>
+            </ContextMenu.SubTrigger>
+            <ContextMenu.SubContent asChild>
+              <div data-testid="custom-sc">
+                <ContextMenu.Item>Nested</ContextMenu.Item>
+              </div>
+            </ContextMenu.SubContent>
+          </ContextMenu.Sub>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+
+    // Assert
+    expect(screen.getByTestId("custom-rg").tagName).toBe("SECTION");
+    expect(screen.getByTestId("custom-ri")).toHaveAttribute(
+      "role",
+      "menuitemradio",
+    );
+    expect(screen.getByTestId("custom-st")).toHaveAttribute(
+      "aria-haspopup",
+      "menu",
+    );
+    expect(screen.getByTestId("custom-sc")).toHaveAttribute("role", "menu");
+  });
+});

package/src/ContextMenu/__tests__/ContextMenu.basic-rendering.test.tsx

@@ -0,0 +1,39 @@
+import { render, screen } from "@testing-library/react";
+
+import { ContextMenu } from "../ContextMenu";
+
+describe("ContextMenu basic rendering", () => {
+  it("renders the Trigger's children so the area that should respond to right-click is in the DOM", () => {
+    // Arrange & Act
+    render(
+      <ContextMenu.Root>
+        <ContextMenu.Trigger>
+          <div>Right-click area</div>
+        </ContextMenu.Trigger>
+      </ContextMenu.Root>,
+    );
+
+    // Assert
+    expect(screen.getByText("Right-click area")).toBeInTheDocument();
+  });
+
+  it("renders Content as a native popover with popover=manual so the browser does not light-dismiss the menu on the right-click's mouseup", () => {
+    // Arrange & Act
+    render(
+      <ContextMenu.Root defaultOpen>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content>Items go here</ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+
+    // Assert — popover=manual is critical: with "auto" the browser treats
+    // the right-click's pointerdown (which fires before the popover opened)
+    // and the subsequent pointerup as an outside-dismiss gesture, closing
+    // the menu the instant the user releases the button. We close on
+    // outside click and Escape ourselves instead.
+    const menu = screen.getByRole("menu", { hidden: true });
+    expect(menu.tagName).toBe("MENU");
+    expect(menu).toHaveAttribute("popover", "manual");
+    expect(menu.id).toBeTruthy();
+  });
+});