@d4gger/design-system 2.7.0 → 3.0.1

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

@@ -0,0 +1,349 @@
+---
+title: DataTable
+status: canonical
+category: Components
+archetype: composite
+depends_on:
+  - Table
+  - Pagination
+  - Toolbar
+  - 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
+
+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. 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.
+
+## Anatomy & slots
+
+**Parent:** `DataTable` (alias of `DataTable.Root` when the component is a compound).
+
+**Slots:**
+
+| Slot | Element | Renders | Notes |
+|---|---|---|---|
+| `DataTable.Root` | `<div>` | Host element with class | Root container. Writes `data-size` and `data-empty` attributes. |
+| `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. 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` | (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 |
+| `onVisibleColumnIdsChange` | `(visibleColumnIds: Set<string>) => void` | `undefined` | no | Callback when visible columns change. | no |
+| `pagination` | `DataTablePaginationState` | `undefined` | no | Controlled pagination state `{ page, pageSize }`. | no |
+| `onPaginationChange` | `(pagination: DataTablePaginationState) => void` | `undefined` | no | Callback when pagination changes. | no |
+| `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:
+
+- Every prop in this table must exist in `<name>.props.ts` or be typed inline in the TSX file. The runtime prop def is the source.
+- Every prop in `<name>.props.ts` must be in this table. Mismatches fail `qa:contracts`.
+- The `Responsive` column is `no` for all props. DataTable does not support responsive props.
+- `columns` and `data` are required. All other props are optional.
+- The `Type` column uses TypeScript syntax. Generic types are parameterized by `Row`.
+
+## CSS class contract
+
+**Root class:** `dsx-data-table`
+
+**Modifier classes** (driven by `data-*` attributes written by the component):
+
+| Attribute | Allowed values | Class | CSS file |
+|---|---|---|---|
+| `data-size` | `sm`, `md`, `lg` | `.dsx-data-table[data-size="sm"]`, `.dsx-data-table[data-size="md"]`, `.dsx-data-table[data-size="lg"]` | inline styles |
+| `data-empty` | `true` | `.dsx-data-table[data-empty="true"]` | inline styles |
+
+**Slot classes** (for compounds and composites):
+
+| 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 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:**
+
+- DataTable does not animate. No motion contract.
+
+## Token mapping
+
+DataTable uses inline styles with token references. Every CSS value the component paints is a `var(--dsx-*)` token.
+
+| Property | Token | Role |
+|---|---|---|
+| 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-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:
+
+- No raw color, spacing, radius, or motion values in the component. All values reference tokens.
+- Tokens come from `DESIGN.md` and the generated `tokens.css`. The token list is closed; new tokens are a `DESIGN.md` change first.
+- Accent color comes through `var(--dsx-color-accent-primary)` and the `data-accent-color` attribute on the `Theme` wrapper. DataTable does not name brand colors directly.
+
+## Motion contract
+
+| Region | Token | Default | Reduced |
+|---|---|---|---|
+| All regions | `none` | `none` | `none` |
+
+Rules:
+
+- DataTable does not animate. No motion presets are used.
+- All motion respects `prefers-reduced-motion`. The `Reduced` column is `none` for all regions.
+
+## Accessibility
+
+**Roles:**
+
+- `table`. The root `Table` component renders a semantic `<table>` element.
+- `columnheader`. Each `TableHead` renders a `<th>` with `aria-sort` when sortable.
+- `cell`. Each `TableCell` renders a `<td>`.
+- `row`. Each `TableRow` renders a `<tr>`.
+- `searchbox`. The search input renders with `type="search"`.
+- `button`. Sort buttons, pagination buttons, and toolbar buttons render with `type="button"`.
+- `checkbox`. Row selection checkboxes render with `role="checkbox"`.
+
+**Keyboard:**
+
+| Key | Action |
+|---|---|
+| `Tab` | Moves focus to / from the next / previous focusable element. |
+| `Enter`, `Space` | Activates sort buttons, pagination buttons, and checkboxes. |
+| Arrow keys | Navigates the faceted filter option list when open. |
+
+**Focus:**
+
+- Visible focus ring via `var(--dsx-ring-focus)`. The ring must remain visible on dark and light surfaces.
+- Sort buttons, pagination buttons, and checkboxes receive focus in tab order.
+
+**Reduced motion:**
+
+- DataTable does not animate. No motion to reduce.
+
+**Color and meaning:**
+
+- 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:**
+
+- Every interactive element has an accessible name. Sort buttons use the column header text. Pagination buttons use `aria-label="Previous page"`, `aria-label="Next page"`, and `aria-label="Page {n}"`.
+- Search input uses `aria-label="Search table rows"`.
+- Select-all checkbox uses `aria-label="Select all visible rows"` or `aria-label="Deselect all visible rows"`.
+- Row checkboxes use `aria-label="Select row {n}"`.
+
+## Playground demo spec
+
+The Playground docs surface has two parts: the registry entry in `playground_registry_path` that imports the component and its prop defs and defines the render fixture, and the generic doc route at `demo_path` that renders every registered component. The demo spec describes what the registry render function must expose:
+
+**Default story:**
+
+- 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):
+
+- Renders the component with `size="sm"`, `size="md"`, and `size="lg"`.
+- Asserts the matching `data-size` attribute is set.
+
+**Composition story** (for composites):
+
+- 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:**
+
+- Renders the component with empty `data` array.
+- Asserts the `emptyState` content renders and `data-empty="true"` is set.
+
+**Token story:**
+
+- DataTable does not honor `data-accent-color` directly. The pagination active page button uses `var(--dsx-color-accent-primary)`, which responds to the `Theme` wrapper's `accentColor` prop.
+- Renders the component inside a `Theme` wrapper with `accentColor="silver"` and one with `accentColor="bronze"`.
+
+**A11y story:**
+
+- Uses `vitest-axe` to assert the rendered component has no axe violations.
+
+**Props exposed in the playground controls:**
+
+| Prop | Control | Default |
+|---|---|---|
+| `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. `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.
+- `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 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.
+
+**Used by:**
+
+- `Shell (Cabinet)`: DataTable is a common content surface in cabinet shell layouts.
+
+**State boundaries:**
+
+- 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:**
+
+- App-owned data: row data, column definitions, data fetching, sorting logic (if server-side), filtering logic (if server-side), pagination logic (if server-side). The consumer owns the `PaginatedResponse` contract (`offset`, `limit`, `sortBy`, `sortOrder`, `totalCount`).
+- DS-owned visuals: token bindings, slot classes, table structure, pagination controls, toolbar layout, faceted filter UI, sort icons, selection checkboxes.
+
+**Backend pagination contract:**
+
+The app owns data fetching and the `PaginatedResponse` contract. The contract is:
+
+- `PaginationQuery`: `{ offset: number, limit: number, sortOrder: 'asc' | 'desc' }`. Sent by the app to the backend.
+- `PaginationParams`: `{ offset: number, limit: number, sortBy: string, sortOrder: 'asc' | 'desc' }`. Extended query with sort field.
+- `PaginatedResponse`: `{ totalCount: number, offset: number, limit: number, items: Row[] }`. Returned by the backend.
+
+DataTable does not implement this contract. The app maps the contract to DataTable's controlled props:
+
+- `pagination.page` maps to `Math.floor(offset / limit) + 1`.
+- `pagination.pageSize` maps to `limit`.
+- `onPaginationChange` maps to updating `offset` and `limit` in the query.
+- `data` maps to `items` from the response.
+- `totalCount` is not a DataTable prop. The app passes `items.length` as `data.length`.
+
+## Penpot build recipe
+
+> Optional. Penpot is a visual reference, not a code authority. Keep this section when the component has a published Penpot asset, or when the spec needs to call out a visual decision the package does not encode. Skip the section when the component is utility or layout-primitive; the package code is the only authority.
+
+DataTable does not have a Penpot build recipe. The package code is the only authority.

package/dist/docs/{date-picker.md → components/date-picker.md}

@@ -3,13 +3,6 @@ title: DatePicker
 status: canonical
 category: Components
 archetype: adapter-backed
-package_path: packages/d4gger-design-system/src/components/datePicker/DatePicker.tsx
-css_path: packages/d4gger-design-system/src/styles/components/datepicker.css
-props_path: packages/d4gger-design-system/src/components/datePicker/datePicker.props.ts
-test_path: packages/d4gger-design-system/src/test/components/DatePicker.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:
   - Calendar
   - Popover
@@ -20,7 +13,7 @@ depends_on:
 
 # DatePicker
 
-> 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
 

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

@@ -3,19 +3,12 @@ title: Dialog
 status: canonical
 category: Components
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/dialog/Dialog.tsx
-css_path: packages/d4gger-design-system/src/styles/components/dialog.css
-props_path: packages/d4gger-design-system/src/components/dialog/dialog.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Dialog.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/overlay.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on: []
 ---
 
 # Dialog
 
-> 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
 
@@ -175,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. |
@@ -305,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:**
 
@@ -315,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:**
@@ -351,7 +348,7 @@ Rules:
 
 | Shape | Property | Token | Token type | Penpot property name |
 |---|---|---|---|---|
-| `<Content frame>` | fill | `var(--dsx-color-surface-overlay)` | Color | `fills` |
+| `<Content frame>` | fill | `var(--dsx-color-panel-translucent)` | Color | `fills` |
 | `<Content frame>` | radius | `var(--dsx-rounded-xl)` | Radius | `borderRadius` |
 | `<Content frame>` | spacing | `var(--dsx-space-lg)` | Spacing | `padding` |
 | `<Title text>` | typography | `var(--dsx-typography-headline-medium-*)` | Typography | `typography` |
@@ -364,7 +361,7 @@ Rules:
 
 | State | Content fill | Content shadow |
 |---|---|---|
-| `default` | `var(--dsx-color-surface-overlay)` | `var(--dsx-shadow-elevation-3)` |
+| `default` | `var(--dsx-color-panel-translucent)` | `var(--dsx-shadow-elevation-3)` |
 | `focus-visible (action)` | `var(--dsx-color-primary)` | `var(--dsx-shadow-focus-ring)` |
 
 ### Variant model

package/dist/docs/{direction-provider.md → components/direction-provider.md}

@@ -3,18 +3,12 @@ title: DirectionProvider
 status: canonical
 category: Foundations
 archetype: utility
-package_path: packages/d4gger-design-system/src/components/directionProvider/DirectionProvider.tsx
-props_path: packages/d4gger-design-system/src/components/directionProvider/directionProvider.props.ts
-test_path: packages/d4gger-design-system/src/test/components/DirectionProvider.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/utility.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on: []
 ---
 
 # DirectionProvider
 
-> 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
 

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

@@ -2,22 +2,16 @@
 title: Drawer
 status: canonical
 category: Components
-archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/drawer/Drawer.tsx
-css_path: packages/d4gger-design-system/src/styles/components/drawer.css
-props_path: packages/d4gger-design-system/src/components/drawer/drawer.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Drawer.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/overlay.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
+archetype: adapter-backed
 depends_on:
+  - vaul
   - Dialog
   - Flex
 ---
 
 # Drawer
 
-> 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
 

package/dist/docs/{dropdown-menu.md → components/dropdown-menu.md}

@@ -3,26 +3,16 @@ title: DropdownMenu
 status: canonical
 category: Components
 archetype: radix-compound
-package_path: packages/d4gger-design-system/src/components/dropdownMenu/DropdownMenu.tsx
-css_path: packages/d4gger-design-system/src/styles/components/dropdown-menu.css
-props_path: packages/d4gger-design-system/src/components/dropdownMenu/dropdownMenu.props.ts
-test_path: packages/d4gger-design-system/src/test/components/DropdownMenu.test.tsx
-demo_path: apps/playground/app/(themeable)/docs/[component]/page.tsx
-playground_registry_path: apps/playground/lib/registry/overlay.tsx
-playground_manifest_path: apps/playground/lib/component-manifest.ts
 depends_on:
   - "@radix-ui/react-dropdown-menu (the underlying Radix primitive; `DropdownMenu.Root`, `Trigger`, `Content`, `Label`, `Separator`, `Group`, `Sub`, `RadioGroup`, `CheckboxItem`, `RadioItem`, `SubTrigger`, `SubContent` proxy to it)"
   - "Menu (the internal abstraction; `MenuContent`, `MenuItem`, `MenuPortal`, `MenuRoot`, `MenuSeparator` are wrapped to share the framer-motion content open / close animation and the portal theme mirroring)"
   - "@radix-ui/react-slot (powers `asChild` on `Shortcut` and the prop-def bag on `Item` / `SubTrigger`)"
-  - _internal/BaseDialog (PortalThemeBoundary + PortalThemeWrapper; mirrors the `data-dsx-*` attribute contract into the content portal; `MenuContent` consumes the wrapper)
-  - _internal/motion (MOTION_TRANSITIONS.menu for the content open / close animation, MOTION_TRANSITIONS.reduced for `prefers-reduced-motion: reduce`; consumed by `MenuContent` and inherited by the DropdownMenu content)
-  - _internal/helpers/extractProps (turns the prop defs on `Item`, `SubTrigger`, and `Shortcut` into merged class + style output)
   - Icon (the `chevron-right` glyph on the sub-trigger; the `check` / `minus` glyphs on checkbox items)
 ---
 
 # DropdownMenu
 
-> 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
 
@@ -168,9 +158,9 @@ Every CSS value the component paints is a `var(--dsx-*)` token. The `dropdown-me
 | Content min-width | `var(--dsx-size-menu-min-width)` | Dropdown minimum width. |
 | Content padding | `var(--dsx-space-xs)` | Content gutter. |
 | Content border radius | `var(--dsx-rounded-lg)` | Content corner roundness. |
-| Content background | `var(--dsx-color-surface-overlay)` | Dropdown surface. |
+| 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. |
@@ -224,7 +214,7 @@ Rules:
 
 **Focus:**
 
-- The CSS file does not declare a focus ring; the shared menu item style in `_internal/baseMenu.css` paints the focus ring on `:focus-visible`. The ring stays visible on dark and light surfaces.
+- The CSS file does not declare a focus ring; the shared menu item style in `_internal/baseMenu.css` paints the focus ring on `:focus-visible`. The ring is **inset** (`inset 0 0 0 2px`) so it follows the item radius and never collides with the menu frame. The ring stays visible on dark and light surfaces.
 
 **Reduced motion:**
 
@@ -283,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/{editable.md → components/editable.md}

@@ -3,11 +3,6 @@ title: Editable
 status: canonical
 category: Components
 archetype: composite
-package_path: packages/d4gger-design-system/src/components/editable/Editable.tsx
-css_path: packages/d4gger-design-system/src/styles/components/editable.css
-props_path: packages/d4gger-design-system/src/components/editable/editable.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Editable.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on:
   - Text (the visible value uses body-medium typography tokens; the runtime does not import the `Text` component, but the rendered string and placeholder share the same body-medium ramp)
   - Icon (lucide-react `Pencil`, `Check`, `X`)
@@ -17,7 +12,7 @@ depends_on:
 
 # Editable
 
-> 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
 
@@ -52,6 +47,9 @@ The roster lists `Editable.Root`, `Editable.Preview`, and `Editable.Input` in th
 | `onCancel` | `() => void` | `undefined` | no | Called when the user cancels the edit (Escape, the cancel button). The value is reset to `defaultValue` in uncontrolled mode; in controlled mode the consumer owns the reset. | no |
 | `placeholder` | `string` | `'Enter text...'` | no | Placeholder text shown inside the preview span when the value is empty. | no |
 | `submitOnBlur` | `boolean` | `true` | no | When `true`, blur on the input commits the edit (calls `onSubmit` and exits edit mode). When `false`, blur keeps edit mode open and only the explicit submit / cancel affordances end it. | no |
+| `activationMode` | `'click' \| 'dblclick' \| 'focus'` | `'click'` | no | How the preview enters edit mode. `dblclick` needs a double click (safe for headings); `focus` activates on focus. Keyboard (Enter/Space on the focused preview) always works. | no |
+| `disabled` | `boolean` | `false` | no | Disables preview activation, input, and action buttons; root takes `dsx-editable--disabled` + `data-disabled`. | no |
+| `invalid` | `boolean` | `false` | no | Error state: input paints the error border and carries `aria-invalid`. | no |
 | `variant` | `'default' \| 'ghost'` | `'default'` | no | Visual variant. Writes `data-variant`. The CSS only declares a root-level hook today; visual treatment is reserved. | no |
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Control padding and font size. Drives `data-size` and the per-size CSS overrides on preview and input. | no |
 | `radius` | `'none' \| 'sm' \| 'md' \| 'lg' \| 'full'` | `undefined` | no | Corner radius override for the input. Writes `data-radius`; the CSS does not currently declare matching overrides — see the Anomalies section. | no |

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

@@ -3,17 +3,12 @@ title: Em
 status: canonical
 category: Primitives
 archetype: primitive
-package_path: packages/d4gger-design-system/src/components/em/Em.tsx
-css_path: packages/d4gger-design-system/src/styles/components/em.css
-props_path: packages/d4gger-design-system/src/components/em/em.props.ts
-test_path: packages/d4gger-design-system/src/test/components/Em.test.tsx
-demo_path: apps/playground/app/page.tsx
 depends_on: []
 ---
 
 # Em
 
-> 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
 
@@ -110,7 +105,7 @@ Rules:
 
 ## Playground demo spec
 
-The demo file at `demo_path` exposes the component to the playground. The playground lives at `apps/playground/app/` (Next.js app router, no per-component routes today). The `demo_path` recorded here is the current playground root; the spec assumes a single shared page that renders all components. Per-component routes are an aspirational target and not yet present in the repo.
+`Em` is registered in `apps/playground/lib/registry/typography.tsx` under the `em` key. The registry entry imports `emPropDefs` and renders the component with a sample emphasis span. Per-component route: `/docs/em`.
 
 **Default story:**
 
@@ -126,7 +121,7 @@ The demo file at `demo_path` exposes the component to the playground. The playgr
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper. Em has no accent-color or surface dependencies, so the story asserts the italic style is visually unchanged between `accentColor="amber"`, `accentColor="silver"`, and `accentColor="bronze"`.
+- Renders inside a `Theme` wrapper. Em has no accent-color or surface dependencies, so the story asserts the italic style is visually unchanged between `accentColor="rift"`, `accentColor="warp"`, and `accentColor="ray"`.
 
 **A11y story:**