@charcuterie/ui 2.13.0 → 2.15.0

package/src/Picker/Picker.mdx

@@ -0,0 +1,63 @@
+import { Canvas, Meta } from "@storybook/addon-docs/blocks"
+
+import * as PickerStories from "./Picker.stories.tsx"
+
+<Meta of={PickerStories} />
+
+# Picker
+
+A `Listbox` with its trigger already attached — the shape an app reaches for when it wants
+"a select, but ours".
+
+<Canvas of={PickerStories.Default} />
+
+## Why this exists when `Listbox` already does
+
+`Listbox` is deliberately trigger-agnostic. It takes a `trigger` element and owns none of the
+open state, which is what lets it hang off a button, a tile, or a table header. The cost is
+that the *common* case — a button showing the current value, with a chevron — is about thirty
+lines, and the fleet wrote those lines **four separate times**: queuepilot's
+`SelectListbox`, board-games' `SelectMenu` (on `useState` rather than `useVisibility`),
+mux-magic's `ListboxPicker`, and twice inside this package (`QueryBuilderCombinator` and
+`QueryBuilder`'s own story). Each hand-rolled the same chevron.
+
+`Listbox` is unchanged. `Picker` is the assembled default; reach for `Listbox` directly when
+the trigger is not a button.
+
+## The accessible name carries the current value
+
+`"Language: English"`, not `"Language"`. The trigger's visible text **is** the value, and
+WCAG 2.5.3 requires the visible text to be contained in the accessible name — a bare
+`aria-label={label}` fails it. It also keeps each control uniquely findable when a form has
+several:
+
+```tsx
+getByRole("button", { name: /^Language: / })
+```
+
+<Canvas of={PickerStories.Interactive} />
+
+## Rich options need a `textValue`
+
+`label` takes a `ReactNode` — a flag, a badge, two lines. When it is not a plain string, give
+the option a `textValue`: it is the type-ahead target, and it is what the trigger and the
+accessible name read, so the button says `Audio track: English` rather than the flattened
+text of the whole node.
+
+<Canvas of={PickerStories.AllStates} />
+
+## `id` does not survive; `data-testid` does
+
+`useAnchoredOverlay` overwrites the trigger's `id` with a generated one so the portalled
+listbox can point `aria-labelledby` across at it. An `id` passed to `Picker` is therefore
+silently replaced — queuepilot found this the hard way and moved its e2e handles to
+`data-testid`, which nothing injects. Every other button prop (`data-*`, `onClick`, `form`,
+…) passes straight through; an `onClick` you pass runs before the panel toggles, which is how
+a picker inside a clickable row stops the event reaching its parent.
+
+## Not the component of `useSinglePicker`
+
+The state layer has `useSinglePicker` and `useMultiplePicker`, and the name invites the
+question. `useSinglePicker` is a **state kind** that `Listbox`, `Combobox` and `Tabs` all
+compose; it has no component of its own. `Picker` owns a `useVisibility` and delegates
+selection to `Listbox`, which is where that state actually lives.

package/src/Picker/Picker.stories.tsx

