@box-kite/react 2.3.1 → 2.4.1

package/BOX_AI_CONTEXT.md

@@ -660,8 +660,15 @@ const wobble = Box.spring({ stiffness: 120, damping: 8 });
   the same commit, with nothing to configure. `Tooltip`, the `Dropdown` popup and the DataGrid column
   menu are all built on it, and each expresses its exit as a `closed` variant in its component styles — plus `up`/`closedUp` on `dropdown.items`, since a popup that opened upward has to collapse upward.
 - **`Box.configure({ transition })`** changes what the base class transitions for the whole engine:
-  a group name, or `false` to declare nothing at all and leave transitions entirely to the props.
+  a group name, a comma list of groups and property names (`'colors, opacity'`), or `false` to declare
+  nothing at all and leave transitions entirely to the props. Anything else transitions `all` and warns.
   Call it before the first render.
+- **An inline phrasing element is `inline-block`**, where every other Box is `block`: `a`, `span`, `label`, `time`, `mark`, `abbr`, `code`, `kbd`, `samp`, `var`, `em`,
+  `strong`, `small`, `b`, `i`, `u`, `s`, `sub`, `sup`, `q`, `cite`, `dfn`, `data`, `output`, `bdi`, `bdo`. It is
+  selected on the rendered element at the base class's specificity, so `<Link>`, `<Box tag="a">` and a
+  `useClassNames` class on a router's `<a>` all stay in their sentence, margin and padding still apply, and a
+  `display` prop or component still wins. Media (`img`, `svg`, `video`, `canvas`, `iframe`) stays block. An `inline-block` never breaks across lines, so a
+  prose link or `<Mark>` that has to wrap with the text sets `display="inline"`.
 
 ---
 
@@ -1263,7 +1270,7 @@ import Textbox from '@box-kite/react/components/textbox';
 <Flex d="column" gap={2} md={{ d: 'row', gap: 4 }}>{children}</Flex>
 
 // Grid
-<Grid gridCols={3} gap={4}>{items.map(i => <Box key={i.id}>{i.content}</Box>)}</Grid>
+<Grid gridTemplateColumns={3} gap={4}>{items.map(i => <Box key={i.id}>{i.content}</Box>)}</Grid>
 
 // Card
 <Box p={4} bgColor="white" borderRadius={8} shadow="medium">{content}</Box>
@@ -1320,6 +1327,11 @@ undefined and rendering it costs nothing, so write the line either way. Pass `{
 second argument for an element inside an `<svg>`. `<Icon>` is this hook plus that flag — reach for
 `Icon` for an icon and this only for everything else.
 
+The class carries the base reset, which is `display: block` except on an `<a>`, `<span>`, `<label>` and the
+other phrasing elements, which are `inline-block`: a `NavLink` styled this way stays in its sentence.
+`{ base: false }` leaves the reset out — for a library's own root (`<ReactFlow>`, `<MiniMap>`, a `BaseEdge`)
+whose margin, display and transitions are its own.
+
 ### Group and Peer
 
 ```tsx
@@ -1456,6 +1468,19 @@ Full reference: `docs/a11y-primitives.md`.
 
 ---
 
+## Field ids, external labels and the invalid state
+
+- **A top-level `id` lands on the control, once.** `<Combobox id="owner">` puts it on the `<input role="combobox">`
+  and nowhere else, as `Textbox`, `Textarea`, `Select` (its button), `Checkbox`, `Switch`, `RadioButton` and
+  `TimeZoneSelect` do, so `<label htmlFor="owner">` names the control. `DateField`, `DatePicker`, `Slider` and
+  `RadioGroup` are groups no `<label>` can name: the `id` goes on the group, and `labelledBy` points it at an
+  external label.
+- **`aria-invalid` draws the error border on every field.** `props={{ 'aria-invalid': true }}` turns the frame of a
+  `Textbox`, `Textarea`, `Select` or `Combobox` `red-500`, through hover and focus, in both themes. A combobox's
+  attribute is on its input and its border on the shell, so the shell matches `:has([aria-invalid="true"])` —
+  restyle it as `combobox: { styles: { has: { '[aria-invalid="true"]': { … } } } }`, the others with
+  `ariaAttr: { invalid: { … } }`. `DateField` and `DatePicker` take an `invalid` prop that does both.
+
 ## Sizes: compact, normal, large
 
 Every built-in component is drawn at one of three sizes, and a size is two CSS variables —
@@ -1521,16 +1546,16 @@ the association needs no `htmlFor`/`id` pair and the whole row is a click target
 nothing wraps the input — the markup is what it always was. `labelProps` styles that `<label>`;
 every other Box prop styles the control itself.
 
