@d4gger/design-system 3.0.0 → 3.0.1

package/dist/docs/components/data-table.md

@@ -7,22 +7,33 @@ depends_on:
   - Table
   - Pagination
   - Toolbar
-  - SearchBar
-  - EmptyState
-  - Pills
+  - Input
+  - Checkbox
+  - Button
+  - Badge
+  - DropdownMenu
+  - Result
 ---
 
 # DataTable
 
+Pagination's page-size label and select wrap together inside their group when the available container is narrow. The full mode continues to expose both; `dense` remains an explicit consumer choice.
+
+Sorting buttons retain their visible header geometry and extend the pointer target to at least 24px through an invisible hit layer inside the padded header cell.
+
 > Consumer note: this document describes public intent and contracts; the package TypeScript declarations are the exact API.
 
 ## Purpose
 
-Advanced table shell with toolbar, search, sort, filter chips, density toggle, pagination, and row actions. The design system owns the visual shell and controlled sort/filter/density UI. The app owns data fetching and the `PaginatedResponse` contract.
+Turnkey data-workspace shell with query tools, sortable and selectable tabular payload, contextual row actions, and pagination. The design system owns the coherent three-zone composition and controlled client state. The app owns data fetching, domain actions, permissions, and the `PaginatedResponse` contract.
+
+**Relationship:** `Table` is the primitive (semantic rows and cells, own density/typography); `DataTable` is the shell over `Table` (`DataTable.tsx` renders `<Table>` and adds toolbar, selection, pagination, and state). Use `Table` for plain data presentation; reach for `DataTable` when sort, filter, density toggling, or pagination is required. See `table.md` for the primitive's ownership statement.
 
 ## 2.6 contract
 
-This section supersedes narrower 2.5 notes below. Columns additionally accept fixed or `{ min, max }` fluid `width`, `align`, `numeric`, `sortable`, `truncate`, and canonical `hideBelow` breakpoints. At most one column may truncate. `sortBy`, `sortOrder`, and `onSortChange` provide controlled sorting while omission retains stable client sorting. `stickyHeader`, controlled/uncontrolled selected row IDs, `onSelectedRowIdsChange`, and `selectionMode="multiple" | "none"` are supported; multiple selection remains the compatibility default.
+This section supersedes narrower 2.5 notes below. Columns additionally accept fixed or `{ min, max }` fluid `width`, `align`, `numeric`, `sortable`, `truncate`, and canonical `hideBelow` breakpoints. At most one column may truncate. Uncontrolled sorting cycles unsorted → ascending → descending → unsorted. Additive `sorting` / `defaultSorting` / `onSortingChange` provide nullable tri-state control; legacy `sortBy`, `sortOrder`, and `onSortChange` retain their two-state controlled contract. `stickyHeader`, controlled/uncontrolled selected row IDs, `onSelectedRowIdsChange`, and `selectionMode="multiple" | "none"` are supported; multiple selection remains the compatibility default.
+
+The default toolbar is composed from the public `DataTable.Toolbar` slots. Inside the nearest DataTable, zero-prop Search, ColumnVisibility, Export, and RowCount slots bind to table state; their existing explicit props remain valid for standalone use. Query, faceted-filter, and tri-state sort changes reset page to 1 and clear selection by default; `resetPageOnViewChange={false}` and `clearSelectionOnViewChange={false}` opt out independently.
 
 `listState="loading" | "empty" | "no-results" | "error"` renders the canonical Result path, or `result` supplies custom content. Fixed columns retain width while the lone truncating fluid column absorbs overflow. Apps continue to own fetching and server query execution; the component emits state changes only.
 
