@box-kite/react 2.2.0 → 2.2.2

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

@@ -80,7 +80,7 @@ globs: '**/*.{ts,tsx,jsx}'
 
 46. **A scroll-driven animation is a timeline prop, and it costs no JavaScript at all.** `animationTimeline="scroll()"` runs an animation off the nearest scrollport's progress and `"view()"` off this element's own pass across it — no listener, no rAF, no state, and the browser drives it on the compositor. Where the scroller is not an ancestor, name one: `scrollTimeline="page block"` on the scroller (or `viewTimeline="card block"` on the subject), `animationTimeline="page"` on the animated element, and `timelineScope="page"` on their common ancestor when the two are not nested — the `--` on a name is optional and added for you, the axis is `block`/`inline`/`x`/`y` (logical, so it mirrors), and the longhands `scrollTimelineName`/`Axis` and `viewTimelineName`/`Axis` exist to override half a shorthand. **`animationRange` is which part of the pass the animation occupies**: `cover`, `contain`, `entry`, `exit`, `entry-crossing`, `exit-crossing`, each taking an offset — `animationRange="entry 0% entry 50%"`, or the `animationRangeStart`/`animationRangeEnd` pair — and `viewTimelineInset` shrinks the scrollport the pass is measured against, which is how a reveal fires before the element really reaches the edge. **Three traps.** The CSS `animation` shorthand **resets `animation-timeline`**, so a timeline declared before it is silently undone; the registry's order settles that for the props, but not for an `animation` written inside `css`. A scroll-driven animation has **no duration**, so `--transitionTime` cannot zero it and it is the one motion here that does _not_ stop itself under `prefers-reduced-motion` — `motionReduce={{ animation: 'none' }}` is the opt-in, and it is not optional. And where the browser has none (Safari, and Firefox behind a flag) the declaration is dropped rather than the animation: it runs on the **document timeline** over whatever duration it was given, so make the end state the resting state and a missing timeline degrades to "already arrived" instead of a loop.
 
-47. **A view transition is two props and one call.** `Box.viewTransition(() => applyChange())` runs a DOM change inside `document.startViewTransition` where the browser has one and plainly where it has not — the same `ready`/`finished`/`updateCallbackDone` promises and `skip()` either way, so a caller has one code path rather than two — and `viewTransitionName="header"` is what makes an element animate _from where it was to where it is_ instead of being cross-faded along with the page. `viewTransitionClass="card"` groups several names, so `::view-transition-group(.card)` styles them at once. **In React the update has to be flushed**: the browser screenshots the page the moment the callback returns and a `setState` has not rendered by then, so a hand-rolled version captures the old state twice and nothing appears to move — write `Box.viewTransition(() => flushSync(() => setTheme('dark')))`, or use **`<Box.Theme viewTransition>`**, which is that call for the one change every app has. **A name has to be unique in the document while the transition runs**, so a list wants a name per item — and a class per item is a rule this library would never free, which is why that one goes in `props={{ style: { viewTransitionName: id } }}`, the exception `useAnchorPosition`'s anchor name and a `Slider` thumb already take. Reduced motion **skips** the transition by default and keeps the update, a whole-page cross-fade being exactly the motion the preference is about; `{ reducedMotion: 'play' }` is the opt-out, and `{ types: ['forward'] }` is what `:active-view-transition-type()` selects on.
+47. **A view transition is two props and one call.** `Box.viewTransition(() => applyChange())` runs a DOM change inside `document.startViewTransition` where the browser has one and plainly where it has not — the same `ready`/`finished`/`updateCallbackDone` promises and `skip()` either way, so a caller has one code path rather than two — and `viewTransitionName="header"` is what makes an element animate _from where it was to where it is_ instead of being cross-faded along with the page. `viewTransitionClass="card"` groups several names, so `::view-transition-group(.card)` styles them at once. **In React the update has to be flushed**: the browser screenshots the page the moment the callback returns and a `setState` has not rendered by then, so a hand-rolled version captures the old state twice and nothing appears to move — write `Box.viewTransition(() => flushSync(() => setTheme('dark')))`, or use **`<Box.Theme viewTransition>`**, which is that call for the one change every app has — `viewTransition="reveal"` grows the new theme out of the control that was pressed as a circle instead of cross-fading. **A theme change pauses every CSS transition** until it has painted (and until the view transition has finished), because `color` is inherited and the base class transitions `all`, so each element would otherwise start one of its own; the view transition is the animation, and it costs the same on any size of page. **A name has to be unique in the document while the transition runs**, so a list wants a name per item — and a class per item is a rule this library would never free, which is why that one goes in `props={{ style: { viewTransitionName: id } }}`, the exception `useAnchorPosition`'s anchor name and a `Slider` thumb already take. Reduced motion **skips** the transition by default and keeps the update, a whole-page cross-fade being exactly the motion the preference is about; `{ reducedMotion: 'play' }` is the opt-out, and `{ types: ['forward'] }` is what `:active-view-transition-type()` selects on.
 
 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.
 

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

