@charcuterie/ui 2.12.1 → 2.14.0

package/src/QueryBuilder/QueryBuilder.tsx

@@ -0,0 +1,136 @@
+import type { Tree } from "@charcuterie/logic"
+import {
+  selectRootGroup,
+  useStoreValue,
+} from "@charcuterie/logic"
+import type { ReactNode } from "react"
+
+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
+}
+
+export type QueryBuilderProps<Combinator, Leaf> = {
+  /**
+   * The combinator choices offered in every group's "Match" select.
+   * The `value` is opaque — `and`/`or` for a mail rule, `any`/`all`/
+   * `none` for a DSL — and the `label` is what a user reads.
+   */
+  combinatorOptions: readonly {
+    label: string
+    value: Combinator
+  }[]
+  /** 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
+   * non-uniform per-kind shape — only that it can be rendered and
+   * patched. The delete control around each leaf is the builder's.
+   */
+  renderLeaf: (args: {
+    nodeId: string
+    onChange: (value: Leaf) => void
+    value: Leaf
+  }) => ReactNode
+  /**
+   * The `Tree` core from `useTree`, owned by the consumer — the same
+   * arrangement as a `Listbox`'s parent owning `useVisibility`.
+   * `QueryBuilder` subscribes to it and drives it; it never creates
+   * one, so a consumer keeps `serialize()` and the initial tree.
+   */
+  tree: Tree<Combinator, Leaf>
+}
+
+const DEFAULT_LABELS = {
+  addGroup: "Add group",
+  addLeaf: "Add condition",
+  match: "Match",
+  removeGroup: "Remove group",
+  removeLeaf: "Remove condition",
+} satisfies Required<QueryBuilderLabels>
+
+/**
+ * The generic, nestable AND/OR — and any-combinator — group editor.
+ *
+ * Two apps in the fleet grow the same widget: Mail Sifter's nested
+ * mail rules (leaf = field/operator/value, combinators AND/OR) and
+ * mux-magic's job DSL (non-uniform leaves, combinators any/all/none).
+ * Both are a recursive group of conditions with a combinator, so the
+ * value **and** the combinator are opaque here — `Combinator` and
+ * `Leaf` never appear except passed through to the consumer's
+ * `renderLeaf` and its `combinatorOptions`.
+ *
+ * State lives entirely in the `Tree` core from `@charcuterie/logic`;
+ * this component holds none of its own. It subscribes with
+ * `useStoreValue`, so a `patchLeaf` deep in the tree re-renders only
+ * the rows whose node identity changed — the same identity discipline
+ * the state layer is built on.
+ *
+ * The recursion and the per-leaf row each live in their own file
+ * (`QueryBuilderGroup`, `QueryBuilderRow`), not exported: a group
+ * renders groups, and both are rendered inside a `.map`, which is
+ * exactly the shape the member-file rule is for.
+ */
+export const QueryBuilder = <Combinator, Leaf>({
+  combinatorOptions,
+  createLeafValue,
+  labels,
+  renderCombinator,
+  renderLeaf,
+  tree,
+}: QueryBuilderProps<Combinator, Leaf>): ReactNode => {
+  const state = useStoreValue(tree)
+
+  const resolvedLabels = { ...DEFAULT_LABELS, ...labels }
+
+  return (
+    <QueryBuilderGroup
+      combinatorOptions={combinatorOptions}
+      createLeafValue={createLeafValue}
+      depth={0}
+      labels={resolvedLabels}
+      node={selectRootGroup(state)}
+      renderCombinator={renderCombinator}
+      renderLeaf={renderLeaf}
+      state={state}
+      tree={tree}
+    />
+  )
+}

package/src/QueryBuilder/QueryBuilderCombinator.tsx

