@d4gger/design-system 3.0.0 → 4.0.0

package/dist/docs/components/filter-bar.md

@@ -6,17 +6,26 @@ archetype: composite
 depends_on:
   - Toolbar
   - Button
+  - IconButton
+  - Icon
+  - Pills
+  - Popover
+  - Select
+  - Input
+  - NumberInput
+  - TagsInput
+  - Badge
 ---
 
 # FilterBar
 
 ## 2.6 contract
 
-Root accepts optional `activeCount`. `FilterBar.Control` applies the same wrapper contract to search, select, date, and custom filters and writes `data-active`. `FilterBar.Count` reads the root count. `FilterBar.Clear` is disabled when an explicit active count is zero; omitting `activeCount` preserves the 2.5 uncontrolled compatibility behavior.
+Root accepts optional `activeCount`. `FilterBar.Control` applies the same wrapper contract to search, select, date, and custom filters and writes `data-active`. `FilterBar.Count` reads the root count. `FilterBar.Clear` is disabled when an explicit active count is zero; omitting `activeCount` preserves the 2.5 uncontrolled compatibility behavior. `FilterBar.Search`, `FilterBar.Rules`, `FilterBar.Rule`, `FilterBar.ConditionGroup`, `FilterBar.Condition`, and `FilterBar.Builder` are additive slots: every pre-existing prop and slot keeps working unchanged.
 
 ## Purpose
 
-A product-agnostic, wrapping filter toolbar that organizes consumer-controlled filter controls, result summary, actions, and a clear callback.
+A product-agnostic filter system that organizes consumer-controlled filters three ways: the classic grouped-controls shell (search, select, date, custom filters plus summary, actions, clear), the first-class rule-builder composition (rule chips showing field/operator/value plus a field → operator → value → Apply builder popup), and the advanced-condition composition (AND/OR condition groups with nesting, per-condition trash delete, Clear all). Consumers own all filter values, reset logic, query execution, date-range policy, and domain fields. The DS owns layout, slots, accessible naming, Clear styling, the rule-chip presentation, and the builder popup shell.
 
 ## Anatomy & slots
 
@@ -26,6 +35,13 @@ A product-agnostic, wrapping filter toolbar that organizes consumer-controlled f
 |---|---|---|---|
 | `FilterBar.Root` | `div role="toolbar"` | `dsx-filter-bar` | Default accessible name is `Filters`. |
 | `FilterBar.Group` | `div role="group"` | `dsx-filter-bar__group` | Groups related controls. |
+| `FilterBar.Search` | `div` | `dsx-filter-bar__search` | Flex-growing search cell for the toolbar cluster. |
+| `FilterBar.Rules` | `Pills (ul)` | `dsx-filter-bar__rules` + `dsx-pills` | Rule-chip cluster; accepts `size` (`sm`/`md`/`lg`, default `md`). Optional `maxVisible` collapses overflow behind `+N more` / `Show less` with an optional `Clear` (`onClearAll`). |
+| `FilterBar.Rule` | `Pill (li)` | `dsx-filter-bar__rule` + `dsx-pill` | One rule chip: `field`/`operator`/`value`, optional `count`, remove, click-to-reopen. |
+| `FilterBar.ConditionGroup` | `div` (+ `role="group"` when named) | `dsx-filter-bar__condition-group` | AND/OR condition group with nesting: combinator toggle, `Add condition` / `Add subgroup`, `Clear all`. Buttons render only for the handlers passed. |
+| `FilterBar.Condition` | `div` | `dsx-filter-bar__condition` | One advanced condition: `field`/`operator`/`value`, optional `count`, click-to-reopen, trash delete (`onRemove`). |
+| `FilterBar.ConditionEditor` | `div role="group"` | `dsx-filter-bar__condition-editor` | Docked BI-panel editor for condition trees that outgrow the Builder popup: field rail, operator/value config, Apply/New. |
+| `FilterBar.Builder` | `Popover` | `dsx-filter-bar__builder` on the popup | Field → operator → value → Apply popup. |
 | `FilterBar.Summary` | `div` | `dsx-filter-bar__summary` | Result/filter summary. |
 | `FilterBar.Actions` | `div` | `dsx-filter-bar__actions` | Action cluster. |
 | `FilterBar.Clear` | `Button` | `dsx-filter-bar__clear` | Styled callback only. |
