@cube-dev/ui-kit 0.0.0-canary-1f0dd2c → 0.0.0-canary-1d27aa0

package/docs/components/data/ItemTable.md

@@ -1,18 +1,27 @@
 # ItemTable
 
-ItemTable renders a list of records as a table: one row per entity, columns declared as data rather than JSX. It is the general-purpose table for list and admin pages.
+ItemTable renders a list of records as a table: one row per entity, columns
+declared as data rather than JSX. It is the general-purpose table for list and
+admin pages.
 
-It renders a real `<table>` with `role="grid"`, and is styled entirely through tasty sub-elements — `Row`, `Cell`, `HeaderCell` and friends are reachable from the single `styles` prop.
+It renders a real `<table>` with `role="grid"`, and is styled entirely through
+tasty sub-elements — `Row`, `Cell`, `HeaderCell` and friends are reachable from
+the single `styles` prop.
 
-> `ItemTable` and `DataTable` are siblings over one internal engine. `ItemTable` is for records; `DataTable` is for analytics results (pivoted columns, pinned totals, cell-range selection).
+> `ItemTable` and `DataTable` are siblings over one internal engine. `ItemTable`
+> is for records; `DataTable` is for analytics results (pivoted columns, pinned
+> totals, cell-range selection).
 
 ## When to Use
 
 - Listing entities the user acts on: deployments, users, API keys, roles.
-- Any table where a row is a _thing_ — it can be opened, selected, or given a menu.
-- Tables that need a column header richer than a label: icon, description, tooltip, actions.
+- Any table where a row is a *thing* — it can be opened, selected, or given a
+  menu.
+- Tables that need a column header richer than a label: icon, description,
+  tooltip, actions.
 
-Use `DataTable` instead when a _cell_ is the unit of interest — query results, pivots, totals. Use `ListBox` when there is only one column.
+Use `DataTable` instead when a *cell* is the unit of interest — query results,
+pivots, totals. Use `ListBox` when there is only one column.
 
 ## Component
 
@@ -22,102 +31,197 @@ Use `DataTable` instead when a _cell_ is the unit of interest — query results,
 - **`columns`** `CubeItemTableColumn<T>[]` — Column definitions. See below.
 - **`rowKey`** `string` (default: `'id'`) — Property used as the row key.
 - **`getRowKey`** `(row: T, index: number) => Key` — Wins over `rowKey`.
-- **`getRowChildren`** `(row: T) => readonly T[] | undefined` — Enables tree mode. `data` then contains top-level rows and children are read recursively.
-- **`treeColumnKey`** `string` — Column containing indentation and the disclosure control. Defaults to the first visible data column.
+- **`getRowChildren`** `(row: T) => readonly T[] | undefined` — Enables tree
+  mode. `data` then contains top-level rows and children are read recursively.
+- **`treeColumnKey`** `string` — Column containing indentation and the
+  disclosure control. Defaults to the first visible data column.
 - **`expandedKeys`** `Key[]` — Controlled expanded rows.
 - **`defaultExpandedKeys`** `Key[]` — Initially expanded rows. Defaults to none.
-- **`onExpand`** `(keys, info) => void` — Reports the complete expanded-key list and the toggled row, key, zero-based level, parent key and resulting state.
-- **`isLoading`** `boolean` (default: `false`) — Marks a fetch in flight. What the user sees depends on `loadingIndicator`.
-- **`loadingIndicator`** `'overlay' | 'skeleton' | 'none'` (default: `'overlay'`) — What to show while `isLoading` is true over rows the table already has. `overlay` keeps them, faded under a sweeping band; `skeleton` replaces them with placeholders; `none` paints nothing beyond `aria-busy`. With no rows yet, `overlay` and `skeleton` both fall back to skeleton rows.
-- **`skeletonRowCount`** `number` (default: `6`) — Skeleton rows to show while loading.
-- **`emptyLabel`** `ReactNode` — Shown when there is nothing at all. Defaults to a localized "No items".
-- **`noResultsLabel`** `ReactNode` — Shown instead of `emptyLabel` when `isFiltered` is set. Defaults to a localized "No results found".
-- **`isFiltered`** `boolean` — Marks the emptiness as the result of a filter, so `noResultsLabel` is shown instead of `emptyLabel`. The built-in search sets it on its own; pass it explicitly when you filter `data` yourself.
+- **`onExpand`** `(keys, info) => void` — Reports the complete expanded-key list
+  and the toggled row, key, zero-based level, parent key and resulting state.
+- **`isLoading`** `boolean` (default: `false`) — Marks a fetch in flight. What
+  the user sees depends on `loadingIndicator`.
+- **`loadingIndicator`** `'overlay' | 'skeleton' | 'none'` (default: `'overlay'`)
+  — What to show while `isLoading` is true over rows the table already has.
+  `overlay` keeps them, faded under a sweeping band; `skeleton` replaces them with
+  placeholders; `none` paints nothing beyond `aria-busy`. With no rows yet,
+  `overlay` and `skeleton` both fall back to skeleton rows.
+- **`skeletonRowCount`** `number` (default: `6`) — Skeleton rows to show while
+  loading.
+- **`emptyLabel`** `ReactNode` — Shown when there is nothing at all. Defaults to
+  a localized "No items".
+- **`noResultsLabel`** `ReactNode` — Shown instead of `emptyLabel` when
+  `isFiltered` is set. Defaults to a localized "No results found".
+- **`isFiltered`** `boolean` — Marks the emptiness as the result of a filter, so
+  `noResultsLabel` is shown instead of `emptyLabel`. The built-in search sets it
+  on its own; pass it explicitly when you filter `data` yourself.
 - **`error`** `ReactNode` — Takes precedence over both labels.
-- **`shape`** `'plain' | 'card'` (default: `'plain'`) — `card` adds a border and a card radius.
-- **`size`** `'xsmall' | 'small' | 'medium' | 'large' | 'xlarge'` (default: `'medium'`) — Drives both heights. At `medium` a row is 40px and the header 32px, each plus its 1px separator.
-- **`rowHeight`** `number` — Row height in px, overriding the one `size` implies. Excludes the 1px separator.
+- **`shape`** `'plain' | 'card'` (default: `'plain'`) — `card` adds a border and
+  a card radius.
+- **`size`** `'xsmall' | 'small' | 'medium' | 'large' | 'xlarge'` (default:
+  `'medium'`) — Drives both heights. At `medium` a row is 40px and the header
+  32px, each plus its 1px separator.
+- **`rowHeight`** `number` — Row height in px, overriding the one `size`
+  implies. Excludes the 1px separator.
 - **`headerHeight`** `number` — Header height in px, excluding its 1px border.
-- **`headerPreset`** `string` (default: `'c3'`) — Typography preset for the column header. `c3` is the small uppercase caption the Cloud list tables use; pass `'t3m'` for body-sized headers.
+- **`headerPreset`** `string` (default: `'c3'`) — Typography preset for the
+  column header. `c3` is the small uppercase caption the Cloud list tables use;
+  pass `'t3m'` for body-sized headers.
 - **`isRowMoveAnimated`** `boolean` (default: `true`) — Slide rows to their new positions when the order changes, instead of teleporting them. Respects `prefers-reduced-motion`.
 - **`isStriped`** `boolean` (default: `false`) — Alternating row background.
-- **`isHeaderHidden`** `boolean` (default: `false`) — Hides the column header row and drops it from `aria-rowcount`.
-- **`isHeaderSticky`** `boolean` (default: `true`) — Pins the column header while the body scrolls.
-- **`isAutoHeight`** `boolean` (default: `false`) — Shrink-wraps the frame to the rendered rows instead of filling its flex pane. It takes precedence over root height/flex sizing and disables virtualization.
-- **`sortMode`** `'client' | 'server' | 'off'` (default: `'client'` when any column is sortable, else `'off'`) — `client` reorders `data` itself; `server` only reflects `sort` and fires `onSortChange`; `off` removes the affordance.
-- **`sort`** `CubeTableSort | null` — Controlled sort, `{ columnKey, direction }` with `direction` being `'asc' | 'desc'`.
+- **`isHeaderHidden`** `boolean` (default: `false`) — Hides the column header
+  row and drops it from `aria-rowcount`.
+- **`isHeaderSticky`** `boolean` (default: `true`) — Pins the column header
+  while the body scrolls.
+- **`isAutoHeight`** `boolean` (default: `false`) — Shrink-wraps the frame to
+  the rendered rows instead of filling its flex pane. It takes precedence over
+  root height/flex sizing and disables virtualization.
+- **`sortMode`** `'client' | 'server' | 'off'` (default: `'client'` when any
+  column is sortable, else `'off'`) — `client` reorders `data` itself; `server`
+  only reflects `sort` and fires `onSortChange`; `off` removes the affordance.
+- **`sort`** `CubeTableSort | null` — Controlled sort, `{ columnKey, direction }`
+  with `direction` being `'asc' | 'desc'`.
 - **`defaultSort`** `CubeTableSort | null` — Initial sort for uncontrolled usage.