-| Component    | Prop                     | What it does                                                                                 |
-| ------------ | ------------------------ | -------------------------------------------------------------------------------------------- |
-| all three    | `label` / `labelProps`   | The wrapping `<label>` and its styles.                                                       |
-| `Checkbox`   | `indeterminate`          | Sets the DOM property **and** `aria-checked="mixed"`, which is what is announced.            |
-| `Switch`     | —                        | `role="switch"` over the same input; Space **and** Enter toggle, Enter does not submit.      |
-| `RadioGroup` | `label`                  | `role="radiogroup"` named by it — a set of radios with nothing over it is a flat list.       |
-| `RadioGroup` | `name`                   | The field every item submits under. Generated when left out.                                 |
-| `RadioGroup` | `value` / `defaultValue` | The selected item's value (a string — the platform's own model for a radio).                 |
-| `RadioGroup` | `onValueChange`          | `(value, { reason, event })` — `click` or `keyboard`. `onChange` is the deprecated spelling. |
-| `RadioGroup` | `orientation`            | `vertical` (default) or `horizontal`. Both arrow pairs navigate either way.                  |
+| Component    | Prop                     | What it does                                                                                                                                       |
+| ------------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| all three    | `label` / `labelProps`   | The wrapping `<label>` and its styles.                                                                                                             |
+| `Checkbox`   | `indeterminate`          | Sets the DOM property **and** `aria-checked="mixed"`, which is what is announced.                                                                  |
+| `Switch`     | —                        | `role="switch"` over the same input; Space **and** Enter toggle, Enter does not submit.                                                            |
+| `RadioGroup` | `label`                  | `role="radiogroup"` named by it — a set of radios with nothing over it is a flat list.                                                             |
+| `RadioGroup` | `name`                   | The field every item submits under. Generated when left out.                                                                                       |
+| `RadioGroup` | `value` / `defaultValue` | The selected item's value (a string — the platform's own model for a radio).                                                                       |
+| `RadioGroup` | `onValueChange`          | `(value, { reason, event })` — `click` or `keyboard`. `onChange` is the deprecated spelling.                                                       |
+| `RadioGroup` | `orientation`            | `vertical` (default) or `horizontal`, which wraps and keeps the label on a line of its own above the radios. Both arrow pairs navigate either way. |
 
 Arrow keys move **and select** inside a group, wrapping at both ends and skipping disabled items;
 Tab enters the group once and leaves it once, because a native radio set is already a single tab