@@ -153,7 +153,7 @@ Detect the package manager from the lock file rather than asking:
 
 46. **A scroll-driven animation is a timeline prop, and it costs no JavaScript at all.** `animationTimeline="scroll()"` runs an animation off the nearest scrollport's progress and `"view()"` off this element's own pass across it — no listener, no rAF, no state, and the browser drives it on the compositor. Where the scroller is not an ancestor, name one: `scrollTimeline="page block"` on the scroller (or `viewTimeline="card block"` on the subject), `animationTimeline="page"` on the animated element, and `timelineScope="page"` on their common ancestor when the two are not nested — the `--` on a name is optional and added for you, the axis is `block`/`inline`/`x`/`y` (logical, so it mirrors), and the longhands `scrollTimelineName`/`Axis` and `viewTimelineName`/`Axis` exist to override half a shorthand. **`animationRange` is which part of the pass the animation occupies**: `cover`, `contain`, `entry`, `exit`, `entry-crossing`, `exit-crossing`, each taking an offset — `animationRange="entry 0% entry 50%"`, or the `animationRangeStart`/`animationRangeEnd` pair — and `viewTimelineInset` shrinks the scrollport the pass is measured against, which is how a reveal fires before the element really reaches the edge. **Three traps.** The CSS `animation` shorthand **resets `animation-timeline`**, so a timeline declared before it is silently undone; the registry's order settles that for the props, but not for an `animation` written inside `css`. A scroll-driven animation has **no duration**, so `--transitionTime` cannot zero it and it is the one motion here that does _not_ stop itself under `prefers-reduced-motion` — `motionReduce={{ animation: 'none' }}` is the opt-in, and it is not optional. And where the browser has none (Safari, and Firefox behind a flag) the declaration is dropped rather than the animation: it runs on the **document timeline** over whatever duration it was given, so make the end state the resting state and a missing timeline degrades to "already arrived" instead of a loop.
 
-47. **A view transition is two props and one call.** `Box.viewTransition(() => applyChange())` runs a DOM change inside `document.startViewTransition` where the browser has one and plainly where it has not — the same `ready`/`finished`/`updateCallbackDone` promises and `skip()` either way, so a caller has one code path rather than two — and `viewTransitionName="header"` is what makes an element animate _from where it was to where it is_ instead of being cross-faded along with the page. `viewTransitionClass="card"` groups several names, so `::view-transition-group(.card)` styles them at once. **In React the update has to be flushed**: the browser screenshots the page the moment the callback returns and a `setState` has not rendered by then, so a hand-rolled version captures the old state twice and nothing appears to move — write `Box.viewTransition(() => flushSync(() => setTheme('dark')))`, or use **`<Box.Theme viewTransition>`**, which is that call for the one change every app has. **A name has to be unique in the document while the transition runs**, so a list wants a name per item — and a class per item is a rule this library would never free, which is why that one goes in `props={{ style: { viewTransitionName: id } }}`, the exception `useAnchorPosition`'s anchor name and a `Slider` thumb already take. Reduced motion **skips** the transition by default and keeps the update, a whole-page cross-fade being exactly the motion the preference is about; `{ reducedMotion: 'play' }` is the opt-out, and `{ types: ['forward'] }` is what `:active-view-transition-type()` selects on.
+47. **A view transition is two props and one call.** `Box.viewTransition(() => applyChange())` runs a DOM change inside `document.startViewTransition` where the browser has one and plainly where it has not — the same `ready`/`finished`/`updateCallbackDone` promises and `skip()` either way, so a caller has one code path rather than two — and `viewTransitionName="header"` is what makes an element animate _from where it was to where it is_ instead of being cross-faded along with the page. `viewTransitionClass="card"` groups several names, so `::view-transition-group(.card)` styles them at once. **In React the update has to be flushed**: the browser screenshots the page the moment the callback returns and a `setState` has not rendered by then, so a hand-rolled version captures the old state twice and nothing appears to move — write `Box.viewTransition(() => flushSync(() => setTheme('dark')))`, or use **`<Box.Theme viewTransition>`**, which is that call for the one change every app has — `viewTransition="reveal"` grows the new theme out of the control that was pressed as a circle instead of cross-fading. **A theme change pauses every CSS transition** until it has painted (and until the view transition has finished), because `color` is inherited and the base class transitions `all`, so each element would otherwise start one of its own; the view transition is the animation, and it costs the same on any size of page. **A name has to be unique in the document while the transition runs**, so a list wants a name per item — and a class per item is a rule this library would never free, which is why that one goes in `props={{ style: { viewTransitionName: id } }}`, the exception `useAnchorPosition`'s anchor name and a `Slider` thumb already take. Reduced motion **skips** the transition by default and keeps the update, a whole-page cross-fade being exactly the motion the preference is about; `{ reducedMotion: 'play' }` is the opt-out, and `{ types: ['forward'] }` is what `:active-view-transition-type()` selects on.
 
 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.
 

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

@@ -229,12 +229,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? }`), `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'`), `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), `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).
 
 **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 all of them. 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.
+**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`), `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`, `bottomBar` > (`info`, `clearFilters`, `pagination` > `button`|`info`).

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

@@ -107,7 +107,8 @@ while the transition runs) and `viewTransitionClass` (a shared name, so `::view-
 `Box.viewTransition(update, { reducedMotion, types })` around the change itself: it feature-detects, hands back the same
 `ready`/`finished`/`updateCallbackDone`/`skip()` handle whether or not a transition ran, and **skips under reduced motion while still
 applying the update**. In React the update must be flushed inside the callback — `Box.viewTransition(() => flushSync(() => setTab(next)))` —
-or the screenshot catches the old state twice; `<Box.Theme viewTransition>` is that already done for a theme switch. A name _per list item_
+or the screenshot catches the old state twice; `<Box.Theme viewTransition>` is that already done for a theme switch (`viewTransition="reveal"`
+grows the new theme out of the pressed control instead), and a theme switch pauses every CSS transition while it is applied. A name _per list item_
 is a rule per item that is never freed, so that one belongs in `props={{ style: { viewTransitionName: id } }}`.
 
 **Gradients**: `bgGradient` — a gradient as a _value_, written as a record, so its stops are palette tokens and it is

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