@@ -40,31 +56,200 @@ A product-agnostic, wrapping filter toolbar that organizes consumer-controlled f
 
 `FilterBar.Clear` accepts Button props and an optional `onClear: () => void`; its default children are `Clear filters`. All wrapper slots accept standard div attributes.
 
+`FilterBar.Rules` accepts `size: 'sm' \| 'md' \| 'lg'` (default `'md'`) plus standard list attributes; it renders a `Pills` cluster so rule chips inherit the Pills contract. `maxVisible: number` collapses the cluster: only the first `maxVisible` chips render, followed by an overflow row with `+N more` (expands; `aria-label="Show N more filters"`, `aria-expanded`), `Show less` (collapses), and an optional `Clear` wired to `onClearAll` (rendered only when the handler is passed, `aria-label="Clear all filters"`). Expansion is controlled (`expanded` + `onExpandedChange`) or uncontrolled (`defaultExpanded`, default `false`). `showMoreLabel(hiddenCount)`, `showLessLabel`, and `clearAllLabel` override the overflow chrome. Omitting `maxVisible` preserves the flat chip list.
+
+`FilterBar.Rule` accepts `field`, `operator`, `value` (`ReactNode`, typically strings), `count` (`ReactNode`, typically a number: per-option match count), `size` (default `'md'`), and `active`. `onRemove` adds the Pills removable affordance (omitting it hides the remove button); `onEdit` wraps the field/operator/value label in a button named `Edit filter: <field> <operator> <value>` that reopens the builder (click-to-reopen). Omitting `onEdit` renders static text. Extra children render after the label inside the chip.
+
+`FilterBar.ConditionGroup` accepts `combinator: 'and' | 'or'` (default `'and'`) plus standard div attributes. `editor` docks a `FilterBar.ConditionEditor` inside the group card between the combinator and the rows, making one composed unit: the group owns add/remove/clear, the editor owns field/operator/value. `rowsLabel` (e.g. `Where:`) heads the row stack; `allLabel`/`anyLabel` (e.g. `All/Any of the following are true:`) head the combinator, falling back to `Match all`/`Match any` when only one is set. `gapCombinators` (one combinator per gap, index-aligned to children) with `onGapCombinatorChange` renders And/Or pills between rows for independent per-gap logic (react-querybuilder pattern) and replaces the header toggle; omitting it keeps the single group combinator. Grouping evaluation (e.g. AND-precedence) is consumer-owned. `onCombinatorChange` renders the AND/OR toggle (buttons with `aria-pressed` inside a group named by `combinatorLabel`, default `Match`); omitting it renders the combinator as static text. `onAddCondition`, `onAddSubgroup`, and `onClearAll` render `Add condition` / `Add subgroup` / `Clear all` (overridable via `addConditionLabel`, `addSubgroupLabel`, `clearAllLabel`); each button renders only when its handler is passed, so there are never dead controls. An empty group (no conditions or subgroups) renders the `emptyHint` line (default `No conditions yet — add one below.`) instead of a void, and writes `data-empty="true"` with a dashed frame. Nested groups indent through a rail (inset start border), not just a margin, so depth reads at a glance. Children are conditions (`FilterBar.Condition`) and nested `FilterBar.ConditionGroup`s to any depth. With an `aria-label` the group takes `role="group"`; without one it renders a plain div so unnamed groups never fail naming rules.
+
+`FilterBar.Condition` accepts `field`, `operator`, `value` (`ReactNode`), optional `count`, and standard div attributes. An empty-string `value` renders an explicit `empty` pill (`data-empty="true"`) instead of blank space, in both `Condition` and `Rule`. `onEdit` wraps the label in a button named `Edit filter: <field> <operator> <value>` (click-to-reopen, same naming as `Rule`); `editLabel` overrides that name (needed when `value` is rich content rather than text). `dragProps` (spread onto the row root) enables native drag reorder and renders the grip handle; omitting it hides the grip. Passing `fields` with `onFieldChange`/`onOperatorChange`/`onValueChange` renders the row as live inline editors (field select, operator select, shared value renderer with `renderValue` support) instead of the display label — the Gyaan pattern; omitting `fields` keeps display mode with click-to-reopen. `onRemove` renders a trash `IconButton` (`aria-label` from `removeLabel`, default `Remove condition`); omitting it hides the delete affordance. Extra children render after the delete button.
+
+`FilterBar.Builder` accepts `fields: Array<{ value: string; label?: ReactNode; type?: 'text' | 'number' | 'enum' | 'multi' | 'range' | 'date' | 'person'; operators?: string[]; options?: Array<{ value: string; label?: ReactNode }>; min?: number; max?: number; step?: number; renderValue?: (state: { value: string; onChange: (nextValue: string) => void; id: string }) => ReactNode }>` and an optional global `operators` fallback (default `is`, `is not`, `contains`, `does not contain`). The value editor resolves in order: `renderValue` when provided; a `Select` when `options` are present (or `type: 'enum'`); a `NumberInput` for `type: 'number'` (bridged to the string rule value); a `TagsInput` for `type: 'multi'` (values are comma-joined into the string rule value); a dual-thumb `Slider` for `type: 'range'` (value encodes as `"min..max"`, bounds from `min`/`max`/`step`, default `0`/`100`/`1`); otherwise a free-text `Input` (`date` hints `YYYY-MM-DD`, `person` hints a name). `date` and `person` are intentionally Input-backed in the package: `DatePicker` and `Combobox` carry optional peers the root barrel must not eagerly load, so consumers plug them through `renderValue` from their dedicated subpaths. `count` renders an active-count `Badge` inside the default `+ Add filter` trigger so the bar has one adhesive filter entry with its number attached. `initialRule` seeds the draft and is re-read every time the popup opens, so editing an existing rule is `initialRule={rule}` plus open state. Open state is controlled (`open` + `onOpenChange`) or uncontrolled (`defaultOpen`). `trigger` overrides the default `+ Add filter` outline button. Pass `trigger={null}` for a triggerless controlled popup (the click-to-reopen edit flow: `open` + `onOpenChange` with no visible trigger) — the popup anchors to a zero-size viewport-center span (`dsx-filter-bar__builder-anchor`), so it opens centered and clickable. `title` (default `Add filter`), `submitLabel` (default `Apply`), and `cancelLabel` (default `Cancel`) override the popup chrome. `onApply(rule: { field; operator; value })` fires on Apply; `onCancel` fires on Cancel. Apply stays disabled until field and operator are chosen; Apply and Cancel both close the popup.
+
+## Density scale
+
+All three sizes render explicit rules through `--dsx-filter-bar-*` custom properties (selected with `:where([data-size])` so specificity stays at the policy baseline):
+
+| Size | Padding | Gap | Control height | Summary type |
+|---|---|---|---|---|
+| `sm` | `space-sm` | `space-xs` | `density-control-height-sm` | `label-small` |
+| `md` | `space-md` | `space-sm` | `density-control-height` | `body-small` |
+| `lg` | `space-lg` | `space-md` | `density-control-height-lg` | `body-medium` |
+
+`FilterBar.Rules` stretches to the row control height so chips align with sibling controls. Pair `Rules`/`Rule` `size` with the root `size` so chips and shell step together.
+
+Editable rule labels retain their typography and chip paint with a centered invisible hit layer at least `size-md` (24px) high. Static labels have no hit layer. The layer stays within the label's horizontal bounds so removal remains a separate action.
+
+Inside FilterBar rules, the Pill remove button likewise has a centered invisible `size-md` floor in both dimensions; its icon paint stays unchanged and the button does not shrink as the label wraps. This scoped rule does not alter other Pills compositions.
+
+Rules clusters and individual chips shrink within their parent. Label parts wrap intrinsically and long identifiers can break inside their part, preserving the separate remove button within the chip at narrow widths.
+
+## Rule-builder composition
+
+The prescribed composition for structured filters (LemonSqueezy-style query builders):
+
+```tsx
+<FilterBar activeCount={rules.length}>
+  <FilterBar.Search>{/* search input, consumer-owned */}</FilterBar.Search>
+  <FilterBar.Rules>
+    {rules.map((rule) => (
+      <FilterBar.Rule
+        key={rule.id}
+        field={rule.fieldLabel}
+        operator={rule.operator}
+        value={rule.valueLabel}
+        onRemove={() => removeRule(rule.id)}
+        onEdit={() => editRule(rule)}
+      />
+    ))}
+  </FilterBar.Rules>
+  <FilterBar.Builder fields={fieldDefs} initialRule={editingRule} onApply={applyRule} />
+  <FilterBar.Summary>{summary}</FilterBar.Summary>
+  <FilterBar.Actions>{/* toolbar cluster */}</FilterBar.Actions>
+</FilterBar>
+```
+
+Rule chips belong to the Pills family per the F6 cardinality rule (Tag = lone dismissible chip, Pills = selectable cluster): `Rule` renders a `Pill` with `removable`, never a `Tag`. The builder popup renders a `Popover` whose title wires the popup's accessible name. Consumers own rule state, field definitions, and what Apply executes; the DS owns chip presentation, popup layout, and the field → operator → value step order.
+
+## Advanced-condition composition
+
+The prescribed composition for Gyaan-style advanced filters (AND/OR groups with nesting):
+
+```tsx
+const [group, setGroup] = useState<ConditionGroupState>({ combinator: 'and', conditions: [...], subgroups: [...] })
+
+<FilterBar>
+  <FilterBar.ConditionGroup
+    aria-label="Advanced conditions"
+    combinator={group.combinator}
+    onCombinatorChange={(next) => setGroup({ ...group, combinator: next })}
+    onAddCondition={addCondition}
+    onAddSubgroup={addSubgroup}
+    onClearAll={clearGroup}
+  >
+    {group.conditions.map((cond) => (
+      <FilterBar.Condition
+        key={cond.id}
+        field={labelFor(cond.field)}
+        operator={cond.operator}
+        value={cond.value}
+        onRemove={() => removeCondition(cond.id)}
+      />
+    ))}
+    {group.subgroups.map((sub, i) => (
+      <FilterBar.ConditionGroup key={sub.id} aria-label={`Subgroup ${i + 1}`} /* ...same handlers, nested */ />
+    ))}
+  </FilterBar.ConditionGroup>
+</FilterBar>
+```
+
+Conditions reuse the rule part presentation (`field`/`operator`/`value` spans) but render as group rows with trash delete instead of Pills remove, so the Pill remove affordance and the condition trash affordance never compete. Consumers own the group tree, combinator state, and what Add/Clear executes; the DS owns group layout, nesting indent, toggle presentation, and the action row.
+
+## Condition editor (docked BI panel)
+
+For condition trees that outgrow the Builder popup, `FilterBar.ConditionEditor` docks the editor beside the accumulation surface instead of floating it: a field rail (one button per field def, `aria-pressed` on the active field) on the left, the selected field's operator select plus its value editor on the right, Apply/New beneath. It accepts `fields` (same shape as `Builder`), a controlled `draft` (`{ field, operator, value }`) with `onDraftChange`, an `operators` fallback, `title` (default `Condition editor`), `submitLabel` (default `Apply`), and `newLabel` (default `New`); `onApply` fires Apply (disabled until field and operator are set), `onNew` fires New and renders the New button only when passed — omit it when the hosting group already offers Add condition, so there is exactly one entry point. The operator/value editors are the same internals as the Builder popup — typed editors, `renderValue` hatch, and range encoding behave identically in both. The editor is a single slot (no sub-slots): the value-editor machinery stays internal so the two surfaces cannot drift. Consumers own the draft and what Apply/New executes; the DS owns rail/config/actions layout, the framed card surface, and the named `Condition editor` group.
+
+## Checked-filter pills with counts and overflow
+
+The drill-down multi-select pattern (counts per option, collapse, clear) on the Rules cluster:
+
+```tsx
+<FilterBar.Rules aria-label="Checked filters" maxVisible={2} onClearAll={clearChecked}>
+  {checked.map((f) => (
+    <FilterBar.Rule key={f.id} field={f.field} operator={f.operator} value={f.value} count={f.count} onRemove={() => uncheck(f.id)} />
+  ))}
+</FilterBar.Rules>
+```
+
+`count` paints the per-option match count after the value. Past `maxVisible`, the cluster collapses behind `+N more` with `Show less` to collapse and `Clear` to reset. Faceted drill-down with select-all stays DataTable-owned (`DataTable.FacetedFilter`); this pattern covers the standalone-bar equivalent without duplicating it.
+
+## Toolbar cluster prescription
+
+The shared toolbar cluster, in order: search (`FilterBar.Search`), Columns control (DataTable-owned, see below), Filters button with active-count `Badge`, Export action. The order and behavior are shared with `DataTable.Toolbar`; only the host differs.
+
+- Search flex-grows (`flex: 1 1 12rem`) and collapses first on narrow widths.
+- The Filters button carries a `Badge` count (`FilterBar.Count` reads the root `activeCount` for the same number) and opens the filter surface; it is never a second clear affordance.
+- Export is a plain action; it never mutates filter state.
+
+## FilterBar vs DataTable.Toolbar
+
+`FilterBar` is the standalone bar for custom surfaces: consumer-composed controls, rule chips, and actions with no table attached. `DataTable.Toolbar` is the built-in shell toolbar: search, column visibility, export, and row counts wired to table state (`Search`, `ColumnVisibility`, `Export`, `RowCount`). Use `FilterBar` when the surface is custom; use `DataTable.Toolbar` when the table owns the query. Columns visibility and faceted drill-down multi-select (counts per option, select-all) stay DataTable-owned (`ColumnVisibility`, `FacetedFilter`) and are deliberately not re-implemented here — the toolbar cluster prescription above references them without duplicating them.
+
+## FilterBar → DataTable bridge
+
+Rules are consumer state; `DataTable` consumes them through its controlled filter/search/sort props. The connection story, worked through:
+
+```tsx
+// 1. FilterBar owns the rule drafts (consumer state, never table state).
+const [rules, setRules] = useState<FilterRule[]>([])
+const [query, setQuery] = useState('')
+const [sort, setSort] = useState<{ sortBy: string; sortOrder: 'asc' | 'desc' } | null>(null)
+
+// 2. Translate rules into the table's faceted-filter shape
+//    (DataTableFacetedFilterState: { columnId, accessorKey, selectedValues: Set<string> }).
+const facetedFilters = rules.map((rule) => ({
+  columnId: rule.field,
+  accessorKey: rule.field,
+  selectedValues: new Set([rule.value]),
+}))
+
+// 3. Feed the table; take sort/search back out of it.
+<DataTable
+  columns={columns}
+  data={rows}
+  facetedFilters={facetedFilters}
+  onFacetedFiltersChange={(next) => setRules(fromFaceted(next))}
+  sortBy={sort?.sortBy}
+  sortOrder={sort?.sortOrder}
+  onSortChange={(sortBy, sortOrder) => setSort({ sortBy, sortOrder })}
+/>
+<FilterBar activeCount={rules.length}>
+  {/* rule chips + builder writing `rules`, search writing `query` */}
+</FilterBar>
+```
+
+Direction of travel: FilterBar → consumer state → DataTable props. The table never reads FilterBar slots, and FilterBar never reads table state; the consumer's translation layer (`rules ↔ facetedFilters`) is the only coupling. Sort travels the same road (controlled `sortBy`/`sortOrder`/`onSortChange`). Search stays consumer-side (`FilterBar.Search` writes `query`): client-side apps filter rows with `rules + query` together, and server-side apps send the translated state (`facetedFilters`, `sortBy`/`sortOrder`, `query`) as their query params instead of filtering client-side.
+
+## Composition recipes (app-owned, documented here)
+
+- **Single-filter backends.** When the API accepts one filter, the Builder's `onApply` replaces instead of appends (`setRules([rule])`), and `Rules` renders at most one chip. No Builder prop changes; the cardinality lives in consumer state.
+- **Searchable enums.** Enum fields past ~7 options switch the value editor from `Select` to `Combobox` (list search) via `renderValue`. Below the threshold the built-in `Select` applies.
+- **Refine entry with count.** The `Builder` `count` prop badges the default `+ Add filter` trigger, giving the bar one adhesive filter entry with its number attached. Pair with a view switcher (`SegmentedControl`) and a result count (`FilterBar.Summary`) for the Refine | View | Count trio — composed by the app, never a new slot.
+- **BI-panel advanced builder.** For AND/OR condition trees that outgrow the popup, dock the editor beside the accumulation surface instead of floating it: a field rail (one button per field def) on the left, the selected field's operator select plus its `renderValue` editor on the right, Apply/Cancel beneath, and the `ConditionGroup` rows as the top-to-bottom accumulation below or beside. Row click loads the condition into the panel (selected state); trash removes in place. Every typed editor is reused through `renderValue`, so date/person/number/range behave identically in the panel and the popup. No new slots — arrangement only.
+
 ## CSS class contract
 
