@primitiv-ui/react 0.1.20 → 0.1.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@primitiv-ui/react",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "Headless, accessible React components built on the WAI-ARIA authoring patterns. Zero styles ship with this package — bring your own (CSS, Tailwind, CSS-in-JS, design tokens).",
   "type": "module",
   "main": "./src/index.ts",
@@ -56,6 +56,7 @@
   "scripts": {
     "qa": "pnpm qa:units",
     "qa:units": "vitest run --coverage",
-    "qa:units:watch": "vitest --coverage"
+    "qa:units:watch": "vitest --coverage",
+    "typecheck": "tsc -p tsconfig.json --noEmit"
   }
 }

package/src/ContextMenu/README.md

@@ -252,7 +252,7 @@ ARIA attributes, event handlers, and ref onto a caller-supplied child:
 ```css
 /* Open state on the menu panel */
 [role="menu"][data-state="open"] {
-  animation: fade-in 120ms ease-out;
+  animation: fade-in var(--primitiv-motion-duration-control) var(--primitiv-motion-easing-enter);
 }
 
 /* Highlighted item — pointer focus */

package/src/ContextMenu/__tests__/ContextMenu.checkbox-item.test.tsx

@@ -142,4 +142,27 @@ describe("ContextMenu.CheckboxItem", () => {
     expect(onCheckedChange).not.toHaveBeenCalled();
     expect(item).toHaveAttribute("aria-disabled", "true");
   });
+
+  it("highlights on pointer enter and clears the highlight on pointer leave", () => {
+    // Arrange
+    render(
+      <ContextMenu.Root defaultOpen>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content>
+          <ContextMenu.CheckboxItem>Show grid</ContextMenu.CheckboxItem>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+    const item = screen.getByRole("menuitemcheckbox", {
+      name: "Show grid",
+      hidden: true,
+    });
+
+    // Act & Assert — enter highlights, leave clears it.
+    fireEvent.mouseEnter(item);
+    expect(item).toHaveAttribute("data-highlighted");
+
+    fireEvent.mouseLeave(item);
+    expect(item).not.toHaveAttribute("data-highlighted");
+  });
 });

package/src/ContextMenu/__tests__/ContextMenu.keyboard-interaction.test.tsx

@@ -1,4 +1,4 @@
-import { render, screen } from "@testing-library/react";
+import { fireEvent, render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
 import { ContextMenu } from "../ContextMenu";
@@ -169,4 +169,59 @@ describe("ContextMenu keyboard interaction", () => {
       screen.getByRole("menuitem", { name: "Delete", hidden: true }),
     ).toHaveFocus();
   });
+
+  it("ArrowUp from a middle item moves to the previous item", async () => {
+    // Arrange — drives the non-wrapping branch (currentIndex - 1).
+    const user = userEvent.setup();
+    renderMenu();
+    await user.keyboard("{ArrowDown}");
+    expect(
+      screen.getByRole("menuitem", { name: "Duplicate", hidden: true }),
+    ).toHaveFocus();
+
+    // Act
+    await user.keyboard("{ArrowUp}");
+
+    // Assert
+    expect(
+      screen.getByRole("menuitem", { name: "Rename", hidden: true }),
+    ).toHaveFocus();
+  });
+
+  it("ignores arrow keys when the menu has no items", () => {
+    // Arrange — an empty Content has nothing to focus, so activeElement is the
+    // body, exercising the no-popover-scope fallback and the empty-items guard.
+    render(
+      <ContextMenu.Root defaultOpen>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content />
+      </ContextMenu.Root>,
+    );
+    const menu = screen.getByRole("menu", { hidden: true });
+
+    // Act + Assert — no throw, menu stays open.
+    expect(() => fireEvent.keyDown(menu, { key: "ArrowDown" })).not.toThrow();
+    expect(menu).toBeInTheDocument();
+  });
+
+  it("Enter does nothing when no item is focused", () => {
+    // Arrange — blur the auto-focused first item so currentIndex resolves to -1.
+    const onSelect = vi.fn();
+    render(
+      <ContextMenu.Root defaultOpen>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content>
+          <ContextMenu.Item onSelect={onSelect}>Rename</ContextMenu.Item>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+    const menu = screen.getByRole("menu", { hidden: true });
+    (document.activeElement as HTMLElement | null)?.blur();
+
+    // Act
+    fireEvent.keyDown(menu, { key: "Enter" });
+
+    // Assert — nothing was activated.
+    expect(onSelect).not.toHaveBeenCalled();
+  });
 });

package/src/ContextMenu/__tests__/ContextMenu.mouse-interaction.test.tsx

@@ -128,6 +128,47 @@ describe("ContextMenu mouse interaction", () => {
     expect(item).not.toHaveAttribute("data-highlighted");
   });
 
+  it("keeps the menu open when the click lands on the trigger itself", async () => {
+    // The outside-click dismissal must exempt the trigger so a click within it
+    // does not immediately re-close a just-opened menu.
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+    render(
+      <ContextMenu.Root defaultOpen onOpenChange={onOpenChange}>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content>
+          <ContextMenu.Item>Rename</ContextMenu.Item>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+
+    // Act
+    await user.click(screen.getByText("Area"));
+
+    // Assert — the trigger-contained click did not request a close.
+    expect(onOpenChange).not.toHaveBeenCalledWith(false);
+  });
+
+  it("keeps the menu open when the click lands inside the content popover", async () => {
+    // A click on the menu surface (but not an item) must not dismiss it.
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+    render(
+      <ContextMenu.Root defaultOpen onOpenChange={onOpenChange}>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content>
+          <ContextMenu.Item>Rename</ContextMenu.Item>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+
+    // Act
+    await user.click(screen.getByRole("menu", { hidden: true }));
+
+    // Assert
+    expect(onOpenChange).not.toHaveBeenCalledWith(false);
+  });
+
   it("closes the menu when the user clicks outside both the trigger and the content", async () => {
     // Arrange
     const user = userEvent.setup();

package/src/ContextMenu/__tests__/ContextMenu.radio-item.test.tsx

@@ -124,4 +124,29 @@ describe("ContextMenu.RadioGroup + ContextMenu.RadioItem", () => {
     // Assert
     expect(onValueChange).not.toHaveBeenCalled();
   });
+
+  it("highlights a RadioItem on pointer enter and clears it on pointer leave", () => {
+    // Arrange
+    render(
+      <ContextMenu.Root defaultOpen>
+        <ContextMenu.Trigger>Area</ContextMenu.Trigger>
+        <ContextMenu.Content>
+          <ContextMenu.RadioGroup defaultValue="light">
+            <ContextMenu.RadioItem value="light">Light</ContextMenu.RadioItem>
+          </ContextMenu.RadioGroup>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+    const item = screen.getByRole("menuitemradio", {
+      name: "Light",
+      hidden: true,
+    });
+
+    // Act & Assert — enter highlights, leave clears it.
+    fireEvent.mouseEnter(item);
+    expect(item).toHaveAttribute("data-highlighted");
+
+    fireEvent.mouseLeave(item);
+    expect(item).not.toHaveAttribute("data-highlighted");
+  });
 });

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

@@ -259,4 +259,149 @@ describe("ContextMenu.Sub", () => {
     // Assert
     expect(subTrigger).toHaveAttribute("aria-expanded", "false");
   });
+
+  it("opens the sub-menu when the SubTrigger is clicked", () => {
+    // Arrange
+    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
+    fireEvent.click(subTrigger);
+
+    // Assert
+    expect(subTrigger).toHaveAttribute("aria-expanded", "true");
+  });
+
+  it("does not open on click when the SubTrigger is disabled", () => {
+    // Arrange
+    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
+    fireEvent.click(subTrigger);
+
+    // Assert
+    expect(subTrigger).toHaveAttribute("aria-expanded", "false");
+  });
+
+  it("ignores the open arrow key when the SubTrigger is disabled", () => {
+    // Arrange
+    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
+    fireEvent.keyDown(subTrigger, { key: "ArrowRight" });
+
+    // Assert
+    expect(subTrigger).toHaveAttribute("aria-expanded", "false");
+  });
+
+  it("closes an already-open sibling sub when a second sub opens via click", () => {
+    // The hover path closes the prior sub up front via closeSiblingSub; opening
+    // by click skips that, so the sub's own registration effect must supplant
+    // the previously registered sibling instead.
+    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.Sub>
+            <ContextMenu.SubTrigger>Move to</ContextMenu.SubTrigger>
+            <ContextMenu.SubContent>
+              <ContextMenu.Item>Trash</ContextMenu.Item>
+            </ContextMenu.SubContent>
+          </ContextMenu.Sub>
+        </ContextMenu.Content>
+      </ContextMenu.Root>,
+    );
+    const a = screen.getByRole("menuitem", { name: "Share", hidden: true });
+    const b = screen.getByRole("menuitem", { name: "Move to", hidden: true });
+
+    // Act — click opens A, then clicking B must supplant A.
+    fireEvent.click(a);
+    expect(a).toHaveAttribute("aria-expanded", "true");
+    fireEvent.click(b);
+
+    // Assert
+    expect(a).toHaveAttribute("aria-expanded", "false");
+    expect(b).toHaveAttribute("aria-expanded", "true");
+  });
+
+  it("leaves the sub-menu open when a non-close key is pressed inside the SubContent", () => {
+    // Arrange
+    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,
+    });
+    const [, subMenu] = screen.getAllByRole("menu", { hidden: true });
+
+    // Act — a key other than the close (inline-backward) key must be ignored.
+    fireEvent.keyDown(subMenu, { key: "ArrowDown" });
+
+    // Assert
+    expect(subTrigger).toHaveAttribute("aria-expanded", "true");
+  });
 });

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

@@ -1,4 +1,4 @@
-import { render, screen } from "@testing-library/react";
+import { fireEvent, render, screen } from "@testing-library/react";
 import userEvent from "@testing-library/user-event";
 
 import { ContextMenu } from "../ContextMenu";
@@ -86,4 +86,49 @@ describe("ContextMenu typeahead", () => {
       screen.getByRole("menuitem", { name: "Blueberry", hidden: true }),
     ).toHaveFocus();
   });
+
+  it("resets the typed query after the typeahead window elapses", () => {
+    // Arrange — fake timers so the reset timeout can be flushed deterministically.
+    vi.useFakeTimers();
+    try {
+      renderMenu();
+      const menu = screen.getByRole("menu", { hidden: true });
+
+      // First keystroke matches Banana and arms the reset timer.
+      fireEvent.keyDown(menu, { key: "b" });
+      expect(
+        screen.getByRole("menuitem", { name: "Banana", hidden: true }),
+      ).toHaveFocus();
+
+      // Let the window lapse so the query clears.
+      vi.advanceTimersByTime(5000);
+
+      // Act — a fresh "a" must be treated as a new search, not appended to "b"
+      // (which would match nothing and leave focus on Banana).
+      fireEvent.keyDown(menu, { key: "a" });
+
+      // Assert
+      expect(
+        screen.getByRole("menuitem", { name: "Apple", hidden: true }),
+      ).toHaveFocus();
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+
+  it("starts the search from the top when no item is focused", () => {
+    // Arrange — blur the auto-focused item so currentIndex resolves to -1 and
+    // the search starts at index 0.
+    renderMenu();
+    const menu = screen.getByRole("menu", { hidden: true });
+    (document.activeElement as HTMLElement | null)?.blur();
+
+    // Act
+    fireEvent.keyDown(menu, { key: "a" });
+
+    // Assert
+    expect(
+      screen.getByRole("menuitem", { name: "Apple", hidden: true }),
+    ).toHaveFocus();
+  });
 });

package/src/Dropdown/README.md

@@ -250,7 +250,7 @@ the component's):
 ```css
 /* Open state on the menu panel */
 [role="menu"][data-popover-open] {
-  animation: fade-in 120ms ease-out;
+  animation: fade-in var(--primitiv-motion-duration-control) var(--primitiv-motion-easing-enter);
 }
 
 /* Highlighted item — pointer focus */