@@ -88,7 +88,7 @@ This library is not in your training data: it was renamed at 1.0.0 (September 20
 
 46. **A scroll-driven animation is a timeline prop, and it costs no JavaScript at all.** `animationTimeline="scroll()"` runs an animation off the nearest scrollport's progress and `"view()"` off this element's own pass across it — no listener, no rAF, no state, and the browser drives it on the compositor. Where the scroller is not an ancestor, name one: `scrollTimeline="page block"` on the scroller (or `viewTimeline="card block"` on the subject), `animationTimeline="page"` on the animated element, and `timelineScope="page"` on their common ancestor when the two are not nested — the `--` on a name is optional and added for you, the axis is `block`/`inline`/`x`/`y` (logical, so it mirrors), and the longhands `scrollTimelineName`/`Axis` and `viewTimelineName`/`Axis` exist to override half a shorthand. **`animationRange` is which part of the pass the animation occupies**: `cover`, `contain`, `entry`, `exit`, `entry-crossing`, `exit-crossing`, each taking an offset — `animationRange="entry 0% entry 50%"`, or the `animationRangeStart`/`animationRangeEnd` pair — and `viewTimelineInset` shrinks the scrollport the pass is measured against, which is how a reveal fires before the element really reaches the edge. **Three traps.** The CSS `animation` shorthand **resets `animation-timeline`**, so a timeline declared before it is silently undone; the registry's order settles that for the props, but not for an `animation` written inside `css`. A scroll-driven animation has **no duration**, so `--transitionTime` cannot zero it and it is the one motion here that does _not_ stop itself under `prefers-reduced-motion` — `motionReduce={{ animation: 'none' }}` is the opt-in, and it is not optional. And where the browser has none (Safari, and Firefox behind a flag) the declaration is dropped rather than the animation: it runs on the **document timeline** over whatever duration it was given, so make the end state the resting state and a missing timeline degrades to "already arrived" instead of a loop.
 
-47. **A view transition is two props and one call.** `Box.viewTransition(() => applyChange())` runs a DOM change inside `document.startViewTransition` where the browser has one and plainly where it has not — the same `ready`/`finished`/`updateCallbackDone` promises and `skip()` either way, so a caller has one code path rather than two — and `viewTransitionName="header"` is what makes an element animate _from where it was to where it is_ instead of being cross-faded along with the page. `viewTransitionClass="card"` groups several names, so `::view-transition-group(.card)` styles them at once. **In React the update has to be flushed**: the browser screenshots the page the moment the callback returns and a `setState` has not rendered by then, so a hand-rolled version captures the old state twice and nothing appears to move — write `Box.viewTransition(() => flushSync(() => setTheme('dark')))`, or use **`<Box.Theme viewTransition>`**, which is that call for the one change every app has. **A name has to be unique in the document while the transition runs**, so a list wants a name per item — and a class per item is a rule this library would never free, which is why that one goes in `props={{ style: { viewTransitionName: id } }}`, the exception `useAnchorPosition`'s anchor name and a `Slider` thumb already take. Reduced motion **skips** the transition by default and keeps the update, a whole-page cross-fade being exactly the motion the preference is about; `{ reducedMotion: 'play' }` is the opt-out, and `{ types: ['forward'] }` is what `:active-view-transition-type()` selects on.
+47. **A view transition is two props and one call.** `Box.viewTransition(() => applyChange())` runs a DOM change inside `document.startViewTransition` where the browser has one and plainly where it has not — the same `ready`/`finished`/`updateCallbackDone` promises and `skip()` either way, so a caller has one code path rather than two — and `viewTransitionName="header"` is what makes an element animate _from where it was to where it is_ instead of being cross-faded along with the page. `viewTransitionClass="card"` groups several names, so `::view-transition-group(.card)` styles them at once. **In React the update has to be flushed**: the browser screenshots the page the moment the callback returns and a `setState` has not rendered by then, so a hand-rolled version captures the old state twice and nothing appears to move — write `Box.viewTransition(() => flushSync(() => setTheme('dark')))`, or use **`<Box.Theme viewTransition>`**, which is that call for the one change every app has — `viewTransition="reveal"` grows the new theme out of the control that was pressed as a circle instead of cross-fading. **A theme change pauses every CSS transition** until it has painted (and until the view transition has finished), because `color` is inherited and the base class transitions `all`, so each element would otherwise start one of its own; the view transition is the animation, and it costs the same on any size of page. **A name has to be unique in the document while the transition runs**, so a list wants a name per item — and a class per item is a rule this library would never free, which is why that one goes in `props={{ style: { viewTransitionName: id } }}`, the exception `useAnchorPosition`'s anchor name and a `Slider` thumb already take. Reduced motion **skips** the transition by default and keeps the update, a whole-page cross-fade being exactly the motion the preference is about; `{ reducedMotion: 'play' }` is the opt-out, and `{ types: ['forward'] }` is what `:active-view-transition-type()` selects on.
 
 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.
 

package/AGENTS.md

@@ -120,7 +120,7 @@ Every value there is a prop, and every prop value becomes one class the engine i
 
 46. **A scroll-driven animation is a timeline prop, and it costs no JavaScript at all.** `animationTimeline="scroll()"` runs an animation off the nearest scrollport's progress and `"view()"` off this element's own pass across it — no listener, no rAF, no state, and the browser drives it on the compositor. Where the scroller is not an ancestor, name one: `scrollTimeline="page block"` on the scroller (or `viewTimeline="card block"` on the subject), `animationTimeline="page"` on the animated element, and `timelineScope="page"` on their common ancestor when the two are not nested — the `--` on a name is optional and added for you, the axis is `block`/`inline`/`x`/`y` (logical, so it mirrors), and the longhands `scrollTimelineName`/`Axis` and `viewTimelineName`/`Axis` exist to override half a shorthand. **`animationRange` is which part of the pass the animation occupies**: `cover`, `contain`, `entry`, `exit`, `entry-crossing`, `exit-crossing`, each taking an offset — `animationRange="entry 0% entry 50%"`, or the `animationRangeStart`/`animationRangeEnd` pair — and `viewTimelineInset` shrinks the scrollport the pass is measured against, which is how a reveal fires before the element really reaches the edge. **Three traps.** The CSS `animation` shorthand **resets `animation-timeline`**, so a timeline declared before it is silently undone; the registry's order settles that for the props, but not for an `animation` written inside `css`. A scroll-driven animation has **no duration**, so `--transitionTime` cannot zero it and it is the one motion here that does _not_ stop itself under `prefers-reduced-motion` — `motionReduce={{ animation: 'none' }}` is the opt-in, and it is not optional. And where the browser has none (Safari, and Firefox behind a flag) the declaration is dropped rather than the animation: it runs on the **document timeline** over whatever duration it was given, so make the end state the resting state and a missing timeline degrades to "already arrived" instead of a loop.
 
-47. **A view transition is two props and one call.** `Box.viewTransition(() => applyChange())` runs a DOM change inside `document.startViewTransition` where the browser has one and plainly where it has not — the same `ready`/`finished`/`updateCallbackDone` promises and `skip()` either way, so a caller has one code path rather than two — and `viewTransitionName="header"` is what makes an element animate _from where it was to where it is_ instead of being cross-faded along with the page. `viewTransitionClass="card"` groups several names, so `::view-transition-group(.card)` styles them at once. **In React the update has to be flushed**: the browser screenshots the page the moment the callback returns and a `setState` has not rendered by then, so a hand-rolled version captures the old state twice and nothing appears to move — write `Box.viewTransition(() => flushSync(() => setTheme('dark')))`, or use **`<Box.Theme viewTransition>`**, which is that call for the one change every app has. **A name has to be unique in the document while the transition runs**, so a list wants a name per item — and a class per item is a rule this library would never free, which is why that one goes in `props={{ style: { viewTransitionName: id } }}`, the exception `useAnchorPosition`'s anchor name and a `Slider` thumb already take. Reduced motion **skips** the transition by default and keeps the update, a whole-page cross-fade being exactly the motion the preference is about; `{ reducedMotion: 'play' }` is the opt-out, and `{ types: ['forward'] }` is what `:active-view-transition-type()` selects on.
+47. **A view transition is two props and one call.** `Box.viewTransition(() => applyChange())` runs a DOM change inside `document.startViewTransition` where the browser has one and plainly where it has not — the same `ready`/`finished`/`updateCallbackDone` promises and `skip()` either way, so a caller has one code path rather than two — and `viewTransitionName="header"` is what makes an element animate _from where it was to where it is_ instead of being cross-faded along with the page. `viewTransitionClass="card"` groups several names, so `::view-transition-group(.card)` styles them at once. **In React the update has to be flushed**: the browser screenshots the page the moment the callback returns and a `setState` has not rendered by then, so a hand-rolled version captures the old state twice and nothing appears to move — write `Box.viewTransition(() => flushSync(() => setTheme('dark')))`, or use **`<Box.Theme viewTransition>`**, which is that call for the one change every app has — `viewTransition="reveal"` grows the new theme out of the control that was pressed as a circle instead of cross-fading. **A theme change pauses every CSS transition** until it has painted (and until the view transition has finished), because `color` is inherited and the base class transitions `all`, so each element would otherwise start one of its own; the view transition is the animation, and it costs the same on any size of page. **A name has to be unique in the document while the transition runs**, so a list wants a name per item — and a class per item is a rule this library would never free, which is why that one goes in `props={{ style: { viewTransitionName: id } }}`, the exception `useAnchorPosition`'s anchor name and a `Slider` thumb already take. Reduced motion **skips** the transition by default and keeps the update, a whole-page cross-fade being exactly the motion the preference is about; `{ reducedMotion: 'play' }` is the opt-out, and `{ types: ['forward'] }` is what `:active-view-transition-type()` selects on.
 
 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.
 

package/BOX_AI_CONTEXT.md

@@ -726,7 +726,7 @@ so a change that was a jump becomes a transition with nothing animated by hand.
 | `viewTransitionName`                  | Names this element, so it animates _from where it was to where it is_ instead of being cross-faded with the page. A `<custom-ident>`, **not** dashed |
 | `viewTransitionClass`                 | A name shared by several elements, so `::view-transition-group(.card)` styles them together. Space-separated for more than one                       |
 | `Box.viewTransition(update, options)` | Runs `update` inside `document.startViewTransition` where the browser has one, and plainly where it has not                                          |
-| `<Box.Theme viewTransition>`          | That call around a theme change, `flushSync` included                                                                                                |
+| `<Box.Theme viewTransition>`          | That call around a theme change, `flushSync` included. `viewTransition="reveal"` grows the new theme out of the pressed control as a circle          |
 
 ```tsx
 const handle = Box.viewTransition(() => flushSync(() => setTab(next)), { types: ['forward'] });
@@ -756,7 +756,9 @@ interface ViewTransitionHandle {
 - **In React the update has to be flushed.** The browser takes its second screenshot the moment the
   callback returns, and a `setState` has not rendered by then — so a hand-rolled version captures the old
   state twice and nothing appears to move. `flushSync` inside the callback is the fix, and
-  `<Box.Theme viewTransition>` is it already done for the one change every app has.
+  `<Box.Theme viewTransition>` is it already done for the one change every app has. A theme change also
+  pauses every CSS transition until the new theme has painted (and the view transition has finished) — `color` is inherited and every Box transitions
+  `all`, so each element would start one of its own — which leaves the view transition as the only animation.
 - **A name has to be unique in the document while the transition runs.** Two elements sharing one is how a
   transition silently does nothing. The prop is for the handful of names a layout has (`header`, `main`);
   a name **per list item** is a rule per item that is never freed, so that one goes in
@@ -2365,34 +2367,36 @@ named ones carry the reason.
 
 ### GridDefinition
 
-| Prop                      | Type                                  | Default     | Description                                                                                                    |
-| ------------------------- | ------------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------- |
-| `columns`                 | `ColumnType[]`                        | required    | Column definitions                                                                                             |
-| `rowKey`                  | `keyof TRow \| (row) => Key`          | auto        | Unique row identifier                                                                                          |
-| `rowHeight`               | `number`                              | `48`        | Row height in px                                                                                               |
-| `visibleRowsCount`        | `number \| 'all'`                     | `10`        | Visible rows. `'all'` disables virtualization                                                                  |
-| `showRowNumber`           | `boolean \| { pinned?, width? }`      | `false`     | Row number column                                                                                              |
-| `rowSelection`            | `boolean \| { pinned? }`              | `false`     | Checkbox selection column                                                                                      |
-| `rowDetail`               | `RowDetailConfig`                     | —           | Expandable detail panel (see below)                                                                            |
-| `treeData`                | `TreeDataConfig`                      | —           | Rows that hold rows: a `treegrid` with a chevron column (see below)                                            |
-| `groupBy`                 | `Key[]`                               | —           | The columns the grid starts grouped by, outermost first. The column menu takes it from there                   |
-| `groupDefaultExpanded`    | `boolean \| number`                   | `false`     | Which group rows start open: `true` for all, a number for how many levels down                                 |
-| `editable`                | `boolean`                             | `false`     | Whether every column can be edited. A column’s own `editable` takes priority                                   |
-| `onCellEdit`              | `(edit) => void \| boolean \| string` | —           | Judges an edit and is told about it: nothing accepts, a string refuses. May be async                           |
-| `dataSource`              | `DataSource`                          | —           | The grid fetches its own rows a block at a time; `data` is not read at all                                     |
-| `pagination`              | `{ totalCount, pageSize? }`           | —           | Server-side pagination. Bypasses client-side filtering                                                         |
-| `topBar` / `bottomBar`    | `boolean`                             | `false`     | Show top/bottom bars                                                                                           |
-| `title` / `topBarContent` | `ReactNode`                           | —           | Top bar content                                                                                                |
-| `globalFilter`            | `boolean`                             | `false`     | Enable global fuzzy search                                                                                     |
-| `globalFilterKeys`        | `(keyof TRow)[]`                      | all         | Limit global filter columns                                                                                    |
-| `sortable` / `resizable`  | `boolean`                             | `true`      | Enable sorting/resizing for all columns                                                                        |
-| `contextMenu`             | `boolean \| ContextMenuConfig`        | `true`      | Control column header context menu. `false` hides it. Object: `{ sort?, pin?, group? }`                        |
-| `resizerStyle`            | `'visible' \| 'hover' \| 'hidden'`    | `'visible'` | Resizer handle visibility. `'hover'`: shows on header cell hover. `'hidden'`: invisible but resize still works |
-| `noDataComponent`         | `ReactNode`                           | `'empty'`   | Custom empty state                                                                                             |
-| `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                         |
-| `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)       |
+| Prop                      | Type                                  | Default     | Description                                                                                                                                                                                                            |
+| ------------------------- | ------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `columns`                 | `ColumnType[]`                        | required    | Column definitions                                                                                                                                                                                                     |
+| `rowKey`                  | `keyof TRow \| (row) => Key`          | auto        | Unique row identifier                                                                                                                                                                                                  |
+| `rowHeight`               | `number`                              | `48`        | Row height in px                                                                                                                                                                                                       |
+| `visibleRowsCount`        | `number \| 'all'`                     | `10`        | Visible rows. `'all'` disables virtualization                                                                                                                                                                          |
+| `showRowNumber`           | `boolean \| { pinned?, width? }`      | `false`     | Row number column                                                                                                                                                                                                      |
+| `rowSelection`            | `boolean \| { pinned? }`              | `false`     | Checkbox selection column. The header checkbox acts on the rows the filters leave on screen; a filter never drops a selection, and the bottom bar counts what it hides, with **Show selected** and **Clear selection** |
+| `rowDetail`               | `RowDetailConfig`                     | —           | Expandable detail panel (see below)                                                                                                                                                                                    |
+| `treeData`                | `TreeDataConfig`                      | —           | Rows that hold rows: a `treegrid` with a chevron column (see below)                                                                                                                                                    |
+| `groupBy`                 | `Key[]`                               | —           | The columns the grid starts grouped by, outermost first. The column menu takes it from there                                                                                                                           |
+| `groupDefaultExpanded`    | `boolean \| number`                   | `false`     | Which group rows start open: `true` for all, a number for how many levels down                                                                                                                                         |
+| `editable`                | `boolean`                             | `false`     | Whether every column can be edited. A column’s own `editable` takes priority                                                                                                                                           |
+| `onCellEdit`              | `(edit) => void \| boolean \| string` | —           | Judges an edit and is told about it: nothing accepts, a string refuses. May be async                                                                                                                                   |
+| `dataSource`              | `DataSource`                          | —           | The grid fetches its own rows a block at a time; `data` is not read at all                                                                                                                                             |
+| `pagination`              | `{ totalCount, pageSize? }`           | —           | Server-side pagination. Bypasses client-side filtering                                                                                                                                                                 |
+| `topBar` / `bottomBar`    | `boolean`                             | `false`     | Show top/bottom bars                                                                                                                                                                                                   |
+| `title` / `topBarContent` | `ReactNode`                           | —           | Top bar content                                                                                                                                                                                                        |
+| `globalFilter`            | `boolean`                             | `false`     | Enable global fuzzy search                                                                                                                                                                                             |
+| `globalFilterKeys`        | `(keyof TRow)[]`                      | all         | Limit global filter columns                                                                                                                                                                                            |
+| `sortable` / `resizable`  | `boolean`                             | `true`      | Enable sorting/resizing for all columns                                                                                                                                                                                |
+| `contextMenu`             | `boolean \| ContextMenuConfig`        | `true`      | Control column header context menu. `false` hides it. Object: `{ sort?, pin?, group? }`                                                                                                                                |
+| `resizerStyle`            | `'visible' \| 'hover' \| 'hidden'`    | `'visible'` | Resizer handle visibility. `'hover'`: shows on header cell hover. `'hidden'`: invisible but resize still works                                                                                                         |
+| `headerHover`             | `'static' \| 'sliding'`               | `'static'`  | Header hover: an inset pill per sortable cell, or one pill that flows from cell to cell. Whole cell sorts on press                                                                                                     |
+| `localeText`              | `Partial<DataGridLocaleText>`         | English     | Every word the grid writes — labels, accessible names, announcements, messages. Values with a number or a name in them are functions; spread `DATA_GRID_LOCALE_TEXT` to start a translation                            |
+| `noDataComponent`         | `ReactNode`                           | `'empty'`   | Custom empty state                                                                                                                                                                                                     |
+| `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                                                                                                                                 |
+| `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
 
@@ -2404,7 +2408,7 @@ named ones carry the reason.
 | `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 }`                                                                                         |
+| `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? }`                                                            |
@@ -2787,52 +2791,66 @@ stops, as they were before A7.
 
 ### Component Style Tree
 
-| Component Name                                            | Description                                      | Variants                                                                                                                                                                                                               |
-| --------------------------------------------------------- | ------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `datagrid`                                                | Root container                                   | —                                                                                                                                                                                                                      |
-| `datagrid.content`                                        | Scroll container for header + body               | —                                                                                                                                                                                                                      |
-| `datagrid.topBar`                                         | Top bar (title, filters, column groups)          | —                                                                                                                                                                                                                      |
-| `datagrid.topBar.globalFilter`                            | Global search wrapper                            | —                                                                                                                                                                                                                      |
-| `datagrid.topBar.globalFilter.stats`                      | Filtered rows count badge                        | —                                                                                                                                                                                                                      |
-| `datagrid.topBar.columnGroups`                            | Column group chips container                     | —                                                                                                                                                                                                                      |
-| `datagrid.topBar.columnGroups.icon`                       | Column group icon                                | —                                                                                                                                                                                                                      |
-| `datagrid.topBar.columnGroups.separator`                  | Separator between groups                         | —                                                                                                                                                                                                                      |
-| `datagrid.topBar.columnGroups.item`                       | Column group chip                                | —                                                                                                                                                                                                                      |
-| `datagrid.topBar.columnGroups.item.icon`                  | Remove icon on chip                              | —                                                                                                                                                                                                                      |
-| `datagrid.topBar.columnVisibility`                        | Column visibility dropdown                       | —                                                                                                                                                                                                                      |
-| `datagrid.topBar.columnVisibility.badge`                  | Hidden columns count badge                       | —                                                                                                                                                                                                                      |
-| `datagrid.filter.cell`                                    | Filter row cell                                  | `isPinned`, `isFirstLeftPinned`, `isLastLeftPinned`, `isFirstRightPinned`, `isLastRightPinned`                                                                                                                         |
-| `datagrid.filter.cell.input`                              | Filter input container (text/number/multiselect) | —                                                                                                                                                                                                                      |
-| `datagrid.header`                                         | Header grid container (sticky)                   | —                                                                                                                                                                                                                      |
-| `datagrid.header.cell`                                    | Header cell                                      | `isPinned`, `isFirstLeftPinned`, `isLastLeftPinned`, `isFirstRightPinned`, `isLastRightPinned`, `isSortable`, `isRowSelection`, `isRowNumber`, `isFirstLeaf`, `isLastLeaf`, `isEmptyCell`                              |
-| `datagrid.header.cell.contextMenu`                        | Column context menu button                       | —                                                                                                                                                                                                                      |
-| `datagrid.header.cell.contextMenu.icon`                   | Context menu icon                                | —                                                                                                                                                                                                                      |
-| `datagrid.header.cell.contextMenu.tooltip`                | Context menu popup                               | —                                                                                                                                                                                                                      |
-| `datagrid.header.cell.contextMenu.tooltip.item`           | Context menu action                              | —                                                                                                                                                                                                                      |
-| `datagrid.header.cell.contextMenu.tooltip.item.icon`      | Action icon                                      | —                                                                                                                                                                                                                      |
-| `datagrid.header.cell.contextMenu.tooltip.item.separator` | Menu separator line                              | —                                                                                                                                                                                                                      |
-| `datagrid.header.cell.resizer`                            | Column resize handle                             | —                                                                                                                                                                                                                      |
-| `datagrid.body`                                           | Body grid container (virtualized rows)           | —                                                                                                                                                                                                                      |
-| `datagrid.body.cell`                                      | Body cell                                        | `isPinned`, `isFirstLeftPinned`, `isLastLeftPinned`, `isFirstRightPinned`, `isLastRightPinned`, `isRowNumber`, `isRowSelection`, `isRowSelected`, `isFirstLeaf`, `isLastLeaf`, `isEmptyCell`, `isEditing`, `isInvalid` |
-| `datagrid.body.cell.text`                                 | Default cell text renderer                       | —                                                                                                                                                                                                                      |
-| `datagrid.body.cell.editor`                               | The open cell editor                             | `isPending`                                                                                                                                                                                                            |
-| `datagrid.body.cell.error`                                | What a refused value says, in the top layer      | —                                                                                                                                                                                                                      |
-| `datagrid.body.cell.rowDetail`                            | Row detail expand/collapse button                | —                                                                                                                                                                                                                      |
-| `datagrid.body.cell.tree`                                 | Tree cell: the indent, the chevron and the value | —                                                                                                                                                                                                                      |
-| `datagrid.body.cell.tree.toggle`                          | Tree expand/collapse chevron                     | `isExpanded`                                                                                                                                                                                                           |
-| `datagrid.body.cell.tree.spacer`                          | What a leaf puts where its chevron would be      | —                                                                                                                                                                                                                      |
-| `datagrid.body.row`                                       | Data row (display: contents)                     | —                                                                                                                                                                                                                      |
-| `datagrid.body.groupRow`                                  | Group row (display: contents)                    | —                                                                                                                                                                                                                      |
-| `datagrid.body.groupRow.expandButton`                     | Group expand/collapse button                     | —                                                                                                                                                                                                                      |
-| `datagrid.body.detailRow`                                 | Expanded detail row                              | —                                                                                                                                                                                                                      |
-| `datagrid.body.empty`                                     | Empty state container                            | —                                                                                                                                                                                                                      |
-| `datagrid.emptyColumns`                                   | No columns selected placeholder                  | —                                                                                                                                                                                                                      |
-| `datagrid.bottomBar`                                      | Bottom bar (row count, pagination)               | —                                                                                                                                                                                                                      |
-| `datagrid.bottomBar.info`                                 | Status text ("Rows: ...", "Selected: ...")       | —                                                                                                                                                                                                                      |
-| `datagrid.bottomBar.clearFilters`                         | "Clear filters" link                             | —                                                                                                                                                                                                                      |
-| `datagrid.bottomBar.pagination`                           | Pagination controls wrapper                      | —                                                                                                                                                                                                                      |
-| `datagrid.bottomBar.pagination.button`                    | Pagination nav button                            | —                                                                                                                                                                                                                      |
-| `datagrid.bottomBar.pagination.info`                      | Page info text ("1 of 5")                        | —                                                                                                                                                                                                                      |
+| Component Name                                            | Description                                               | Variants                                                                                                                                                                                                               |
+| --------------------------------------------------------- | --------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `datagrid`                                                | Root container                                            | —                                                                                                                                                                                                                      |
+| `datagrid.content`                                        | Scroll container for header + body                        | —                                                                                                                                                                                                                      |
+| `datagrid.topBar`                                         | Top bar (title, filters, column groups)                   | —                                                                                                                                                                                                                      |
+| `datagrid.topBar.globalFilter`                            | Global search wrapper                                     | —                                                                                                                                                                                                                      |
+| `datagrid.topBar.globalFilter.stats`                      | Filtered rows count badge (only without a bottom bar)     | —                                                                                                                                                                                                                      |
+| `datagrid.topBar.columnGroups`                            | Column group chips container                              | —                                                                                                                                                                                                                      |
+| `datagrid.topBar.columnGroups.icon`                       | Column group icon                                         | —                                                                                                                                                                                                                      |
+| `datagrid.topBar.columnGroups.separator`                  | Separator between groups                                  | —                                                                                                                                                                                                                      |
+| `datagrid.topBar.columnGroups.item`                       | Column group chip                                         | —                                                                                                                                                                                                                      |
+| `datagrid.topBar.columnGroups.item.icon`                  | Remove icon on chip                                       | —                                                                                                                                                                                                                      |
+| `datagrid.topBar.columnVisibility`                        | Columns button (opens the columns panel)                  | —                                                                                                                                                                                                                      |
+| `datagrid.topBar.columnVisibility.badge`                  | Shown/total count, only while columns are hidden          | `empty`                                                                                                                                                                                                                |
+| `datagrid.topBar.columnVisibility.panel`                  | Columns panel body                                        | —                                                                                                                                                                                                                      |
+| `datagrid.topBar.columnVisibility.search`                 | Search row (past six columns)                             | —                                                                                                                                                                                                                      |
+| `datagrid.topBar.columnVisibility.searchIcon`             | Magnifier inside the search field                         | —                                                                                                                                                                                                                      |
+| `datagrid.topBar.columnVisibility.searchInput`            | Search field                                              | —                                                                                                                                                                                                                      |
+| `datagrid.topBar.columnVisibility.toolbar`                | Count + Show all / Hide all row                           | —                                                                                                                                                                                                                      |
+| `datagrid.topBar.columnVisibility.count`                  | "6 of 8 shown"                                            | —                                                                                                                                                                                                                      |
+| `datagrid.topBar.columnVisibility.action`                 | Show all / Hide all buttons                               | —                                                                                                                                                                                                                      |
+| `datagrid.topBar.columnVisibility.list`                   | Scrolling list of switches                                | —                                                                                                                                                                                                                      |
+| `datagrid.topBar.columnVisibility.section`                | A run of columns under one header group                   | `divided`                                                                                                                                                                                                              |
+| `datagrid.topBar.columnVisibility.group`                  | Header group name above its columns                       | —                                                                                                                                                                                                                      |
+| `datagrid.topBar.columnVisibility.item`                   | One column: label + switch (the `<label>`)                | —                                                                                                                                                                                                                      |
+| `datagrid.topBar.columnVisibility.empty`                  | No-match message                                          | —                                                                                                                                                                                                                      |
+| `datagrid.filter.cell`                                    | Filter row cell                                           | `isPinned`, `isFirstLeftPinned`, `isLastLeftPinned`, `isFirstRightPinned`, `isLastRightPinned`                                                                                                                         |
+| `datagrid.filter.cell.input`                              | Filter input container (text/number/multiselect)          | —                                                                                                                                                                                                                      |
+| `datagrid.header`                                         | Header grid container (sticky)                            | —                                                                                                                                                                                                                      |
+| `datagrid.header.cell`                                    | Header cell                                               | `isPinned`, `isFirstLeftPinned`, `isLastLeftPinned`, `isFirstRightPinned`, `isLastRightPinned`, `isSortable`, `isRowSelection`, `isRowNumber`, `isFirstLeaf`, `isLastLeaf`, `isEmptyCell`                              |
+| `datagrid.header.cell.contextMenu`                        | Column context menu button                                | —                                                                                                                                                                                                                      |
+| `datagrid.header.cell.contextMenu.icon`                   | Context menu icon                                         | —                                                                                                                                                                                                                      |
+| `datagrid.header.cell.contextMenu.tooltip`                | Context menu popup                                        | —                                                                                                                                                                                                                      |
+| `datagrid.header.cell.contextMenu.tooltip.item`           | Context menu action                                       | —                                                                                                                                                                                                                      |
+| `datagrid.header.cell.contextMenu.tooltip.item.icon`      | Action icon                                               | —                                                                                                                                                                                                                      |
+| `datagrid.header.cell.contextMenu.tooltip.item.separator` | Menu separator line                                       | —                                                                                                                                                                                                                      |
+| `datagrid.header.cell.resizer`                            | Column resize handle                                      | —                                                                                                                                                                                                                      |
+| `datagrid.body`                                           | Body grid container (virtualized rows)                    | —                                                                                                                                                                                                                      |
+| `datagrid.body.cell`                                      | Body cell                                                 | `isPinned`, `isFirstLeftPinned`, `isLastLeftPinned`, `isFirstRightPinned`, `isLastRightPinned`, `isRowNumber`, `isRowSelection`, `isRowSelected`, `isFirstLeaf`, `isLastLeaf`, `isEmptyCell`, `isEditing`, `isInvalid` |
+| `datagrid.body.cell.text`                                 | Default cell text renderer                                | —                                                                                                                                                                                                                      |
+| `datagrid.body.cell.editor`                               | The open cell editor                                      | `isPending`                                                                                                                                                                                                            |
+| `datagrid.body.cell.error`                                | What a refused value says, in the top layer               | —                                                                                                                                                                                                                      |
+| `datagrid.body.cell.rowDetail`                            | Row detail expand/collapse button                         | —                                                                                                                                                                                                                      |
+| `datagrid.body.cell.tree`                                 | Tree cell: the indent, the chevron and the value          | —                                                                                                                                                                                                                      |
+| `datagrid.body.cell.tree.toggle`                          | Tree expand/collapse chevron                              | `isExpanded`                                                                                                                                                                                                           |
+| `datagrid.body.cell.tree.spacer`                          | What a leaf puts where its chevron would be               | —                                                                                                                                                                                                                      |
+| `datagrid.body.row`                                       | Data row (display: contents)                              | —                                                                                                                                                                                                                      |
+| `datagrid.body.groupRow`                                  | Group row (display: contents)                             | —                                                                                                                                                                                                                      |
+| `datagrid.body.groupRow.expandButton`                     | Group expand/collapse button                              | —                                                                                                                                                                                                                      |
+| `datagrid.body.detailRow`                                 | Expanded detail row                                       | —                                                                                                                                                                                                                      |
+| `datagrid.body.empty`                                     | Empty state container                                     | —                                                                                                                                                                                                                      |
+| `datagrid.emptyColumns`                                   | No columns selected placeholder                           | —                                                                                                                                                                                                                      |
+| `datagrid.bottomBar`                                      | Bottom bar (row count, pagination)                        | —                                                                                                                                                                                                                      |
+| `datagrid.bottomBar.info`                                 | Status text ("Rows: ...", "Selected: ...")                | —                                                                                                                                                                                                                      |
+| `datagrid.bottomBar.clearFilters`                         | "Clear filters" button                                    | —                                                                                                                                                                                                                      |
+| `datagrid.bottomBar.selection`                            | The selection count and its buttons, at the bar's far end | —                                                                                                                                                                                                                      |
+| `datagrid.bottomBar.action`                               | "Show selected" and "Clear selection"                     | `pressed` (Show selected while it is on)                                                                                                                                                                               |
+| `datagrid.bottomBar.pagination`                           | Pagination controls wrapper                               | —                                                                                                                                                                                                                      |
+| `datagrid.bottomBar.pagination.button`                    | Pagination nav button                                     | —                                                                                                                                                                                                                      |
+| `datagrid.bottomBar.pagination.info`                      | Page info text ("1 of 5")                                 | —                                                                                                                                                                                                                      |
 
 ---