@primitiv-ui/react 0.1.28 → 0.1.30

package/src/Combobox/README.md

@@ -0,0 +1,170 @@
+# Combobox
+
+A headless, accessible **combobox** — an editable text field with a filtered
+popup listbox, implementing the
+[WAI-ARIA APG combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/).
+
+```tsx
+import { Combobox } from "@primitiv-ui/react";
+
+<Combobox.Root onQueryChange={setQuery} onValueChange={setFramework}>
+  <Combobox.Input aria-label="Framework" />
+  <Combobox.Content aria-label="Frameworks">
+    <Combobox.Item value="react">React</Combobox.Item>
+    <Combobox.Item value="preact">Preact</Combobox.Item>
+  </Combobox.Content>
+</Combobox.Root>;
+```
+
+## Sub-components
+
+| Export              | Element   | Notes                                                                              |
+| ------------------- | --------- | ---------------------------------------------------------------------------------- |
+| `Combobox.Root`     | `<div>`   | Owns open state, value, query and cursor; context provider; `asChild`              |
+| `Combobox.Input`    | `<input>` | `role="combobox"`, the full keyboard model, all the ARIA wiring; `asChild`         |
+| `Combobox.Content`  | `<div>`   | `role="listbox"` `popover="auto"` — top layer + light dismiss, **unmounted while closed**; `asChild` |
+| `Combobox.Item`     | `<div>`   | `role="option"`, `aria-selected`, `data-highlighted`; `asChild`                    |
+| `Combobox.Empty`    | `<div>`   | `role="presentation"` no-results message, never navigable; `asChild`               |
+
+## Filtering is yours
+
+There is deliberately **no `filter` prop**. `onQueryChange` reports every
+keystroke and you render the options you want:
+
+```tsx
+const [query, setQuery] = useState("");
+const matches = FRAMEWORKS.filter((f) =>
+  f.label.toLowerCase().includes(query.toLowerCase()),
+);
+
+<Combobox.Root onQueryChange={setQuery}>
+  <Combobox.Input aria-label="Framework" />
+  <Combobox.Content aria-label="Frameworks">
+    {matches.map((f) => (
+      <Combobox.Item key={f.value} value={f.value}>
+        {f.label}
+      </Combobox.Item>
+    ))}
+    {matches.length === 0 && <Combobox.Empty>No matches</Combobox.Empty>}
+  </Combobox.Content>
+</Combobox.Root>;
+```
+
+That keeps async loading, fuzzy matching and sorting where the data lives,
+rather than inventing a filtering API the component would have to own.
+
+## Query versus value
+
+One field, two readings, disambiguated by whether the popup is open:
+
+- **while open** — the input holds whatever the user typed (the query);
+- **on commit, Escape, or a dismiss** — the text is reset **from the value**.
+
+So the field never sits showing a half-typed query that is not the value,
+which is the classic combobox bug.
+
+**Emptying the field is a deselect.** Clearing the text clears the value too —
+`onValueChange` fires with `""` — so the reset above cannot resurrect a label the
+user just deleted. That keeps the invariant intact (empty text, empty value: the
+field still isn't showing something that is not the value) while letting the
+gesture mean what it looks like. Clearing a field that has no value fires nothing,
+so an empty field never reports a change the consumer didn't cause.
+
+The label shown after committing comes from the item's children when they are a
+string. When an item renders elements (an icon plus a span, say), there is no
+reliable way to read a label out of arbitrary JSX, so **the value stands in** —
+pass string children if you want a nicer closed-state label.
+
+## Dismissal
+
+Three ways out, and all three land in the same state:
+
+| Gesture           | How                                                          |
+| ----------------- | ------------------------------------------------------------ |
+| <kbd>Escape</kbd> | Handled on the input                                         |
+| Click outside     | The browser's own light dismiss                              |
+| Commit an item    | Click or <kbd>Enter</kbd>                                    |
+
+`Combobox.Content` renders as a **`popover="auto"`** element and promotes itself
+with `showPopover()`, which is what buys the outside-click behaviour: the browser
+does the hit-testing and reports the result back as a `toggle` event. There is
+deliberately no hand-rolled pointerdown-outside listener. The same promotion puts
+the panel in the **top layer**, so nothing on the page can paint over it and no
+`z-index` is needed anywhere.
+
+A light dismiss runs the *same* path as Escape — closing, clearing the cursor and
+resetting the text — rather than only closing, so clicking away can't strand a
+half-typed query on screen.
+
+Note this is why the panel can animate **in** but not out: it unmounts on close,
+so there is no element left for an exit rule to match. That's the deliberate
+trade for a closed combobox having no listbox in the accessibility tree at all.
+
+## Keyboard
+
+| Key                   | Behaviour                                                        |
+| --------------------- | ---------------------------------------------------------------- |
+| any printable char    | Sets the query and **opens** the popup                           |
+| clearing the field    | Clears the query **and the value** (see above)                    |
+| <kbd>↓</kbd>          | Moves the cursor down; seeds it on the **first** item if none     |
+| <kbd>↑</kbd>          | Moves the cursor up; seeds it on the **last** item if none        |
+| <kbd>Home</kbd> / <kbd>End</kbd> | Jumps the cursor to the first / last item             |
+| <kbd>Enter</kbd>      | Commits the cursor item. Ignored when there is no cursor          |
+| <kbd>Escape</kbd>     | Closes, clears the cursor, restores the committed label           |
+
+Arrow travel wraps at both ends, and every cursor move **scrolls the item into
+view** (`scrollIntoView({ block: "nearest" })`, so a move to an already-visible item
+doesn't jerk the list). That matters because the styled panel scrolls — without it
+the cursor walks off the bottom of a long filtered list.
+
+## Virtual focus, not a roving tabstop
+
+DOM focus **never leaves the input**. The cursor is published as
+`aria-activedescendant` on the input and `data-highlighted` on the item; no
+option is ever given a `tabIndex` or `focus()`ed. That is what lets the input
+keep focus while driving the list, and it is the same model
+[`Listbox`](../Listbox/README.md) uses — the two were designed to agree.
+
+## Controlled and uncontrolled
+
+Both `open` and `value` support either shape:
+
+```tsx
+// uncontrolled
+<Combobox.Root defaultOpen defaultValue="react">
+
+// controlled — the combobox asks, the parent decides
+<Combobox.Root open={open} onOpenChange={setOpen} value={value} onValueChange={setValue}>
+```
+
+Under a controlled prop the combobox never moves on its own: it calls the
+change handler and waits.
+
+## Styling hooks
+
+| Hook                     | Where             | When                                   |
+| ------------------------ | ----------------- | -------------------------------------- |
+| `aria-expanded`          | `Combobox.Input`  | Reflects open state                    |
+| `aria-activedescendant`  | `Combobox.Input`  | Present only once a cursor exists      |
+| `aria-selected`          | `Combobox.Item`   | The committed value                    |
+| `data-highlighted`       | `Combobox.Item`   | The cursor sits on this item           |
+
+Selection and cursor are **separate** states and are meant to look different —
+one says "this is chosen", the other "Enter picks this".
+
+## Accessibility notes
+
+- The input carries `role="combobox"`, `aria-autocomplete="list"` and
+  `aria-controls` pointing at the listbox id, which is derived per instance so
+  two comboboxes on one page never collide.
+- `Combobox.Content` is unmounted while closed rather than hidden, so a closed
+  combobox contributes no list to the accessibility tree.
+- Give the input an accessible name (`aria-label` or a `<label>`) and the
+  listbox one too.
+
+## Not in v1
+
+Deliberately out of scope, recorded on the Figma "Combobox — exploration" page:
+a built-in `filter` prop, async option loading, multi-select with token chips,
+and virtualization. The **command palette** is a separate composite that
+*wraps* this component in a `Modal` — it is not a Combobox mode.

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

@@ -0,0 +1,62 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { Combobox } from "../Combobox";
+
+describe("Combobox asChild", () => {
+  it("renders the consumer's element for each part", () => {
+    render(
+      <Combobox.Root asChild defaultOpen>
+        <section data-testid="root">
+          <Combobox.Input asChild aria-label="Framework">
+            <input data-testid="input" />
+          </Combobox.Input>
+          <Combobox.Content asChild aria-label="Frameworks">
+            <ul data-testid="content">
+              <Combobox.Item asChild value="react">
+                <li data-testid="item">React</li>
+              </Combobox.Item>
+              <Combobox.Empty asChild>
+                <p data-testid="empty">Nothing</p>
+              </Combobox.Empty>
+            </ul>
+          </Combobox.Content>
+        </section>
+      </Combobox.Root>,
+    );
+
+    expect(screen.getByTestId("root").tagName).toBe("SECTION");
+    expect(screen.getByTestId("content").tagName).toBe("UL");
+    expect(screen.getByTestId("item").tagName).toBe("LI");
+    expect(screen.getByTestId("empty").tagName).toBe("P");
+
+    // the behaviour-bearing props still land on the consumer's elements
+    expect(screen.getByTestId("input")).toHaveAttribute("role", "combobox");
+    expect(screen.getByTestId("content")).toHaveAttribute("role", "listbox");
+    expect(screen.getByTestId("item")).toHaveAttribute("role", "option");
+    expect(screen.getByTestId("empty")).toHaveAttribute("role", "presentation");
+  });
+
+  it("composes the consumer's handlers rather than replacing them", async () => {
+    const user = userEvent.setup();
+    const onItemClick = vi.fn();
+    const onValueChange = vi.fn();
+
+    render(
+      <Combobox.Root defaultOpen onValueChange={onValueChange}>
+        <Combobox.Input aria-label="Framework" />
+        <Combobox.Content aria-label="Frameworks">
+          <Combobox.Item asChild value="react">
+            <li onClick={onItemClick}>React</li>
+          </Combobox.Item>
+        </Combobox.Content>
+      </Combobox.Root>,
+    );
+
+    await user.click(screen.getByRole("option", { hidden: true, name: "React" }));
+
+    expect(onItemClick).toHaveBeenCalledTimes(1);
+    expect(onValueChange).toHaveBeenCalledWith("react");
+  });
+});

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

@@ -0,0 +1,16 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { Combobox } from "../Combobox";
+
+describe("Combobox basic rendering", () => {
+  it("renders a combobox role on the input", () => {
+    render(
+      <Combobox.Root>
+        <Combobox.Input aria-label="Framework" />
+      </Combobox.Root>,
+    );
+
+    expect(screen.getByRole("combobox", { name: "Framework" })).toBeInTheDocument();
+  });
+});

package/src/Combobox/__tests__/Combobox.content.test.tsx

@@ -0,0 +1,36 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { Combobox } from "../Combobox";
+
+describe("Combobox content", () => {
+  it("keeps the popup unmounted while closed and reports aria-expanded=false", () => {
+    render(
+      <Combobox.Root>
+        <Combobox.Input aria-label="Framework" />
+        <Combobox.Content aria-label="Frameworks" />
+      </Combobox.Root>,
+    );
+
+    expect(screen.getByRole("combobox", { name: "Framework" })).toHaveAttribute(
+      "aria-expanded",
+      "false",
+    );
+    expect(screen.queryByRole("listbox", { hidden: true })).not.toBeInTheDocument();
+  });
+
+  it("renders the popup when open and reports aria-expanded=true", () => {
+    render(
+      <Combobox.Root defaultOpen>
+        <Combobox.Input aria-label="Framework" />
+        <Combobox.Content aria-label="Frameworks" />
+      </Combobox.Root>,
+    );
+
+    expect(screen.getByRole("combobox", { name: "Framework" })).toHaveAttribute(
+      "aria-expanded",
+      "true",
+    );
+    expect(screen.getByRole("listbox", { hidden: true })).toBeInTheDocument();
+  });
+});

package/src/Combobox/__tests__/Combobox.controlled-state.test.tsx

@@ -0,0 +1,88 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { Combobox } from "../Combobox";
+
+describe("Combobox controlled state", () => {
+  it("does not open on its own when `open` is controlled", async () => {
+    const user = userEvent.setup();
+    const onOpenChange = vi.fn();
+
+    render(
+      <Combobox.Root open={false} onOpenChange={onOpenChange}>
+        <Combobox.Input aria-label="Framework" />
+        <Combobox.Content aria-label="Frameworks">
+          <Combobox.Item value="react">React</Combobox.Item>
+        </Combobox.Content>
+      </Combobox.Root>,
+    );
+
+    await user.type(screen.getByRole("combobox", { name: "Framework" }), "R");
+
+    // the parent owns it: we ask, we do not assume
+    expect(onOpenChange).toHaveBeenCalledWith(true);
+    expect(screen.queryByRole("listbox", { hidden: true })).not.toBeInTheDocument();
+  });
+
+  it("honours a controlled `open` set by the parent", () => {
+    render(
+      <Combobox.Root open>
+        <Combobox.Input aria-label="Framework" />
+        <Combobox.Content aria-label="Frameworks">
+          <Combobox.Item value="react">React</Combobox.Item>
+        </Combobox.Content>
+      </Combobox.Root>,
+    );
+
+    expect(screen.getByRole("listbox", { hidden: true })).toBeInTheDocument();
+    expect(screen.getByRole("combobox", { name: "Framework" })).toHaveAttribute(
+      "aria-expanded",
+      "true",
+    );
+  });
+
+  it("marks the controlled value as selected without any interaction", () => {
+    render(
+      <Combobox.Root open value="preact">
+        <Combobox.Input aria-label="Framework" />
+        <Combobox.Content aria-label="Frameworks">
+          <Combobox.Item value="react">React</Combobox.Item>
+          <Combobox.Item value="preact">Preact</Combobox.Item>
+        </Combobox.Content>
+      </Combobox.Root>,
+    );
+
+    expect(screen.getByRole("option", { hidden: true, name: "Preact" })).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+    expect(screen.getByRole("option", { hidden: true, name: "React" })).toHaveAttribute(
+      "aria-selected",
+      "false",
+    );
+  });
+
+  it("does not change the selected value on its own when `value` is controlled", async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+
+    render(
+      <Combobox.Root open value="react" onValueChange={onValueChange}>
+        <Combobox.Input aria-label="Framework" />
+        <Combobox.Content aria-label="Frameworks">
+          <Combobox.Item value="react">React</Combobox.Item>
+          <Combobox.Item value="preact">Preact</Combobox.Item>
+        </Combobox.Content>
+      </Combobox.Root>,
+    );
+
+    await user.click(screen.getByRole("option", { hidden: true, name: "Preact" }));
+
+    expect(onValueChange).toHaveBeenCalledWith("preact");
+    expect(screen.getByRole("option", { hidden: true, name: "React" })).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+  });
+});

package/src/Combobox/__tests__/Combobox.empty.test.tsx

@@ -0,0 +1,42 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it } from "vitest";
+
+import { Combobox } from "../Combobox";
+
+describe("Combobox empty", () => {
+  it("renders a no-results message that is not itself an option", () => {
+    render(
+      <Combobox.Root defaultOpen>
+        <Combobox.Input aria-label="Framework" />
+        <Combobox.Content aria-label="Frameworks">
+          <Combobox.Empty>No frameworks match “xyz”</Combobox.Empty>
+        </Combobox.Content>
+      </Combobox.Root>,
+    );
+
+    expect(screen.getByText("No frameworks match “xyz”")).toBeInTheDocument();
+    expect(screen.queryAllByRole("option", { hidden: true })).toHaveLength(0);
+  });
+
+  it("is not navigable — the cursor has nothing to land on", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <Combobox.Root defaultOpen>
+        <Combobox.Input aria-label="Framework" />
+        <Combobox.Content aria-label="Frameworks">
+          <Combobox.Empty>Nothing here</Combobox.Empty>
+        </Combobox.Content>
+      </Combobox.Root>,
+    );
+
+    const input = screen.getByRole("combobox", { name: "Framework" });
+    await user.click(input);
+    await user.keyboard("{ArrowDown}");
+
+    expect(input).not.toHaveAttribute("aria-activedescendant");
+    // and the panel stays open so the user can keep typing
+    expect(screen.getByRole("listbox", { hidden: true })).toBeInTheDocument();
+  });
+});