@@ -2660,6 +2685,51 @@ function TrendCell({ cell }: { cell: CellModel<Row> }) {
 <DataGrid data={rows} def={{ rowKey: 'id', columns: [{ key: 'trend', header: 'Last 12 months', width: 180, Cell: TrendCell }] }} />;
 ```
 
+### Theming a React Flow canvas — `FlowContainer`
+
+`ChartContainer`'s move for diagrams. `@box-kite/react/components/flow` (server-safe, imports nothing from xyflow) is a Box
+that declares React Flow's `--xy-*` variables from the palette in both themes, so the canvas — background, pattern, edges,
+handles, built-in nodes, minimap, controls, selection box, edge labels — names no colour and follows the page:
+
+```tsx
+import { Background, Controls, MiniMap, ReactFlow } from '@xyflow/react';
+import '@xyflow/react/dist/style.css';
+import { FlowContainer, flowColorMode } from '@box-kite/react/components/flow';
+
+function Canvas() {
+  const [theme] = Box.useTheme();
+
+  return (
+    <FlowContainer height={120}>
+      <ReactFlow nodes={nodes} edges={edges} colorMode={flowColorMode(theme)} fitView>
+        <Background />
+        <Controls />
+        <MiniMap />
+      </ReactFlow>
+    </FlowContainer>
+  );
+}
+```
+
+| Prop     | What it is                                                                                                                       |
+| -------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `tokens` | Repaints a role: `{ selection: 'emerald-500' }` for both themes, `{ surface: { light: 'base-50', dark: 'base-950' } }` per theme |
+| `motion` | `'static'` zeroes every Box transition inside the canvas, for nodes moved or resized every frame                                 |
+
+- **Eight roles**, each a custom property a custom node can read: `--flow-surface`, `--flow-panel`, `--flow-text`, `--flow-border`,
+  `--flow-grid`, `--flow-edge`, `--flow-selection`, `--flow-handle`. Defaults are `base`/`accent`, so `Box.palette()` reaches them.
+- **The defaults are the `flowContainer` style node**, so one override repaints every canvas in an app:
+  `Box.components({ flowContainer: { styles: { vars: { 'flow-selection': 'emerald-500' } } } })`; `tokens` is the per-canvas answer.
+- **One `--xy-*` variable is `vars`** (`vars={{ 'xy-edge-stroke-width': '2' }}`); a prop on `<MiniMap>`/`<Background>` still wins.
+- **`colorMode={flowColorMode(theme)}`** keeps React Flow's own `.dark` class in step with the page. A canvas in another theme sits
+  in `<Box.Theme use="local">`; never `colorMode="light"` under a dark page — `.light` is no theme boundary, so the two mix.
+- **A custom node is invisible to the keyboard** — xyflow removes every node's focus outline. Spread `flowNodeStyles` on its
+  root (an outline while xyflow's wrapper is `:focus-visible`) and `flowNodeSelectedStyles` when its `selected` prop is true;
+  both are outlines in the `selection` role, so they survive forced colours. A custom edge on `BaseEdge` takes `flowEdgeStyles`
+  through `useClassNames(flowEdgeStyles, { svg: true, base: false })`.
+- Colour props refuse `var()`, so a custom node reads a role through `css`:
+  `css={{ backgroundColor: 'var(--flow-panel)', borderColor: 'var(--flow-border)', color: 'var(--flow-text)' }}`.
+
 ---
 
 ## Key Reminders for AI Assistants
@@ -2677,7 +2747,7 @@ function TrendCell({ cell }: { cell: CellModel<Row> }) {
 11. **Size shortcuts**: `width="fit"` = 100%, `width="fit-screen"` = 100vw, `width="1/2"` = 50%
 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
+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, and a React Flow canvas goes in `<FlowContainer>` with `colorMode={flowColorMode(theme)}`
 15. **All sizing props use divider 4** — `width`, `height`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight` are NOT direct pixels. `height={10}` = 2.5rem = 40px
 16. **A state your own code sets is a nested prop too**: `dataAttr={{ 'state=open': { … } }}` → `[data-state="open"]`, `ariaAttr={{ selected: { … } }}` → `[aria-selected="true"]`, `has={{ ':checked': { … } }}`, `not={{ hover: { … } }}`, `nth={{ odd: { … } }}`. The attribute itself still goes in `props`
 17. **Somebody else's state is `group`/`peer`**: `group={{ 'card/hover': { … } }}` → `.card:hover .x`, `peer={{ 'agree/checked': { … } }}` → `.agree:checked ~ .x`. The ancestor or sibling carries the class via `className`; `hoverGroup` and its four siblings are the older spelling
@@ -2790,27 +2860,27 @@ named ones carry the reason.
 
 ### ColumnType
 
-| Prop                     | Type                                                                            | Default   | Description                                                                                                                                     |
-| ------------------------ | ------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `key`                    | `Key`                                                                           | required  | Column identifier (maps to TRow property)                                                                                                       |
-| `header`                 | `string`                                                                        | —         | Header text                                                                                                                                     |
-| `width`                  | `number`                                                                        | `200`     | Base width in px                                                                                                                                |
-| `align`                  | `'start' \| 'end' \| 'center' \| 'left' \| 'right'`                             | `'left'`  | Cell alignment. `start`/`end` follow the reading order; `left`/`right` stay on the screen side they name                                        |
-| `pin`                    | `'START' \| 'END'` (also `'LEFT'`/`'RIGHT'`)                                    | —         | Pin to an edge of the **inline axis** (sticky on scroll), so it holds under either `dir`. `LEFT`/`RIGHT` are the older spelling of the same two |
-| `columns`                | `ColumnType[]`                                                                  | —         | Nested columns (grouped header)                                                                                                                 |
-| `Cell`                   | `({ cell }) => ReactNode`                                                       | —         | Custom renderer. `cell`: `{ value, row, column, grid }`. It redraws when its row changes or the grid does — not when another row is selected    |
-| `sortable` / `resizable` | `boolean`                                                                       | inherits  | Override grid-level setting                                                                                                                     |
-| `flexible`               | `boolean`                                                                       | `true`    | Participate in flex width distribution                                                                                                          |
-| `filterable`             | `boolean \| FilterConfig`                                                       | —         | `true` (text), `{ type: 'number', min?, max? }`, `{ type: 'multiselect', options? }`                                                            |
-| `contextMenu`            | `boolean \| ContextMenuConfig`                                                  | inherits  | Override grid-level context menu. `false` hides entirely. `{ sort?, pin?, group? }` controls sections                                           |
-| `aggregate`              | `AggregateName \| (values, rows) => value`                                      | —         | Total this column over each group row, and over the footer. See below                                                                           |
-| `AggregateCell`          | `({ cell }) => ReactNode`                                                       | —         | Renders the aggregate. `cell`: `{ value, column, rows, scope }`, `scope` being `'group'` or `'footer'`                                          |
-| `editable`               | `boolean \| (row) => boolean`                                                   | inherits  | Whether this column’s cells can be edited — every row, or the rows a predicate says                                                             |
-| `editor`                 | `CellEditorType \| CellEditorConfig`                                            | inferred  | `text`/`number`/`checkbox`/`select`. Without one it is read off the value in the cell                                                           |
-| `EditCell`               | `({ cell }) => ReactNode`                                                       | —         | An editor of your own, bound to `cell.draft` with `cell.commitEdit()`/`cell.cancelEdit()`                                                       |
-| `exportValue`            | `(row: TRow) => value`                                                          | the field | What this column writes to an exported file — an export runs no React, so a `Cell` renderer needs it                                            |
-| `list`                   | `'title' \| 'kicker' \| 'subtitle' \| 'end' \| 'field' \| 'detail' \| 'hidden'` | inferred  | Where the column goes in a list item, on a phone                                                                                                |
-| `exportFormat`           | `string`                                                                        | —         | The number format its cells wear in a workbook, `'#,##0.00'` or `'yyyy-mm-dd'`                                                                  |
+| Prop                     | Type                                                                            | Default   | Description                                                                                                                                                                                                                                                                   |
+| ------------------------ | ------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `key`                    | `Key`                                                                           | required  | Column identifier (maps to TRow property)                                                                                                                                                                                                                                     |
+| `header`                 | `string`                                                                        | —         | Header text                                                                                                                                                                                                                                                                   |
+| `width`                  | `number`                                                                        | `200`     | Base width in px                                                                                                                                                                                                                                                              |
+| `align`                  | `'start' \| 'end' \| 'center' \| 'left' \| 'right'`                             | `'left'`  | Cell alignment. `start`/`end` follow the reading order; `left`/`right` stay on the screen side they name                                                                                                                                                                      |
+| `pin`                    | `'START' \| 'END'` (also `'LEFT'`/`'RIGHT'`)                                    | —         | Pin to an edge of the **inline axis** (sticky on scroll), so it holds under either `dir`. `LEFT`/`RIGHT` are the older spelling of the same two                                                                                                                               |
+| `columns`                | `ColumnType[]`                                                                  | —         | Nested columns (grouped header)                                                                                                                                                                                                                                               |
+| `Cell`                   | `({ cell }) => ReactNode`                                                       | —         | Custom renderer. `cell`: `{ value, row, column, grid }`. It fills the cell **edge to edge, with no padding** — the built-in text pads itself `px={3}`, so text of your own does the same. It redraws when its row changes or the grid does — not when another row is selected |
+| `sortable` / `resizable` | `boolean`                                                                       | inherits  | Override grid-level setting                                                                                                                                                                                                                                                   |
+| `flexible`               | `boolean`                                                                       | `true`    | Participate in flex width distribution                                                                                                                                                                                                                                        |
+| `filterable`             | `boolean \| FilterConfig`                                                       | —         | `true` (text), `{ type: 'number', min?, max? }`, `{ type: 'multiselect', options? }`                                                                                                                                                                                          |
+| `contextMenu`            | `boolean \| ContextMenuConfig`                                                  | inherits  | Override grid-level context menu. `false` hides entirely. `{ sort?, pin?, group? }` controls sections                                                                                                                                                                         |
+| `aggregate`              | `AggregateName \| (values, rows) => value`                                      | —         | Total this column over each group row, and over the footer. See below                                                                                                                                                                                                         |
+| `AggregateCell`          | `({ cell }) => ReactNode`                                                       | —         | Renders the aggregate. `cell`: `{ value, column, rows, scope }`, `scope` being `'group'` or `'footer'`                                                                                                                                                                        |
+| `editable`               | `boolean \| (row) => boolean`                                                   | inherits  | Whether this column’s cells can be edited — every row, or the rows a predicate says                                                                                                                                                                                           |
+| `editor`                 | `CellEditorType \| CellEditorConfig`                                            | inferred  | `text`/`number`/`checkbox`/`select`. Without one it is read off the value in the cell                                                                                                                                                                                         |
+| `EditCell`               | `({ cell }) => ReactNode`                                                       | —         | An editor of your own, bound to `cell.draft` with `cell.commitEdit()`/`cell.cancelEdit()`                                                                                                                                                                                     |
+| `exportValue`            | `(row: TRow) => value`                                                          | the field | What this column writes to an exported file — an export runs no React, so a `Cell` renderer needs it                                                                                                                                                                          |
+| `list`                   | `'title' \| 'kicker' \| 'subtitle' \| 'end' \| 'field' \| 'detail' \| 'hidden'` | inferred  | Where the column goes in a list item, on a phone                                                                                                                                                                                                                              |
+| `exportFormat`           | `string`                                                                        | —         | The number format its cells wear in a workbook, `'#,##0.00'` or `'yyyy-mm-dd'`                                                                                                                                                                                                |
 
 ### Aggregation
 
@@ -3786,15 +3856,16 @@ with `language` and `code`, `rule`, `image`, `tableWrap`, `table`, `row`, `cell`
 
 Where content will be, while it is being fetched.
 
-| Prop     | Type        | What it does                                                                 |
-| -------- | ----------- | ---------------------------------------------------------------------------- |
-| `lines`  | `number`    | How many bars. Default 1; past that the last one is short.                   |
-| `circle` | `boolean`   | One round bar — an avatar. `width` sets its size and the height follows.     |
-| `label`  | `ReactNode` | Makes it a `role="status"` naming what is on its way. Absent: `aria-hidden`. |
+| Prop     | Type        | What it does                                                                             |
+| -------- | ----------- | ---------------------------------------------------------------------------------------- |
+| `lines`  | `number`    | How many bars. Default 1, which fills the skeleton; past that the last one is short.     |
+| `circle` | `boolean`   | One round bar — an avatar. `width` sets its size (40px without one), the height follows. |
+| `label`  | `ReactNode` | Makes it a `role="status"` naming what is on its way. Absent: `aria-hidden`.             |
 
 ```tsx
 <Skeleton lines={3} label="Loading orders" />
 <Skeleton circle width={10} />
+<Skeleton height={40} /> {/* one bar fills it: an image or a chart placeholder */}
 ```
 
 A `label` belongs on the one skeleton standing for a region and not on each bar — a screen of
@@ -3802,7 +3873,7 @@ placeholders each announcing itself is a screen nobody can listen to, and a regi
 with its text is not reliably announced anyway, so what it really buys is words for somebody who lands
 there. The gloss is a named duration in milliseconds, so it sits outside what `--transitionTime` zeroes
 and stops itself under `prefers-reduced-motion`. It renders on a server. Tree: `skeleton` (+ `bar` with
-`short` and `circle` variants, `gloss`).
+`short`, `circle` and `fill` variants, `gloss`).
 
 ## The catalog (`@box-kite/react/catalog`)
 

