@primitiv-ui/react 0.1.0

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

@@ -0,0 +1,262 @@
+import { fireEvent, render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { ContextMenu } from "../ContextMenu";
+
+describe("ContextMenu.Sub", () => {
+  it("renders SubTrigger as role=menuitem with aria-haspopup=menu and aria-expanded=false when the sub is closed", () => {
+    // Arrange & Act
+    render(
+      <ContextMenu.Root defaultOpen>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content>
+          <ContextMenu.Sub>
+            <ContextMenu.SubTrigger>More</ContextMenu.SubTrigger>
+            <ContextMenu.SubContent>
+              <ContextMenu.Item>Nested</ContextMenu.Item>
+            </ContextMenu.SubContent>
+          </ContextMenu.Sub>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+
+    // Assert
+    const subTrigger = screen.getByRole("menuitem", {
+      name: "More",
+      hidden: true,
+    });
+    expect(subTrigger).toHaveAttribute("aria-haspopup", "menu");
+    expect(subTrigger).toHaveAttribute("aria-expanded", "false");
+    expect(subTrigger).toHaveAttribute("aria-controls");
+  });
+
+  it("wires aria-controls on the SubTrigger to the SubContent's id", () => {
+    // Arrange & Act
+    render(
+      <ContextMenu.Root defaultOpen>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content>
+          <ContextMenu.Sub defaultOpen>
+            <ContextMenu.SubTrigger>More</ContextMenu.SubTrigger>
+            <ContextMenu.SubContent>
+              <ContextMenu.Item>Nested</ContextMenu.Item>
+            </ContextMenu.SubContent>
+          </ContextMenu.Sub>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+
+    // Assert
+    const subTrigger = screen.getByRole("menuitem", {
+      name: "More",
+      hidden: true,
+    });
+    const [, subMenu] = screen.getAllByRole("menu", { hidden: true });
+    expect(subMenu.id).toBeTruthy();
+    expect(subTrigger).toHaveAttribute("aria-controls", subMenu.id);
+    expect(subTrigger).toHaveAttribute("aria-expanded", "true");
+  });
+
+  it("opens the sub-menu on ArrowRight from the SubTrigger", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <ContextMenu.Root defaultOpen>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content>
+          <ContextMenu.Sub>
+            <ContextMenu.SubTrigger>More</ContextMenu.SubTrigger>
+            <ContextMenu.SubContent>
+              <ContextMenu.Item>Nested</ContextMenu.Item>
+            </ContextMenu.SubContent>
+          </ContextMenu.Sub>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+    const subTrigger = screen.getByRole("menuitem", {
+      name: "More",
+      hidden: true,
+    });
+    expect(subTrigger).toHaveAttribute("aria-expanded", "false");
+
+    // Act
+    await user.keyboard("{ArrowRight}");
+
+    // Assert
+    expect(subTrigger).toHaveAttribute("aria-expanded", "true");
+  });
+
+  it("closes the sub-menu on ArrowLeft and returns focus to the SubTrigger", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <ContextMenu.Root defaultOpen>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content>
+          <ContextMenu.Sub defaultOpen>
+            <ContextMenu.SubTrigger>More</ContextMenu.SubTrigger>
+            <ContextMenu.SubContent>
+              <ContextMenu.Item>Nested</ContextMenu.Item>
+            </ContextMenu.SubContent>
+          </ContextMenu.Sub>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+    const subTrigger = screen.getByRole("menuitem", {
+      name: "More",
+      hidden: true,
+    });
+
+    // Act
+    await user.keyboard("{ArrowLeft}");
+
+    // Assert
+    expect(subTrigger).toHaveAttribute("aria-expanded", "false");
+    expect(subTrigger).toHaveFocus();
+  });
+
+  it("opens the sub-menu when the pointer enters the SubTrigger", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <ContextMenu.Root defaultOpen>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content>
+          <ContextMenu.Sub>
+            <ContextMenu.SubTrigger>More</ContextMenu.SubTrigger>
+            <ContextMenu.SubContent>
+              <ContextMenu.Item>Nested</ContextMenu.Item>
+            </ContextMenu.SubContent>
+          </ContextMenu.Sub>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+    const subTrigger = screen.getByRole("menuitem", {
+      name: "More",
+      hidden: true,
+    });
+
+    // Act
+    await user.hover(subTrigger);
+
+    // Assert
+    expect(subTrigger).toHaveAttribute("aria-expanded", "true");
+  });
+
+  it("throws when SubTrigger is rendered outside a Sub", () => {
+    // Arrange
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+
+    // Act + Assert
+    expect(() =>
+      render(
+        <ContextMenu.Root defaultOpen>
+          <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+          <ContextMenu.Content>
+            <ContextMenu.SubTrigger>More</ContextMenu.SubTrigger>
+          </ContextMenu.Content>
+        </ContextMenu.Root>,
+      ),
+    ).toThrow(/SubTrigger.*<ContextMenu\.Sub>/);
+
+    spy.mockRestore();
+  });
+
+  it("disables ArrowRight, click, and hover when SubTrigger is disabled", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <ContextMenu.Root defaultOpen>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content>
+          <ContextMenu.Sub>
+            <ContextMenu.SubTrigger disabled>More</ContextMenu.SubTrigger>
+            <ContextMenu.SubContent>
+              <ContextMenu.Item>Nested</ContextMenu.Item>
+            </ContextMenu.SubContent>
+          </ContextMenu.Sub>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+    const subTrigger = screen.getByRole("menuitem", {
+      name: "More",
+      hidden: true,
+    });
+
+    // Act
+    await user.hover(subTrigger);
+
+    // Assert
+    expect(subTrigger).toHaveAttribute("aria-disabled", "true");
+    expect(subTrigger).toHaveAttribute("aria-expanded", "false");
+  });
+
+  it("closes the nested Sub when an item inside the SubContent is activated, so the sub state does not leak to the next open", async () => {
+    // Repro: open menu, hover into the sub, click an item inside. The whole
+    // menu closes. If the sub's own state were left stale, re-opening the
+    // menu would briefly render the sub popover before anything else closed
+    // it — a real-browser flash in the top-left corner.
+    const user = userEvent.setup();
+    render(
+      <ContextMenu.Root defaultOpen>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content>
+          <ContextMenu.Sub>
+            <ContextMenu.SubTrigger>Share</ContextMenu.SubTrigger>
+            <ContextMenu.SubContent>
+              <ContextMenu.Item>Email</ContextMenu.Item>
+            </ContextMenu.SubContent>
+          </ContextMenu.Sub>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+    const subTrigger = screen.getByRole("menuitem", {
+      name: "Share",
+      hidden: true,
+    });
+
+    // Act — hover opens the sub, then activate a nested item
+    await user.hover(subTrigger);
+    expect(subTrigger).toHaveAttribute("aria-expanded", "true");
+    fireEvent.click(
+      screen.getByRole("menuitem", { name: "Email", hidden: true }),
+    );
+
+    // Assert — the sub's open must have collapsed alongside the root close
+    expect(subTrigger).toHaveAttribute("aria-expanded", "false");
+  });
+
+  it("closes a stale nested Sub when the parent menu closes via outside click", async () => {
+    // Same leak shape via a different close path: outside-click dismisses
+    // the menu while a sub is open. The sub must collapse with it.
+    const user = userEvent.setup();
+    render(
+      <div>
+        <ContextMenu.Root defaultOpen>
+          <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+          <ContextMenu.Content>
+            <ContextMenu.Sub>
+              <ContextMenu.SubTrigger>Share</ContextMenu.SubTrigger>
+              <ContextMenu.SubContent>
+                <ContextMenu.Item>Email</ContextMenu.Item>
+              </ContextMenu.SubContent>
+            </ContextMenu.Sub>
+          </ContextMenu.Content>
+        </ContextMenu.Root>
+        <button type="button">Outside</button>
+      </div>,
+    );
+    const subTrigger = screen.getByRole("menuitem", {
+      name: "Share",
+      hidden: true,
+    });
+    await user.hover(subTrigger);
+    expect(subTrigger).toHaveAttribute("aria-expanded", "true");
+
+    // Act
+    await user.click(screen.getByText("Outside"));
+
+    // Assert
+    expect(subTrigger).toHaveAttribute("aria-expanded", "false");
+  });
+});

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