@@ -0,0 +1,108 @@
+import { useVisibility } from "@charcuterie/logic"
+import type { ReactNode } from "react"
+
+import { Button } from "../Button/Button.tsx"
+import { Listbox } from "../Listbox/Listbox.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 `Listbox`, not 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).
+ * `QueryBuilder` shipped in #84 with a `Select` the day after that
+ * record landed; `charcuterie/prefer-listbox-over-select` did not
+ * catch it because the component-choice block is scoped to app
+ * packages and exempts this one — right for a primitive, wrong for a
+ * composite an app consumes whole.
+ *
+ * ### Why this is its own file
+ *
+ * `Listbox` needs a visibility state, and a group renders one picker
+ * per group inside a recursive `.map`. A hook cannot be called there,
+ * so the picker becomes a component — the same member-file case as
+ * `QueryBuilderRow`.
+ *
+ * ### The name, and why it is not a `Field`
+ *
+ * `Field` wires `<label htmlFor>` by cloning its `id` onto the
+ * control. `Listbox`'s trigger cannot take one: `useAnchoredOverlay`
+ * overwrites the cloned trigger's `id` with the one the panel points
+ * `aria-labelledby` at, so the label would address an element that no
+ * longer carries that id — the exact defect `Field` exists to
+ * prevent. So the caption is plain text and the trigger is named with
+ * `aria-label`.
+ *
+ * That name is `"<label>: <current value>"` rather than bare
+ * `"<label>"` on purpose: the button's visible text is the current
+ * combinator, and WCAG 2.5.3 wants the visible text contained in the
+ * accessible name. "Match" alone would fail it; "Match: ALL — every
+ * condition" reads correctly and keeps each group's control findable
+ * by name.
+ *
+ * The combinator stays opaque here exactly as it is in the rest of
+ * the component: `String(value)` bridges it to the string-valued
+ * `Listbox`, and a selection is mapped back to the real `Combinator`
+ * before it leaves.
+ */
+export const QueryBuilderCombinator = <Combinator,>({
+  label,
+  onChange,
+  options,
+  value,
+}: QueryBuilderCombinatorProps<Combinator>): ReactNode => {
+  const { hide, isVisible, toggle } = useVisibility()
+
+  const currentOption = options.find(
+    (option) => String(option.value) === String(value),
+  )
+
+  const currentLabel = currentOption?.label ?? ""
+
+  return (
+    <div className="flex flex-col gap-1.5">
+      <span className="font-medium text-content-primary text-sm">
+        {label}
+      </span>
+
+      <Listbox
+        isVisible={isVisible}
+        onDismiss={hide}
+        onSelect={(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),
+        }))}
+        selectedValue={String(value)}
+        trigger={
+          <Button
+            appearance="outline"
+            aria-label={`${label}: ${currentLabel}`}
+            intent="neutral"
+            onClick={toggle}
+          >
+            {currentLabel}
+          </Button>
+        }
+      />
+    </div>
+  )
+}

package/src/QueryBuilder/QueryBuilderGroup.tsx

@@ -0,0 +1,189 @@
+import type {
+  Tree,
+  TreeGroupNode,
+  TreeState,
+} from "@charcuterie/logic"
+import { selectChildNodes } from "@charcuterie/logic"
+import type { ReactNode } from "react"
+
+import { Button } from "../Button/Button.tsx"
+import { Card } from "../Card/Card.tsx"
+import { IconButton } from "../IconButton/IconButton.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> = {
+  combinatorOptions: readonly {
+    label: string
+    value: Combinator
+  }[]
+  createLeafValue: () => Leaf
+  /** Root is `0`; nested groups deepen and gain the accent rail. */
+  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
+    value: Leaf
+  }) => ReactNode
+  state: TreeState<Combinator, Leaf>
+  tree: Tree<Combinator, 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 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,
+  createLeafValue,
+  depth,
+  labels,
+  node,
+  renderCombinator,
+  renderLeaf,
+  state,
+  tree,
+}: QueryBuilderGroupProps<Combinator, Leaf>): ReactNode => {
+  const children = selectChildNodes(state, node.id)
+
+  const setCombinator = (nextCombinator: Combinator) => {
+    tree.setCombinator(node.id, nextCombinator)
+  }
+
+  const card = (
+    <Card
+      // Nested groups sit on the sunken surface so the depth reads as
+      // recession, not another raised card floating at the same level.
+      surface={depth === 0 ? "raised" : "sunken"}
+    >
+      <div className="flex flex-col gap-3">
+        <div className="flex items-start justify-between gap-2">
+          <div className="min-w-52">
+            {renderCombinator ? (
+              renderCombinator({
+                nodeId: node.id,
+                onChange: setCombinator,
+                options: combinatorOptions,
+                value: node.combinator,
+              })
+            ) : (
+              <QueryBuilderCombinator
+                label={labels.match}
+                onChange={setCombinator}
+                options={combinatorOptions}
+                value={node.combinator}
+              />
+            )}
+          </div>
+
+          {depth === 0 ? null : (
+            <IconButton
+              appearance="ghost"
+              intent="danger"
+              label={labels.removeGroup}
+              onClick={() => {
+                tree.removeNode(node.id)
+              }}
+              size="sm"
+            >
+              ✕
+            </IconButton>
+          )}
+        </div>
+
+        {children.length === 0 ? null : (
+          <div className="flex flex-col gap-2">
+            {children.map((child) =>
+              child.kind === "group" ? (
+                <QueryBuilderGroup
+                  combinatorOptions={combinatorOptions}
+                  createLeafValue={createLeafValue}
+                  depth={depth + 1}
+                  key={child.id}
+                  labels={labels}
+                  node={child}
+                  renderCombinator={renderCombinator}
+                  renderLeaf={renderLeaf}
+                  state={state}
+                  tree={tree}
+                />
+              ) : (
+                <QueryBuilderRow
+                  key={child.id}
+                  label={labels.removeLeaf}
+                  nodeId={child.id}
+                  onChange={(value) => {
+                    tree.patchLeaf(child.id, value)
+                  }}
+                  onRemove={() => {
+                    tree.removeNode(child.id)
+                  }}
+                  renderLeaf={renderLeaf}
+                  value={child.value}
+                />
+              ),
+            )}
+          </div>
+        )}
+
+        <div className="flex flex-wrap gap-2">
+          <Button
+            appearance="outline"
+            intent="neutral"
+            onClick={() => {
+              tree.addLeaf(node.id, createLeafValue())
+            }}
+            size="sm"
+          >
+            {`+ ${labels.addLeaf}`}
+          </Button>
+
+          <Button
+            appearance="outline"
+            intent="neutral"
+            onClick={() => {
+              tree.addGroup(node.id)
+            }}
+            size="sm"
+          >
+            {`+ ${labels.addGroup}`}
+          </Button>
+        </div>
+      </div>
+    </Card>
+  )
+
+  // Depth is shown with a semantic-token inline-start rail. The colour
+  // utility paints all four sides, but only the inline-start edge has
+  // a width, so only it renders — no raw palette colour anywhere.
+  return depth === 0 ? (
+    card
+  ) : (
+    <div
+      className={toClassName(
+        "border-intent-accent-border border-s-2 ps-3",
+      )}
+    >
+      {card}
+    </div>
+  )
+}

