@primitiv-ui/react 0.1.28 → 0.1.30

package/src/Listbox/__tests__/Listbox.fixtures.ts

@@ -0,0 +1,27 @@
+/** Three options, enough to exercise wrap-around in both directions. */
+export const fruits = [
+  { value: "apple", label: "Apple" },
+  { value: "banana", label: "Banana" },
+  { value: "cherry", label: "Cherry" },
+] as const;
+
+/**
+ * Cursor movement cases for a vertical listbox. `from` seeds the cursor via
+ * `defaultValue`; `expected` is the option the key should move it to.
+ */
+export const cursorKeyCases = [
+  { key: "{ArrowDown}", from: "apple", expected: "Banana" },
+  { key: "{ArrowDown}", from: "cherry", expected: "Apple" },
+  { key: "{ArrowUp}", from: "banana", expected: "Apple" },
+  { key: "{ArrowUp}", from: "apple", expected: "Cherry" },
+  { key: "{Home}", from: "cherry", expected: "Apple" },
+  { key: "{End}", from: "apple", expected: "Cherry" },
+] as const;
+
+/** Four options with overlapping prefixes, for typeahead cycling. */
+export const typeaheadOptions = [
+  { value: "apple", label: "Apple" },
+  { value: "apricot", label: "Apricot" },
+  { value: "avocado", label: "Avocado" },
+  { value: "banana", label: "Banana" },
+] as const;

package/src/Listbox/__tests__/Listbox.group-label.test.tsx

@@ -0,0 +1,97 @@
+import { render, screen } from "@testing-library/react";
+import { describe, expect, it } from "vitest";
+
+import { Listbox } from "../Listbox";
+
+/**
+ * APG's grouped-options example names each group with `aria-labelledby`
+ * pointing at a *visible* heading inside the group, not an invisible
+ * `aria-label`. `Listbox.GroupLabel` renders that heading and wires the id.
+ */
+describe("Listbox group label", () => {
+  it("names the group from a visible heading", () => {
+    render(
+      <Listbox.Root type="single" aria-label="Animals">
+        <Listbox.Group>
+          <Listbox.GroupLabel>Land</Listbox.GroupLabel>
+          <Listbox.Option value="cat">Cat</Listbox.Option>
+        </Listbox.Group>
+      </Listbox.Root>,
+    );
+
+    const group = screen.getByRole("group", { name: "Land" });
+    const heading = screen.getByText("Land");
+    expect(group).toHaveAttribute("aria-labelledby", heading.id);
+    expect(heading).toBeVisible();
+    // Only one naming attribute: emitting both would be misleading, since
+    // aria-labelledby silently outranks aria-label.
+    expect(group).not.toHaveAttribute("aria-label");
+  });
+
+  it("lets the rendered heading win over the label prop when both are given", () => {
+    render(
+      <Listbox.Root type="single" aria-label="Animals">
+        <Listbox.Group label="Water">
+          <Listbox.GroupLabel>Land</Listbox.GroupLabel>
+          <Listbox.Option value="cat">Cat</Listbox.Option>
+        </Listbox.Group>
+      </Listbox.Root>,
+    );
+
+    const group = screen.getByRole("group", { name: "Land" });
+    expect(group).toHaveAttribute(
+      "aria-labelledby",
+      screen.getByText("Land").id,
+    );
+    // The label prop is dropped rather than emitted alongside. The test above
+    // cannot show this: with no label prop, aria-label is absent either way.
+    expect(group).not.toHaveAttribute("aria-label");
+  });
+
+  it("keeps the heading out of the option list", () => {
+    render(
+      <Listbox.Root type="single" aria-label="Animals">
+        <Listbox.Group>
+          <Listbox.GroupLabel>Land</Listbox.GroupLabel>
+          <Listbox.Option value="cat">Cat</Listbox.Option>
+        </Listbox.Group>
+      </Listbox.Root>,
+    );
+
+    expect(screen.getByText("Land")).toHaveAttribute("role", "presentation");
+    expect(screen.getAllByRole("option")).toHaveLength(1);
+  });
+
+  it("still supports the invisible label prop", () => {
+    render(
+      <Listbox.Root type="single" aria-label="Animals">
+        <Listbox.Group label="Water">
+          <Listbox.Option value="cod">Cod</Listbox.Option>
+        </Listbox.Group>
+      </Listbox.Root>,
+    );
+
+    const group = screen.getByRole("group", { name: "Water" });
+    expect(group).toHaveAttribute("aria-label", "Water");
+    expect(group).not.toHaveAttribute("aria-labelledby");
+  });
+
+  it("gives each group its own heading id", () => {
+    render(
+      <Listbox.Root type="single" aria-label="Animals">
+        <Listbox.Group>
+          <Listbox.GroupLabel>Land</Listbox.GroupLabel>
+          <Listbox.Option value="cat">Cat</Listbox.Option>
+        </Listbox.Group>
+        <Listbox.Group>
+          <Listbox.GroupLabel>Water</Listbox.GroupLabel>
+          <Listbox.Option value="cod">Cod</Listbox.Option>
+        </Listbox.Group>
+      </Listbox.Root>,
+    );
+
+    expect(screen.getByText("Land").id).not.toBe(screen.getByText("Water").id);
+    expect(screen.getByRole("group", { name: "Land" })).toBeInTheDocument();
+    expect(screen.getByRole("group", { name: "Water" })).toBeInTheDocument();
+  });
+});

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