@@ -38,20 +49,36 @@ This section supersedes narrower 2.5 notes below. Columns additionally accept fi
 | `DataTable.Toolbar` | `<div>` | `DataTableToolbar` with class | Toolbar container for search, column visibility, export, and row count controls. |
 | `DataTable.Toolbar.Search` | `<Input>` | Search input | Text search input with `type="search"`. Filters rows client-side. |
 | `DataTable.Toolbar.ColumnVisibility` | `<DropdownMenu>` | Column toggle dropdown | Dropdown with checkbox items for toggling column visibility. |
-| `DataTable.Toolbar.Export` | `<DropdownMenu>` | Export dropdown | Dropdown with CSV and JSON export options. |
+| `DataTable.Toolbar.Export` | `<DropdownMenu>` | Export dropdown | Dropdown with CSV and JSON export options. Menu items state what they export (`CSV file · N rows`, filtered or standalone count); exports over 1000 rows build in chunks with a determinate `Exporting N%` trigger state and polite live announcements instead of a silent freeze. |
 | `DataTable.Toolbar.RowCount` | `<div>` | Row count display | Displays total, filtered, and selected row counts. |
 | `DataTable.Pagination` | `<div>` | `DataTablePagination` with class | Pagination controls with page size selector and page navigation. |
 | `DataTable.FacetedFilter` | `<div>` | `DataTableFacetedFilter` with class | Faceted filter dropdown with checkbox list and search. |
+| `DataTable.BulkBar` | `<div>` | Contextual selection action group | Renders as a second row beneath the query toolbar while rows are selected — the toolbar stays mounted and interactive so filters are never lost. Shows the `{count} selected` status, the `bulkActions` slot, and a built-in Deselect all button. |
 
 The root `DataTable` component is a flat export, not a compound. Subcomponents are attached as static properties: `DataTable.Toolbar`, `DataTable.Pagination`, `DataTable.FacetedFilter`.
 
+## Bulk action guidance
+
+The selection bar answers two questions: how many, and what can I do.
+
+- Count: the `{count} selected` pill is rendered by the shell; the toolbar `RowCount` additionally badges the selected count while unselected. No consumer counting needed.
+- Actions: pass domain actions through `bulkActions` in runway order — Export selected, mutating actions (Assign, Archive), destructive Delete selected last. Deselect all is built-in and always trailing.
+- Scope: bulk actions operate on all selected row IDs across pages, not just the visible page. The demo Delete/export handlers must say so in their notices.
+- Empty selection dissolves the bar; the query toolbar underneath was never unmounted.
+
+## Composition recipes (app-owned, documented here)
+
+- **Header-anchored filters.** A column header may host its own filter trigger (funnel icon button beside the sort button) opening the `FacetedFilter` content for that column. Column option management (add/rename/delete options, per the Topics-editor reference) stays consumer-owned; the DS owns the trigger, the checklist, and select-all.
+- **Row actions.** Per-row operations render as an `actions` column of `IconButton`s (edit, delete) via the column `cell` renderer. Row actions act on one row; `bulkActions` act on the selection — never duplicate one as the other.
+- **Saved searches.** Named filter presets ("Invoices over 500€") are consumer state (a preset → `{ query, rules, sort }` applier); the bar renders the applied result like any other filter state. The DS owns no preset storage.
+
 ## Props contract
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `columns` | `Array<DataTableColumn<Row>>` | `undefined` | yes | Column definitions with `id`, `header`, `accessorKey`, and optional `cell` renderer. | no |
 | `data` | `Row[]` | `undefined` | yes | Row data array. | no |
-| `emptyState` | `ReactNode` | `'No results.'` | no | Content rendered when no rows match filters. | no |
+| `emptyState` | `ReactNode` | (default empty content) | no | Content rendered when no rows match filters. Omitted, the default distinguishes two meanings: a non-empty dataset renders the no-results state (search icon, recovery hint, and a Clear search and filters button whenever query or faceted filters are active — the button clears the query and emits empty faceted filters); an empty dataset renders the dataset-empty state (inbox icon, no action — creation actions are app-owned). | no |
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Table density. Maps to `data-size` attribute. | no |
 | `getRowId` | `(row: Row, rowIndex: number) => React.Key` | `undefined` | no | Custom row ID extractor. Defaults to `rowIndex`. | no |
 | `visibleColumnIds` | `Set<string>` | `undefined` | no | Controlled visible column IDs. Defaults to all columns. | no |
