@d4gger/design-system 2.7.0 → 3.0.1

package/dist/docs/{empty-state.md → components/empty-state.md}

@@ -3,13 +3,6 @@ title: EmptyState
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/emptyState/EmptyState.tsx
-css_path: packages/d4gger-design-system/src/styles/components/empty-state.css
-props_path: packages/d4gger-design-system/src/components/emptyState/emptyState.props.ts
-test_path: packages/d4gger-design-system/src/test/components/EmptyState.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/display.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Icon
   - Text
@@ -22,7 +15,7 @@ depends_on:
 
 `EmptyState` is deprecated but not removed. Its normal host delegates to `Result state="empty"` while preserving the `dsx-empty-state` class, size/variant attributes, unavailable/staleness behavior, and public import. New list-state work should use Result and distinguish `empty` from `no-results`.
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -94,6 +87,7 @@ Rules:
 **Responsive behavior:**
 
 - The component does not write `@media` rules. `size` is single-value only.
+- The root and header can shrink within the available width. Long titles and identifiers wrap in both the default Result host and the legacy `asChild` host.
 
 **Reduced motion:**
 
@@ -159,7 +153,7 @@ The component is static.
 
 **Naming:**
 
-- `title` is the accessible name of the section. The description provides supplementary context. The action's accessible name is the consumer's responsibility.
+- `title` provides the visible heading; it does not automatically name the section. Consumers use `aria-labelledby` or `aria-label` when a named region is needed. The action's accessible name is the consumer's responsibility.
 
 ## Playground demo spec
 
@@ -203,6 +197,7 @@ The component is static.
 
 - `Icon`, `Text`, `Button`: the typical content of the illustration, description, and action slots. EmptyState does not import any of these; the consumer supplies the nodes.
 - `@radix-ui/react-slot`: enables `asChild` on the root.
+- `Result`: supplies the normal section host with `state="empty"`; the legacy `asChild` path uses Slot directly.
 - `Card` is not composed; the base card surface is inherited through the CSS import (`@import '../../_internal/baseCard.css'`) so the EmptyState background, border, and shadow resolve through the same tokens as `Card`.
 
 **Used by:**

package/dist/docs/{field.md → components/field.md}

@@ -3,13 +3,6 @@ title: Field
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/field/Field.tsx
-css_path: packages/d4gger-design-system/src/styles/components/field.css
-props_path: packages/d4gger-design-system/src/components/field/field.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Field.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/forms.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Label (the `Field.Label` slot renders through the `Label` primitive for accessible `<label htmlFor>` association)
   - Text (the `Field.Description`, `Field.Error`, and `Field.Title` slots render through the `Text` primitive at the `body-medium` ramp; the runtime does not import `Text` as a value, it composes through it for the typography ramp only — see Anomalies)
@@ -18,7 +11,7 @@ depends_on:
 
 # Field
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -49,9 +42,9 @@ The default form-control wrapper for the design repo. Pairs a label, a control r
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `asChild` | `boolean` | `false` | no | Renders the root through `Slot` from `@radix-ui/react-slot`. | no |
-| `invalid` | `boolean` | `false` | no | Marks the row as invalid. Writes `data-invalid="true"`, derives `data-state="invalid"`, and adds the `dsx-field-invalid` class. | no |
-| `disabled` | `boolean` | `false` | no | Marks the row as disabled. Writes `data-disabled="true"`, derives `data-state="disabled"`, and adds the `dsx-field-disabled` class. | no |
-| `orientation` | `'vertical' \| 'horizontal' \| 'responsive'` | `'vertical'` | no | Row layout. Writes `data-orientation` and the `dsx-field-orientation` class. The CSS uses the attribute to swap to a 2-column grid for `horizontal` and a responsive auto-fit grid for `responsive`. | no |
+| `invalid` | `boolean` | `false` | no | Marks the row as invalid. Writes `data-invalid="true"` and derives `data-state="invalid"`. | no |
+| `disabled` | `boolean` | `false` | no | Marks the row as disabled. Writes `data-disabled="true"` and derives `data-state="disabled"`. | no |
+| `orientation` | `'vertical' \| 'horizontal' \| 'responsive'` | `'vertical'` | no | Row layout. Writes `data-orientation`. The CSS uses the attribute to swap to a 2-column grid for `horizontal` and a responsive auto-fit grid for `responsive`. | no |
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Size of the row. Writes `data-size`. The CSS does not currently declare per-size rules; the attribute is the contract hook. | no |
 | (HTML div props) | n/a | n/a | no | All standard `<div>` attributes are forwarded. | no |
 