@@ -0,0 +1,89 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { ContextMenu } from "../ContextMenu";
+
+function renderMenu() {
+  return render(
+    <ContextMenu.Root defaultOpen>
+      <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+      <ContextMenu.Content>
+        <ContextMenu.Item>Apple</ContextMenu.Item>
+        <ContextMenu.Item>Banana</ContextMenu.Item>
+        <ContextMenu.Item>Blueberry</ContextMenu.Item>
+        <ContextMenu.Item>Cherry</ContextMenu.Item>
+      </ContextMenu.Content>
+    </ContextMenu.Root>,
+  );
+}
+
+describe("ContextMenu typeahead", () => {
+  it("focuses the next item that starts with the typed character", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    renderMenu();
+
+    // Act
+    await user.keyboard("b");
+
+    // Assert
+    expect(
+      screen.getByRole("menuitem", { name: "Banana", hidden: true }),
+    ).toHaveFocus();
+  });
+
+  it("cycles through items sharing a first letter when the same character is pressed repeatedly", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    renderMenu();
+
+    // Act
+    await user.keyboard("b");
+    expect(
+      screen.getByRole("menuitem", { name: "Banana", hidden: true }),
+    ).toHaveFocus();
+    await user.keyboard("b");
+
+    // Assert
+    expect(
+      screen.getByRole("menuitem", { name: "Blueberry", hidden: true }),
+    ).toHaveFocus();
+  });
+
+  it("matches a multi-character prefix typed within the typeahead window", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    renderMenu();
+
+    // Act — "bl" should jump straight to Blueberry, skipping Banana
+    await user.keyboard("bl");
+
+    // Assert
+    expect(
+      screen.getByRole("menuitem", { name: "Blueberry", hidden: true }),
+    ).toHaveFocus();
+  });
+
+  it("ignores disabled items in the typeahead match", async () => {
+    // Arrange
+    const user = userEvent.setup();
+    render(
+      <ContextMenu.Root defaultOpen>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content>
+          <ContextMenu.Item>Apple</ContextMenu.Item>
+          <ContextMenu.Item disabled>Banana</ContextMenu.Item>
+          <ContextMenu.Item>Blueberry</ContextMenu.Item>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+
+    // Act
+    await user.keyboard("b");
+
+    // Assert — Banana is disabled, so first match is Blueberry
+    expect(
+      screen.getByRole("menuitem", { name: "Blueberry", hidden: true }),
+    ).toHaveFocus();
+  });
+});

