@primitiv-ui/react 0.1.29 → 0.1.31

package/src/Listbox/__tests__/Listbox.selection-follows-focus.test.tsx

@@ -0,0 +1,64 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { Listbox } from "../Listbox";
+
+import { fruits } from "./Listbox.fixtures";
+
+describe("Listbox selectionFollowsFocus", () => {
+  it("selects each option the cursor lands on", async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(
+      <Listbox.Root
+        type="single"
+        defaultValue="apple"
+        selectionFollowsFocus
+        onValueChange={onValueChange}
+        aria-label="Fruits"
+      >
+        {fruits.map((fruit) => (
+          <Listbox.Option key={fruit.value} value={fruit.value}>
+            {fruit.label}
+          </Listbox.Option>
+        ))}
+      </Listbox.Root>,
+    );
+
+    await user.tab();
+    await user.keyboard("{ArrowDown}");
+
+    expect(onValueChange).toHaveBeenCalledWith("banana");
+    expect(screen.getByRole("option", { name: "Banana" })).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+  });
+
+  it("still moves the cursor with the selection", async () => {
+    const user = userEvent.setup();
+    render(
+      <Listbox.Root
+        type="single"
+        defaultValue="apple"
+        selectionFollowsFocus
+        aria-label="Fruits"
+      >
+        {fruits.map((fruit) => (
+          <Listbox.Option key={fruit.value} value={fruit.value}>
+            {fruit.label}
+          </Listbox.Option>
+        ))}
+      </Listbox.Root>,
+    );
+
+    await user.tab();
+    await user.keyboard("{End}");
+
+    expect(screen.getByRole("listbox")).toHaveAttribute(
+      "aria-activedescendant",
+      screen.getByRole("option", { name: "Cherry" }).id,
+    );
+  });
+});

package/src/Listbox/__tests__/Listbox.strict-context.test.tsx