@@ -113,6 +106,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Row gap | `var(--dsx-space-xs)` | Default row gap. |
 | Row min-width | `0` | Allows the grid to shrink. |
 | Horizontal label column | `minmax(var(--dsx-size-field-label-min), var(--dsx-size-field-label-max))` | Label column size for `horizontal` orientation. |
+| Horizontal label alignment | `end` | Label text magnetizes toward the control in `horizontal` orientation. |
 | Horizontal row column gap | `var(--dsx-space-md)` | Row gap for `horizontal` orientation. |
 | Responsive column min | `var(--dsx-size-popover-min-width)` | Min column width for `responsive` orientation. |
 | Label color | `var(--dsx-color-on-surface)` | Default label. |
@@ -166,7 +160,7 @@ Rules:
 
 **Color and meaning:**
 
-- Invalid state is communicated by the `data-state="invalid"` attribute, the `data-invalid="true"` attribute, the `dsx-field-invalid` class, and the `Field.Error` slot. The label color also shifts to the error color, so the row does not rely on color alone.
+- Invalid state is communicated by the `data-state="invalid"` attribute, the `data-invalid="true"` attribute, and the `Field.Error` slot. The label color also shifts to the error color, so the row does not rely on color alone.
 
 **Naming:**
 
@@ -176,11 +170,12 @@ Rules:
 
 **Default story:**
 
-- Renders `Field` with a label, an input, and a description. Asserts the root class is `dsx-field`, the label is bound to the input via `htmlFor`, and the description text is rendered.
+- Renders `Field` with a label, an input, and a description. Asserts the root class is `dsx-field`, the label is bound to the input via `htmlFor`, and the description text is rendered. The matrix demo forwards the row's `size` (as the demo control's `density`), `disabled`, and `invalid` to the demo control so each axis reads visually; `Field` itself never sizes or disables children — that wiring is the consumer's composition.
 
 **Orientation story:**
 
-- Renders `Field` with `orientation="vertical"`, `orientation="horizontal"`, and `orientation="responsive"`. Asserts the matching `data-orientation` attribute is set on the root.
+- Renders `Field` with `orientation="vertical"`, `orientation="horizontal"`, and `orientation="responsive"`. Asserts the matching `data-orientation` attribute is set on the root. The `horizontal` story asserts the label is end-aligned toward the control.
+- The `responsive` orientation is an auto-fit grid: it needs room (wider than twice the 200px column minimum) and sibling controls to reflow. The fixture demonstrates it with a two-control dense row in a 640px container; a single control in a narrow container stacks exactly like `vertical` by design.
 
 **State story:**
 
