@d4gger/design-system 3.0.0 → 4.0.0

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. |
@@ -237,6 +239,8 @@ Rules:
 
 ## Playground demo spec
 
+The live connection-settings example uses the package Select for Region and a nested Popover for display density. Apply closes only the child popover; Save region reports the selected value and returns focus to the dialog launcher. Long-content mode verifies reachable body and footer controls.
+
 **Default story:**
 
 - Renders `DialogRoot` with a `Trigger` and `Content` containing `Header`, `Body`. Asserts the content has `dsx-dialog__content` and `data-size="md"`.
@@ -272,7 +276,7 @@ Rules:
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="silver"` and one with `accentColor="bronze"`. Asserts the `data-accent-color` attribute on the content wrapper.
+- Renders inside a `Theme` wrapper with `accentColor="rift"` and one with `accentColor="warp"`. Asserts the `data-accent-color` attribute on the content wrapper.
 
 **Props exposed in the playground controls:**
 
@@ -298,6 +302,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 +313,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/drawer.md

@@ -51,8 +51,6 @@ A mobile or edge-attached modal overlay that slides in from any edge of the view
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
 | `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Drawer content size; writes `data-size` attribute. | no |
-| `height` | `string` (responsive) | `undefined` | no | Responsive height override via CSS variable. | yes |
-| `width` | `string` (responsive) | `undefined` | no | Responsive width override via CSS variable. | yes |
 | `className` | `string` | `undefined` | no | Extra classes appended to `dsx-drawer__content`. | no |
 
 **Header props:**
@@ -76,7 +74,7 @@ Standard Radix `Title` and `Description` props plus `className`.
 Rules:
 
 - `direction` on Root is wired through `extractProps`.
-- `size`, `height`, and `width` on Content are wired through `extractProps`.
+- `size` on Content are wired through `extractProps`.
 - `asChild` on Header and Footer is wired through `extractProps`.
 - The Root manages open state through a controllable hook (`useControllableDrawerOpenState`) that supports both controlled and uncontrolled modes.
 - The Root provides `DrawerOpenContext` and `DrawerDirectionContext` so Content can access the open state and direction for motion calculations.
@@ -102,12 +100,12 @@ Rules:
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
 | `data-direction` (on content) | `top`, `right`, `bottom`, `left` | `.dsx-drawer__content[data-direction='...']` | `drawer.css` |
-| `data-size` (on content) | `sm`, `md`, `lg` | (no CSS rules in source; reserved for consumer extension) | n/a |
+| `data-size` (on content) | `sm`, `md`, `lg` | Top/bottom minimum-height and side-panel width bands | n/a |
 | `data-slot` | `drawer-overlay`, `drawer-content`, `drawer-handle`, `drawer-header`, `drawer-footer`, `drawer-title`, `drawer-description` | (CSS hook only) | n/a |
 
 **Responsive behavior:**
 
-- Content `height` and `width` props are responsive via CSS variables (`--dsx-r-height`, `--dsx-r-width`).
+- Content size is single-valued. It does not expose responsive height/width props. Viewport caps and scrolling are intrinsic.
 
 **Reduced motion:**
 
@@ -208,7 +206,7 @@ Rules:
 
 **Token story:**
 
-- Renders inside a `Theme` wrapper with `accentColor="silver"` and `accentColor="bronze"`. Drawer does not track `data-accent-color` directly; the story asserts the overlay and content surfaces are visually unchanged.
+- Renders inside a `Theme` wrapper with `accentColor="astral"` and `accentColor="spark"`. Drawer does not track `data-accent-color` directly; the story asserts the overlay and content surfaces are visually unchanged.
 
 **A11y story:**
 
@@ -243,3 +241,16 @@ Rules:
 
 - App-owned data: the drawer content, the trigger label, the action handlers, and the open state when controlled.
 - DS-owned visuals: token bindings, the slot CSS classes, the motion presets, and the portal theme mirroring.