package/src/ContextMenu/constants.ts

@@ -0,0 +1,4 @@
+export const MENUITEM_SELECTOR =
+  '[role="menuitem"]:not([aria-disabled="true"]), [role="menuitemcheckbox"]:not([aria-disabled="true"]), [role="menuitemradio"]:not([aria-disabled="true"])';
+
+export const TYPEAHEAD_RESET_MS = 500;

package/src/ContextMenu/index.ts

@@ -0,0 +1 @@
+export { ContextMenu } from "./ContextMenu";

package/src/ContextMenu/types.ts

@@ -0,0 +1,199 @@
+import { ComponentProps, ReactNode, Ref } from "react";
+
+import { CheckedState } from "../Checkbox/types";
+import { Direction } from "../DirectionProvider";
+
+type ContextMenuRootBaseProps = {
+  children?: ReactNode;
+  /**
+   * Reading direction for the menu. Affects which arrow key opens / closes
+   * a submenu — `ArrowRight` opens in `"ltr"`, `ArrowLeft` opens in
+   * `"rtl"`. Falls back to the inherited {@link DirectionProvider} value,
+   * or to `"ltr"` if no provider is present.
+   */
+  dir?: Direction;
+};
+
+type ContextMenuRootUncontrolledProps = ContextMenuRootBaseProps & {
+  defaultOpen?: boolean;
+  open?: never;
+  onOpenChange?: (open: boolean) => void;
+};
+
+type ContextMenuRootControlledProps = ContextMenuRootBaseProps & {
+  defaultOpen?: never;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+};
+
+export type ContextMenuRootProps =
+  | ContextMenuRootUncontrolledProps
+  | ContextMenuRootControlledProps;
+
+export type ContextMenuTriggerProps = ComponentProps<"span"> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLSpanElement>;
+  asChild?: boolean;
+  disabled?: boolean;
+};
+
+export type ContextMenuContentProps = Omit<
+  ComponentProps<"menu">,
+  "role" | "popover" | "id"
+> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLMenuElement>;
+  asChild?: boolean;
+};
+
+export type ContextMenuItemProps = Omit<
+  ComponentProps<"li">,
+  "role" | "tabIndex" | "onSelect"
+> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLLIElement>;
+  asChild?: boolean;
+  disabled?: boolean;
+  /**
+   * Fires when the item is activated (click, Enter, or Space). Called
+   * with an event whose `preventDefault()` skips the auto-close that
+   * ContextMenu performs after selection.
+   */
+  onSelect?: (event: Event) => void;
+};
+
+export type ContextMenuSeparatorProps = Omit<ComponentProps<"li">, "role"> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLLIElement>;
+  asChild?: boolean;
+};
+
+export type ContextMenuGroupProps = Omit<ComponentProps<"li">, "role"> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLLIElement>;
+  asChild?: boolean;
+};
+
+export type ContextMenuLabelProps = ComponentProps<"li"> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLLIElement>;
+  asChild?: boolean;
+};
+
+type ContextMenuCheckboxItemBaseProps = Omit<
+  ComponentProps<"li">,
+  "role" | "tabIndex" | "aria-checked" | "defaultChecked" | "onSelect"
+> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLLIElement>;
+  asChild?: boolean;
+  disabled?: boolean;
+  /**
+   * Fires when activation completes and the auto-close fires. Call
+   * `event.preventDefault()` to keep the menu open after toggling.
+   */
+  onSelect?: (event: Event) => void;
+};
+
+type ContextMenuCheckboxItemUncontrolledProps =
+  ContextMenuCheckboxItemBaseProps & {
+    defaultChecked?: CheckedState;
+    checked?: never;
+    onCheckedChange?: (checked: boolean) => void;
+  };
+
+type ContextMenuCheckboxItemControlledProps =
+  ContextMenuCheckboxItemBaseProps & {
+    defaultChecked?: never;
+    checked: CheckedState;
+    onCheckedChange: (checked: boolean) => void;
+  };
+
+export type ContextMenuCheckboxItemProps =
+  | ContextMenuCheckboxItemUncontrolledProps
+  | ContextMenuCheckboxItemControlledProps;
+
+export type ContextMenuItemIndicatorProps = ComponentProps<"span"> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLSpanElement>;
+  asChild?: boolean;
+  /**
+   * Render the indicator even when its parent item is unchecked. The
+   * `data-state` attribute still reflects the live state.
+   */
+  forceMount?: boolean;
+};
+
+type ContextMenuRadioGroupBaseProps = Omit<ComponentProps<"li">, "role"> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLLIElement>;
+  asChild?: boolean;
+};
+
+type ContextMenuRadioGroupUncontrolledProps =
+  ContextMenuRadioGroupBaseProps & {
+    defaultValue?: string;
+    value?: never;
+    onValueChange?: (value: string) => void;
+  };
+
+type ContextMenuRadioGroupControlledProps = ContextMenuRadioGroupBaseProps & {
+  defaultValue?: never;
+  value: string;
+  onValueChange: (value: string) => void;
+};
+
+export type ContextMenuRadioGroupProps =
+  | ContextMenuRadioGroupUncontrolledProps
+  | ContextMenuRadioGroupControlledProps;
+
+export type ContextMenuRadioItemProps = Omit<
+  ComponentProps<"li">,
+  "role" | "tabIndex" | "aria-checked" | "onSelect"
+> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLLIElement>;
+  asChild?: boolean;
+  disabled?: boolean;
+  value: string;
+  onSelect?: (event: Event) => void;
+};
+
+type ContextMenuSubBaseProps = {
+  children?: ReactNode;
+};
+
+type ContextMenuSubUncontrolledProps = ContextMenuSubBaseProps & {
+  defaultOpen?: boolean;
+  open?: never;
+  onOpenChange?: (open: boolean) => void;
+};
+
+type ContextMenuSubControlledProps = ContextMenuSubBaseProps & {
+  defaultOpen?: never;
+  open: boolean;
+  onOpenChange: (open: boolean) => void;
+};
+
+export type ContextMenuSubProps =
+  | ContextMenuSubUncontrolledProps
+  | ContextMenuSubControlledProps;
+
+export type ContextMenuSubTriggerProps = Omit<
+  ComponentProps<"li">,
+  "role" | "tabIndex" | "aria-haspopup" | "aria-expanded" | "aria-controls"
+> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLLIElement>;
+  asChild?: boolean;
+  disabled?: boolean;
+};
+
+export type ContextMenuSubContentProps = Omit<
+  ComponentProps<"menu">,
+  "role" | "popover" | "id"
+> & {
+  children?: ReactNode;
+  ref?: Ref<HTMLMenuElement>;
+  asChild?: boolean;
+};