-- **`onSortChange`** `(sort: CubeTableSort | null) => void` — Fires on every step of the cycle, including the return to unsorted.
-- **`toolbar`** `ReactNode` — Replaces the entire toolbar row. Compose it from `ItemTable.Search` / `ItemTable.Toolbar`, which read the table's state from context.
-- **`isSearchable`** `boolean` (default: `false`) — Render the built-in search input in the toolbar.
-- **`searchMode`** `'client' | 'server'` (default: `'client'`) — `client` filters `data` with the built-in matcher; `server` only reports the term.
+- **`onSortChange`** `(sort: CubeTableSort | null) => void` — Fires on every step
+  of the cycle, including the return to unsorted.
+- **`toolbar`** `ReactNode` — Replaces the entire toolbar row. Compose it from
+  `ItemTable.Search` / `ItemTable.Toolbar`, which read the table's state from
+  context.
+- **`isSearchable`** `boolean` (default: `false`) — Render the built-in search
+  input in the toolbar.
+- **`searchMode`** `'client' | 'server'` (default: `'client'`) — `client`
+  filters `data` with the built-in matcher; `server` only reports the term.
 - **`searchPlaceholder`** `string` — Placeholder for the search input.
-- **`searchValue`** `string` — Controlled term. Works with `isSearchable={false}` too, so a page can render its own input anywhere and still drive the table's matcher.
+- **`searchValue`** `string` — Controlled term. Works with
+  `isSearchable={false}` too, so a page can render its own input anywhere and
+  still drive the table's matcher.
 - **`defaultSearchValue`** `string` — Initial term for uncontrolled usage.
 - **`onSearchChange`** `(value: string) => void` — Debounced.
-- **`searchDelay`** `number` (default: `500`) — Debounces the filter **and** the callback, in both modes. The input itself stays immediate.
-- **`searchFilter`** `(row: T, query: string) => boolean` — Replaces the default client matcher.
+- **`searchDelay`** `number` (default: `500`) — Debounces the filter **and** the
+  callback, in both modes. The input itself stays immediate.
+- **`searchFilter`** `(row: T, query: string) => boolean` — Replaces the default
+  client matcher.
 - **`filters`** `ReactNode` — Left group, after the search input.
 - **`actions`** `ReactNode` — Right group. Arbitrary JSX.
-- **`onRefresh`** `() => void` — Renders a refresh button at the end of the toolbar.
-- **`isVirtualized`** `boolean | 'auto'` (default: `'auto'`) — `'auto'` turns virtualization on once the row count passes `virtualizeThreshold`. It needs a bounded height to have a viewport to work against and is ignored when `isAutoHeight` is enabled.
-- **`virtualizeThreshold`** `number` (default: `50`) — Row count above which `'auto'` virtualizes.
-- **`overscan`** `number` (default: `12`) — Rows mounted beyond each viewport edge while virtualized. Higher than a list's, because a fast flick outruns React's re-render and the gap shows as blank rows.
-- **`selectionMode`** `'none' | 'single' | 'multiple'` (default: `'none'`) — `multiple` adds the checkbox column and a select-all header checkbox; `single` adds the column without the header checkbox.
-- **`selectedKeys`** `Key[] | 'all'` — Controlled selection. `'all'` is a sentinel meaning "everything, including rows the client has not loaded".
+- **`onRefresh`** `() => void` — Renders a refresh button at the end of the
+  toolbar.
+- **`isVirtualized`** `boolean | 'auto'` (default: `'auto'`) — `'auto'` turns
+  virtualization on once the row count passes `virtualizeThreshold`. It needs a
+  bounded height to have a viewport to work against and is ignored when
+  `isAutoHeight` is enabled.
+- **`virtualizeThreshold`** `number` (default: `50`) — Row count above which
+  `'auto'` virtualizes.
+- **`overscan`** `number` (default: `12`) — Rows mounted beyond each viewport
+  edge while virtualized. Higher than a list's, because a fast flick outruns
+  React's re-render and the gap shows as blank rows.
+- **`selectionMode`** `'none' | 'single' | 'multiple'` (default: `'none'`) —
+  `multiple` adds the checkbox column and a select-all header checkbox;
+  `single` adds the column without the header checkbox.
+- **`selectedKeys`** `Key[] | 'all'` — Controlled selection. `'all'` is a
+  sentinel meaning "everything, including rows the client has not loaded".
 - **`defaultSelectedKeys`** `Key[] | 'all'` — Initial selection.
-- **`onSelectionChange`** `(keys: Key[] | 'all', rows: T[]) => void` — `rows` holds only the rows the client has loaded.
-- **`selectAllMode`** `'page' | 'filtered' | 'all'` (default: `'page'`) — What the header checkbox acts on.
-- **`isRowSelectable`** `(row: T) => boolean` — The row stays focusable and clickable; only its checkbox goes inert.
-- **`selectionTooltip`** `string | ((row: T) => string | undefined)` — Explains an inert checkbox.
+- **`onSelectionChange`** `(keys: Key[] | 'all', rows: T[]) => void` — `rows`
+  holds only the rows the client has loaded.
+- **`selectAllMode`** `'page' | 'filtered' | 'all'` (default: `'page'`) — What
+  the header checkbox acts on.
+- **`isRowSelectable`** `(row: T) => boolean` — The row stays focusable and
+  clickable; only its checkbox goes inert.
+- **`selectionTooltip`** `string | ((row: T) => string | undefined)` — Explains
+  an inert checkbox.
 - **`disabledKeys`** `Key[]` — Rows that cannot be interacted with at all.
-- **`treeSelectionBehavior`** `'cascade' | 'independent'` (default: `'cascade'` in tree mode) — Multiple selection only. Cascade selects eligible descendants and derives checked or indeterminate ancestors; single selection is always independent.
-- **`rowLink`** `(row: T, index: number) => NavigateArg | undefined` — Turns the row-header cell into a stretched link covering the whole row. Return `undefined` for a row that should not navigate.
-- **`onRowAction`** `(row: T, key: Key) => void` — Non-navigational activation: Enter, or a click that did not land on a control inside a cell.
-- **`rowMenu`** `ReactNode | ((row, ctx) => ReactNode | null)` — `Menu.Item` children. Inert until `rowContextMenu` exposes it.
-- **`rowContextMenu`** `boolean | 'context-only'` (default: `false`) — `true` gives a `⋮` trigger column **and** right-click / Shift+F10; `'context-only'` gives the keyboard and pointer paths without the column.
-- **`onRowMenuAction`** `(action: string, row: T, key: Key) => void` — The action key as written on `Menu.Item`.
-- **`rowMenuTriggerProps`** `Partial<CubeItemActionProps>` — Forwarded to every `⋮` trigger.
-- **`bulkActions`** `CubeTableBulkAction<T>[]` — Actions offered while rows are selected. Supplying any implies `selectionMode="multiple"`.
-- **`bulkBarPlacement`** `'floating' | 'toolbar'` (default: `'floating'`) — `floating` centres the bar over the body without changing the table's height; `toolbar` replaces the `actions` group while a selection exists.
+- **`treeSelectionBehavior`** `'cascade' | 'independent'` (default: `'cascade'`
+  in tree mode) — Multiple selection only. Cascade selects eligible descendants
+  and derives checked or indeterminate ancestors; single selection is always
+  independent.
+- **`rowLink`** `(row: T, index: number) => NavigateArg | undefined` — Turns the
+  row-header cell into a stretched link covering the whole row. Return
+  `undefined` for a row that should not navigate.
+- **`onRowAction`** `(row: T, key: Key) => void` — Non-navigational activation:
+  Enter, or a click that did not land on a control inside a cell.
+- **`rowMenu`** `ReactNode | ((row, ctx) => ReactNode | null)` — `Menu.Item`
+  children. Inert until `rowContextMenu` exposes it.
+- **`rowContextMenu`** `boolean | 'context-only'` (default: `false`) — `true`
+  gives a `⋮` trigger column **and** right-click / Shift+F10;
+  `'context-only'` gives the keyboard and pointer paths without the column.
+- **`onRowMenuAction`** `(action: string, row: T, key: Key) => void` — The
+  action key as written on `Menu.Item`.
+- **`rowMenuTriggerProps`** `Partial<CubeItemActionProps>` — Forwarded to every
+  `⋮` trigger.
+- **`bulkActions`** `CubeTableBulkAction<T>[]` — Actions offered while rows are
+  selected. Supplying any implies `selectionMode="multiple"`.
+- **`bulkBarPlacement`** `'floating' | 'toolbar'` (default: `'floating'`) —
+  `floating` centres the bar over the body without changing the table's height;
+  `toolbar` replaces the `actions` group while a selection exists.
 - **`bulkBarStyles`** `Styles` — Styles for the bar.