-Root `dsx-filter-bar` writes `data-size`. Slot classes are `dsx-filter-bar__group`, `__summary`, `__actions`, and `__clear`. The shell uses flex wrapping without embedded product breakpoints.
+Root `dsx-filter-bar` writes `data-size`. Slot classes are `dsx-filter-bar__group`, `__search`, `__rules`, `__rule`, `__condition-group`, `__condition`, `__summary`, `__actions`, and `__clear`. Rule parts are `dsx-filter-bar__rule-label`, `__rule-field`, `__rule-operator`, `__rule-value` (empty string renders an `empty` pill via `data-empty="true"`), and `__rule-count` (shared by `Rule` and `Condition`); an `active` rule writes `data-active` on the chip. Rules overflow is `dsx-filter-bar__rules-overflow`. Condition-group parts are `__condition-combinator`, `__condition-combinator-label`, `__condition-match-label` (Any/All sentence header), `__condition-children`, `__condition-rows-label` (`Where:` head), `__condition-empty` (hint line for childless groups, which also write `data-empty="true"`), `__condition`, `__condition-label`, and `__condition-actions`; condition rows prepend `__condition-grip` when draggable and lay inline editors out as `__condition-field` / `__condition-operator` / `__condition-value`. Per-gap logic renders `__condition-gap` pill rows between children. nesting indents through a rail (inset start border on the descendant selector), not a depth attribute. Condition rows are full-width flex top-to-bottom: the label grows (long values ellipsize) and the trash delete pins to the right edge. Builder parts are `dsx-filter-bar__builder`, `__builder-anchor` (triggerless centering span), `__builder-field`, `__builder-label`, `__builder-actions`. Condition-editor parts are `dsx-filter-bar__condition-editor` (framed card, `role="group"` named by `title`), `__condition-editor-title`, `__condition-editor-body` (rail + config grid), `__condition-editor-fields` (rail), `__condition-editor-config`, `__condition-editor-field`, `__condition-editor-label`, `__condition-editor-actions`. The editor writes no `data-*` attributes; the rail's active field is `aria-pressed` on the button. The Builder's field/operator/value selects ride the shared nested floating tier (see the contract in `menu.md`): the Builder popup is a `Popover` host, so its option lists escalate to `modal + 2` automatically via `dsx-menu__nested` — the round-3 scoped `dsx-filter-bar__builder-select` override is retired. Rule parts render in the chip font throughout (field, operator, and value share one weight; the operator is distinguished by `on-surface-variant` color only). The shell uses flex wrapping without embedded product breakpoints. No new `data-variant`, `data-accent-color`, `data-radius`, or `data-high-contrast` attributes are written by FilterBar source (Pills, Badge, Popover, Select, Input, IconButton, Icon, and Button write their own in their files), so the component-contract profile stays size-only.
 
 ## Token mapping
 
 | Property | Token | Role |
 |---|---|---|