@@ -61,8 +88,24 @@ The root `DataTable` component is a flat export, not a compound. Subcomponents a
 | `facetedFilters` | `Array<DataTableFacetedFilterState>` | `undefined` | no | Controlled faceted filter state array. | no |
 | `onFacetedFiltersChange` | `(facetedFilters: Array<DataTableFacetedFilterState>) => void` | `undefined` | no | Callback when faceted filters change. | no |
 | `toolbar` | `ReactNode` | `undefined` | no | Custom toolbar content. Replaces default search toolbar. | no |
+| `query` | `string` | `undefined` | no | Controlled client query. | no |
+| `defaultQuery` | `string` | `''` | no | Initial uncontrolled client query. | no |
+| `onQueryChange` | `(query: string) => void` | `undefined` | no | Fires when the built-in or context-bound search changes. | no |
 | `showToolbar` | `boolean` | `true` | no | Whether to show the default toolbar. | no |
 | `showPagination` | `boolean` | `false` | no | Whether to show pagination controls. | no |
+| `paginationPosition` | `'top' \| 'bottom' \| 'both'` | `'bottom'` | no | Where the pagination footer renders relative to the table. | no |
+| `paginationAlign` | `'start' \| 'center' \| 'end'` | `undefined` | no | Justification of the pagination footer. Omitted keeps the default `space-between` (range info left, controls right). | no |
+| `paginationFirstLast` | `boolean` | `false` | no | Shows First/Last edge links in the pagination footer (round-2 gap fill). Additive; default renders Previous/numbered/Next only. | no |
+| `paginationPageInput` | `boolean` | `false` | no | Shows the "Page N of M" jump input in the pagination footer (round-2 gap fill). Additive; default hides it. | no |
+| `onTableChange` | `(action: 'paginate' \| 'sort' \| 'filter', state: { pagination, sortBy, sortOrder }) => void` | `undefined` | no | Action-tagged change event for server-side apps. `paginate` fires on page/page-size change, `sort` on sort change, `filter` on built-in search change. Coexists with `onPaginationChange` / `onSortChange` / `onFacetedFiltersChange`. | no |
+| `bulkActions` | `ReactNode` | `undefined` | no | Action slot rendered inside the contextual selection bar after the count label (e.g. Export, Delete buttons). The bar stacks beneath the query toolbar while rows are selected; no actions means count + Deselect all only. | no |
+| `sorting` | `DataTableSortState \| null` | `undefined` | no | Additive controlled tri-state sorting. Explicit `null` means unsorted and takes precedence over legacy sort props. | no |
+| `defaultSorting` | `DataTableSortState \| null` | `null` | no | Initial uncontrolled sort state. | no |
+| `onSortingChange` | `(sorting: DataTableSortState \| null) => void` | `undefined` | no | Emits all tri-state transitions, including unsort. | no |
+| `resetPageOnViewChange` | `boolean` | `true` | no | Resets pagination to page 1 when query, filters, or sort change. | no |
+| `clearSelectionOnViewChange` | `boolean` | `true` | no | Clears row selection when query, filters, or sort change. | no |
+| `wrapScrollArea` | `boolean` | `true` | no | Inner `Table` always rides in a horizontal `ScrollArea` so wide column sets scroll instead of clipping inside the shell (TMA slice-1: `overflow: hidden` shell clipped unreachable columns at 320px). Pass-through of the `Table` prop; set `false` only to restore the bare table. | no |
+| `separator` | `'rules' \| 'grid'` | `'rules'` | no | Separator treatment of the inner `Table`. Pass-through of the `Table` prop. | no |
 
 Rules:
 
