` is a region landmark too, so a screen reader has a second way in. Timers stop while the pointer is over the stack, while anything in it has focus, and while the tab is in the background — and resume where they left off rather than starting again. That is WCAG 2.2.1, and it is the only reason a toast is allowed to carry a control at all: a button that can vanish mid-reach is not operable. ### The top layer, and no portal The viewport carries `popover="manual"` and is shown the moment it mounts, so it paints over every stacking context and outside every clipped or transformed ancestor — and because it never leaves the place it was declared, it inherits the theme, the custom properties and the text direction around it. `manual` rather than `auto`, because a stack of messages owns no dismissal: a press outside has to reach the page. Which raises the problem a fixed strip across a corner always raises, and it was measured rather than assumed: the viewport takes **no pointer events at all** and the toasts take them back, so a press in the gaps between them goes through to whatever is underneath. Two more things the UA stylesheet's own `[popover]` rule decides, both found in Chrome 153 and worth knowing before overriding the style tree. `inset: 0` leaves a corner-pinned stack over-constrained — `top` and `left` win over the two sides a `position` variant sets, and the stack lands in the top-left corner whatever you asked for — so all four sides are declared `auto` first. And `overflow: auto` quietly makes the viewport a scroll container, which clips the toasts' own shadows, so it is declared `visible`. `position` is one of six corners and its inline half is logical, so `'bottom-start'` is the bottom left of a left-to-right page and the bottom right of a right-to-left one. The newest toast is always the one nearest the screen edge, which is why a stack pinned to the top is drawn in the opposite order to one pinned to the bottom. ## A combobox whose value is your own row `` is APG's editable combobox over a list you already have — a text field that filters a `role="listbox"`, one tab stop however many options are open, and DOM focus that never leaves the input. ```tsx import Combobox from '@box-kite/react/components/combobox'; assign(person)} />; ``` **A row in is a row out.** `data` is the list of objects you already hold, and the value is one of _those rows_ rather than a string dug out of one — `onValueChange` hands the object straight back, typed, so there is no lookup table on the other side of the handler. `def` says how to read a row: `label` is its text (searched, displayed and read out) and `key` is what makes two rows the same row, so a list refetched from the server still shows the selection as chosen. Both take a key of the row or a function, and `disabled` and `display` are the other two. **`multiple` turns the selection into chips and the value into an array.** It is a prop rather than something inferred from the value, which is the one place this differs from ``: a slider always has a value to read the shape off, and a combobox usually starts with nothing in it. Choosing a row that is already chosen takes it off again. A chip's remove button is deliberately **not** a tab stop — twenty selections would otherwise cost twenty presses to Tab past. Backspace on an empty field removes the last one and the listbox toggles any row back off, so removal is reachable from the keyboard without them, and each button still carries a name for anyone reading the control rather than tabbing through it. **The filter composes.** The built-in one folds case and strips accents, so `jose` finds `José`, and matches anywhere in the label rather than only at the front. `filter` replaces it and takes the _whole list_, so it can rank as well as reject — and it is handed the label reader, so starting from the built-in one costs nothing: ```tsx ComboboxUtils.filterRows(rows, query, labelOf).slice(0, 20)} /> ``` `filter={false}` says the data arrived filtered, which is what a server that already searched needs; `onQueryChange` is the hook that request hangs off, and `loading` makes the popup say the rows are coming rather than that there are none — the difference between "still looking" and "nothing here". **`createRow` turns what was typed into a row.** Return the row, or `null` to refuse the query. Its presence is what offers the create row at all, and one is never offered for a query a row already answers by name — offering "Create Design" beside Design is how a list grows twins. The change arrives with its own reason, `create`, beside `select`, `deselect` and `remove`. Typing filters and never highlights a suggestion: that is _list_ autocomplete rather than inline, and a highlight nobody asked for is one Tab away from being committed. The arrows move through what the filter left, Home/End and the sideways arrows move the caret and hand the highlight back to the field, Enter chooses the highlighted row and does nothing when there is none, and Escape closes the listbox keeping what was typed before a second one clears the field. ### Ten thousand options A list past a hundred rows is windowed: the popup renders the dozen on screen and a few either side, so it opens in one frame whether it holds a hundred rows or ten thousand. Measured in Chrome on the ten-thousand-row demo — fifteen options in the DOM, 49 ms from the press to the open listbox, and sixty consecutive frames of scrolling with none of them over the frame budget. Nothing else about the component changes: the filter still runs over the whole list, the arrows still walk all of it, and the value is still the row you passed in. The row height is measured rather than declared — the _pitch_, taken from two rendered rows, so a gap or a border between them is part of the step — which means a restyled option windows correctly with nothing to configure. What windowing assumes is that rows are all the **same** height, so a `display` that varies one wants `virtualize={false}`, which renders every row however many there are. `virtualize` also takes `true` to window a short list, and an object to tune it: `threshold` is the row count it starts at, `overscan` how many rows are kept either side, and `itemHeight` the pitch, when it should be stated rather than measured. **The half of this that is not performance is the ARIA.** A windowed listbox holds a slice of its rows, so every option carries `aria-setsize` and `aria-posinset` — without them a screen reader announces "City 1 of 15" on a list of ten thousand. And **the row the keyboard is on is always rendered**, whatever the scroll position says: `aria-activedescendant` naming a row that was never put in the DOM names nothing at all, so the window goes where the keyboard is and lets the scroll catch up. It does not stay pinned there — a wheel scroll away from the highlight moves the list, or a combobox opened on its first row could never be scrolled at all. `combobox.window` is the one new style key, the element the slice is rendered into. Its height and its top padding are inline styles rather than classes, because they change with every scroll event and a class per pixel is a rule per frame that is never freed — the same exception a slider's thumb and an anchor's name already take. **9.53 KB gz on top of Box** — the model, the listbox, the chips, the windowing and the APG keyboard, on top of the anchoring and dismissal every other layer in the library already shares. A combobox is usually assembled instead — a headless behaviour package, and then the markup, the styling and the ARIA written around it. ## The component contract, written down and enforced Twenty components have arrived in this release, and the thing you cannot see from any one of them is that their APIs were decisions rather than accidents. [The component contract](https://github.com/box-kite/box-kite/blob/main/docs/component-conventions.md) is those decisions, in five rules — and `npm run check:conventions` is what stops the library drifting out of them. **What a consumer can now rely on.** Every piece of state you may own is held by `useControllableState`, so controlling a value behaves exactly like not controlling it — including when you stop, which carries on from the last value you asked for rather than snapping back to the default. Every change is `onXChange(value, { reason })` with the reason a **named union** you can `switch` on exhaustively, so no handler has to guess whether a popup closed because something was picked, Escape was pressed or the page was clicked. Every part takes Box style props and every component has a node in `boxComponents.ts`, so `` works and the defaults can be replaced wholesale. And composition is a **render prop** — the answer to `asChild`: a component hands you a bag to spread and never reaches into the element you rendered, because cloning has to guess whether a DOM attribute belongs in a Box's `props` bag or on top of a plain element, and a wrong guess is silent. **The exceptions are the interesting part, so they are a ledger rather than a habit.** The biggest is deliberate: a component rendering a real form control — `Checkbox`, `Switch`, `RadioButton`, `Textbox`, `Textarea`, `Button` — forwards React's own `onChange`/`onInput`/`onClick` unchanged, because the DOM event _is_ the API there and a second channel beside it would mean two ways to hear about one keystroke. `Menu.Item`'s `onSelect` is a command with no value to report, `Overlay`'s `onSideChange` reports what the browser did, and `Icon` is the one component that clones its child — it styles an icon somebody else drew, so there is no render prop to offer. Every ledger in the check **fails two ways**: on a new break, and on a listed exception that has stopped being true. That is the rule the accessibility sweep's `knownViolations` already follows, and it is what keeps an exception list from becoming a place things go to be forgotten. Its list of debts is now empty: `DataGrid`, the last component older than the contract, is on it too. - **`RadioGroup` reports through `onValueChange`.** `onChange` still works and still fires — pass either, or both — but it was the one `ChangeHandler` in the library under a DOM event's name, on a component that is not an ``. It is deprecated and will go in a future major. ### `Dropdown` and `Select` report through `onValueChange` too The library's oldest component now holds its selection in `useControllableState` like every other one, and reports it the way every other one does: ```tsx label="Fruit" value={fruit} onValueChange={(next, { reason }) => setFruit(next as string)}> Apple ``` `onValueChange` hands back **the selection in whatever shape `value` takes** — the array in `multiple` mode, the one chosen option otherwise — and a reason you can `switch` on exhaustively: `'select'`, `'deselect'`, `'select-all'` and `'clear'`, the last two being the `Dropdown.SelectAll` and `Dropdown.Unselect` rows, which act on the whole list rather than on one option. `onChange` is deprecated and still fires with its old `(value, values)` pair, where the first argument is the option _acted on_; pass either, or both, and nothing needs changing today. Moving the pair onto the hook is also where a quiet bug went: `defaultValue={0}` and `value={''}` were read as "nothing selected", because the old code tested the value for truthiness rather than for being there. A falsy value is a value somebody can pick. ### `RadioGroup` and the chart primitives have style trees `Box.components()` now reaches all six: `radioGroup` (with a `horizontal` variant) and its `label`, `sparkline` and its `line`/`area`/`bar` paths, `progressRing` and `gauge` with their `track` and `arc`, `miniDonut` and its `segment`, and `chartContainer`. What used to be a default written into the component is a node you can replace, so one override restyles every drawing in an app: ```tsx Box.components({ sparkline: { styles: { stroke: 'emerald-500', strokeWidth: 2 } } }); ``` `ChartContainer`'s node is the interesting one: it holds the `--chart-1` … `--chart-6` palette and its dark twin, so re-skinning every chart on a page — including a Recharts one that names no colour of its own — is one override rather than a prop on every container. A `series` prop and a `vars` of your own still win over it, exactly as before. One thing to look at when you upgrade: a `RadioGroup`'s `label` now wears the same type as a `Combobox`'s — `14px` in `gray-700`, `gray-300` in the dark theme — where it used to inherit whatever was around it. `Box.components({ radioGroup: { children: { label: { styles: … } } } })` is where to say otherwise. ### `DataGrid` takes Box props, and says why each thing changed The grid is a Box now, so the element wrapping the bars, the rows and the pager takes the same props as anything else — `` — with no wrapper `` around it and no style tree override for a border. A `style` of your own sits on top of the column-width variables the grid writes there rather than replacing them. Its eight callbacks report a reason now. Four kept their names, because a handler written `(value) => …` is still assignable to one that hands it a second argument — so this is additive and nothing needs changing today: ```tsx reason === 'clear' && resetSearch()} onServerStateChange={(state, { reason }) => refetch(state, { debounce: reason === 'filter' })} /> ``` `onGlobalFilterChange` and `onColumnFiltersChange` say `'filter'` or `'clear'`, `onExpandedRowKeysChange` says `'expand'` or `'collapse'`, and `onServerStateChange` — the one most people wire an API to — says which of `'page'`, `'page-size'`, `'sort'`, `'filter'` or `'clear'` moved. That last one is worth having: the grid sends the pager back to the first page whenever a query changes underneath it, and until now nothing said whether a page-1 snapshot was a navigation or a reset. The other four could not grow a details argument where their second argument already meant something else, so each has a new name beside it and the old one is deprecated and still fires: - **`onSelectionChange(event)` → `onSelectedRowKeysChange(keys, { reason })`** — the selection itself, and the event's `action` as a named reason: `'select'`, `'deselect'`, `'select-all'` or `'clear'`, which are the four `Dropdown` already reports a selection under. The old event's `affectedRowKeys` is what it is still for. - **`onSortChange(columnKey, direction)` → `onSortingChange(sort, { reason })`**, where `sort` is `{ columnKey, direction }` or `undefined` once the third press clears it. - **`onPageChange(page, pageSize)` and `onPageSizeChange(size)` → `onPaginationChange({ page, pageSize }, { reason })`** — one callback, because the two always moved together: a new page size always returns to page 1. ## A column that adds itself up `aggregate` on a column is the half of grouping the grid was missing: the column totals itself over the rows under each group row, and over the whole grid when `def.footer` is on. ```tsx ``` Five built-ins — `sum`, `avg`, `min`, `max` and `count` — or a function of your own, handed the column's values and the rows they came from, so a weighted average can reach the column it weights by. The four numeric ones read the numbers in the column and skip everything else, so a blank cell is not a zero and a column holding no number at all answers **`null` rather than `0`**: a total of nothing is not zero, and a footer reading `0` over an empty grid is a claim about the data. `count` counts rows rather than values, which is why it is the one that never skips anything. `avg` rounds to two decimals, because an exact mean is longer than the cell it goes in — any other precision is an `AggregateCell`, which is to an aggregate what `Cell` is to a row: ```tsx { key: 'salary', aggregate: 'sum', AggregateCell: ({ cell }) => {cell.value === null ? '—' : format(cell.value)}, } ``` Every total covers the rows the filters left, so filtering the grid changes them. Three things worth knowing. **A group row's label stops spanning at the first aggregated column.** It used to run across every data column beside it, and a number under the wrong heading is worse than a label with less room — so from there on each column draws its own value, and a group row's figures line up under the same headings the rows below them do. With nothing aggregating, the span is exactly what it was. **The footer covers the rows the grid holds**, which under server-side pagination is the page rather than the table, because those are the only rows it has; a server-computed total is what E3's row model will be for. And **the footer is a row of the grid in every sense** — `aria-rowcount` counts it, it is numbered last, Ctrl+End lands in it and Up leaves it, which is why it is pinned rather than parked at the end of the scroll. Its style nodes are `datagrid.footer`, `datagrid.footer.cell` and `datagrid.footer.label`, with `datagrid.body.groupRow.aggregate` for the same value on a group row. `def.footer` also takes `{ label }`, which replaces the default `Total` in the first column that is not aggregating. ## The DataGrid, restyled The grid's default appearance was a spreadsheet: a `gray-200` rule under every cell and down every column boundary, 13px headings as dark as the data under them, and a `large` drop shadow around the whole thing. It reads as one surface now — the chrome quiet, the data loud. What changed, and why each one: - **Numbers line up.** Every body cell is `font-variant-numeric: tabular-nums`, so a column of figures shares a digit width instead of drifting. It is the one thing a data grid cannot do without, and the registry has no prop for it — `css` is where a property with no prop goes, and it still compiles to one shared class. - **A selected row finally looks selected.** It tints (`indigo-50`, `indigo-950` in the dark), pinned columns included. `isRowSelected` had been declared on `datagrid.body.cell` and `datagrid.header.cell` since the grid shipped and was applied by **nothing**, so a selected row was legible only by its own checkbox. Both dead variants are gone; the appearance comes from `aria-selected` on the row, through the library's own `group` prop. - **A group row reads as a section header**, tinted the same way off its `aria-expanded`. - **Pinned columns float rather than fence.** The hard border on the frozen edge is a soft directional shadow, so the pinned columns sit _over_ the scrolled ones. - **Quieter chrome.** Row separators drop to `gray-100`, the column resizer from a 2px `gray-400` rule to a 1px hairline, the header to 12px tracked `gray-500`, and the bars to the grid's own surface with a hairline under them — three stacked greys was what made it read as a spreadsheet. The container keeps a tight `xs` shadow instead of `large`. - **One type scale.** The grid sets `fontSize: 14` once at its root and every part inherits it. Three colours were measured rather than chosen: a muted row number at `gray-400` is 2.60:1 on white, and the header's menu button at `gray-400` is 2.49:1 on `gray-50` — both below what text and controls owe. They are `gray-500` (4.84:1 and 4.63:1), which is as quiet as the contrast allows. **If you override `datagrid` styles**, the parts are unchanged — only their values. The two removed variants are the exception, and neither ever painted anything. ### A row-detail panel is a drawer `rowDetail` shipped with no appearance of its own beyond a grey band. The row that opened the panel looked like every other row, and the hairline between the two said the panel was the _next_ row rather than part of this one. They are one block now: the expanded row takes the panel's surface (`gray-50`, and `gray-950` in the dark — _darker_ than the grid, because a drawer should read as a well) and gives up its bottom hairline, and a 2px `indigo-500` accent runs down the inline start of the row and on down the panel, which is the only thing tying a panel this tall back to the row it belongs to. The accent is logical, so it mirrors with the reading order. The expand chevron is a control rather than data now — `gray-500` at rest, the accent when open. The row also gets a hover one step off its new surface, since the grid's own row hover is the colour an expanded row is already painted: it had stopped answering. A panel that opens below the fold now scrolls itself into view. It is `block: 'nearest'`, so a panel already on screen moves nothing, and a grid that scrolls internally absorbs the scroll rather than the page. The row that opened the panel is part of what gets revealed: `datagrid.body.detailRow` carries a `scroll-margin-block-start` of one row, so a panel taller than the viewport aligns the _row's_ top rather than its own instead of pushing it off the screen — measured in Chrome, where without the margin the row lands 40px above the scrollport. The scroll happens where the panel mounts rather than where the row was toggled, because an `auto` panel's real height exists nowhere else: virtualization carries a 200px estimate for it. `rowDetail: { scrollIntoView: false }` turns it off. Neutral rather than tinted on purpose: a **selected** row is the one that tints, so the two states stay legible beside each other. Re-colouring the block is two keys — `body.cell`'s `isExpanded` variant and `body.detailRow` — which is all the docs site's own Orders demo does now, where it used to spell out a 3px frame across four nodes. ## Excel and CSV, with nothing to install `def.export` puts two buttons in the grid's top bar, and a `ref` on the grid is the same two calls for a toolbar of your own: ```tsx ``` ```tsx const grid = useRef(null); ``` 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. It adds exactly one thing back — a column hidden _because the grid is grouped by it_. Its values moved to the group rows rather than going away, and a spreadsheet with no Country column in it is not the grid that was exported. The workbook is a real `.xlsx`, not a CSV wearing the extension: a bold header on a frozen row, column widths taken from the grid's own, values that keep their type — a number is a number, a `Date` is a date cell — an auto-filter, and **the grouping as Excel's own outline levels**, so a group left collapsed in the grid opens collapsed in Excel with every row still in the file. An export runs no React, so a column drawn by a `Cell` renderer says what it writes, and a column can name the number format its cells wear: ```tsx { key: 'salary', header: 'Payroll', aggregate: 'sum', exportFormat: '$#,##0' }, { key: 'name', exportValue: (row) => `${row.first} ${row.last}` }, ``` **There is no ExcelJS to install.** An `.xlsx` is a ZIP of XML parts, and this writes both — 3.80 KB gz for the two formats together, in a chunk behind a dynamic import, so a grid nobody exports from carries none of it and the grid's own entry grows 1.03 KB for the model and the buttons. A real `.xlsx` is usually either a paid tier or a second dependency; here it is neither. Two smaller things, both deliberate. A CSV starts with a byte-order mark, without which Excel reads UTF-8 as the local code page and mangles every accented name. And a CSV value beginning `=`, `+`, `-` or `@` is quoted into text: a file a page generated must not run a formula somebody typed into a cell. `exportCsv({ escapeFormulas: false })` writes it as it stands. Both take `fileName`, `columns`, `groups` and `footer`; `exportXlsx` also takes `sheetName`, `headerFill` and `headerColor` as `RRGGBB` — a workbook carries one appearance, not a light and a dark one. The buttons are `datagrid.topBar.export` and `datagrid.topBar.export.button`. ## A grid that fetches its own rows `def.dataSource` turns the grid the other way round. Instead of handing it an array and wiring five callbacks to keep that array in step, you hand it one function and it asks: ```tsx ``` There is no `data` prop in that call, and no `loading`, `page` or `totalCount` either — the grid owns all four. Sorting, filtering and paging stop being work the browser does over an array and become part of a request, which is what lets a grid stand in front of a table nobody could send to a browser at all. The range arrives twice, as `startRow`/`endRow` for an API that offsets and as `page`/`pageSize` for one that pages, because they always describe the same block. **A block is the unit of everything**: one request, one wait, one failure. `blockSize` is how many rows each asks for — the page size when `def.pagination` is beside it, 100 otherwise — and `maxBlocks` is how many are kept before the ones furthest from the viewport are dropped and asked for again on the way back. Rows that have not arrived are drawn as skeletons and are **still counted**, so the scrollbar and `aria-rowcount` describe the whole result set from the first block rather than growing under whoever is reading it; a placeholder row says `aria-busy`, and the row number, which is known without the row, is the one cell it still fills. A superseded request costs the network nothing: every call carries an `AbortSignal` that fires when the sort or the filters change underneath it. And a reply that arrives anyway is **dropped** rather than written over the newer one — the out-of-order race is the whole of what an async row model has to get right, and it is not something a page should have to write again. `def.pagination` beside a datasource is the pager rather than the scroller, and the two share one cache: a page already fetched is shown with no round trip. It needs no `totalCount` any more, since the response carries one — and a response may leave it out altogether, in which case the grid follows the rows and treats a block shorter than it asked for as the end of the data. A failed block shows one strip with the error's own message and a Retry that asks for every block that failed. The grid invalidates its own cache whenever it changes the query; for the half it cannot see — a filter of the page's own, a row somebody saved — `refresh()` on the grid's ref throws the blocks away and asks again. Two things a server-backed grid must not pretend: a select-all reaches the rows that are loaded, not the table behind them, and an export writes what the grid holds. Grouping used to be the third — it is the next section now. The existing `onServerStateChange` grid is untouched and still works — `dataSource` is the answer for a new one. The parts are `datagrid.body.cell.placeholder` and its `bar`, and `datagrid.error` with `message` and `retry`. **+2.51 KB gz** on the DataGrid entry, and 0.15 KB on every other engine-carrying entry for the two style-tree nodes — `/a11y` and `/anchor`, which carry no engine, moved nothing at all. ## A group the server counts, and children it fetches when you open one Grouping was the one thing a datasource did not offer, for a good reason: grouping the blocks that happen to be in the browser is not grouping the data. So the server does it. Say that it can, and _Group By_ comes back in the column menu: ```tsx dataSource: { // Without this, Group By is not offered at all: a `getRows` that ignored `groupKeys` would // answer a group level with leaf rows, and the grid has no way to tell that it had. grouping: true, async getRows({ startRow, endRow, groupBy, groupKeys, signal }) { const res = await fetch(`/api/people?` + new URLSearchParams({ offset: String(startRow), limit: String(endRow - startRow), groupBy: groupBy.join(','), // ['country'] — what to GROUP BY groupKeys: groupKeys.join(','), // [] for the groups, ['Japan'] for what is inside one }), { signal }); const body = await res.json(); return { rows: body.items, totalCount: body.total, groupCounts: body.counts }; }, } ``` Every request now carries **`groupBy`**, the columns being grouped by, outermost first, and **`groupKeys`**, the group it is inside. Shorter than `groupBy` and the rows wanted are _group_ rows, one per distinct value of `groupBy[groupKeys.length]`, with `groupCounts` beside them; the same length and they are that group's own rows. One rule covers both directions, and there is no second callback. A group row is **a row of the same shape**: the level's own column, and whatever it totals. A column with an `aggregate` reads its value off that row rather than adding up rows the browser has not got — so the number on a group row is the server's arithmetic over the whole group, not over the fifty rows in hand. Its count goes in the label; omit `groupCounts` and the label is the value alone. Nothing under a group is fetched until its chevron is pressed. **Each open group is a cache of its own** — its own blocks, its own count, its own failure — and shutting one disposes of it and everything beneath. Eviction keeps the chain _above_ a level in play, so scrolling deep inside a group never drops the group row it hangs off; that was measured, because the obvious least-recently-used order takes it first. Two things the grid still declines to pretend. A group whose rows have never been fetched shows **no select-all checkbox**: it cannot select what the browser has never seen, and a checkbox that did nothing would be worse than none. And the totals come down with the group row, so a column with no `aggregate` declared still shows nothing — declaring one is how you say a column totals, whoever does the arithmetic. Measured in Chrome 152 on the built site, scrolling twelve blocks deep inside an open group: **109 ms** worst frame gap against **105 ms** for the same scroll through the ungrouped million-row grid beside it, and **52 ms** back over blocks already cached. The walk over the open levels costs nothing the flat path did not. **+1.45 KB gz** on the DataGrid entry; every other entry moved by zero. One fix came out of it. A group row carried `aria-expanded`, which is only defined on a row inside a `treegrid` and is a serious axe violation inside a `grid` — it had been there since grouping shipped, and no fixture had ever rendered a group row for the sweep to see. The open state is on the expand button, where it always also was. ## A grid whose rows hold rows A file system, an org chart, a bill of materials: rows with rows inside them. `def.treeData` reads that shape off the data and the grid does the rest — one column grows a chevron and an indent, and the whole thing reports itself as a `treegrid`: ```tsx ``` The tree comes in **two shapes**, and both are the data you already have. Nested, where a row carries its children (`childrenKey`, or `getChildren` to compute them); or flat, where every row carries the path to itself (`pathKey`/`getPath`) — which is what an export, a `WHERE path LIKE` or a materialised-path table hands you. A flat list needs no ordering: shallower rows are read first, and a row whose parent is missing hangs off the nearest ancestor that is there. **A filter keeps the path to a match.** Filtering a tree row by row would hide every match three folders down, so a row survives when it matches _or something under it does_ — what is left is the matches and the way to them. A row that matches on its own keeps none of the children that did not, and a sort happens _inside_ each parent, because a tree sorted across its levels is not a tree any more. **A shut row costs nothing.** Nothing under one is built at all — no models, no cells — so ten thousand rows nobody has opened cost the page its top level; opening one builds that level and no more. The tree itself is built once and left alone, so an expand rebuilds none of it. It is **a `treegrid`**, which is the only place ARIA allows a row to say it is expandable: every row carries `aria-level`, `aria-posinset` and `aria-setsize`, and a row with something under it carries `aria-expanded`. On the tree's own column, **Right** opens a shut row and **Left** shuts an open one — and on a row that is already shut, Left steps out to its parent, which is APG's rule. Both follow the reading order, so they swap in a right-to-left grid; on every other column they are the ordinary move along the row. Two things it does not pretend. Selection cascades only when you ask (`selection: 'cascade'`, which also makes a half-ticked row read as indeterminate) — a checkbox is otherwise the row it is on, like every other row in the grid. And _Group By_ is not offered on a tree at all: the rows are already in a shape. Measured in Chrome on the built site, on the docs page's own ten-thousand-node tree (12 areas × 25 modules × 33 files = 10,212 rows): scrolling it is a **18 ms** worst frame gap against **42 ms** for the thousand-row flat grid further up the same page, opening a folder is **16 ms** — one frame's work — and filtering the whole tree costs **82 ms** on the first keystroke and 11–25 ms after, against 112 ms and 12–30 ms for that flat grid's own filter over a tenth as many rows. Right-to-left was measured with a real `dir`, which no test environment resolves: ArrowLeft opens. **+2.0 KB gz** on the DataGrid entry and ~35 B on every entry that carries the engine (the three new style-tree nodes); `/a11y`, `/anchor` and the export chunk moved by zero, which is what attributes the rest. ## A tree the server holds, one level per chevron The tree above is in the browser. Put `def.treeData` beside `def.dataSource` and it is not: the grid asks for one level at a time, and a folder nobody has opened costs the page nothing however deep it goes. ```tsx const dataSource = useMemo( () => ({ async getRows({ startRow, endRow, treeKeys, signal }) { // [] is the top of the tree, ['app'] what is in that folder, // ['app', 'app/m3'] what is in the one under that. const res = await fetch(`/api/files?path=${treeKeys.join('/')}&offset=${startRow}&limit=${endRow - startRow}`, { signal }); const body = await res.json(); return { rows: body.items, totalCount: body.total }; }, }), [], ); ; ``` **The path is keys, so the server names a node the way it named it.** `treeKeys` is built from `def.rowKey` rather than from the values on screen — the ids the server sent come back to it verbatim, outermost first, `[]` for the top. A row three deep asks with all three, so a query can be written against the whole path or against the last segment alone. **A chevron is the server's answer, not a guess.** `hasChildren` names a field (`hasChildren: 'folder'`) or works the answer out (`hasChildren: (row) => row.kind !== 'file'`). Without one no row grows a chevron: a grid that offered one on every row would promise a level that may not exist, and a grid that fetched to find out would defeat the whole thing. It is **the same mechanism as server-side grouping**, not a second one beside it. A level per open path, each with its own blocks, its own count and its own failure; a level is created when its row is opened and disposed of the moment nothing reaches it; and eviction keeps the chain above a level in play, so scrolling deep inside a folder never drops the row it hangs off. `treeKeys` and `groupKeys` are the same field of the cache seen from two ends, which is also why the two are mutually exclusive — _Group By_ is not offered on a tree, whoever holds it. Everything the eager tree gives the keyboard and the screen reader is unchanged: a `treegrid`, `aria-level` /`aria-posinset`/`aria-setsize` on every row, `aria-expanded` on the ones that hold rows, and **Right** to open with **Left** to shut and step out to the parent, following the reading order. Two differences, both of them the honest answer rather than a gap. `selection: 'cascade'` is not offered — a tick cannot take rows nobody has fetched — and `defaultExpanded` costs one request per row it opens, so a list of keys is what it is for and `true` would fetch the whole tree. `onExpandedTreeKeysChange` still reports the rows that are open _and reachable_: a row under one that has been shut is not open, and its level is gone. The docs page's demo is a repository of 144,732 rows (12 areas × 60 modules × 200 files) generated a level at a time and never built — beside the eager tree further up the same page, which holds all 10,212 of its own, and that neighbour is the control. Measured in Chrome on the built site: scrolling three levels deep with blocks arriving is a **46 ms** worst frame gap against the eager tree's **56 ms** on the same page and the same harness, **29 ms** back over cached blocks, and opening a folder is **1 ms** — the level it adds is a walk, not a rebuild. Thirty-three rows in the DOM either way. Right-to-left was measured with a real `dir`, which no test environment resolves: ArrowLeft opens and ArrowRight shuts. **+0.56 KB gz** on the DataGrid entry; `/a11y`, `/anchor`, the export chunk, the core engine and every other component moved by exactly zero, which is what attributes the rest. ## Grouping can be declared now, not only clicked Row grouping was reachable only through a column's menu, which meant a grid could not _start_ grouped — no server render, no fixture, no demo that shows anything before the reader opens a menu. `def.groupBy` is where the grid starts, and `def.groupDefaultExpanded` says which of those groups start open: ```tsx def={{ groupBy: ['country'], // outermost first; a grouped column is hidden, as the menu hides one groupDefaultExpanded: 1, // `true` for all of them, a number for how many levels down columns: [ { key: 'name', header: 'Name' }, { key: 'country', header: 'Country' }, { key: 'salary', header: 'Salary', aggregate: 'avg', align: 'end' }, ], }} ``` The menu takes it from there, and a group somebody opens or shuts stays where they left it. It also closed a hole in the accessibility sweep: a group row had never been rendered by a fixture, because no fixture could produce one. ## A cell you can type into, and one place that judges it A grid that only shows rows is a report; the thing that makes it an application surface is being able to change a value in it. `column.editable` is the whole opt-in, and `def.onCellEdit` is the one function that both judges an edit and is told about it — answer nothing to accept the value, or a string to refuse it: ```tsx (columnKey === 'name' && !String(value).trim() ? 'A name is required' : undefined), columns: [ { key: 'name', header: 'Name', editable: true }, { key: 'salary', header: 'Salary', editable: true, align: 'end' }, { key: 'active', header: 'Active', editable: true }, { key: 'country', header: 'Country', editable: true, editor: { type: 'select', options: [{ value: 'Japan' }, { value: 'Peru' }] } }, ], }} /> ``` **Which editor a cell opens is read off the value in it** — a number gets a numeric field, a boolean a checkbox, everything else a text field — so a column of numbers has a numeric keypad on a phone without being told. `editor` names one of the four (`text`, `number`, `checkbox`, `select`) or configures it, and `EditCell` is a control of your own, bound to `cell.draft` with `cell.commitEdit()` and `cell.cancelEdit()` beside it — the same three calls the built-in four make, so a date picker is a component and not a second copy of the commit rules. **A `select` editor opens its list with the editor**, highlighting the value already in the cell, so choosing one is the single gesture it looks like. The list is the whole control there — an editor that opened and then waited for a second press to show what could be chosen is the interaction a select editor cannot design out of a native `` and the page-number input were unlabelled beside them, both critical axe failures. All six are named now — and the a11y sweep grew a paginated grid fixture, which is what found them: the two DataGrid fixtures it already had never rendered a pager. - **The DataGrid's two tree props were spread onto the element it renders.** `expandedTreeKeys` and `onExpandedTreeKeysChange` were never taken off the props on their way through, so they reached `` with everything else — exactly what the comment above that line forbids ("a new grid prop cannot leak onto the element by being forgotten"). Nothing was visible, since Box forwards only what is in `props`, but a future prop of that name on Box would have been set by a grid that never meant to. Both come off now. - **A `DataGrid` given a callback but no value prop did nothing at all.** `` without a `page` beside it fired the callback on every press of the pager and never moved — and the same for `onGlobalFilterChange` without `globalFilterValue`, `onColumnFiltersChange`, `onPageSizeChange` and `onExpandedRowKeysChange`. The grid read the _handler_ as "the caller owns this state", so a grid wired up only to watch its user was left with a pager, a filter box and a set of expanders that could not change anything. A handler is a listener; ownership is the value prop, which still wins wherever it is passed. --- _Every page: https://www.box-kite.dev/llms.txt · every prop, measured: https://www.box-kite.dev/props.md_