@box-kite/react 2.1.0 → 2.2.1

package/BOX_AI_CONTEXT.md

@@ -1,6 +1,6 @@
 # @box-kite/react - AI Assistant Context
 
-Runtime CSS-in-JS library. `Box` component accepts 221 CSS props and generates CSS classes at runtime. Same prop values share a single class.
+Runtime CSS-in-JS library. `Box` component accepts 235 CSS props and generates CSS classes at runtime. Same prop values share a single class.
 
 ---
 
@@ -282,9 +282,13 @@ const { css, anchorProps, layerProps } = useAnchorPosition({ side: 'bottom', ali
 The palette is **Tailwind 4.3's, in OKLCH**: twenty-six families of eleven steps (`50`–`950`) — the five
 neutrals (`slate`, `gray`, `zinc`, `neutral`, `stone`), the four Tailwind 4.3 added (`mauve`, `mist`,
 `olive`, `taupe`) and seventeen hues (`red`, `orange`, `amber`, `yellow`, `lime`, `green`, `emerald`,
-`teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`). Each token is a
-CSS variable declared in `:root` the first time something uses it, so a colour you never write costs
-nothing.
+`teal`, `cyan`, `sky`, `blue`, `indigo`, `violet`, `purple`, `fuchsia`, `pink`, `rose`). A token is a
+CSS variable written **with its own value as the fallback** — `bgColor="sky-500"` is
+`background-color: var(--sky-500,oklch(68.5% .169 237.3))` — so nothing is declared in `:root` (a late
+`:root` insert recalculates every element on the page) and declaring `--sky-500` yourself still overrides
+it. `var(--sky-500)` elsewhere in this file is that, shortened. Your own CSS cannot count on `--sky-500`
+existing: hand it a variable of yours with `vars={{ brand: 'violet-500' }}` on an ancestor. A hand-written
+`var(--sky-500)` _inside_ a Box value — `fill`, `vars`, `css`, a `Box.extend()` variable — gets the fallback too.
 
 Any colour value takes a slash and a percentage:
 
@@ -642,6 +646,131 @@ const wobble = Box.spring({ stiffness: 120, damping: 8 });
 
 ---
 
+### Scroll-driven animations
+
+An animation's progress can come from a scroll position rather than a clock. There is no listener, no
+`requestAnimationFrame` and no state: the browser runs it off the compositor, and the whole thing is props.
+
+| Prop                                        | CSS Property                 | Notes                                                                                                                                                 |
+| ------------------------------------------- | ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `animationTimeline`                         | animation-timeline           | `'none'`, `'auto'`, an anonymous timeline (`'scroll()'`, `'scroll(root block)'`, `'view()'`, `'view(inline 20%)'`) or a name a declaration below gave |
+| `animationRange`                            | animation-range              | One end or both: `'entry'`, `'cover 20%'`, `'entry 0% entry 100%'`, `'normal'`                                                                        |
+| `animationRangeStart` / `animationRangeEnd` | animation-range-start / -end | One end at a time. A named part of the pass with an optional offset, a bare length, or `'normal'`                                                     |
+| `scrollTimeline`                            | scroll-timeline              | Declares a named timeline on a **scroller**: `'page'` or `'page block'`. The `--` is optional and added for you                                       |
+| `scrollTimelineName` / `scrollTimelineAxis` | scroll-timeline-name / -axis | The two halves of that shorthand. Axis: `'block'`, `'inline'`, `'x'`, `'y'`                                                                           |
+| `viewTimeline`                              | view-timeline                | Declares a named timeline on a **subject** — its own pass across the scrollport: `'card'` or `'card block'`                                           |
+| `viewTimelineName` / `viewTimelineAxis`     | view-timeline-name / -axis   | The two halves of that one                                                                                                                            |
+| `viewTimelineInset`                         | view-timeline-inset          | `'auto'`, or one or two lengths, shrinking the scrollport the pass is measured against                                                                |
+| `timelineScope`                             | timeline-scope               | Makes named timelines below this element reachable from anywhere else below it. Comma-separated                                                       |
+
+The two anonymous timelines cover most of it and need nothing declared elsewhere:
+
+```tsx
+// A reading-progress bar: the page's own scroll, driving a scaleX from 0 to 1.
+Box.keyframes({ progress: { from: { scale: 0 }, to: { scale: 1 } } });
+
+<Box
+  position="fixed"
+  top={0}
+  insetX={0}
+  height={1}
+  bgColor="sky-500"
+  css={{ transformOrigin: 'left' }}
+  animationName="progress"
+  animationTimeline="scroll(root)"
+  animationFillMode="both"
+  motionReduce={{ animation: 'none' }}
+/>;
+
+// Reveal on scroll: this element's own pass, over the first 60% of its entry.
+Box.keyframes({ 'fade-up': { from: { opacity: 0, translateY: 4 }, to: { opacity: 1, translateY: 0 } } });
+
+<Box animationName="fade-up" animationTimeline="view()" animationRange="entry 0% entry 60%" motionReduce={{ animation: 'none' }}>
+  …
+</Box>;
+```
+
+A **named** timeline is the two-sided form, for when the animated element is not inside the scroller:
+
+```tsx
+<Box timelineScope="page">
+  <Box height="fit-screen" overflow="auto" scrollTimeline="page block">
+    …
+  </Box>
+  <Box animationName="progress" animationTimeline="page" animationFillMode="both" />
+</Box>
+```
+
+**Three things to know, and all three are traps:**
+
+- **The CSS `animation` shorthand resets `animation-timeline`.** A timeline declared before it is
+  silently undone. The registry declares `animationTimeline` after `animation`, so writing both props is
+  safe in either order — but an `animation` written inside `css` sorts last and will undo it.
+- **A scroll-driven animation has no duration**, so `--transitionTime` cannot zero it. It is the one kind
+  of motion in this library that does **not** stop itself under `prefers-reduced-motion`: pair it with
+  `motionReduce={{ animation: 'none' }}`, every time.
+- **Where the browser has none, the declaration is dropped rather than the animation.** It then runs on the
+  document timeline over whatever duration it was given. Make the end state the resting state — with
+  `animationFillMode="both"` and a sequence that ends where the element belongs, a missing timeline degrades
+  to "already arrived" rather than to a loop. Chrome/Edge 115+, Safari 26+; Firefox is behind a flag.
+
+---
+
+### View transitions
+
+The browser screenshots the page, runs the update, screenshots again, and cross-fades between the two —
+so a change that was a jump becomes a transition with nothing animated by hand.
+
+| Prop / API                            | What it does                                                                                                                                         |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `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                                                                                                |
+
+```tsx
+const handle = Box.viewTransition(() => flushSync(() => setTab(next)), { types: ['forward'] });
+await handle.finished;
+```
+
+```ts
+interface ViewTransitionOptions {
+  /** `'skip'` (default) runs the update with no transition under reduced motion; `'play'` transitions anyway. */
+  reducedMotion?: 'skip' | 'play';
+  /** Types `:active-view-transition-type(name)` selects on, so forward and back can differ. */
+  types?: string[];
+}
+
+interface ViewTransitionHandle {
+  ready: Promise<void>;
+  finished: Promise<void>;
+  updateCallbackDone: Promise<void>;
+  skip(): void;
+  /** False when the browser had no API, or reduced motion skipped it. */
+  transitioned: boolean;
+}
+```
+
+**Four things to know:**
+
+- **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.
+- **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
+  `props={{ style: { viewTransitionName: id } }}` — the exception `useAnchorPosition`'s anchor name and a
+  `Slider` thumb already take.
+- **Reduced motion skips the transition and keeps the update.** A whole-page cross-fade is exactly the
+  motion the preference is about. `{ reducedMotion: 'play' }` is the opt-out, for a change that is
+  unreadable without one.
+- **The handle is the same shape either way**, so there is one code path: with no API, `finished` is an
+  already-resolved promise, `skip()` a no-op and `transitioned` false. `ready` rejects when a transition is
+  skipped, which is not an error — branch on `finished`.
+
+---
+
 ## Pseudo-Classes, Breakpoints & Themes
 
 ```tsx
@@ -1119,24 +1248,41 @@ second argument for an element inside an `<svg>`. `<Icon>` is this hook plus tha
 ### Server-Side Rendering
 
 ```tsx
-import { getStyles, resetStyles } from '@box-kite/react/ssg';
+import Box from '@box-kite/react';
+import { getStyleTag, resetStyles } from '@box-kite/react/ssg';
+
+Box.configure({ classNames: 'stable' }); // in the server AND in the browser entry
 
 const html = renderToString(<App />); // any React server renderer
-const cssString = getStyles(); // the CSS for what was just rendered
-// <style id="box-kite-styles">{cssString}</style> in the document head
+const styleTag = getStyleTag(); // <style id="box-kite-styles" data-box-kite="…">…</style>, for the head
 resetStyles(); // reset before the next request
 ```
 
-Or in one call, which injects the styles into the rendered `<head>` and resets afterwards:
+Or in one call, which injects the tag into the rendered `<head>` and resets afterwards:
 
 ```tsx
 import { renderToStaticMarkup } from '@box-kite/react/ssg';
 
-const { html, styles } = renderToStaticMarkup(<App />);
+const { html, styles, styleTag } = renderToStaticMarkup(<App />);
 ```
 
 No DOM is needed: with no `document` in the process the engine collects CSS in memory. Sequential
-requests are independent and identical markup gets identical class names.
+requests are independent and identical markup gets identical class names. `getStyles()` is the bare CSS.
+
+**Adoption.** The `data-box-kite` attribute is a manifest — each rule's cascade position and a checksum
+of the classes it styles. On the first render the browser engine checks it against the sheet it parsed
+and takes the sheet over: every rule in it counts as generated, so hydration builds and inserts nothing
+for what the HTML already styled, and only rules the client adds afterwards are inserted, each in its
+cascade position. Two conditions:
+
+| Condition                               | Why                                                                        | If it does not hold                                                           |
+| --------------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| `classNames: 'stable'` on both sides    | the content-hashed names are how the browser recognises the server's rules | the sheet is left in place under no id and the engine writes its own after it |
+| the browser parsed every generated rule | an index is only trustworthy if nothing in between was dropped             | same fallback                                                                 |
+
+Do **not** remove the server's `<style>` after hydration — it is the engine's own sheet now. Register
+the same `Box.extend()` props and `Box.keyframes()` sequences on both sides. `engine.getStyleTag()` is
+the same thing for `@box-kite/core`.
 
 ---
 
@@ -2139,7 +2285,7 @@ function TrendCell({ cell }: { cell: CellModel<Row> }) {
 9. **Theme styles nest**: `theme={{ dark: { hover: { ... } } }}`
 10. **HTML attributes go in `props` prop**: `<Link props={{ href: '/about' }}>` not `<Link href>`. `data-*` and `aria-*` go there too — a `data-state` written at the top level typechecks and is then dropped
 11. **Size shortcuts**: `width="fit"` = 100%, `width="fit-screen"` = 100vw, `width="1/2"` = 50%
-12. **Box is memoized** with `React.memo`
+12. **Box is memoized** with `React.memo`, and so are `Flex`, `H1`, `Button` and the rest. A component of your own that is a Box with defaults calls `useBoxElement({ p: 4, ...props }, ref)` from its own `forwardRef` rather than returning `<Box>` — one fiber instead of two
 13. **`style` is top-level only** — never inside breakpoints (`sm={{ style: ... }}`), pseudo-classes, or theme objects. `css` is the one that nests: `sm={{ css: { objectPosition: 'top' } }}` is a rule
 14. **A CSS variable is a prop**: `vars={{ 'color-x': 'sky-500' }}` declares `--color-x` for everything inside — and a third-party chart goes in `<ChartContainer series={['revenue']}>` so it names no colour at all
 15. **All sizing props use divider 4** — `width`, `height`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight` are NOT direct pixels. `height={10}` = 2.5rem = 40px
@@ -2219,34 +2365,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
 
@@ -2258,7 +2406,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? }`                                                            |
@@ -2641,52 +2789,54 @@ 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`                        | 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" 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")                                 | —                                                                                                                                                                                                                      |
 
 ---
 
@@ -2896,6 +3046,19 @@ Also accepts: `data` (TRow[]), `value`/`defaultValue`, `label`/`labelProps`, `mu
 3. **CSS variables**: In `:root` rules
 4. **Theme issues**: Ensure `<Box.Theme>` wraps your app
 5. **Layer theming**: a tooltip or dropdown popup stays where it was declared and inherits the theme; only the no-Popover-API fallback uses the `#box-kite-portal` container
+6. **Read the console first**: outside a production build the engine prints one `[box-kite]` warning per mistake that would otherwise be silent, each naming the fix:
+
+   | You wrote                  | The warning says                                                           |
+   | -------------------------- | -------------------------------------------------------------------------- |
+   | `bgColor="bleu-500"`       | wrote no CSS … Did you mean `"blue-500"`?                                  |
+   | `opacity={50}`             | wrote no CSS … It takes one of 0, 0.1, … 1                                 |
+   | `<Link href="/about">`     | `href` is an HTML attribute … write `props={{ href: ... }}`                |
+   | `fontSize={4}`             | is 4px text … For 16px write `fontSize={16}`                               |
+   | `lineHeight={1.5}`         | is a 1.5px line … `lineHeight="font-size"`, or `css={{ lineHeight: 1.5 }}` |
+   | `transitionDuration={0.3}` | is 0.3ms … For 0.3s write `transitionDuration={300}`                       |
+   | `brightness={1.1}`         | is 1.1% … For 110% write `brightness={110}`                                |
+
+   Once per value, and `Box.configure({ warnings: false })` silences them. In production a rejected value is dropped with nothing said, which is why `check_styles` (`@box-kite/mcp`) exists
 
 ---
 
@@ -3204,7 +3367,7 @@ allowed.tokens; // the colours, the @keyframes names and the style-tree nodes a
   `DataGrid`'s `def` (required — the columns and the grid-wide flags) and `data`, `DashboardGrid`'s
   `layout`/`defaultLayout`/`columns`, `Widget`'s `empty`, `ChartContainer`'s `series`. A column's nested
   `columns`, and `dataSource`/`onCellEdit`/`rowDetail`/`treeData`, stay out — they are the app's to pass.
-- **The allow-list is the app's.** `catalog()` with no options is all 78 components and all 221 props —
+- **The allow-list is the app's.** `catalog()` with no options is all 78 components and all 235 props —
   ~4.6 MB serialized. `include`, `exclude` and `styleProps` are how an app narrows it.
 
 Full reference: `docs/catalog.md`.