@@ -88,14 +131,30 @@ Rules:
 | Slot | Class | CSS file |
 |---|---|---|
 | `DataTable.Toolbar` | `dsx-data-table-toolbar` | inline styles |
+| Toolbar region | `dsx-data-table__toolbar-region` | `data-table.css` |
+| Toolbar trailing actions | `dsx-data-table-toolbar__actions` | `data-table.css` |
 | `DataTable.Pagination` | `dsx-data-table-pagination` | inline styles |
+| Pagination range | `dsx-data-table-pagination__info` | `data-table.css` |
+| Pagination navigation | `dsx-data-table-pagination__navigation` | `data-table.css` |
+| Pagination page size | `dsx-data-table-pagination__page-size` | `data-table.css` |
+| `DataTable.Pagination` (top) | `dsx-data-table-pagination dsx-data-table__pagination-top` | `data-table.css` (flips the separator to `border-bottom`) |
+| `DataTable.BulkBar` | `dsx-data-table__bulk-bar` | `data-table.css` |
+| `DataTable.BulkBar` count | `dsx-data-table__bulk-bar-count` | `data-table.css` |
+| `DataTable.BulkBar` actions | `dsx-data-table__bulk-bar-actions` | `data-table.css` |
+| `DataTable.BulkBar` clear | `dsx-data-table__bulk-bar-clear` | `data-table.css` |
 | `DataTable.FacetedFilter` | `dsx-data-table-faceted-filter` | inline styles |
+| Sort button | `dsx-data-table__sort-button` | `data-table.css` |
+| Sort indicator | `dsx-data-table__sort-indicator` (`data-direction="none" \| "asc" \| "desc"`) | `data-table.css` |
 | Empty cell | `dsx-data-table__empty` | inline styles |
+| Empty content | `dsx-data-table__empty-content` | `data-table.css` |
 
 **Responsive behavior:**
 
-- The component does not write `@media` rules. Responsive sizing is driven by the layout primitives' responsive classes when composed by the app.
-- The component's CSS is breakpoint-agnostic. DataTable uses inline styles for all visual properties.
+- The toolbar and pagination use intrinsic wrapping rather than product breakpoints. At narrow widths the range, navigation, and page-size regions reflow without removing labels or controls — unless the consumer opts into `dense`, which omits the page-size region (and the status summary that duplicates the range) by explicit prop, never by width.
+- Column visibility remains governed by each column's canonical `hideBelow` value.
+
+- Toolbar search and commands form intrinsic flex regions with wrapping at available container width; no toolbar width query is used. The bulk-selection bar wraps count, action group, and deselect control, and its action group can shrink.
+- Legacy `hideBelow` column queries remain an existing public contract. The current breakpoint gate verifies token values; it does not enforce component ownership. Migrating that column contract requires a separate compatibility decision.
 
 **Reduced motion:**
 
@@ -109,12 +168,18 @@ DataTable uses inline styles with token references. Every CSS value the componen
 |---|---|---|
 | Gap | `var(--dsx-space-sm)`, `var(--dsx-space-xs)` | Spacing between controls |
 | Padding | `var(--dsx-space-md)`, `var(--dsx-space-sm)` | Internal gutter |
-| Font size | `var(--dsx-font-size-xs)` | Small text |
+| Font size | `var(--dsx-typography-label-small-font-size)` | Small text |
 | Color | `var(--dsx-color-on-surface)`, `var(--dsx-color-on-surface-variant)` | Text colors |
 | Border | `var(--dsx-color-outline)` | Edge |
 | Radius | `var(--dsx-radius-sm)` | Standard roundness |
 | Background | `var(--dsx-color-surface)`, `var(--dsx-color-surface-raised)` | Surface colors |
 | Accent | `var(--dsx-color-accent-primary)`, `var(--dsx-color-on-accent-primary)` | Active page button |
