@charcuterie/ui 1.1.0 → 2.0.0

package/src/Combobox/Combobox.stories.tsx

@@ -0,0 +1,245 @@
+import { useVisibility } from "@charcuterie/logic"
+import type { Meta, StoryObj } from "@storybook/react"
+import type { ReactNode } from "react"
+import { useState } from "react"
+
+import { Button } from "../Button/Button.tsx"
+import type { ListboxItem } from "../Listbox/Listbox.tsx"
+import { Combobox } from "./Combobox.tsx"
+
+const LANGUAGES: ListboxItem[] = [
+  { label: "English", value: "eng" },
+  { label: "Spanish", value: "spa" },
+  { label: "French", value: "fra" },
+  { label: "German", value: "deu" },
+  { label: "Japanese", value: "jpn" },
+  { label: "Korean", value: "kor" },
+  { label: "Portuguese", value: "por" },
+]
+
+const LANGUAGES_DISABLED_FIRST: ListboxItem[] = [
+  { isDisabled: true, label: "English", value: "eng" },
+  { label: "Spanish", value: "spa" },
+  { label: "French", value: "fra" },
+]
+
+// A long list, to trip the auto-virtualization threshold.
+const MANY: ListboxItem[] = Array.from(
+  { length: 500 },
+  (_unused, index) => ({
+    label: `Track ${index + 1}`,
+    textValue: `Track ${index + 1}`,
+    value: `track-${index + 1}`,
+  }),
+)
+
+const meta = {
+  title: "Components/Combobox",
+  component: Combobox,
+  parameters: { layout: "padded" },
+} satisfies Meta<typeof Combobox>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+const ComboboxHarness = ({
+  emptyLabel,
+  error,
+  footer,
+  isCreatable,
+  isInitiallyVisible = false,
+  isLoading,
+  isMultiple,
+  isVirtualized,
+  options,
+  triggerLabel,
+}: {
+  emptyLabel?: string
+  error?: ReactNode
+  footer?: ReactNode
+  isCreatable?: boolean
+  isInitiallyVisible?: boolean
+  isLoading?: boolean
+  isMultiple?: boolean
+  isVirtualized?: boolean
+  options: ListboxItem[]
+  triggerLabel: string
+}): ReactNode => {
+  const { hide, isVisible, toggle } = useVisibility({
+    isVisible: isInitiallyVisible,
+  })
+
+  const [chosen, setChosen] = useState<string[]>([])
+
+  return (
+    <>
+      <Combobox
+        emptyLabel={emptyLabel}
+        error={error}
+        footer={footer}
+        isCreatable={isCreatable}
+        isLoading={isLoading}
+        isMultiple={isMultiple}
+        isVirtualized={isVirtualized}
+        isVisible={isVisible}
+        onDismiss={hide}
+        onSelect={(value) => {
+          setChosen((previous) =>
+            previous.includes(value)
+              ? previous.filter((one) => one !== value)
+              : [...previous, value],
+          )
+        }}
+        options={options}
+        trigger={
+          <Button appearance="outline" onClick={toggle}>
+            {triggerLabel}
+          </Button>
+        }
+      />
+
+      <p className="mt-2 text-content-muted text-xs">
+        Chosen: {chosen.join(", ") || "—"}
+      </p>
+    </>
+  )
+}
+
+export const Default: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: LANGUAGES,
+    trigger: <Button>Search languages</Button>,
+  },
+  render: () => (
+    <ComboboxHarness
+      options={LANGUAGES}
+      triggerLabel="Search languages"
+    />
+  ),
+}
+
+/**
+ * The loading and error panel states — the ones only `PathPicker` had
+ * all of, and every fleet picker did differently. Both keep the popup
+ * open.
+ */
+export const AllStates: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: LANGUAGES,
+    trigger: <Button>Search</Button>,
+  },
+  render: () => (
+    <div className="flex flex-col gap-8">
+      <ComboboxHarness
+        isLoading
+        options={LANGUAGES}
+        triggerLabel="Loading state"
+      />
+
+      <ComboboxHarness
+        error="Could not reach the server."
+        options={LANGUAGES}
+        triggerLabel="Error state"
+      />
+    </div>
+  ),
+}
+
+/**
+ * Multi-select renders the chosen values as removable chips rather
+ * than filling the input, with a sticky footer hint — the
+ * `LanguageCodeField` and `LinkPicker` shapes. `isCreatable` lets Enter
+ * commit the raw query.
+ */
+export const AllVariants: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: LANGUAGES,
+    trigger: <Button>Pick languages</Button>,
+  },
+  render: () => (
+    <ComboboxHarness
+      footer="Type a code and press Enter to add it."
+      isCreatable
+      isMultiple
+      options={LANGUAGES}
+      triggerLabel="Pick languages"
+    />
+  ),
+}
+
+/**
+ * Five hundred options, windowed with `@tanstack/react-virtual`: only
+ * the visible rows are in the DOM, so each carries `aria-setsize` and
+ * `aria-posinset` — otherwise a screen reader announces "2 of 12" for
+ * a list that is nothing of the sort.
+ */
+export const Virtualized: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: MANY,
+    trigger: <Button>Search 500 tracks</Button>,
+  },
+  render: () => (
+    <ComboboxHarness
+      isInitiallyVisible
+      options={MANY}
+      triggerLabel="Search 500 tracks"
+    />
+  ),
+}
+
+/**
+ * Open it and type: the list filters as you go, arrows move the active
+ * option while the caret stays in the input, Enter chooses, and Escape
+ * clears the query before it closes.
+ */
+export const Interactive: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: LANGUAGES,
+    trigger: <Button>Search languages</Button>,
+  },
+  render: () => (
+    <ComboboxHarness
+      options={LANGUAGES}
+      triggerLabel="Search languages"
+    />
+  ),
+}
+
+/**
+ * A disabled option in the seed position. Opening seeds the active row at
+ * index 0, so the resolved active descendant must skip past the disabled
+ * first option to the first enabled one — and Enter must never commit the
+ * disabled value.
+ */
+export const DisabledFirstOption: Story = {
+  args: {
+    isVisible: false,
+    onDismiss: () => {},
+    onSelect: () => {},
+    options: LANGUAGES_DISABLED_FIRST,
+    trigger: <Button>Pick a language</Button>,
+  },
+  render: () => (
+    <ComboboxHarness
+      isInitiallyVisible
+      options={LANGUAGES_DISABLED_FIRST}
+      triggerLabel="Pick a language"
+    />
+  ),
+}

