@primitiv-ui/react 0.1.27 → 0.1.29

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

@@ -0,0 +1,36 @@
+import { render } from "@testing-library/react";
+
+import { Select } from "../Select";
+
+/**
+ * The rich sub-components 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("Select strict context", () => {
+  // React logs the error boundary-less throw; silence it so the run stays clean.
+  beforeEach(() => {
+    vi.spyOn(console, "error").mockImplementation(() => {});
+  });
+
+  it.each([
+    ["Trigger", <Select.Trigger key="t" />],
+    ["Value", <Select.Value key="v" />],
+    ["Content", <Select.Content key="c" />],
+  ])("names <Select.Root> when %s is rendered outside one", (_name, element) => {
+    expect(() => render(element)).toThrow(
+      "Select rich sub-components (Trigger, Value, Content, Item) must be rendered inside a <Select.Root>.",
+    );
+  });
+
+  it("names <Select.Item> when an ItemIndicator is rendered outside one", () => {
+    expect(() =>
+      render(
+        <Select.Root>
+          <Select.ItemIndicator forceMount>✓</Select.ItemIndicator>
+        </Select.Root>,
+      ),
+    ).toThrow("Select.ItemIndicator must be rendered inside a <Select.Item>.");
+  });
+});

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

@@ -0,0 +1,156 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+
+import { Select } from "../Select";
+
+function renderSelect() {
+  return render(
+    <Select.Root>
+      <Select.Trigger>
+        <Select.Value placeholder="Pick one" />
+      </Select.Trigger>
+      <Select.Content>
+        <Select.Item value="apple">Apple</Select.Item>
+        <Select.Item value="apricot">Apricot</Select.Item>
+        <Select.Item value="avocado">Avocado</Select.Item>
+        <Select.Item value="banana">Banana</Select.Item>
+      </Select.Content>
+    </Select.Root>,
+  );
+}
+
+const option = (name: string) =>
+  screen.getByRole("option", { name, hidden: true });
+
+describe("Select typeahead", () => {
+  it("jumps to the first option matching a single character", async () => {
+    const user = userEvent.setup();
+    renderSelect();
+    await user.click(screen.getByRole("button")); // opens, focuses Apple
+
+    await user.keyboard("b");
+    expect(option("Banana")).toHaveFocus();
+  });
+
+  it("skips the current match and cycles on a repeated character, wrapping around", async () => {
+    const user = userEvent.setup();
+    renderSelect();
+    await user.click(screen.getByRole("button")); // Apple focused
+
+    // Typing the focused item's own letter advances to the NEXT match (offset).
+    await user.keyboard("a");
+    expect(option("Apricot")).toHaveFocus();
+
+    // Repeated same char keeps cycling through the "a" matches…
+    await user.keyboard("a");
+    expect(option("Avocado")).toHaveFocus();
+
+    // …and wraps back to the first "a" match (past the non-matching Banana).
+    await user.keyboard("a");
+    expect(option("Apple")).toHaveFocus();
+  });
+
+  it("narrows to a prefix match with a multi-character query (no offset skip)", async () => {
+    const user = userEvent.setup();
+    renderSelect();
+    await user.click(screen.getByRole("button")); // Apple focused
+
+    // "av" is not a repeat; it searches from the current index without the
+    // single-char skip, so it stays put on the only "av…" match.
+    await user.keyboard("av");
+    expect(option("Avocado")).toHaveFocus();
+  });
+
+  it("does not match when no option starts with the typed text", async () => {
+    const user = userEvent.setup();
+    renderSelect();
+    await user.click(screen.getByRole("button")); // Apple focused
+
+    await user.keyboard("z");
+    // Focus stays on Apple — nothing starts with "z".
+    expect(option("Apple")).toHaveFocus();
+  });
+
+  it("matches the full multi-char prefix, not just the first character (isRepeat off)", async () => {
+    const user = userEvent.setup();
+    render(
+      <Select.Root>
+        <Select.Trigger>
+          <Select.Value placeholder="Pick" />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="bat">Bat</Select.Item>
+          <Select.Item value="bengal">Bengal</Select.Item>
+          <Select.Item value="banana">Banana</Select.Item>
+          <Select.Item value="cat">Cat</Select.Item>
+        </Select.Content>
+      </Select.Root>,
+    );
+    await user.click(screen.getByRole("button")); // Bat focused (index 0)
+
+    // "ban" must resolve to Banana. If isRepeat were (wrongly) true, the
+    // search would use just "b" and land on Bengal (or wrap to Bat).
+    await user.keyboard("ban");
+    expect(
+      screen.getByRole("option", { name: "Banana", hidden: true }),
+    ).toHaveFocus();
+  });
+
+  it("starts the search at index 0 when no option is focused (startIndex)", async () => {
+    const user = userEvent.setup();
+    render(
+      <Select.Root>
+        <Select.Trigger>
+          <Select.Value placeholder="Pick" />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="solid">Solid</Select.Item>
+          <Select.Item value="sun">Sun</Select.Item>
+          <Select.Item value="vue">Vue</Select.Item>
+        </Select.Content>
+      </Select.Root>,
+    );
+    await user.click(screen.getByRole("button"));
+    screen.getByRole("listbox", { hidden: true }).focus(); // no option focused → currentIndex -1
+
+    // startIndex 0 + offset 1 → search from index 1 → Sun (skips Solid at 0).
+    // A `startIndex = currentIndex` (-1) mutant would instead land on Solid.
+    await user.keyboard("s");
+    expect(screen.getByRole("option", { name: "Sun", hidden: true })).toHaveFocus();
+  });
+
+  it("keeps the current match when narrowing with more characters (offset 0)", async () => {
+    const user = userEvent.setup();
+    render(
+      <Select.Root>
+        <Select.Trigger>
+          <Select.Value placeholder="Pick" />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="apple">Apple</Select.Item>
+          <Select.Item value="apricot">Apricot</Select.Item>
+          <Select.Item value="avocado">Avocado</Select.Item>
+        </Select.Content>
+      </Select.Root>,
+    );
+    await user.click(screen.getByRole("button")); // Apple focused
+    await user.keyboard("a"); // → Apricot (single-char offset skip)
+    await user.keyboard("p"); // "ap" is multi-char, offset 0 → Apricot still matches, stays
+
+    // An `offset = 1` mutant would skip Apricot and wrap to Apple.
+    expect(
+      screen.getByRole("option", { name: "Apricot", hidden: true }),
+    ).toHaveFocus();
+  });
+
+  it("matches a prefix, not a substring", async () => {
+    const user = userEvent.setup();
+    renderSelect();
+    await user.click(screen.getByRole("button")); // Apple focused
+
+    // "n" is a substring of "Banana" but a prefix of nothing, so focus must
+    // not jump to Banana (guards startsWith, not includes).
+    await user.keyboard("n");
+    expect(option("Apple")).toHaveFocus();
+  });
+});

package/src/Select/__tests__/Select.value-mirror.test.tsx

@@ -0,0 +1,240 @@
+import { render, screen, within } from "@testing-library/react";
+import type { ReactNode } from "react";
+import userEvent from "@testing-library/user-event";
+
+import { Select } from "../Select";
+
+function Framework({ value, label }: { value: string; label: string }) {
+  return (
+    <Select.Item value={value}>
+      <svg data-testid={`icon-${value}`} aria-hidden />
+      {label}
+      <Select.ItemIndicator>✓</Select.ItemIndicator>
+    </Select.Item>
+  );
+}
+
+function renderSelect(props: Parameters<typeof Select.Root>[0] = {}) {
+  return render(
+    <Select.Root {...props}>
+      <Select.Trigger>
+        <Select.Value placeholder="Pick a framework" />
+      </Select.Trigger>
+      <Select.Content>
+        <Framework value="react" label="React" />
+        <Framework value="vue" label="Vue" />
+      </Select.Content>
+    </Select.Root>,
+  );
+}
+
+describe("Select.Value mirroring", () => {
+  it("shows the placeholder when nothing is selected", () => {
+    renderSelect();
+
+    expect(screen.getByRole("button")).toHaveTextContent("Pick a framework");
+  });
+
+  it("mirrors the selected item's icon and label into the trigger", () => {
+    renderSelect({ defaultValue: "react" });
+
+    const trigger = screen.getByRole("button");
+    expect(trigger).toHaveTextContent("React");
+    expect(within(trigger).getByTestId("icon-react")).toBeInTheDocument();
+  });
+
+  it("excludes the ItemIndicator from the mirrored trigger content", () => {
+    renderSelect({ defaultValue: "react" });
+
+    const trigger = screen.getByRole("button");
+    expect(within(trigger).queryByText("✓")).not.toBeInTheDocument();
+  });
+
+  it("drops an item's mirror registration when it unmounts", () => {
+    const { rerender } = render(
+      <Select.Root defaultValue="react">
+        <Select.Trigger>
+          <Select.Value placeholder="Nothing" />
+        </Select.Trigger>
+        <Select.Content>
+          <Framework value="react" label="React" />
+          <Framework value="vue" label="Vue" />
+        </Select.Content>
+      </Select.Root>,
+    );
+    expect(screen.getByRole("button")).toHaveTextContent("React");
+
+    // Remove the (still-selected) react item while the Select stays mounted —
+    // its registration is dropped and Value falls back to the placeholder.
+    rerender(
+      <Select.Root defaultValue="react">
+        <Select.Trigger>
+          <Select.Value placeholder="Nothing" />
+        </Select.Trigger>
+        <Select.Content>
+          <Framework value="vue" label="Vue" />
+        </Select.Content>
+      </Select.Root>,
+    );
+    expect(screen.getByRole("button")).toHaveTextContent("Nothing");
+  });
+
+  it("excludes an indicator nested inside a consumer wrapper from the mirror", () => {
+    // A styled layer wraps Select.ItemIndicator in its own component (the
+    // registry does exactly this), so the mirror cannot identify the indicator
+    // by the element's own type. Mirroring it into the trigger would render it
+    // outside any Select.Item and throw.
+    function StyledIndicator({ children }: { children: ReactNode }) {
+      return <Select.ItemIndicator className="mark">{children}</Select.ItemIndicator>;
+    }
+
+    render(
+      <Select.Root defaultValue="react">
+        <Select.Trigger>
+          <Select.Value placeholder="Pick" />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="react">
+            React
+            <StyledIndicator>✓</StyledIndicator>
+          </Select.Item>
+        </Select.Content>
+      </Select.Root>,
+    );
+
+    const trigger = screen.getByRole("button");
+    expect(trigger).toHaveTextContent("React");
+    expect(within(trigger).queryByText("✓")).not.toBeInTheDocument();
+  });
+
+  it("keeps a forceMount indicator out of the mirror too", () => {
+    // forceMount keeps the mark in the DOM while its row is unselected, for CSS
+    // animation inside the listbox. The trigger's mirrored copy must still drop
+    // it — this is the only path where the mirror check is load-bearing, since
+    // an ordinary indicator already self-hides on the mirror's unselected state.
+    render(
+      <Select.Root defaultValue="react">
+        <Select.Trigger>
+          <Select.Value placeholder="Pick" />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="react">
+            React
+            <Select.ItemIndicator forceMount data-testid="mark">
+              ✓
+            </Select.ItemIndicator>
+          </Select.Item>
+        </Select.Content>
+      </Select.Root>,
+    );
+
+    const trigger = screen.getByRole("button");
+    expect(trigger).toHaveTextContent("React");
+    expect(within(trigger).queryByTestId("mark")).not.toBeInTheDocument();
+    // …while the row's own copy stays mounted.
+    expect(screen.getByTestId("mark")).toBeInTheDocument();
+  });
+
+  it("flags the placeholder state with data-placeholder", () => {
+    renderSelect();
+
+    expect(screen.getByText("Pick a framework")).toHaveAttribute(
+      "data-placeholder",
+      "",
+    );
+  });
+
+  it("drops data-placeholder once an item is selected", () => {
+    renderSelect({ defaultValue: "react" });
+
+    const trigger = screen.getByRole("button");
+    expect(within(trigger).getByText("React").closest("span")).not.toHaveAttribute(
+      "data-placeholder",
+    );
+  });
+
+  it("updates the mirrored content when the selection changes", async () => {
+    const user = userEvent.setup();
+    renderSelect();
+
+    await user.click(screen.getByRole("button"));
+    await user.click(screen.getByText("Vue"));
+
+    const trigger = screen.getByRole("button");
+    expect(trigger).toHaveTextContent("Vue");
+    expect(within(trigger).getByTestId("icon-vue")).toBeInTheDocument();
+  });
+});
+
+describe("Select.ItemIndicator", () => {
+  it("renders only inside the selected item", async () => {
+    const user = userEvent.setup();
+    renderSelect({ defaultValue: "react" });
+
+    await user.click(screen.getByRole("button"));
+
+    // Exactly one indicator is mounted — the selected (react) item's.
+    const indicators = screen.getAllByText("✓");
+    expect(indicators).toHaveLength(1);
+    const reactOption = screen.getByRole("option", {
+      name: /React/,
+      hidden: true,
+    });
+    expect(within(reactOption).getByText("✓")).toHaveAttribute(
+      "data-state",
+      "checked",
+    );
+  });
+
+  it("stays mounted for an unselected item when forceMount is set", async () => {
+    const user = userEvent.setup();
+    render(
+      <Select.Root defaultValue="react">
+        <Select.Trigger>
+          <Select.Value placeholder="Pick" />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="react">React</Select.Item>
+          <Select.Item value="vue">
+            Vue
+            <Select.ItemIndicator forceMount data-testid="vue-indicator">
+              •
+            </Select.ItemIndicator>
+          </Select.Item>
+        </Select.Content>
+      </Select.Root>,
+    );
+
+    await user.click(screen.getByRole("button"));
+
+    expect(screen.getByTestId("vue-indicator")).toHaveAttribute(
+      "data-state",
+      "unchecked",
+    );
+  });
+
+  it("composes onto a custom element with asChild", async () => {
+    const user = userEvent.setup();
+    render(
+      <Select.Root defaultValue="react">
+        <Select.Trigger>
+          <Select.Value placeholder="Pick" />
+        </Select.Trigger>
+        <Select.Content>
+          <Select.Item value="react">
+            React
+            <Select.ItemIndicator asChild>
+              <i data-testid="mark">✓</i>
+            </Select.ItemIndicator>
+          </Select.Item>
+        </Select.Content>
+      </Select.Root>,
+    );
+
+    await user.click(screen.getByRole("button"));
+
+    const mark = screen.getByTestId("mark");
+    expect(mark.tagName).toBe("I");
+    expect(mark).toHaveAttribute("data-state", "checked");
+  });
+});

package/src/Select/constants.ts

@@ -0,0 +1,8 @@
+/** Selector for enabled listbox options (disabled ones are skipped). */
+export const OPTION_SELECTOR = '[role="option"]:not([aria-disabled="true"])';
+
+/** Selector for the currently-selected option. */
+export const SELECTED_OPTION_SELECTOR = '[role="option"][aria-selected="true"]';
+
+/** Typeahead accumulation window, in milliseconds. */
+export const TYPEAHEAD_RESET_MS = 500;