+| Bulk bar background | `var(--dsx-color-accent-surface)` | Theme-aware tinted surface for the selection bar (round-2: replaces the high-contrast inverse, which read as a broken light strip in dark theme) |
+| Bulk bar text | `var(--dsx-color-on-surface)` | Count, actions, and Clear on the bar |
+| Bulk bar accent edge | `var(--dsx-color-accent-indicator)` | Inset start edge (`box-shadow`) tying the bar to the active accent |
+| Bulk bar separator | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Edge below the bar |
+
+Density: `size` writes `data-size` on the shell root and is forwarded to the inner `Table`, so `sm` / `md` / `lg` cell padding visibly renders through the primitive's size rules (`table.css`). The shell adds no separate row-height scale.
 
 Rules:
 
@@ -164,7 +229,7 @@ Rules:
 
 **Color and meaning:**
 
-- Sort direction is communicated by icon (↑, ↓, ↕) and `aria-sort` attribute, not by color alone.
+- Sort direction is communicated by a single Lucide arrow indicator and `aria-sort`, not by color alone. Unsorted columns show a subdued `arrow-up-down` at reduced emphasis; the active direction collapses to one full-emphasis accent-colored `arrow-up` / `arrow-down` in a fixed-width slot so labels never shift.
 - Selection state is communicated by checkbox checked state and `data-selected` attribute on the row.
 
 **Naming:**
@@ -180,8 +245,8 @@ The Playground docs surface has two parts: the registry entry in `playground_reg
 
 **Default story:**
 
-- Renders the component with `columns` and `data` props. No other props passed.
-- Asserts the root class is `dsx-data-table`.
+- Renders the component with enough rows to produce multiple pages and keeps pagination visible, so pagination-position and pagination-control variants are observable instead of identical two-row shells.
+- Asserts the root class is `dsx-data-table` and exercises the page-size selector against a meaningful dataset.
 
 **Variant story** (one per variant):
 
@@ -192,6 +257,18 @@ The Playground docs surface has two parts: the registry entry in `playground_reg
 
 - Renders the component with `showPagination={true}` and a custom `toolbar` prop.
 - Asserts pagination controls and toolbar render.
+- **Turnkey workspace:** one primary, initially unselected story demonstrates context-bound search, row count, column visibility, export, tri-state sorting, selection actions, and the three-zone pagination footer. Selecting rows stacks the selection bar beneath the query toolbar with real Export selected / Delete selected actions — the toolbar stays mounted so filters are never lost; Deselect all drops the bar.
+- The toolbar is one row at tablet/desktop widths: search occupies the flexible query zone, while row count, Columns, and Export form the trailing tool cluster. Columns and Export use package icons; Export exposes direct `CSV file` / `JSON file` actions rather than checkbox-like format state.
+- The default no-results state is a compact, centred search state with a title and recovery hint; consumers may still replace it through `emptyState` or the richer `result` / `listState` path.
+- **Compact secondary coverage:** density and empty/list-state examples remain concise. Pagination placement/alignment stays unit-tested instead of producing a nine-table fixture wall.
+
+**Composition patterns** (documented guidance, composed by the app — no new DataTable props):
+
+- **KPI header over table:** render a `StatCard` / `Metric` row above the `DataTable` (outside the shell). The shell owns the table; the app owns the summary strip. Keep the strip outside `DataTable.Root` so toolbar, bulk bar, and pagination borders stay contiguous.
+- **Visualization cells:** a column `cell` renderer may return inline visuals — a progress track (filled `div` width `%`, token background) or a sparkline (`ChartArea` with `spark`, or a minimal inline SVG). Cells stay text-sized; visuals never set row height. No `Chart` card chrome inside cells.
+- **View switcher:** a `SegmentedControl` (Table / Board / List) above the shell, owned by the app, toggling between the `DataTable` and alternate surfaces. The switcher is not part of the shell.
+- **Rich person cell:** a column `cell` returning avatar + name + title stacked (avatar `sm`, name label, title muted caption). Compose from `Avatar` + `Text`, not from new table slots.
+- **No ghost variant, by rule:** a borderless read-only table with no toolbar, selection, or pagination is plain `Table`, not a `DataTable` variant. The shell's identity is its workspace chrome (toolbar, bulk bar, pagination borders); stripping all three leaves nothing to vary. Compliance: reach for `Table`, never a ghost prop on `DataTable`.
 
 **State story:**
 
