@box-kite/react 1.0.0 → 2.0.0

package/BOX_KITE_AI_CONTEXT.md

@@ -1,6 +1,6 @@
 # @box-kite/react - AI Assistant Context
 
-Runtime CSS-in-JS library. `Box` component accepts 212 CSS props and generates CSS classes at runtime. Same prop values share a single class.
+Runtime CSS-in-JS library. `Box` component accepts 221 CSS props and generates CSS classes at runtime. Same prop values share a single class.
 
 ---
 
@@ -51,9 +51,13 @@ NEVER use `<Box tag="...">` when a component exists. NEVER use `<Box display="fl
 | `<Box tag="nav/header/footer/main">` | `<Nav>/<Header>/<Footer>/<Main>` | `components/semantics` |
 | `<Box tag="section/article/aside">`  | `<Section>/<Article>/<Aside>`    | `components/semantics` |
 | `<Box tag="svg/path/circle/rect">`   | `<Svg>/<Path>/<Circle>/<Rect>`   | `components/svg`       |
+| `<Box tag="dialog">`                 | `<Dialog>/<AlertDialog>`         | `components/dialog`    |
+| a menu button and its menu           | `<Menu>`                         | `components/menu`      |
+| a tablist over one panel at a time   | `<Tabs>`                         | `components/tabs`      |
+| a message sent from anywhere         | `<Toaster>` + `toast()`          | `components/toaster`   |
 | a lucide/Tabler icon, styled         | `<Icon>`                         | `components/icon`      |
 
-All imports from `@box-kite/react/components/...`. Semantics also export: `Mark`, `Figure`, `Figcaption`, `Details`, `Summary`, `Menu`, `Time`.
+All imports from `@box-kite/react/components/...`. Semantics also export: `Mark`, `Figure`, `Figcaption`, `Details`, `Summary`, `MenuList` (the semantic `<menu>`; the menu **button** is `Menu` from `components/menu`), `Time`.
 
 ---
 
@@ -131,8 +135,8 @@ Every axis prop was already logical — `mx` is `margin-inline`, `px` is `paddin
 
 - **The arrow keys follow the reading order.** `useRovingFocus` reads the element's _resolved_ direction when a sideways arrow arrives, so in a right-to-left list or grid `ArrowLeft` moves to the **next** item — which is what APG asks for. Nothing is configured; a `dir` anywhere above the list is enough, and a vertical list pays nothing. Tab, Home and End never flip.
 - **A DataGrid column pins to `'START'` or `'END'`** of the inline axis rather than to a screen side, so it stays where the reading begins under either direction; `'LEFT'`/`'RIGHT'` are the older spelling of those two. `align` gained `'start'`/`'end'`, the resize handle grows a column towards the reading end, and the column menu's _Pin Left_ reads _Pin Right_ when that is the side it would pin to.
-- **A popup carries the direction out of the tree with it.** `Overlay` portals into a container that is a child of the body, where nothing of the declaration site is inherited, so it measures the direction it was declared in and writes it back on as `dir` — `Tooltip`, the `Dropdown` popup and the grid's column menu all get that.
-- **What stays physical, on purpose**: `Overlay` positions its layer with a transform in page coordinates, so its box is anchored at the page's own origin either way, and the grid's loading bar sweeps the same way in both. A measured pixel has no reading order.
+- **A popup keeps the direction it was declared in.** `Overlay` stays in the subtree it was declared in — the top layer inherits normally — so `Tooltip`, the `Dropdown` popup and the grid's column menu simply inherit it. Only on the portal fallback, where the container is a child of the body and nothing of the declaration site reaches it, does it read the direction off its anchor and write it back on as `dir`.
+- **What stays physical, on purpose**: the grid's loading bar sweeps the same way in both. (`Overlay` no longer positions in page coordinates at all — a `side` is logical, so a layer beside its anchor mirrors with the reading order.)
 
 ### Layout
 
@@ -189,6 +193,90 @@ All sizing, spacing, and positioning props also accept percentage strings: `p="5
 | `willChange`                                                                                                                                                                         | will-change                             | `'transform'`, `'opacity'`, `'filter'`, `'scroll-position'`, `'contents'`, `'auto'`. A hint with a real cost (a promoted layer holds memory), so it belongs on the few elements that animate, not on a list                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `cursor` / `pointerEvents` / `userSelect`                                                                                                                                            | misc                                    | string values. For `transition`, `animation` and the transform props see _Animation and transitions_ below                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
 
+### Anchor positioning — a floating layer with no JavaScript
+
+CSS Anchor Positioning as six props, so a tooltip, popup or badge is placed by the browser instead of measured in an effect. The anchor names itself; the layer says which anchor and which cell of the 3×3 grid around it:
+
+```tsx
+<Button anchorName="menu-trigger">Options</Button>
+
+<Box position="absolute" positionAnchor="menu-trigger" positionArea="block-end span-all" positionTryFallbacks="flip-block" mt={2}>
+  …
+</Box>
+```
+
+| Prop                   | CSS                      | Values                                                                                                                                      |
+| ---------------------- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| `anchorName`           | `anchor-name`            | a name with or without `--` (`"trigger"` → `--trigger`), or `'none'`. Global to the document, so one instance needs one name                |
+| `positionAnchor`       | `position-anchor`        | the same name, or `'auto'` / `'none'`. Needs `position="absolute"` (or `"fixed"`) beside it                                                 |
+| `positionArea`         | `position-area`          | one or two keywords, **block axis first**, both from one family: `'block-end center'`, `'top left'`, `'center inline-end'`, `'span-all'`    |
+| `positionTryFallbacks` | `position-try-fallbacks` | `'flip-block'`, `'flip-inline'`, `'flip-start'`, space-combined into one candidate, comma-separated into a list tried in order, or `'none'` |
+| `positionTryOrder`     | `position-try-order`     | `'normal'` (first fit), `'most-width'`, `'most-height'`, `'most-block-size'`, `'most-inline-size'`                                          |
+| `positionVisibility`   | `position-visibility`    | `'always'`, `'anchors-visible'`, `'no-overflow'`, `'anchors-visible no-overflow'`                                                           |
+
+`justifySelf` and `alignSelf` also take `'anchor-center'`. Offset a layer from its anchor with an ordinary margin — there is no offset prop, because `mt={2}` already is one.
+
+The keyword families do not mix: physical (`top`/`bottom` × `left`/`right`), logical (`block-start`/`block-end` × `inline-start`/`inline-end`), their `self-` twins, the `start`/`end` shorthand, its `self-` twin, and the `y-*` × `x-*` pair — with `center` and `span-all` neutral in all of them. So `'block-end inline-start'` is a value and `'top inline-start'` is not; a mixed pair emits no rule and no class, as does an unknown flip keyword or a name that is not an identifier.
+
+**Two traps, both measured in Chrome 152 rather than read off the spec:**
+
+- **A candidate position has to fit on _both_ axes to be taken**, so an overflow the flips cannot fix disqualifies every one of them and the layer silently stays where it started. `positionArea="block-end center"` with a layer wider than its anchor overflows the centre column, and `flip-block` then does nothing at all. Span the axis being kept — `"block-end span-all"` — and it flips.
+- **`positionVisibility` hides at paint time**, so the layer keeps its box and its computed `visibility` still reads `visible` (`checkVisibility()` agrees). Only painting and hit-testing stop, so a test asserting it needs a screenshot.
+
+Chrome 125+, Firefox 147+, Safari 26+. Where it is missing the layer renders unpositioned, so the portable path is `useAnchorPosition` (which measures instead) or `Overlay`, which is that hook plus the top layer.
+
+A length can also come off the anchor. Every sizing prop takes an `anchor-size()` value and every single-side inset prop an `anchor()` one, so a layer sizes and places itself against its anchor with nothing measured:
+
+```tsx
+<Box position="fixed" positionAnchor="menu-trigger" minWidth="anchor-size(width)" maxHeight="anchor-size(height, 20rem)" />
+<Box position="fixed" top="anchor(bottom)" insetStart="anchor(left)" />
+```
+
+`anchor-size()` takes an axis (`width`, `height`, `block`, `inline`, `self-block`, `self-inline`), `anchor()` an edge (`top`, `right`, `bottom`, `left`, `start`, `end`, `self-start`, `self-end`, `center`, `inside`, `outside`) or a percentage along one. Both take an optional anchor name first — with the same optional `--` — and an optional fallback after a comma. A bare `anchor()` is rejected (CSS needs the edge); a bare `anchor-size()` is not (it means the layer's own axis).
+
+### `useAnchorPosition` — the placement as one hook
+
+`@box-kite/react/anchor` turns a side and an alignment into the props above, and measures instead where the browser has no anchor positioning. It renders nothing and owns no state beyond that.
+
+```tsx
+import { useAnchorPosition } from '@box-kite/react/anchor';
+
+const { css, anchorProps, layerProps } = useAnchorPosition({ side: 'bottom', align: 'start', offset: 2, matchWidth: true });
+
+<Button {...anchorProps} onClick={toggle}>
+  Options
+</Button>;
+{
+  isOpen && (
+    <Box {...layerProps} component="menu">
+      …
+    </Box>
+  );
+}
+```
+
+| Option       | Default    | What it means                                                                                                       |
+| ------------ | ---------- | ------------------------------------------------------------------------------------------------------------------- |
+| `side`       | `'bottom'` | `'top'`/`'bottom'` are the block axis, `'start'`/`'end'` the inline one — so a side mirrors in a right-to-left page |
+| `align`      | `'center'` | which of the anchor's edges to line up with on the other axis                                                       |
+| `offset`     | `0`        | the gap, on the ÷4 spacing scale — emitted as the margin on the side facing the anchor, and a flip flips it too     |
+| `flip`       | `true`     | `positionTryFallbacks`: the side's own axis, then the alignment's, then both                                        |
+| `matchWidth` | `false`    | `minWidth="anchor-size(width)"`                                                                                     |
+| `name`       | generated  | the anchor's name; one per instance unless you pass one                                                             |
+| `anchor`     | —          | an anchor handed to the hook rather than one it spreads props onto — the name is written on in an effect            |
+| `trackSide`  | `false`    | whether `side` in the result reports where the layer ended up, which costs one read after layout                    |
+
+`css` in the result says which path ran: `true` is the browser placing the layer with no JavaScript at all, `false` is the measured fallback (flip to the opposite side, then shift along the other axis to stay in the viewport). `side` is where the layer actually is — the requested side unless `trackSide` is on and a flip moved it.
+
+**Three more things worth knowing, all measured:**
+
+- **The layer is `position: fixed`**, so it escapes every `overflow: hidden` ancestor without a portal — but not a _transformed_ ancestor, which is a fixed element's containing block, and not the page's stacking order. `Overlay` is this hook plus the browser's top layer, which beats both, and is still the answer when the layer has to come out on top of everything.
+- **Three fallbacks, not one.** A candidate has to fit on _both_ axes, so a lone `flip-block` does nothing at all for a layer that overflows the _cross_ axis — the browser leaves it pressed against the edge of the viewport. `flip` therefore offers the side's axis, the alignment's, and both, and a menu aligned to its trigger's end mirrors to the other end rather than running off the page.
+- **Which side the browser chose costs the entrance.** `trackSide` reads the _used_ `position-area`, and that read is the style resolution `@starting-style` computes its before-change style from — so a class that depends on the answer lands after the entrance has already been decided. The exit runs long afterwards and can use it (`dropdown.items` has `closedUp` and no `up`).
+- **A used `position-area` is not the value that went in.** Chrome 152 drops a `span-all` half (`block-end span-all` reads back `block-end`) and collapses a value naming both axes into the `start`/`end` shorthand, where position names the axis: `block-end span-inline-end` reads back `end span-end`, and `start span-end` once it has flipped.
+- **A flip is sticky, and in the top layer it is never re-evaluated on scroll at all.** Once the browser takes one it keeps it until the layer is laid out afresh, which is what stops it oscillating as the page scrolls: hiding the layer and showing it again re-evaluates. So a popup that mounts when it opens always picks the side that fits, while one that stays mounted keeps the side it first chose. For an element in the **top layer** — which is every pre-built layer: `Overlay`, and so `Tooltip`, the `Dropdown` popup and the DataGrid menu, plus `Popover` — Chrome does not re-evaluate on scroll even once the side has run out of room, so a layer open across a long scroll slides past the viewport edge. Measured in Chrome 152 against an otherwise identical non-top-layer element, which does flip; only leaving and re-entering the top layer re-arms it.
+- **The anchor's name is an inline style, not a prop.** An identity is per instance, so a class for it would be a rule per instance that is never freed — the same reason a sparkline's `d` is an attribute while its stroke is a class. Everything shared — the area, the flip, the margin, the width — is an ordinary prop.
+
 ### Colours, and the opacity modifier
 
 The palette is **Tailwind 4.3's, in OKLCH**: twenty-six families of eleven steps (`50`–`950`) — the five
@@ -980,10 +1068,20 @@ import Textbox from '@box-kite/react/components/textbox';
 <Box position="fixed" top={0} left={0} right={0} bottom={0} bgColor="black" opacity={0.5} zIndex={50} />
 ```
 