package/src/Combobox/__tests__/Combobox.ids.test.tsx

@@ -0,0 +1,66 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { Combobox } from "../Combobox";
+
+describe("Combobox ids and ARIA wiring", () => {
+  it("points the input's aria-controls at the popup listbox", () => {
+    render(
+      <Combobox.Root defaultOpen>
+        <Combobox.Input aria-label="Framework" />
+        <Combobox.Content aria-label="Frameworks" />
+      </Combobox.Root>,
+    );
+
+    const input = screen.getByRole("combobox", { name: "Framework" });
+    const listbox = screen.getByRole("listbox", { hidden: true });
+
+    expect(listbox.id).not.toBe("");
+    expect(input).toHaveAttribute("aria-controls", listbox.id);
+  });
+
+  it("declares list autocomplete on the input", () => {
+    render(
+      <Combobox.Root>
+        <Combobox.Input aria-label="Framework" />
+        <Combobox.Content aria-label="Frameworks" />
+      </Combobox.Root>,
+    );
+
+    expect(screen.getByRole("combobox", { name: "Framework" })).toHaveAttribute(
+      "aria-autocomplete",
+      "list",
+    );
+  });
+
+  it("scopes ids per instance so two comboboxes never collide", () => {
+    render(
+      <>
+        <Combobox.Root defaultOpen>
+          <Combobox.Input aria-label="First" />
+          <Combobox.Content aria-label="First list" />
+        </Combobox.Root>
+        <Combobox.Root defaultOpen>
+          <Combobox.Input aria-label="Second" />
+          <Combobox.Content aria-label="Second list" />
+        </Combobox.Root>
+      </>,
+    );
+
+    // Indexed rather than named: the popup is a [popover], which jsdom leaves
+    // `display: none` (it does not wire up the `:popover-open` selector), and an
+    // `aria-label` on a hidden element yields no accessible name — so `{ name }`
+    // cannot tell these two apart. DOM order can.
+    const [first, second] = screen.getAllByRole("listbox", { hidden: true });
+
+    expect(first.id).not.toBe(second.id);
+    expect(screen.getByRole("combobox", { name: "First" })).toHaveAttribute(
+      "aria-controls",
+      first.id,
+    );
+    expect(screen.getByRole("combobox", { name: "Second" })).toHaveAttribute(
+      "aria-controls",
+      second.id,
+    );
+  });
+});