package/BOX_KITE_AI_CONTEXT.md

@@ -660,8 +660,15 @@ const wobble = Box.spring({ stiffness: 120, damping: 8 });
   the same commit, with nothing to configure. `Tooltip`, the `Dropdown` popup and the DataGrid column
   menu are all built on it, and each expresses its exit as a `closed` variant in its component styles — plus `up`/`closedUp` on `dropdown.items`, since a popup that opened upward has to collapse upward.
 - **`Box.configure({ transition })`** changes what the base class transitions for the whole engine:
-  a group name, or `false` to declare nothing at all and leave transitions entirely to the props.
+  a group name, a comma list of groups and property names (`'colors, opacity'`), or `false` to declare
+  nothing at all and leave transitions entirely to the props. Anything else transitions `all` and warns.
   Call it before the first render.
+- **An inline phrasing element is `inline-block`**, where every other Box is `block`: `a`, `span`, `label`, `time`, `mark`, `abbr`, `code`, `kbd`, `samp`, `var`, `em`,
+  `strong`, `small`, `b`, `i`, `u`, `s`, `sub`, `sup`, `q`, `cite`, `dfn`, `data`, `output`, `bdi`, `bdo`. It is
+  selected on the rendered element at the base class's specificity, so `<Link>`, `<Box tag="a">` and a
+  `useClassNames` class on a router's `<a>` all stay in their sentence, margin and padding still apply, and a
+  `display` prop or component still wins. Media (`img`, `svg`, `video`, `canvas`, `iframe`) stays block. An `inline-block` never breaks across lines, so a
+  prose link or `<Mark>` that has to wrap with the text sets `display="inline"`.
 
 ---
 