@@ -0,0 +1,45 @@
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, expect, it } from "vitest";
+
+import { Listbox } from "../Listbox";
+
+describe("Listbox group", () => {
+  it("names each group for assistive technology", () => {
+    render(
+      <Listbox.Root type="single" aria-label="Fruits">
+        <Listbox.Group label="Citrus">
+          <Listbox.Option value="lemon">Lemon</Listbox.Option>
+        </Listbox.Group>
+        <Listbox.Group label="Berries">
+          <Listbox.Option value="fig">Fig</Listbox.Option>
+        </Listbox.Group>
+      </Listbox.Root>,
+    );
+
+    expect(screen.getByRole("group", { name: "Citrus" })).toBeInTheDocument();
+    expect(screen.getByRole("group", { name: "Berries" })).toBeInTheDocument();
+  });
+
+  it("navigates across group boundaries in DOM order", async () => {
+    const user = userEvent.setup();
+    render(
+      <Listbox.Root type="single" aria-label="Fruits">
+        <Listbox.Group label="Citrus">
+          <Listbox.Option value="lemon">Lemon</Listbox.Option>
+        </Listbox.Group>
+        <Listbox.Group label="Berries">
+          <Listbox.Option value="fig">Fig</Listbox.Option>
+        </Listbox.Group>
+      </Listbox.Root>,
+    );
+
+    await user.tab();
+    await user.keyboard("{ArrowDown}");
+
+    expect(screen.getByRole("listbox")).toHaveAttribute(
+      "aria-activedescendant",
+      screen.getByRole("option", { name: "Fig" }).id,
+    );
+  });
+});

package/src/Listbox/__tests__/Listbox.keyboard-edge-cases.test.tsx

