@charcuterie/ui 2.13.0 → 2.15.0

package/src/QueryBuilder/QueryBuilder.stories.tsx

@@ -2,8 +2,9 @@ import type { SerializedTree } 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 { StorySection } from "../board.storyHelpers.tsx"
-import { Select } from "../Select/Select.tsx"
+import { Picker } from "../Picker/Picker.tsx"
 import { QueryBuilder } from "./QueryBuilder.tsx"
 
 /**
@@ -55,7 +56,8 @@ const renderLeaf = ({
   value: DemoLeaf
 }): ReactNode => (
   <div className="flex flex-wrap items-center gap-2">
-    <Select
+    <Picker
+      iconEnd={null}
       label="Field"
       onChange={(field) => {
         onChange({ ...value, field })
@@ -65,7 +67,8 @@ const renderLeaf = ({
       value={value.field}
     />
 
-    <Select
+    <Picker
+      iconEnd={null}
       label="Operator"
       onChange={(operator) => {
         onChange({ ...value, operator })
@@ -241,3 +244,137 @@ export const Interactive: Story = {
     />
   ),
 }
+
+/**
+ * `renderCombinator` — the group's combinator control, owned by the app.
+ *
+ * The default single picker is right when a combinator is a plain enum.
+ * mux-magic's is not: it is a **quantifier** (ANY/ALL/NO) crossed with a
+ * **target** (these groups, style rows, script-info blocks), and the legal
+ * pairs are asymmetric — the DSL has `notAllScriptInfo` and no
+ * `notAllStyle`. Flattened to one list, that asymmetry is invisible; split
+ * in two, the second picker filters and the illegal pair cannot be built.
+ *
+ * This story is that shape in miniature: pick `NOT ALL` and the target
+ * list collapses to the one target it can legally take.
+ */
+const PAIR_COMBINATORS = {
+  "all:group": "and",
+  "all:row": "and",
+  "any:group": "or",
+  "any:row": "or",
+  "notAll:group": "and",
+} as const
+
+const QUANTIFIER_OPTIONS = [
+  { label: "ALL", value: "all" },
+  { label: "ANY", value: "any" },
+  { label: "NOT ALL", value: "notAll" },
+] as const
+
+const CombinatorPair = ({
+  onChange,
+  value,
+}: {
+  onChange: (combinator: Combinator) => void
+  value: Combinator
+}): ReactNode => {
+  const [quantifier, setQuantifier] =
+    useState<string>("all")
+
+  // "NOT ALL" is legal over groups only here — the same filtered
+  // second picker mux-magic needs, in one line.
+  const targetOptions =
+    quantifier === "notAll"
+      ? [{ label: "of these groups", value: "group" }]
+      : [
+          { label: "of these groups", value: "group" },
+          { label: "matching rows", value: "row" },
+        ]
+
+  const [target, setTarget] = useState<string>("group")
+
+  const resolvedTarget =
+    quantifier === "notAll" ? "group" : target
+
+  return (
+    <div className="flex flex-col gap-1.5">
+      <span className="font-medium text-content-primary text-sm">
+        Match
+      </span>
+
+      <div className="flex items-center gap-1.5">
+        <Picker
+          iconEnd={null}
+          label="Quantifier"
+          onChange={(nextQuantifier) => {
+            setQuantifier(nextQuantifier)
+
+            const nextTarget =
+              nextQuantifier === "notAll"
+                ? "group"
+                : resolvedTarget
+
+            onChange(
+              PAIR_COMBINATORS[
+                `${nextQuantifier}:${nextTarget}` as keyof typeof PAIR_COMBINATORS
+              ],
+            )
+          }}
+          options={QUANTIFIER_OPTIONS}
+          size="sm"
+          value={quantifier}
+        />
+
+        <Picker
+          iconEnd={null}
+          label="Target"
+          onChange={(nextTarget) => {
+            setTarget(nextTarget)
+
+            onChange(
+              PAIR_COMBINATORS[
+                `${quantifier}:${nextTarget}` as keyof typeof PAIR_COMBINATORS
+              ],
+            )
+          }}
+          options={targetOptions}
+          size="sm"
+          value={resolvedTarget}
+        />
+      </div>
+
+      <span className="text-content-muted text-xs">
+        {`Combinator: ${String(value)}`}
+      </span>
+    </div>
+  )
+}
+
+export const CustomCombinator: Story = {
+  render: () => {
+    const CustomCombinatorHarness = (): ReactNode => {
+      const tree = useTree<Combinator, DemoLeaf>({
+        defaultCombinator: "and",
+        initialTree: FLAT_TREE,
+      })
+
+      return (
+        <QueryBuilder
+          combinatorOptions={COMBINATOR_OPTIONS}
+          createLeafValue={createLeafValue}
+          renderCombinator={({ onChange, value }) => (
+            <CombinatorPair
+              onChange={onChange}
+              value={value}
+            />
+          )}
+          renderLeaf={renderLeaf}
+          tree={tree}
+        />
+      )
+    }
+
+    return <CustomCombinatorHarness />
+  },
+}