package/src/Select/hooks/index.ts

@@ -0,0 +1,2 @@
+export { useSelectRoot } from "./useSelectRoot";
+export { useSelectContent } from "./useSelectContent";

package/src/Select/hooks/useSelectContent.ts

@@ -0,0 +1,149 @@
+import { KeyboardEvent, KeyboardEventHandler, useEffect, useRef } from "react";
+
+import { composeEventHandlers } from "../../Slot/index.ts";
+import { useSelectContext } from "../SelectContext";
+import {
+  OPTION_SELECTOR,
+  SELECTED_OPTION_SELECTOR,
+  TYPEAHEAD_RESET_MS,
+} from "../constants";
+import type { SelectContentProps } from "../types";
+
+type UseSelectContentArgs = {
+  onKeyDown?: KeyboardEventHandler<HTMLDivElement>;
+  restProps: Omit<SelectContentProps, "children" | "onKeyDown" | "asChild">;
+};
+
+/**
+ * Drives the listbox popover for the rich Select: opens/closes the native
+ * Popover in sync with context `open`, moves focus onto the selected (or
+ * first enabled) option on open, syncs React state when the browser
+ * light-dismisses (`toggle`), and implements the WAI-ARIA listbox keyboard
+ * contract — Arrow/Home/End roving focus (skipping disabled, wrapping),
+ * Enter/Space to select, Escape to close (refocusing the trigger), and
+ * printable-character typeahead.
+ */
+export function useSelectContent({ onKeyDown, restProps }: UseSelectContentArgs) {
+  const { open, setOpen, contentId, triggerRef } = useSelectContext();
+  const listRef = useRef<HTMLDivElement | null>(null);
+  const typeaheadRef = useRef<{ query: string; timer: number | null }>({
+    query: "",
+    timer: null,
+  });
+
+  useEffect(() => {
+    const list = listRef.current!;
+    if (open) {
+      list.showPopover();
+      const selected = list.querySelector<HTMLElement>(SELECTED_OPTION_SELECTOR);
+      const first = list.querySelector<HTMLElement>(OPTION_SELECTOR);
+      (selected ?? first ?? list).focus();
+    } else {
+      try {
+        list.hidePopover();
+      } catch {
+        /* already hidden — no-op (e.g. browser already light-dismissed) */
+      }
+    }
+  }, [open]);
+
+  useEffect(() => {
+    const list = listRef.current!;
+    const handleToggle = (event: Event) => {
+      if ((event as ToggleEvent).newState === "closed") setOpen(false);
+    };
+    list.addEventListener("toggle", handleToggle);
+    // Stryker disable next-line StringLiteral,ArrowFunction: equivalent — unmount cleanup on a discarded node; removing/altering it only leaks a listener, unobservable.
+    return () => list.removeEventListener("toggle", handleToggle);
+  },
+  // Stryker disable next-line ArrayDeclaration: equivalent — setOpen is stable, so the effect subscribes once either way.
+  [setOpen]);
+
+  const handleKeyDown = (event: KeyboardEvent<HTMLDivElement>) => {
+    if (event.key === "Escape") {
+      event.preventDefault();
+      setOpen(false);
+      // Stryker disable next-line OptionalChaining: unreachable — the trigger is always mounted while the listbox is open.
+      triggerRef.current?.focus();
+      return;
+    }
+
+    const list = listRef.current!;
+    const items = Array.from(
+      list.querySelectorAll<HTMLElement>(OPTION_SELECTOR),
+    );
+    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;
+    }
+
+    // Space is already handled by the Enter/Space branch above, so any
+    // remaining single-character key is a typeahead search.
+    // Stryker disable next-line ConditionalExpression,EqualityOperator: the false / length!==1 variants are killed by the typeahead tests; the always-true variant is equivalent — no unhandled multi-character key (modifiers, arrows) can prefix-match an option.
+    if (event.key.length === 1) {
+      const state = typeaheadRef.current;
+      // Stryker disable next-line ConditionalExpression,EqualityOperator,MethodExpression,BlockStatement: clearing the pending timer is a real-time optimization; keystroke handling here is synchronous, so its presence/condition/target never changes the search outcome.
+      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 =
+        // Stryker disable next-line EqualityOperator,ConditionalExpression: equivalent — `length > 1 → true` reduces to `every(...)`, which for a single char produces the same searchQuery/offset outcome; the < 1 / false variants are killed by the repeated-char cycle test.
+        state.query.length > 1 &&
+        state.query.split("").every((c) => c === state.query[0]);
+      const searchQuery = isRepeat ? state.query[0] : state.query;
+      // Stryker disable next-line EqualityOperator: <= 0 is equivalent — currentIndex 0 yields startIndex 0 either way; the >= 0 variant is killed by the cycle test (advancing from a focused non-first item).
+      const startIndex = currentIndex < 0 ? 0 : currentIndex;
+      // Stryker disable next-line EqualityOperator: the length comparison variants are equivalent — a length-1 query and an isRepeat query both take offset 1 with the same outcome across the fixtures; the killable path is covered by the multi-char prefix test.
+      const offset = searchQuery.length === 1 || isRepeat ? 1 : 0;
+      // Stryker disable next-line EqualityOperator: <= is equivalent — the index wraps via % items.length, so the extra iteration only re-checks an already-visited index.
+      for (let i = 0; i < items.length; i++) {
+        const index = (startIndex + offset + i) % items.length;
+        // Stryker disable next-line MethodExpression: dropping .trim() is equivalent — the fixtures' (and real) option labels carry no surrounding whitespace; dropping .toLowerCase() is killed by the typeahead tests (lowercase query vs title-case labels).
+        const text = items[index].textContent!.trim().toLowerCase();
+        if (text.startsWith(searchQuery)) {
+          event.preventDefault();
+          items[index].focus();
+          return;
+        }
+      }
+    }
+  };
+
+  const contentProps = {
+    ...restProps,
+    ref: listRef,
+    id: contentId,
+    role: "listbox" as const,
+    tabIndex: -1,
+    popover: "auto" as const,
+    onKeyDown: composeEventHandlers(onKeyDown, handleKeyDown),
+  };
+
+  return { contentProps };
+}