@@ -0,0 +1,144 @@
+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 keyboard edge cases", () => {
+  it("absorbs typeahead on a listbox with nothing to navigate", async () => {
+    const user = userEvent.setup();
+    render(<Listbox.Root type="single" aria-label="Fruits" />);
+
+    await user.tab();
+    await user.keyboard("a");
+
+    expect(screen.getByRole("listbox")).not.toHaveAttribute(
+      "aria-activedescendant",
+    );
+  });
+
+  it("absorbs typeahead when every option is disabled", async () => {
+    const user = userEvent.setup();
+    render(
+      <Listbox.Root type="single" aria-label="Fruits">
+        {fruits.map((fruit) => (
+          <Listbox.Option key={fruit.value} value={fruit.value} disabled>
+            {fruit.label}
+          </Listbox.Option>
+        ))}
+      </Listbox.Root>,
+    );
+
+    await user.tab();
+    await user.keyboard("b");
+
+    expect(screen.getByRole("listbox")).not.toHaveAttribute(
+      "aria-activedescendant",
+    );
+  });
+
+  it("ignores arrow keys on a listbox with nothing to navigate", async () => {
+    const user = userEvent.setup();
+    render(<Listbox.Root type="single" aria-label="Fruits" />);
+
+    await user.tab();
+    await user.keyboard("{ArrowDown}{End}");
+
+    expect(screen.getByRole("listbox")).not.toHaveAttribute(
+      "aria-activedescendant",
+    );
+  });
+
+  it("has nothing to select when Enter arrives with no cursor", async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    const { rerender } = render(
+      <Listbox.Root
+        type="single"
+        onValueChange={onValueChange}
+        aria-label="Fruits"
+      />,
+    );
+
+    await user.tab();
+    rerender(
+      <Listbox.Root
+        type="single"
+        onValueChange={onValueChange}
+        aria-label="Fruits"
+      >
+        {fruits.map((fruit) => (
+          <Listbox.Option key={fruit.value} value={fruit.value}>
+            {fruit.label}
+          </Listbox.Option>
+        ))}
+      </Listbox.Root>,
+    );
+
+    await user.keyboard("{Enter}");
+
+    expect(onValueChange).not.toHaveBeenCalled();
+  });
+
+  it.each([
+    ["{ArrowDown}", "Apple"],
+    ["{ArrowUp}", "Cherry"],
+  ])(
+    "%s enters the list at %s when options arrived after focus",
+    async (key, expected) => {
+      const user = userEvent.setup();
+      const { rerender } = render(
+        <Listbox.Root type="single" aria-label="Fruits" />,
+      );
+
+      await user.tab();
+      rerender(
+        <Listbox.Root type="single" aria-label="Fruits">
+          {fruits.map((fruit) => (
+            <Listbox.Option key={fruit.value} value={fruit.value}>
+              {fruit.label}
+            </Listbox.Option>
+          ))}
+        </Listbox.Root>,
+      );
+
+      await user.keyboard(key);
+
+      expect(screen.getByRole("listbox")).toHaveAttribute(
+        "aria-activedescendant",
+        screen.getByRole("option", { name: expected }).id,
+      );
+    },
+  );
+
+  // The search-suggestions case: the listbox is focused while still empty and
+  // its options stream in afterwards, so the cursor was never seeded. Typeahead
+  // has to cope with having no cursor to search from.
+  it("matches from the top when options arrive after focus", async () => {
+    const user = userEvent.setup();
+    const { rerender } = render(
+      <Listbox.Root type="single" aria-label="Fruits" />,
+    );
+
+    await user.tab();
+
+    rerender(
+      <Listbox.Root type="single" aria-label="Fruits">
+        {fruits.map((fruit) => (
+          <Listbox.Option key={fruit.value} value={fruit.value}>
+            {fruit.label}
+          </Listbox.Option>
+        ))}
+      </Listbox.Root>,
+    );
+
+    await user.keyboard("b");
+
+    expect(screen.getByRole("listbox")).toHaveAttribute(
+      "aria-activedescendant",
+      screen.getByRole("option", { name: "Banana" }).id,
+    );
+  });
+});

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