@@ -1263,7 +1270,7 @@ import Textbox from '@box-kite/react/components/textbox';
 <Flex d="column" gap={2} md={{ d: 'row', gap: 4 }}>{children}</Flex>
 
 // Grid
-<Grid gridCols={3} gap={4}>{items.map(i => <Box key={i.id}>{i.content}</Box>)}</Grid>
+<Grid gridTemplateColumns={3} gap={4}>{items.map(i => <Box key={i.id}>{i.content}</Box>)}</Grid>
 
 // Card
 <Box p={4} bgColor="white" borderRadius={8} shadow="medium">{content}</Box>
@@ -1320,6 +1327,11 @@ undefined and rendering it costs nothing, so write the line either way. Pass `{
 second argument for an element inside an `<svg>`. `<Icon>` is this hook plus that flag — reach for
 `Icon` for an icon and this only for everything else.
 
+The class carries the base reset, which is `display: block` except on an `<a>`, `<span>`, `<label>` and the
+other phrasing elements, which are `inline-block`: a `NavLink` styled this way stays in its sentence.
+`{ base: false }` leaves the reset out — for a library's own root (`<ReactFlow>`, `<MiniMap>`, a `BaseEdge`)
+whose margin, display and transitions are its own.
+
 ### Group and Peer
 
 ```tsx
@@ -1456,6 +1468,19 @@ Full reference: `docs/a11y-primitives.md`.
 
 ---
 
+## Field ids, external labels and the invalid state
+
+- **A top-level `id` lands on the control, once.** `<Combobox id="owner">` puts it on the `<input role="combobox">`
+  and nowhere else, as `Textbox`, `Textarea`, `Select` (its button), `Checkbox`, `Switch`, `RadioButton` and
+  `TimeZoneSelect` do, so `<label htmlFor="owner">` names the control. `DateField`, `DatePicker`, `Slider` and
+  `RadioGroup` are groups no `<label>` can name: the `id` goes on the group, and `labelledBy` points it at an
+  external label.
+- **`aria-invalid` draws the error border on every field.** `props={{ 'aria-invalid': true }}` turns the frame of a
+  `Textbox`, `Textarea`, `Select` or `Combobox` `red-500`, through hover and focus, in both themes. A combobox's
+  attribute is on its input and its border on the shell, so the shell matches `:has([aria-invalid="true"])` —
+  restyle it as `combobox: { styles: { has: { '[aria-invalid="true"]': { … } } } }`, the others with
+  `ariaAttr: { invalid: { … } }`. `DateField` and `DatePicker` take an `invalid` prop that does both.
+
 ## Sizes: compact, normal, large
 
 Every built-in component is drawn at one of three sizes, and a size is two CSS variables —
@@ -1521,16 +1546,16 @@ the association needs no `htmlFor`/`id` pair and the whole row is a click target
 nothing wraps the input — the markup is what it always was. `labelProps` styles that `<label>`;
 every other Box prop styles the control itself.
 