@@ -0,0 +1,21 @@
+import { render } from "@testing-library/react";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+
+import { Listbox } from "../Listbox";
+
+/**
+ * Options read a strict context, so rendering one outside its provider throws
+ * a consumer-actionable message rather than failing obscurely further down.
+ * The message itself is the contract — assert it, not just that something threw.
+ */
+describe("Listbox strict context", () => {
+  beforeEach(() => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  it("names <Listbox.Root> when an Option is rendered outside one", () => {
+    expect(() =>
+      render(<Listbox.Option value="apple">Apple</Listbox.Option>),
+    ).toThrow("Listbox.Option must be rendered as a child of Listbox.Root");
+  });
+});

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

@@ -0,0 +1,123 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { Listbox } from "../Listbox";
+import { TYPEAHEAD_RESET_MS } from "../constants";
+
+import { typeaheadOptions } from "./Listbox.fixtures";
+
+function renderListbox(props: { onValueChange?: (value: string) => void } = {}) {
+  return render(
+    <Listbox.Root type="single" aria-label="Fruits" {...props}>
+      {typeaheadOptions.map((fruit) => (
+        <Listbox.Option key={fruit.value} value={fruit.value}>
+          {fruit.label}
+        </Listbox.Option>
+      ))}
+    </Listbox.Root>,
+  );
+}
+
+const cursorIsOn = (name: string) =>
+  expect(screen.getByRole("listbox")).toHaveAttribute(
+    "aria-activedescendant",
+    screen.getByRole("option", { name }).id,
+  );
+
+describe("Listbox typeahead", () => {
+  it("moves the cursor to the first option matching a single character", async () => {
+    const user = userEvent.setup();
+    renderListbox();
+
+    await user.tab();
+    await user.keyboard("b");
+
+    cursorIsOn("Banana");
+  });
+
+  it("cycles through matches on a repeated character, wrapping around", async () => {
+    const user = userEvent.setup();
+    renderListbox();
+
+    await user.tab();
+
+    await user.keyboard("a");
+    cursorIsOn("Apricot");
+
+    await user.keyboard("a");
+    cursorIsOn("Avocado");
+
+    await user.keyboard("a");
+    cursorIsOn("Apple");
+  });
+
+  it("narrows to a prefix match with a multi-character query", async () => {
+    const user = userEvent.setup();
+    renderListbox();
+
+    await user.tab();
+    await user.keyboard("av");
+
+    cursorIsOn("Avocado");
+  });
+
+  it("does not select the option it lands on", async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    renderListbox({ onValueChange });
+
+    await user.tab();
+    await user.keyboard("b");
+
+    expect(onValueChange).not.toHaveBeenCalled();
+  });
+
+  it("skips a disabled match", async () => {
+    const user = userEvent.setup();
+    render(
+      <Listbox.Root type="single" aria-label="Fruits">
+        <Listbox.Option value="apple">Apple</Listbox.Option>
+        <Listbox.Option value="banana" disabled>
+          Banana
+        </Listbox.Option>
+        <Listbox.Option value="blueberry">Blueberry</Listbox.Option>
+      </Listbox.Root>,
+    );
+
+    await user.tab();
+    await user.keyboard("b");
+
+    cursorIsOn("Blueberry");
+  });
+});
+
+/**
+ * The accumulation window is real elapsed time. userEvent + fake timers
+ * deadlocks in this repo (RTL's asyncWrapper drives fake clocks through a
+ * global `jest`, which vitest does not define), so this waits on the real
+ * clock rather than reaching for fireEvent. The timer callback only clears a
+ * ref, so nothing lands outside act.
+ */
+describe("Listbox typeahead reset window", () => {
+  it("starts a fresh query once the accumulation window lapses", async () => {
+    const user = userEvent.setup();
+    renderListbox();
+
+    await user.tab();
+
+    // A two-character query narrows in place onto the only "av..." match.
+    await user.keyboard("av");
+    cursorIsOn("Avocado");
+
+    await new Promise((resolve) =>
+      setTimeout(resolve, TYPEAHEAD_RESET_MS + 100),
+    );
+
+    // With the buffer cleared this is a fresh single "a", which advances past
+    // Avocado and wraps to Apple. Had "av" survived, "ava" would match nothing
+    // and the cursor would not move.
+    await user.keyboard("a");
+    cursorIsOn("Apple");
+  });
+});

package/src/Listbox/__tests__/Listbox.uncontrolled-state.test.tsx

@@ -0,0 +1,48 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { Listbox } from "../Listbox";
+
+describe("Listbox uncontrolled state", () => {
+  it("marks the defaultValue option as selected", () => {
+    render(
+      <Listbox.Root type="single" defaultValue="banana" aria-label="Fruits">
+        <Listbox.Option value="apple">Apple</Listbox.Option>
+        <Listbox.Option value="banana">Banana</Listbox.Option>
+      </Listbox.Root>,
+    );
+
+    expect(screen.getByRole("option", { name: "Banana" })).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+    expect(screen.getByRole("option", { name: "Apple" })).toHaveAttribute(
+      "aria-selected",
+      "false",
+    );
+  });
+
+  it("selects an option on click and reports it via onValueChange", async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(
+      <Listbox.Root
+        type="single"
+        onValueChange={onValueChange}
+        aria-label="Fruits"
+      >
+        <Listbox.Option value="apple">Apple</Listbox.Option>
+        <Listbox.Option value="banana">Banana</Listbox.Option>
+      </Listbox.Root>,
+    );
+
+    await user.click(screen.getByRole("option", { name: "Banana" }));
+
+    expect(onValueChange).toHaveBeenCalledWith("banana");
+    expect(screen.getByRole("option", { name: "Banana" })).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+  });
+});

package/src/Listbox/constants.ts

@@ -0,0 +1,2 @@
+/** Typeahead accumulation window, in milliseconds. */
+export const TYPEAHEAD_RESET_MS: number = 500;

package/src/Listbox/hooks/index.ts

@@ -0,0 +1 @@
+export * from "./useListboxRoot";