@@ -0,0 +1,184 @@
+import type { Meta, StoryObj } from "@storybook/react"
+import type { ReactNode } from "react"
+import { useState } from "react"
+
+import {
+  controlSizeArgType,
+  intentArgType,
+  placementArgType,
+} from "../argTypes.storyHelpers.ts"
+import { Badge } from "../Badge/Badge.tsx"
+import {
+  StoryRow,
+  StorySection,
+} from "../board.storyHelpers.tsx"
+import type { PickerOption } from "./Picker.tsx"
+import { Picker } from "./Picker.tsx"
+
+const LANGUAGES: PickerOption[] = [
+  { label: "English", value: "eng" },
+  { label: "Spanish", value: "spa" },
+  { label: "French", value: "fra" },
+  { isDisabled: true, label: "German", value: "deu" },
+  { label: "Japanese", value: "jpn" },
+]
+
+/**
+ * The rich options a native `<option>` cannot render — a trailing
+ * intent-coloured badge. No emoji: the VRT runner has no emoji font, so
+ * a flag would snapshot as a blank box and make the shot font-dependent.
+ */
+const TRACKS: PickerOption[] = [
+  {
+    label: (
+      <span className="flex items-center gap-2">
+        <span>English</span>
+        <Badge intent="neutral" size="sm">
+          5.1
+        </Badge>
+      </span>
+    ),
+    textValue: "English",
+    value: "eng",
+  },
+  {
+    label: (
+      <span className="flex items-center gap-2">
+        <span>Japanese</span>
+        <Badge intent="warning" size="sm">
+          forced
+        </Badge>
+      </span>
+    ),
+    textValue: "Japanese",
+    value: "jpn",
+  },
+]
+
+const meta = {
+  title: "Components/Picker",
+  component: Picker,
+  parameters: { layout: "padded" },
+  argTypes: {
+    intent: intentArgType,
+    placement: placementArgType,
+    size: controlSizeArgType,
+  },
+  args: {
+    label: "Language",
+    onChange: () => {},
+    options: LANGUAGES,
+  },
+} satisfies Meta<typeof Picker>
+
+export default meta
+
+type Story = StoryObj<typeof meta>
+
+const PickerHarness = ({
+  initialValue,
+  label,
+  options,
+  placeholder,
+}: {
+  initialValue?: string
+  label: string
+  options: PickerOption[]
+  placeholder?: string
+}): ReactNode => {
+  const [value, setValue] = useState<string | undefined>(
+    initialValue,
+  )
+
+  return (
+    <Picker
+      label={label}
+      onChange={setValue}
+      options={options}
+      placeholder={placeholder}
+      value={value}
+    />
+  )
+}
+
+/**
+ * The assembled default: a button showing the current value, a
+ * chevron, and the `Listbox` panel already wired to it.
+ */
+export const Default: Story = {
+  render: () => (
+    <PickerHarness
+      initialValue="eng"
+      label="Language"
+      options={LANGUAGES}
+    />
+  ),
+}
+
+/**
+ * Nothing chosen yet, a disabled option, and rich option labels —
+ * each with a `textValue` so type-ahead and the trigger's text stay
+ * plain strings.
+ */
+export const AllStates: Story = {
+  render: () => (
+    <div className="flex flex-col gap-6">
+      <StorySection title="Seeded">
+        <StoryRow>
+          <PickerHarness
+            initialValue="spa"
+            label="Language"
+            options={LANGUAGES}
+          />
+        </StoryRow>
+      </StorySection>
+
+      <StorySection title="Empty — reads its placeholder">
+        <StoryRow>
+          <PickerHarness
+            label="Language"
+            options={LANGUAGES}
+            placeholder="Choose a language…"
+          />
+        </StoryRow>
+      </StorySection>
+
+      <StorySection title="Rich options">
+        <StoryRow>
+          <PickerHarness
+            initialValue="eng"
+            label="Audio track"
+            options={TRACKS}
+          />
+        </StoryRow>
+      </StorySection>
+
+      <StorySection title="Disabled">
+        <StoryRow>
+          <Picker
+            isDisabled
+            label="Language"
+            onChange={() => {}}
+            options={LANGUAGES}
+            value="eng"
+          />
+        </StoryRow>
+      </StorySection>
+    </div>
+  ),
+}
+
+/**
+ * Drive it: open, choose, and watch the trigger's accessible name
+ * follow the value — `"Language: English"` becomes
+ * `"Language: French"`.
+ */
+export const Interactive: Story = {
+  render: () => (
+    <PickerHarness
+      initialValue="eng"
+      label="Language"
+      options={LANGUAGES}
+    />
+  ),
+}

package/src/Picker/Picker.test.tsx

@@ -0,0 +1,98 @@
+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 "./Picker.stories.tsx"
+
+const { AllStates, Default, Interactive } =
+  composeStories(stories)
+
+test("the trigger's accessible name carries the current value", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(Default)
+
+  // Not a bare "Language": the button's VISIBLE text is the value, and
+  // WCAG 2.5.3 wants the visible text inside the accessible name.
+  const trigger = expectAgentDrivable(canvas, {
+    name: "Language: English",
+    role: "button",
+  })
+
+  await expect(trigger).toHaveAttribute(
+    "aria-haspopup",
+    "listbox",
+  )
+
+  await expectNoAxeViolations(canvasElement)
+})
+
+test("choosing an option updates the trigger", async () => {
+  const { body, canvas } = await mountStory(Interactive)
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Language: English",
+      role: "button",
+    }),
+  )
+
+  await userEvent.click(
+    expectAgentDrivable(body, {
+      name: "French",
+      role: "option",
+    }),
+  )
+
+  await waitFor(() => {
+    expectAgentDrivable(canvas, {
+      name: "Language: French",
+      role: "button",
+    })
+  })
+})
+
+test("a picker with no value reads its placeholder", async () => {
+  const { canvas } = await mountStory(AllStates)
+
+  expectAgentDrivable(canvas, {
+    name: "Language: Choose a language…",
+    role: "button",
+  })
+})
+
+test("a disabled picker does not open", async () => {
+  const { body, canvas } = await mountStory(AllStates)
+
+  const disabledTrigger = canvas
+    .getAllByRole("button", { name: "Language: English" })
+    .find((button: HTMLElement) =>
+      button.hasAttribute("disabled"),
+    )
+
+  await expect(disabledTrigger).toBeDefined()
+
+  await userEvent.click(disabledTrigger as HTMLElement, {
+    pointerEventsCheck: 0,
+  })
+
+  await expect(body.queryAllByRole("listbox")).toHaveLength(
+    0,
+  )
+})
+
+test("a rich option label keeps a plain-string trigger via textValue", async () => {
+  const { canvas, canvasElement } =
+    await mountStory(AllStates)
+
+  // The label is JSX (a flag, a badge); `textValue` is what the name
+  // and the type-ahead use, so the trigger does not read "🇬🇧 English 5.1".
+  expectAgentDrivable(canvas, {
+    name: "Audio track: English",
+    role: "button",
+  })
+
+  await expectNoAxeViolations(canvasElement)
+})