package/src/Field/__tests__/Field.contract.test.tsx

@@ -49,7 +49,11 @@ describe("Field styling contract", () => {
 
   it("emits exactly the contracted data-* attribute names across its states", () => {
     const emitted = new Set<string>();
-    for (const props of [{}, { invalid: true, disabled: true, required: true }]) {
+    const states: Record<string, boolean>[] = [
+      {},
+      { invalid: true, disabled: true, required: true },
+    ];
+    for (const props of states) {
       for (const name of dataAttributeNames(renderRoot(props))) {
         emitted.add(name);
       }

package/src/Field/hooks/__tests__/useFieldProps.test.tsx

@@ -0,0 +1,47 @@
+import { render, screen } from "@testing-library/react";
+
+import { FieldContext, type FieldContextValue } from "../../FieldContext";
+import { useFieldProps } from "../useFieldProps";
+
+/**
+ * `useFieldProps` is a reusable hook that reads {@link FieldContext} directly,
+ * so it is exercised here against a hand-built provider value rather than the
+ * full `Field.Root`. `Field.Root` always supplies a truthy `descriptionId`,
+ * which means its defensive "nothing to describe" fallback is only reachable
+ * through a custom provider like the one below.
+ */
+function Probe(props: { "aria-describedby"?: string }) {
+  const merged = useFieldProps(props);
+  return <input data-testid="probe" {...merged} />;
+}
+
+function renderInField(
+  field: Partial<FieldContextValue>,
+  props: { "aria-describedby"?: string } = {},
+) {
+  const value: FieldContextValue = {
+    id: "f",
+    descriptionId: "",
+    errorId: "",
+    invalid: false,
+    disabled: false,
+    required: false,
+    ...field,
+  };
+  return render(
+    <FieldContext.Provider value={value}>
+      <Probe {...props} />
+    </FieldContext.Provider>,
+  );
+}
+
+describe("useFieldProps aria-describedby composition", () => {
+  it("omits aria-describedby entirely when nothing contributes an id", () => {
+    // Arrange & Act — empty description/error ids, not invalid, no consumer id.
+    renderInField({});
+
+    // Assert — the empty join collapses to undefined, so the attribute is absent
+    // rather than rendered as aria-describedby="".
+    expect(screen.getByTestId("probe")).not.toHaveAttribute("aria-describedby");
+  });
+});

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

@@ -76,8 +76,9 @@ describe("InputGroup asChild composition", () => {
   });
 
   it("forwards a ref through Slot on the Root", () => {
-    // Arrange
-    const ref = createRef<HTMLLabelElement>();
+    // Arrange: Root types its ref as HTMLDivElement (its default element); the
+    // asChild <label> still receives it, which the identity assertion confirms.
+    const ref = createRef<HTMLDivElement>();
 
     // Act
     render(

package/src/Modal/README.md

@@ -168,10 +168,10 @@ animation can play against the `data-state="closed"` attribute:
 
 ```css
 [data-state="open"] {
-  animation: fade-in 150ms ease-out;
+  animation: fade-in var(--primitiv-motion-duration-control) var(--primitiv-motion-easing-enter);
 }
 [data-state="closed"] {
-  animation: fade-out 120ms ease-in forwards;
+  animation: fade-out var(--primitiv-motion-duration-feedback) var(--primitiv-motion-easing-exit) forwards;
 }
 ```
 

package/src/RadioGroup/README.md

@@ -159,10 +159,10 @@ animation can play against `data-state="unchecked"`:
 
 ```css
 [data-state="checked"] {
-  animation: dot-in 120ms ease-out;
+  animation: dot-in var(--primitiv-motion-duration-control) var(--primitiv-motion-easing-enter);
 }
 [data-state="unchecked"] {
-  animation: dot-out 100ms ease-in forwards;
+  animation: dot-out var(--primitiv-motion-duration-feedback) var(--primitiv-motion-easing-exit) forwards;
 }
 ```
 

package/src/Select/__tests__/Select.placeholder.test.tsx

@@ -29,4 +29,22 @@ describe("Select placeholder", () => {
     const select = screen.getByRole("combobox") as HTMLSelectElement;
     expect(select.value).toBe("");
   });
+
+  it("ignores non-element children when scanning for a placeholder", () => {
+    // Arrange & Act — a bare text node sits among the options (e.g. stray
+    // whitespace or a conditional that resolved to a string). The placeholder
+    // scan must skip it rather than treat it as a candidate.
+    const { container } = render(
+      <Select.Root>
+        {"  "}
+        <Select.Option value="apple">Apple</Select.Option>
+      </Select.Root>,
+    );
+
+    // Assert — with no placeholder present, no empty-value default is inferred,
+    // so the browser falls back to the first real option.
+    expect(container.querySelector("option[hidden]")).toBeNull();
+    const select = screen.getByRole("combobox") as HTMLSelectElement;
+    expect(select.value).toBe("apple");
+  });
 });

package/src/Slot/Slot.tsx

@@ -20,6 +20,9 @@ import {
   cloneElement,
   Children,
   RefObject,
+  type ForwardRefExoticComponent,
+  type PropsWithoutRef,
+  type RefAttributes,
 } from "react";
 import { SlotProps } from "./types";
 import { AnyProps, PossibleRef } from "../types";
@@ -137,7 +140,9 @@ function mergeProps(slotProps: AnyProps, childProps: AnyProps): AnyProps {
  * return <button {...buttonProps}>{children}</button>;
  * ```
  */
-export const Slot = forwardRef<HTMLElement, SlotProps>(
+export const Slot: ForwardRefExoticComponent<
+  PropsWithoutRef<SlotProps> & RefAttributes<HTMLElement>
+> = forwardRef<HTMLElement, SlotProps>(
   ({ children, ...slotProps }, forwardedRef) => {
     if (Children.count(children) !== 1 || !isValidElement(children)) {
       throw new Error("Slot requires exactly one React element child.");

package/src/Switch/README.md

@@ -99,7 +99,7 @@ animate with `transition` or Web Animations.
   background: #6366f1;
 }
 .switch__thumb {
-  transition: translate 120ms ease;
+  transition: translate var(--primitiv-motion-duration-control) var(--primitiv-motion-easing-default);
 }
 .switch > input:checked ~ .switch__thumb {
   translate: 1.25rem 0;

package/src/Tooltip/README.md

@@ -183,8 +183,8 @@ subtree stays in the DOM while closed so a CSS animation can play on
 ```
 
 ```css
-[data-state="open"]  { animation: fade-in  120ms ease-out; }
-[data-state="closed"] { animation: fade-out 80ms  ease-in forwards; }
+[data-state="open"]  { animation: fade-in var(--primitiv-motion-duration-control) var(--primitiv-motion-easing-enter); }
+[data-state="closed"] { animation: fade-out var(--primitiv-motion-duration-feedback) var(--primitiv-motion-easing-exit) forwards; }
 ```
 
 ## `asChild` composition