-- **`paginationMode`** `'client' | 'server' | 'off'` (default: `'client'`) — `client` slices the searched and sorted rows; `server` never slices and only reflects `page` / `total`; `off` removes the control.
+- **`paginationMode`** `'client' | 'server' | 'off'` (default: `'client'`) —
+  `client` slices the searched and sorted rows; `server` never slices and only
+  reflects `page` / `total`; `off` removes the control.
 - **`pageSize`** `number` — Controlled page size.
 - **`defaultPageSize`** `number` (default: `50`) — Initial page size.
-- **`onPageSizeChange`** `(pageSize: number) => void` — Fires with the new size. Changing the size returns to page 1.
-- **`pageSizeOptions`** `number[]` (default: `[10, 20, 50, 100, 500]`) — Choices in the page-size selector.
+- **`onPageSizeChange`** `(pageSize: number) => void` — Fires with the new size.
+  Changing the size returns to page 1.
+- **`pageSizeOptions`** `number[]` (default: `[10, 20, 50, 100, 500]`) — Choices
+  in the page-size selector.
 - **`page`** `number` — Controlled 1-based page.
 - **`defaultPage`** `number` (default: `1`) — Initial page.
 - **`onPageChange`** `(page: number) => void` — Fires with the clamped page.
-- **`onLoadMore`** `() => void` — `paginationMode="infinite"` only. Fires once the end of the list comes into view.
+- **`onLoadMore`** `() => void` — `paginationMode="infinite"` only. Fires once
+  the end of the list comes into view.
 - **`hasMore`** `boolean` — Whether there is anything left to fetch.
-- **`isLoadingMore`** `boolean` — Suppresses further calls while a batch is in flight and shows a loading row.
-- **`loadMoreMargin`** `number` (default: one viewport height) — How far before the end to start fetching, in px.
-- **`autoHidePagination`** `boolean` (default: `true`) — Hides the pagination control when it cannot do anything: a single page whose total even the smallest `pageSizeOptions` entry would not split. The footer still renders if any slot has content.
+- **`isLoadingMore`** `boolean` — Suppresses further calls while a batch is in
+  flight and shows a loading row.
+- **`loadMoreMargin`** `number` (default: one viewport height) — How far before
+  the end to start fetching, in px.
+- **`autoHidePagination`** `boolean` (default: `true`) — Hides the pagination
+  control when it cannot do anything: a single page whose total even the
+  smallest `pageSizeOptions` entry would not split. The footer still renders if
+  any slot has content.
 - **`total`** `number` — Server mode: total row count behind the query.
-- **`totalPages`** `number` — Server mode alternative to `total` when the count is unknown.
-- **`hasNextPage`** `boolean` — Server mode: keeps "next" enabled when neither `total` nor `totalPages` is known.
-- **`summary`** `boolean | ((info: CubeTablePageInfo) => ReactNode)` (default: `true`) — The localized item range in the footer, e.g. "1–50 of 1,204".
+- **`totalPages`** `number` — Server mode alternative to `total` when the count
+  is unknown.
+- **`hasNextPage`** `boolean` — Server mode: keeps "next" enabled when neither
+  `total` nor `totalPages` is known.
+- **`summary`** `boolean | ((info: CubeTablePageInfo) => ReactNode)` (default:
+  `true`) — The localized item range in the footer, e.g. "1–50 of 1,204".
 - **`footer`** `ReactNode` — Replaces the entire footer row.
-- **`footerStart`** `ReactNode` — Start footer slot. Renders even with `paginationMode="off"` — this is where a "Load all results" button belongs.
+- **`footerStart`** `ReactNode` — Start footer slot. Renders even with
+  `paginationMode="off"` — this is where a "Load all results" button belongs.
 - **`footerCenter`** `ReactNode` — Center footer slot.
 - **`footerEnd`** `ReactNode` — End footer slot, before the pagination control.
 - **`footerStyles`** `Styles` — Styles for the footer row.
-- **`isReorderable`** `boolean` (default: `false`) — Lets rows be dragged into a new order.
-- **`onReorder`** `(keys: Key[], rows: T[]) => void` — The **whole** new order, not just the moved row, so it can be persisted directly.
-- **`dropOnRow`** `{ isTarget, isAllowed?, onDrop }` — Dropping rows _onto_ a row, e.g. a workbook into a folder. Enables dragging on its own, and composes with `isReorderable`.
-- **`getItemDragInfo`** `(row: T) => { label, icon? }` — What the cursor drags. One row shows its icon and label; several show a count. Without it the browser drags a screenshot of the row.
-- **`isResizable`** `boolean` (default: `false`) — Adds a resize handle to every column; a column overrides with its own `isResizable`.
+- **`isReorderable`** `boolean` (default: `false`) — Lets rows be dragged into a
+  new order.
+- **`onReorder`** `(keys: Key[], rows: T[]) => void` — The **whole** new order,
+  not just the moved row, so it can be persisted directly.
+- **`dropOnRow`** `{ isTarget, isAllowed?, onDrop }` — Dropping rows *onto* a
+  row, e.g. a workbook into a folder. Enables dragging on its own, and composes
+  with `isReorderable`.
+- **`getItemDragInfo`** `(row: T) => { label, icon? }` — What the cursor drags.
+  One row shows its icon and label; several show a count. Without it the browser
+  drags a screenshot of the row.
+- **`isResizable`** `boolean` (default: `false`) — Adds a resize handle to every
+  column; a column overrides with its own `isResizable`.
 - **`columnWidths`** `Record<string, number>` — Controlled widths by column key.
 - **`defaultColumnWidths`** `Record<string, number>` — Initial widths.
-- **`onColumnResize`** `(columnKey, width, all) => void` — Fires once the gesture ends, not on every pixel.
-- **`columnContextMenu`** `boolean | 'context-only'` (default: `true`) — Where a column's `header.menu` is exposed: a `⋮` trigger plus right-click and Shift+F10, right-click only, or nowhere.
-- **`onColumnMenuAction`** `(action, columnKey) => void` — The pressed `Menu.Item` key, as written. Fires for the reserved sort keys too, after the table has applied them.
+- **`onColumnResize`** `(columnKey, width, all) => void` — Fires once the
+  gesture ends, not on every pixel.
+- **`columnContextMenu`** `boolean | 'context-only'` (default: `true`) — Where a
+  column's `header.menu` is exposed: a `⋮` trigger plus right-click and
+  Shift+F10, right-click only, or nowhere.
+- **`onColumnMenuAction`** `(action, columnKey) => void` — The pressed
+  `Menu.Item` key, as written. Fires for the reserved sort keys too, after the
+  table has applied them.
 - **`columnMenuTriggerProps`** `Record<string, any>` — Props for the `⋮` trigger.
 - **`columnMenuProps`** `Record<string, any>` — Props for the `Menu`.
-- **`storageKey`** `string` — Persists the table's own state under `cube-ui-kit:table:${storageKey}`. Controlled state is never stored — a controlled `pageSize` or `sort` belongs to the page, and restoring it would give the table a second, competing source of truth.
-- **`persist`** `('pageSize' | 'columnWidths' | 'sort')[]` (default: `['pageSize', 'columnWidths']`) — What `storageKey` covers. Sort is opt-in, because a stored sort silently changes what the first screen of a table means.
-- **`getRowProps`** `(ctx) => { isDimmed?, mods?, styles?, height?, qa?, tooltip? }` — Per-row visuals.
+- **`storageKey`** `string` — Persists the table's own state under
+  `cube-ui-kit:table:${storageKey}`. Controlled state is never stored — a
+  controlled `pageSize` or `sort` belongs to the page, and restoring it would
+  give the table a second, competing source of truth.
+- **`persist`** `('pageSize' | 'columnWidths' | 'sort')[]` (default:
+  `['pageSize', 'columnWidths']`) — What `storageKey` covers. Sort is opt-in,
+  because a stored sort silently changes what the first screen of a table means.
+- **`getRowProps`** `(ctx) => { isDimmed?, mods?, styles?, height?, qa?, tooltip? }`
+  — Per-row visuals.
 - **`ariaLabel`** `string` — Labels the grid.
 - **`isChecked`** `boolean` — Base checked-state modifier.
 - **`place`** `string` — Tasty placement shorthand on the root frame.