-**Portals**: `Overlay` (`components/overlay`) renders its children into `#box-kite-portal` at the place it
-is declared, so they escape `overflow: hidden` and clipped ancestors. No ARIA, no open state — it is
-positioning only. For a _description of a control_, use `Tooltip` instead (below): it is the same
-layer with the APG pattern on it.
+**Floating layers**: `Overlay` (`components/overlay`) anchors a layer to a trigger (`anchor`, `side`, `align`,
+`offset`, `flip`, `matchWidth` — the vocabulary `useAnchorPosition` and `Tooltip` share) and renders it
+**where it was declared, in the browser's top layer** (`popover="manual"`, shown on mount), so it escapes
+`overflow: hidden`, clipped and transformed ancestors and the stacking order while still inheriting the
+theme, the custom properties and the direction around it. `manual` because it owns no dismissal — and no
+ARIA and no open state either: it is positioning only. **Never declare one inside its trigger**: a
+listbox or a menu inside a `<button>` is unreachable content, which the portal used to hide by moving it
+elsewhere. **One cost comes with the top layer**: the layer keeps the side it chose when it opened, because
+Chrome never re-evaluates `position-try-fallbacks` on scroll for a top-layer element (measured in 152) — so
+a layer left open while the page scrolls slides past the viewport edge rather than flipping. Every open
+picks the right side; close a layer if the page can scroll far underneath it. Where the browser has no
+Popover API it is portalled into `#box-kite-portal` instead, and that path measures, so it flips. For a
+_panel a user interacts with_, use `Popover` (below); for a _description of a control_, use `Tooltip`.
+Both are that layer with a pattern on it.
 
 ### Styling an element Box cannot render (`useClassNames`)
 
@@ -1141,7 +1239,7 @@ import RadioButton from '@box-kite/react/components/radioButton';
 <Checkbox label="Select all rows" name="rows" indeterminate />
 <Switch label="Email notifications" name="notify" defaultChecked />
 
-<RadioGroup label="Plan" name="plan" defaultValue="free" onChange={(plan, { reason }) => setPlan(plan)}>
+<RadioGroup label="Plan" name="plan" defaultValue="free" onValueChange={(plan, { reason }) => setPlan(plan)}>
   <RadioGroup.Item value="free" label="Free" />
   <RadioGroup.Item value="pro" label="Pro" />
   <RadioGroup.Item value="team" label="Team" disabled />
@@ -1155,16 +1253,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` | `onChange`               | `(value, { reason, event })` — `click` or `keyboard`.                                   |
-| `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`. 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
@@ -1213,6 +1311,644 @@ next to the markup. Everything else is a Box prop, and `props` takes the `<form>
 
 ---
 
