@charcuterie/ui 2.14.0 → 2.15.1

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.stories.tsx

@@ -1,15 +1,10 @@
 import type { SerializedTree } from "@charcuterie/logic"
-import {
-  createTree,
-  useTree,
-  useVisibility,
-} from "@charcuterie/logic"
+import { createTree, useTree } 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 { StorySection } from "../board.storyHelpers.tsx"
-import { Listbox } from "../Listbox/Listbox.tsx"
+import { Picker } from "../Picker/Picker.tsx"
 import { QueryBuilder } from "./QueryBuilder.tsx"
 
 /**
@@ -52,58 +47,6 @@ const createLeafValue = (): DemoLeaf => ({
   value: "",
 })
 
-/**
- * A leaf's own picker — a `Listbox`, like the combinator above it,
- * because [the 2026-08-10 demotion](../../../../docs/decisions/2026-08-10-listbox-and-combobox-are-the-default-and-select-is-demoted.md)
- * applies to an app's leaf UI exactly as it does to this component's
- * own controls. This story is the example apps copy, so it must not
- * teach the native `Select` the record demoted.
- *
- * It is a component rather than inline JSX for the same reason
- * `QueryBuilderCombinator` is: `Listbox` needs a visibility state, and
- * a leaf is rendered inside a `.map` where a hook cannot be called.
- * An app adopting `QueryBuilder` writes this same small wrapper — see
- * the note in `QueryBuilder.mdx`.
- */
-const LeafPicker = ({
-  label,
-  onChange,
-  options,
-  value,
-}: {
-  label: string
-  onChange: (value: string) => void
-  options: readonly { label: string; value: string }[]
-  value: string
-}): ReactNode => {
-  const { hide, isVisible, toggle } = useVisibility()
-
-  const currentLabel =
-    options.find((option) => option.value === value)
-      ?.label ?? ""
-
-  return (
-    <Listbox
-      isVisible={isVisible}
-      onDismiss={hide}
-      onSelect={onChange}
-      options={options}
-      selectedValue={value}
-      trigger={
-        <Button
-          appearance="outline"
-          aria-label={`${label}: ${currentLabel}`}
-          intent="neutral"
-          onClick={toggle}
-          size="sm"
-        >
-          {currentLabel}
-        </Button>
-      }
-    />
-  )
-}
-
 const renderLeaf = ({
   onChange,
   value,
@@ -113,21 +56,25 @@ const renderLeaf = ({
   value: DemoLeaf
 }): ReactNode => (
   <div className="flex flex-wrap items-center gap-2">
-    <LeafPicker
+    <Picker
+      iconEnd={null}
       label="Field"
       onChange={(field) => {
         onChange({ ...value, field })
       }}
       options={FIELD_OPTIONS}
+      size="sm"
       value={value.field}
     />
 
-    <LeafPicker
+    <Picker
+      iconEnd={null}
       label="Operator"
       onChange={(operator) => {
         onChange({ ...value, operator })
       }}
       options={OPERATOR_OPTIONS}
+      size="sm"
       value={value.operator}
     />
 
@@ -357,7 +304,8 @@ const CombinatorPair = ({
       </span>
 
       <div className="flex items-center gap-1.5">
-        <LeafPicker
+        <Picker
+          iconEnd={null}
           label="Quantifier"
           onChange={(nextQuantifier) => {
             setQuantifier(nextQuantifier)
@@ -374,10 +322,12 @@ const CombinatorPair = ({
             )
           }}
           options={QUANTIFIER_OPTIONS}
+          size="sm"
           value={quantifier}
         />
 
-        <LeafPicker
+        <Picker
+          iconEnd={null}
           label="Target"
           onChange={(nextTarget) => {
             setTarget(nextTarget)
@@ -389,6 +339,7 @@ const CombinatorPair = ({
             )
           }}
           options={targetOptions}
+          size="sm"
           value={resolvedTarget}
         />
       </div>