package/src/DirectionProvider/DirectionContext.ts

@@ -0,0 +1,21 @@
+import { createContext, useContext } from "react";
+
+import { Direction } from "./types";
+
+export const DirectionContext = createContext<Direction>("ltr");
+
+/**
+ * Reads the current reading direction from the nearest
+ * {@link DirectionProvider} ancestor.
+ *
+ * Falls back to `"ltr"` when no provider is present, so it is always safe
+ * to call — components use it as the default for an omitted `dir` prop.
+ *
+ * @example Fall back to the inherited direction
+ * ```tsx
+ * const resolvedDir = dir ?? useDirection();
+ * ```
+ */
+export function useDirection(): Direction {
+  return useContext(DirectionContext);
+}

package/src/DirectionProvider/DirectionProvider.tsx

@@ -0,0 +1,31 @@
+import { DirectionContext } from "./DirectionContext";
+import { DirectionProviderProps } from "./types";
+
+/**
+ * Broadcasts a reading direction to every descendant so direction-aware
+ * components can inherit it instead of each being passed an explicit
+ * `dir` prop.
+ *
+ * Renders **no DOM** — only a context provider. Direction is never
+ * inferred from the DOM; the consumer still owns setting `dir` on their
+ * `<html>` (or another element) for CSS. A descendant component's own
+ * `dir` prop always wins over the inherited value; components fall back
+ * to {@link useDirection} only when their `dir` prop is omitted.
+ *
+ * @example Declare direction once near the app root
+ * ```tsx
+ * <DirectionProvider dir="rtl">
+ *   <Tabs.Root>…</Tabs.Root>
+ *   <Slider.Root>…</Slider.Root>
+ * </DirectionProvider>
+ * ```
+ */
+export function DirectionProvider({ dir, children }: DirectionProviderProps) {
+  return (
+    <DirectionContext.Provider value={dir}>
+      {children}
+    </DirectionContext.Provider>
+  );
+}
+
+DirectionProvider.displayName = "DirectionProvider";