@@ -221,6 +216,7 @@ Rules:
 
 - `Form` (per the roster's `Composed From` column) uses `Field` as its label, description, and error carrier. The `Form` runtime does not import `Field` directly; it composes the same primitives (`Label`, `Text`).
 - Every DS form-row spec (e.g. `Select`, `Combobox`, `InputOtp`) is intended to live inside `Field.Root` for label, description, and error wiring.
+- See [form-ownership.md](./form-ownership.md) for the Field vs Form ownership diagram and nesting rules.
 
 **State boundaries:**
 

package/dist/docs/{file-upload.md → components/file-upload.md}

@@ -3,13 +3,6 @@ title: FileUpload
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/fileUpload/FileUpload.tsx
-css_path: packages/d4gger-design-system/src/styles/components/file-upload.css
-props_path: packages/d4gger-design-system/src/components/fileUpload/fileUpload.props.ts
-test_path: packages/d4gger-design-system/src/test/components/FileUpload.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/forms.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Card
   - EmptyState
@@ -17,15 +10,16 @@ depends_on:
   - Progress
   - Button
   - Icon
+  - react-dropzone
 ---
 
 # FileUpload
 
-> Source of truth: the package source at `package_path`. The spec file mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
-A card-based file selection surface with a dropzone, a list of file rows, and a progress bar per row. The dropzone is built on `EmptyState` and exposes a `dragging` data attribute, the list wraps `Item` rows that compose a `Progress` bar and an actions block, and the root is a `Card` so the whole surface fits the standard card surface treatment.
+A card-based file selection surface with a dropzone, a list of file rows, and a progress bar per row. The dropzone is built on `EmptyState` and captures files through `react-dropzone` (optional peer) when `onFiles` is set — without `onFiles` it renders a visual-only shell with no file input. It exposes a `dragging` data attribute, the list wraps `Item` rows that compose a `Progress` bar and an actions block, and each row carries a `statusTone` (`muted`/`danger`) so failed uploads read in the error color. The root is a `Card` so the whole surface fits the standard card surface treatment.
 
 ## Anatomy & slots
 
@@ -36,9 +30,9 @@ A card-based file selection surface with a dropzone, a list of file rows, and a
 | Slot | Element | Renders | Notes |
 |---|---|---|---|
 | `FileUpload.Root` | `Card.Root` | card host | The surface container. Writes `data-size`. |
-| `FileUpload.Dropzone` | `EmptyState` (rendered through a `<section>`) | dropzone target with title, description, illustration, and action | Exposes `data-dragging` for the active drop state. |
+| `FileUpload.Dropzone` | `EmptyState` (rendered through a `<section>`) | dropzone target with title, description, illustration, and action | Captures files via `react-dropzone` when `onFiles` is set (hidden input + drag events); visual-only shell otherwise. Exposes `data-dragging` for the active drop state. |
 | `FileUpload.List` | `<div>` | vertical list container | The list of `FileUpload.Item` rows. |
-| `FileUpload.Item` | `Item` | one file row with media, content, and actions | Composes `ItemMedia`, `ItemContent` (title, description, optional progress), and `ItemActions` (status, actions). |
+| `FileUpload.Item` | `Item` | one file row with media, content, and actions | Composes `ItemMedia`, `ItemContent` (title, description, status, optional progress), and `ItemActions` (icon actions only). Writes `data-status-tone="danger"` when `statusTone` is `danger`; omits the attribute when `muted`. |
 | `FileUpload.Progress` | `<div>` wrapping `Progress` | progress bar + optional label | When `showValueLabel` is `true` and no `label` is provided, the progress label is ``${Math.round(value)}%``. |
 
 ## Props contract
@@ -62,6 +56,10 @@ A card-based file selection surface with a dropzone, a list of file rows, and a
 | `action` | `ReactNode` | `undefined` | no | Custom action element. Takes precedence over `actionLabel`. | no |
 | `actionLabel` | `ReactNode` | `undefined` | no | Default action label. When set without an explicit `action`, the dropzone renders a `Button` with `variant="outline"`. | no |
 | `onActionClick` | `MouseEventHandler<HTMLButtonElement>` | `undefined` | no | Default action click handler. | no |
+| `accept` | `Accept` (`react-dropzone`) | `undefined` | no | Accepted MIME types / extensions forwarded to `useDropzone`. | no |
+| `multiple` | `boolean` | `undefined` | no | When `true`, the hidden input and drop accept multiple files. | no |
+| `capture` | `boolean \| 'user' \| 'environment'` | `undefined` | no | Mobile capture hint forwarded to the hidden input (`getInputProps`); pairs with `accept="image/*"` for direct camera capture. Omitted by default so desktop file dialogs are unaffected. | no |
+| `onFiles` | `(files: File[]) => void` | `undefined` | no | File capture handler. When set, the dropzone mounts the hidden input and forwards drops and picks; when absent, the dropzone is a visual-only shell (`useDropzone` disabled, no input). | no |
 | `dragging` | `boolean` | `false` | no | Active drop state. Drives `data-dragging="true"`. | no |
 | `asChild` | `boolean` | `false` | no | Renders the dropzone through `Slot` from `@radix-ui/react-slot`. | no |
 | Standard `EmptyState` props | `EmptyStateProps` (without `action`, `description`, `illustration`, `title`) | n/a | no | The dropzone omits the four props it owns and forwards the rest. | no |
@@ -83,7 +81,8 @@ A card-based file selection surface with a dropzone, a list of file rows, and a
 | `icon` | `ReactNode` | `undefined` | no | Custom file icon. When `null`, the icon slot is hidden. Default is `Icon name="file" size="sm"`. | no |
 | `progress` | `number` | `undefined` | no | When a number, the item renders a `FileUpload.Progress` with this value. | no |
 | `progressLabel` | `ReactNode` | `undefined` | no | Custom progress label. Overrides the auto `${value}%` label. | no |
-| `status` | `ReactNode` | `undefined` | no | Status text rendered above the actions block. | no |
+| `status` | `ReactNode` | `undefined` | no | Status text rendered in the content column under the description (name → meta → bar, icons alone on the right). | no |
+| `statusTone` | `'muted' \| 'danger'` | `'muted'` | no | Status text tone. `danger` paints the status in the error color and writes `data-status-tone="danger"` on the item; `muted` keeps the quiet label and omits the attribute. | no |
 | `actions` | `ReactNode` | `undefined` | no | Action affordances rendered in the `ItemActions` block. | no |
 | `asChild` | `boolean` | `false` | no | Renders the item through `Slot`. | no |
 | Standard `Item` props | `Omit<ItemProps, 'children'>` | n/a | no | Forwarded. The interface omits `children` because the item composes its own. | no |
@@ -111,7 +110,8 @@ Rules:
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
 | `data-size` | `sm`, `md`, `lg` | n/a (no size-specific root CSS today) | `file-upload.css` |
-| `data-dragging` | `true` | `.dsx-file-upload__dropzone[data-dragging='true']` border, background, and focus ring | `file-upload.css` |
+| `data-dragging` | `true` | `.dsx-file-upload__dropzone[data-dragging='true']` thicker accent dashed border + active background (no ring) | `file-upload.css` |
+| `data-status-tone` | `danger` (omitted when `muted`) | `.dsx-file-upload__item:where([data-status-tone='danger']) .dsx-file-upload__status` error color | `file-upload.css` |
 
 **Slot classes:**
 
@@ -149,13 +149,13 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Root layout | `display: grid; gap: var(--dsx-space-md); width: 100%` | Surface layout. |
 | Dropzone width | `width: 100%` | Full width. |
 | Dropzone min-height | `calc(var(--dsx-size-4xl) * 2)` | Tall enough to invite a drop. |
-| Dropzone border | `var(--dsx-border-width-sm)` dashed `var(--dsx-color-outline-variant)` | Resting edge. |
+| Dropzone border | `var(--dsx-border-width-md)` dashed `var(--dsx-color-outline)` | Resting edge, visible against the sunken fill. |
 | Dropzone radius | `var(--dsx-rounded-lg)` | Round corners. |
 | Dropzone background | `var(--dsx-color-surface-sunken)` | Sunken surface. |
 | Dropzone transition | `var(--dsx-motion-duration-fast, 150ms)` + `var(--dsx-motion-easing-standard, ease)` | Border, background, and box-shadow transitions. |
-| Dropzone dragging border | `var(--dsx-color-primary)` | Active edge. |
+| Dropzone dragging border | `var(--dsx-border-width-md)` dashed `var(--dsx-color-primary)` | Active edge — thicker and accent-colored, no ring, so the drag state never doubles the outline. |
 | Dropzone dragging background | `var(--dsx-color-high-contrast-container)` | Active fill. |
-| Dropzone dragging shadow | `var(--dsx-shadow-focus-ring)` | Active focus ring. |
+| Dropzone keyboard focus | `var(--dsx-shadow-focus-ring)` on `:focus-visible` | The ring belongs to keyboard focus, not to the drag state. |
 | Dropzone icon color | `var(--dsx-color-primary)` | Active affordance color. |
 | Item icon size | `var(--dsx-size-lg)` square | Round icon slot. |
 | Item icon color | `var(--dsx-color-on-surface-variant)` | Quiet icon. |
@@ -166,6 +166,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Progress width | `width: 100%` | Full row width. |
 | Progress label/status typography | `var(--dsx-typography-label-small-*)` | Small label ramp. |
 | Progress label/status color | `var(--dsx-color-on-surface-variant)` | Quiet label. |
+| Failed status color | `var(--dsx-color-error)` | Error tone, gated behind `data-status-tone="danger"` so `muted` rows never pay for it. |
 
 ## Motion contract
 
@@ -188,7 +189,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Focus:**
 
-- The dropzone relies on the underlying `EmptyState` and `Button` focus rules. The `data-dragging='true'` state adds the focus ring to the dropzone as a visual cue.
+- The dropzone relies on the underlying `EmptyState` and `Button` focus rules. Keyboard focus paints `var(--dsx-shadow-focus-ring)` via `:focus-visible`; the `data-dragging='true'` state instead thickens the dashed border to the accent color, so drag feedback and focus feedback never stack into a double outline.
 
 **Reduced motion:**
 
@@ -200,7 +201,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Naming:**
 
-- The dropzone should expose an accessible name via its `title` prop. The default action button labels itself through the `actionLabel` prop. Each `FileUpload.Item` is named by its `fileName` content.
+- The dropzone should expose an accessible name via its `title` prop. The default action button labels itself through the `actionLabel` prop. Each `FileUpload.Item` is named by its `fileName` content. Row actions are consumer-owned — the recommended pattern is ghost `IconButton`s (`trash` for remove, `redo` for retry) with `aria-label`s naming the file, as the playground fixture demonstrates.
 
 ## Playground demo spec
 
@@ -218,7 +219,11 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Composition story:**
 
-- Renders the full surface: dropzone, list, two items. The first item has a `progress={42}` and a `progressLabel="Uploading…"`. The second item has a `status="Complete"` and an `actions={<Button>Remove</Button>}`. Asserts each slot renders with the right class, the progress bar renders with the rounded percentage, and the actions block sits at the right edge.
+- Renders the full surface: dropzone, list, three items. The first item has a `progress={42}` with no label (the meta line carries the numbers, as in the reference). The second item has a `status="Complete"` and a ghost `IconButton` trash remove action. The third item has a `status="Upload failed"` with `statusTone="danger"` and ghost `IconButton` redo retry + trash remove actions. Asserts each slot renders with the right class, the progress bar renders, the failed row writes `data-status-tone="danger"`, and the actions block sits at the right edge with icons only.
+
+**Live capture story:**
+
+- Renders `FileUploadLiveCapture`: a `multiple` dropzone with `onFiles` feeding a simulated upload list (interval-driven `progress` with reference-style `"X MB | Y% • Z sec left"` descriptions), an "Or upload from URL" `Input` + `Upload` `Button` composition appending completed rows, ghost `IconButton` row actions (trash remove always, redo retry on failed rows — retry resets the row to 0%), a fail preview (files with "fail" in the name fail at 60%), and a Cancel / Attach-files footer. Covered by `tests/file-upload.spec.ts` (drag capture, browse capture, zero console issues).
 
 **A11y story:**
 
@@ -239,22 +244,27 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 - `Card`: the root extends `CardProps` and renders through `Card.Root`.
 - `EmptyState`: the dropzone extends `EmptyStateProps` and renders through `EmptyState`.
+- `react-dropzone` (optional peer `>=14`, declared in `peerDependencies`): the dropzone forwards `accept`, `multiple`, and `onDrop → onFiles` to `useDropzone`. Consumers install it only when they use file capture; the visual-only shell never touches it. The hidden input carries an `aria-label` derived from the dropzone `title`.
 - `Item` and its subcomponents: the file row composes `ItemMedia`, `ItemContent`, `ItemTitle`, `ItemDescription`, and `ItemActions`.
 - `Progress`: the progress block composes the package `Progress` primitive.
 - `Button`: the default dropzone action renders through `Button` with `variant="outline"`.
 - `Icon` (lucide-react `upload`, `file`): the default illustrations.
 - `@radix-ui/react-slot`: enables `asChild` on the root, dropzone, list, and item hosts.
 
+**Composed by consumers (not DS slots):**
+
+- URL upload (`Input` + `Button` appending a completed row) and modal shells with Cancel / Attach-files footers are app composition. The playground `FileUploadLiveCapture` fixture demonstrates both against the same list state.
+
 **Used by:**
 
 - Form specs that need a managed file picker. Apps own the file selection pipeline, the upload progress source, the onAction click handler, and the actual upload transport.
 
 **State boundaries:**
 
-- Owned by FileUpload: the root card surface, the dropzone presentation, the file row layout, the progress block, and the auto `${value}%` label derivation.
-- Owned by the consumer: the file list, the upload progress source, the dropzone click handler, the drag state (`dragging` is a controlled boolean), the per-item `fileName` and `description`, and the surrounding form context.
+- Owned by FileUpload: the root card surface, the dropzone presentation, the file capture engine (drag events, keyboard activation, hidden input) while `onFiles` is set, the file row layout, the progress block, the `statusTone` derivation, and the auto `${value}%` label derivation.
+- Owned by the consumer: the file list, the upload progress source and transport, the dropzone click handler, the forced drag state (`dragging` is a controlled boolean layered over the engine's own active state), the per-item `fileName` and `description`, URL fetching, and the surrounding form or dialog context.
 
 **Boundary rules:**
 
-- App-owned data: the files, the upload pipeline, the drag detection (the package does not implement drag-and-drop, only the visual `dragging` state), the validation, and the persisted references.
-- DS-owned visuals: the surface, the dropzone, the list, the item, the progress block, the icons, the labels, and the size token.
+- App-owned data: the files, the upload pipeline, the validation, the persisted references, URL fetching, and transport-level progress.
+- DS-owned visuals and capture: the surface, the dropzone, the drag-and-drop plus browse capture engine, the list, the item, the progress block, the icons, the labels, the `statusTone`, and the size token.

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

@@ -0,0 +1,255 @@
+---
+title: FilterBar
+status: canonical
+category: Components
+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. `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 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
+
+**Parent:** `FilterBar` (alias of `FilterBar.Root`).
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `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. |
+
+## Props contract
+
+| Prop | Type | Default | Required | Description | Responsive |
+|---|---|---|---|---|---|
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Toolbar density. | no |
+| `aria-label` | `string` | `'Filters'` | no | Accessible toolbar name. | no |
+| `className` | `string` | `undefined` | no | Appended root class. | no |
+
+`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`, `__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 | `--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. 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. 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
+
+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, 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`.

package/dist/docs/{flex.md → components/flex.md}

@@ -3,20 +3,13 @@ title: Flex
 status: canonical
 category: Foundations
 archetype: layout-primitive
-package_path: packages/d4gger-design-system/src/components/flex/Flex.tsx
-css_path: packages/d4gger-design-system/src/styles/components/flex.css
-props_path: packages/d4gger-design-system/src/layout/layout.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Flex.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/layout.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - Box
 ---
 
 # Flex
 
-> Source of truth: the package source at `package_path`. The spec mirrors the source. Edits to the spec must land in the source in the same change, or the QA flags will fire.
+> Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
@@ -80,7 +73,7 @@ The runtime also produces the same set of classes for the `align`, `justify`, an
 | `data-align` | serialized `ResponsiveValue` of `align` | Visual value |
 | `data-justify` | serialized `ResponsiveValue` of `justify` | Visual value |
 
-The `dsx-flex` selector sets `display: var(--dsx-box-display, flex)` so the default Flex container is `display: flex`.
+The `dsx-flex` selector sets `display: var(--dsx-box-display, flex)` so the default Flex container is `display: flex`. It also consumes the `--dsx-flex-direction`, `--dsx-flex-align`, `--dsx-flex-justify`, and `--dsx-flex-wrap` custom properties written through `FLEX_PROP_DEFS` (for example by `Container` flex props), with `row` / `stretch` / `flex-start` / `nowrap` fallbacks. The canonical `Flex` component itself renders the `dsx-r-fd-*` / `dsx-r-ai-*` / `dsx-r-jc-*` / `dsx-r-fw-*` utility classes, which load after `flex.css` and win at equal specificity; the custom-property path is the fallback for `extractLayoutProps` consumers that do not emit those classes.
 
 **Slot classes:** none. Flex is a flat export.