package/src/QueryBuilder/QueryBuilderRow.tsx

@@ -0,0 +1,54 @@
+import type { ReactNode } from "react"
+
+import { IconButton } from "../IconButton/IconButton.tsx"
+
+export type QueryBuilderRowProps<Leaf> = {
+  /** The accessible name of the row's delete control. */
+  label: string
+  nodeId: string
+  onChange: (value: Leaf) => void
+  onRemove: () => void
+  renderLeaf: (args: {
+    nodeId: string
+    onChange: (value: Leaf) => void
+    value: Leaf
+  }) => ReactNode
+  value: Leaf
+}
+
+/**
+ * A single leaf row: the app's own leaf UI, plus the builder's delete
+ * control. Its own file for the same reason `ListboxOption` is —
+ * rendered inside the group's `.map`, so it cannot be an inline
+ * component — and it is a member file (`QueryBuilder*.tsx`, not
+ * `QueryBuilder/QueryBuilder.tsx`), so it stays out of the barrel and
+ * the component count by rule.
+ *
+ * The delete control is an `IconButton` because a bare glyph is not an
+ * accessible name; its required `label` is what makes each row's
+ * remove button findable and unique per condition.
+ */
+export const QueryBuilderRow = <Leaf,>({
+  label,
+  nodeId,
+  onChange,
+  onRemove,
+  renderLeaf,
+  value,
+}: QueryBuilderRowProps<Leaf>): ReactNode => (
+  <div className="flex items-start gap-2">
+    <div className="grow">
+      {renderLeaf({ nodeId, onChange, value })}
+    </div>
+
+    <IconButton
+      appearance="ghost"
+      intent="danger"
+      label={label}
+      onClick={onRemove}
+      size="sm"
+    >
+      ✕
+    </IconButton>
+  </div>
+)

package/src/index.ts

@@ -173,6 +173,11 @@ export {
   toProgressPercent,
   toProgressValue,
 } from "./ProgressBar/progressValue.ts"
+export type {
+  QueryBuilderLabels,
+  QueryBuilderProps,
+} from "./QueryBuilder/QueryBuilder.tsx"
+export { QueryBuilder } from "./QueryBuilder/QueryBuilder.tsx"
 export type {
   RadioGroupProps,
   RadioItem,

package/src/sourceRules.test.ts

@@ -364,7 +364,16 @@ test("the barrel is the only place components are re-exported", async () => {
   // `useToolbarOverflow.ts` and `chooseVisibleCount.ts` are its
   // members and stay out of this count by the `<Name>/<Name>.tsx`
   // rule.
-  expect(componentNames.length).toBe(43)
+  //
+  // `QueryBuilder` — the generic nestable AND/OR (any-combinator) group
+  // editor Mail Sifter's nested rules and mux-magic's job DSL both need
+  // — is the library's first recursive component and its first with a
+  // fully opaque value *and* combinator: +1 -> 44. `QueryBuilderGroup`
+  // and `QueryBuilderRow` are its members — a group renders groups, and
+  // 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)
 
   for (const name of componentNames) {
     expect(barrel).toContain(`export { ${name} }`)