-| Gap/padding | `var(--dsx-space-sm)` / `var(--dsx-space-md)` | Responsive wrapping rhythm |
+| Gap/padding | `--dsx-filter-bar-gap` / `--dsx-filter-bar-padding` (per-size: `space-xs`–`space-md` / `space-sm`–`space-lg`) | Responsive wrapping rhythm |
 | Border | `var(--dsx-control-separator-color)` | Muted toolbar edge |
 | Background | `var(--dsx-color-surface-raised)` | Toolbar surface |
 | Radius | `var(--dsx-rounded-lg)` | Shell roundness |
+| Control height | `--dsx-filter-bar-control-height` (`density-control-height-sm` / `-height` / `-height-lg`) | Row alignment for chips |
+| Summary type | per-size `label-small` / `body-small` / `body-medium` | Density-matched summary |
+| Rule operator/label | `on-surface-variant`, chip font throughout | Chip part hierarchy |
+| Builder label | `on-surface-variant`, `label-small` | Popup field labels |
 
 ## Motion contract
 
-No motion.
+No motion. The builder popup inherits the Popover motion contract (reduced-motion aware); rule chips have no transitions.
 
 ## Accessibility
 
-The root is a named toolbar. Tab order follows DOM order and controls retain their own semantics; FilterBar does not implement roving focus because it may contain form controls. Groups may provide their own accessible names. Clear is a native button and never mutates sibling controls automatically.
+The root is a named toolbar. Tab order follows DOM order and controls retain their own semantics; FilterBar does not implement roving focus because it may contain form controls. Groups may provide their own accessible names. Clear is a native button and never mutates sibling controls automatically. Rule chips render in a list (`Rules` is a `ul`, including the overflow row which is an `li`); the remove affordance is the Pills remove button and the edit affordance is a named button (`Edit filter: field operator value`), so both are keyboard-reachable with no nested-interactive violation. Condition groups take `role="group"` only when named via `aria-label`; the AND/OR toggle is an `aria-pressed` button pair, the overflow `+N more` carries `aria-expanded` with a counted label, and condition delete is a named trash button (`Remove condition` by default). The builder popup is a Popover with a title-wired accessible name; its field/operator/value controls are labelled (visible label spans for the selects, native label for the value input).
 
 ## Playground demo spec
 