package/src/Listbox/hooks/useListboxRoot.ts

@@ -0,0 +1,407 @@
+import { useCallback, useId, useState, type KeyboardEvent } from "react";
+
+import {
+  useCollection,
+  useControllableState,
+  useTypeahead,
+} from "../../hooks/index.ts";
+import { deriveId, getKeyToActionMap } from "../../utils/index.ts";
+
+import { TYPEAHEAD_RESET_MS } from "../constants";
+
+
+type OptionMeta = { element: HTMLElement; disabled: boolean };
+
+type UseListboxRootArgs = {
+  type: "single" | "multiple";
+  defaultValue: string | string[] | undefined;
+  value: string | string[] | undefined;
+  onValueChange:
+    | ((value: string) => void)
+    | ((value: string[]) => void)
+    | undefined;
+  selectionFollowsFocus: boolean;
+  orientation: "horizontal" | "vertical";
+  dir: "ltr" | "rtl";
+};
+
+function toArray(value: string | string[] | undefined): string[] {
+  if (value === undefined) return [];
+  return typeof value === "string" ? [value] : value;
+}
+
+/**
+ * Owns the Listbox's selection state and its virtual-focus cursor.
+ *
+ * Selection is normalised into an array so options only ever ask "am I in
+ * the selected set?". The cursor (`activeValue`) is the option
+ * `aria-activedescendant` points at — real DOM focus stays on the root, so
+ * the cursor is seeded when the root takes focus and cleared when it loses
+ * it.
+ *
+ * No `tabIndex` is moved between options: the root is the single tab stop,
+ * and navigation just repoints the cursor.
+ *
+ * Navigation order is read from the **live DOM** on every interaction rather
+ * than from a memoised array. Reordering options in place (APG's rearrangeable
+ * example) keeps the same elements mounted with unchanged props, so nothing
+ * re-registers and any cached order would silently go stale.
+ */
+export function useListboxRoot({
+  type,
+  defaultValue,
+  value: controlledValue,
+  onValueChange,
+  selectionFollowsFocus,
+  orientation,
+  dir,
+}: UseListboxRootArgs): {
+  selectedValues: string[];
+  select: (optionValue: string) => void;
+  activeValue: string | undefined;
+  registerOption: (
+    optionValue: string,
+    element: HTMLElement | null,
+    disabled?: boolean,
+  ) => void;
+  getOptionId: (optionValue: string) => string;
+  seedActiveValue: () => void;
+  clearActiveValue: () => void;
+  handleKeyDown: (event: KeyboardEvent<HTMLElement>) => void;
+  moveCursor: (optionValue: string) => void;
+} {
+  const rootId = useId();
+  const [selectedValues, setSelectedValues] = useControllableState<string[]>(
+    controlledValue === undefined ? undefined : toArray(controlledValue),
+    toArray(defaultValue),
+  );
+  const [activeValue, setActiveValue] = useState<string | undefined>(undefined);
+  // `keys` is deliberately unused: navigation order comes from the DOM, not
+  // from registration order. The collection is still what keeps `itemsRef`
+  // populated and re-renders the Root as options mount and unmount.
+  const { register: registerBase, itemsRef } = useCollection<
+    string,
+    OptionMeta
+  >();
+
+  const registerOption = useCallback(
+    // Stryker disable next-line BooleanLiteral: equivalent — the only caller that omits this argument is the unmount path, which passes a null element and so never reads it.
+    (optionValue: string, element: HTMLElement | null, disabled = false) => {
+      registerBase(optionValue, element ? { element, disabled } : null);
+    },
+    // Stryker disable next-line ArrayDeclaration: equivalent — registerBase is a stable useCollection callback, so an empty dep array memoises identically.
+    [registerBase],
+  );
+
+  // Disabled options stay in the DOM and in the a11y tree, but drop out of
+  // every navigable list: cursor movement and focus seeding both skip them.
+  //
+  // Sorted by document position, not registration order — see the note above.
+  const getNavigableValues = useCallback(
+    () => {
+      const entries = Array.from(itemsRef.current.entries()).filter(
+        ([, meta]) => !meta.disabled,
+      );
+      entries.sort(([, a], [, b]) =>
+        a.element.compareDocumentPosition(b.element) &
+        Node.DOCUMENT_POSITION_FOLLOWING
+          ? -1
+          : 1,
+      );
+      return entries.map(([key]) => key);
+    },
+    // Stryker disable next-line ArrayDeclaration: equivalent — itemsRef is a stable RefObject.
+    [itemsRef],
+  );
+
+  // Single mode replaces the selection outright — re-selecting the current
+  // option is a no-op re-select, not a deselect (a listbox is not a toggle).
+  // Multiple mode toggles the option in place, preserving the rest.
+  const select = useCallback(
+    (optionValue: string) => {
+      if (type === "single") {
+        setSelectedValues([optionValue]);
+        (onValueChange as ((value: string) => void) | undefined)?.(optionValue);
+        return;
+      }
+      const next = selectedValues.includes(optionValue)
+        ? selectedValues.filter((key) => key !== optionValue)
+        : [...selectedValues, optionValue];
+      setSelectedValues(next);
+      (onValueChange as ((value: string[]) => void) | undefined)?.(next);
+    },
+    [type, selectedValues, setSelectedValues, onValueChange],
+  );
+
+  // Bulk selection writes. Multiple-mode only: single mode's onValueChange
+  // takes a string, and none of the range shortcuts apply to it.
+  const commitSelection = useCallback(
+    (next: string[]) => {
+      setSelectedValues(next);
+      (onValueChange as ((value: string[]) => void) | undefined)?.(next);
+    },
+    // Stryker disable next-line ArrayDeclaration: equivalent — both are stable for a given render pair; the value read is the ref/state itself.
+    [setSelectedValues, onValueChange],
+  );
+
+  // APG: Ctrl+A selects all, or deselects if everything is already selected.
+  // Disabled options are not selectable, so they are not part of "all".
+  const toggleSelectAll = useCallback(() => {
+    const navigable = getNavigableValues();
+    const allSelected =
+      // Stryker disable next-line ConditionalExpression,EqualityOperator: equivalent — with nothing navigable both arms commit the empty array.
+      navigable.length > 0 &&
+      navigable.every((key) => selectedValues.includes(key));
+    commitSelection(allSelected ? [] : navigable);
+  }, [getNavigableValues, selectedValues, commitSelection]);
+
+  const getOptionId = useCallback(
+    // Stryker disable next-line StringLiteral: equivalent — the suffix only has to be stable; every assertion compares against the element's own id.
+    (optionValue: string) => deriveId(rootId, "option", optionValue),
+    // Stryker disable next-line ArrayDeclaration: equivalent — rootId is a useId() constant.
+    [rootId],
+  );
+
+  // APG: when the referenced option is not fully visible, scroll it into view.
+  const moveCursor = useCallback(
+    (optionValue: string) => {
+      setActiveValue(optionValue);
+      // Stryker disable next-line OptionalChaining: unreachable — every value reaching moveCursor comes from getNavigableValues(), so the entry is always registered.
+      itemsRef.current
+        .get(optionValue)
+        ?.element.scrollIntoView({ block: "nearest" });
+    },
+    // Stryker disable next-line ArrayDeclaration: equivalent — itemsRef is a stable RefObject.
+    [itemsRef],
+  );
+
+  // APG: when the listbox receives focus, the first selected option takes
+  // the cursor; with nothing selected, the first option does.
+  const seedActiveValue = useCallback(
+    () => {
+      const navigable = getNavigableValues();
+      setActiveValue(
+        (current) =>
+          current ??
+          navigable.find((key) => selectedValues.includes(key)) ??
+          navigable[0],
+      );
+    },
+    // Stryker disable next-line ArrayDeclaration: equivalent — the callback is rebuilt each render and reads both through its closure.
+    [getNavigableValues, selectedValues],
+  );
+
+  // Stryker disable next-line ArrayDeclaration: equivalent — the dep array is already empty; adding a phantom entry cannot change a setState-only callback.
+  const clearActiveValue = useCallback(() => setActiveValue(undefined), []);
+
+  // One navigation path for both the arrow keymap and typeahead, so
+  // `selectionFollowsFocus` applies identically to each.
+  const navigateTo = useCallback(
+    (target: string) => {
+      moveCursor(target);
+      if (selectionFollowsFocus) select(target);
+    },
+    // Stryker disable next-line ArrayDeclaration: equivalent — a stale closure here still calls the same setState and select.
+    [moveCursor, selectionFollowsFocus, select],
+  );
+
+  // APG: Shift+Arrow "moves focus and selects" the option it lands on. Unlike
+  // the plain arrows this deliberately does not wrap — extending a range off
+  // the end and round to the top would select options never travelled past.
+  const extendSelection = useCallback(
+    (direction: "next" | "prev") => {
+      const navigable = getNavigableValues();
+      const currentIndex =
+        // Stryker disable next-line ConditionalExpression: equivalent — indexOf(undefined) is itself -1, so both arms yield the same index.
+        activeValue === undefined ? -1 : navigable.indexOf(activeValue);
+      if (currentIndex === -1) return;
+
+      const targetIndex =
+        direction === "next" ? currentIndex + 1 : currentIndex - 1;
+      if (targetIndex < 0 || targetIndex >= navigable.length) return;
+
+      const target = navigable[targetIndex];
+      moveCursor(target);
+      if (!selectedValues.includes(target)) {
+        commitSelection([...selectedValues, target]);
+      }
+    },
+    [
+      activeValue,
+      getNavigableValues,
+      moveCursor,
+      selectedValues,
+      commitSelection,
+    ],
+  );
+
+  // APG: Ctrl+Shift+Home/End selects from the cursor through to the first or
+  // last option and moves the cursor to that edge. Selections outside the
+  // swept range are preserved.
+  const extendToEdge = useCallback(
+    (edge: "first" | "last") => {
+      const navigable = getNavigableValues();
+      const currentIndex =
+        // Stryker disable next-line ConditionalExpression: equivalent — indexOf(undefined) is itself -1, so both arms yield the same index.
+        activeValue === undefined ? -1 : navigable.indexOf(activeValue);
+      if (currentIndex === -1) return;
+
+      const range =
+        edge === "first"
+          ? navigable.slice(0, currentIndex + 1)
+          : navigable.slice(currentIndex);
+
+      const next = [...selectedValues];
+      for (const key of range) {
+        if (!next.includes(key)) next.push(key);
+      }
+      commitSelection(next);
+      moveCursor(
+        edge === "first" ? navigable[0] : navigable[navigable.length - 1],
+      );
+    },
+    [
+      activeValue,
+      getNavigableValues,
+      selectedValues,
+      commitSelection,
+      moveCursor,
+    ],
+  );
+
+  // The arrow / Home / End / Enter-Space keymap. This mirrors what
+  // `useRovingTabindex` does, but resolves `navigable` at event time so a
+  // reorder is picked up; that hook takes its list at render time.
+  const handleNavigationKey = useCallback(
+    (event: KeyboardEvent<HTMLElement>) => {
+      const action = getKeyToActionMap({
+        orientation,
+        dir,
+        homeEnd: true,
+        activate: true,
+      })[event.key];
+      if (!action) return;
+
+      const navigable = getNavigableValues();
+      // Stryker disable next-line ConditionalExpression: equivalent — with no options every downstream index resolves to undefined, which moves the cursor nowhere.
+      if (navigable.length === 0) return;
+
+      if (action === "activate") {
+        if (activeValue === undefined) return;
+        event.preventDefault();
+        select(activeValue);
+        return;
+      }
+
+      const currentIndex =
+        // Stryker disable next-line ConditionalExpression: equivalent — indexOf(undefined) is itself -1, so both arms yield the same index.
+        activeValue === undefined ? -1 : navigable.indexOf(activeValue);
+      let targetIndex: number;
+      if (action === "first") {
+        targetIndex = 0;
+      } else if (action === "last") {
+        targetIndex = navigable.length - 1;
+      } else if (currentIndex === -1) {
+        // No cursor yet — the options streamed in after the listbox took
+        // focus, so seeding never ran. Enter the list from the near end
+        // rather than swallowing the keystroke.
+        targetIndex = action === "next" ? 0 : navigable.length - 1;
+      } else {
+        targetIndex =
+          action === "next"
+            ? (currentIndex + 1) % navigable.length
+            : (currentIndex - 1 + navigable.length) % navigable.length;
+      }
+
+      event.preventDefault();
+      navigateTo(navigable[targetIndex]);
+    },
+    [orientation, dir, getNavigableValues, activeValue, select, navigateTo],
+  );
+
+  // `optionValue` is always drawn from `navigable` (the enabled subset of the
+  // registered keys), and useCollection writes `itemsRef` and the keys state
+  // together — so the entry, and an element with textContent, always exist.
+  const getLabel = useCallback(
+    (optionValue: string) =>
+      itemsRef.current.get(optionValue)!.element.textContent!,
+    // Stryker disable next-line ArrayDeclaration: equivalent — itemsRef is a stable RefObject.
+    [itemsRef],
+  );
+
+  const { handleTypeahead } = useTypeahead({
+    getNavigable: getNavigableValues,
+    getLabel,
+    currentKey: activeValue,
+    onMatch: navigateTo,
+    resetMs: TYPEAHEAD_RESET_MS,
+  });
+
+  // The keymap gets first refusal: it calls preventDefault on every key it
+  // consumes, so a still-unhandled printable character falls through to
+  // typeahead (and Space, which activates, never does).
+  const handleKeyDown = useCallback(
+    (event: KeyboardEvent<HTMLElement>) => {
+      const chord = event.ctrlKey || event.metaKey;
+
+      if (chord && !event.altKey && event.key.toLowerCase() === "a") {
+        if (type !== "multiple") return;
+        event.preventDefault();
+        toggleSelectAll();
+        return;
+      }
+
+      if (
+        chord &&
+        event.shiftKey &&
+        (event.key === "Home" || event.key === "End")
+      ) {
+        if (type !== "multiple") return;
+        event.preventDefault();
+        // Stryker disable next-line StringLiteral: equivalent — extendToEdge branches on `edge === "first"`, so any non-"first" string selects the same path.
+        extendToEdge(event.key === "Home" ? "first" : "last");
+        return;
+      }
+
+      // Every other chorded shortcut belongs to the browser and the consumer —
+      // APG's rearrangeable example binds Alt+Arrow to its toolbar. Only Shift
+      // is ours, for range selection.
+      if (chord || event.altKey) return;
+
+      if (event.shiftKey && type === "multiple") {
+        const action = getKeyToActionMap({ orientation, dir })[event.key];
+        if (action === "next" || action === "prev") {
+          event.preventDefault();
+          extendSelection(action);
+          return;
+        }
+      }
+
+      handleNavigationKey(event);
+      if (event.defaultPrevented) return;
+      handleTypeahead(event);
+    },
+    [
+      type,
+      orientation,
+      dir,
+      toggleSelectAll,
+      extendSelection,
+      extendToEdge,
+      handleNavigationKey,
+      handleTypeahead,
+    ],
+  );
+
+  return {
+    selectedValues,
+    select,
+    activeValue,
+    registerOption,
+    getOptionId,
+    seedActiveValue,
+    clearActiveValue,
+    handleKeyDown,
+    moveCursor,
+  };
+}

package/src/Listbox/index.ts

@@ -0,0 +1,3 @@
+export * from "./Listbox";
+export * from "./ListboxContext";
+export * from "./types";