package/src/QueryBuilder/QueryBuilder.test.tsx

@@ -7,20 +7,31 @@ import { mountStory } from "../mountStory.testHelpers.ts"
 import { expectAgentDrivable } from "../testing/index.ts"
 import * as stories from "./QueryBuilder.stories.tsx"
 
-const { AllStates, Default, Interactive } =
-  composeStories(stories)
+const {
+  AllStates,
+  CustomCombinator,
+  Default,
+  Interactive,
+} = composeStories(stories)
 
 test("the root group exposes its combinator as a named 'Match' control", async () => {
   const { canvas, canvasElement } =
     await mountStory(Default)
 
-  // One root group, so exactly one combinator select — findable by
-  // the label `Field` wires, not a testid.
-  expectAgentDrivable(canvas, {
-    name: "Match",
-    role: "combobox",
+  // One root group, so exactly one combinator picker. It is a
+  // `Listbox` trigger, so the control is a button that opens a
+  // listbox — named "Match: <current>", which keeps the button's
+  // visible text (the combinator) inside its accessible name.
+  const combinator = expectAgentDrivable(canvas, {
+    name: /^Match: /,
+    role: "button",
   })
 
+  await expect(combinator).toHaveAttribute(
+    "aria-haspopup",
+    "listbox",
+  )
+
   await expectNoAxeViolations(canvasElement)
 })
 
@@ -55,7 +66,7 @@ test("'+ Add group' nests a second group with its own combinator", async () => {
     await mountStory(Interactive)
 
   await expect(
-    canvas.getAllByRole("combobox", { name: "Match" }),
+    canvas.getAllByRole("button", { name: /^Match: / }),
   ).toHaveLength(1)
 
   await userEvent.click(
@@ -67,7 +78,7 @@ test("'+ Add group' nests a second group with its own combinator", async () => {
 
   await waitFor(() => {
     expect(
-      canvas.getAllByRole("combobox", { name: "Match" }),
+      canvas.getAllByRole("button", { name: /^Match: / }),
     ).toHaveLength(2)
   })
 
@@ -80,23 +91,31 @@ test("'+ Add group' nests a second group with its own combinator", async () => {
   await expectNoAxeViolations(canvasElement)
 })
 
-test("changing the combinator select updates its value", async () => {
-  const { canvas } = await mountStory(Interactive)
-
-  const combinator = expectAgentDrivable(canvas, {
-    name: "Match",
-    role: "combobox",
-  })
+test("choosing a combinator from the listbox updates the group", async () => {
+  const { body, canvas } = await mountStory(Interactive)
 
-  await expect(combinator).toHaveValue("and")
+  // The trigger's label IS the current combinator, so the change is
+  // asserted on its accessible name rather than a form value — a
+  // `Listbox` trigger is a button and holds none.
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: "Match: ALL — every condition",
+      role: "button",
+    }),
+  )
 
-  await userEvent.selectOptions(
-    combinator,
-    "ANY — one condition",
+  await userEvent.click(
+    expectAgentDrivable(body, {
+      name: "ANY — one condition",
+      role: "option",
+    }),
   )
 
   await waitFor(() => {
-    expect(combinator).toHaveValue("or")
+    expectAgentDrivable(canvas, {
+      name: "Match: ANY — one condition",
+      role: "button",
+    })
   })
 })
 
@@ -122,11 +141,64 @@ test("a nested tree renders every group's combinator and passes axe", async () =
     await mountStory(AllStates)
 
   // Flat harness (1 group) + nested harness (root + one sub-group) =
-  // three combinator selects, which is the nesting rendering.
+  // three combinator pickers, which is the nesting rendering.
   await expect(
-    canvas.getAllByRole("combobox", { name: "Match" })
+    canvas.getAllByRole("button", { name: /^Match: / })
       .length,
   ).toBeGreaterThanOrEqual(3)
 
   await expectNoAxeViolations(canvasElement)
 })
+
+test("renderCombinator replaces the built-in picker, and its second control filters", async () => {
+  const { body, canvas } = await mountStory(
+    CustomCombinator,
+  )
+
+  // The app's control is rendered instead of the default one — no
+  // "Match: <combinator>" trigger anywhere.
+  await expect(
+    canvas.queryAllByRole("button", { name: /^Match: / }),
+  ).toHaveLength(0)
+
+  const target = expectAgentDrivable(canvas, {
+    name: /^Target: /,
+    role: "button",
+  })
+
+  // Both targets are offered while the quantifier is ALL.
+  await userEvent.click(target)
+
+  await expect(body.getAllByRole("option")).toHaveLength(2)
+
+  await userEvent.keyboard("{Escape}")
+
+  // Switching to NOT ALL collapses the target list to the one legal
+  // pair — the asymmetry this prop exists to express.
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: /^Quantifier: /,
+      role: "button",
+    }),
+  )
+
+  await userEvent.click(
+    expectAgentDrivable(body, {
+      name: "NOT ALL",
+      role: "option",
+    }),
+  )
+
+  await userEvent.click(
+    expectAgentDrivable(canvas, {
+      name: /^Target: /,
+      role: "button",
+    }),
+  )
+
+  await waitFor(async () => {
+    await expect(body.getAllByRole("option")).toHaveLength(
+      1,
+    )
+  })
+})

package/src/QueryBuilder/QueryBuilder.tsx

@@ -10,6 +10,8 @@ import { QueryBuilderGroup } from "./QueryBuilderGroup.tsx"
 export type QueryBuilderLabels = {
   addGroup?: string
   addLeaf?: string
+  /** The caption over each group's combinator picker. */
+  match?: string
   removeGroup?: string
   removeLeaf?: string
 }
@@ -27,6 +29,35 @@ export type QueryBuilderProps<Combinator, Leaf> = {
   /** The value a fresh leaf is born with when "+ Condition" is pressed. */
   createLeafValue: () => Leaf
   labels?: QueryBuilderLabels
+  /**
+   * The group's combinator control, when one `Listbox` over a flat
+   * option list is the wrong shape for it.
+   *
+   * Optional, and the default is the right answer for most consumers:
+   * a combinator that is a plain enum reads as one picker. But a
+   * combinator can be a *composite* — mux-magic's is a quantifier
+   * (ANY/ALL/NO) crossed with a target (a nested group, a style row,
+   * a script-info block), and the legal pairs are asymmetric
+   * (`notAllScriptInfo` exists, `notAllStyle` does not). Flattened
+   * into one list that is nine options where the user is making two
+   * choices, and the illegal pairs are invisible until they are
+   * missing.
+   *
+   * So the combinator is app-ownable for the same reason `renderLeaf`
+   * is: `Combinator` is opaque here, and only the app knows whether
+   * its shape is an enum or a product. `options` and the current
+   * `value` are handed over unchanged; the app calls `onChange` with a
+   * real `Combinator`.
+   */
+  renderCombinator?: (args: {
+    nodeId: string
+    onChange: (combinator: Combinator) => void
+    options: readonly {
+      label: string
+      value: Combinator
+    }[]
+    value: Combinator
+  }) => ReactNode
   /**
    * The leaf UI, owned by the app. `QueryBuilder` knows nothing about
    * what a condition *is* — a field/operator/value triple, a
@@ -50,6 +81,7 @@ export type QueryBuilderProps<Combinator, Leaf> = {
 const DEFAULT_LABELS = {
   addGroup: "Add group",
   addLeaf: "Add condition",
+  match: "Match",
   removeGroup: "Remove group",
   removeLeaf: "Remove condition",
 } satisfies Required<QueryBuilderLabels>
@@ -80,6 +112,7 @@ export const QueryBuilder = <Combinator, Leaf>({
   combinatorOptions,
   createLeafValue,
   labels,
+  renderCombinator,
   renderLeaf,
   tree,
 }: QueryBuilderProps<Combinator, Leaf>): ReactNode => {
@@ -94,6 +127,7 @@ export const QueryBuilder = <Combinator, Leaf>({
       depth={0}
       labels={resolvedLabels}
       node={selectRootGroup(state)}
+      renderCombinator={renderCombinator}
       renderLeaf={renderLeaf}
       state={state}
       tree={tree}

package/src/QueryBuilder/QueryBuilderCombinator.tsx

@@ -0,0 +1,69 @@
+import type { ReactNode } from "react"
+
+import { Picker } from "../Picker/Picker.tsx"
+
+export type QueryBuilderCombinatorProps<Combinator> = {
+  /** The visible caption above the control, e.g. "Match". */
+  label: string
+  onChange: (combinator: Combinator) => void
+  options: readonly {
+    label: string
+    value: Combinator
+  }[]
+  value: Combinator
+}
+
+/**
+ * One group's combinator picker.
+ *
+ * A `Picker` — a `Listbox` with its trigger attached — 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).
+ * This file used to assemble the trigger by hand; `Picker` exists
+ * because it was the fourth place in the fleet doing so.
+ *
+ * ### What is left here, and why it is still a component
+ *
+ * Only the bridging. `Combinator` is opaque to `QueryBuilder`, so it
+ * cannot reach `Picker`'s string-valued API directly: `String(value)`
+ * carries it out and the matching option carries it back, so the
+ * generic never leaks. The caption is plain text rather than a
+ * `Field`, because `useAnchoredOverlay` overwrites the trigger's `id`
+ * and a `<label htmlFor>` would then address an element that no longer
+ * carries it — the exact defect `Field` exists to prevent.
+ */
+export const QueryBuilderCombinator = <Combinator,>({
+  label,
+  onChange,
+  options,
+  value,
+}: QueryBuilderCombinatorProps<Combinator>): ReactNode => (
+  <div className="flex flex-col gap-1.5">
+    <span className="font-medium text-content-primary text-sm">
+      {label}
+    </span>
+
+    <Picker
+      // No chevron: this is a refactor onto the shared component, and
+      // the trigger that shipped in 2.14.0 had none. Adding the
+      // affordance here is a visual change and belongs in its own PR,
+      // not smuggled in under an extraction.
+      iconEnd={null}
+      label={label}
+      onChange={(nextValue) => {
+        const match = options.find(
+          (option) => String(option.value) === nextValue,
+        )
+
+        if (match) {
+          onChange(match.value)
+        }
+      }}
+      options={options.map((option) => ({
+        label: option.label,
+        value: String(option.value),
+      }))}
+      value={String(value)}
+    />
+  </div>
+)

package/src/QueryBuilder/QueryBuilderGroup.tsx

@@ -8,11 +8,10 @@ import type { ReactNode } from "react"
 
 import { Button } from "../Button/Button.tsx"
 import { Card } from "../Card/Card.tsx"
-import { Field } from "../Field/Field.tsx"
 import { IconButton } from "../IconButton/IconButton.tsx"
-import { Select } from "../Select/Select.tsx"
 import { toClassName } from "../toClassName.ts"
 import type { QueryBuilderLabels } from "./QueryBuilder.tsx"
+import { QueryBuilderCombinator } from "./QueryBuilderCombinator.tsx"
 import { QueryBuilderRow } from "./QueryBuilderRow.tsx"
 
 export type QueryBuilderGroupProps<Combinator, Leaf> = {
@@ -25,6 +24,15 @@ export type QueryBuilderGroupProps<Combinator, Leaf> = {
   depth: number
   labels: Required<QueryBuilderLabels>
   node: TreeGroupNode<Combinator>
+  renderCombinator?: (args: {
+    nodeId: string
+    onChange: (combinator: Combinator) => void
+    options: readonly {
+      label: string
+      value: Combinator
+    }[]
+    value: Combinator
+  }) => ReactNode
   renderLeaf: (args: {
     nodeId: string
     onChange: (value: Leaf) => void
@@ -35,18 +43,14 @@ export type QueryBuilderGroupProps<Combinator, Leaf> = {
 }
 
 /**
- * One match group: a "Match" combinator select, its children (leaf
+ * One match group: a "Match" combinator picker, its children (leaf
  * rows and nested groups), and a toolbar to add either. Its own file
  * because it renders itself recursively for nested groups and is
  * itself rendered inside the parent's `.map` — the member-file case.
  *
- * The combinator is opaque, so the native `Select` (which speaks
- * strings) is bridged by `String(value)`: options carry the
- * stringified combinator, and a change is mapped back to the real
- * `Combinator` before it reaches `setCombinator`. That keeps
- * `Combinator` fully generic while still using the platform control
- * that brings type-ahead, the mobile wheel, and form semantics for
- * free.
+ * The picker is `QueryBuilderCombinator`, a `Listbox` rather than the
+ * native `Select` this shipped with — see that file for why it is a
+ * component and how it stays generic over an opaque `Combinator`.
  */
 export const QueryBuilderGroup = <Combinator, Leaf>({
   combinatorOptions,
@@ -54,16 +58,16 @@ export const QueryBuilderGroup = <Combinator, Leaf>({
   depth,
   labels,
   node,
+  renderCombinator,
   renderLeaf,
   state,
   tree,
 }: QueryBuilderGroupProps<Combinator, Leaf>): ReactNode => {
   const children = selectChildNodes(state, node.id)
 
-  const selectOptions = combinatorOptions.map((option) => ({
-    label: option.label,
-    value: String(option.value),
-  }))
+  const setCombinator = (nextCombinator: Combinator) => {
+    tree.setCombinator(node.id, nextCombinator)
+  }
 
   const card = (
     <Card
@@ -74,22 +78,21 @@ export const QueryBuilderGroup = <Combinator, Leaf>({
       <div className="flex flex-col gap-3">
         <div className="flex items-start justify-between gap-2">
           <div className="min-w-52">
-            <Field label="Match">
-              <Select
-                onChange={(nextValue) => {
-                  const match = combinatorOptions.find(
-                    (option) =>
-                      String(option.value) === nextValue,
-                  )
-
-                  if (match) {
-                    tree.setCombinator(node.id, match.value)
-                  }
-                }}
-                options={selectOptions}
-                value={String(node.combinator)}
+            {renderCombinator ? (
+              renderCombinator({
+                nodeId: node.id,
+                onChange: setCombinator,
+                options: combinatorOptions,
+                value: node.combinator,
+              })
+            ) : (
+              <QueryBuilderCombinator
+                label={labels.match}
+                onChange={setCombinator}
+                options={combinatorOptions}
+                value={node.combinator}
               />
-            </Field>
+            )}
           </div>
 
           {depth === 0 ? null : (
@@ -118,6 +121,7 @@ export const QueryBuilderGroup = <Combinator, Leaf>({
                   key={child.id}
                   labels={labels}
                   node={child}
+                  renderCombinator={renderCombinator}
                   renderLeaf={renderLeaf}
                   state={state}
                   tree={tree}

package/src/index.ts

@@ -160,6 +160,11 @@ export type {
 export { Menu } from "./Menu/Menu.tsx"
 export type { ModalProps } from "./Modal/Modal.tsx"
 export { Modal } from "./Modal/Modal.tsx"
+export type {
+  PickerOption,
+  PickerProps,
+} from "./Picker/Picker.tsx"
+export { Picker } from "./Picker/Picker.tsx"
 export type { PopoverProps } from "./Popover/Popover.tsx"
 export { Popover } from "./Popover/Popover.tsx"
 export type {

package/src/sourceRules.test.ts

@@ -373,7 +373,13 @@ test("the barrel is the only place components are re-exported", async () => {
   // both are rendered inside a `.map` — and stay out of this count and
   // the barrel by the `<Name>/<Name>.tsx` rule, exactly as
   // `SegmentedOption` and `ListboxOption` do.
-  expect(componentNames.length).toBe(44)
+  //
+  // `Picker` — a `Listbox` with its trigger already attached — is +1 ->
+  // 45. It is a component rather than a recipe in the docs because the
+  // fleet wrote it four separate times (plex-channels' `SelectListbox`,
+  // board-games' `SelectMenu`, mux-magic's `ListboxPicker`, and twice
+  // inside this package), each with its own hand-rolled chevron.
+  expect(componentNames.length).toBe(45)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)