@@ -156,11 +260,16 @@ interface CubeItemTableColumn<T> {
 }
 ```
 
-**The value pipeline is the escape hatch.** `getValue`, `format` and `compare` exist so a column whose displayed text differs from its raw value stays sortable, searchable and copyable. `render` is for appearance only — sorting and searching never see its output, which is why an object-valued column with no `format` renders empty rather than `"[object Object]"`.
+**The value pipeline is the escape hatch.** `getValue`, `format` and `compare`
+exist so a column whose displayed text differs from its raw value stays
+sortable, searchable and copyable. `render` is for appearance only — sorting and
+searching never see its output, which is why an object-valued column with no
+`format` renders empty rather than `"[object Object]"`.
 
 #### `CubeTableColumnHeader`
 
-Every slot maps 1:1 onto the `Item` rendered inside the header cell, so a header gets an icon, a description, a tooltip and actions for free:
+Every slot maps 1:1 onto the `Item` rendered inside the header cell, so a header
+gets an icon, a description, a tooltip and actions for free:
 
 ```jsx
 {
@@ -178,7 +287,11 @@ Every slot maps 1:1 onto the `Item` rendered inside the header cell, so a header
 
 `header.render(ctx)` takes over the cell's content entirely.
 
-On a sortable column the sort arrow occupies the `rightIcon` slot — it is an icon, and that slot is sized and aligned for one. The slot stays reserved while unsorted, so toggling a sort never shifts the label. If you set `header.rightIcon` yourself it keeps the slot and the arrow falls back to `suffix`.
+On a sortable column the sort arrow occupies the `rightIcon` slot — it is an
+icon, and that slot is sized and aligned for one. The slot stays reserved while
+unsorted, so toggling a sort never shifts the label. If you set
+`header.rightIcon` yourself it keeps the slot and the arrow falls back to
+`suffix`.
 
 ### Base Properties
 
@@ -188,7 +301,8 @@ Supports Base Properties.
 
 #### styles
 
-Customizes the root frame. Every internal part of the table is a **sub-element** reachable from this one prop — that is the whole styling contract.
+Customizes the root frame. Every internal part of the table is a **sub-element**
+reachable from this one prop — that is the whole styling contract.
 
 **Sub-elements:**
 
@@ -196,7 +310,8 @@ Customizes the root frame. Every internal part of the table is a **sub-element**
 - `Table` — the `<table>`
 - `Head`, `HeadRow`, `HeaderCell` — the column header
 - `Body`, `Row`, `Cell` — the data rows
-- `TreeContent`, `TreeToggle`, `TreeValue` — indentation, disclosure/leaf placeholder, and the consumer-rendered value in the tree column
+- `TreeContent`, `TreeToggle`, `TreeValue` — indentation, disclosure/leaf
+  placeholder, and the consumer-rendered value in the tree column
 - `SortIndicator` — the sort arrow, inside the header `Item`'s suffix
 - `Foot`, `FootRow`, `FootCell` — pinned totals
 - `StateContent` — the empty / no-results / error content
@@ -210,13 +325,20 @@ const Compact = tasty(ItemTable, {
 });
 ```
 
-Rows publish their paint as inherited custom properties — `#row-base`, `#row-overlay`, `#row-text` and `$dim` — which cells consume. That is what lets a pinned (and therefore opaque) cell match its row's state without duplicating the state matrix.
+Rows publish their paint as inherited custom properties — `#row-base`,
+`#row-overlay`, `#row-text` and `$dim` — which cells consume. That is what lets
+a pinned (and therefore opaque) cell match its row's state without duplicating
+the state matrix.
 
-Geometry runs through tokens too: `$row-height`, `$header-height`, `$cell-padding-x` (16px) and `$cell-padding-y`. Height lives on the **cells**, not the `<tr>` — table layout ignores `min-height` on a row and sizes it from its cells instead.
+Geometry runs through tokens too: `$row-height`, `$header-height`,
+`$cell-padding-x` (16px) and `$cell-padding-y`. Height lives on the **cells**,
+not the `<tr>` — table layout ignores `min-height` on a row and sizes it from
+its cells instead.
 
 #### toolbarStyles
 
-The toolbar row. Sub-elements: `Start` (search + filters) and `End` (actions + refresh).
+The toolbar row. Sub-elements: `Start` (search + filters) and `End` (actions +
+refresh).
 
 #### searchStyles
 
@@ -224,11 +346,13 @@ The built-in search input.
 
 #### headerStyles
 
-The **column header row**. (The top chrome, when it arrives, is `toolbarStyles` — a table has two things called "header" and this one is the columns.)
+The **column header row**. (The top chrome, when it arrives, is `toolbarStyles`
+— a table has two things called "header" and this one is the columns.)
 
 #### headerCellStyles
 
-Every column header cell. Wins over `headerPreset`, so this is where you go for anything the preset does not cover.
+Every column header cell. Wins over `headerPreset`, so this is where you go for
+anything the preset does not cover.
 
 #### bodyStyles
 
@@ -253,17 +377,21 @@ These properties allow direct style application without using the `styles` prop:
 - **Color:** `color`, `fill`, `fade`, `image`
 - **Flow:** `flow`, `gap`, `columnGap`, `rowGap`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
 
-`height` is the important one: there is no page-scroll mode, so bounding the table is what turns the body into a scroller and pins the header. An unbounded table simply sizes to its content.
+`height` is the important one: there is no page-scroll mode, so
+bounding the table is what turns the body into a scroller and pins the header.
+An unbounded table simply sizes to its content.
 
 ### Modifiers
 
-| Modifier        | Type                | Description      |
-| --------------- | ------------------- | ---------------- |
-| `size`          | `SizeName`          | Row height scale |
-| `shape`         | `'plain' \| 'card'` | Frame treatment  |
-| `sticky-header` | `boolean`           | Header is pinned |
+| Modifier | Type | Description |
+| -------- | ---- | ----------- |
+| `size` | `SizeName` | Row height scale |
+| `shape` | `'plain' \| 'card'` | Frame treatment |
+| `sticky-header` | `boolean` | Header is pinned |
 
-Row-level modifiers, set on each `<tr>`: `odd`, `selected`, `focused`, `dimmed`, `disabled`, `drop-target`, `placeholder`. Cell-level: `pin`, `pin-edge`, `align`, `wrap`, `state`.
+Row-level modifiers, set on each `<tr>`: `odd`, `selected`, `focused`, `dimmed`,
+`disabled`, `drop-target`, `placeholder`. Cell-level: `pin`, `pin-edge`,
+`align`, `wrap`, `state`.
 
 ## Examples
 
@@ -285,7 +413,8 @@ Row-level modifiers, set on each `<tr>`: `odd`, `selected`, `focused`, `dimmed`,
 
 ### Tree Rows
 
-Supplying `getRowChildren` changes the root to `role="treegrid"`. Rows keep their original objects; keys must be unique across the complete hierarchy.
+Supplying `getRowChildren` changes the root to `role="treegrid"`. Rows keep their
+original objects; keys must be unique across the complete hierarchy.
 
 ```jsx
 <ItemTable
@@ -298,11 +427,22 @@ Supplying `getRowChildren` changes the root to `role="treegrid"`. Rows keep thei
 />
 ```
 
-Client sorting runs independently within every sibling collection. Client search retains ancestor paths; a matching parent keeps its complete subtree, and required branches open temporarily without changing `expandedKeys`. Client pagination counts and slices roots, keeping each subtree on its parent's page. Server modes treat the supplied nested page as already processed, and `total` counts roots.
+Client sorting runs independently within every sibling collection. Client
+search retains ancestor paths; a matching parent keeps its complete subtree,
+and required branches open temporarily without changing `expandedKeys`. Client
+pagination counts and slices roots, keeping each subtree on its parent's page.
+Server modes treat the supplied nested page as already processed, and `total`
+counts roots.
 
-The chevron and Right/Left arrows expand or collapse. Up/Down traverse visible rows, typeahead uses the tree column, and Left on a collapsed child moves to its parent. Ordinary row clicks still activate `onRowAction`/`rowLink`; the disclosure does not. Select-all includes collapsed descendants. Disabled and unselectable descendants are excluded from cascade.
+The chevron and Right/Left arrows expand or collapse. Up/Down traverse visible
+rows, typeahead uses the tree column, and Left on a collapsed child moves to its
+parent. Ordinary row clicks still activate `onRowAction`/`rowLink`; the
+disclosure does not. Select-all includes collapsed descendants. Disabled and
+unselectable descendants are excluded from cascade.
 
-Tree mode ignores `isReorderable`, because a flat reordered array cannot encode parents. `dropOnRow` remains available for folder moves; self/descendant cycles are rejected and selected descendants are collapsed under a dragged ancestor.
+Tree mode ignores `isReorderable`, because a flat reordered array cannot encode
+parents. `dropOnRow` remains available for folder moves; self/descendant cycles
+are rejected and selected descendants are collapsed under a dragged ancestor.
 
 ### Custom Cells
 
@@ -317,15 +457,21 @@ Tree mode ignores `isReorderable`, because a flat reordered array cannot encode
 
 ### Appearance
 
-`shape="card"` frames the table, `isStriped` bands the rows, `size` drives both row and header height, and `isHeaderHidden` drops the header row.
+`shape="card"` frames the table, `isStriped` bands the rows, `size` drives both
+row and header height, and `isHeaderHidden` drops the header row.
 
 ### Empty, No-results and Error States
 
-`isFiltered` is what separates "no matches" from "nothing exists"; the built-in search sets it for you.
+`isFiltered` is what separates "no matches" from "nothing exists"; the built-in
+search sets it for you.
 
 ### Sorting
 
-Sorting is **opt in, per column**: a table with no `isSortable` column has inert headers and `sortMode` resolves to `'off'`. Mark columns `isSortable` and clicking a header cycles `ascending → descending → unsorted`. The third state matters whenever the source order is meaningful, which is why it is the default cycle; set `disallowSortRemoval` on a column to reduce it to `asc ↔ desc`.
+Sorting is **opt in, per column**: a table with no `isSortable` column has inert
+headers and `sortMode` resolves to `'off'`. Mark columns `isSortable` and
+clicking a header cycles `ascending → descending → unsorted`. The third state
+matters whenever the source order is meaningful, which is why it is the default
+cycle; set `disallowSortRemoval` on a column to reduce it to `asc ↔ desc`.
 
 ```jsx
 <ItemTable
@@ -341,7 +487,10 @@ Sorting is **opt in, per column**: a table with no `isSortable` column has inert
 
 #### A fixed order the user cannot change
 
-For a list that arrives in a meaningful order — most of them — leave every column alone and pass the order you want. `sortMode="client"` keeps the engine sorting while the headers stay inert, so nothing is clickable and no header takes a tab stop:
+For a list that arrives in a meaningful order — most of them — leave every column
+alone and pass the order you want. `sortMode="client"` keeps the engine sorting
+while the headers stay inert, so nothing is clickable and no header takes a tab
+stop:
 
 ```jsx
 <ItemTable
@@ -352,13 +501,21 @@ For a list that arrives in a meaningful order — most of them — leave every c
 />
 ```
 
-The sorted column still carries `aria-sort`, so a screen reader announces the order even though the header cannot be operated. It is **not** drawn — the sort arrow belongs to the clickable affordance — so add your own marker through `header.suffix` if sighted users need to see which column the order follows.
+The sorted column still carries `aria-sort`, so a screen reader announces the
+order even though the header cannot be operated. It is **not** drawn — the sort
+arrow belongs to the clickable affordance — so add your own marker through
+`header.suffix` if sighted users need to see which column the order follows.
 
 Data already in the right order needs none of this: pass it and set nothing.
 
-Client-side sorting compares raw `getValue` results — numerically for numbers, chronologically for dates — and falls back to a locale-aware collator over the column's display text, so a formatted column sorts the way it reads. `compare` overrides all of it. Nullish values sort first, then flip with the direction.
+Client-side sorting compares raw `getValue` results — numerically for numbers,
+chronologically for dates — and falls back to a locale-aware collator over the
+column's display text, so a formatted column sorts the way it reads. `compare`
+overrides all of it. Nullish values sort first, then flip with the direction.
 
-`sortMode="server"` reflects the state and reports changes without ever reordering the rows. The second table below is server-sorted over a simulated round trip:
+`sortMode="server"` reflects the state and reports changes without ever
+reordering the rows. The second table below is server-sorted over a simulated
+round trip:
 
 ```jsx
 <ItemTable
@@ -385,17 +542,30 @@ Client-side sorting compares raw `getValue` results — numerically for numbers,
 />
 ```
 
-The default matcher tests each column's **display text** — `format?.(value) ?? String(getValue(row))` — not the raw value. So a formatted column matches what the user can actually see, a dotted `key` like `owner.name` is searchable, and a column holding an object with no `format` is skipped rather than stringified into `"[object Object]"` (which would make the query "object" match every row). Opt a column out with `isSearchable: false`, or replace the matcher entirely with `searchFilter`.
+The default matcher tests each column's **display text** — `format?.(value) ??
+String(getValue(row))` — not the raw value. So a formatted column matches what
+the user can actually see, a dotted `key` like `owner.name` is searchable, and a
+column holding an object with no `format` is skipped rather than stringified
+into `"[object Object]"` (which would make the query "object" match every row).
+Opt a column out with `isSearchable: false`, or replace the matcher entirely
+with `searchFilter`.
 
-Searching also selects `noResultsLabel` over `emptyLabel` on its own, and resets to page 1, so a client-search table distinguishes "no matches" from "nothing exists" without the page owning the term.
+Searching also selects `noResultsLabel` over `emptyLabel` on its own, and resets
+to page 1, so a client-search table distinguishes "no matches" from "nothing
+exists" without the page owning the term.
 
 ### Server-side Search
 
-`searchMode="server"` never filters — it reports the debounced term and the query does the work.
+`searchMode="server"` never filters — it reports the debounced term and the
+query does the work.
 
 ### An External Search Box, and a Custom Toolbar
 
-The input does not have to live in the table. `isSearchable={false}` hides the built-in one while a controlled `searchValue` still drives the table's matcher — a first-class path, not a workaround. The second table rebuilds the toolbar entirely; `ItemTable.Search` reads the table's state from context, so the term still has one owner.
+The input does not have to live in the table. `isSearchable={false}` hides the
+built-in one while a controlled `searchValue` still drives the table's matcher —
+a first-class path, not a workaround. The second table rebuilds the toolbar
+entirely; `ItemTable.Search` reads the table's state from context, so the term
+still has one owner.
 
 ```jsx
 const [term, setTerm] = useState('');
@@ -406,21 +576,34 @@ const [term, setTerm] = useState('');
 
 ### Pagination
 
-Pagination lives in the footer and is on by default (`paginationMode="client"`, 50 rows a page). The page-size selector appears whenever `pageSizeOptions` is set, and `summary` prints the localized item range.
+Pagination lives in the footer and is on by default (`paginationMode="client"`,
+50 rows a page). The page-size selector appears whenever `pageSizeOptions` is
+set, and `summary` prints the localized item range.
 
 ```jsx
 <ItemTable data={rows} columns={columns} defaultPageSize={20} pageSizeOptions={[20, 50, 100]} />
 ```
 
-Client pagination slices the **searched and sorted** rows, so a page always reflects what the user is looking at, and the summary counts filtered rows rather than the raw array. Changing the page size returns to page 1, because the old page index points at different rows under a new size.
+Client pagination slices the **searched and sorted** rows, so a page always
+reflects what the user is looking at, and the summary counts filtered rows
+rather than the raw array. Changing the page size returns to page 1, because the
+old page index points at different rows under a new size.
 
-Pagination that cannot do anything hides itself. One page of five rows would otherwise render "1–5 of 5", a page-size selector whose every option shows the same five rows, and a solitary "1" button. The test is both conditions together — a single page **and** a total the smallest page size would not split — so a 15-row single page keeps its control, because "10 / page" would genuinely paginate it. Set `autoHidePagination={false}` to always show it.
+Pagination that cannot do anything hides itself. One page of five rows would
+otherwise render "1–5 of 5", a page-size selector whose every option shows the
+same five rows, and a solitary "1" button. The test is both conditions together
+— a single page **and** a total the smallest page size would not split — so a
+15-row single page keeps its control, because "10 / page" would genuinely
+paginate it. Set `autoHidePagination={false}` to always show it.
 
-Note that pagination and virtualization are alternatives: a 50-row page is well under `virtualizeThreshold`, so a paginated table normally renders every row. Set `paginationMode="off"` for the long-scroll case.
+Note that pagination and virtualization are alternatives: a 50-row page is well
+under `virtualizeThreshold`, so a paginated table normally renders every row.
+Set `paginationMode="off"` for the long-scroll case.
 
 ### Infinite Scroll
 
-`paginationMode="infinite"` replaces the page control with load-on-scroll. The table never slices in this mode — `data` is the list accumulated so far:
+`paginationMode="infinite"` replaces the page control with load-on-scroll. The
+table never slices in this mode — `data` is the list accumulated so far:
 
 ```jsx
 <ItemTable
@@ -434,19 +617,42 @@ Note that pagination and virtualization are alternatives: a 50-row page is well
 />
 ```
 
-It is driven by an `IntersectionObserver` on a sentinel at the end of the body rather than a scroll handler: `loadMoreMargin` then expresses "prefetch this far before the end" directly, and it costs nothing per scroll tick. The observer re-arms only once `isLoadingMore` clears, so a request in flight is never fired twice by a sentinel still sitting in view.
-
-The fetch starts **a full screen before the end** — `loadMoreMargin` defaults to the scroller's own height — so the request goes out while there is still a viewport of rows left to read, and the batch has usually arrived by the time the user gets there. A fixed 200px, about five rows, meant a fast scroll reached the bottom before the response did, which is exactly the stall infinite scroll is supposed to avoid.
-
-While a batch is in flight the table appends **skeleton rows**, not a spinner. They keep the row grid, read as "more rows of this shape are coming", and grow the scroll height smoothly instead of a block that appears and vanishes — and it matches what the first load already shows.
-
-The burst is sized to **the batch that is coming**, measured from the last one that arrived, so the list keeps its length through the load: the user can carry on scrolling into it, and nothing lurches when the rows land. Measured rather than read from `pageSize`, which infinite-scroll consumers often do not set — and the first batch is the best predictor of the second. Capped at 50 rows, which is taller than any viewport, because these particular rows are not virtualized.
-
-Under virtualization the trailing spacer holds the remaining height, so the sentinel still marks the true end of the list rather than the end of the rendered window.
+It is driven by an `IntersectionObserver` on a sentinel at the end of the body
+rather than a scroll handler: `loadMoreMargin` then expresses "prefetch this far
+before the end" directly, and it costs nothing per scroll tick. The observer
+re-arms only once `isLoadingMore` clears, so a request in flight is never fired
+twice by a sentinel still sitting in view.
+
+The fetch starts **a full screen before the end** — `loadMoreMargin` defaults to
+the scroller's own height — so the request goes out while there is still a
+viewport of rows left to read, and the batch has usually arrived by the time the
+user gets there. A fixed 200px, about five rows, meant a fast scroll reached the
+bottom before the response did, which is exactly the stall infinite scroll is
+supposed to avoid.
+
+While a batch is in flight the table appends **skeleton rows**, not a spinner.
+They keep the row grid, read as "more rows of this shape are coming", and grow
+the scroll height smoothly instead of a block that appears and vanishes — and it
+matches what the first load already shows.
+
+The burst is sized to **the batch that is coming**, measured from the last one
+that arrived, so the list keeps its length through the load: the user can carry
+on scrolling into it, and nothing lurches when the rows land. Measured rather
+than read from `pageSize`, which infinite-scroll consumers often do not set —
+and the first batch is the best predictor of the second. Capped at 50 rows,
+which is taller than any viewport, because these particular rows are not
+virtualized.
+
+Under virtualization the trailing spacer holds the remaining height, so the
+sentinel still marks the true end of the list rather than the end of the
+rendered window.
 
 ### Footer Slots
 
-The footer has three named slots, and they render whether or not pagination is on. `footerStart` is where Cloud's "Load all results" button belongs — the thing that today needs a `MutationObserver` to inject into ag-grid's paging panel, because Community has no status bar.
+The footer has three named slots, and they render whether or not pagination is
+on. `footerStart` is where Cloud's "Load all results" button belongs — the thing
+that today needs a `MutationObserver` to inject into ag-grid's paging panel,
+because Community has no status bar.
 
 ```jsx
 <ItemTable
@@ -459,7 +665,8 @@ The footer has three named slots, and they render whether or not pagination is o
 
 ### Server-side Pagination
 
-`paginationMode="server"` never slices — it reflects `page` and reports changes, and `total` comes from the query. `data` is the current page.
+`paginationMode="server"` never slices — it reflects `page` and reports changes,
+and `total` comes from the query. `data` is the current page.
 
 ```jsx
 <ItemTable
@@ -477,7 +684,8 @@ The footer has three named slots, and they render whether or not pagination is o
 
 ### Loading Behaviour
 
-`loadingIndicator` chooses what happens while `isLoading` is true over rows the table already has — the window that only exists once a query is involved:
+`loadingIndicator` chooses what happens while `isLoading` is true over rows the
+table already has — the window that only exists once a query is involved:
 
 | Value | Behaviour |
 | --- | --- |
@@ -485,11 +693,15 @@ The footer has three named slots, and they render whether or not pagination is o
 | `skeleton` | The previous rows are discarded for placeholders. Honest that the data is gone, but it flashes on every page and a short page makes the table jump. |
 | `none` | No visuals beyond `aria-busy`. For pages that already show a top-level progress bar and do not want a second indicator. |
 
-With no rows yet, `overlay` and `skeleton` both render skeleton rows — there is nothing to keep — and `none` renders an empty body rather than flashing the `emptyLabel` before the first response arrives.
+With no rows yet, `overlay` and `skeleton` both render skeleton rows — there is
+nothing to keep — and `none` renders an empty body rather than flashing the
+`emptyLabel` before the first response arrives.
 
 ### Bounded Height, Sticky Header and Pinned Columns
 
-A bounded height turns the body into a scroller and pins the header. Pinned columns are sticky `<th>`/`<td>` — one scroller, no lanes, no scroll sync. They are moved to the edges in DOM order too, so `aria-colindex` stays truthful.
+A bounded height turns the body into a scroller and pins the header. Pinned
+columns are sticky `<th>`/`<td>` — one scroller, no lanes, no scroll sync. They
+are moved to the edges in DOM order too, so `aria-colindex` stays truthful.
 
 ```jsx
 <ItemTable
@@ -505,9 +717,14 @@ A bounded height turns the body into a scroller and pins the header. Pinned colu
 
 ### Virtualization
 
-Above `virtualizeThreshold` rows a bounded table virtualizes automatically. The DOM and the styles are identical either way — only the number of mounted rows changes, so sorting, search, pinned columns and the sticky header all behave the same.
+Above `virtualizeThreshold` rows a bounded table virtualizes automatically. The
+DOM and the styles are identical either way — only the number of mounted rows
+changes, so sorting, search, pinned columns and the sticky header all behave the
+same.
 
-For a compact list in normal page flow, set `isAutoHeight`. Its frame then ends at the final rendered row instead of filling the surrounding flex pane. The complete result is rendered, so keep large lists bounded and virtualized.
+For a compact list in normal page flow, set `isAutoHeight`. Its frame then ends
+at the final rendered row instead of filling the surrounding flex pane. The
+complete result is rendered, so keep large lists bounded and virtualized.
 
 ```jsx
 <ItemTable data={recentRows} columns={columns} paginationMode="off" isAutoHeight />
@@ -517,15 +734,26 @@ For a compact list in normal page flow, set `isAutoHeight`. Its frame then ends
 <ItemTable height="420px" paginationMode="off" data={tenThousandRows} columns={columns} />
 ```
 
-Overscroll is locked per axis, and only where the table can actually scroll, so a table whose content fits never traps the wheel — the page behind it scrolls as usual. On an axis that does scroll, a swipe at the edge neither chains to the page (which is what would trigger browser back-navigation) nor rubber-bands, since bouncing drags the rows off the sticky header and shows blank surface behind them.
+Overscroll is locked per axis, and only where the table can actually scroll, so
+a table whose content fits never traps the wheel — the page behind it scrolls as
+usual. On an axis that does scroll, a swipe at the edge neither chains to the
+page (which is what would trigger browser back-navigation) nor rubber-bands,
+since bouncing drags the rows off the sticky header and shows blank surface
+behind them.
 
-A native table cannot absolutely position a `<tr>` without breaking the table box, so the offset comes from leading and trailing spacer rows. Those are `aria-hidden`, and `aria-rowcount` / `aria-rowindex` continue to describe the whole dataset rather than the mounted window.
+A native table cannot absolutely position a `<tr>` without breaking the table
+box, so the offset comes from leading and trailing spacer rows. Those are
+`aria-hidden`, and `aria-rowcount` / `aria-rowindex` continue to describe the
+whole dataset rather than the mounted window.
 
-Virtualization is skipped for the empty, error and loading states, and turns off entirely with `isVirtualized={false}`.
+Virtualization is skipped for the empty, error and loading states, and turns off
+entirely with `isVirtualized={false}`.
 
 ### Wrapping Cells
 
-Rows are **measured, not assumed**, so a column with `autoHeight` can wrap to a different number of lines per row and the virtualized window still tracks correctly.
+Rows are **measured, not assumed**, so a column with `autoHeight` can wrap to a
+different number of lines per row and the virtualized window still tracks
+correctly.
 
 ### Selection
 
@@ -543,9 +771,13 @@ const [keys, setKeys] = useState([]);
 />
 ```
 
-Selection is **keyed, not indexed**, so it survives sorting, searching and paging — the same row stays selected wherever it lands, and a row filtered out by a search keeps its key rather than being silently deselected.
+Selection is **keyed, not indexed**, so it survives sorting, searching and
+paging — the same row stays selected wherever it lands, and a row filtered out
+by a search keeps its key rather than being silently deselected.
 
-Shift-click a checkbox to extend the range from the last one you clicked plainly. Shift-clicking back toward the anchor shrinks the range rather than leaving the overshoot selected.
+Shift-click a checkbox to extend the range from the last one you clicked
+plainly. Shift-clicking back toward the anchor shrinks the range rather than
+leaving the overshoot selected.
 
 #### Three ways a row can be special
 
@@ -557,21 +789,30 @@ Deliberately distinct, and not interchangeable:
 | `isRowSelectable` | yes | yes | no |
 | `getRowProps().isDimmed` | yes | yes | **yes** — it is purely visual |
 
-`selectionTooltip` explains an inert checkbox, which is the difference between "this is broken" and "this row is still deploying".
+`selectionTooltip` explains an inert checkbox, which is the difference between
+"this is broken" and "this row is still deploying".
 
 #### What select-all reaches
 
 `selectAllMode` decides the scope of the header checkbox:
 
 - **`'page'`** (default) — the rows on the current page.
-- **`'filtered'`** — every row passing the current search or filter, across pages.
-- **`'all'`** — emits the `'all'` sentinel instead of a key list. This is the only mode that can mean rows the client has never loaded, so the consumer decides what it means for its query — usually a `DELETE … WHERE <filter>` rather than `WHERE id IN (…)`.
-
-Unselectable rows are excluded from every scope. Pressing the header checkbox while everything in scope is selected clears the **whole** selection, not just the scope — leaving keys selected on other pages behind an unchecked-looking box is how people delete things they did not mean to.
+- **`'filtered'`** — every row passing the current search or filter, across
+  pages.
+- **`'all'`** — emits the `'all'` sentinel instead of a key list. This is the
+  only mode that can mean rows the client has never loaded, so the consumer
+  decides what it means for its query — usually a `DELETE … WHERE <filter>`
+  rather than `WHERE id IN (…)`.
+
+Unselectable rows are excluded from every scope. Pressing the header checkbox
+while everything in scope is selected clears the **whole** selection, not just
+the scope — leaving keys selected on other pages behind an unchecked-looking box
+is how people delete things they did not mean to.
 
 ### Row Links and Row Actions
 
-`rowLink` turns the row-header cell into a stretched anchor covering the whole row:
+`rowLink` turns the row-header cell into a stretched anchor covering the whole
+row:
 
 ```jsx
 <ItemTable
@@ -581,15 +822,24 @@ Unselectable rows are excluded from every scope. Pressing the header checkbox wh
 />
 ```
 
-Because it is a real `<a href>`, ⌘-click, middle-click and "Open in new tab" all work natively — none of which an `onClick` handler can give you. The anchor sits below the cells' own content in the stacking order, so a button or `⋮` trigger inside a cell still takes its own clicks, and its accessible name comes from the row-header cell rather than being announced as "link".
+Because it is a real `<a href>`, ⌘-click, middle-click and "Open in new tab"
+all work natively — none of which an `onClick` handler can give you. The anchor
+sits below the cells' own content in the stacking order, so a button or `⋮`
+trigger inside a cell still takes its own clicks, and its accessible name comes
+from the row-header cell rather than being announced as "link".
 
-The row-header cell is styled as a link — `#purple-text` at weight 600, matching the kit's `Link`, with an underline while the row is hovered. The anchor itself is invisible, so without that the row would give no sign that it navigates.
+The row-header cell is styled as a link — `#purple-text` at weight 600, matching
+the kit's `Link`, with an underline while the row is hovered. The anchor itself
+is invisible, so without that the row would give no sign that it navigates.
 
-`onRowAction` is the non-navigational alternative — Enter, or a click that did not land on a control inside a cell. Use one or the other, not both.
+`onRowAction` is the non-navigational alternative — Enter, or a click that did
+not land on a control inside a cell. Use one or the other, not both.
 
 ### Row Menu
 
-`rowMenu` supplies `Menu.Item` children, and `rowContextMenu` decides where they are exposed. The split is deliberate: `rowMenu` alone renders nothing, so a row never grows a `⋮` nobody asked for.
+`rowMenu` supplies `Menu.Item` children, and `rowContextMenu` decides where they
+are exposed. The split is deliberate: `rowMenu` alone renders nothing, so a row
+never grows a `⋮` nobody asked for.
 
 ```jsx
 <ItemTable
@@ -606,17 +856,19 @@ The row-header cell is styled as a link — `#purple-text` at weight 600, matchi
 />
 ```
 
-| `rowContextMenu`  | `⋮` column | Right-click / Shift+F10 |
-| ----------------- | ---------- | ----------------------- |
-| `false` (default) | no         | no                      |
-| `true`            | yes        | yes                     |
-| `'context-only'`  | no         | yes                     |
+| `rowContextMenu` | `⋮` column | Right-click / Shift+F10 |
+| --- | --- | --- |
+| `false` (default) | no | no |
+| `true` | yes | yes |
+| `'context-only'` | no | yes |
 
-A row whose resolver returns `null` gets no trigger, and right-clicking it falls through to the browser's own context menu — more useful than an empty popover.
+A row whose resolver returns `null` gets no trigger, and right-clicking it falls
+through to the browser's own context menu — more useful than an empty popover.
 
 ### Bulk Actions
 
-`bulkActions` implies `selectionMode="multiple"` — a bulk action with no way to select rows is a contradiction, not a configuration.
+`bulkActions` implies `selectionMode="multiple"` — a bulk action with no way to
+select rows is a contradiction, not a configuration.
 
 ```jsx
 <ItemTable
@@ -643,13 +895,22 @@ A row whose resolver returns `null` gets no trigger, and right-clicking it falls
 />
 ```
 
-Each action drives its own spinner through `setLoading`, so one slow request does not freeze the others, and the selection clears when the action resolves. Opt out with `deselectAfter: false` for an action that only reads — the default exists because the rows an action just deleted or moved are usually gone.
+Each action drives its own spinner through `setLoading`, so one slow request
+does not freeze the others, and the selection clears when the action resolves.
+Opt out with `deselectAfter: false` for an action that only reads — the default
+exists because the rows an action just deleted or moved are usually gone.
 
-`bulkBarPlacement="floating"` (the default) centres the bar over the body without changing the table's height, so the rows never shift under the cursor. `"toolbar"` takes over the `actions` group instead, for a page whose toolbar is already crowded — the two compete for the same space, and while rows are selected the bulk actions are what the user is reaching for.
+`bulkBarPlacement="floating"` (the default) centres the bar over the body
+without changing the table's height, so the rows never shift under the cursor.
+`"toolbar"` takes over the `actions` group instead, for a page whose toolbar is
+already crowded — the two compete for the same space, and while rows are
+selected the bulk actions are what the user is reaching for.
 
 **Escape** clears the selection from anywhere inside the table.
 
-`ItemTable.BulkBar` is available as a compound member for placing the bar outside the default chrome; it reads the selection from context, so there is still exactly one owner.
+`ItemTable.BulkBar` is available as a compound member for placing the bar
+outside the default chrome; it reads the selection from context, so there is
+still exactly one owner.
 
 ### Reordering Rows
 
@@ -664,15 +925,22 @@ Each action drives its own spinner through `setLoading`, so one slow request doe
 />
 ```
 
-It is built on React Aria's collection drag-and-drop, through the same `DraggableCollection` wrapper `Tabs` and `ListBox` use — `RowCollection` and the table's own `SelectionManager` satisfy its contract unchanged.
+It is built on React Aria's collection drag-and-drop, through the same
+`DraggableCollection` wrapper `Tabs` and `ListBox` use — `RowCollection` and the
+table's own `SelectionManager` satisfy its contract unchanged.
 
-That buys the keyboard path as well as the pointer one: the grid takes a single tab stop, arrows move between rows, Enter picks a row up and drops it, Escape cancels. The drop line is drawn **on** the row rather than between rows, because a native table has nowhere to put an element between two `<tr>`s.
+That buys the keyboard path as well as the pointer one: the grid takes a single
+tab stop, arrows move between rows, Enter picks a row up and drops it, Escape
+cancels. The drop line is drawn **on** the row rather than between rows, because
+a native table has nowhere to put an element between two `<tr>`s.
 
-`onReorder` reports the whole key order rather than just the moved row, so the result can be persisted without reconstructing it.
+`onReorder` reports the whole key order rather than just the moved row, so the
+result can be persisted without reconstructing it.
 
 ### Dropping Rows onto a Row
 
-Some tables move rows _into_ other rows rather than around them — a workbook into a folder. `dropOnRow` covers that, and enables dragging on its own:
+Some tables move rows *into* other rows rather than around them — a workbook
+into a folder. `dropOnRow` covers that, and enables dragging on its own:
 
 ```jsx
 <ItemTable
@@ -686,11 +954,21 @@ Some tables move rows _into_ other rows rather than around them — a workbook i
 />
 ```
 
-This is a **different case from reordering**, and usually the only one a given table wants: Cloud's Workbooks page drags items into folders and never reorders them. The story below is that shape.
+This is a **different case from reordering**, and usually the only one a given
+table wants: Cloud's Workbooks page drags items into folders and never reorders
+them. The story below is that shape.
 
-They do compose if you need it — set `isReorderable` as well and a row that refuses a drop falls back to reordering — but that combination is rare. Cloud has to treat them as mutually exclusive because ag-grid cannot express both at once; that restriction does not carry over.
+They do compose if you need it — set `isReorderable` as well and a row that
+refuses a drop falls back to reordering — but that combination is rare. Cloud
+has to treat them as mutually exclusive because ag-grid cannot express both at
+once; that restriction does not carry over.
 
-`dropOnRow` replaces Cloud's `isDropOnRowEnabled`, `isDropTarget`, `isDropOnRowAllowed` and `onDropOnRow` with one object, and drops the two ag-grid workarounds beside them (`dropTargetRowKeyRef`, `dropTargetRefreshColumnKey`) that existed only because ag-grid cannot re-render a single cell from React state. Here the hovered row is just `ctx.isDropTarget`.
+`dropOnRow` replaces Cloud's `isDropOnRowEnabled`, `isDropTarget`,
+`isDropOnRowAllowed` and `onDropOnRow` with one object, and drops the two
+ag-grid workarounds beside them (`dropTargetRowKeyRef`,
+`dropTargetRefreshColumnKey`) that existed only because ag-grid cannot re-render
+a single cell from React state. Here the hovered row is just
+`ctx.isDropTarget`.
 
 ### Column Resize
 
@@ -700,25 +978,36 @@ They do compose if you need it — set `isReorderable` as well and a row that re
 <ItemTable isResizable storageKey="deployments" data={rows} columns={columns} />
 ```
 
-It is built on React Aria's `useMove` — the same hook behind `Board`'s widgets — so the handle takes **keyboard** input for free: focus it and use the arrow keys, or Home/End to jump to the column's minimum and maximum. Widths clamp to each column's `minWidth` / `maxWidth`, and a column opts out with `isResizable: false`.
+It is built on React Aria's `useMove` — the same hook behind `Board`'s widgets —
+so the handle takes **keyboard** input for free: focus it and use the arrow
+keys, or Home/End to jump to the column's minimum and maximum. Widths clamp to
+each column's `minWidth` / `maxWidth`, and a column opts out with
+`isResizable: false`.
 
-`onColumnResize` fires once the gesture ends rather than on every pixel, and `columnWidths` is in the default `persist` list, so pairing `isResizable` with `storageKey` makes a resized table come back the way the user left it.
+`onColumnResize` fires once the gesture ends rather than on every pixel, and
+`columnWidths` is in the default `persist` list, so pairing `isResizable` with
+`storageKey` makes a resized table come back the way the user left it.
 
 ### Persisting State
 
-`storageKey` remembers the parts of the table's state a user expects to survive a reload:
+`storageKey` remembers the parts of the table's state a user expects to survive
+a reload:
 
 ```jsx
 <ItemTable data={rows} columns={columns} storageKey="deployments" />
 ```
 
-Only state the **table** owns is stored, so a controlled `pageSize` or `sort` stays entirely the page's business. Sort is opt-in via `persist` — a stored sort silently changes what the first screen of a table means, which is rarely what you want by default:
+Only state the **table** owns is stored, so a controlled `pageSize` or `sort`
+stays entirely the page's business. Sort is opt-in via `persist` — a stored sort
+silently changes what the first screen of a table means, which is rarely what
+you want by default:
 
 ```jsx
 <ItemTable storageKey="deployments" persist={['pageSize', 'sort']} data={rows} columns={columns} />
 ```
 
-Reads and writes are best-effort: private mode, a disabled store, a quota error or a hand-edited value all degrade to "no persistence" rather than failing.
+Reads and writes are best-effort: private mode, a disabled store, a quota error
+or a hand-edited value all degrade to "no persistence" rather than failing.
 
 ### Per-row Visuals
 
@@ -735,32 +1024,46 @@ Reads and writes are best-effort: private mode, a disabled store, a quota error
 ### Screen Reader Support
 
 - The `<table>` carries `role="grid"` with `aria-rowcount` and `aria-colcount`.
-- Row and column indices are **1-based and document-absolute** — header rows are counted, and the indices stay truthful when rows are virtualized or columns are pinned.
-- A column marked `isRowHeader` renders `<th scope="row">`, so a screen reader announces the row by name when moving between cells.
+- Row and column indices are **1-based and document-absolute** — header rows are
+  counted, and the indices stay truthful when rows are virtualized or columns
+  are pinned.
+- A column marked `isRowHeader` renders `<th scope="row">`, so a screen reader
+  announces the row by name when moving between cells.
 - `aria-sort` is set on the sorted header only, never `"none"` on the rest.
-- `aria-busy` is set while loading; skeleton rows keep the full cell structure so nothing shifts when the data lands.
+- `aria-busy` is set while loading; skeleton rows keep the full cell structure so
+  nothing shifts when the data lands.
 
 ### ARIA Properties
 
-| Property                          | Applied to                     |
-| --------------------------------- | ------------------------------ |
-| `role="grid"`                     | the `<table>`                  |
-| `aria-rowcount` / `aria-colcount` | the `<table>`                  |
-| `aria-rowindex`                   | every `<tr>`                   |
-| `aria-colindex`                   | every cell and column header   |
-| `aria-sort`                       | the sorted column header       |
-| `aria-busy`                       | the grid and its skeleton rows |
+| Property | Applied to |
+| -------- | ---------- |
+| `role="grid"` | the `<table>` |
+| `aria-rowcount` / `aria-colcount` | the `<table>` |
+| `aria-rowindex` | every `<tr>` |
+| `aria-colindex` | every cell and column header |
+| `aria-sort` | the sorted column header |
+| `aria-busy` | the grid and its skeleton rows |
 
 ## Best Practices
 
-- Do: mark one column `isRowHeader`. It names the row for assistive tech and is where a row link will anchor.
-- Do: give a column `format` when its display text differs from its raw value — that is what keeps it sortable, searchable and copyable.
-- Do: bound the table's height. Without a bound it grows to fit, the header cannot stick, and virtualization has no viewport to work against.
-- Do: leave the header preset alone unless you have a reason. `c3` is what the Cloud list tables use, and the header `Item` inherits the cell's typography so overriding `headerPreset` restyles the whole header consistently.
-- Do: pass `isFiltered` when you filter `data` yourself, so the empty state says "no matches".
-- Don't: reach for `render` to reformat text. `format` does it in a way the rest of the table understands — including sorting and search.
-- Don't: filter `data` yourself _and_ leave `isFiltered` unset, or an empty result will read as "nothing exists".
-- Don't: put an `Item` in every cell. `Item` runs a hotkey subscription per instance; use `TextItem` (which the table does automatically for plain text) and reserve `Item` for the row-header cell.
+- Do: mark one column `isRowHeader`. It names the row for assistive tech and is
+  where a row link will anchor.
+- Do: give a column `format` when its display text differs from its raw value —
+  that is what keeps it sortable, searchable and copyable.
+- Do: bound the table's height. Without a bound it grows to fit, the header
+  cannot stick, and virtualization has no viewport to work against.
+- Do: leave the header preset alone unless you have a reason. `c3` is what the
+  Cloud list tables use, and the header `Item` inherits the cell's typography so
+  overriding `headerPreset` restyles the whole header consistently.
+- Do: pass `isFiltered` when you filter `data` yourself, so the empty state says
+  "no matches".
+- Don't: reach for `render` to reformat text. `format` does it in a way the rest
+  of the table understands — including sorting and search.
+- Don't: filter `data` yourself *and* leave `isFiltered` unset, or an empty
+  result will read as "nothing exists".
+- Don't: put an `Item` in every cell. `Item` runs a hotkey subscription per
+  instance; use `TextItem` (which the table does automatically for plain text)
+  and reserve `Item` for the row-header cell.
 
 ## Suggested Improvements