+
+## Overlay review containment
+
+Content caps at 100dvh and its containing viewport width, wraps long words,
+and scrolls vertically. Direct content regions do not shrink into each other.
+Left/right content uses height=100dvh with min-height=0 and width bands capped
+at 100%; top/bottom content retains its minimum-height size bands. No width
+media query is required. `/docs/drawer` opens all four directions and offers
+short/long content to verify both the first row and the footer after scrolling.
+
+The package disables Vaul’s offscreen ::after filler on its scrolling shell.
+That pseudo-element otherwise adds blank scroll range and covers bottom-drawer
+footer controls after scrolling; it is unnecessary for the bounded surface.

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

@@ -39,7 +39,7 @@ A button-triggered secondary action menu. The DS `DropdownMenu` wraps `@radix-ui
 | `DropdownMenu.CheckboxItem` | Radix `DropdownMenu.CheckboxItem` | `dsx-dropdown-menu__item` + `dsx-dropdown-menu__item-indicator` | Checkbox row. Renders `check` or `minus` indicator. |
 | `DropdownMenu.RadioItem` | Radix `DropdownMenu.RadioItem` | `dsx-dropdown-menu__item` + `dsx-dropdown-menu__item-indicator` + `dsx-dropdown-menu__radio-dot` | Radio row. |
 | `DropdownMenu.SubTrigger` | Radix `DropdownMenu.SubTrigger` | `dsx-dropdown-menu__item` + `dsx-dropdown-menu__sub-trigger` + optional `data-inset` + `chevron-right` | Row that opens the sub-content. |
-| `DropdownMenu.SubContent` | Radix `DropdownMenu.SubContent` inside `MenuContent` (no portal) | `dsx-dropdown-menu__content` | The submenu panel. `MenuContent` is invoked with `forceMount`, `open`, and `portal === null` so the sub-content renders inline. |
+| `DropdownMenu.SubContent` | Radix `DropdownMenu.SubContent` inside portal-mounted `MenuContent` | `dsx-dropdown-menu__content` | The submenu panel tracks its own Sub open state and uses a portal so the parent scroll frame does not clip it. forceMount remains consumer-controlled. |
 | `DropdownMenu.Shortcut` | `<span>` (or `Slot` child when `asChild`) | `dsx-dropdown-menu__shortcut` | Keyboard hint rendered on the right. |
 
 The roster's `Parent / Slots` column lists `DropdownMenu.Root`, `DropdownMenu.Trigger`, `DropdownMenu.Content`, `DropdownMenu.Label`, `DropdownMenu.Separator`, `DropdownMenu.Item`, `DropdownMenu.Group`. The source exports the full Radix part set through `Object.assign`, including `Sub`, `RadioGroup`, `Portal`, `CheckboxItem`, `RadioItem`, `SubTrigger`, `SubContent`, and `Shortcut`. The spec records the full set so the public surface is unambiguous.
@@ -71,7 +71,7 @@ The roster's `Parent / Slots` column lists `DropdownMenu.Root`, `DropdownMenu.Tr
 
 ### `DropdownMenu.Trigger`, `DropdownMenu.Label`, `DropdownMenu.Separator`, `DropdownMenu.Group`, `DropdownMenu.Sub`, `DropdownMenu.RadioGroup`, `DropdownMenu.Portal`, `DropdownMenu.CheckboxItem`, `DropdownMenu.RadioItem`, `DropdownMenu.SubTrigger`, `DropdownMenu.SubContent`
 
-These proxy the corresponding Radix props. `DropdownMenu.Trigger` accepts the standard Radix trigger props (no class). `DropdownMenu.Label` and `DropdownMenu.Group` accept the standard Radix props. `DropdownMenu.SubContent` accepts the same `align` and `side` props as `Content`; the portal is forced to `null` so the sub-content renders inline.
+These proxy the corresponding Radix props. `DropdownMenu.Trigger` accepts the standard Radix trigger props (no class). `DropdownMenu.Label` and `DropdownMenu.Group` accept the standard Radix props. `DropdownMenu.SubContent` accepts the same `align` and `side` props as `Content`; Sub preserves controlled/uncontrolled open props; SubContent uses the Radix portal and its owning Sub state.
 
 ### `DropdownMenu.Item`
 
@@ -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:**
 
@@ -287,3 +288,12 @@ Rules:
 
 - App-owned data: the command set, the disabled reasons, the trigger element, and the keyboard shortcut strings.
 - DS-owned visuals: the `dsx-dropdown-menu__*` slot classes, the token bindings, the data-attribute contract, and the open / close animation.