package/src/Picker/Picker.tsx

@@ -0,0 +1,186 @@
+import { useVisibility } from "@charcuterie/logic"
+import type {
+  ControlSize,
+  IntentName,
+} from "@charcuterie/tokens"
+import type { Placement } from "@floating-ui/react"
+import type {
+  ComponentPropsWithRef,
+  ReactNode,
+} from "react"
+
+import { Button } from "../Button/Button.tsx"
+import type { IntentAppearance } from "../intentStyles.ts"
+import type { ListboxItem } from "../Listbox/Listbox.tsx"
+import { Listbox } from "../Listbox/Listbox.tsx"
+
+export type PickerOption = ListboxItem
+
+/**
+ * A constant element rather than a component, for the same reason
+ * `Select` inlines its own: a second component in this file trips the
+ * house rule, and this never varies.
+ */
+const CHEVRON_DOWN = (
+  <svg
+    aria-hidden="true"
+    className="size-4"
+    fill="none"
+    focusable={false}
+    stroke="currentColor"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    strokeWidth={1.75}
+    viewBox="0 0 24 24"
+    xmlns="http://www.w3.org/2000/svg"
+  >
+    <path d="m6 9 6 6 6-6" />
+  </svg>
+)
+
+export type PickerProps = Omit<
+  ComponentPropsWithRef<"button">,
+  "disabled" | "onChange" | "value"
+> & {
+  appearance?: IntentAppearance
+  className?: string
+  intent?: IntentName
+  isDisabled?: boolean
+  /**
+   * What the control is FOR — "Language", "Quantifier", "Rule type".
+   * Not the current value; that is read off `options`.
+   */
+  label: string
+  /**
+   * Defaults to a chevron. Pass `null` to drop it — a picker rendered
+   * inside a denser control row may not want the affordance, and a
+   * refactor moving an existing hand-rolled trigger onto `Picker`
+   * stays pixel-identical by passing `null` rather than re-baselining
+   * every screenshot that contains it.
+   */
+  iconEnd?: ReactNode
+  onChange: (value: string) => void
+  options: readonly PickerOption[]
+  placement?: Placement
+  /** Read by the trigger when `value` matches no option. */
+  placeholder?: string
+  size?: ControlSize
+  value?: string
+}
+
+/**
+ * A `Listbox` with the trigger already attached — the shape every app
+ * reaches for when it wants "a select, but ours".
+ *
+ * ### Four repos wrote this, and the fourth is this package
+ *
+ * `Listbox` is deliberately trigger-agnostic: it takes a `trigger`
+ * element and owns none of the open state, which is what lets it hang
+ * off a button, a tile, a table header. The cost is that the *common*
+ * case — a button showing the current value — is about thirty lines,
+ * and the fleet wrote them four times: queuepilot's `SelectListbox`,
+ * board-games' `SelectMenu` (on `useState` rather than
+ * `useVisibility`), mux-magic's `ListboxPicker`, and — the tell —
+ * **twice inside this package**, in `QueryBuilderCombinator` and in
+ * `QueryBuilder`'s own story. Each also hand-rolled the same chevron.
+ *
+ * `Listbox` stays exactly as it is. This is the assembled default.
+ *
+ * ### Why it is not called `SinglePicker`
+ *
+ * The state layer has `useSinglePicker` and `useMultiplePicker`, so a
+ * name near "picker" invites the question of whether this is their
+ * component. It is not, and no component is: `useSinglePicker` is a
+ * state kind that `Listbox`, `Combobox` and `Tabs` all compose. This
+ * component owns a `useVisibility` and delegates selection to
+ * `Listbox`, which is where the picker state actually lives. The name
+ * is the owner's, chosen over `SelectListbox` and `ListboxButton`.
+ *
+ * ### The accessible name carries the current value
+ *
+ * `"Language: English"`, not `"Language"`. The trigger's visible text
+ * IS the current value, and WCAG 2.5.3 requires the visible text to be
+ * contained in the accessible name — so a bare `aria-label={label}`
+ * fails it, which is a latent defect in one of the hand-rolled
+ * versions this replaces. It also makes each control uniquely findable
+ * when a form has several, which is the property `expectAgentDrivable`
+ * exists to protect.
+ *
+ * Query it as `getByRole("button", { name: /^Language: / })`.
+ *
+ * ### `id` does not survive; `data-testid` does
+ *
+ * `useAnchoredOverlay` overwrites the trigger's `id` with a generated
+ * one, so the portalled listbox can point `aria-labelledby` across at
+ * it. An `id` passed here is therefore silently replaced — queuepilot
+ * found this the hard way and switched its e2e handles to
+ * `data-testid`, which nothing injects. Everything else on the button
+ * (`data-*`, `onClick`, `form`, …) passes straight through.
+ */
+export const Picker = ({
+  appearance = "outline",
+  className,
+  iconEnd = CHEVRON_DOWN,
+  intent = "neutral",
+  isDisabled = false,
+  label,
+  onChange,
+  options,
+  placement,
+  placeholder,
+  size,
+  value,
+  ...buttonProps
+}: PickerProps): ReactNode => {
+  const { hide, isVisible, toggle } = useVisibility()
+
+  const currentOption = options.find(
+    (option) => option.value === value,
+  )
+
+  const currentText =
+    currentOption === undefined
+      ? placeholder
+      : (currentOption.textValue ??
+        (typeof currentOption.label === "string"
+          ? currentOption.label
+          : undefined))
+
+  const triggerText = currentText ?? placeholder ?? ""
+
+  return (
+    <Listbox
+      // A disabled control must not open, and hiding the panel is a
+      // truer way to say that than trusting the trigger's click alone —
+      // Escape and outside-press both route through `onDismiss`.
+      isVisible={isVisible && !isDisabled}
+      onDismiss={hide}
+      onSelect={onChange}
+      options={options}
+      placement={placement}
+      selectedValue={value}
+      trigger={
+        <Button
+          {...buttonProps}
+          appearance={appearance}
+          aria-label={`${label}: ${triggerText}`}
+          className={className}
+          iconEnd={iconEnd}
+          intent={intent}
+          isDisabled={isDisabled}
+          onClick={(clickEvent) => {
+            buttonProps.onClick?.(clickEvent)
+
+            toggle()
+          }}
+          size={size}
+          type="button"
+        >
+          {currentOption === undefined
+            ? placeholder
+            : currentOption.label}
+        </Button>
+      }
+    />
+  )
+}