-| Component    | Prop                     | What it does                                                                                 |
-| ------------ | ------------------------ | -------------------------------------------------------------------------------------------- |
-| all three    | `label` / `labelProps`   | The wrapping `<label>` and its styles.                                                       |
-| `Checkbox`   | `indeterminate`          | Sets the DOM property **and** `aria-checked="mixed"`, which is what is announced.            |
-| `Switch`     | —                        | `role="switch"` over the same input; Space **and** Enter toggle, Enter does not submit.      |
-| `RadioGroup` | `label`                  | `role="radiogroup"` named by it — a set of radios with nothing over it is a flat list.       |
-| `RadioGroup` | `name`                   | The field every item submits under. Generated when left out.                                 |
-| `RadioGroup` | `value` / `defaultValue` | The selected item's value (a string — the platform's own model for a radio).                 |
-| `RadioGroup` | `onValueChange`          | `(value, { reason, event })` — `click` or `keyboard`. `onChange` is the deprecated spelling. |
-| `RadioGroup` | `orientation`            | `vertical` (default) or `horizontal`. Both arrow pairs navigate either way.                  |
+| Component    | Prop                     | What it does                                                                                                                                       |
+| ------------ | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------- |
+| all three    | `label` / `labelProps`   | The wrapping `<label>` and its styles.                                                                                                             |
+| `Checkbox`   | `indeterminate`          | Sets the DOM property **and** `aria-checked="mixed"`, which is what is announced.                                                                  |
+| `Switch`     | —                        | `role="switch"` over the same input; Space **and** Enter toggle, Enter does not submit.                                                            |
+| `RadioGroup` | `label`                  | `role="radiogroup"` named by it — a set of radios with nothing over it is a flat list.                                                             |
+| `RadioGroup` | `name`                   | The field every item submits under. Generated when left out.                                                                                       |
+| `RadioGroup` | `value` / `defaultValue` | The selected item's value (a string — the platform's own model for a radio).                                                                       |
+| `RadioGroup` | `onValueChange`          | `(value, { reason, event })` — `click` or `keyboard`. `onChange` is the deprecated spelling.                                                       |
+| `RadioGroup` | `orientation`            | `vertical` (default) or `horizontal`, which wraps and keeps the label on a line of its own above the radios. Both arrow pairs navigate either way. |
 
 Arrow keys move **and select** inside a group, wrapping at both ends and skipping disabled items;
 Tab enters the group once and leaves it once, because a native radio set is already a single tab
