@box-kite/react 2.2.3 → 2.2.5

package/.claude/rules/box-kite-rules.md

@@ -84,4 +84,12 @@ globs: '**/*.{ts,tsx,jsx}'
 
 48. **In development the console is part of the answer: read it.** Three mistakes write nothing, or the wrong thing, and say so in one `[box-kite]` warning that names what rendered and the line to write instead. **A value a prop does not take** — `bgColor="bleu-500"` → `wrote no CSS … Did you mean "blue-500"?`, `opacity={50}` → `It takes one of 0, 0.1, …`. **An HTML attribute at the top level** — `href`, `onClick`, `data-*`, `aria-*` → `write props={{ href: ... }}`. **A number in a unit it almost certainly did not mean**, which is valid CSS and so the one mistake nothing else catches: `fontSize={4}` is 4px text (`For 16px write fontSize={16}`), `lineHeight={1.5}` a 1.5px line, `transitionDuration={0.3}` 0.3ms, `brightness={1.1}` 1.1%. Each prints once per value, in any environment whose `NODE_ENV` is not `production` — a test run included, which is the cheapest place to see them — and never in a production build, where a rejected value is still dropped with nothing said. `Box.configure({ warnings: false })` turns them off; `check_styles` in `@box-kite/mcp` gives the same three verdicts before anything renders.
 