@@ -214,20 +291,24 @@ The Playground docs surface has two parts: the registry entry in `playground_reg
 | `size` | `select` | `md` |
 | `showPagination` | `boolean` | `false` |
 | `showToolbar` | `boolean` | `true` |
+| `paginationPosition` | `select` | `bottom` |
+| `paginationAlign` | `select` | (unset = `space-between`) |
+| `paginationFirstLast` | `boolean` | `false` |
+| `paginationPageInput` | `boolean` | `false` |
 
 ## Wiring notes
 
 **Composes from:**
 
 - `Table`: Renders the semantic table structure (`<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>`).
-- `Pagination`: Renders pagination controls when `showPagination={true}`. DataTable uses its own `DataTablePagination` subcomponent, not the standalone `Pagination` component.
+- `Pagination`: Renders pagination controls when `showPagination={true}`. DataTable uses its own `DataTablePagination` subcomponent, not the standalone `Pagination` component. `paginationFirstLast` / `paginationPageInput` pass through to it; `DataTablePagination` itself accepts `showFirstLast` / `showPageInput` for standalone use.
 - `Toolbar`: Renders toolbar controls. DataTable uses its own `DataTableToolbar` subcomponent, not the standalone `Toolbar` component.
-- `SearchBar`: DataTable does not compose `SearchBar`. It uses a plain `Input` with `type="search"` for client-side filtering.
+- `Input`: `DataTable.Toolbar.Search` renders the client-side query field. The default toolbar uses this public slot rather than a private search row.
 - `EmptyState`: DataTable does not compose `EmptyState`. It renders the `emptyState` prop content in a table cell when no rows match.
 - `Pills`: DataTable does not compose `Pills`. Faceted filters use `DataTableFacetedFilter` subcomponents.
 - `Input`: Renders the search input in the default toolbar.
 - `Checkbox`: Renders row selection checkboxes and the select-all checkbox.
-- `Button`: Renders pagination buttons and toolbar buttons.
+- `Button`: Renders toolbar, export, pagination, and Deselect all actions.
 - `Badge`: Renders active filter count badges in toolbar and faceted filter.
 - `DropdownMenu`: Renders column visibility, export, and faceted filter dropdowns.
 
@@ -237,7 +318,7 @@ The Playground docs surface has two parts: the registry entry in `playground_reg
 
 **State boundaries:**
 
-- Owned by this component: sort state (internal `useState`), search query (internal `useState`), row selection (internal `useState`), pagination state (internal or controlled), faceted filter state (internal or controlled), visible column IDs (internal or controlled).
+- Owned by this component: controlled/uncontrolled query, nullable sort, row selection, pagination, faceted filters, and visible-column state. View-changing transactions reset page and selection by default so stale selections cannot silently cross result sets.
 - Owned by the consumer: row data, column definitions, custom toolbar content, custom empty state content. The consumer passes these in as props.
 
 **Boundary rules:**

package/dist/docs/components/dialog.md

@@ -168,6 +168,8 @@ Rules:
 | Property | Token | Role |
 |---|---|---|
 | Overlay padding | `var(--dsx-space-md)` | Edge gutter between overlay and content. |