@@ -2660,6 +2685,51 @@ function TrendCell({ cell }: { cell: CellModel<Row> }) {
 <DataGrid data={rows} def={{ rowKey: 'id', columns: [{ key: 'trend', header: 'Last 12 months', width: 180, Cell: TrendCell }] }} />;
 ```
 
+### Theming a React Flow canvas — `FlowContainer`
+
+`ChartContainer`'s move for diagrams. `@box-kite/react/components/flow` (server-safe, imports nothing from xyflow) is a Box
+that declares React Flow's `--xy-*` variables from the palette in both themes, so the canvas — background, pattern, edges,
+handles, built-in nodes, minimap, controls, selection box, edge labels — names no colour and follows the page:
+
+```tsx
+import { Background, Controls, MiniMap, ReactFlow } from '@xyflow/react';
+import '@xyflow/react/dist/style.css';
+import { FlowContainer, flowColorMode } from '@box-kite/react/components/flow';
+
+function Canvas() {
+  const [theme] = Box.useTheme();
+
+  return (
+    <FlowContainer height={120}>
+      <ReactFlow nodes={nodes} edges={edges} colorMode={flowColorMode(theme)} fitView>
+        <Background />
+        <Controls />
+        <MiniMap />
+      </ReactFlow>
+    </FlowContainer>
+  );
+}
+```
+
+| Prop     | What it is                                                                                                                       |
+| -------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| `tokens` | Repaints a role: `{ selection: 'emerald-500' }` for both themes, `{ surface: { light: 'base-50', dark: 'base-950' } }` per theme |
+| `motion` | `'static'` zeroes every Box transition inside the canvas, for nodes moved or resized every frame                                 |
+
+- **Eight roles**, each a custom property a custom node can read: `--flow-surface`, `--flow-panel`, `--flow-text`, `--flow-border`,
+  `--flow-grid`, `--flow-edge`, `--flow-selection`, `--flow-handle`. Defaults are `base`/`accent`, so `Box.palette()` reaches them.
+- **The defaults are the `flowContainer` style node**, so one override repaints every canvas in an app:
+  `Box.components({ flowContainer: { styles: { vars: { 'flow-selection': 'emerald-500' } } } })`; `tokens` is the per-canvas answer.
+- **One `--xy-*` variable is `vars`** (`vars={{ 'xy-edge-stroke-width': '2' }}`); a prop on `<MiniMap>`/`<Background>` still wins.
+- **`colorMode={flowColorMode(theme)}`** keeps React Flow's own `.dark` class in step with the page. A canvas in another theme sits
+  in `<Box.Theme use="local">`; never `colorMode="light"` under a dark page — `.light` is no theme boundary, so the two mix.
+- **A custom node is invisible to the keyboard** — xyflow removes every node's focus outline. Spread `flowNodeStyles` on its
+  root (an outline while xyflow's wrapper is `:focus-visible`) and `flowNodeSelectedStyles` when its `selected` prop is true;
+  both are outlines in the `selection` role, so they survive forced colours. A custom edge on `BaseEdge` takes `flowEdgeStyles`
+  through `useClassNames(flowEdgeStyles, { svg: true, base: false })`.
+- Colour props refuse `var()`, so a custom node reads a role through `css`:
+  `css={{ backgroundColor: 'var(--flow-panel)', borderColor: 'var(--flow-border)', color: 'var(--flow-text)' }}`.
+
 ---
 
 ## Key Reminders for AI Assistants
@@ -2677,7 +2747,7 @@ function TrendCell({ cell }: { cell: CellModel<Row> }) {
 11. **Size shortcuts**: `width="fit"` = 100%, `width="fit-screen"` = 100vw, `width="1/2"` = 50%
 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
+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, and a React Flow canvas goes in `<FlowContainer>` with `colorMode={flowColorMode(theme)}`
 15. **All sizing props use divider 4** — `width`, `height`, `minWidth`, `maxWidth`, `minHeight`, `maxHeight` are NOT direct pixels. `height={10}` = 2.5rem = 40px
 16. **A state your own code sets is a nested prop too**: `dataAttr={{ 'state=open': { … } }}` → `[data-state="open"]`, `ariaAttr={{ selected: { … } }}` → `[aria-selected="true"]`, `has={{ ':checked': { … } }}`, `not={{ hover: { … } }}`, `nth={{ odd: { … } }}`. The attribute itself still goes in `props`
 17. **Somebody else's state is `group`/`peer`**: `group={{ 'card/hover': { … } }}` → `.card:hover .x`, `peer={{ 'agree/checked': { … } }}` → `.agree:checked ~ .x`. The ancestor or sibling carries the class via `className`; `hoverGroup` and its four siblings are the older spelling
@@ -2790,27 +2860,27 @@ named ones carry the reason.
 
 ### ColumnType
 
-| Prop                     | Type                                                                            | Default   | Description                                                                                                                                     |
-| ------------------------ | ------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
-| `key`                    | `Key`                                                                           | required  | Column identifier (maps to TRow property)                                                                                                       |
-| `header`                 | `string`                                                                        | —         | Header text                                                                                                                                     |
-| `width`                  | `number`                                                                        | `200`     | Base width in px                                                                                                                                |
-| `align`                  | `'start' \| 'end' \| 'center' \| 'left' \| 'right'`                             | `'left'`  | Cell alignment. `start`/`end` follow the reading order; `left`/`right` stay on the screen side they name                                        |
-| `pin`                    | `'START' \| 'END'` (also `'LEFT'`/`'RIGHT'`)                                    | —         | Pin to an edge of the **inline axis** (sticky on scroll), so it holds under either `dir`. `LEFT`/`RIGHT` are the older spelling of the same two |
-| `columns`                | `ColumnType[]`                                                                  | —         | Nested columns (grouped header)                                                                                                                 |
-| `Cell`                   | `({ cell }) => ReactNode`                                                       | —         | Custom renderer. `cell`: `{ value, row, column, grid }`. It redraws when its row changes or the grid does — not when another row is selected    |
-| `sortable` / `resizable` | `boolean`                                                                       | inherits  | Override grid-level setting                                                                                                                     |
-| `flexible`               | `boolean`                                                                       | `true`    | Participate in flex width distribution                                                                                                          |
-| `filterable`             | `boolean \| FilterConfig`                                                       | —         | `true` (text), `{ type: 'number', min?, max? }`, `{ type: 'multiselect', options? }`                                                            |
-| `contextMenu`            | `boolean \| ContextMenuConfig`                                                  | inherits  | Override grid-level context menu. `false` hides entirely. `{ sort?, pin?, group? }` controls sections                                           |
-| `aggregate`              | `AggregateName \| (values, rows) => value`                                      | —         | Total this column over each group row, and over the footer. See below                                                                           |
-| `AggregateCell`          | `({ cell }) => ReactNode`                                                       | —         | Renders the aggregate. `cell`: `{ value, column, rows, scope }`, `scope` being `'group'` or `'footer'`                                          |
-| `editable`               | `boolean \| (row) => boolean`                                                   | inherits  | Whether this column’s cells can be edited — every row, or the rows a predicate says                                                             |
-| `editor`                 | `CellEditorType \| CellEditorConfig`                                            | inferred  | `text`/`number`/`checkbox`/`select`. Without one it is read off the value in the cell                                                           |
-| `EditCell`               | `({ cell }) => ReactNode`                                                       | —         | An editor of your own, bound to `cell.draft` with `cell.commitEdit()`/`cell.cancelEdit()`                                                       |
-| `exportValue`            | `(row: TRow) => value`                                                          | the field | What this column writes to an exported file — an export runs no React, so a `Cell` renderer needs it                                            |
-| `list`                   | `'title' \| 'kicker' \| 'subtitle' \| 'end' \| 'field' \| 'detail' \| 'hidden'` | inferred  | Where the column goes in a list item, on a phone                                                                                                |
-| `exportFormat`           | `string`                                                                        | —         | The number format its cells wear in a workbook, `'#,##0.00'` or `'yyyy-mm-dd'`                                                                  |
+| Prop                     | Type                                                                            | Default   | Description                                                                                                                                                                                                                                                                   |
+| ------------------------ | ------------------------------------------------------------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `key`                    | `Key`                                                                           | required  | Column identifier (maps to TRow property)                                                                                                                                                                                                                                     |
+| `header`                 | `string`                                                                        | —         | Header text                                                                                                                                                                                                                                                                   |
+| `width`                  | `number`                                                                        | `200`     | Base width in px                                                                                                                                                                                                                                                              |
+| `align`                  | `'start' \| 'end' \| 'center' \| 'left' \| 'right'`                             | `'left'`  | Cell alignment. `start`/`end` follow the reading order; `left`/`right` stay on the screen side they name                                                                                                                                                                      |
+| `pin`                    | `'START' \| 'END'` (also `'LEFT'`/`'RIGHT'`)                                    | —         | Pin to an edge of the **inline axis** (sticky on scroll), so it holds under either `dir`. `LEFT`/`RIGHT` are the older spelling of the same two                                                                                                                               |
+| `columns`                | `ColumnType[]`                                                                  | —         | Nested columns (grouped header)                                                                                                                                                                                                                                               |
+| `Cell`                   | `({ cell }) => ReactNode`                                                       | —         | Custom renderer. `cell`: `{ value, row, column, grid }`. It fills the cell **edge to edge, with no padding** — the built-in text pads itself `px={3}`, so text of your own does the same. It redraws when its row changes or the grid does — not when another row is selected |
+| `sortable` / `resizable` | `boolean`                                                                       | inherits  | Override grid-level setting                                                                                                                                                                                                                                                   |
+| `flexible`               | `boolean`                                                                       | `true`    | Participate in flex width distribution                                                                                                                                                                                                                                        |
+| `filterable`             | `boolean \| FilterConfig`                                                       | —         | `true` (text), `{ type: 'number', min?, max? }`, `{ type: 'multiselect', options? }`                                                                                                                                                                                          |
+| `contextMenu`            | `boolean \| ContextMenuConfig`                                                  | inherits  | Override grid-level context menu. `false` hides entirely. `{ sort?, pin?, group? }` controls sections                                                                                                                                                                         |
+| `aggregate`              | `AggregateName \| (values, rows) => value`                                      | —         | Total this column over each group row, and over the footer. See below                                                                                                                                                                                                         |
+| `AggregateCell`          | `({ cell }) => ReactNode`                                                       | —         | Renders the aggregate. `cell`: `{ value, column, rows, scope }`, `scope` being `'group'` or `'footer'`                                                                                                                                                                        |
+| `editable`               | `boolean \| (row) => boolean`                                                   | inherits  | Whether this column’s cells can be edited — every row, or the rows a predicate says                                                                                                                                                                                           |
+| `editor`                 | `CellEditorType \| CellEditorConfig`                                            | inferred  | `text`/`number`/`checkbox`/`select`. Without one it is read off the value in the cell                                                                                                                                                                                         |
+| `EditCell`               | `({ cell }) => ReactNode`                                                       | —         | An editor of your own, bound to `cell.draft` with `cell.commitEdit()`/`cell.cancelEdit()`                                                                                                                                                                                     |
+| `exportValue`            | `(row: TRow) => value`                                                          | the field | What this column writes to an exported file — an export runs no React, so a `Cell` renderer needs it                                                                                                                                                                          |
+| `list`                   | `'title' \| 'kicker' \| 'subtitle' \| 'end' \| 'field' \| 'detail' \| 'hidden'` | inferred  | Where the column goes in a list item, on a phone                                                                                                                                                                                                                              |
+| `exportFormat`           | `string`                                                                        | —         | The number format its cells wear in a workbook, `'#,##0.00'` or `'yyyy-mm-dd'`                                                                                                                                                                                                |
 
 ### Aggregation
 
@@ -3786,15 +3856,16 @@ with `language` and `code`, `rule`, `image`, `tableWrap`, `table`, `row`, `cell`
 
 Where content will be, while it is being fetched.
 
-| Prop     | Type        | What it does                                                                 |
-| -------- | ----------- | ---------------------------------------------------------------------------- |
-| `lines`  | `number`    | How many bars. Default 1; past that the last one is short.                   |
-| `circle` | `boolean`   | One round bar — an avatar. `width` sets its size and the height follows.     |
-| `label`  | `ReactNode` | Makes it a `role="status"` naming what is on its way. Absent: `aria-hidden`. |
+| Prop     | Type        | What it does                                                                             |
+| -------- | ----------- | ---------------------------------------------------------------------------------------- |
+| `lines`  | `number`    | How many bars. Default 1, which fills the skeleton; past that the last one is short.     |
+| `circle` | `boolean`   | One round bar — an avatar. `width` sets its size (40px without one), the height follows. |
+| `label`  | `ReactNode` | Makes it a `role="status"` naming what is on its way. Absent: `aria-hidden`.             |
 
 ```tsx
 <Skeleton lines={3} label="Loading orders" />
 <Skeleton circle width={10} />
+<Skeleton height={40} /> {/* one bar fills it: an image or a chart placeholder */}
 ```
 
 A `label` belongs on the one skeleton standing for a region and not on each bar — a screen of
@@ -3802,7 +3873,7 @@ placeholders each announcing itself is a screen nobody can listen to, and a regi
 with its text is not reliably announced anyway, so what it really buys is words for somebody who lands
 there. The gloss is a named duration in milliseconds, so it sits outside what `--transitionTime` zeroes
 and stops itself under `prefers-reduced-motion`. It renders on a server. Tree: `skeleton` (+ `bar` with
-`short` and `circle` variants, `gloss`).
+`short`, `circle` and `fill` variants, `gloss`).
 
 ## The catalog (`@box-kite/react/catalog`)