package/src/DirectionProvider/README.md

@@ -0,0 +1,62 @@
+# DirectionProvider
+
+Broadcasts a reading direction (`ltr` / `rtl`) to its descendants so
+direction-aware components inherit it through context instead of each
+being passed an explicit `dir` prop.
+
+Renders **no DOM** — only a React context provider.
+
+## Usage
+
+```tsx
+import { DirectionProvider } from "@primitiv-ui/react";
+
+<DirectionProvider dir="rtl">
+  <Tabs.Root defaultValue="overview">…</Tabs.Root>
+  <Slider.Root defaultValue={[50]} aria-label="Volume" />
+</DirectionProvider>;
+```
+
+A component's own `dir` prop always wins over the inherited direction —
+components fall back to the provider only when `dir` is omitted:
+
+```tsx
+<DirectionProvider dir="rtl">
+  {/* inherits rtl */}
+  <Tabs.Root defaultValue="a">…</Tabs.Root>
+  {/* explicit ltr overrides the provider */}
+  <Tabs.Root dir="ltr" defaultValue="a">…</Tabs.Root>
+</DirectionProvider>;
+```
+
+## Props
+
+| Prop       | Type             | Default | Description                                    |
+| ---------- | ---------------- | ------- | ---------------------------------------------- |
+| `dir`      | `"ltr" \| "rtl"` | —       | Reading direction broadcast to all descendants |
+| `children` | `ReactNode`      | —       | The subtree that inherits the direction        |
+
+## useDirection
+
+`useDirection()` reads the current direction from the nearest
+`DirectionProvider`. It falls back to `"ltr"` when no provider is present,
+so it is always safe to call — direction-aware components use it as the
+default for an omitted `dir` prop:
+
+```tsx
+import { useDirection } from "@primitiv-ui/react";
+
+function MyControl({ dir }: { dir?: "ltr" | "rtl" }) {
+  const resolvedDir = dir ?? useDirection();
+  // …
+}
+```
+
+## Notes
+
+- `DirectionProvider` never inspects the DOM. Setting `dir` on `<html>`
+  (or another element) for CSS purposes remains the consumer's
+  responsibility — this component only propagates the value to
+  `@primitiv-ui/react` components.
+- Providers nest: an inner `DirectionProvider` overrides an outer one for
+  its subtree.