+| Overlay z-index | `var(--dsx-z-index-overlay)` | Masks page content (including standalone menu-tier floating content at the dropdown tier). |
+| Content z-index | `var(--dsx-z-index-modal)` | Modal surface; host tier for the shared nested floating tier contract. |
 | Content gap | `var(--dsx-space-lg)` | Vertical rhythm inside the content frame. |
 | Content padding | `var(--dsx-space-lg)` | Internal gutter. |
 | Content border radius | `var(--dsx-rounded-xl)` | Rounded corners. |
@@ -298,6 +300,7 @@ Rules:
 - `Spinner` (from `../spinner/Spinner`): `Dialog.ActionTrigger` renders a spinner while the action promise is in flight.
 - `Theme`: `DialogContent` mirrors the portal theme into a `Theme` wrapper so `data-dsx-*` attributes resolve inside the portal.
 - `framer-motion`: provides the `motion.div` for mount and exit. The reduced motion preset is read from `usePrefersReducedMotion`.
+- `_internal/floatingLayer`: `Dialog.Content` provides `FloatingLayerHostContext` to its body, so menu-tier content (`Select`, `Combobox`, `DropdownMenu`) nested inside the dialog escalates via `dsx-menu__nested` (see the shared nested floating tier contract in `menu.md`). `AlertDialog.Content` inherits this through `Dialog.Content`.
 
 **Used by:**
 
@@ -308,6 +311,7 @@ Rules:
 **State boundaries:**
 
 - Owned by `Dialog`: open state when uncontrolled, presence context, portal theme mirroring, action-trigger loading state, motion preset.
+- Owned by `Dialog`: the nested-host signal — `Dialog.Content` marks its body as a modal-tier host for the shared nested floating tier contract.
 - Owned by the consumer: title copy, description copy, the body content, the action handlers, the close behavior.
 
 **Boundary rules:**

package/dist/docs/components/dropdown-menu.md

@@ -160,7 +160,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token. The `dropdown-me
 | Content border radius | `var(--dsx-rounded-lg)` | Content corner roundness. |
 | Content background | `var(--dsx-color-panel-translucent)` | Dropdown surface. |
 | Content border | `var(--dsx-border-width-sm) solid var(--dsx-color-outline)` | Dropdown edge. |
-| Content z-index | `var(--dsx-z-index-dropdown)` | Stack above page. |
+| Content z-index | `var(--dsx-z-index-dropdown)` standalone; `calc(var(--dsx-z-index-modal, 90) + 2)` when nested inside a modal-tier host (`dsx-menu__nested`, see the shared nested floating tier contract in `menu.md`) | Stack above page; nested menus clear their host surface. |
 | Item min-height | `var(--dsx-size-lg)` | Item touch target. |
 | Item padding | `var(--dsx-space-sm) var(--dsx-space-sm) var(--dsx-space-sm) calc(var(--dsx-space-lg) + var(--dsx-space-sm))` | Item gutter with indicator gutter. |
 | Item border radius | `var(--dsx-rounded-md)` | Item corner roundness. |
@@ -273,6 +273,7 @@ Rules:
 - `_internal/usePrefersReducedMotion`: gates the open / close animation.
 - `_internal/helpers/extractProps`: turns the `Item`, `SubTrigger`, and `Shortcut` prop defs into merged class + style output.
 - `Icon`: the `chevron-right` glyph on the sub-trigger; the `check` / `minus` glyphs on checkbox items.
+- `_internal/floatingLayer`: `useFloatingLayerHost` (consumed in `MenuContent`, covering `Content` and `SubContent`) adds `dsx-menu__nested` when the menu renders inside a modal-tier host (`Popover.Content` / `Dialog.Content`), so the menu paints above its host. Standalone menus never carry the class (see the shared nested floating tier contract in `menu.md`).
 
 **Used by:**
 

package/dist/docs/components/empty-state.md

@@ -87,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:**
 
@@ -152,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
 
@@ -196,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/components/file-upload.md

@@ -58,6 +58,7 @@ A card-based file selection surface with a dropzone, a list of file rows, and a
 | `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 |

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`.