@primitiv-ui/react 0.1.38 → 0.1.39

package/src/Combobox/README.md

@@ -1,170 +0,0 @@
-# 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

@@ -1,62 +0,0 @@
-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

@@ -1,16 +0,0 @@
-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

@@ -1,36 +0,0 @@
-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

@@ -1,88 +0,0 @@
-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

@@ -1,42 +0,0 @@
-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

@@ -1,66 +0,0 @@
-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

@@ -1,76 +0,0 @@
-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",
-    );
-  });
-});