package/src/QueryBuilder/QueryBuilder.mdx

@@ -55,9 +55,16 @@ the sunken surface so it recedes rather than floating at the same level as its p
 
 ## Driving it
 
-Every control is nameable, not a `data-testid`: the combinator select is named `Match` by the
-field label, the leaf controls by their own labels, and each delete is an `IconButton` whose
-required `label` makes it findable. Add a condition, nest a group, flip a combinator, delete a
-row — all reachable by role and name.
+Every control is nameable, not a `data-testid`: the combinator picker is a `Listbox` whose
+trigger is named `Match: <current combinator>`, the leaf controls by their own labels, and each
+delete is an `IconButton` whose required `label` makes it findable. Add a condition, nest a
+group, flip a combinator, delete a row — all reachable by role and name.
+
+The picker is a `Listbox` rather than a native `Select`, per
+[the 2026-08-10 demotion](../../../../docs/decisions/2026-08-10-listbox-and-combobox-are-the-default-and-select-is-demoted.md).
+Its name carries the current value because the trigger's visible text *is* that value, and
+WCAG 2.5.3 wants the visible text contained in the accessible name — so query it with
+`getByRole("button", { name: /^Match: / })`, not by the bare caption. Rename the caption with
+`labels.match`.
 
 <Canvas of={QueryBuilderStories.Interactive} />