+
+## Overlay review interaction
+
+Submenus are absent while closed unless forceMount is requested. Sub owns
+controlled/uncontrolled state and SubContent receives that state through a
+private context; it is no longer forced open. Portalling matches the
+[Radix submenu anatomy](https://www.radix-ui.com/primitives/docs/components/dropdown-menu)
+and keeps the submenu outside the parent’s overflow frame. The live example
+demonstrates working Profile/Settings, Autosave and Share project actions.

package/dist/docs/components/em.md

@@ -105,7 +105,7 @@ Rules:
 
 ## Playground demo spec
 
-`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`.
+`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`. The live example uses English and Russian sentence context plus a slotted span.
 
 **Default story:**
 

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

@@ -41,7 +41,7 @@ A card-based file selection surface with a dropzone, a list of file rows, and a
 
 | Prop | Type | Default | Required | Description | Responsive |
 |---|---|---|---|---|---|
-| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Card-level size token. Drives `data-size`. | no |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | no | Card-level size; `sm` uses a wrapping inline attachment layout, `md`/`lg` use a centered drop area. Drives `data-size`. | no |
 | `asChild` | `boolean` | `false` | no | Renders the card through `Slot` from `@radix-ui/react-slot`. | no |
 | Standard `Card` props | `CardProps` | n/a | no | The root extends `CardProps`, so variant, radius, and standard card attributes pass through. | no |
 | `children` | `React.ReactNode` | `undefined` | no | `FileUpload.Dropzone`, `FileUpload.List`, and `FileUpload.Item` children. | no |
@@ -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 |
@@ -108,7 +109,7 @@ Rules:
 
 | Attribute | Allowed values | Class | CSS file |
 |---|---|---|---|
-| `data-size` | `sm`, `md`, `lg` | n/a (no size-specific root CSS today) | `file-upload.css` |
+| `data-size` | `sm`, `md`, `lg` | Root controls dropzone layout, minimum height and padding | `file-upload.css` |
 | `data-dragging` | `true` | `.dsx-file-upload__dropzone[data-dragging='true']` thicker accent dashed border + active background (no ring) | `file-upload.css` |
 | `data-status-tone` | `danger` (omitted when `muted`) | `.dsx-file-upload__item:where([data-status-tone='danger']) .dsx-file-upload__status` error color | `file-upload.css` |
 
@@ -134,6 +135,8 @@ Rules:
 **Responsive behavior:**
 
 - The component does not write `@media` rules. None of its prop defs are `responsive: true`. Size is single-value only.
+- The `sm` dropzone places illustration, text and action in a wrapping row. Consumers choose this attachment composition for narrow forms; `md`/`lg` retain the centered drag area. All sizes grow with content and localized labels.
+- FileUpload owns its dropzone minimum height and typography; it does not inherit EmptyState's standalone empty-page minimum height.
 
 **Reduced motion:**
 
@@ -147,7 +150,10 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 |---|---|---|
 | Root layout | `display: grid; gap: var(--dsx-space-md); width: 100%` | Surface layout. |
 | Dropzone width | `width: 100%` | Full width. |
-| Dropzone min-height | `calc(var(--dsx-size-4xl) * 2)` | Tall enough to invite a drop. |
+| Dropzone min-height | `var(--dsx-size-4xl)` / `calc(var(--dsx-size-4xl) * 2)` / `calc(var(--dsx-size-4xl) * 2.5)` | sm/md/lg content-growing minimums. |
+| Dropzone padding / gap | `var(--dsx-space-sm)` / `var(--dsx-space-md)` / `var(--dsx-space-lg)`; gap `var(--dsx-space-sm)` | sm/md/lg padding and compact internal spacing. |
+| Dropzone illustration | `var(--dsx-size-lg)` square | Upload affordance rather than an empty-page illustration. |
+| Dropzone title | `var(--dsx-typography-label-large-*)` | Form-level title, independent of EmptyState headline typography. |
 | Dropzone border | `var(--dsx-border-width-md)` dashed `var(--dsx-color-outline)` | Resting edge, visible against the sunken fill. |
 | Dropzone radius | `var(--dsx-rounded-lg)` | Round corners. |
 | Dropzone background | `var(--dsx-color-surface-sunken)` | Sunken surface. |
@@ -159,9 +165,10 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 | Item icon size | `var(--dsx-size-lg)` square | Round icon slot. |
 | Item icon color | `var(--dsx-color-on-surface-variant)` | Quiet icon. |
 | Item content min-width | `min-width: 0` | Allows the title to ellipsis. |
+| Item content flex / row gap | `flex: 1 1 0`; `var(--dsx-space-sm)` | A short file row can shrink its text column before wrapping media/actions. FileUpload overrides Item's prose-oriented content basis. |
 | Item title overflow | `overflow: hidden; text-overflow: ellipsis; white-space: nowrap` | Long file names truncate. |
 | Item media color | `var(--dsx-color-on-surface-variant)` | Quiet media. |
-| Item actions alignment | `margin-left: auto; flex-direction: column; align-items: flex-end; gap: var(--dsx-space-xs)` | Right-aligned, stacked. |
+| Item actions alignment | `margin-left: auto; flex-direction: column; flex-wrap: nowrap; align-items: flex-end; gap: var(--dsx-space-xs)` | Right-aligned, stacked. Consumer wrappers may define their own inner layout. |
 | Progress width | `width: 100%` | Full row width. |
 | Progress label/status typography | `var(--dsx-typography-label-small-*)` | Small label ramp. |
 | Progress label/status color | `var(--dsx-color-on-surface-variant)` | Quiet label. |
@@ -218,11 +225,11 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Composition story:**
 
-- Renders the full surface: dropzone, list, three items. The first item has a `progress={42}` with no label (the meta line carries the numbers, as in the reference). The second item has a `status="Complete"` and a ghost `IconButton` trash remove action. The third item has a `status="Upload failed"` with `statusTone="danger"` and ghost `IconButton` redo retry + trash remove actions. Asserts each slot renders with the right class, the progress bar renders, the failed row writes `data-status-tone="danger"`, and the actions block sits at the right edge with icons only.
+- One compact live capture surface populates dropzone, list, item, progress and working remove/retry actions after selection. An expandable row-state gallery shows progress, completed and failed rows, followed by forced drag feedback and Rift/Warp token stories. Size comparisons stay in the matrix rather than duplicating three large surfaces in the live example.
 
 **Live capture story:**
 
-- Renders `FileUploadLiveCapture`: a `multiple` dropzone with `onFiles` feeding a simulated upload list (interval-driven `progress` with reference-style `"X MB | Y% • Z sec left"` descriptions), an "Or upload from URL" `Input` + `Upload` `Button` composition appending completed rows, ghost `IconButton` row actions (trash remove always, redo retry on failed rows — retry resets the row to 0%), a fail preview (files with "fail" in the name fail at 60%), and a Cancel / Attach-files footer. Covered by `tests/file-upload.spec.ts` (drag capture, browse capture, zero console issues).
+- Renders `FileUploadLiveCapture` with `size="sm"`, `variant="filled"`, a short title/description and a working Browse files action. A `multiple` dropzone with `onFiles` feeds a simulated upload list (interval-driven progress). Compact rows use the existing `size="sm"` and `icon={null}` options, a file-size description, progress/completion/error status and stacked md ghost icon actions (trash remove always, redo retry on failed rows — retry resets the row to 0%). Files with "fail" in the name fail at 60%. Selection count is announced through a status region. Covered by `tests/file-upload.spec.ts` and `tests/sweep-polish.spec.ts` (drag/browse/keyboard capture, retry/remove, mobile geometry, zero console issues).
 
 **A11y story:**
 
@@ -252,7 +259,7 @@ Every CSS value the component paints is a `var(--dsx-*)` token.
 
 **Composed by consumers (not DS slots):**
 
-- URL upload (`Input` + `Button` appending a completed row) and modal shells with Cancel / Attach-files footers are app composition. The playground `FileUploadLiveCapture` fixture demonstrates both against the same list state.
+- URL fetching and modal shells with Cancel / Attach-files footers are app composition. The primary playground story focuses on file capture and rows; it does not imply FileUpload supplies a URL transport or an attach-to-record action.
 
 **Used by:**