package/src/Combobox/Combobox.test.tsx

@@ -0,0 +1,289 @@
+import { composeStories } from "@storybook/react"
+import { expect, userEvent, waitFor } from "storybook/test"
+import { test } from "vitest"
+
+import { expectNoAxeViolations } from "../expectNoAxeViolations.testHelpers.ts"
+import { mountStory } from "../mountStory.testHelpers.ts"
+import { expectAgentDrivable } from "../testing/index.ts"
+import * as stories from "./Combobox.stories.tsx"
+
+const {
+  AllVariants,
+  Default,
+  DisabledFirstOption,
+  Interactive,
+  Virtualized,
+} = composeStories(stories)
+
+const openMulti = async () => {
+  const mounted = await mountStory(AllVariants)
+
+  await userEvent.click(
+    expectAgentDrivable(mounted.canvas, {
+      name: "Pick languages",
+      role: "button",
+    }),
+  )
+
+  const input = expectAgentDrivable(mounted.body, {
+    role: "combobox",
+  })
+
+  await waitFor(() => {
+    expect(input).toHaveFocus()
+  })
+
+  return { ...mounted, input }
+}
+
+const openDefault = async () => {
+  const mounted = await mountStory(Default)
+
+  await userEvent.click(
+    expectAgentDrivable(mounted.canvas, {
+      name: "Search languages",
+      role: "button",
+    }),
+  )
+
+  const input = expectAgentDrivable(mounted.body, {
+    role: "combobox",
+  })
+
+  await waitFor(() => {
+    expect(input).toHaveFocus()
+  })
+
+  return { ...mounted, input }
+}
+
+test("a button opens a combobox whose popup is a listbox", async () => {
+  const { body, input } = await openDefault()
+
+  await expect(input).toHaveAttribute(
+    "aria-autocomplete",
+    "list",
+  )
+
+  const listbox = expectAgentDrivable(body, {
+    role: "listbox",
+  })
+
+  await expect(input).toHaveAttribute(
+    "aria-controls",
+    listbox.id,
+  )
+
+  await expectNoAxeViolations(listbox)
+})
+
+test("typing filters the options, and focus stays in the input", async () => {
+  const { body, input } = await openDefault()
+
+  await expect(body.getAllByRole("option")).toHaveLength(7)
+
+  await userEvent.keyboard("fr")
+
+  await waitFor(() => {
+    expect(body.getAllByRole("option")).toHaveLength(1)
+  })
+
+  expect(body.getByRole("option")).toHaveTextContent(
+    "French",
+  )
+
+  // The caret never left the input.
+  await expect(input).toHaveFocus()
+})
+
+test("no match shows the empty label and keeps the popup open", async () => {
+  const { body } = await openDefault()
+
+  await userEvent.keyboard("zzz")
+
+  await waitFor(() => {
+    expect(body.queryAllByRole("option")).toHaveLength(0)
+  })
+
+  // Still open, still typeable.
+  await expect(
+    body.getByText("No matches"),
+  ).toBeInTheDocument()
+
+  await expect(
+    body.getByRole("combobox"),
+  ).toBeInTheDocument()
+})
+
+test("the arrow keys move aria-activedescendant, not focus", async () => {
+  const { body, input } = await openDefault()
+
+  const options = body.getAllByRole("option")
+
+  // Opens on the first option.
+  await expect(input).toHaveAttribute(
+    "aria-activedescendant",
+    options[0]?.id,
+  )
+
+  await userEvent.keyboard("{ArrowDown}")
+
+  await waitFor(() => {
+    expect(input).toHaveAttribute(
+      "aria-activedescendant",
+      options[1]?.id,
+    )
+  })
+
+  // Focus never moved to the option.
+  await expect(input).toHaveFocus()
+})
+
+test("Enter selects the active option and closes", async () => {
+  const { body, input } = await openDefault()
+
+  await userEvent.keyboard("{ArrowDown}{Enter}")
+
+  await waitFor(() => {
+    expect(body.queryByRole("combobox")).toBeNull()
+  })
+
+  // Single-select flows back through `onSelect`.
+  await expect(input).not.toBeInTheDocument()
+})
+
+test("Escape clears the query first, then closes", async () => {
+  const { body, canvas } = await mountStory(Interactive)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Search languages",
+      role: "button",
+    }),
+  )
+
+  const input = body.getByRole("combobox")
+
+  await waitFor(() => {
+    expect(input).toHaveFocus()
+  })
+
+  await userEvent.keyboard("fr")
+
+  await expect(input).toHaveValue("fr")
+
+  await userEvent.keyboard("{Escape}")
+
+  // First Escape clears the query but leaves the popup open.
+  await expect(input).toHaveValue("")
+
+  await expect(
+    body.getByRole("combobox"),
+  ).toBeInTheDocument()
+
+  await userEvent.keyboard("{Escape}")
+
+  await waitFor(() => {
+    expect(body.queryByRole("combobox")).toBeNull()
+  })
+})
+
+test("multi-select Tab escapes the field instead of committing", async () => {
+  const { body, canvas, input } = await openMulti()
+
+  // Nothing chosen yet.
+  await expect(
+    canvas.getByText("Chosen: —"),
+  ).toBeInTheDocument()
+
+  await userEvent.tab()
+
+  // Tab did not commit the active option — no chip, still nothing chosen…
+  await expect(
+    canvas.getByText("Chosen: —"),
+  ).toBeInTheDocument()
+
+  await expect(
+    body.queryByRole("button", { name: /^Remove / }),
+  ).toBeNull()
+
+  // …and focus left the input rather than being trapped back in it.
+  await expect(input).not.toHaveFocus()
+})
+
+test("removing a chip reports the removal through onSelect", async () => {
+  const { body, canvas } = await openMulti()
+
+  // Enter commits the active option in multi-select and keeps the popup
+  // open, so a chip appears and the parent is told.
+  await userEvent.keyboard("{Enter}")
+
+  await waitFor(() => {
+    expect(
+      canvas.getByText("Chosen: eng"),
+    ).toBeInTheDocument()
+  })
+
+  await userEvent.click(
+    body.getByRole("button", { name: "Remove eng" }),
+  )
+
+  // The removal flowed back through `onSelect`, so the parent cleared it
+  // — a chip removal and a list toggle-off now agree.
+  await waitFor(() => {
+    expect(
+      canvas.getByText("Chosen: —"),
+    ).toBeInTheDocument()
+  })
+})
+
+test("a disabled first option is skipped, never active or committed", async () => {
+  const { body, canvas } = await mountStory(
+    DisabledFirstOption,
+  )
+
+  const input = body.getByRole("combobox")
+
+  await waitFor(() => {
+    expect(input).toHaveFocus()
+  })
+
+  const options = body.getAllByRole("option")
+
+  // The seed lands on index 0 (disabled English); the resolved active
+  // descendant skips to the first enabled option, Spanish.
+  await expect(input).toHaveAttribute(
+    "aria-activedescendant",
+    options[1]?.id,
+  )
+
+  await userEvent.keyboard("{Enter}")
+
+  // Enter committed Spanish, not the disabled English, and closed.
+  await waitFor(() => {
+    expect(body.queryByRole("combobox")).toBeNull()
+  })
+
+  await expect(
+    canvas.getByText("Chosen: spa"),
+  ).toBeInTheDocument()
+})
+
+test("a windowed list carries aria-setsize and aria-posinset", async () => {
+  const { body } = await mountStory(Virtualized)
+
+  const options = body.getAllByRole("option")
+
+  // Only a window of the 500 is in the DOM.
+  await expect(options.length).toBeLessThan(500)
+
+  await expect(options.length).toBeGreaterThan(0)
+
+  // Each announces its place in the whole set, not the window.
+  await expect(options[0]).toHaveAttribute(
+    "aria-setsize",
+    "500",
+  )
+
+  await expect(options[0]).toHaveAttribute("aria-posinset")
+})