@@ -0,0 +1,112 @@
+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 { cursorKeyCases, fruits } from "./Listbox.fixtures";
+
+describe("Listbox keyboard interaction", () => {
+  describe.each(cursorKeyCases)(
+    "$key with the cursor on $from",
+    ({ key, from, expected }) => {
+      it(`moves the cursor to ${expected}`, async () => {
+        const user = userEvent.setup();
+        render(
+          <Listbox.Root type="single" defaultValue={from} 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(key);
+
+        expect(screen.getByRole("listbox")).toHaveAttribute(
+          "aria-activedescendant",
+          screen.getByRole("option", { name: expected }).id,
+        );
+      });
+    },
+  );
+
+  it("does not change the selection while the cursor moves", async () => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(
+      <Listbox.Root
+        type="single"
+        defaultValue="apple"
+        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).not.toHaveBeenCalled();
+    expect(screen.getByRole("option", { name: "Apple" })).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+  });
+
+  it.each(["{Enter}", " "])("selects the cursor option with %s", async (key) => {
+    const user = userEvent.setup();
+    const onValueChange = vi.fn();
+    render(
+      <Listbox.Root
+        type="single"
+        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}");
+    await user.keyboard(key);
+
+    expect(onValueChange).toHaveBeenCalledWith("banana");
+    expect(screen.getByRole("option", { name: "Banana" })).toHaveAttribute(
+      "aria-selected",
+      "true",
+    );
+  });
+
+  it("scrolls the newly active option into view", async () => {
+    const user = userEvent.setup();
+    render(
+      <Listbox.Root type="single" defaultValue="apple" aria-label="Fruits">
+        {fruits.map((fruit) => (
+          <Listbox.Option key={fruit.value} value={fruit.value}>
+            {fruit.label}
+          </Listbox.Option>
+        ))}
+      </Listbox.Root>,
+    );
+
+    const banana = screen.getByRole("option", { name: "Banana" });
+    const scrollIntoView = vi.spyOn(banana, "scrollIntoView");
+
+    await user.tab();
+    await user.keyboard("{ArrowDown}");
+
+    expect(scrollIntoView).toHaveBeenCalledWith({ block: "nearest" });
+  });
+});

package/src/Listbox/__tests__/Listbox.modifier-keys.test.tsx

@@ -0,0 +1,86 @@
+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 { typeaheadOptions } from "./Listbox.fixtures";
+
+function renderListbox(props: Record<string, unknown> = {}) {
+  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,
+  );
+
+/**
+ * Chorded shortcuts belong to the browser and to the consumer — APG's
+ * rearrangeable example binds Alt+Arrow to its toolbar. The listbox must not
+ * eat them: a bare "a" is typeahead, but Ctrl+A is select-all.
+ */
+describe("Listbox modifier keys", () => {
+  it("leaves Ctrl+A alone rather than treating it as typeahead", async () => {
+    const user = userEvent.setup();
+    renderListbox();
+
+    await user.tab();
+    cursorIsOn("Apple");
+
+    await user.keyboard("{Control>}a{/Control}");
+
+    cursorIsOn("Apple");
+  });
+
+  it("leaves Cmd+A alone rather than treating it as typeahead", async () => {
+    const user = userEvent.setup();
+    renderListbox();
+
+    await user.tab();
+    await user.keyboard("{Meta>}a{/Meta}");
+
+    cursorIsOn("Apple");
+  });
+
+  it("leaves Alt+Arrow for the consumer's own shortcut", async () => {
+    const user = userEvent.setup();
+    const onKeyDown = vi.fn();
+    renderListbox({ onKeyDown });
+
+    await user.tab();
+    await user.keyboard("{Alt>}{ArrowDown}{/Alt}");
+
+    cursorIsOn("Apple");
+    expect(onKeyDown).toHaveBeenCalled();
+  });
+
+  it("still runs typeahead for an unmodified character", async () => {
+    const user = userEvent.setup();
+    renderListbox();
+
+    await user.tab();
+    await user.keyboard("b");
+
+    cursorIsOn("Banana");
+  });
+
+  it("still moves the cursor for an unmodified arrow", async () => {
+    const user = userEvent.setup();
+    renderListbox();
+
+    await user.tab();
+    await user.keyboard("{ArrowDown}");
+
+    cursorIsOn("Apricot");
+  });
+});