+49. **A design that stops at a subtree is `Box.createComponents()`, not `Box.components()`.** `Box.components()` is one registry for the whole app: a second call merges into the first, so two designs cannot share a page through it. `const aurora = Box.createComponents({ button: { styles: { borderRadius: 999 } } })` takes the same shape and registers nothing, and `<Box.Components value={aurora}>` — or `<Box.Theme use="local" components={aurora}>`, a design in light and dark in one wrapper — applies it to every Box inside, pre-built components included. `base` is what it merges over: `'global'` (default, the app's own `Box.components()`), `'builtin'` (ignores them) or another registry. Props still beat the design. It is identified by its content, so an inline one costs no cache, but declare it at module scope. The provider renders no element and a Server Component cannot read it. Two designs that both name `button` type as `interface ComponentsTypes extends MergeComponentsAndVariants<[typeof aurora, typeof harbor]> {}`.
+
+50. **A list of things to read and pick from is `<List>`, and one action covers each item.** `<List><List.Item chevron><List.Media variant="avatar">AL</List.Media><List.Content><List.Row><List.Title lines={1}><List.Action props={{ href: '/inbox/42' }}>Ada Lovelace</List.Action></List.Title><List.Meta>9:41</List.Meta></List.Row><List.Description lines={2}>…</List.Description></List.Content></List.Item></List>` (`components/list`). **An item is a flex row of three slots** — `List.Media` leading (`variant` `icon`/`avatar`/`image`), `List.Content` taking the room, `List.End` trailing (a value over its label, aligned to the end) — and the content is a column of `List.Row`s, each its parts side by side with the last pushed to the end: a main row (the title and its time) and a `secondary` one under it (smaller, muted). `wrap` on a row or an item lets the parts wrap instead of squeezing; `List.Overline`/`List.Title`/`List.Description` take `lines={1|2|3}` (an ellipsis, then a clamp); `List.Meta` is a small value that never wraps; `List.Fields` + `List.Field label` is a `<dl>` of labelled values; `List.Group label level sticky` is a section with a nested list of its own. **`List.Action` goes in the title and its `::after` covers the item**, so the whole row presses while the name a reader hears is the title alone — an `href` in `props` makes it an `<a>`, an `htmlFor` a `<label>` (a press anywhere ticks that checkbox), neither a `<button>` with a top-level `onClick`; a control of the item's own (a switch, a menu, that checkbox) goes in `List.Actions`, which sits above it. **Four things to know.** It renders on a server — no hook, no context — so the list's look reaches its items as **custom properties**: `variant="plain"|"card"|"separated"` on `List`, and `vars={{ 'list-divider': …, 'list-divider-inset': '4.5rem', 'list-item-radius': …, 'list-sticky-top': '4rem' }}` to tune it. The style tree is **paint only** (`list`, `list.item`, `list.media`, `list.muted`, `list.action`, `list.label`), the hairlines and tints mixed from `currentColor`; the spacing is each part's default props, so `<List.Item py={1}>` wins and `Box.components` cannot move it. Hover, pressed, `aria-current` and disabled are read off the action with `:has()` — no prop — and `selected` on an item is a tint only, the state a reader hears belonging on the control. And it is a `<ul role="list">` (Safari drops the semantics otherwise; `tag="ol"` for an ordered one), **not a composite widget**: every action is a tab stop and the arrows stay the page's — arrow-key selection among options is a listbox, `Combobox` or `Select`.
+
+51. **On a phone a DataGrid is a list, and a column says where it goes in an item.** Below `def.list.breakpoint` (576px) of **the grid's own width** — not the viewport's — `layout: 'auto'` (the default) draws each row as a list item: `list: 'title'` is its name and the button that opens it, `'kicker'` a small line above, `'subtitle'` a line under, `'end'` the one value opposite the title with its column's name under it, `'field'` a labelled value, `'detail'` the record view only, `'hidden'` nowhere. Left unset, the first column is the title, the first end-aligned one the end, the next four fields (`def.list.fields`) and the rest detail. A press opens the **record view** — every column of one row in a bottom sheet with a pager (buttons, Left/Right, a swipe) that follows the list's sort and filters, and an **Edit** button on each editable column through the same `onCellEdit`. Sort and filters are bottom sheets behind two pills, the filters in force are removable chips, **Select** is a mode (a press ticks instead of opening, and a bar pinned to the bottom counts the selection), and the list grows twenty a **Show more** — a button, so the totals and the page below stay reachable — or pages when the host paginates. **Four things to know.** It is a `<List>` (rule 50) — each row a `List.Item` whose title is the `List.Action` — not a restyled `role="grid"`, so the `list` tree styles its rows. It is a chunk of its own, loaded the first time a grid is narrow, and the grid draws its table until it arrives — in a test, `await loadListLayout()` first. Unmeasured is a table, so a server prerenders the table and `layout: 'list'` is how to say otherwise. And the selection bar sticks to the viewport, so no ancestor may be `overflow: hidden`/`auto` — `css={{ overflow: 'clip' }}` clips without being a scroll container. `layout: 'table'` keeps the table at every width.
+
+52. **Swiping, reordering and windowing a list are three client entries on top of `List`.** `<SwipeItem endActions={<SwipeItem.Action variant="danger" onClick={remove}>Delete</SwipeItem.Action>} fullSwipe>` (`components/swipeItem`) is a `List.Item` — same parts, `size`, `chevron`, `selected` — whose row slides to open a tray; the first action of each tray is the outermost, and `fullSwipe` performs it by clicking it, so its `onClick` is where the command lives. The actions are tab stops and focus opens their tray, but a swipe is a path gesture: put the same commands where a press reaches too. `<SortableList onOrderChange={(order) => setIds(order)}>` (`components/sortableList`) with `<SortableList.Item value={id} label={name}>` and a `<SortableList.Handle />` in each: **the app owns the order** and renders it, `onOrderChange` fires once per drop and per keyboard step, `onOrderCommit` when it settles; the keyboard grabs (Enter/Space, arrows, Escape puts back), and a press on a handle then a press on another item drops it there. `<VirtualList items={rows} itemKey={(row) => row.id}>{(row) => <List.Item>…</List.Item>}</VirtualList>` (`components/virtualList`) renders a window, measuring each item by key; the scroller is the nearest scrolling ancestor or the page, `scrollerRef` when that is wrong, and `onRangeChange` fetches the next page. **Three things to know.** The children function returns exactly one `<li>` per item and nothing around it, since the list measures its children. A windowed list has no `List.Group`s and find-in-page cannot see what is not rendered. And a `SwipeItem` windows like any item, but a `SortableList` holds its whole list: reorder a list short enough to render, window one too long to.
+
 Full reference: `src/BOX_KITE_AI_CONTEXT.md` or invoke `/box-kite` skill.

package/.claude/skills/box-kite/SKILL.md

@@ -157,4 +157,12 @@ Detect the package manager from the lock file rather than asking:
 
 48. **In development the console is part of the answer: read it.** Three mistakes write nothing, or the wrong thing, and say so in one `[box-kite]` warning that names what rendered and the line to write instead. **A value a prop does not take** — `bgColor="bleu-500"` → `wrote no CSS … Did you mean "blue-500"?`, `opacity={50}` → `It takes one of 0, 0.1, …`. **An HTML attribute at the top level** — `href`, `onClick`, `data-*`, `aria-*` → `write props={{ href: ... }}`. **A number in a unit it almost certainly did not mean**, which is valid CSS and so the one mistake nothing else catches: `fontSize={4}` is 4px text (`For 16px write fontSize={16}`), `lineHeight={1.5}` a 1.5px line, `transitionDuration={0.3}` 0.3ms, `brightness={1.1}` 1.1%. Each prints once per value, in any environment whose `NODE_ENV` is not `production` — a test run included, which is the cheapest place to see them — and never in a production build, where a rejected value is still dropped with nothing said. `Box.configure({ warnings: false })` turns them off; `check_styles` in `@box-kite/mcp` gives the same three verdicts before anything renders.
 
+49. **A design that stops at a subtree is `Box.createComponents()`, not `Box.components()`.** `Box.components()` is one registry for the whole app: a second call merges into the first, so two designs cannot share a page through it. `const aurora = Box.createComponents({ button: { styles: { borderRadius: 999 } } })` takes the same shape and registers nothing, and `<Box.Components value={aurora}>` — or `<Box.Theme use="local" components={aurora}>`, a design in light and dark in one wrapper — applies it to every Box inside, pre-built components included. `base` is what it merges over: `'global'` (default, the app's own `Box.components()`), `'builtin'` (ignores them) or another registry. Props still beat the design. It is identified by its content, so an inline one costs no cache, but declare it at module scope. The provider renders no element and a Server Component cannot read it. Two designs that both name `button` type as `interface ComponentsTypes extends MergeComponentsAndVariants<[typeof aurora, typeof harbor]> {}`.
+
+50. **A list of things to read and pick from is `<List>`, and one action covers each item.** `<List><List.Item chevron><List.Media variant="avatar">AL</List.Media><List.Content><List.Row><List.Title lines={1}><List.Action props={{ href: '/inbox/42' }}>Ada Lovelace</List.Action></List.Title><List.Meta>9:41</List.Meta></List.Row><List.Description lines={2}>…</List.Description></List.Content></List.Item></List>` (`components/list`). **An item is a flex row of three slots** — `List.Media` leading (`variant` `icon`/`avatar`/`image`), `List.Content` taking the room, `List.End` trailing (a value over its label, aligned to the end) — and the content is a column of `List.Row`s, each its parts side by side with the last pushed to the end: a main row (the title and its time) and a `secondary` one under it (smaller, muted). `wrap` on a row or an item lets the parts wrap instead of squeezing; `List.Overline`/`List.Title`/`List.Description` take `lines={1|2|3}` (an ellipsis, then a clamp); `List.Meta` is a small value that never wraps; `List.Fields` + `List.Field label` is a `<dl>` of labelled values; `List.Group label level sticky` is a section with a nested list of its own. **`List.Action` goes in the title and its `::after` covers the item**, so the whole row presses while the name a reader hears is the title alone — an `href` in `props` makes it an `<a>`, an `htmlFor` a `<label>` (a press anywhere ticks that checkbox), neither a `<button>` with a top-level `onClick`; a control of the item's own (a switch, a menu, that checkbox) goes in `List.Actions`, which sits above it. **Four things to know.** It renders on a server — no hook, no context — so the list's look reaches its items as **custom properties**: `variant="plain"|"card"|"separated"` on `List`, and `vars={{ 'list-divider': …, 'list-divider-inset': '4.5rem', 'list-item-radius': …, 'list-sticky-top': '4rem' }}` to tune it. The style tree is **paint only** (`list`, `list.item`, `list.media`, `list.muted`, `list.action`, `list.label`), the hairlines and tints mixed from `currentColor`; the spacing is each part's default props, so `<List.Item py={1}>` wins and `Box.components` cannot move it. Hover, pressed, `aria-current` and disabled are read off the action with `:has()` — no prop — and `selected` on an item is a tint only, the state a reader hears belonging on the control. And it is a `<ul role="list">` (Safari drops the semantics otherwise; `tag="ol"` for an ordered one), **not a composite widget**: every action is a tab stop and the arrows stay the page's — arrow-key selection among options is a listbox, `Combobox` or `Select`.
+
+51. **On a phone a DataGrid is a list, and a column says where it goes in an item.** Below `def.list.breakpoint` (576px) of **the grid's own width** — not the viewport's — `layout: 'auto'` (the default) draws each row as a list item: `list: 'title'` is its name and the button that opens it, `'kicker'` a small line above, `'subtitle'` a line under, `'end'` the one value opposite the title with its column's name under it, `'field'` a labelled value, `'detail'` the record view only, `'hidden'` nowhere. Left unset, the first column is the title, the first end-aligned one the end, the next four fields (`def.list.fields`) and the rest detail. A press opens the **record view** — every column of one row in a bottom sheet with a pager (buttons, Left/Right, a swipe) that follows the list's sort and filters, and an **Edit** button on each editable column through the same `onCellEdit`. Sort and filters are bottom sheets behind two pills, the filters in force are removable chips, **Select** is a mode (a press ticks instead of opening, and a bar pinned to the bottom counts the selection), and the list grows twenty a **Show more** — a button, so the totals and the page below stay reachable — or pages when the host paginates. **Four things to know.** It is a `<List>` (rule 50) — each row a `List.Item` whose title is the `List.Action` — not a restyled `role="grid"`, so the `list` tree styles its rows. It is a chunk of its own, loaded the first time a grid is narrow, and the grid draws its table until it arrives — in a test, `await loadListLayout()` first. Unmeasured is a table, so a server prerenders the table and `layout: 'list'` is how to say otherwise. And the selection bar sticks to the viewport, so no ancestor may be `overflow: hidden`/`auto` — `css={{ overflow: 'clip' }}` clips without being a scroll container. `layout: 'table'` keeps the table at every width.
+
+52. **Swiping, reordering and windowing a list are three client entries on top of `List`.** `<SwipeItem endActions={<SwipeItem.Action variant="danger" onClick={remove}>Delete</SwipeItem.Action>} fullSwipe>` (`components/swipeItem`) is a `List.Item` — same parts, `size`, `chevron`, `selected` — whose row slides to open a tray; the first action of each tray is the outermost, and `fullSwipe` performs it by clicking it, so its `onClick` is where the command lives. The actions are tab stops and focus opens their tray, but a swipe is a path gesture: put the same commands where a press reaches too. `<SortableList onOrderChange={(order) => setIds(order)}>` (`components/sortableList`) with `<SortableList.Item value={id} label={name}>` and a `<SortableList.Handle />` in each: **the app owns the order** and renders it, `onOrderChange` fires once per drop and per keyboard step, `onOrderCommit` when it settles; the keyboard grabs (Enter/Space, arrows, Escape puts back), and a press on a handle then a press on another item drops it there. `<VirtualList items={rows} itemKey={(row) => row.id}>{(row) => <List.Item>…</List.Item>}</VirtualList>` (`components/virtualList`) renders a window, measuring each item by key; the scroller is the nearest scrolling ancestor or the page, `scrollerRef` when that is wrong, and `onRangeChange` fetches the next page. **Three things to know.** The children function returns exactly one `<li>` per item and nothing around it, since the list measures its children. A windowed list has no `List.Group`s and find-in-page cannot see what is not rendered. And a `SwipeItem` windows like any item, but a `SortableList` holds its whole list: reorder a list short enough to render, window one too long to.
+
 Full reference: `references/` beside this file, and `docs/props.md` inside the package.

package/.claude/skills/box-kite/references/components.md

@@ -18,6 +18,7 @@ Which component replaces which `<Box tag>`, and the three that carry a pattern o
 | a menu button and its menu           | `<Menu>`                               | `components/menu`                                                |
 | sections that open one at a time     | `<Accordion>`                          | `components/accordion`                                           |
 | one "show more" disclosure           | `<Collapsible>`                        | `components/accordion`                                           |
+| rows to read and pick from           | `<List>`                               | `components/list`                                                |
 | a value dragged along a track        | `<Slider>`                             | `components/slider`                                              |
 | how far a task has got               | `<Progress>`                           | `components/progress`                                            |
 | a message sent from anywhere         | `<Toaster>` + `toast()`                | `components/toaster`                                             |
@@ -67,6 +68,51 @@ own tab stop; Down/Up/Home/End are a shortcut. Style the open state with `ariaAt
 never a variant, and leave `accordion.track`/`accordion.clip` alone: padding on a grid item cannot be
 squeezed, so it floors the `0fr` track — which is why your padded panel sits inside the clip (#142).
 
+## List
+
+```tsx
+import List from '@box-kite/react/components/list';
+
+<List variant="card">
+  <List.Group label="Today" level={3} sticky>
+    <List.Item chevron>
+      <List.Media variant="avatar">AL</List.Media>
+      <List.Content>
+        <List.Row>
+          <List.Title lines={1}>
+            <List.Action props={{ href: '/inbox/42' }}>Ada Lovelace</List.Action>
+          </List.Title>
+          <List.Meta>9:41</List.Meta>
+        </List.Row>
+        <List.Row secondary>Re: the engine</List.Row>
+        <List.Description lines={2}>It might compose elaborate pieces of music.</List.Description>
+      </List.Content>
+    </List.Item>
+  </List.Group>
+</List>;
+```
+
+`List`: `variant` (`plain`, `card`, `separated`; dividers by default), `tag="ol"`. `List.Item`: `size` (`sm` 44px, `md` 56px,
+`lg` 72px), `wrap`, `selected`, `chevron`. `List.Row`: `wrap`, `secondary`. `List.Title`/`Description`/`Overline`: `lines`
+(`1` ellipsis, `2`/`3` clamp). `List.Media`: `variant` `icon`/`avatar`/`image`. `List.Field`: `label`. `List.Group`:
+`label`, `level`, `sticky`. `List.Content`, `List.Meta`, `List.End`, `List.Actions`, `List.Fields`: every Box prop.
+
+`List.Action` goes in the title and covers the item: `props={{ href }}` is a link, `props={{ htmlFor }}` the label of a
+checkbox in `List.Actions` (a pick-list), otherwise a button with `onClick`. Anything else interactive goes in
+`List.Actions`, which sits above the action. No hook and no context — it renders on a server — so the look reaches
+the items as `--list-divider`, `--list-divider-inset`, `--list-item-frame`, `--list-item-radius` and
+`--list-sticky-top`, set with `vars`. The tree is paint only (`list`, `list.item`, `list.media`, `list.muted`,
+`list.action`, `list.label`); the spacing is the parts' own default props, which a prop on the part beats.
+
+Three client-only entries build on it. `SwipeItem` (`components/swipeItem`) is a `List.Item` whose row slides aside:
+`startActions`/`endActions` of `SwipeItem.Action` (`variant` `accent`/`warning`/`danger`, `icon`), `fullSwipe` to
+perform the outermost by swiping across, `open`/`onOpenChange`; the actions are tab stops and focus opens their tray.
+`SortableList` (`components/sortableList`) reorders `SortableList.Item`s (`value`, `label`) by a `SortableList.Handle`:
+the app owns the order, `onOrderChange(order, { reason, value, from, to })` fires on the drop and on each keyboard step
+(Enter/Space grabs, arrows move, Escape puts back), `onOrderCommit` once it settles. `VirtualList`
+(`components/virtualList`) windows `items` through a `children(item, index)` that returns one `<li>`, measuring each
+item by `itemKey`; `estimateSize`, `overscan`, `onRangeChange`, `scrollerRef`. `List.Chevron` is the chevron as a part.
+
 ## Slider and Progress
 
 ```tsx
@@ -229,12 +275,12 @@ import DataGrid from '@box-kite/react/components/dataGrid';
 
 **DataGridProps**: `data`, `def`, `component` (default `'datagrid'`), `loading`, `filters` (predicate[]), `page`/`onPageChange`, `onSortChange`, `onServerStateChange` (`{ page, pageSize, sortColumn, sortDirection, columnFilters, globalFilterValue }`), `onSelectionChange` (`{ action, selectedRowKeys, affectedRowKeys, isAllSelected }`), `expandedRowKeys`/`onExpandedRowKeysChange`, `globalFilterValue`/`onGlobalFilterChange`, `columnFilters`/`onColumnFiltersChange`, `onCellEditsChange` (`edit`/`paste`/`clear`), `onRangeChange` (`(range, { reason })` with `select`/`extend`/`clear`; `range` is `{ startRow, endRow, columns, values() }` or `undefined`), `onPaste` (`{ range, applied, rejected, skipped }`, once per Ctrl+V).
 
-**GridDefinition**: `columns` (required), `rowKey`, `rowHeight` (px, default 48), `visibleRowsCount` (number/`'all'`), `showRowNumber` (bool/`{ pinned?, width? }`), `rowSelection` (bool/`{ pinned? }` — the header checkbox acts on the rows the filters leave on screen, and the bottom bar counts selected rows the filters hide, with Show selected and Clear selection), `rowDetail` (`{ content, height?, expandOnRowClick?, pinned?, expandColumnWidth?, expandColumnHeader? }`), `pagination` (`{ totalCount, pageSize? }`), `topBar`/`bottomBar`, `title`/`topBarContent`, `globalFilter`, `globalFilterKeys`, `sortable`/`resizable` (default true), `contextMenu` (bool/`{ sort?, pin?, group? }`, default true), `resizerStyle` (`'visible'`/`'hover'`/`'hidden'`), `headerHover` (`'static'` — an inset pill per sortable cell — or `'sliding'`, one pill that flows between cells), `localeText` (any subset of `DataGridLocaleText` — every word the grid writes, for a translation; values with a number or a name in them are functions, and `DATA_GRID_LOCALE_TEXT` is the English to spread over), `noDataComponent`, `editable`/`onCellEdit`, `tabNavigation` (`'none'` default — APG's single tab stop — or `'cells'`, the spreadsheet reading), `rangeSelection` (a drag or Shift+arrow marks a block of cells; `Ctrl+C` copies it as TSV and `Ctrl+V` fills it back through `onCellEdit`, one judgement per cell — both need no opt-in for the current cell alone).
+**GridDefinition**: `columns` (required), `rowKey`, `rowHeight` (px, default 48), `visibleRowsCount` (number/`'all'`), `showRowNumber` (bool/`{ pinned?, width? }`), `rowSelection` (bool/`{ pinned? }` — the header checkbox acts on the rows the filters leave on screen, and the bottom bar counts selected rows the filters hide, with Show selected and Clear selection), `rowDetail` (`{ content, height?, expandOnRowClick?, pinned?, expandColumnWidth?, expandColumnHeader? }`), `pagination` (`{ totalCount, pageSize? }`), `topBar`/`bottomBar`, `title`/`topBarContent`, `globalFilter`, `globalFilterKeys`, `sortable`/`resizable` (default true), `contextMenu` (bool/`{ sort?, pin?, group? }`, default true), `resizerStyle` (`'visible'`/`'hover'`/`'hidden'`), `headerHover` (`'static'` — an inset pill per sortable cell — or `'sliding'`, one pill that flows between cells), `localeText` (any subset of `DataGridLocaleText` — every word the grid writes, for a translation; values with a number or a name in them are functions, and `DATA_GRID_LOCALE_TEXT` is the English to spread over), `noDataComponent`, `editable`/`onCellEdit`, `tabNavigation` (`'none'` default — APG's single tab stop — or `'cells'`, the spreadsheet reading), `layout` (`'auto'` default — a list item per row once the grid's own width is under `list.breakpoint`, 576px; `'table'`/`'list'` choose for good — rule 51), `list` (`{ breakpoint?, fields?, batchSize?, recordView? }`), `rangeSelection` (a drag or Shift+arrow marks a block of cells; `Ctrl+C` copies it as TSV and `Ctrl+V` fills it back through `onCellEdit`, one judgement per cell — both need no opt-in for the current cell alone).
 
-**ColumnType**: `key`, `header`, `width` (px, default 200), `align` (`'start'`/`'end'`/`'center'`, or the physical `'left'`/`'right'`), `pin` (`'START'`/`'END'` — an edge of the **inline axis**, so a pinned column holds under either `dir`; `'LEFT'`/`'RIGHT'` are the older spelling of the same two), `columns` (grouped headers), `Cell` (`({ cell }) => ReactNode`), `sortable`/`resizable` (override grid), `flexible`, `filterable` (`true`=text, `{ type: 'number' }`, `{ type: 'multiselect' }`), `contextMenu` (override grid).
+**ColumnType**: `key`, `header`, `width` (px, default 200), `align` (`'start'`/`'end'`/`'center'`, or the physical `'left'`/`'right'`), `pin` (`'START'`/`'END'` — an edge of the **inline axis**, so a pinned column holds under either `dir`; `'LEFT'`/`'RIGHT'` are the older spelling of the same two), `columns` (grouped headers), `Cell` (`({ cell }) => ReactNode`), `sortable`/`resizable` (override grid), `flexible`, `filterable` (`true`=text, `{ type: 'number' }`, `{ type: 'multiselect' }`), `contextMenu` (override grid), `list` (`'title'`/`'kicker'`/`'subtitle'`/`'end'`/`'field'`/`'detail'`/`'hidden'` — where it goes in a list item).
 
 **Server-side**: `def={{ pagination: { totalCount }, bottomBar: true }}` + `page={page}` + `onServerStateChange={fetchData}`.
 
 **Accessibility (A7, A10)**: the APG grid pattern, over a virtualized body — supplied whole, so add no roles and no `tabIndex`. The scrolling element is `role="grid"` (header and body are `rowgroup`s, rows `role="row"`, cells `role="gridcell"`/`columnheader`, scroll spacers `presentation`). `aria-rowcount`/`-colcount` describe the _whole_ grid and `aria-rowindex`/`-colindex` place each rendered cell in it, header rows first. Also `aria-sort` on sortable headers, `aria-selected` on rows only with `rowSelection`, `aria-busy` while `loading`, `aria-expanded` on group and expanded rows, and a live region announcing the selection count. Keyboard: one cell in the tab order; arrows move it, Home/End along the row, Ctrl+Home/End to the corners (scrolling to unrendered rows), PageUp/Down by a screenful, Enter/Space sorts a header or steps into the cell’s control, F2 always steps in, Escape steps back out. Down/Up keep the _column_ rather than the cell ordinal, so they land under where they started even through a grouped header. The column resizer is APG's window splitter — `role="separator"` with `aria-valuenow`/`-valuemin`/`-valuemax` in pixels; Tab or F2 reaches it, the arrows move it 16px, Home/End go to the narrowest the grid allows and to the grid's own width. Space on any cell selects its row, and on the header cell the select-all box sits in it toggles every row the filters leave on screen. Every cell carries the **current-cell mark**, which survives the grid losing focus so `Ctrl+C` has something to act on; with `def.rangeSelection` the cells of a marked block carry `aria-selected` and the grid is `aria-multiselectable`, while a lone current cell carries neither. Every control the grid draws names itself after what it acts on ("Select row 4", "Column options for Age"); the column menu is the APG menu button. **Give it `def.title`** — a grid is not named by its rows. Every widget a cell holds is out of the page tab sequence, so the grid is one tab stop: Enter or F2 steps in, Tab walks the widgets **within that cell** and wraps, and Escape is the way out.
 
-**Style tree**: `datagrid` > `content`, `topBar` > (`globalFilter` > `stats`, `columnGroups` > `icon`|`separator`|`item` > `icon`, `columnVisibility` > `badge`|`panel`|`search`|`searchIcon`|`searchInput`|`toolbar`|`count`|`action`|`list`|`section`|`group`|`item`|`empty`), `filter` > `cell` > `input`, `header` > `cell` > (`contextMenu` > `icon`|`tooltip` > `item` > `icon`|`separator`, `resizer`), `body` > (`cell` > `text`|`rowDetail`, `row`, `groupRow` > `expandButton`, `detailRow`, `empty`), `emptyColumns`, `bottomBar` > (`info`, `clearFilters`, `pagination` > `button`|`info`).
+**Style tree**: `datagrid` > `content`, `topBar` > (`globalFilter` > `stats`, `columnGroups` > `icon`|`separator`|`item` > `icon`, `columnVisibility` > `badge`|`panel`|`search`|`searchIcon`|`searchInput`|`toolbar`|`count`|`action`|`list`|`section`|`group`|`item`|`empty`), `filter` > `cell` > `input`, `header` > `cell` > (`contextMenu` > `icon`|`tooltip` > `item` > `icon`|`separator`, `resizer`), `body` > (`cell` > `text`|`rowDetail`, `row`, `groupRow` > `expandButton`, `detailRow`, `empty`), `emptyColumns`, `list` > (`toolbar`, `toggle`, `detail`, `button`, `selectionBar`, `sheet`) — its rows are `List.Item`s, styled by the `list` tree, `bottomBar` > (`info`, `clearFilters`, `pagination` > `button`|`info`).

package/.cursor/rules/box-kite.mdc

@@ -92,4 +92,12 @@ This library is not in your training data: it was renamed at 1.0.0 (September 20
 
 48. **In development the console is part of the answer: read it.** Three mistakes write nothing, or the wrong thing, and say so in one `[box-kite]` warning that names what rendered and the line to write instead. **A value a prop does not take** — `bgColor="bleu-500"` → `wrote no CSS … Did you mean "blue-500"?`, `opacity={50}` → `It takes one of 0, 0.1, …`. **An HTML attribute at the top level** — `href`, `onClick`, `data-*`, `aria-*` → `write props={{ href: ... }}`. **A number in a unit it almost certainly did not mean**, which is valid CSS and so the one mistake nothing else catches: `fontSize={4}` is 4px text (`For 16px write fontSize={16}`), `lineHeight={1.5}` a 1.5px line, `transitionDuration={0.3}` 0.3ms, `brightness={1.1}` 1.1%. Each prints once per value, in any environment whose `NODE_ENV` is not `production` — a test run included, which is the cheapest place to see them — and never in a production build, where a rejected value is still dropped with nothing said. `Box.configure({ warnings: false })` turns them off; `check_styles` in `@box-kite/mcp` gives the same three verdicts before anything renders.
 
+49. **A design that stops at a subtree is `Box.createComponents()`, not `Box.components()`.** `Box.components()` is one registry for the whole app: a second call merges into the first, so two designs cannot share a page through it. `const aurora = Box.createComponents({ button: { styles: { borderRadius: 999 } } })` takes the same shape and registers nothing, and `<Box.Components value={aurora}>` — or `<Box.Theme use="local" components={aurora}>`, a design in light and dark in one wrapper — applies it to every Box inside, pre-built components included. `base` is what it merges over: `'global'` (default, the app's own `Box.components()`), `'builtin'` (ignores them) or another registry. Props still beat the design. It is identified by its content, so an inline one costs no cache, but declare it at module scope. The provider renders no element and a Server Component cannot read it. Two designs that both name `button` type as `interface ComponentsTypes extends MergeComponentsAndVariants<[typeof aurora, typeof harbor]> {}`.
+
+50. **A list of things to read and pick from is `<List>`, and one action covers each item.** `<List><List.Item chevron><List.Media variant="avatar">AL</List.Media><List.Content><List.Row><List.Title lines={1}><List.Action props={{ href: '/inbox/42' }}>Ada Lovelace</List.Action></List.Title><List.Meta>9:41</List.Meta></List.Row><List.Description lines={2}>…</List.Description></List.Content></List.Item></List>` (`components/list`). **An item is a flex row of three slots** — `List.Media` leading (`variant` `icon`/`avatar`/`image`), `List.Content` taking the room, `List.End` trailing (a value over its label, aligned to the end) — and the content is a column of `List.Row`s, each its parts side by side with the last pushed to the end: a main row (the title and its time) and a `secondary` one under it (smaller, muted). `wrap` on a row or an item lets the parts wrap instead of squeezing; `List.Overline`/`List.Title`/`List.Description` take `lines={1|2|3}` (an ellipsis, then a clamp); `List.Meta` is a small value that never wraps; `List.Fields` + `List.Field label` is a `<dl>` of labelled values; `List.Group label level sticky` is a section with a nested list of its own. **`List.Action` goes in the title and its `::after` covers the item**, so the whole row presses while the name a reader hears is the title alone — an `href` in `props` makes it an `<a>`, an `htmlFor` a `<label>` (a press anywhere ticks that checkbox), neither a `<button>` with a top-level `onClick`; a control of the item's own (a switch, a menu, that checkbox) goes in `List.Actions`, which sits above it. **Four things to know.** It renders on a server — no hook, no context — so the list's look reaches its items as **custom properties**: `variant="plain"|"card"|"separated"` on `List`, and `vars={{ 'list-divider': …, 'list-divider-inset': '4.5rem', 'list-item-radius': …, 'list-sticky-top': '4rem' }}` to tune it. The style tree is **paint only** (`list`, `list.item`, `list.media`, `list.muted`, `list.action`, `list.label`), the hairlines and tints mixed from `currentColor`; the spacing is each part's default props, so `<List.Item py={1}>` wins and `Box.components` cannot move it. Hover, pressed, `aria-current` and disabled are read off the action with `:has()` — no prop — and `selected` on an item is a tint only, the state a reader hears belonging on the control. And it is a `<ul role="list">` (Safari drops the semantics otherwise; `tag="ol"` for an ordered one), **not a composite widget**: every action is a tab stop and the arrows stay the page's — arrow-key selection among options is a listbox, `Combobox` or `Select`.
+
+51. **On a phone a DataGrid is a list, and a column says where it goes in an item.** Below `def.list.breakpoint` (576px) of **the grid's own width** — not the viewport's — `layout: 'auto'` (the default) draws each row as a list item: `list: 'title'` is its name and the button that opens it, `'kicker'` a small line above, `'subtitle'` a line under, `'end'` the one value opposite the title with its column's name under it, `'field'` a labelled value, `'detail'` the record view only, `'hidden'` nowhere. Left unset, the first column is the title, the first end-aligned one the end, the next four fields (`def.list.fields`) and the rest detail. A press opens the **record view** — every column of one row in a bottom sheet with a pager (buttons, Left/Right, a swipe) that follows the list's sort and filters, and an **Edit** button on each editable column through the same `onCellEdit`. Sort and filters are bottom sheets behind two pills, the filters in force are removable chips, **Select** is a mode (a press ticks instead of opening, and a bar pinned to the bottom counts the selection), and the list grows twenty a **Show more** — a button, so the totals and the page below stay reachable — or pages when the host paginates. **Four things to know.** It is a `<List>` (rule 50) — each row a `List.Item` whose title is the `List.Action` — not a restyled `role="grid"`, so the `list` tree styles its rows. It is a chunk of its own, loaded the first time a grid is narrow, and the grid draws its table until it arrives — in a test, `await loadListLayout()` first. Unmeasured is a table, so a server prerenders the table and `layout: 'list'` is how to say otherwise. And the selection bar sticks to the viewport, so no ancestor may be `overflow: hidden`/`auto` — `css={{ overflow: 'clip' }}` clips without being a scroll container. `layout: 'table'` keeps the table at every width.
+
+52. **Swiping, reordering and windowing a list are three client entries on top of `List`.** `<SwipeItem endActions={<SwipeItem.Action variant="danger" onClick={remove}>Delete</SwipeItem.Action>} fullSwipe>` (`components/swipeItem`) is a `List.Item` — same parts, `size`, `chevron`, `selected` — whose row slides to open a tray; the first action of each tray is the outermost, and `fullSwipe` performs it by clicking it, so its `onClick` is where the command lives. The actions are tab stops and focus opens their tray, but a swipe is a path gesture: put the same commands where a press reaches too. `<SortableList onOrderChange={(order) => setIds(order)}>` (`components/sortableList`) with `<SortableList.Item value={id} label={name}>` and a `<SortableList.Handle />` in each: **the app owns the order** and renders it, `onOrderChange` fires once per drop and per keyboard step, `onOrderCommit` when it settles; the keyboard grabs (Enter/Space, arrows, Escape puts back), and a press on a handle then a press on another item drops it there. `<VirtualList items={rows} itemKey={(row) => row.id}>{(row) => <List.Item>…</List.Item>}</VirtualList>` (`components/virtualList`) renders a window, measuring each item by key; the scroller is the nearest scrolling ancestor or the page, `scrollerRef` when that is wrong, and `onRangeChange` fetches the next page. **Three things to know.** The children function returns exactly one `<li>` per item and nothing around it, since the list measures its children. A windowed list has no `List.Group`s and find-in-page cannot see what is not rendered. And a `SwipeItem` windows like any item, but a `SortableList` holds its whole list: reorder a list short enough to render, window one too long to.
+
 Full reference: `node_modules/@box-kite/react/docs/props.md` in the project, or https://www.box-kite.dev/props.md — every prop, the CSS it writes and one measured example.

package/AGENTS.md

@@ -124,4 +124,12 @@ Every value there is a prop, and every prop value becomes one class the engine i
 
 48. **In development the console is part of the answer: read it.** Three mistakes write nothing, or the wrong thing, and say so in one `[box-kite]` warning that names what rendered and the line to write instead. **A value a prop does not take** — `bgColor="bleu-500"` → `wrote no CSS … Did you mean "blue-500"?`, `opacity={50}` → `It takes one of 0, 0.1, …`. **An HTML attribute at the top level** — `href`, `onClick`, `data-*`, `aria-*` → `write props={{ href: ... }}`. **A number in a unit it almost certainly did not mean**, which is valid CSS and so the one mistake nothing else catches: `fontSize={4}` is 4px text (`For 16px write fontSize={16}`), `lineHeight={1.5}` a 1.5px line, `transitionDuration={0.3}` 0.3ms, `brightness={1.1}` 1.1%. Each prints once per value, in any environment whose `NODE_ENV` is not `production` — a test run included, which is the cheapest place to see them — and never in a production build, where a rejected value is still dropped with nothing said. `Box.configure({ warnings: false })` turns them off; `check_styles` in `@box-kite/mcp` gives the same three verdicts before anything renders.
 
+49. **A design that stops at a subtree is `Box.createComponents()`, not `Box.components()`.** `Box.components()` is one registry for the whole app: a second call merges into the first, so two designs cannot share a page through it. `const aurora = Box.createComponents({ button: { styles: { borderRadius: 999 } } })` takes the same shape and registers nothing, and `<Box.Components value={aurora}>` — or `<Box.Theme use="local" components={aurora}>`, a design in light and dark in one wrapper — applies it to every Box inside, pre-built components included. `base` is what it merges over: `'global'` (default, the app's own `Box.components()`), `'builtin'` (ignores them) or another registry. Props still beat the design. It is identified by its content, so an inline one costs no cache, but declare it at module scope. The provider renders no element and a Server Component cannot read it. Two designs that both name `button` type as `interface ComponentsTypes extends MergeComponentsAndVariants<[typeof aurora, typeof harbor]> {}`.
+
+50. **A list of things to read and pick from is `<List>`, and one action covers each item.** `<List><List.Item chevron><List.Media variant="avatar">AL</List.Media><List.Content><List.Row><List.Title lines={1}><List.Action props={{ href: '/inbox/42' }}>Ada Lovelace</List.Action></List.Title><List.Meta>9:41</List.Meta></List.Row><List.Description lines={2}>…</List.Description></List.Content></List.Item></List>` (`components/list`). **An item is a flex row of three slots** — `List.Media` leading (`variant` `icon`/`avatar`/`image`), `List.Content` taking the room, `List.End` trailing (a value over its label, aligned to the end) — and the content is a column of `List.Row`s, each its parts side by side with the last pushed to the end: a main row (the title and its time) and a `secondary` one under it (smaller, muted). `wrap` on a row or an item lets the parts wrap instead of squeezing; `List.Overline`/`List.Title`/`List.Description` take `lines={1|2|3}` (an ellipsis, then a clamp); `List.Meta` is a small value that never wraps; `List.Fields` + `List.Field label` is a `<dl>` of labelled values; `List.Group label level sticky` is a section with a nested list of its own. **`List.Action` goes in the title and its `::after` covers the item**, so the whole row presses while the name a reader hears is the title alone — an `href` in `props` makes it an `<a>`, an `htmlFor` a `<label>` (a press anywhere ticks that checkbox), neither a `<button>` with a top-level `onClick`; a control of the item's own (a switch, a menu, that checkbox) goes in `List.Actions`, which sits above it. **Four things to know.** It renders on a server — no hook, no context — so the list's look reaches its items as **custom properties**: `variant="plain"|"card"|"separated"` on `List`, and `vars={{ 'list-divider': …, 'list-divider-inset': '4.5rem', 'list-item-radius': …, 'list-sticky-top': '4rem' }}` to tune it. The style tree is **paint only** (`list`, `list.item`, `list.media`, `list.muted`, `list.action`, `list.label`), the hairlines and tints mixed from `currentColor`; the spacing is each part's default props, so `<List.Item py={1}>` wins and `Box.components` cannot move it. Hover, pressed, `aria-current` and disabled are read off the action with `:has()` — no prop — and `selected` on an item is a tint only, the state a reader hears belonging on the control. And it is a `<ul role="list">` (Safari drops the semantics otherwise; `tag="ol"` for an ordered one), **not a composite widget**: every action is a tab stop and the arrows stay the page's — arrow-key selection among options is a listbox, `Combobox` or `Select`.
+
+51. **On a phone a DataGrid is a list, and a column says where it goes in an item.** Below `def.list.breakpoint` (576px) of **the grid's own width** — not the viewport's — `layout: 'auto'` (the default) draws each row as a list item: `list: 'title'` is its name and the button that opens it, `'kicker'` a small line above, `'subtitle'` a line under, `'end'` the one value opposite the title with its column's name under it, `'field'` a labelled value, `'detail'` the record view only, `'hidden'` nowhere. Left unset, the first column is the title, the first end-aligned one the end, the next four fields (`def.list.fields`) and the rest detail. A press opens the **record view** — every column of one row in a bottom sheet with a pager (buttons, Left/Right, a swipe) that follows the list's sort and filters, and an **Edit** button on each editable column through the same `onCellEdit`. Sort and filters are bottom sheets behind two pills, the filters in force are removable chips, **Select** is a mode (a press ticks instead of opening, and a bar pinned to the bottom counts the selection), and the list grows twenty a **Show more** — a button, so the totals and the page below stay reachable — or pages when the host paginates. **Four things to know.** It is a `<List>` (rule 50) — each row a `List.Item` whose title is the `List.Action` — not a restyled `role="grid"`, so the `list` tree styles its rows. It is a chunk of its own, loaded the first time a grid is narrow, and the grid draws its table until it arrives — in a test, `await loadListLayout()` first. Unmeasured is a table, so a server prerenders the table and `layout: 'list'` is how to say otherwise. And the selection bar sticks to the viewport, so no ancestor may be `overflow: hidden`/`auto` — `css={{ overflow: 'clip' }}` clips without being a scroll container. `layout: 'table'` keeps the table at every width.
+
+52. **Swiping, reordering and windowing a list are three client entries on top of `List`.** `<SwipeItem endActions={<SwipeItem.Action variant="danger" onClick={remove}>Delete</SwipeItem.Action>} fullSwipe>` (`components/swipeItem`) is a `List.Item` — same parts, `size`, `chevron`, `selected` — whose row slides to open a tray; the first action of each tray is the outermost, and `fullSwipe` performs it by clicking it, so its `onClick` is where the command lives. The actions are tab stops and focus opens their tray, but a swipe is a path gesture: put the same commands where a press reaches too. `<SortableList onOrderChange={(order) => setIds(order)}>` (`components/sortableList`) with `<SortableList.Item value={id} label={name}>` and a `<SortableList.Handle />` in each: **the app owns the order** and renders it, `onOrderChange` fires once per drop and per keyboard step, `onOrderCommit` when it settles; the keyboard grabs (Enter/Space, arrows, Escape puts back), and a press on a handle then a press on another item drops it there. `<VirtualList items={rows} itemKey={(row) => row.id}>{(row) => <List.Item>…</List.Item>}</VirtualList>` (`components/virtualList`) renders a window, measuring each item by key; the scroller is the nearest scrolling ancestor or the page, `scrollerRef` when that is wrong, and `onRangeChange` fetches the next page. **Three things to know.** The children function returns exactly one `<li>` per item and nothing around it, since the list measures its children. A windowed list has no `List.Group`s and find-in-page cannot see what is not rendered. And a `SwipeItem` windows like any item, but a `SortableList` holds its whole list: reorder a list short enough to render, window one too long to.
+
 Full reference: `docs/props.md` and `BOX_KITE_AI_CONTEXT.md`, in this package.

package/BOX_AI_CONTEXT.md

@@ -1064,6 +1064,36 @@ Box.components({
 });
 ```
 
+`extends` is resolved over everything registered so far, chains included, so overriding the base later still reaches the component built on it.
+
+**A prop on the element wins in every theme.** `<Box component="card" bgColor="red-500">` replaces the card's `bgColor` and also its `theme.dark.bgColor` (at the same level: `hover.bgColor` replaces the themed hover). Everything else the card styles for dark stays. To keep a different dark value, write it: `theme={{ dark: { bgColor: 'red-900' } }}`.
+
+### Box.createComponents() — A Design for One Subtree
+
+`Box.components()` styles the whole app: every call merges into one registry, so two designs cannot share a page through it. `Box.createComponents()` takes the same shape and registers nothing. It returns a design, and `<Box.Components value>`, or `components` on `Box.Theme`, applies it to everything inside.
+
+```tsx
+const aurora = Box.createComponents({ button: { styles: { borderRadius: 999 } }, card: { styles: { p: 6 } } });
+const harbor = Box.createComponents({ button: { styles: { borderRadius: 0 } } }, { base: 'builtin' });
+
+<Box.Theme use="local" components={aurora}>   {/* light/dark + design in one wrapper */}
+  <Button>Pill</Button>
+</Box.Theme>
+<Box.Components value={harbor}>
+  <Button>Square</Button>
+</Box.Components>
+```
+
+- **`base`** is what the design is merged over:
+  - `'global'` (the default) is the app's own `Box.components()`, followed as it changes.
+  - `'builtin'` ignores the app's registrations.
+  - Another registry chains onto that design.
+- **Props still beat the design**, the way they beat `Box.components()`.
+- **A design is identified by its content**, so building one inline does not grow the cache. Module scope still reads best.
+- **`<Box.Components>` renders no element.** `value={undefined}` hands a subtree back to the app's design.
+- **A Server Component cannot read the provider.** A client component under it can.
+- **Types for two designs that both name a component**: `interface ComponentsTypes extends MergeComponentsAndVariants<[typeof aurora, typeof harbor]> {}` (from `@box-kite/core/types`). Extending two `ExtractComponentsAndVariants` that disagree on `button` is an interface conflict.
+
 ---
 
 ## Extension System
@@ -1891,6 +1921,170 @@ on something at the panel's edge needs, since the clip is permanent.
 
 ---
 
+## List (`components/list`)
+
+```tsx
+import List from '@box-kite/react/components/list';
+
+<List>
+  {people.map((person) => (
+    <List.Item key={person.id} chevron>
+      <List.Media variant="avatar">{person.initials}</List.Media>
+      <List.Content>
+        <List.Row>
+          <List.Title lines={1}>
+            <List.Action props={{ href: `/people/${person.id}` }}>{person.name}</List.Action>
+          </List.Title>
+          <List.Meta>{person.lastSeen}</List.Meta>
+        </List.Row>
+        <List.Description lines={2}>{person.bio}</List.Description>
+      </List.Content>
+    </List.Item>
+  ))}
+</List>;
+```
+
+A list of things to read and pick from — messages, orders, people, settings. **An item is a flex row of
+three slots**, and the content is a column of rows:
+
+| Part               | Element                        | What it is                                                                                                     |
+| ------------------ | ------------------------------ | -------------------------------------------------------------------------------------------------------------- |
+| `List`             | `<ul role="list">`             | `variant`: dividers by default, `plain`, `card` (one framed block), `separated` (a frame per item); `tag="ol"` |
+| `List.Item`        | `<li>`                         | A flex row. `size` `sm`/`md`/`lg` (44/56/72px), `wrap`, `selected` (a tint), `chevron`                         |
+| `List.Media`       | `<div>`                        | Leading: `variant` `icon` (a tinted square), `avatar` (a circle that clips), `image` (a thumbnail)             |
+| `List.Content`     | `<div>`                        | The middle, taking the room; a column                                                                          |
+| `List.Row`         | `<div>`                        | Parts side by side, the last at the end. `secondary` (smaller, muted), `wrap`                                  |
+| `List.Overline`    | `<span>`                       | A small line above the title. `lines`                                                                          |
+| `List.Title`       | `<span>`                       | The name, holding the `List.Action`. `lines` `1` (ellipsis), `2`/`3` (clamp); unset, it wraps                  |
+| `List.Description` | `<span>`                       | Muted supporting text. `lines`                                                                                 |
+| `List.Meta`        | `<span>`                       | A small value that never wraps: a time, a count                                                                |
+| `List.End`         | `<div>`                        | Trailing: a value over its label, aligned to the end in tabular figures                                        |
+| `List.Actions`     | `<div>`                        | Controls of the item's own, lifted above the action                                                            |
+| `List.Action`      | `<a>` / `<label>` / `<button>` | The primary action, covering the item: `href` → link, `htmlFor` → label, otherwise a button                    |
+| `List.Fields`      | `<dl>`                         | Labelled values, as many to a line as fit at 8rem                                                              |
+| `List.Field`       | `<div>` + `<dt>` + `<dd>`      | `label` and the value                                                                                          |
+| `List.Group`       | `<li>` + `<ul>`                | A section: `label`, `level` (makes the label a heading), `sticky`                                              |
+| `List.Chevron`     | `<span aria-hidden>`           | The chevron `chevron` draws, for an item something else renders                                                |
+
+**One action covers the item.** `List.Action`'s `::after` stretches over the whole `<li>`, so a press
+anywhere on the item is a press on it and the focus ring draws round the item — while its accessible
+name is the title alone, not every value in the row. A pick-list is a label: put the checkbox in
+`List.Actions` and give the action its `htmlFor`.
+
+```tsx
+<List.Item selected={picked}>
+  <List.Actions>
+    <Checkbox id="pick-ada" checked={picked} onChange={toggle} />
+  </List.Actions>
+  <List.Title>
+    <List.Action props={{ htmlFor: 'pick-ada' }}>Ada Lovelace</List.Action>
+  </List.Title>
+</List.Item>
+```
+
+Hover, pressed, current (`aria-current` on the action) and disabled are read off the action with
+`:has()`, so an item with no action is plain text and needs no prop to say so.
+
+**It renders on a server**: no hook, no context, no effect. That is why the list's look reaches its
+items as custom properties rather than through React — and they are yours to set with `vars`:
+
+| Variable               | Default               | What it is                                                    |
+| ---------------------- | --------------------- | ------------------------------------------------------------- |
+| `--list-divider`       | `currentColor` at 12% | The line between items; `plain` and `separated` make it clear |
+| `--list-divider-inset` | `0px`                 | Where the line starts — `4.5rem` lines it up with the text    |
+| `--list-item-frame`    | `none`                | The border round each item, which `separated` sets            |
+| `--list-item-radius`   | `0`                   | Each item's corners, which its tint follows                   |
+| `--list-sticky-top`    | `0`                   | How far down a sticky group label stops — an app's header     |
+
+**The style tree is paint only** — `list` (the three variants), `list.item` (the divider colour, the
+states, `selected`), `list.media`, `list.muted`, `list.action` (the focus ring) and `list.label` —
+because every engine entry carries it. The spacing is each part's default props, so a prop on the part
+beats it (`<List.Item py={1}>`) and `Box.components` cannot move it. The hairlines and tints are mixed
+from `currentColor`, so they follow any theme with no rule for it.
+
+It is a `<ul role="list">` — the role spelled out because Safari stops reporting a list whose items have
+lost their markers — and **not a composite widget**: each action is a tab stop, Enter follows or presses
+it, and the arrow keys stay the page's. Arrow-key selection among options is a listbox: `Combobox` or
+`Select`.
+
+### Swipe actions, reorder and a long list
+
+Three client-only entries on top of `List`, so `List` itself stays server-safe. Each item they draw is a
+`List.Item` in everything but name — same parts, same sizes, same `list.item` paint.
+
+```tsx
+import SwipeItem from '@box-kite/react/components/swipeItem';
+import SortableList from '@box-kite/react/components/sortableList';
+import VirtualList from '@box-kite/react/components/virtualList';
+
+<SwipeItem
+  fullSwipe
+  startActions={
+    <SwipeItem.Action variant="accent" onClick={pin}>
+      Pin
+    </SwipeItem.Action>
+  }
+  endActions={
+    <SwipeItem.Action variant="danger" onClick={remove}>
+      Delete
+    </SwipeItem.Action>
+  }
+>
+  <List.Content>…</List.Content>
+</SwipeItem>;
+
+<SortableList onOrderChange={(order) => setIds(order)} onOrderCommit={save}>
+  {ids.map((id) => (
+    <SortableList.Item key={id} value={id} label={names[id]}>
+      <List.Content>…</List.Content>
+      <SortableList.Handle />
+    </SortableList.Item>
+  ))}
+</SortableList>;
+
+<VirtualList items={messages} itemKey={(message) => message.id} onRangeChange={loadMore}>
+  {(message) => <List.Item>…</List.Item>}
+</VirtualList>;
+```
+
+| Component             | Props                                                                                                                                                                               |
+| --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `SwipeItem`           | `startActions`, `endActions` (the first of each is outermost), `fullSwipe`, `open`/`defaultOpen`/`onOpenChange`, and `List.Item`'s `size`/`wrap`/`selected`/`chevron`               |
+| `SwipeItem.Action`    | A `<button>`: `variant` `accent`/`warning`/`danger` (unset is neutral), `icon`, `onClick`, `closeOnSelect` (default `true`)                                                         |
+| `SortableList`        | Everything `List` takes, `onOrderChange(order, { reason, value, from, to })`, `onOrderCommit` (the drop — the one to save)                                                          |
+| `SortableList.Item`   | Everything `List.Item` takes, `value` (required, unique), `label` (what the handle and announcements call it), `disabled`                                                           |
+| `SortableList.Handle` | The `<button>` a drag starts from; six dots unless given children; named "Move" + the item's `label`                                                                                |
+| `VirtualList`         | Everything `List` takes, `items`, `itemKey`, `children` (a function returning one `<li>`), `estimateSize` (57), `overscan` (6), `initialCount` (20), `onRangeChange`, `scrollerRef` |
+
+**`SwipeItem`'s row slides and a tray opens in the space it leaves** — nothing is under the row, so it
+needs no background. Past half open opens, short of it closes, a flick goes the way it was going, and
+`fullSwipe` carried most of the way across performs the outermost action (it clicks it, so its `onClick`
+is the one place the command lives). A press on an open item closes it instead of following the action.
+The actions are real buttons in the tab order and focus reaching one opens its tray; Escape closes it.
+A swipe is a path gesture (WCAG 2.5.1), so put the same commands somewhere a press reaches too.
+
+**`SortableList`: the app owns the order.** During a drag nothing is reordered — the item follows the
+pointer, its neighbours step aside as inline translates — and `onOrderChange` fires once, on the drop,
+which then glides into place (the Web Animations API, from where it was drawn). The keyboard is a grab,
+DashboardGrid's model: Enter/Space picks up, ArrowUp/ArrowDown/Home/End move (reporting each step),
+Enter drops, Escape puts back. A press on a handle that does not drag also picks the item up, and a
+press on another item then drops it there — the single-pointer way WCAG 2.5.7 asks for. Render the
+items in the order you hold; a refused move is just not applied.
+
+**`VirtualList` measures each item it draws** and keeps the height by `itemKey`, so mixed heights work;
+an undrawn item counts as the mean of those drawn (`estimateSize` before any is), and the list holds its
+height while it scrolls, since a scrollbar drag loses a move whenever it changes. The scroller is the nearest ancestor that scrolls, else the
+page; `scrollerRef` overrides. Each item gets `aria-setsize`/`aria-posinset`, the item focus is in
+stays rendered, and an item above the screen that turns out taller than estimated scrolls the list by
+the difference so nothing on screen moves. Groups and sticky labels need the whole list and do not
+window; find-in-page cannot see an unrendered item.
+
+Styling: `swipeItem.row`/`swipeItem.tray` (`dragging` variants), `swipeItem.action` (the three colour
+variants, `armed`), `sortableList.handle` (`grabbed`), and on `list.item` the `lifted` (dragged),
+`grabbed` (keyboard) and `settling` variants. `List.Chevron` is the item's chevron as a part.
+
+---
+
 ## Slider & Progress
 
 ```tsx
@@ -2396,30 +2590,33 @@ named ones carry the reason.
 | `footer`                  | `boolean \| { label? }`               | `false`     | A pinned row of grand totals over every column with an `aggregate`. `label` replaces the default `Total`                                                                                                               |
 | `export`                  | `boolean \| ExportConfig`             | `false`     | Export buttons in the top bar: `{ csv?, xlsx?, fileName? }`. The writers load on the first press                                                                                                                       |
 | `tabNavigation`           | `'none' \| 'cells'`                   | `'none'`    | What Tab does. `'none'` is APG's single tab stop; `'cells'` is the spreadsheet reading                                                                                                                                 |
+| `layout`                  | `'auto' \| 'table' \| 'list'`         | `'auto'`    | A table, or a list once the grid's own width is under `list.breakpoint` (see "On a phone")                                                                                                                             |
+| `list`                    | `ListConfig`                          | —           | `{ breakpoint?, fields?, batchSize?, recordView? }` — the list layout's settings                                                                                                                                       |
 | `rangeSelection`          | `boolean`                             | `false`     | A drag or Shift+arrow marks a block of cells, and `Ctrl+C`/`Ctrl+V` copy and paste it as TSV (see below)                                                                                                               |
 
 ### ColumnType
 
-| Prop                     | Type                                                | Default   | Description                                                                                                                                     |
-| ------------------------ | --------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `key`                    | `Key`                                               | required  | Column identifier (maps to TRow property)                                                                                                       |
-| `header`                 | `string`                                            | —         | Header text                                                                                                                                     |
-| `width`                  | `number`                                            | `200`     | Base width in px                                                                                                                                |
-| `align`                  | `'start' \| 'end' \| 'center' \| 'left' \| 'right'` | `'left'`  | Cell alignment. `start`/`end` follow the reading order; `left`/`right` stay on the screen side they name                                        |
-| `pin`                    | `'START' \| 'END'` (also `'LEFT'`/`'RIGHT'`)        | —         | Pin to an edge of the **inline axis** (sticky on scroll), so it holds under either `dir`. `LEFT`/`RIGHT` are the older spelling of the same two |
-| `columns`                | `ColumnType[]`                                      | —         | Nested columns (grouped header)                                                                                                                 |
-| `Cell`                   | `({ cell }) => ReactNode`                           | —         | Custom renderer. `cell`: `{ value, row, column, grid }`. It redraws when its row changes or the grid does — not when another row is selected    |
-| `sortable` / `resizable` | `boolean`                                           | inherits  | Override grid-level setting                                                                                                                     |
-| `flexible`               | `boolean`                                           | `true`    | Participate in flex width distribution                                                                                                          |
-| `filterable`             | `boolean \| FilterConfig`                           | —         | `true` (text), `{ type: 'number', min?, max? }`, `{ type: 'multiselect', options? }`                                                            |
-| `contextMenu`            | `boolean \| ContextMenuConfig`                      | inherits  | Override grid-level context menu. `false` hides entirely. `{ sort?, pin?, group? }` controls sections                                           |
-| `aggregate`              | `AggregateName \| (values, rows) => value`          | —         | Total this column over each group row, and over the footer. See below                                                                           |
-| `AggregateCell`          | `({ cell }) => ReactNode`                           | —         | Renders the aggregate. `cell`: `{ value, column, rows, scope }`, `scope` being `'group'` or `'footer'`                                          |
-| `editable`               | `boolean \| (row) => boolean`                       | inherits  | Whether this column’s cells can be edited — every row, or the rows a predicate says                                                             |
-| `editor`                 | `CellEditorType \| CellEditorConfig`                | inferred  | `text`/`number`/`checkbox`/`select`. Without one it is read off the value in the cell                                                           |
-| `EditCell`               | `({ cell }) => ReactNode`                           | —         | An editor of your own, bound to `cell.draft` with `cell.commitEdit()`/`cell.cancelEdit()`                                                       |
-| `exportValue`            | `(row: TRow) => value`                              | the field | What this column writes to an exported file — an export runs no React, so a `Cell` renderer needs it                                            |
-| `exportFormat`           | `string`                                            | —         | The number format its cells wear in a workbook, `'#,##0.00'` or `'yyyy-mm-dd'`                                                                  |
+| Prop                     | Type                                                                            | Default   | Description                                                                                                                                     |
+| ------------------------ | ------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
+| `key`                    | `Key`                                                                           | required  | Column identifier (maps to TRow property)                                                                                                       |
+| `header`                 | `string`                                                                        | —         | Header text                                                                                                                                     |
+| `width`                  | `number`                                                                        | `200`     | Base width in px                                                                                                                                |
+| `align`                  | `'start' \| 'end' \| 'center' \| 'left' \| 'right'`                             | `'left'`  | Cell alignment. `start`/`end` follow the reading order; `left`/`right` stay on the screen side they name                                        |
+| `pin`                    | `'START' \| 'END'` (also `'LEFT'`/`'RIGHT'`)                                    | —         | Pin to an edge of the **inline axis** (sticky on scroll), so it holds under either `dir`. `LEFT`/`RIGHT` are the older spelling of the same two |
+| `columns`                | `ColumnType[]`                                                                  | —         | Nested columns (grouped header)                                                                                                                 |
+| `Cell`                   | `({ cell }) => ReactNode`                                                       | —         | Custom renderer. `cell`: `{ value, row, column, grid }`. It redraws when its row changes or the grid does — not when another row is selected    |
+| `sortable` / `resizable` | `boolean`                                                                       | inherits  | Override grid-level setting                                                                                                                     |
+| `flexible`               | `boolean`                                                                       | `true`    | Participate in flex width distribution                                                                                                          |
+| `filterable`             | `boolean \| FilterConfig`                                                       | —         | `true` (text), `{ type: 'number', min?, max? }`, `{ type: 'multiselect', options? }`                                                            |
+| `contextMenu`            | `boolean \| ContextMenuConfig`                                                  | inherits  | Override grid-level context menu. `false` hides entirely. `{ sort?, pin?, group? }` controls sections                                           |
+| `aggregate`              | `AggregateName \| (values, rows) => value`                                      | —         | Total this column over each group row, and over the footer. See below                                                                           |
+| `AggregateCell`          | `({ cell }) => ReactNode`                                                       | —         | Renders the aggregate. `cell`: `{ value, column, rows, scope }`, `scope` being `'group'` or `'footer'`                                          |
+| `editable`               | `boolean \| (row) => boolean`                                                   | inherits  | Whether this column’s cells can be edited — every row, or the rows a predicate says                                                             |
+| `editor`                 | `CellEditorType \| CellEditorConfig`                                            | inferred  | `text`/`number`/`checkbox`/`select`. Without one it is read off the value in the cell                                                           |
+| `EditCell`               | `({ cell }) => ReactNode`                                                       | —         | An editor of your own, bound to `cell.draft` with `cell.commitEdit()`/`cell.cancelEdit()`                                                       |
+| `exportValue`            | `(row: TRow) => value`                                                          | the field | What this column writes to an exported file — an export runs no React, so a `Cell` renderer needs it                                            |
+| `list`                   | `'title' \| 'kicker' \| 'subtitle' \| 'end' \| 'field' \| 'detail' \| 'hidden'` | inferred  | Where the column goes in a list item, on a phone                                                                                                |
+| `exportFormat`           | `string`                                                                        | —         | The number format its cells wear in a workbook, `'#,##0.00'` or `'yyyy-mm-dd'`                                                                  |
 
 ### Aggregation
 
@@ -2715,6 +2912,65 @@ only gives it a bigger target.
   landed, so `range.values()` reads what the grid now shows. Everything it accepted lands in the same
   stream a typed value does: `onCellEditsChange(edits, { reason: 'paste' })`.
 
+### On a phone: the list layout
+
+Below `def.list.breakpoint` (576px, 36rem) of **the grid's own width** — measured with a `ResizeObserver`, not read off the viewport — the grid draws each row as a list item instead of a table row. Same rows, filters, sort, selection, grouping, tree and edits; a different drawing. `layout: 'table'` or `layout: 'list'` chooses one for good.
+
+```tsx
+<DataGrid
+  data={orders}
+  def={{
+    title: 'Orders',
+    globalFilter: true,
+    rowSelection: true,
+    columns: [
+      { key: 'customer', header: 'Customer', list: 'title' },
+      { key: 'id', header: 'Order', list: 'kicker' },
+      { key: 'total', header: 'Total', align: 'end', list: 'end', filterable: { type: 'number' } },
+      { key: 'status', header: 'Status', Cell: StatusBadge, filterable: { type: 'multiselect' } },
+      { key: 'date', header: 'Date' },
+      { key: 'notes', header: 'Notes', list: 'detail' },
+    ],
+  }}
+/>
+```
+
+| `column.list` | Where the column goes                                                                            |
+| ------------- | ------------------------------------------------------------------------------------------------ |
+| `'title'`     | The item's name, 16px semibold, and the button that opens the record view                        |
+| `'kicker'`    | A small muted line above the title — an id, a date                                               |
+| `'subtitle'`  | A line under the title; several are joined with `·`                                              |
+| `'end'`       | The one value opposite the title, with its column's name under it — a total, a status            |
+| `'field'`     | A labelled value in the two-column `<dl>` under the title                                        |
+| `'detail'`    | Only the record view                                                                             |
+| `'hidden'`    | Nowhere in the list layout                                                                       |
+| (unset)       | First column → title, first end-aligned → end, next `def.list.fields` (4) → field, rest → detail |
+
+| `def.list`   | Default | Description                                                                                        |
+| ------------ | ------- | -------------------------------------------------------------------------------------------------- |
+| `breakpoint` | `576`   | The grid's own width, in px, below which `layout: 'auto'` draws the list                           |
+| `fields`     | `4`     | How many unassigned columns become fields before the rest wait for the record view                 |
+| `batchSize`  | `20`    | How many items one **Show more** adds. A paginated grid draws its page and a compact pager instead |
+| `recordView` | `true`  | Whether pressing an item opens the record view                                                     |
+
+What the list does, in the order a reader meets it:
+
+- **Toolbar**: the title and row count, a full-width search (`globalFilter`), then pills — **Sort** and **Filters** open bottom sheets, **Select** (with `rowSelection`) turns selecting on. The filters in force sit under them as chips, each removable on its own.
+- **Sort sheet**: one radio group of the sortable columns and one of the direction, applied as they are picked.
+- **Filter sheet**: a section per filterable column — a full-width field, the phone's own operator picker for a number, chips for eight options or fewer and a searchable checklist past that. A filter applies as it is set, and the main button reads **Show N rows**.
+- **Item**: a press opens the record view; while selecting it ticks the row instead, a checkbox leads every item and a bar pinned to the bottom of the viewport counts the selection, with **Select all** and **Clear selection**. A tree row carries its chevron before the title, a `rowDetail` row a **Details** toggle, a group is a section header with its count and aggregates.
+- **Record view**: every column of one row in a bottom sheet, with a pager (`3 of 40`) that follows the list's own sort and filters — the arrow buttons, Left/Right, or a sideways swipe. An editable column has an **Edit** button that opens the column's editor through the same `def.onCellEdit`. Closing hands focus to the item of the row on screen.
+- **Footer**: the `def.footer` totals as a summary block, then **Show more** (`20 of 340`) — a button, never an endless scroll, so the totals and the page below stay reachable — or the compact pager when the host paginates.
+
+Four things to know:
+
+1. **It is a list, not a restyled grid.** A `<ul>` of `<li>`s, each value in a `<dl>`, `aria-posinset`/`aria-setsize` on each item; the grid's APG keyboard is the table's alone. Do not reach for `role="grid"` in a list item.
+2. **It is a chunk of its own.** The sheets and the record view load the first time a grid is narrow (and on import, on a phone-width screen); until then the grid goes on drawing its table. In a test, `await loadListLayout()` from `components/dataGrid/useListLayout` before rendering.
+3. **Unmeasured is a table.** A server render cannot know the width, so `layout: 'auto'` prerenders the table and a phone switches before its first paint after hydration. Force `layout: 'list'` where the server knows better.
+4. **The selection bar sticks to the viewport**, so no ancestor of the grid may be a scroll container (`overflow: hidden`/`auto`): `overflow: clip` clips the same corners without being one. The grid itself switches to `clip` in the list layout.
+
+Styling: every row and group header is a `List.Item` (see List), so the `list` tree styles them — the dividers, the hover and pressed tints, `selected`, the muted text. The grid's own is `datagrid.list` > `toolbar` > (`count`, `search`, `button` with an `active` variant, `chip`), `toggle` (a tree's chevron, the Details toggle), `detail`, `button`, `selectionBar`, `sheet` > (`line`, `input`, `chip`, `button`, `primary`). Both trees carry paint only; the geometry is in the list's own chunk.
+
 ### ContextMenuConfig
 
 | Prop    | Type      | Default | Description                                                               |