@box-kite/react 2.1.0 → 2.2.1

package/BOX_KITE_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`.

package/README.md

@@ -5,12 +5,12 @@
 [![Tests](https://github.com/box-kite/box-kite/actions/workflows/test.yml/badge.svg)](https://github.com/box-kite/box-kite/actions/workflows/test.yml)
 [![license](https://img.shields.io/npm/l/@box-kite/react)](LICENSE)
 
-`Box` is a single React component with 221 typed CSS props. It generates the CSS for the values you
+`Box` is a single React component with 235 typed CSS props. It generates the CSS for the values you
 pass at runtime and caches every rule by its content, so the same value anywhere in the app reuses
 one class — a project styles itself in TypeScript, with no CSS files to write and no class-name
 convention to remember.
 
-[Docs and live demos](https://www.box-kite.dev) · [Contributing](CONTRIBUTING.md) ·
+[Docs and live demos](https://www.box-kite.dev) · [Blog](https://www.box-kite.dev/blog/) · [Contributing](CONTRIBUTING.md) ·
 [Support](SUPPORT.md) · [Security](SECURITY.md) ·
 [Releases](https://github.com/box-kite/box-kite/releases)
 
@@ -690,7 +690,7 @@ A complete page — props, pseudo-classes, breakpoints, themes, `extend`, `compo
 
 ## Architecture
 
-The styling engine is framework-free. Everything that generates CSS — the 221 prop definitions,
+The styling engine is framework-free. Everything that generates CSS — the 235 prop definitions,
 the value formatters, class-name generation, rule ordering, the style sinks (CSSOM, `textContent`,
 string for SSR, style elements for React 19), the flush scheduler, CSS variables and the theme
 runtime — lives in `src/core/` and imports no React at all. CI fails the build if it ever does

package/box.cjs

@@ -1 +1 @@
-Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});const e=require("./rolldown-runtime.cjs"),t=require("./react-shared.cjs"),n=require("./client.cjs");let r=require("react");r=e.t(r,1);let i=require("@box-kite/core");function a(e,i){let{tag:a=`div`,children:o}=e,{classNames:s,styleElements:c}=n.i(e,a===`svg`),l=(0,r.useMemo)(()=>{let n=t.d(e,s);return i&&(n.ref=i),n},[e]),[u,d]=(0,r.useState)(!1),f=typeof o==`function`,p=f?{...l,onMouseEnter:()=>d(!0),onMouseLeave:()=>d(!1)}:l,m=r.default.createElement(a,p,f?o({isHover:u}):o);return c?r.default.createElement(r.default.Fragment,null,c,m):m}var o=(0,r.memo)((0,r.forwardRef)(a));o.displayName=`Box`,o.extend=i.BoxExtends.extend,o.components=i.BoxExtends.components,o.keyframes=i.BoxExtends.keyframes,o.spring=i.Springs.spring,o.Theme=n.n,o.useTheme=n.n.useTheme,o.getVariableValue=e=>(0,i.getDefaultEngine)().getVariableValue(e),o.configure=n.r.configure;function s(e,r){return t.f(n.i(e,r?.svg===!0),e.className)}exports.default=o,exports.useClassNames=s,exports.useVisibility=n.a;
+Object.defineProperties(exports,{__esModule:{value:!0},[Symbol.toStringTag]:{value:`Module`}});const e=require("./rolldown-runtime.cjs"),t=require("./react-shared.cjs"),n=require("./client.cjs");let r=require("react");r=e.t(r,1);let i=require("@box-kite/core");function a({tag:e,tagProps:t,render:n}){let[i,a]=(0,r.useState)(!1);return r.default.createElement(e,{...t,onMouseEnter:()=>a(!0),onMouseLeave:()=>a(!1)},n({isHover:i}))}function o(e,i){let{tag:o=`div`,children:s}=e,{classNames:c,styleElements:l}=n.i(e,o===`svg`),u=t.d(e,c);i&&(u.ref=i);let d=typeof s==`function`?r.default.createElement(a,{tag:o,tagProps:u,render:s}):r.default.createElement(o,u,s);return l?r.default.createElement(r.default.Fragment,null,l,d):d}var s=t.f(o,`Box`);s.extend=i.BoxExtends.extend,s.components=i.BoxExtends.components,s.keyframes=i.BoxExtends.keyframes,s.spring=i.Springs.spring,s.Theme=n.n,s.useTheme=n.n.useTheme,s.getVariableValue=e=>(0,i.getDefaultEngine)().getVariableValue(e),s.configure=n.r.configure,s.viewTransition=i.startViewTransition;function c(e,r){return t.p(n.i(e,r?.svg===!0),e.className)}exports.default=s,exports.useBoxElement=o,exports.useClassNames=c,exports.useVisibility=n.a;

package/box.d.ts

@@ -1,5 +1,5 @@
-import { default as React, RefAttributes } from 'react';
-import { BoxExtends, Springs } from '@box-kite/core';
+import { default as React, Ref, RefAttributes } from 'react';
+import { BoxExtends, Springs, startViewTransition } from '@box-kite/core';
 import { BoxClassNames } from './react/boxClassNames';
 import { BoxClassNameProps, BoxCoreProps } from './react/boxProps';
 import { default as useVisibility } from './react/hooks/useVisibility';
@@ -7,6 +7,15 @@ import { ExtractElementFromTag } from './react/reactTypes';
 import { default as Theme } from './react/theme/theme';
 import { StylesContext } from './react/useStyles';
 import { ComponentsAndVariants } from '@box-kite/core/types';
+/**
+ * Box's render as a hook, for a component that is a Box with defaults: called from its own `forwardRef`, it
+ * makes that component one fiber rather than a wrapper around a second one. `Flex`, `H1` and `Button` are this.
+ *
+ * ```tsx
+ * const Card = forwardRef<HTMLDivElement, BoxProps>((props, ref) => useBoxElement({ p: 4, ...props }, ref));
+ * ```
+ */
+export declare function useBoxElement<TTag extends keyof React.JSX.IntrinsicElements = 'div', TKey extends keyof ComponentsAndVariants = never>(props: BoxCoreProps<TTag, TKey>, ref?: Ref<ExtractElementFromTag<TTag>>): React.ReactNode;
 interface BoxType {
     <TTag extends keyof React.JSX.IntrinsicElements = 'div', TKey extends keyof ComponentsAndVariants = never>(props: BoxCoreProps<TTag, TKey> & RefAttributes<ExtractElementFromTag<TTag>>): React.ReactNode;
     extend: typeof BoxExtends.extend;
@@ -19,6 +28,8 @@ interface BoxType {
     getVariableValue: (name: string) => string;
     /** Explicit engine configuration (class-name hashing, style sink). Call once, before the first render. */
     configure: typeof StylesContext.configure;
+    /** Run a DOM change inside a view transition where the browser has one, and plainly where it has not. */
+    viewTransition: typeof startViewTransition;
 }
 declare const Box: BoxType;
 export default Box;