-Show default, all sizes, full slot composition, empty/active summary, light/dark, and alternate accents. The composition story demonstrates source, direction, and a paired DatePicker range using consumer state. Test Clear callback/keyboard behavior and `vitest-axe`.
+The orders workspace separates three consumer-defined bands: search plus the Add filter/More command group; applied rules followed immediately by one Clear filters action; and a passive results count. The applied band exists only while a query or condition is active. Clear resets the query, simple rules, advanced conditions, selection, and page, then hides the emptied advanced editor. Its position follows the labels rather than the far edge of the results row. Advanced conditions have an editable/removable summary chip even while their editor is hidden; hiding that editor does not disable applied conditions. A group's Clear conditions action resets only that group. Advanced filters and Export live in the More menu at every width. Group slots accept layout styles for these full-width bands; the package does not invent a width-driven mode. Search clamps its minimum to the available width. Related commands stay together, with intrinsic wrapping as the containment fallback.
+
+Research: [PatternFly toolbar guidelines](https://www.patternfly.org/components/toolbar/design-guidelines/) group related controls and use overflow for secondary actions. Local Primer Table's named filter/actions regions and ActionBar's grouping/overflow model informed the composition; see the data-stream decisions for pinned source references.
+
+Show ONE complete workspace in the live example: a 28-row orders dataset (text, person, status, currency, date, tag columns) with FilterBar query + typed rule Builder, removable and editable rule chips, a toggleable advanced AND/OR condition group wired to the same rows, a passive selectable DataTable payload with bulk actions and the DataTable pagination footer. The workspace Builder plugs `renderValue` with the `DatePicker` (Placed) and `Combobox` (Owner) dedicated subpaths — the package stays Input-backed per barrel policy; rule chips display owner labels while rule state keeps raw values. The workspace DataTable sets `wrapScrollArea` so the 7-column table scrolls internally at narrow widths and the bar wraps into clean rows instead of stretching past the viewport. Consumer-owned `query`, rules, and group tree filter the same dataset; the summary counts visible rows (`N of M orders`); Export downloads those rows with a count label; Clear resets query, rules, group, selection, and page. The result table uses `showToolbar={false}` so the FilterBar is the only tool zone, with `selectionMode="multiple"` so the bulk bar proves itself against live filters. Use a ten-row page to make filtering and pagination directly testable. The dataset-empty state is proven on the DataTable route; the workspace proves the filtered-empty state with its Clear recovery. Advanced condition-group and overflow mechanics stay unit-tested component capabilities; the workspace additionally wires one live group tree.
 
 ## Wiring notes
 
-Consumers own all filter values, reset logic, query execution, date-range policy, and domain fields. The DS owns only layout, slots, accessible naming, and Clear styling.
+Consumers own all filter values, rule state, field definitions, reset logic, query execution, date-range policy, and domain fields. The DS owns only layout, slots, accessible naming, Clear styling, rule-chip presentation, and the builder popup shell. Drill-down multi-select with per-option counts and select-all is owned by `DataTable.FacetedFilter`; column visibility is owned by `DataTable.Toolbar.ColumnVisibility`.