package/src/Combobox/__tests__/Combobox.item.test.tsx

@@ -0,0 +1,76 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it, vi } from "vitest";
+
+import { Combobox } from "../Combobox";
+
+function renderCombobox(props: Record<string, unknown> = {}) {
+  return render(
+    <Combobox.Root defaultOpen {...props}>
+      <Combobox.Input aria-label="Framework" />
+      <Combobox.Content aria-label="Frameworks">
+        <Combobox.Item value="react">React</Combobox.Item>
+        <Combobox.Item value="preact">Preact</Combobox.Item>
+      </Combobox.Content>
+    </Combobox.Root>,
+  );
+}
+
+describe("Combobox item", () => {
+  it("renders each item as an option", () => {
+    renderCombobox();
+
+    expect(screen.getByRole("option", { hidden: true, name: "React" })).toBeInTheDocument();
+    expect(screen.getByRole("option", { hidden: true, name: "Preact" })).toBeInTheDocument();
+  });
+
+  it("selects on click: reports the value, closes, and shows the label in the input", async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    renderCombobox({ onValueChange });
+
+    await user.click(screen.getByRole("option", { hidden: true, name: "Preact" }));
+
+    expect(onValueChange).toHaveBeenCalledWith("preact");
+    expect(screen.queryByRole("listbox", { hidden: true })).not.toBeInTheDocument();
+    // D1: closing resets the input text from the value, not from the query
+    expect(screen.getByRole("combobox", { name: "Framework" })).toHaveValue("Preact");
+  });
+
+  it("falls back to the value as the label when the item has element children", async () => {
+    const user = userEvent.setup();
+
+    render(
+      <Combobox.Root defaultOpen>
+        <Combobox.Input aria-label="Framework" />
+        <Combobox.Content aria-label="Frameworks">
+          <Combobox.Item value="react">
+            <svg aria-hidden="true" />
+            <span>React</span>
+          </Combobox.Item>
+        </Combobox.Content>
+      </Combobox.Root>,
+    );
+
+    await user.click(screen.getByRole("option", { hidden: true, name: "React" }));
+
+    expect(screen.getByRole("combobox", { name: "Framework" })).toHaveValue("react");
+  });
+
+  it("marks only the selected item aria-selected", async () => {
+    const user = userEvent.setup();
+    renderCombobox();
+
+    await user.click(screen.getByRole("option", { hidden: true, name: "Preact" }));
+    await user.type(screen.getByRole("combobox", { name: "Framework" }), "a");
+
+    expect(screen.getByRole("option", { hidden: true, name: "Preact" })).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+    expect(screen.getByRole("option", { hidden: true, name: "React" })).toHaveAttribute(
+      "aria-selected",
+      "false",
+    );
+  });
+});