+## Popover Component
+
+```tsx
+import Popover from '@box-kite/react/components/popover';
+
+<Popover label="Filters" trigger={(t) => <Button {...t}>Filters</Button>}>
+  <Checkbox label="Only mine" />
+</Popover>;
+```
+
+A panel anchored to a trigger, on the platform's **Popover API**. The `trigger` is a render prop (the
+`ref` and the ARIA have to land on the control itself) and the **children are the panel's content** —
+the other way round from `Tooltip`, whose `content` is a short description and whose `children` are the
+trigger. The trigger must be a **button**: the toggle is the browser's own `popovertarget`.
+
+**There is no portal.** The panel is in the top layer, so it paints above every stacking context and
+outside every clipped ancestor — and because it is never moved, it keeps the theme, the custom
+properties, the direction and the tab order it was declared in. Use `Popover` rather than `Overlay`
+whenever the layer is a panel a user interacts with; `Overlay` is in the same top layer, but it is
+positioning only and light-dismisses nothing.
+
+| Prop                   | Default             | What it does                                                                        |
+| ---------------------- | ------------------- | ----------------------------------------------------------------------------------- |
+| `trigger`              | —                   | Render prop given `{ ref, props }`. Spread onto a **button**.                       |
+| `children`             | —                   | The panel's content. Rendered whether or not it is open.                            |
+| `label` / `labelledBy` | —                   | The panel's accessible name. `role="dialog"` has none of its own — give it one.     |
+| `open` / `defaultOpen` | —                   | Controlled / uncontrolled open state.                                               |
+| `onOpenChange`         | —                   | `(open, { reason, event })` — `trigger`, `escape`, `outside-pointer`, `imperative`. |
+| `side` / `align`       | `bottom` / `center` | Which side of the trigger the panel sits on, and how it lines up.                   |
+| `offset`               | `2`                 | The gap, on the ÷4 scale — 8px.                                                     |
+| `flip`                 | `true`              | Whether a side with no room is swapped for its opposite.                            |
+| `matchWidth`           | `false`             | Whether the panel is at least as wide as its trigger.                               |
+| `autoFocus`            | `true`              | Whether opening moves focus into the panel. An `autofocus` inside wins.             |
+
+What the component supplies, because the `popover` attribute supplies none of it: `role="dialog"`, the
+name, and `aria-expanded`/`aria-haspopup="dialog"`/`aria-controls` on the trigger. What the **platform**
+supplies, so it is not reimplemented: the top layer, light dismiss on Escape and on an outside press,
+and focus return when the panel is hidden.
+
+Three traps, all measured in Chrome 152:
+
+- **The panel is always rendered**; closed is `display: none`, not unmounted. So the exit is a CSS
+  transition (`transitionBehavior="allow-discrete"`, already in the component styles) and **not**
+  `<Presence>` — nothing leaves the DOM. Gate expensive children yourself: `{open ? <Heavy /> : null}`.
+- **A close cannot be refused.** `beforetoggle` is cancelable opening and not closing, so a controlled
+  `<Popover open>` hears about a light dismiss only after it has happened; keep `open` true and the
+  component re-shows the panel.
+- **Never put an `onClick` toggle on the trigger.** Light dismiss closes on `pointerdown`, so the
+  `click` after it reads "closed" and reopens the panel — pressing the trigger would never close it.
+  That is exactly why the toggle is handed to `popovertarget`.
+
+Where the browser has no Popover API the panel falls back to a portalled `Overlay` with `useDismiss`
+and `useFocusReturn`. Same props, same styling; what is lost is what a portal costs.
+
+---
+
+## Dialog Component
+
+```tsx
+import Dialog, { AlertDialog } from '@box-kite/react/components/dialog';
+
+<Dialog trigger={(t) => <Button {...t}>Rename</Button>}>
+  <Dialog.Title>Rename this view</Dialog.Title>
+  <Dialog.Description>The name is only shown to you.</Dialog.Description>
+  <Textbox name="name" props={{ 'aria-label': 'Name' }} />
+</Dialog>;
+```
+
+A real `<dialog>` shown with **`showModal()`**, which is where the whole pattern comes from: the top
+layer, the `::backdrop`, an inert page behind it, Escape, focus containment and focus return are all the
+browser's. There is no focus trap here, no `aria-hidden` sweep over the page and no `z-index` — measured
+in Chrome 152, a modal dialog paints over a `position: fixed` sibling with `z-index: 9999`.
+
+| Prop                   | Default | What it does                                                                        |
+| ---------------------- | ------- | ----------------------------------------------------------------------------------- |
+| `trigger`              | —       | Render prop given `{ ref, props }`. Optional — open it from anywhere instead.       |
+| `children`             | —       | The dialog's content. Rendered whether or not it is open.                           |
+| `open` / `defaultOpen` | —       | Controlled / uncontrolled open state.                                               |
+| `onOpenChange`         | —       | `(open, { reason, event })` — `trigger`, `escape`, `outside-pointer`, `imperative`. |
+| `label` / `labelledBy` | —       | The name, when no `Dialog.Title` supplies one.                                      |
+| `describedBy`          | —       | The description, when no `Dialog.Description` supplies one.                         |
+| `modal`                | `true`  | `showModal()`. `false` is `show()`: no backdrop, nothing inert.                     |
+| `dismissible`          | `true`  | Whether a press outside closes it.                                                  |
+| `lockScroll`           | `modal` | Whether the page behind it stops scrolling.                                         |
+| `initialFocus`         | —       | Where focus lands, instead of the first focusable thing inside.                     |
+
+`Dialog.Title` and `Dialog.Description` are how it is named: rendering a title writes `aria-labelledby`
+on the dialog and rendering a description writes `aria-describedby`. **Neither attribute is written when
+the part is absent**, so a reference never dangles — and a dialog showing no heading wants `label`,
+`labelledBy` or `describedBy` instead. Both are Boxes (`dialog.title`, `dialog.description` in the style
+tree), and `AlertDialog` carries the same two.
+
+```tsx
+const cancel = useRef(null);
+
+<AlertDialog initialFocus={cancel} trigger={(t) => <Button {...t}>Delete</Button>}>
+  <AlertDialog.Title>Delete this view?</AlertDialog.Title>
+  <AlertDialog.Description>Nothing here can be undone.</AlertDialog.Description>
+  <Button bgColor="rose-600">Delete</Button>
+  <Button ref={cancel}>Cancel</Button>
+</AlertDialog>;
+```
+
+`AlertDialog` is `role="alertdialog"` — the content is an alert rather than a panel, so the name and the
+description are announced together on open. It is always modal and **never dismissed by a press
+outside**; Escape still closes it, because a keyboard user must always have a way out. `initialFocus` is
+APG's requirement that focus land on the least destructive action, so a deletion cannot be confirmed by
+reflex. It takes every `Dialog` prop but `modal`, `dismissible` and `lockScroll`, which are not choices
+it gets to make.
+
+Four traps, all measured in Chrome 152:
+
+- **The dialog is always rendered**; closed is `display: none`, not unmounted — the same shape as
+  `Popover`. The exit is a CSS transition (`transitionBehavior="allow-discrete"`, already in the
+  component styles, and it covers the `::backdrop` too) and **not** `<Presence>`. Gate expensive
+  children yourself: `{open ? <Heavy /> : null}`.
+- **A close cannot be refused.** `cancel` is cancelable, but the browser has already closed the dialog
+  by the time `onOpenChange` runs, so a controlled `<Dialog open>` hears about a dismissal afterwards
+  and keeping `open` true shows it again. `dismissible={false}` is how a decision is made unavoidable.
+- **For a modal dialog the backdrop _is_ the dialog element.** A press on it targets the `<dialog>`, so
+  every containment test calls it inside. The platform's `closedby="any"` gets this right and the
+  component writes it; where the browser has not got it yet, the press is measured against the dialog's
+  own box instead.
+- **The platform does not stop the page scrolling** (measured: `overflow` stays `visible` while a modal
+  dialog is open). That is what `lockScroll` is — an `overflow: hidden` class on `<html>`, held by a
+  counter so an inner dialog closing cannot unlock the page under an outer one. The scrollbar's width
+  leaves the page as it is applied, so a document that must not shift wants `scrollbarGutter="stable"`;
+  iOS Safari scrolls anyway.
+
+The style tree says almost nothing about position or size on purpose: the UA stylesheet centres a modal
+dialog in the viewport and caps it at `calc(100% - 6px - 2em)`. The **one** exception is `margin: auto`,
+which `Box.components('dialog')` has to declare because `._b` sets `margin: 0` and outranks the UA rule
+— without it the dialog sits in the corner. `display: none` while closed is declared for the same
+reason.
+
+---
+
+## Menu Component
+
+```tsx
+import Menu from '@box-kite/react/components/menu';
+
+<Menu trigger={(t) => <Button {...t}>Actions</Button>}>
+  <Menu.Item onSelect={duplicate}>Duplicate</Menu.Item>
+  <Menu.Item disabled>Move</Menu.Item>
+  <Menu.Separator />
+  <Menu.Group label="View">
+    <Menu.CheckboxItem checked={compact} onCheckedChange={setCompact}>
+      Compact rows
+    </Menu.CheckboxItem>
+  </Menu.Group>
+  <Menu.RadioGroup label="Sort by" value={sort} onValueChange={setSort}>
+    <Menu.RadioItem value="name">Name</Menu.RadioItem>
+    <Menu.RadioItem value="date">Date added</Menu.RadioItem>
+  </Menu.RadioGroup>
+  <Menu.Sub label="Share">
+    <Menu.Item onSelect={copyLink}>Copy link</Menu.Item>
+  </Menu.Sub>
+</Menu>;
+```
+
+APG's menu button on the platform's own Popover API, and **a submenu is a popover nested inside its
+menu**. The top layer, light dismiss and the toggle are the browser's: the menu paints over every
+stacking context with no portal and no `z-index`, Escape closes the innermost menu first — one layer per
+press — and a press outside closes the lot. What the component adds is the ARIA, the keyboard, and the
+two focus moves the platform does not make.
+
+| Prop                   | Default    | What it does                                                                                         |
+| ---------------------- | ---------- | ---------------------------------------------------------------------------------------------------- |
+| `trigger`              | —          | Render prop given `{ ref, props }`. It has to be a **button**.                                       |
+| `children`             | —          | The items. Rendered whether or not the menu is open.                                                 |
+| `open` / `defaultOpen` | —          | Controlled / uncontrolled open state.                                                                |
+| `onOpenChange`         | —          | `(open, { reason, event })` — `select`, `tab`, `trigger`, `escape`, `outside-pointer`, `imperative`. |
+| `label` / `labelledBy` | trigger    | The menu's name. Left out, it takes its trigger's, which is what APG asks for.                       |
+| `side`                 | `'bottom'` | `top`/`bottom` (block axis) or `start`/`end` (inline, so it mirrors in a right-to-left page).        |
+| `align`                | `'start'`  | Which of the trigger's edges to line the menu up with.                                               |
+| `offset`               | `1`        | The gap, on the ÷4 scale — 4px.                                                                      |
+| `flip`                 | `true`     | Whether a side with no room may be swapped for its opposite.                                         |
+| `matchWidth`           | `false`    | Whether the menu is at least as wide as its trigger.                                                 |
+
+| Part                | Props                                                                                       | Role                         |
+| ------------------- | ------------------------------------------------------------------------------------------- | ---------------------------- |
+| `Menu.Item`         | `onSelect`, `disabled`, `closeOnSelect` (default `true`)                                    | `menuitem`                   |
+| `Menu.CheckboxItem` | `checked`/`defaultChecked`/`onCheckedChange`, `disabled`, `closeOnSelect` (default `false`) | `menuitemcheckbox`           |
+| `Menu.RadioGroup`   | `label`, `value`/`defaultValue`/`onValueChange`                                             | `group`                      |
+| `Menu.RadioItem`    | `value`, `disabled`, `closeOnSelect` (default `false`)                                      | `menuitemradio`              |
+| `Menu.Group`        | `label` — names the group through `aria-labelledby`                                         | `group`                      |
+| `Menu.Separator`    | every Box prop                                                                              | `separator`                  |
+| `Menu.Sub`          | `label` (its item's content), `disabled`, `itemProps`, `side`/`align`/`offset`/`flip`       | `menuitem` + a nested `menu` |
+
+`Menu.Sub` renders both halves: the item that opens it — `aria-haspopup="menu"`, `aria-expanded`, a
+chevron — and the menu beside it, declared inside the menu it belongs to, which is what nests the two
+popovers. Its defaults are `side="end"` and `offset={0}`, so a submenu abuts the menu it came out of, and
+they nest as deeply as the markup does.
+
+| Key                   | What it does                                                                                                                                |
+| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
+| Enter / Space         | On the trigger, opens with the first item focused. On an item, chooses it. On a submenu's item, opens it.                                   |
+| Down / Up             | On the trigger, opens at the first or last item. Inside, moves between items and **wraps**.                                                 |
+| Home / End            | The first or the last item.                                                                                                                 |
+| Right / Left          | Opens the submenu of the focused item, and closes the submenu focus is in — the **reading order**, so the two swap in a right-to-left menu. |
+| Escape                | Closes the innermost menu, and puts focus back on what opened it.                                                                           |
+| Tab                   | Closes the menu and moves focus on, as APG asks.                                                                                            |
+| A printable character | Typeahead. A longer buffer narrows; the same letter again cycles through the items starting with it.                                        |
+
+Four things to know, all measured in Chrome 152:
+
+- **A disabled item is `aria-disabled` and stays focusable.** APG asks for that, so a keyboard user can
+  find out the item is there at all; the `disabled` attribute would take it out of the keyboard's reach
+  and silence it. The arrows land on it and activating it does nothing.
+- **A command closes the menu and a state does not.** `Menu.Item` closes on select, because choosing a
+  command ends the visit; a checkbox or a radio item does not, so several boxes can be ticked in one go.
+  `closeOnSelect` swaps either default.
+- **The menu is always rendered**; closed is `display: none`, not unmounted — the same shape as
+  `Popover` and `Dialog`. The exit is a CSS transition (`transitionBehavior="allow-discrete"`, already in
+  the component styles) and **not** `<Presence>`. Gate expensive items yourself:
+  `{open ? <Items /> : null}`.
+- **The platform returns focus for the outermost layer only.** Closing a nested popover drops focus to
+  `<body>`, so a submenu puts focus back on its own item itself — and opening one moves focus into it,
+  hover included, which is what keeps the highlight and the keyboard in the same place. The top layer's
+  one cost applies as it does to `Popover`: a menu **keeps the side it opened on**.
+
+The style tree is `menu` with `menu.item` (plus a `sub` variant), `menu.group`, `menu.label`,
+`menu.separator`, and `menu.indicator`, `menu.check`, `menu.dot` and `menu.arrow` for the four marks a
+menu draws — all of them borders and a radius rather than an asset, since the library ships no icons.
+The highlight is drawn on `:focus` because in a menu focus **is** the highlight: the pointer moves it, so
+hover and the keyboard cannot disagree.
+
+**The semantic `<menu>` element is `MenuList`** (`components/semantics`) now. `Menu` is still exported
+there and still works, but it is deprecated: two exports of that name are one import away from the wrong
+component.
+
+---
+
+## Tabs Component
+
+```tsx
+import Tabs from '@box-kite/react/components/tabs';
+
+<Tabs defaultValue="overview" onValueChange={(value, { reason }) => log(value, reason)}>
+  <Tabs.List label="Project">
+    <Tabs.Tab value="overview">Overview</Tabs.Tab>
+    <Tabs.Tab value="activity">Activity</Tabs.Tab>
+    <Tabs.Tab value="audit" disabled>
+      Audit log
+    </Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panel value="overview">Who is on it, and what is left.</Tabs.Panel>
+  <Tabs.Panel value="activity">What changed this week.</Tabs.Panel>
+</Tabs>;
+```
+
+APG's tabs pattern, where **selection follows focus**: one arrow key moves to a tab and shows its panel.
+`activation="manual"` splits the two — the arrows move, Enter or Space chooses — which is what a panel
+too expensive to render on the way past needs.
+
+| Prop            | Default        | What it does                                                                                |
+| --------------- | -------------- | ------------------------------------------------------------------------------------------- |
+| `value`         | —              | Controlled selection.                                                                       |
+| `defaultValue`  | —              | Which tab starts selected. Left out, nothing is selected and no panel is shown.             |
+| `onValueChange` | —              | `(value, { reason, event })` — `click` or `keyboard`.                                       |
+| `orientation`   | `'horizontal'` | `vertical` turns the axis, moves the arrows to Down/Up and the indicator to the inline end. |
+| `activation`    | `'automatic'`  | `manual` moves focus without selecting.                                                     |
+| `loop`          | `true`         | Whether the arrows wrap at the ends.                                                        |
+| `keepMounted`   | `false`        | Render every panel rather than only the selected one, hiding the rest.                      |
+| `indicator`     | `'static'`     | `sliding` is one element for the whole list, travelling between tabs.                       |
+
+| Part          | Props                                  | Role                                              |
+| ------------- | -------------------------------------- | ------------------------------------------------- |
+| `Tabs.List`   | `label` / `labelledBy`, every Box prop | `tablist` + `aria-orientation`                    |
+| `Tabs.Tab`    | `value`, `disabled`, every Box prop    | `tab` + `aria-selected`, `aria-controls`          |
+| `Tabs.Panels` | `children`, every Box prop             | none — the optional box that resizes to its panel |
+| `Tabs.Panel`  | `value`, every Box prop                | `tabpanel` + `aria-labelledby`, `tabindex="0"`    |
+
+| Key           | What it does                                                                                         |
+| ------------- | ---------------------------------------------------------------------------------------------------- |
+| Tab           | Enters the list once, landing on the selected tab; again, leaves it for the panel.                   |
+| Right / Left  | The next and previous tab in a horizontal list, wrapping and stepping over disabled tabs.            |
+| Down / Up     | The same in a vertical list. The off-axis pair is left to the page, so a list does not eat a scroll. |
+| Home / End    | The first and last selectable tab.                                                                   |
+| Enter / Space | Chooses the focused tab. Only `activation="manual"` needs them.                                      |
+
+The arrows follow the **reading order**, so in a right-to-left page ArrowLeft is the _next_ tab, read off
+the element's own resolved direction rather than an ancestor's `dir`.
+
+Two things move, and both are opt-in. `indicator="sliding"` swaps each tab's own border for one element
+for the whole list, which animates between tabs because it _is_ the same element; wrapping the panels in a
+`Tabs.Panels` gives that container the height of the panel on screen, so panels of different heights
+transition instead of jumping.
+
+```tsx
+<Tabs defaultValue="summary" indicator="sliding">
+  <Tabs.List label="Release">
+    <Tabs.Tab value="summary">Summary</Tabs.Tab>
+    <Tabs.Tab value="changelog">Changelog</Tabs.Tab>
+  </Tabs.List>
+  <Tabs.Panels>
+    <Tabs.Panel value="summary">One line, and the box is one line tall.</Tabs.Panel>
+    <Tabs.Panel value="changelog">Four, and it grows to fit them.</Tabs.Panel>
+  </Tabs.Panels>
+</Tabs>
+```
+
+Both are measured, which is where their three surprises come from. The travelling indicator **appears
+once the widget has run**, so until then the tabs keep drawing their own border — what a prerendered page
+paints, in exactly the same place, so the handover is invisible rather than a page with no indicator at
+all. The container **watches the panel and never itself**, since its own height is what it writes, and
+watching the panel catches a reflow as well as a switch. And both ride `--transitionTime`, so
+`prefers-reduced-motion` computes each to `0s` with no opt-out. The container is clipped **only while its
+height is travelling**: at rest it is exactly as tall as its panel, so a permanent clip would cut the
+focus ring off anything sitting at that edge — and `overflow` clips both axes whatever is asked for,
+computing a `visible` companion to a clipped axis up to `auto`.
+
+Four things to know:
+
+- **A disabled tab is not selectable and the arrows step over it** — the opposite of `Menu.Item`, which
+  APG asks stay reachable. Selection follows focus here, so a tab focus could reach but selection could
+  not would leave the widget with no state to be in.
+- **Only the selected panel is rendered.** An unmounted panel costs nothing and gets an entrance from
+  `startingStyle` for free, but it loses whatever state it held — `keepMounted` renders them all and
+  hides the rest, which is what a half-filled form needs. A hidden panel carries the `hidden` attribute
+  **and** a `display: none` of its own, since every Box carries `display: block` and any author rule
+  outranks the UA's `[hidden]` one.
+- **The tabs are read off the DOM**, not out of a registry, so a tab wrapped in a layout of your own,
+  rendered from a list or put behind a condition navigates like any other — and a nested set of tabs
+  belongs to its own list rather than the one around it.
+- **The tab sequence follows the selection**, so a controlled `value` changed elsewhere on the page moves
+  the keyboard's entry point with it. Under `activation="manual"` it follows the focus instead, which is
+  what APG's own example does.
+
+The style tree is `tabs` with `tabs.list`, `tabs.tab` and `tabs.panel` beneath it, plus
+`tabs.indicator` for the travelling bar and `tabs.panels` for the resizing container. The selected state is
+`aria-selected`: inside a style tree it is the bare `selected` key, and **on a tab it is
+`ariaAttr={{ selected: … }}`** — a top-level `selected` _prop_ writes the attribute the component owns
+rather than nesting styles under it, which is the rule for `selected`, `disabled` and `checked` alike.
+The indicator is a border rather than a background: a forced-colors mode keeps one and throws the other
+away, so selection would otherwise read identically on and off.
+
+---
+
+## Accordion & Collapsible
+
+```tsx
+import Accordion, { Collapsible } from '@box-kite/react/components/accordion';
+
+<Accordion defaultValue={['shipping']} onValueChange={(open, { reason }) => log(open, reason)}>
+  <Accordion.Item value="shipping">
+    <Accordion.Trigger>Shipping</Accordion.Trigger>
+    <Accordion.Panel>Two to four working days, tracked.</Accordion.Panel>
+  </Accordion.Item>
+  <Accordion.Item value="returns">
+    <Accordion.Trigger>Returns</Accordion.Trigger>
+    <Accordion.Panel>Thirty days, in the packaging it came in.</Accordion.Panel>
+  </Accordion.Item>
+</Accordion>;
+```
+
+APG's accordion. **The height animation is a class, not a measurement**: the panel sits in a grid of one
+row whose track runs `1fr` to `0fr`, so there is no `ResizeObserver`, no measured pixel and nothing
+written per instance — and content that grows while a panel is open grows with it.
+
+| Prop            | Default | What it does                                                              |
+| --------------- | ------- | ------------------------------------------------------------------------- |
+| `value`         | —       | Controlled: the values of every panel standing open, a `string[]`.        |
+| `defaultValue`  | —       | Which panels start open. Left out, all of them are closed.                |
+| `onValueChange` | —       | `(open, { reason, event })` — `reason` is `'trigger'`.                    |
+| `multiple`      | `false` | Whether several panels may stand open at once.                            |
+| `loop`          | `true`  | Whether Down and Up wrap at the ends.                                     |
+| `level`         | `3`     | Which heading each header sits in. It has to fit the outline of the page. |
+
+| Part                | Props                               | Role                                                |
+| ------------------- | ----------------------------------- | --------------------------------------------------- |
+| `Accordion.Item`    | `value`, `disabled`, every Box prop | none — it owns the pair of ids                      |
+| `Accordion.Trigger` | `level`, `arrow`, every Box prop    | `<button aria-expanded aria-controls>` in a heading |
+| `Accordion.Panel`   | every Box prop                      | `region` + `aria-labelledby`                        |
+
+| Key           | What it does                                                                                  |
+| ------------- | --------------------------------------------------------------------------------------------- |
+| Tab           | Every header is its own tab stop, and so is anything inside an open panel.                    |
+| Enter / Space | Opens the focused section, or closes it.                                                      |
+| Down / Up     | The next and previous header, wrapping and stepping over disabled ones. Inert inside a panel. |
+| Home / End    | The first and last header.                                                                    |
+
+An accordion is **not** a composite widget, so nothing here is a roving tabindex — that is the one thing
+to unlearn from `Tabs`, where the whole list is a single tab stop.
+
+**A closed panel is hidden with `visibility`, and is always rendered.** Content behind a zero-height
+track is still laid out, still tabbable and still read out, so it has to be hidden by something —
+and `visibility` is the one that is animatable, flipping to hidden only once the track has closed and
+back the instant it opens. So there is no `@starting-style` and no `transitionBehavior="allow-discrete"`
+here, a server-rendered open panel does not animate itself open on load, a half-filled form in a panel
+survives being shut, and children too expensive to render closed are yours to gate:
+
+```tsx
+<Accordion.Panel>{open ? <ExpensiveThing /> : null}</Accordion.Panel>
+```
+
+One panel stands open at a time unless `multiple`, and closing the open one is always allowed — so an
+accordion can stand with everything shut and there is no second prop for it. A `disabled` item is the
+`disabled` attribute, so the browser takes the header out of the tab sequence and the arrows step over it.
+The panel is a `role="region"` named by its header; past about six panels the landmarks are noise, which
+is APG's own caveat, and `props={{ role: undefined }}` drops it.
+
+`Collapsible` is a **named export of the same module**: the same mechanism with no heading, no group and
+no arrow keys. The trigger is a render prop and the children are the content, the way `<Popover>` reads.
+
+```tsx
+<Collapsible defaultOpen trigger={(trigger) => <Button {...trigger}>What is in the box?</Button>}>
+  <P>A kite, and the string for it.</P>
+</Collapsible>
+```
+
+Styling is the `accordion` tree — `accordion.item`, `accordion.heading`, `accordion.trigger`,
+`accordion.arrow`, `accordion.panel` — plus `collapsible` for the lone one. A header's open state is its
+own `aria-expanded`, so `ariaAttr={{ expanded: … }}` styles it and no variant is involved:
+
+```tsx
+<Accordion.Trigger py={4} ariaAttr={{ expanded: { color: 'emerald-600' } }}>
+  Shipping
+</Accordion.Trigger>
+```
+
+Two parts are not yours: `accordion.track`, the grid whose row animates, and `accordion.clip` inside it,
+the bare grid item that clips. Bare is the point — **padding cannot be squeezed**, so a grid item carrying
+any floors the `0fr` track at exactly that much, leaving a permanent stub and a stretch of the transition
+where the height has stopped but the text is still painted (measured in Chrome, bug #142). The panel you
+pad is inside the clip, so its padding costs the track nothing; that padding is also the room a focus ring
+on something at the panel's edge needs, since the clip is permanent.
+
+---
+
+## Slider & Progress
+
+```tsx
+import Slider from '@box-kite/react/components/slider';
+import Progress from '@box-kite/react/components/progress';
+
+<Slider label="Volume" defaultValue={40} onValueChange={(value) => setVolume(value)} />;
+<Slider label="Price" defaultValue={[20, 80]} thumbLabels={['Lowest', 'Highest']} format={(value) => `${value} lei`} />;
+<Progress label="Upload" value={62} />;
+<Progress label="Preparing" />;
+```
+
+APG's slider and its multi-thumb sibling, plus the `role="progressbar"` beside them. **A number in is a
+number out**: `defaultValue={40}` is one thumb whose `onValueChange` hands back a `number`, and
+`defaultValue={[20, 80]}` is a range whose handler takes a `number[]`. The value's own shape is how many
+thumbs there are, so there is no second prop saying which kind this is and nothing to narrow at the call
+site.
+
+| Prop (`Slider`) | Default        | What it does                                                                  |
+| --------------- | -------------- | ----------------------------------------------------------------------------- |
+| `value`         | —              | Controlled. A `number` is one thumb, a `number[]` is one per entry.           |
+| `defaultValue`  | `min`          | What it starts at, and what decides how many thumbs there are.                |
+| `onValueChange` | —              | `(value, { reason, event })` on every step. `reason` is `pointer`/`keyboard`. |
+| `onValueCommit` | —              | The same, once, when the interaction ends. The place for a request.           |
+| `min` / `max`   | `0` / `100`    | The range.                                                                    |
+| `step`          | `1`            | The grid every value lands on, counted from `min`. `0` is continuous.         |
+| `largeStep`     | `step * 10`    | What PageUp and PageDown move by.                                             |
+| `orientation`   | `'horizontal'` | `'vertical'` counts up from the bottom edge, in either reading order.         |
+| `disabled`      | `false`        | `aria-disabled`, so the thumb stays readable and in the tab order.            |
+| `label`         | —              | Names the thumb on one, and the `role="group"` on a range.                    |
+| `labelledBy`    | —              | The same, naming an element that already says it.                             |
+| `thumbLabels`   | —              | One name per thumb. A range wants them — `label` names the group.             |
+| `format`        | —              | `(value) => string`, written as `aria-valuetext`.                             |
+| `name`          | —              | Submits: one hidden input per thumb, so a range posts two values.             |
+
+| Prop (`Progress`)      | Default     | What it does                                                     |
+| ---------------------- | ----------- | ---------------------------------------------------------------- |
+| `value`                | —           | Leave it out for indeterminate: it reports no position at all.   |
+| `min` / `max`          | `0` / `100` | What "full" means.                                               |
+| `label` / `labelledBy` | —           | What names it. A bar with neither is a percentage about nothing. |
+| `format`               | —           | `(value) => string`, written as `aria-valuetext`.                |
+
+| Key               | What it does                                                                    |
+| ----------------- | ------------------------------------------------------------------------------- |
+| Tab               | Every thumb is its own tab stop, so a range is two of them.                     |
+| Right / Up        | One step towards the maximum. In a right-to-left page **Left** is the increase. |
+| Left / Down       | One step towards the minimum.                                                   |
+| PageUp / PageDown | `largeStep`.                                                                    |
+| Home / End        | The minimum and the maximum themselves, on the step grid or off it.             |
+
+**Neither is the native element, and that is the one place the platform loses.** Every other control here
+is a real form element with a role over it — a `Switch` is a checkbox, a `RadioGroup` is a set of radios.
+But `<input type="range">` cannot hold two thumbs, and it and `<progress>` both draw themselves with
+vendor pseudo-elements (`::-webkit-slider-thumb`, `::-moz-range-track`) that no typed prop reaches, so a
+styled one is a rewrite of every part. `name` is what keeps the half worth keeping: the value submits.
+
+**The position is an inline style, and it is the only thing here that is not a class.** A thumb's offset
+is a per-frame value, so a class for it would be a rule per frame of a drag, written into the stylesheet
+and never freed — the same exception `useAnchorPosition`'s anchor name and the travelling `Tabs`
+indicator take. Where the value is data rather than an animation, a `ProgressRing` (`components/chart`)
+rounds its fraction to half a percent and puts it in a shared class instead: nobody drags a ring.
+
+**No `value` on a `Progress` is a state, not a zero.** `aria-valuenow` is omitted entirely rather than
+reported as `0` — a position nobody measured is the one thing a reader must not be told — and the bar
+sweeps instead. The sweep names its duration in milliseconds, so it is outside what `--transitionTime`
+zeroes and stops itself under `prefers-reduced-motion`.
+
+**A press travels; a nudge does not.** A press on the track is the one move the eye has to follow, so the
+thumb animates the whole way. Every other move — a drag, an arrow key, a held arrow — is the `tracking`
+variant instead: 60ms `ease-out` on both the thumb and the fill, which must both carry it or they come
+apart. **Short rather than off, because off is exact and steps**: a value on a grid can only be at its grid
+positions, so a 1-in-100 slider moves 3.2px at a time on a 320px track. **Eased out rather than linear or
+eased**: a repeat restarts the transition every 33ms, so only its first half is ever seen, and on this curve
+that half is the straight part — it glides while held and still decelerates on the last transition, the one
+allowed to finish. Linear rode 1.4 steps behind the value and stopped at full speed; this rides 0.9 behind
+and lands at 0.6 of cruising. An arrow key taking the 250ms travel for one
+3.2px step was itself the lag: a tap arrives in 60ms now. `step` is the real dial:
+`step={0}` is continuous and interpolates nothing. And **a controlled slider re-renders whatever component
+owns its `useState`**, thirty times a second while an arrow is held — the slider costs 0.3ms a keystroke, so
+keep the value beside it rather than at the top of a page, or use `defaultValue` with `onValueCommit`.
+
+**It mirrors for free.** The fill and the thumbs are placed with `inset-inline-start` and centred with a
+logical margin, so a right-to-left page draws the minimum on the right with nothing declared twice and no
+re-render. The half that is not free is the keyboard: the sideways arrows swap, read off the element's
+resolved direction when one arrives, and Up/Down never do.
+
+Styling is `slider`/`slider.track`/`slider.fill`/`slider.thumb`, every part carrying the `vertical`
+variant, plus `progress`/`progress.fill`, whose `indeterminate` variant is the sweep. `Progress` renders
+on a **server** — no state, no effect, no measurement — so a page paints a real figure before any
+JavaScript arrives.
+
+```tsx
+Box.components({
+  slider: {
+    children: {
+      fill: { styles: { bgGradient: { linear: 'r', colors: ['sky-400', 'indigo-500'] } } },
+      thumb: { styles: { borderColor: 'sky-500' } },
+    },
+  },
+});
+```
+
+---
+
+## Toaster (`toast()` + `<Toaster>`)
+
+```tsx
+import Toaster, { toast } from '@box-kite/react/components/toaster';
+
+// once, near the root of the app
+<Toaster position="bottom-end" limit={3} />;
+
+// then from anywhere at all — an event handler, a fetch, a module with no React in it
+toast.success('Saved');
+toast.error('Could not save', { action: { label: 'Retry', onClick: save } });
+toast('Row deleted', { description: 'Ada Lovelace, added in March.', action: { label: 'Undo', onClick: restore } });
+toast.promise(save(), { loading: 'Saving…', success: (saved) => `Saved as ${saved.name}`, error: 'Could not save' });
+```
+
+Messages the app sends rather than renders. The store behind `toast()` is framework-free, so a call made
+**before** the viewport mounts is queued rather than lost, and `<Toaster>` only draws what is there.
+
+### The imperative API
+
+| Call                                           | What it does                                                                    |
+| ---------------------------------------------- | ------------------------------------------------------------------------------- |
+| `toast(message, options?)`                     | Adds one and returns its id. `message` is any `ReactNode`.                      |
+| `toast.success` / `error` / `warning` / `info` | The same with a `kind`. `error` is the assertive one — `role="alert"`.          |
+| `toast.loading(message, options?)`             | `duration: Infinity` by default: a spinner that timed out would report nothing. |
+| `toast.promise(promise, messages, options?)`   | One toast for the whole call. The promise comes back untouched.                 |
+| `toast.update(id, message, options?)`          | Changes one already on screen. An unknown id is ignored rather than added.      |
+| `toast.dismiss(id?)`                           | Starts the exit for one, or for all of them with no id.                         |
+
+An `options.id` that is already on screen is an **update**, not a second toast — which is exactly how
+`toast.promise` turns into one toast rather than two.
+
+| Option        | Default       | What it does                                                                                                         |
+| ------------- | ------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `id`          | generated     | Name it to update it later.                                                                                          |
+| `kind`        | `'default'`   | `success` / `error` / `warning` / `info` / `loading`. Decides the accent and the role.                               |
+| `description` | —             | A second line under the message. Any `ReactNode`.                                                                    |
+| `duration`    | `<Toaster>`'s | **Milliseconds.** `Infinity` waits for a dismissal.                                                                  |
+| `action`      | —             | `{ label, onClick, closeOnClick }` — one button, which dismisses the toast it answered unless `closeOnClick: false`. |
+| `dismissible` | `true`        | Whether the close button is drawn.                                                                                   |
+| `onDismiss`   | —             | `(reason)` — `'timeout'` / `'close'` / `'action'` / `'imperative'`.                                                  |
+
+### The viewport
+
+| Prop            | Default                   | What it does                                                                    |
+| --------------- | ------------------------- | ------------------------------------------------------------------------------- |
+| `position`      | `'bottom-end'`            | Six corners. The inline half is logical, so `start`/`end` mirror with the page. |
+| `limit`         | `3`                       | How many are on screen. The rest **queue**, timers and all.                     |
+| `duration`      | `5000`                    | Milliseconds for a toast that names none of its own.                            |
+| `label`         | `'Notifications'`         | Names the region. It is never labelled visually.                                |
+| `closeLabel`    | `'Close'`                 | Names the close button.                                                         |
+| `overflowLabel` | `` (n) => `+${n} more` `` | What the counter at the far end of the stack says.                              |
+| `hotkey`        | `'F6'`                    | Moves focus to the stack. Takes `'alt+t'` and the like, or `false`.             |
+| `store`         | the default one           | A second, independent stack — or a test that must not share state.              |
+
+**The limit is a queue, not a cap.** Past it a toast waits _with its timer unstarted_, so nothing expires
+that was never on screen.
+
+### Four things to know, all measured in Chrome 153
+
+1. **The region exists before there is anything in it.** The viewport is a `<section>` carrying
+   `aria-live="polite"` from the moment it mounts — a live region inserted together with its content is
+   not reliably announced. An error toast is `role="alert"`, which is assertive and is the one
+   announcement pattern every screen reader implements; **nothing else carries a region of its own**,
+   because the nearest region to a change is the one that speaks, and a second would only take the
+   first's head start away.
+2. **The top layer, and no portal.** `popover="manual"`, shown as it mounts, so it paints over every
+   stacking context and outside every clipped or transformed ancestor while staying where it was
+   declared — it inherits the theme, the custom properties and the direction around it. `manual` rather
+   than `auto` because a stack of messages owns no dismissal: a press outside has to reach the page. The
+   viewport takes **no pointer events at all** and the toasts take them back, or a corner-sized fixed
+   strip would swallow every press in its gaps.
+3. **Four things stop the clock**: the pointer over the stack, focus inside it, a background tab, and a
+   dismissal. A paused timer resumes where it left off rather than restarting. WCAG 2.2.1, and the only
+   reason a toast is allowed to carry a control at all.
+4. **A toast never takes focus.** `F6` moves focus to the viewport, Tab walks the toasts in the order
+   they are on screen, and Escape dismisses the toast focus is in — handing focus back where it came
+   from once the stack is empty.
+
+### Styling
+
+```tsx
+Box.components({
+  toaster: {
+    children: {
+      toast: { styles: { borderRadius: 4, shadow: 'large' } },
+      action: { styles: { borderColor: 'indigo-500' } },
+    },
+  },
+});
+```
+
+Parts: `toaster` (the viewport), `toaster.toast` — the kind is a **variant** on it, as is `fromTop` —
+`toaster.message`, `toaster.description`, `toaster.action`, `toaster.close` and `toaster.overflow`. The
+accent bar the kind paints is never the only signal: the message itself is what says what happened.
+
+The viewport's own style tree has to answer the UA's `[popover]` rule, which is worth knowing before
+overriding it: `inset: 0` leaves a corner-pinned stack over-constrained (`top`/`left` win and it lands in
+the wrong corner) and `overflow: auto` makes it a scroll container, so all four sides are declared `auto`
+and `overflow: visible` before a `position` variant names the two it wants.
+
+---
+
 ## Tooltip Component
 
 ```tsx
@@ -1227,14 +1963,16 @@ component — `<Button {...trigger}>` — or, on a plain element,
 `<button ref={trigger.ref} {...trigger.props}>`. The `ref` is what the bubble is positioned against,
 so the tooltip sits under the trigger and adds nothing to the layout.
 
-| Prop                      | Default | What it does                                                                       |
-| ------------------------- | ------- | ---------------------------------------------------------------------------------- |
-| `content`                 | —       | The description. Nothing renders while it is empty.                                |
-| `open` / `defaultOpen`    | —       | Controlled / uncontrolled open state.                                              |
-| `onOpenChange`            | —       | `(open, { reason, event })` — `hover`, `focus`, `pointer-leave`, `blur`, `escape`. |
-| `openDelay`               | `300`   | Hover dwell before it appears. Focus ignores it and shows immediately.             |
-| `closeDelay`              | `150`   | Grace period after the pointer leaves, so it can travel onto the tooltip.          |
-| `adjustTranslateX` / `…Y` | `0px`   | Nudge where the bubble lands.                                                      |
+| Prop                   | Default             | What it does                                                                       |
+| ---------------------- | ------------------- | ---------------------------------------------------------------------------------- |
+| `content`              | —                   | The description. Nothing renders while it is empty.                                |
+| `open` / `defaultOpen` | —                   | Controlled / uncontrolled open state.                                              |
+| `onOpenChange`         | —                   | `(open, { reason, event })` — `hover`, `focus`, `pointer-leave`, `blur`, `escape`. |
+| `openDelay`            | `300`               | Hover dwell before it appears. Focus ignores it and shows immediately.             |
+| `closeDelay`           | `150`               | Grace period after the pointer leaves, so it can travel onto the tooltip.          |
+| `side` / `align`       | `bottom` / `center` | Which side of the trigger the bubble sits on, and how it lines up.                 |
+| `offset`               | `1`                 | The gap, on the ÷4 scale — 4px, near enough for the pointer to cross.              |
+| `flip`                 | `true`              | Whether a side with no room is swapped for its opposite.                           |
 
 Every other Box prop styles the bubble, over the built-in `tooltip` component style. What the
 component guarantees, so you do not wire it: `role="tooltip"`, `aria-describedby` on the trigger only
@@ -1242,6 +1980,13 @@ while it is open, opening on hover **and** focus, Escape to dismiss with focus l
 no re-show until the pointer leaves and returns), the pointer able to move onto the tooltip, and no
 auto-hide timer — the three WCAG 1.4.13 rules.
 
+The bubble is an `Overlay`, so it sits in the browser's **top layer** with no portal: it paints over
+every stacking context and out of every clipped ancestor, and it inherits the theme, the custom
+properties and the direction around it. Its popover type is `manual` on purpose — light dismiss would
+close the bubble behind the component's back, and WCAG 1.4.13 asks for a dismissal that _lasts_, which
+is stricter than what the platform does for free. `<Presence>` still owns the mount, so a closed
+tooltip renders nothing at all.
+
 ---
 
 ## Chart primitives (`components/chart`)
@@ -1439,74 +2184,292 @@ import DataGrid from '@box-kite/react/components/dataGrid';
     contextMenu: { sort: true, pin: true, group: false },
     resizerStyle: 'hover',
   }}
-  onSelectionChange={(e) => console.log(e.selectedRowKeys)}
+  onSelectedRowKeysChange={(keys, { reason }) => console.log(keys, reason)}
 />;
 ```
 
 ### DataGridProps
 
-| Prop                                          | Type                                  | Description                                                                                |
-| --------------------------------------------- | ------------------------------------- | ------------------------------------------------------------------------------------------ |
-| `data`                                        | `TRow[]`                              | Row data (required)                                                                        |
-| `def`                                         | `GridDefinition`                      | Grid config (required)                                                                     |
-| `component`                                   | `string`                              | Style tree name (default: `'datagrid'`)                                                    |
-| `loading`                                     | `boolean`                             | Loading state                                                                              |
-| `filters`                                     | `((row) => boolean)[]`                | External predicate filters (applied before column/global filters)                          |
-| `page` / `onPageChange`                       | `number` / `(page, size) => void`     | Controlled pagination (1-indexed)                                                          |
-| `onSortChange`                                | `(columnKey, direction) => void`      | Sort callback (`direction`: `'ASC'`/`'DESC'`/`undefined`)                                  |
-| `onServerStateChange`                         | `(state) => void`                     | Unified: `{ page, pageSize, sortColumn, sortDirection, columnFilters, globalFilterValue }` |
-| `onSelectionChange`                           | `(event) => void`                     | `event`: `{ action, selectedRowKeys, affectedRowKeys, isAllSelected }`                     |
-| `expandedRowKeys` / `onExpandedRowKeysChange` | `Key[]` / `(keys) => void`            | Controlled expanded rows                                                                   |
-| `globalFilterValue` / `onGlobalFilterChange`  | `string` / `(value) => void`          | Controlled global filter                                                                   |
-| `columnFilters` / `onColumnFiltersChange`     | `ColumnFilters` / `(filters) => void` | Controlled column filters                                                                  |
+Box style props too: `DataGridProps` extends them, so `<DataGrid b={1} borderRadius={2} p={4}>` styles
+the element wrapping the bars, the rows and the pager. Every callback below is a `ChangeHandler` —
+`(value, { reason }) => void`, the shape every component in the library reports a change under.
+
+| Prop                                          | Type                                                     | Description                                                                                |
+| --------------------------------------------- | -------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
+| `data`                                        | `TRow[]`                                                 | Row data (required)                                                                        |
+| `def`                                         | `GridDefinition`                                         | Grid config (required)                                                                     |
+| `component`                                   | `string`                                                 | Style tree name (default: `'datagrid'`)                                                    |
+| `loading`                                     | `boolean`                                                | Loading state                                                                              |
+| `filters`                                     | `((row) => boolean)[]`                                   | External predicate filters (applied before column/global filters)                          |
+| `page` / `pageSize` / `onPaginationChange`    | `number` / `number` / `({ page, pageSize }, { reason })` | Controlled pagination (1-indexed). Reason: `page`/`page-size`/`sort`/`filter`/`clear`      |
+| `onSortingChange`                             | `({ columnKey, direction } \| undefined, { reason })`    | Sort. `undefined` once cleared; reason: `sort`/`clear`                                     |
+| `onServerStateChange`                         | `(state, { reason })`                                    | Unified: `{ page, pageSize, sortColumn, sortDirection, columnFilters, globalFilterValue }` |
+| `onSelectedRowKeysChange`                     | `(keys, { reason })`                                     | Every selected key; reason: `select`/`deselect`/`select-all`/`clear`                       |
+| `expandedRowKeys` / `onExpandedRowKeysChange` | `Key[]` / `(keys, { reason })`                           | Controlled expanded rows; reason: `expand`/`collapse`                                      |
+| `globalFilterValue` / `onGlobalFilterChange`  | `string` / `(value, { reason })`                         | Controlled global filter; reason: `filter`/`clear`                                         |
+| `columnFilters` / `onColumnFiltersChange`     | `ColumnFilters` / `(filters, { reason })`                | Controlled column filters; reason: `filter`/`clear`                                        |
+| `onCellEditsChange`                           | `(edits, { reason })`                                    | Every accepted edit, oldest first; reason: `edit`/`clear`                                  |
+
+`onSelectionChange(event)`, `onSortChange(key, dir)`, `onPageChange(page, size)` and
+`onPageSizeChange(size)` are the pre-contract spellings of the four above. They still fire; the
+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)                                                                            |
-| `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                                                                                             |
+| 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               |
 
 ### 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 }`                                                                                         |
-| `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                                           |
+| 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 }`                                                                                         |
+| `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                                            |
+| `exportFormat`           | `string`                                            | —         | The number format its cells wear in a workbook, `'#,##0.00'` or `'yyyy-mm-dd'`                                                                  |
+
+### Aggregation
+
+`aggregate` on a column totals it over the rows under each group row, and over the whole grid when
+`def.footer` is on. `AggregateName` is `'sum' | 'avg' | 'min' | 'max' | 'count'`; anything else is a
+function `(values: unknown[], rows: TRow[]) => number | string | null`, handed this column's value from
+every row in scope beside the rows themselves.
+
+- **The four numeric ones skip everything that is not a number**, so a blank cell is not a zero — and a
+  column holding no number at all answers **`null` rather than `0`**, because a total of nothing is not
+  zero. `count` counts **rows**, which is why it is the one that never skips anything.
+- **`avg` rounds to two decimals.** Any other precision is an `AggregateCell`; the value itself is what
+  the aggregation returned, and formatting is the renderer's.
+- **Every total covers the rows the filters left.** Under server-side pagination that is the page rather
+  than the table, since those are the only rows the grid has.
+- **A group row's label cell stops spanning at the first aggregated column**, so each figure sits under
+  its own heading. With nothing aggregating, it spans every data column beside it as it always did.
+- The footer is a row of the grid: `aria-rowcount` counts it, it is numbered last, and Ctrl+End lands in
+  it. Style nodes: `datagrid.footer`, `datagrid.footer.cell`, `datagrid.footer.label`, and
+  `datagrid.body.groupRow.aggregate` for the same value on a group row.
+
+```tsx
+<DataGrid
+  data={people}
+  def={{
+    footer: true, // or { label: 'All teams' }
+    columns: [
+      { key: 'country' },
+      { key: 'username', header: 'People', aggregate: 'count' },
+      { key: 'age', header: 'Avg age', aggregate: 'avg' },
+      { key: 'salary', header: 'Payroll', aggregate: 'sum', AggregateCell: ({ cell }) => <Box px={3}>{format(cell.value)}</Box> },
+    ],
+  }}
+/>
+```
+
+### Export to Excel and CSV
+
+**Never install a spreadsheet library for this.** The grid writes `.xlsx` itself — an `.xlsx` is a ZIP of
+XML parts, and both writers sit behind a dynamic import, so they cost the grid's bundle nothing until
+somebody presses the button and there is nothing to add to `package.json`.
+
+Two ways in. `def.export` puts the buttons in the top bar (which needs `topBar: true`):
+
+```tsx
+<DataGrid data={rows} def={{ topBar: true, export: true }} />
+// or: export: { csv: false, fileName: 'payroll' }
+```
+
+A `ref` on the grid is the same two calls, for a toolbar of your own:
+
+```tsx
+const grid = useRef<DataGridHandle>(null);
+
+<DataGrid ref={grid} data={rows} def={{ columns }} />
+<Button onClick={() => grid.current?.exportXlsx({ sheetName: 'Q1' })}>Download</Button>
+```
+
+Both take `fileName`, `columns` (keys, in the order given), `groups` and `footer`; `exportXlsx` also takes
+`sheetName`, `headerFill` and `headerColor` (as `RRGGBB`), and `exportCsv` takes `delimiter` and
+`escapeFormulas`. Both return a promise that resolves once the file has been handed to the browser.
+
+- **The file is what the grid is showing**: the visible columns in their pinned order, the rows the filters
+  and the sort left, the group rows and their totals. The one addition is a column hidden _because the grid
+  is grouped by it_ — its values moved to the group rows, and a file with no Country column in it is not
+  the grid.
+- **An export runs no React**, so a column drawn by a `Cell` renderer exports the raw field. The column's
+  own `exportValue: (row) => …` is what it writes instead, and `exportFormat: '#,##0.00'` is the number
+  format the workbook's cells wear.
+- **Values keep their type.** A number is a number, a boolean is a boolean, and a `Date` is a real date cell
+  (given `yyyy-mm-dd` automatically when the column declares no format of its own).
+- **Grouping is Excel's own outline**, not indentation: a collapsed group in the grid opens collapsed in
+  Excel, and every row is in the file either way. The workbook also gets a bold header on a frozen row,
+  column widths from the grid's own, and an auto-filter when nothing is grouped.
+- **A CSV starts with a byte-order mark**, without which Excel reads UTF-8 as the local code page, and a
+  value beginning `=`, `+`, `-` or `@` is quoted into text — a downloaded file must not run a formula
+  somebody typed into a cell. `escapeFormulas: false` turns that off.
+- Style nodes: `datagrid.topBar.export` and `datagrid.topBar.export.button`.
 
 ### RowDetailConfig
 
-| Prop                 | Type                                  | Default  | Description                                   |
-| -------------------- | ------------------------------------- | -------- | --------------------------------------------- |
-| `content`            | `(row: TRow) => ReactNode`            | required | Render function for the detail panel          |
-| `height`             | `'auto' \| number \| (row) => number` | `'auto'` | Detail row height                             |
-| `expandOnRowClick`   | `boolean`                             | `false`  | Click anywhere on the row to toggle expansion |
-| `pinned`             | `boolean`                             | `false`  | Pin the expand column to the reading start    |
-| `expandColumnWidth`  | `number`                              | `50`     | Width of the expand column in px              |
-| `expandColumnHeader` | `string`                              | `''`     | Header text for the expand column             |
+| Prop                 | Type                                  | Default  | Description                                    |
+| -------------------- | ------------------------------------- | -------- | ---------------------------------------------- |
+| `content`            | `(row: TRow) => ReactNode`            | required | Render function for the detail panel           |
+| `height`             | `'auto' \| number \| (row) => number` | `'auto'` | Detail row height                              |
+| `expandOnRowClick`   | `boolean`                             | `false`  | Click anywhere on the row to toggle expansion  |
+| `pinned`             | `boolean`                             | `false`  | Pin the expand column to the reading start     |
+| `expandColumnWidth`  | `number`                              | `50`     | Width of the expand column in px               |
+| `expandColumnHeader` | `string`                              | `''`     | Header text for the expand column              |
+| `scrollIntoView`     | `boolean`                             | `true`   | Scroll a panel opened below the fold into view |
+
+### TreeDataConfig
+
+Rows that hold rows. The shape comes off the data — nested in it, or named by a path on every row — and
+the grid becomes a `role="treegrid"`: one column grows a chevron and an indent, and every row carries
+`aria-level`, `aria-posinset`, `aria-setsize` and, where there is something under it, `aria-expanded`.
+On that column **Right** opens a shut row, **Left** shuts an open one and steps out to the parent of a
+row that is already shut (they swap in a right-to-left grid).
+
+| Prop              | Type                                 | Default   | Description                                                               |
+| ----------------- | ------------------------------------ | --------- | ------------------------------------------------------------------------- |
+| `childrenKey`     | `keyof TRow`                         | —         | Nested data: the field a row's children live in                           |
+| `getChildren`     | `(row: TRow) => TRow[] \| undefined` | —         | Nested data, worked out rather than stored                                |
+| `pathKey`         | `keyof TRow`                         | —         | Flat data: the field holding the path to this row, its own segment last   |
+| `getPath`         | `(row: TRow) => Key[]`               | —         | Flat data, worked out                                                     |
+| `column`          | `Key`                                | first own | Which column carries the chevrons and the indent                          |
+| `indent`          | `number`                             | `4`       | How far one level indents, on the ÷4 spacing scale                        |
+| `defaultExpanded` | `boolean \| number \| Key[]`         | none open | `true` for every row, a number for a depth, or the keys to open           |
+| `selection`       | `'self' \| 'cascade'`                | `'self'`  | `cascade` ticks the whole subtree, and half of one reads as indeterminate |
+| `hasChildren`     | `keyof TRow \| (row) => boolean`     | —         | **Lazy only**: whether the row holds rows the server can be asked for     |
+
+```tsx
+<DataGrid
+  data={files}
+  def={{
+    rowKey: 'id',
+    treeData: { childrenKey: 'children', defaultExpanded: 1, selection: 'cascade' },
+    columns: [
+      { key: 'name', header: 'Name' },
+      { key: 'size', header: 'Size', align: 'end' },
+    ],
+  }}
+  // Controlled instead: `expandedTreeKeys` is the open rows, and this reports them.
+  onExpandedTreeKeysChange={(keys, { reason }) => setOpen(keys)}
+/>
+```
+
+A filter over a tree keeps **a match and every ancestor of one**, so the way to a match stays visible; a
+sort happens inside each parent. Nothing under a shut row is built at all. _Group By_ is not offered on a
+tree: the rows are already in a shape.
+
+**Beside `def.dataSource` the tree is the server's** — one level per open row, and the browser holds none
+of it. Each request carries `treeKeys` (the row whose children are wanted, named by its `rowKey` and its
+ancestors', `[]` for the top), and `hasChildren` is how a row says there is a level to ask for — without
+one no row grows a chevron. `childrenKey`/`getChildren`/`pathKey`/`getPath` are not read, `selection: 'cascade'`
+is not offered (a tick cannot reach rows nobody has fetched), and `defaultExpanded` costs one request per
+row it opens, so name the keys rather than passing `true`.
+
+```tsx
+<DataGrid
+  def={{
+    rowKey: 'id',
+    dataSource: { getRows: async ({ startRow, endRow, treeKeys, signal }) => fetchLevel(treeKeys, startRow, endRow, signal) },
+    treeData: { hasChildren: 'folder', column: 'name' },
+    columns: [
+      { key: 'name', header: 'Name' },
+      { key: 'size', header: 'Size', align: 'end' },
+    ],
+  }}
+/>
+```
+
+### Cell editing
+
+`column.editable` is the opt-in and `def.onCellEdit` is the one function that both **judges** an edit and
+is **told** about it: answer nothing (or `true`) to accept the value, a string to refuse it with that
+message, `false` to refuse it with the grid's own. It may return a promise, so a check against a server is
+the same function — and an answer to an edit the user has since abandoned is dropped.
+
+```tsx
+<DataGrid
+  data={people}
+  def={{
+    rowKey: 'id',
+    onCellEdit: ({ columnKey, value, oldValue, row, rowKey }) => {
+      if (columnKey === 'name' && !String(value).trim()) return 'A name is required';
+    },
+    columns: [
+      { key: 'name', header: 'Name', editable: true },
+      { key: 'salary', header: 'Salary', editable: true, align: 'end' }, // a number, so a number field
+      { key: 'active', header: 'Active', editable: (row) => row.salary > 0 }, // a boolean, so a checkbox
+      { key: 'country', editable: true, editor: { type: 'select', options: [{ value: 'Japan' }, { value: 'Peru' }] } },
+    ],
+  }}
+  onCellEditsChange={(edits) => setEdits(edits)}
+/>
+```
+
+- **Which editor a cell opens is read off the value in it** — a number gets `number`, a boolean
+  `checkbox`, everything else `text` — unless `column.editor` names one (`text`/`number`/`checkbox`/
+  `select`) or configures it (`{ type, options?, placeholder?, step?, min?, max? }`; `options` may be a
+  function of the row). `column.EditCell` is a control of your own, bound to `cell.draft` with
+  `cell.setDraft(v)`, `cell.commitEdit()` and `cell.cancelEdit()` — the same three calls the built-in four
+  make.
+- **Pointer:** a press makes a cell the current one — it takes the ring, whether the pointer or the
+  keyboard put it there — and a **double press opens the editor** on an editable cell. A cell that cannot
+  be edited takes both as focus and nothing else, and a double press landing on a widget inside a cell (a
+  tree chevron, a link in a `Cell` of your own) belongs to the widget rather than the editor.
+- **Keys (APG's editable cell):** Enter or F2 opens the editor, any printable character opens it on that
+  character (replacing the value), Escape throws the draft away, Enter commits and hands the keyboard back
+  to the cell, and **Tab commits and opens the next editable cell** — along the row and on into the rows
+  after it. A press somewhere else commits; `checkbox` and `select` commit on the change instead.
+- **A refused value keeps the editor open**, with the message in a `role="alert"` in the top layer (a
+  bubble inside the scroller would be clipped on the last row) and `aria-invalid` + `aria-describedby` on
+  the field. Typing clears the message.
+- **The grid does not own `data`, so an accepted value is kept as an edit over the rows it was given**, and
+  is what every cell, every `Cell` renderer and every export reads. That is what lets a `def.dataSource`
+  grid be edited at all. `onCellEditsChange(edits, { reason })` reports the whole list, oldest first —
+  the stream an undo is built from — and `ref.clearEdits()` hands them back once your own data holds them.
+  A datasource `refresh()` drops them too.
+- **An edit does not re-sort or re-filter the grid.** Sorting and filtering read the row's own values; only
+  what is _displayed_ reads the edit, so a row never jumps out from under the person typing into it.
+- Style nodes: `datagrid.body.cell` gains `isEditing` and `isInvalid` variants — one ring, red when the
+  value was refused — and `datagrid.body.cell.editor` (`isPending`) and `datagrid.body.cell.error` are
+  the editor and its message.
 
 ### ContextMenuConfig
 
@@ -1521,8 +2484,9 @@ import DataGrid from '@box-kite/react/components/dataGrid';
 ```tsx
 <DataGrid
   data={pageData} page={page} loading={loading}
-  onServerStateChange={(state) => {
+  onServerStateChange={(state, { reason }) => {
     // state = { page, pageSize, sortColumn, sortDirection, columnFilters, globalFilterValue }
+    // reason = what moved: 'page' | 'page-size' | 'sort' | 'filter' | 'clear'
     setPage(state.page); refetch(state);
   }}
   def={{ columns: [...], bottomBar: true, pagination: { totalCount, pageSize: 25 }, globalFilter: true }}
@@ -1562,7 +2526,8 @@ not add roles or `tabIndex` by hand.
 - Keyboard: one cell is in the tab order at a time. Arrows move it, Home/End go to the row's ends,
   Ctrl+Home/End to the grid's corners (scrolling to a row that has not been rendered), PageUp/Down
   move a screenful. Enter/Space sorts on a sortable header and otherwise steps into the cell's own
-  control; F2 steps in even on a header; Escape hands the keyboard back to the cell. Down/Up keep
+  control — or, on an editable cell, opens its editor; F2 steps in even on a header; Escape hands the
+  keyboard back to the cell, and from an editor throws the draft away as well. Down/Up keep
   the **column**, not the cell ordinal, so they land under where they started even through a
   grouped header or a group row whose cells cover several columns each.
 - The column resizer is APG's window splitter: `role="separator"` with `aria-valuenow`/`-valuemin`/
@@ -1582,47 +2547,52 @@ 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` |
-| `datagrid.body.cell.text`                                 | Default cell text renderer                       | —                                                                                                                                                                                            |
-| `datagrid.body.cell.rowDetail`                            | Row detail expand/collapse button                | —                                                                                                                                                                                            |
-| `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                        | —                                                                                                                                                                                                                      |
+| `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")                        | —                                                                                                                                                                                                                      |
 
 ---
 
@@ -1636,14 +2606,14 @@ import Dropdown from '@box-kite/react/components/dropdown';
 
 ```tsx
 // Single selection (uncontrolled). `label` is not decoration — see Accessibility below.
-<Dropdown<string> label="Fruit" defaultValue="apple" onChange={(value, values) => console.log(value)}>
+<Dropdown<string> label="Fruit" defaultValue="apple" onValueChange={(fruit, { reason }) => console.log(fruit, reason)}>
   <Dropdown.Unselect>Pick a fruit...</Dropdown.Unselect>
   <Dropdown.Item value="apple">Apple</Dropdown.Item>
   <Dropdown.Item value="banana">Banana</Dropdown.Item>
 </Dropdown>
 
 // Controlled
-<Dropdown<string> label="Fruit" value={fruit} onChange={(value) => setFruit(value!)}>
+<Dropdown<string> label="Fruit" value={fruit} onValueChange={(value) => setFruit(value as string)}>
   <Dropdown.Item value="apple">Apple</Dropdown.Item>
   <Dropdown.Item value="banana">Banana</Dropdown.Item>
 </Dropdown>
@@ -1663,21 +2633,22 @@ import Dropdown from '@box-kite/react/components/dropdown';
 
 ### Props
 
-| Prop                     | Type                                                 | Description                                                               |
-| ------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------- |
-| `value` / `defaultValue` | `TVal \| TVal[]`                                     | Controlled / uncontrolled selected value(s)                               |
-| `label`                  | `ReactNode`                                          | The control's name, rendered above it and wired with `aria-labelledby`    |
-| `labelProps`             | `BoxProps<'div'>`                                    | Styles for the wrapper the label and the trigger share                    |
-| `multiple`               | `boolean`                                            | Multi-select mode                                                         |
-| `isSearchable`           | `boolean`                                            | Editable combobox: a text field that filters the list (see Accessibility) |
-| `searchPlaceholder`      | `string`                                             | Search input placeholder                                                  |
-| `hideIcon`               | `boolean`                                            | Hide chevron icon                                                         |
-| `showCheckbox`           | `boolean`                                            | Show checkboxes in multiple mode                                          |
-| `name`                   | `string`                                             | Form field name (renders hidden `<input>` elements)                       |
-| `onChange`               | `(value: TVal \| undefined, values: TVal[]) => void` | Selection callback                                                        |
-| `itemsProps`             | `BoxStyleProps`                                      | Style overrides for the opened items container (`dropdown.items`)         |
-| `iconProps`              | `BoxStyleProps`                                      | Style overrides for the chevron icon container (`dropdown.icon`)          |
-| `variant`                | `ClassNameType`                                      | Propagates to root **and all child sub-components**                       |
+| Prop                     | Type                                                 | Description                                                                                        |
+| ------------------------ | ---------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| `value` / `defaultValue` | `TVal \| TVal[]`                                     | Controlled / uncontrolled selected value(s)                                                        |
+| `label`                  | `ReactNode`                                          | The control's name, rendered above it and wired with `aria-labelledby`                             |
+| `labelProps`             | `BoxProps<'div'>`                                    | Styles for the wrapper the label and the trigger share                                             |
+| `multiple`               | `boolean`                                            | Multi-select mode                                                                                  |
+| `isSearchable`           | `boolean`                                            | Editable combobox: a text field that filters the list (see Accessibility)                          |
+| `searchPlaceholder`      | `string`                                             | Search input placeholder                                                                           |
+| `hideIcon`               | `boolean`                                            | Hide chevron icon                                                                                  |
+| `showCheckbox`           | `boolean`                                            | Show checkboxes in multiple mode                                                                   |
+| `name`                   | `string`                                             | Form field name (renders hidden `<input>` elements)                                                |
+| `onValueChange`          | `ChangeHandler<TVal \| TVal[] \| undefined, …>`      | The selection — an array in `multiple` mode — and why: `select`, `deselect`, `select-all`, `clear` |
+| `onChange`               | `(value: TVal \| undefined, values: TVal[]) => void` | **Deprecated**, still firing. The option acted on, and the selection beside it                     |
+| `itemsProps`             | `BoxStyleProps`                                      | Style overrides for the opened items container (`dropdown.items`)                                  |
+| `iconProps`              | `BoxStyleProps`                                      | Style overrides for the chevron icon container (`dropdown.icon`)                                   |
+| `variant`                | `ClassNameType`                                      | Propagates to root **and all child sub-components**                                                |
 
 Also accepts all `BoxProps` (styling props), which apply to the root element — a `<button>`, or the wrapper around the text field when `isSearchable`. Anything in `props` goes to the combobox itself: the button, or that field.
 
@@ -1775,15 +2746,15 @@ Box.components({
 
 ### Component Style Tree
 
-| Component Name       | Description                     | Built-in Variants     |
-| -------------------- | ------------------------------- | --------------------- |
-| `dropdown`           | Root button trigger             | `compact`             |
-| `dropdown.items`     | Opened items container (portal) | —                     |
-| `dropdown.item`      | Selectable item                 | `compact`, `multiple` |
-| `dropdown.unselect`  | Clear selection option          | `compact`             |
-| `dropdown.selectAll` | Select all option               | `compact`             |
-| `dropdown.emptyItem` | No results placeholder          | `compact`             |
-| `dropdown.icon`      | Chevron arrow container         | —                     |
+| Component Name       | Description                        | Built-in Variants     |
+| -------------------- | ---------------------------------- | --------------------- |
+| `dropdown`           | Root button trigger                | `compact`             |
+| `dropdown.items`     | Opened items container (top layer) | —                     |
+| `dropdown.item`      | Selectable item                    | `compact`, `multiple` |
+| `dropdown.unselect`  | Clear selection option             | `compact`             |
+| `dropdown.selectAll` | Select all option                  | `compact`             |
+| `dropdown.emptyItem` | No results placeholder             | `compact`             |
+| `dropdown.icon`      | Chevron arrow container            | —                     |
 
 ---
 
@@ -1796,7 +2767,7 @@ import Select from '@box-kite/react/components/select';
 
 // Basic — `label` names the combobox, same as on Dropdown
 <Select<User, number> label="User" data={users} def={{ valueKey: 'id', displayKey: 'name', placeholder: 'Pick...' }}
-  value={selected} onChange={(value) => setSelected(value!)} />
+  value={selected} onValueChange={(value) => setSelected(value as number)} />
 
 // Multiple + search + custom display
 <Select<User, number> label="Users" data={users} multiple showCheckbox isSearchable searchPlaceholder="Search..."
@@ -1820,7 +2791,7 @@ import Select from '@box-kite/react/components/select';
 | `selectAllText`   | `string`                                       | Select all option text (multiple mode)                 |
 | `emptyText`       | `string`                                       | Empty search results text                              |
 
-Also accepts: `data` (TRow[]), `value`/`defaultValue`, `label`/`labelProps`, `multiple`, `isSearchable`, `searchPlaceholder`, `showCheckbox`, `hideIcon`, `name`, `onChange`, `itemsProps`, `iconProps`, `variant`, and all BoxProps. Same styling, variants and combobox accessibility as Dropdown — including owing it a name, and including `isSearchable` switching it to the editable combobox.
+Also accepts: `data` (TRow[]), `value`/`defaultValue`, `label`/`labelProps`, `multiple`, `isSearchable`, `searchPlaceholder`, `showCheckbox`, `hideIcon`, `name`, `onValueChange` (and the deprecated `onChange`), `itemsProps`, `iconProps`, `variant`, and all BoxProps. Same styling, variants and combobox accessibility as Dropdown — including owing it a name, and including `isSearchable` switching it to the editable combobox.
 
 ---
 
@@ -1830,4 +2801,4 @@ Also accepts: `data` (TRow[]), `value`/`defaultValue`, `label`/`labelProps`, `mu
 2. **Class names**: Elements get classes like `_b`, `_2a`, etc.
 3. **CSS variables**: In `:root` rules
 4. **Theme issues**: Ensure `<Box.Theme>` wraps your app
-5. **Portal theming**: Tooltips/dropdowns use `#box-kite-portal` container
+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