@cube-dev/ui-kit 0.0.0-canary-1f0dd2c → 0.0.0-canary-1d27aa0

package/docs/components/layout/Board.md

@@ -1,8 +1,14 @@
 # Board
 
-A draggable and resizable widget grid for building dashboards. Widgets are declared with `Board.Widget` and positioned via a `layout` (grid units). Wrap multiple boards in a `BoardProvider` (`Board.Provider`) to drag widgets between them, including out of a nested board into its parent.
+A draggable and resizable widget grid for building dashboards. Widgets are
+declared with `Board.Widget` and positioned via a `layout` (grid units). Wrap
+multiple boards in a `BoardProvider` (`Board.Provider`) to drag widgets between
+them, including out of a nested board into its parent.
 
-Dragging and resizing are powered by React Aria's `useMove`, so they work with mouse, touch, and keyboard (focus a widget and use the arrow keys). While a widget is dragged with a pointer it renders into a fixed overlay so it is never clipped by an ancestor's `overflow: hidden`.
+Dragging and resizing are powered by React Aria's `useMove`, so they work with
+mouse, touch, and keyboard (focus a widget and use the arrow keys). While a
+widget is dragged with a pointer it renders into a fixed overlay so it is never
+clipped by an ancestor's `overflow: hidden`.
 
 ## When to Use
 
@@ -17,11 +23,25 @@ Dragging and resizing are powered by React Aria's `useMove`, so they work with m
 
 ## Concepts
 
-- **Layout** — an array of items `{ i, x, y, w, h }` in grid units. `i` matches a `Board.Widget` `id`.
-- **Content vs. position** — `Board.Widget` declares content; the owning `Board` positions it. This decoupling is what lets a widget be transferred between boards.
-- **Compaction** — `vertical` (default), `horizontal`, or `free`. In `free` mode a widget is placed exactly where you drop it and its neighbours are never pushed or swapped; without `allowOverlap` a drop onto an occupied cell is blocked, and with `allowOverlap` widgets may stack for a fully free canvas.
-- **Selection** — off by default. Pressing a widget selects it and arms a drag of the selection: selecting and grabbing are one gesture, so move the pointer and it drags, stay still and it was just a selection. <kbd>Shift</kbd> (or <kbd>Cmd</kbd>/<kbd>Ctrl</kbd>) toggles a widget's membership. Keys are layout item ids, scoped to a single board, and always reported in layout order.
-- **Selection is focus-like** — it tracks what the user is working with, and touching anything else moves it on: pressing another widget makes _that_ the selection, pressing a control inside a widget drops it, and so does focus leaving the board. With `'multiple'`, pressing an already-selected widget keeps the selection so a drag moves the whole block.
+- **Layout** — an array of items `{ i, x, y, w, h }` in grid units. `i` matches a
+  `Board.Widget` `id`.
+- **Content vs. position** — `Board.Widget` declares content; the owning `Board`
+  positions it. This decoupling is what lets a widget be transferred between
+  boards.
+- **Compaction** — `vertical` (default), `horizontal`, or `free`. In `free` mode a
+  widget is placed exactly where you drop it and its neighbours are never pushed
+  or swapped; without `allowOverlap` a drop onto an occupied cell is blocked, and
+  with `allowOverlap` widgets may stack for a fully free canvas.
+- **Selection** — off by default. Pressing a widget selects it and arms a drag
+  of the selection: selecting and grabbing are one gesture, so move the pointer
+  and it drags, stay still and it was just a selection. <kbd>Shift</kbd> (or
+  <kbd>Cmd</kbd>/<kbd>Ctrl</kbd>) toggles a widget's membership. Keys are layout
+  item ids, scoped to a single board, and always reported in layout order.
+- **Selection is focus-like** — it tracks what the user is working with, and
+  touching anything else moves it on: pressing another widget makes *that* the
+  selection, pressing a control inside a widget drops it, and so does focus
+  leaving the board. With `'multiple'`, pressing an already-selected widget
+  keeps the selection so a drag moves the whole block.
 
 ## Properties
 
@@ -41,21 +61,21 @@ Dragging and resizing are powered by React Aria's `useMove`, so they work with m
 - **`compact`** `'vertical' | 'horizontal' | 'free' | null` (default: `'vertical'`) — Compaction behavior. `'vertical'`/`'horizontal'` reflow widgets to remove gaps; `'free'` places each widget exactly where dropped and never pushes its neighbours (blocked from occupied cells unless `allowOverlap`); `null` disables compaction but still resolves collisions the legacy react-grid-layout way.
 - **`allowOverlap`** `boolean` (default: `false`) — Allow widgets to overlap (stack). In `'free'` mode this is what distinguishes stacking from blocking a drop onto an occupied cell.
 - **`preventCollision`** `boolean` (default: `false`) — Block movement into occupied cells instead of pushing.
-- **`collisionMode`** `'revert' | 'downscale' | 'swap'` (default: `'revert'`) — How to resolve a drop the grid would otherwise refuse. Only applies where a collision _blocks_ a move — `compact="free"` (which prevents collisions) or an explicit `preventCollision` — and never under `allowOverlap`, where nothing is blocked. `'revert'` snaps the widget back. `'downscale'` shrinks it into the free space at the drop cell, growing rightward and downward, floored at its `minW`/`minH` (below that it reverts). Within one board, `'swap'` trades places with **one** widget — the one the drop covers most — which takes the cell the drag began at, each keeping as much of its own size as fits there. It never displaces more than that one widget. A drop straddling two widgets trades with one of them rather than refusing, so the swap never blinks away as you sweep across a boundary; ties go to the widget earlier in reading order. Dragging back retraces the original arrangement exactly. For a widget arriving from another board (including a nested board entering its parent), the destination board's `'swap'` mode becomes strict insertion: the requested anchor cell must be empty, the incoming widget keeps its size when possible or downscales into the available room to its right and below, and existing destination widgets are neither exchanged nor reflowed. Releasing over an occupied anchor or where `minW`/`minH` cannot fit cancels the transfer and restores both boards; it does not reuse the last valid preview or search for another slot. No mode ever _grows_ a widget. Applies to single-widget drags. Arrow keys honour it too but never resize anything — each press is a gesture of its own, so a press that shrank a widget would have nothing to restore from, and only an exchange that fits outright is allowed. A multi-widget selection still only moves where it fits outright, and a resize is still blocked by a collision.
+- **`collisionMode`** `'revert' | 'downscale' | 'swap'` (default: `'revert'`) — How to resolve a drop the grid would otherwise refuse. Only applies where a collision *blocks* a move — `compact="free"` (which prevents collisions) or an explicit `preventCollision` — and never under `allowOverlap`, where nothing is blocked. `'revert'` snaps the widget back. `'downscale'` shrinks it into the free space at the drop cell, growing rightward and downward, floored at its `minW`/`minH` (below that it reverts). Within one board, `'swap'` trades places with **one** widget — the one the drop covers most — which takes the cell the drag began at, each keeping as much of its own size as fits there. It never displaces more than that one widget. A drop straddling two widgets trades with one of them rather than refusing, so the swap never blinks away as you sweep across a boundary; ties go to the widget earlier in reading order. Dragging back retraces the original arrangement exactly. For a widget arriving from another board (including a nested board entering its parent), the destination board's `'swap'` mode becomes strict insertion: the requested anchor cell must be empty, the incoming widget keeps its size when possible or downscales into the available room to its right and below, and existing destination widgets are neither exchanged nor reflowed. Releasing over an occupied anchor or where `minW`/`minH` cannot fit cancels the transfer and restores both boards; it does not reuse the last valid preview or search for another slot. No mode ever *grows* a widget. Applies to single-widget drags. Arrow keys honour it too but never resize anything — each press is a gesture of its own, so a press that shrank a widget would have nothing to restore from, and only an exchange that fits outright is allowed. A multi-widget selection still only moves where it fits outright, and a resize is still blocked by a collision.
 - **`isDraggable`** `boolean` (default: `true`) — Enable dragging for all widgets.
 - **`isResizable`** `boolean` (default: `true`) — Enable resizing for all widgets.
 - **`isDroppable`** `boolean` (default: `true`) — Whether the board accepts widgets dropped from other boards.
 - **`resizeHandles`** `ResizeHandleAxis[]` (default: `['se']`) — Which resize handles to show. Corner handles (`ne`/`nw`/`se`/`sw`) show an angle grip; edge handles (`n`/`s`/`e`/`w`) show a dotted grip. Both are revealed on hover/focus/resize. A single edge (e.g. `['e']` or `['s']`) gives a horizontally- or vertically-only resizable widget.
-- **`resizeGripPlacement`** `'inside' | 'corner'` (default: `'inside'`) — Where the corner grips sit. `'inside'` tucks each one into the widget box; `'corner'` centres it on the widget's corner, so it lines up with a control centred on the opposite corner. Only affects corner handles — a dotted edge grip always stays inside. A corner-placed grip is drawn _outside_ the widget (a widget clips its own content, which would otherwise cut the grip in half), so it needs the board to have at least half a grip's worth of `containerPadding` to show in full against the board's edge. Its hit-zone moves out with it and overhangs by the same half-grip, so the whole visible grip is grabbable and hovering it keeps it revealed — the trade is a ~5px band just outside each corner where a press starts a resize rather than a marquee. Can be overridden per widget.
+- **`resizeGripPlacement`** `'inside' | 'corner'` (default: `'inside'`) — Where the corner grips sit. `'inside'` tucks each one into the widget box; `'corner'` centres it on the widget's corner, so it lines up with a control centred on the opposite corner. Only affects corner handles — a dotted edge grip always stays inside. A corner-placed grip is drawn *outside* the widget (a widget clips its own content, which would otherwise cut the grip in half), so it needs the board to have at least half a grip's worth of `containerPadding` to show in full against the board's edge. Its hit-zone moves out with it and overhangs by the same half-grip, so the whole visible grip is grabbable and hovering it keeps it revealed — the trade is a ~5px band just outside each corner where a press starts a resize rather than a marquee. Can be overridden per widget.
 - **`dragCancel`** `string` — CSS selector for elements that must not start a pointer drag (e.g. form controls inside a widget: `"input,textarea,button,a,.no-drag"`). Does not affect keyboard moves — those only run when the widget host itself is focused. Can be overridden per widget.
 - **`dragHandle`** `string` — CSS selector for the only elements from which a pointer drag may start. Can be overridden per widget.
-- **`showGridLines`** `boolean | 'drag' | 'any-drag'` (default: `false`) — Show grid lines behind the widgets. `true` always; `false` never; `'drag'` only while _this_ board is part of the active gesture — it owns the drag (as its source, or as the board the widget is currently over) or one of its own widgets is being resized; `'any-drag'` while any drag is in flight anywhere under a shared `Board.Provider`, so every board advertises itself as somewhere the widget could land. Under one `Board.Provider`, `'drag'` keeps boards a widget cannot land in quiet, and `'any-drag'` is the opt-in for the noisier, more informative version. A nested board that does not set this inherits an enabled ancestor's setting, at the ancestor's own scope.
+- **`showGridLines`** `boolean | 'drag' | 'any-drag'` (default: `false`) — Show grid lines behind the widgets. `true` always; `false` never; `'drag'` only while *this* board is part of the active gesture — it owns the drag (as its source, or as the board the widget is currently over) or one of its own widgets is being resized; `'any-drag'` while any drag is in flight anywhere under a shared `Board.Provider`, so every board advertises itself as somewhere the widget could land. Under one `Board.Provider`, `'drag'` keeps boards a widget cannot land in quiet, and `'any-drag'` is the opt-in for the noisier, more informative version. A nested board that does not set this inherits an enabled ancestor's setting, at the ancestor's own scope.
 - **`isAligned`** `boolean` (default: `false`) — Align a nested board with its ancestor `Board`'s layout. Only takes effect when the board is nested inside another `Board`'s widget. When set, every cell matches the parent's cell size exactly: the board inherits the parent's column pitch (deriving its own column count from its measured width so cells stay parent-sized as the container is resized) and uses the parent's row height verbatim. It never shrinks rows to fit — pair it with an `isAutoHeight` container so the widget grows to fit its rows at that height. `cols`/`rowHeight` then act as fallbacks used only until the parent metrics resolve.
 - **`selectionMode`** `'none' | 'single' | 'multiple'` (default: `'none'`) — Whether widgets can be selected, and how many at a time. `'multiple'` also enables the marquee and rigid group movement.
 - **`selectedKeys`** `string[]` — Controlled selection. Keys are layout item ids (`LayoutItem.i`).
 - **`defaultSelectedKeys`** `string[]` — Initial selection for uncontrolled usage.
 - **`onSelectionChange`** `(keys: string[]) => void` — Called when the selection changes. Keys are deduped and returned in the board's layout order, never in click order.
-- **`selectionCancel`** `string` (default: `BOARD_SELECTION_CANCEL`) — CSS selector marking interactive descendants. A press on one never selects and never starts a drag, so the control keeps its own click _and_ its native focus; it also drops the selection, since interacting with a widget's content means the user has moved on. On a selectable board this doubles as the drag guard, so form controls stay usable without also configuring `dragCancel`. The default covers native form controls, links, and the common ARIA widget roles, plus `[data-no-select]` as an escape hatch. Pass `''` to disable the guard. Can be overridden per widget.
+- **`selectionCancel`** `string` (default: `BOARD_SELECTION_CANCEL`) — CSS selector marking interactive descendants. A press on one never selects and never starts a drag, so the control keeps its own click *and* its native focus; it also drops the selection, since interacting with a widget's content means the user has moved on. On a selectable board this doubles as the drag guard, so form controls stay usable without also configuring `dragCancel`. The default covers native form controls, links, and the common ARIA widget roles, plus `[data-no-select]` as an escape hatch. Pass `''` to disable the guard. Can be overridden per widget.
 - **`allowMarqueeSelection`** `boolean` (default: `selectionMode === 'multiple'`) — Draw a rubber-band selection when a drag starts on empty board space. A press on a widget selects and drags instead, so the lasso owns empty canvas only. Hold <kbd>Shift</kbd> or <kbd>Cmd</kbd>/<kbd>Ctrl</kbd> to add to the existing selection rather than replacing it. A board sized to its content has no empty space left once the grid fills up, which makes the lasso undiscoverable — use `extraRows` to keep a band of it.
 - **`onWidgetsDelete`** `(keys: string[]) => void` — Called when <kbd>Delete</kbd>/<kbd>Backspace</kbd> is pressed with a non-empty selection and focus is not in an editable field. **Board never mutates the layout itself** — removing the widgets is yours to do, which is what lets you make it undoable. Board only handles these keys when this handler is set.
 - **`constraints`** `LayoutConstraint[]` — Grid/item layout constraints.
@@ -87,19 +107,35 @@ Dragging and resizing are powered by React Aria's `useMove`, so they work with m
 - **`selectionCancel`** `string` — Override the board's `selectionCancel` selector for this widget.
 - **`aria-label`** `string` — Accessible name for the widget. Falls back to `qa`, then the layout item id — both developer-facing, so set this whenever the widget is user-visible. Also what the selection announcement reads out.
 
-A widget clips its content to its grid cell, card or not — otherwise a nested board with more rows than currently fit, or a mid-drag reflow, would paint over its neighbours. The cost is that a descendant's `outline` is cropped at the edge (an outline is clipped by an _ancestor's_ overflow, not its own), so a widget whose content must paint outside — a control drawing its own active ring — sets `overflow="visible"`, or draws the ring inset with a negative `outlineOffset`.
+A widget clips its content to its grid cell, card or not — otherwise a nested
+board with more rows than currently fit, or a mid-drag reflow, would paint over
+its neighbours. The cost is that a descendant's `outline` is cropped at the edge
+(an outline is clipped by an *ancestor's* overflow, not its own), so a widget
+whose content must paint outside — a control drawing its own active ring — sets
+`overflow="visible"`, or draws the ring inset with a negative `outlineOffset`.
 
 ### Board.Provider
 
-Shares one drag context across multiple boards. A standalone `Board` provides its own automatically; only use `Board.Provider` when you need cross-board dragging.
+Shares one drag context across multiple boards. A standalone `Board` provides its
+own automatically; only use `Board.Provider` when you need cross-board dragging.
 
-- **`onWidgetTransfer`** `(info: { widgetId, fromBoardId, toBoardId, item }) => void` — Fired when a widget is dropped from one board into another.
+- **`onWidgetTransfer`** `(info: { widgetId, fromBoardId, toBoardId, item }) => void` —
+  Fired when a widget is dropped from one board into another.
 
-Dragging a widget across a container that can unmount (for example, out of an inactive `Tab`) requires controlled ownership: a widget's content is declared by its `Board.Widget`, so if that declaration unmounts the content is lost. Keep each board's `layout` controlled and, in response to `onWidgetTransfer`, move the `Board.Widget` declaration into the destination container so the content follows the widget. The [Boards inside Tabs](#boards-inside-tabs) example shows the pattern.
+Dragging a widget across a container that can unmount (for example, out of an
+inactive `Tab`) requires controlled ownership: a widget's content is declared by
+its `Board.Widget`, so if that declaration unmounts the content is lost. Keep
+each board's `layout` controlled and, in response to `onWidgetTransfer`, move the
+`Board.Widget` declaration into the destination container so the content follows
+the widget. The [Boards inside Tabs](#boards-inside-tabs) example shows the
+pattern.
 
 ### Board.Responsive
 
-A wrapper around `Board` that selects a layout and column count based on the container's measured width, mirroring react-grid-layout's `Responsive` + `WidthProvider`. It accepts all `Board` props except `layout`, `defaultLayout`, `cols`, `onLayoutChange`, and `width` (which it manages), plus:
+A wrapper around `Board` that selects a layout and column count based on the
+container's measured width, mirroring react-grid-layout's `Responsive` +
+`WidthProvider`. It accepts all `Board` props except `layout`, `defaultLayout`,
+`cols`, `onLayoutChange`, and `width` (which it manages), plus:
 
 - **`breakpoints`** `Record<string, number>` — Breakpoint name to minimum container width (px).
 - **`cols`** `Record<string, number>` — Breakpoint name to column count.
@@ -111,14 +147,17 @@ A wrapper around `Board` that selects a layout and column count based on the con
 - **`breakpoint`** `string` — Force a specific breakpoint regardless of width (e.g. for a fixed-size screenshot or PDF export).
 - **`width`** `number` — Explicit width; disables measurement (SSR/tests/forced-size exports).
 
-A breakpoint with no layout is synthesized from the nearest available one, corrected into bounds and compacted for the target column count.
+A breakpoint with no layout is synthesized from the nearest available one,
+corrected into bounds and compacted for the target column count.
 
 ### Modifiers
 
-Every widget host exposes these as `data-*` attributes, and any style map passed through `widgetProps.styles` or a per-widget `styles` resolves against them.
+Every widget host exposes these as `data-*` attributes, and any style map passed
+through `widgetProps.styles` or a per-widget `styles` resolves against them.
 
 - **`selected`** — the widget is in the board's selection.
-- **`pre-selected`** — a live marquee covers the widget, so releasing the pointer will select it. Never set at the same time as `selected`.
+- **`pre-selected`** — a live marquee covers the widget, so releasing the pointer
+  will select it. Never set at the same time as `selected`.
 - **`card`** — the widget draws a card border (`isCard`).
 - **`draggable`** — the widget can be dragged and no drag is in flight.
 - **`drag`** — the widget is being dragged.
@@ -128,7 +167,13 @@ Every widget host exposes these as `data-*` attributes, and any style map passed
 - **`hovered`**, **`focus-visible`** — pointer and keyboard-focus states.
 - **`settled`** — the board has painted its widgets once, so position changes animate.
 
-Selection is an _edge_ treatment — a `#primary-border` border plus a `#primary` ring — because it reads as a focus-like state rather than a fill. `outline` stays reserved for the real focus ring, which is what keeps the two legible together: they use different tokens and the focus outline sits one border-width further out. `pre-selected` draws the same edge with the ring dimmed, so committing a lasso only changes the strength of something already on screen. To restyle either, override the same keys:
+Selection is an *edge* treatment — a `#primary-border` border plus a `#primary`
+ring — because it reads as a focus-like state rather than a fill. `outline` stays
+reserved for the real focus ring, which is what keeps the two legible together:
+they use different tokens and the focus outline sits one border-width further
+out. `pre-selected` draws the same edge with the ring dimmed, so committing a
+lasso only changes the strength of something already on screen. To restyle
+either, override the same keys:
 
 ```jsx
 <Board
@@ -159,7 +204,9 @@ Supports [Base properties](../../BaseProperties.md).
 
 ### Style Properties
 
-These properties allow direct style application without using the `styles` prop. Note: `margin` is repurposed as the grid gap (see Properties above) rather than a CSS margin.
+These properties allow direct style application without using the `styles` prop.
+Note: `margin` is repurposed as the grid gap (see Properties above) rather than a
+CSS margin.
 
 - **Base:** `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`
 - **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `scrollMargin`
@@ -174,11 +221,14 @@ These properties allow direct style application without using the `styles` prop.
 
 ### Free positioning
 
-A widget stays exactly where you drop it and never shuffles its neighbours. Dropping onto an occupied cell is blocked, so the widget stays at its last free spot.
+A widget stays exactly where you drop it and never shuffles its neighbours.
+Dropping onto an occupied cell is blocked, so the widget stays at its last free
+spot.
 
 ### Free positioning (overlap)
 
-Add `allowOverlap` to let widgets stack on top of each other instead of being blocked from occupied cells.
+Add `allowOverlap` to let widgets stack on top of each other instead of being
+blocked from occupied cells.
 
 ### Horizontal compaction
 
@@ -190,23 +240,34 @@ Bound resizing with per-widget `minW`/`maxW` (columns) and `minH`/`maxH` (rows).
 
 ### Grid lines
 
-Show grid lines behind the widgets while dragging or resizing (or always). With several boards under one `Board.Provider`, `'drag'` lights up only the board the drag belongs to; `'any-drag'` lights up all of them.
+Show grid lines behind the widgets while dragging or resizing (or always). With
+several boards under one `Board.Provider`, `'drag'` lights up only the board the
+drag belongs to; `'any-drag'` lights up all of them.
 
 ### Corner resize grip
 
-Centre the resize grip on the widget's corner with `resizeGripPlacement="corner"`, so it lines up with a control centred on the opposite corner.
+Centre the resize grip on the widget's corner with `resizeGripPlacement="corner"`,
+so it lines up with a control centred on the opposite corner.
 
 ### Resolving a blocked drop
 
-On a free grid a drop onto occupied cells is refused. `collisionMode` resolves it instead: `'downscale'` shrinks the widget into whatever room is at the drop cell. Within one board, `'swap'` trades places with the widget already there. Across boards, the same mode inserts only at an empty anchor and downscales without moving destination widgets; an invalid release cancels the transfer. None of these paths ever grows a widget. The examples below show all three behaviors.
+On a free grid a drop onto occupied cells is refused. `collisionMode` resolves it
+instead: `'downscale'` shrinks the widget into whatever room is at the drop cell.
+Within one board, `'swap'` trades places with the widget already there. Across
+boards, the same mode inserts only at an empty anchor and downscales without
+moving destination widgets; an invalid release cancels the transfer. None of
+these paths ever grows a widget. The examples below show all three behaviors.
 
 ### Card widgets
 
-Widgets are filled (`#surface-2`) and rounded by default, but borderless. Add a card border per widget with `isCard`, or for the whole board at once with `widgetProps={{ isCard: true }}`. Per-widget `isCard` overrides the board default.
+Widgets are filled (`#surface-2`) and rounded by default, but borderless. Add a
+card border per widget with `isCard`, or for the whole board at once with
+`widgetProps={{ isCard: true }}`. Per-widget `isCard` overrides the board default.
 
 ### Drag cancel
 
-Keep interactive controls inside a widget clickable by excluding them from the drag gesture with `dragCancel`.
+Keep interactive controls inside a widget clickable by excluding them from the
+drag gesture with `dragCancel`.
 
 ### Responsive
 
@@ -218,27 +279,63 @@ Wrap boards in `Board.Provider` to drag widgets between them.
 
 ### Nested boards
 
-A `Board` can be placed inside a `Board.Widget`, making the whole container draggable while its children can be dragged out into sibling boards.
+A `Board` can be placed inside a `Board.Widget`, making the whole container
+draggable while its children can be dragged out into sibling boards.
 
-Set `isAligned` on the nested board to align it with the surrounding layout: every cell matches the parent's cell size exactly. Its columns keep the parent's pixel pitch (so resizing the container adds or removes columns instead of stretching them) and its rows use the parent's row height verbatim.
+Set `isAligned` on the nested board to align it with the surrounding layout:
+every cell matches the parent's cell size exactly. Its columns keep the parent's
+pixel pitch (so resizing the container adds or removes columns instead of
+stretching them) and its rows use the parent's row height verbatim.
 
-Because an aligned board never shrinks its rows to fit, add `isAutoHeight` to the container `Board.Widget` so it grows (only ever taller) until the inner board's rows fit at the parent's row height. It also stops the container's resize handle at that height, so you can't drag it shorter than the inner board needs.
+Because an aligned board never shrinks its rows to fit, add `isAutoHeight` to the
+container `Board.Widget` so it grows (only ever taller) until the inner board's
+rows fit at the parent's row height. It also stops the container's resize handle
+at that height, so you can't drag it shorter than the inner board needs.
 
 ### Aligned nested boards
 
-A nested `Board` with `isAligned` and no padding, fill, border, or radius of its own — only a header above the grid — inherits the parent column pitch with zero offset, so its columns line up exactly with the outer board. Grid lines are shown on both boards while dragging to verify the alignment.
+A nested `Board` with `isAligned` and no padding, fill, border, or radius of its
+own — only a header above the grid — inherits the parent column pitch with zero
+offset, so its columns line up exactly with the outer board. Grid lines are
+shown on both boards while dragging to verify the alignment.
 
 ### Boards inside Tabs
 
-A `Board.Widget` can host a `Tabs` where each tab renders its own `Board`, all under a shared `Board.Provider` so widgets can be dragged between tabs and out into the surrounding board. Because an inactive tab unmounts, this example is fully controlled: each board's `layout` is controlled and `onWidgetTransfer` moves a widget's declaration into the destination container so its content survives dragging out of (and switching away from) a tab.
-
-When a `Tabs` sits inside a `Board`, tab switching becomes "spring-loaded" automatically: while you drag a widget, hovering a tab header for a moment opens that tab so you can drop into it (or move a widget between tabs). This needs no setup - `Tabs` detects the active Board drag and, for its duration, keeps panels mounted so the tab a widget is dragged out of (and the board owning the in-flight drag) is not unmounted mid-gesture. Spring-loading works with mouse and pen; touch drags capture the pointer, so they do not trigger it.
+A `Board.Widget` can host a `Tabs` where each tab renders its own `Board`, all
+under a shared `Board.Provider` so widgets can be dragged between tabs and out
+into the surrounding board. Because an inactive tab unmounts, this example is
+fully controlled: each board's `layout` is controlled and `onWidgetTransfer`
+moves a widget's declaration into the destination container so its content
+survives dragging out of (and switching away from) a tab.
+
+When a `Tabs` sits inside a `Board`, tab switching becomes "spring-loaded"
+automatically: while you drag a widget, hovering a tab header for a moment opens
+that tab so you can drop into it (or move a widget between tabs). This needs no
+setup - `Tabs` detects the active Board drag and, for its duration, keeps panels
+mounted so the tab a widget is dragged out of (and the board owning the in-flight
+drag) is not unmounted mid-gesture. Spring-loading works with mouse and pen;
+touch drags capture the pointer, so they do not trigger it.
 
 ### Selection
 
-Press a widget to select it, <kbd>Shift</kbd>-press to add or remove one, and drag from empty board space to lasso. Because the press both selects and arms the drag, grabbing a widget you have not selected simply makes it the selection and moves it; grabbing one that _is_ selected moves the whole block rigidly — keeping its shape, clamping against the grid edge as a unit rather than collapsing, and committing once. While the band is out, the widgets it covers show a dimmed version of the selected edge (`pre-selected`), and no text can be selected under it.
-
-A group reflows like a single widget — it is compacted by the same rules, so on a `vertical` board it can no more be parked in empty space than one widget can, and the widgets around it close the gap in the same frame — but it does so as one block. Its members keep their exact offsets for the whole drag, and the widgets standing where it lands move out of its way rather than being packed between its members — whether it is dragged against the compaction axis or across it. When the drag ends the board compacts normally, so a group whose members could each float further settles on release. Under `compact="free"` (or `null`) nothing compacts, so the block stays precisely where it was dropped.
+Press a widget to select it, <kbd>Shift</kbd>-press to add or remove one, and
+drag from empty board space to lasso. Because the press both selects and arms the
+drag, grabbing a widget you have not selected simply makes it the selection and
+moves it; grabbing one that *is* selected moves the whole block rigidly — keeping
+its shape, clamping against the grid edge as a unit rather than collapsing, and
+committing once. While the band is out, the widgets it covers show a dimmed
+version of the selected edge (`pre-selected`), and no text can be selected under
+it.
+
+A group reflows like a single widget — it is compacted by the same rules, so on a
+`vertical` board it can no more be parked in empty space than one widget can, and
+the widgets around it close the gap in the same frame — but it does so as one
+block. Its members keep their exact offsets for the whole drag, and the widgets
+standing where it lands move out of its way rather than being packed between its
+members — whether it is dragged against the compaction axis or across it. When
+the drag ends the board compacts normally, so a group whose members could each
+float further settles on release. Under `compact="free"` (or `null`) nothing compacts,
+so the block stays precisely where it was dropped.
 
 ### Interactive content keeps its clicks
 
@@ -259,30 +356,73 @@ A group reflows like a single widget — it is compacted by the same rules, so o
 | <kbd>Escape</kbd> | Clear the selection. |
 | <kbd>Delete</kbd> / <kbd>Backspace</kbd> | Request deletion of the selection via `onWidgetsDelete`. |
 
-Arrow keys and <kbd>Space</kbd> only act when the widget host **itself** is focused, never when focus is inside a nested control, so an `input`, `textarea`, or `button` inside a widget keeps every key it needs. Board's own keys are handled on the board element rather than on `document`, and are only consumed when they actually do something — an <kbd>Escape</kbd> with nothing selected still reaches an ancestor Dialog, and <kbd>Backspace</kbd> stays available for text editing and browser-back.
+Arrow keys and <kbd>Space</kbd> only act when the widget host **itself** is
+focused, never when focus is inside a nested control, so an `input`,
+`textarea`, or `button` inside a widget keeps every key it needs. Board's own
+keys are handled on the board element rather than on `document`, and are only
+consumed when they actually do something — an <kbd>Escape</kbd> with nothing
+selected still reaches an ancestor Dialog, and <kbd>Backspace</kbd> stays
+available for text editing and browser-back.
 
-Every draggable or selectable widget is its own tab stop. Roving tabindex would be an improvement on a large board, but arrow keys are already claimed for movement, so it needs a navigation key set of its own — see below.
+Every draggable or selectable widget is its own tab stop. Roving tabindex would
+be an improvement on a large board, but arrow keys are already claimed for
+movement, so it needs a navigation key set of its own — see below.
 
 ### Screen Reader Support
 
-Each widget host is a `group` with an accessible name, taken from `aria-label`, then `qa`, then the layout item id — set `aria-label` on any user-visible widget, since the other two are developer-facing. Draggable widgets carry a localized `aria-roledescription`, and selectable ones advertise `aria-keyshortcuts="Space"`.
+Each widget host is a `group` with an accessible name, taken from
+`aria-label`, then `qa`, then the layout item id — set `aria-label` on any
+user-visible widget, since the other two are developer-facing. Draggable widgets
+carry a localized `aria-roledescription`, and selectable ones advertise
+`aria-keyshortcuts="Space"`.
 
-Selection state is conveyed two ways: a selected widget is described as "Selected" via `aria-describedby`, and every selection change is announced through a polite live region owned by the board ("Revenue selected", "3 widgets selected", "Selection cleared"). A marquee announces once, on release — not once per pointer frame.
+Selection state is conveyed two ways: a selected widget is described as
+"Selected" via `aria-describedby`, and every selection change is announced
+through a polite live region owned by the board ("Revenue selected", "3 widgets
+selected", "Selection cleared"). A marquee announces once, on release — not once
+per pointer frame.
 
 ### ARIA Properties
 
-Board deliberately does **not** use a collection role. `aria-selected` is only valid on `option`, `gridcell`, `row`, `treeitem` and friends, and every one of those requires presentational children — but a Board widget hosts arbitrary interactive content (nested boards, tabs, inputs), and a `grid`'s keyboard model would fight `useMove`'s arrow keys. Rather than ship ARIA that lies about the structure, selection is exposed through the name, description, and live region described above. Set `aria-label` on your widgets and this reads correctly.
+Board deliberately does **not** use a collection role. `aria-selected` is only
+valid on `option`, `gridcell`, `row`, `treeitem` and friends, and every one of
+those requires presentational children — but a Board widget hosts arbitrary
+interactive content (nested boards, tabs, inputs), and a `grid`'s keyboard model
+would fight `useMove`'s arrow keys. Rather than ship ARIA that lies about the
+structure, selection is exposed through the name, description, and live region
+described above. Set `aria-label` on your widgets and this reads correctly.
 
 ## Not yet supported
 
-- **External drag-in from a palette** — dragging a brand-new widget from an element outside any board into the grid (react-grid-layout's `isDroppable`/`onDrop`/`droppingItem`) is not implemented. Board's drag engine is built entirely on React Aria's `useMove` over registered widgets; drag-in is a separate HTML5 drag-and-drop modality (pixel-to-grid mapping, a dropping placeholder, and new `onDrop`/`droppingItem` props). Add widgets programmatically (render a new `Board.Widget` and add its layout item), or drag between boards with `Board.Provider`.
-- **Cross-board group transfer** — a group drag never leaves its source board. Cross-board transfer is single-item throughout (`WidgetTransferInfo`, the carried preview, the free-slot fallback), and landing a group on a board with a different column count has no obvious right answer. Degrading to a single-widget transfer would silently split a selection the user made, so the gesture is confined instead. Drag widgets across one at a time.
-- **Collection ARIA semantics** — `role="grid"`/`option`, `aria-selected` and `aria-multiselectable`, for the reason above.
-- **Roving tabindex** — needs a widget-navigation key set that does not collide with `useMove`'s arrow keys.
+- **External drag-in from a palette** — dragging a brand-new widget from an
+  element outside any board into the grid (react-grid-layout's
+  `isDroppable`/`onDrop`/`droppingItem`) is not implemented. Board's drag engine
+  is built entirely on React Aria's `useMove` over registered widgets; drag-in
+  is a separate HTML5 drag-and-drop modality (pixel-to-grid mapping, a dropping
+  placeholder, and new `onDrop`/`droppingItem` props). Add widgets
+  programmatically (render a new `Board.Widget` and add its layout item), or drag
+  between boards with `Board.Provider`.
+- **Cross-board group transfer** — a group drag never leaves its source board.
+  Cross-board transfer is single-item throughout (`WidgetTransferInfo`, the
+  carried preview, the free-slot fallback), and landing a group on a board with a
+  different column count has no obvious right answer. Degrading to a
+  single-widget transfer would silently split a selection the user made, so the
+  gesture is confined instead. Drag widgets across one at a time.
+- **Collection ARIA semantics** — `role="grid"`/`option`, `aria-selected` and
+  `aria-multiselectable`, for the reason above.
+- **Roving tabindex** — needs a widget-navigation key set that does not collide
+  with `useMove`'s arrow keys.
 - **<kbd>Cmd/Ctrl</kbd>+<kbd>A</kbd>** — select all.
-- **Cross-board marquee and cross-board selection** — selection is per board; a `Board.Provider` shares drag, not selection.
-- **Windows High Contrast Mode** — no component in the kit styles for `forced-colors` yet. The selected state uses a tint, a border _and_ an extra ring, so it does not rely on hue alone, but a full forced-colors pass is a system-wide change.
+- **Cross-board marquee and cross-board selection** — selection is per board; a
+  `Board.Provider` shares drag, not selection.
+- **Windows High Contrast Mode** — no component in the kit styles for
+  `forced-colors` yet. The selected state uses a tint, a border *and* an extra
+  ring, so it does not rely on hue alone, but a full forced-colors pass is a
+  system-wide change.
 
 ## Attribution
 
-The layout engine in `grid-core/` is a vendored, trimmed copy of [react-grid-layout](https://github.com/react-grid-layout/react-grid-layout) (MIT). The React layer is a UI Kit-native reimplementation on top of tasty and React Aria. See `grid-core/NOTICE.md`.
+The layout engine in `grid-core/` is a vendored, trimmed copy of
+[react-grid-layout](https://github.com/react-grid-layout/react-grid-layout)
+(MIT). The React layer is a UI Kit-native reimplementation on top of tasty and
+React Aria. See `grid-core/NOTICE.md`.

package/docs/components/navigation/Pagination.md

@@ -1,40 +1,71 @@
 # Pagination
 
-Pagination is the control for moving through a paged collection. It renders a bounded run of page buttons, optional first/last jumps, an optional page-size selector, and an optional item-range summary.
+Pagination is the control for moving through a paged collection. It renders a
+bounded run of page buttons, optional first/last jumps, an optional page-size
+selector, and an optional item-range summary.
 
-It is a pure control: it owns no data. Client-side slicing lives in the companion `usePagination` hook, and `ItemTable` composes the two.
+It is a pure control: it owns no data. Client-side slicing lives in the
+companion `usePagination` hook, and `ItemTable` composes the two.
 
 ## When to Use
 
-- Paging through a list, table, or grid where the user needs to jump around rather than scroll.
-- Cursor pagination with an unknown total — supply `hasNextPage` and omit `total`/`totalPages`, and the control degrades to prev/next.
+- Paging through a list, table, or grid where the user needs to jump around
+  rather than scroll.
+- Cursor pagination with an unknown total — supply `hasNextPage` and omit
+  `total`/`totalPages`, and the control degrades to prev/next.
 - Anywhere you need a page-size selector wired to the same state.
 
-Prefer infinite scroll when the collection is a feed the user skims, and pagination when they need stable, addressable positions.
+Prefer infinite scroll when the collection is a feed the user skims, and
+pagination when they need stable, addressable positions.
 
 ## Component
 
 ### Properties
 
-- **`page`** `number` — Controlled current page, 1-based. Pair with `onPageChange`.
-- **`defaultPage`** `number` (default: `1`) — Initial page for uncontrolled usage.
-- **`onPageChange`** `(page: number) => void` — Never fires with a page outside `1…totalPages` when the total is known.
-- **`total`** `number` — Total items across all pages. Preferred over `totalPages`; it also powers the range summary and the `select` type's range labels.
-- **`totalPages`** `number` — Total pages. Only needed when the item count is genuinely unavailable. Wins over the value derived from `total` + `pageSize`.
+- **`page`** `number` — Controlled current page, 1-based. Pair with
+  `onPageChange`.
+- **`defaultPage`** `number` (default: `1`) — Initial page for uncontrolled
+  usage.
+- **`onPageChange`** `(page: number) => void` — Never fires with a page outside
+  `1…totalPages` when the total is known.
+- **`total`** `number` — Total items across all pages. Preferred over
+  `totalPages`; it also powers the range summary and the `select` type's range
+  labels.
+- **`totalPages`** `number` — Total pages. Only needed when the item count is
+  genuinely unavailable. Wins over the value derived from `total` + `pageSize`.
 - **`pageSize`** `number` — Controlled page size.
-- **`defaultPageSize`** `number` (default: `50`) — Initial page size for uncontrolled usage.
-- **`onPageSizeChange`** `(pageSize: number) => void` — Changing the size also resets to page 1, because the old page index no longer refers to the same items.
-- **`pageSizeOptions`** `number[]` — Supplying this **and** `onPageSizeChange` renders the size selector.
-- **`type`** `'numbers' | 'select' | 'compact'` (default: `'numbers'`) — How the page control is rendered. `numbers` is the default because it is the only mode whose rendered element count is independent of the page count; `select` materializes one entry per page, so above a safety cap the component falls back to `compact` on its own.
-- **`siblingCount`** `number` (default: `1`) — Page buttons either side of the current page.
-- **`boundaryCount`** `number` (default: `1`) — Page buttons pinned at each end. Together with `siblingCount` this bounds the rendered count at `boundaryCount * 2 + siblingCount * 2 + 3`.
+- **`defaultPageSize`** `number` (default: `50`) — Initial page size for
+  uncontrolled usage.
+- **`onPageSizeChange`** `(pageSize: number) => void` — Changing the size also
+  resets to page 1, because the old page index no longer refers to the same
+  items.
+- **`pageSizeOptions`** `number[]` — Supplying this **and** `onPageSizeChange`
+  renders the size selector.
+- **`type`** `'numbers' | 'select' | 'compact'` (default: `'numbers'`) — How the
+  page control is rendered. `numbers` is the default because it is the only mode
+  whose rendered element count is independent of the page count; `select`
+  materializes one entry per page, so above a safety cap the component falls
+  back to `compact` on its own.
+- **`siblingCount`** `number` (default: `1`) — Page buttons either side of the
+  current page.
+- **`boundaryCount`** `number` (default: `1`) — Page buttons pinned at each end.
+  Together with `siblingCount` this bounds the rendered count at
+  `boundaryCount * 2 + siblingCount * 2 + 3`.
 - **`size`** `'small' | 'medium'` (default: `'small'`) — Control size.
 - **`isDisabled`** `boolean` — Disable every control.
-- **`hasNextPage`** `boolean` — Keeps "next" enabled when the total is unknown. Ignored once `total` or `totalPages` is supplied — a known total is always authoritative.
-- **`isCompact`** `boolean` (default: `false`) — Hide the first/last jump buttons.
-- **`summary`** `boolean | ((info: CubeTablePageInfo) => ReactNode)` (default: `false`) — `true` renders the localized `1–50 of 1,204`, with numbers formatted for the active locale. Pass a function for full control.
-- **`labelFormatter`** `(info: CubeTablePageInfo) => ReactNode` — Labels the entries of `type="select"`. Receives the page info with `page` set to the entry being labelled.
-- **`ariaLabel`** `string` — Labels the `<nav>` landmark. Defaults to the localized "Pagination".
+- **`hasNextPage`** `boolean` — Keeps "next" enabled when the total is unknown.
+  Ignored once `total` or `totalPages` is supplied — a known total is always
+  authoritative.
+- **`isCompact`** `boolean` (default: `false`) — Hide the first/last jump
+  buttons.
+- **`summary`** `boolean | ((info: CubeTablePageInfo) => ReactNode)` (default:
+  `false`) — `true` renders the localized `1–50 of 1,204`, with numbers
+  formatted for the active locale. Pass a function for full control.
+- **`labelFormatter`** `(info: CubeTablePageInfo) => ReactNode` — Labels the
+  entries of `type="select"`. Receives the page info with `page` set to the
+  entry being labelled.
+- **`ariaLabel`** `string` — Labels the `<nav>` landmark. Defaults to the
+  localized "Pagination".
 
 #### `CubeTablePageInfo`
 
@@ -81,9 +112,9 @@ These properties allow direct style application without using the `styles` prop:
 
 ### Modifiers
 
-| Modifier | Type                  | Description  |
-| -------- | --------------------- | ------------ |
-| `size`   | `'small' \| 'medium'` | Control size |
+| Modifier | Type | Description |
+| -------- | ---- | ----------- |
+| `size` | `'small' \| 'medium'` | Control size |
 
 ## Examples
 
@@ -173,26 +204,34 @@ Every control is a real `<button>`, so there is nothing bespoke to learn.
 
 ### Screen Reader Support
 
-- The root is a `<nav>` landmark labelled "Pagination" (override with `ariaLabel`).
+- The root is a `<nav>` landmark labelled "Pagination" (override with
+  `ariaLabel`).
 - The current page button carries `aria-current="page"`.
-- Every button has an explicit `aria-label` — "Page 3", "Next page", and so on — so an icon-only button is never announced as unlabelled.
+- Every button has an explicit `aria-label` — "Page 3", "Next page", and so on
+  — so an icon-only button is never announced as unlabelled.
 - The `…` gap is `aria-hidden`; it conveys nothing a screen reader user needs.
 
 ### ARIA Properties
 
-| Property              | Applied to                   |
-| --------------------- | ---------------------------- |
-| `aria-label`          | The `<nav>` and every button |
-| `aria-current="page"` | The current page button      |
-| `aria-hidden="true"`  | The `…` gap                  |
+| Property | Applied to |
+| -------- | ---------- |
+| `aria-label` | The `<nav>` and every button |
+| `aria-current="page"` | The current page button |
+| `aria-hidden="true"` | The `…` gap |
 
 ## Best Practices
 
-- Do: pass `total` rather than `totalPages` when you know the item count — the summary and range labels both need it.
-- Do: use `type="numbers"` (the default) for anything that can grow. It is the only mode whose cost does not scale with the page count.
-- Do: reset to page 1 whenever the underlying query changes (a new search term, a new filter). A stale page index against a smaller result set shows an empty page.
-- Don't: render `type="select"` over a large page count. It builds one collection item per page.
-- Don't: pass both `hasNextPage` and a known total and expect the former to win — it doesn't.
+- Do: pass `total` rather than `totalPages` when you know the item count — the
+  summary and range labels both need it.
+- Do: use `type="numbers"` (the default) for anything that can grow. It is the
+  only mode whose cost does not scale with the page count.
+- Do: reset to page 1 whenever the underlying query changes (a new search term,
+  a new filter). A stale page index against a smaller result set shows an empty
+  page.
+- Don't: render `type="select"` over a large page count. It builds one
+  collection item per page.
+- Don't: pass both `hasNextPage` and a known total and expect the former to win
+  — it doesn't.
 
 ## Suggested Improvements
 

package/docs/components/navigation/Tabs.md

@@ -142,7 +142,9 @@ DOM order is always "bar then panels" — visual order is controlled internally
 
 #### Vertical tabs across types
 
-`narrow` only makes sense for a horizontal strip (it collapses horizontal label padding for a denser row). When `placement` is `'left'` or `'right'`, `type="narrow"` is coerced to `type="default"`.
+`narrow` only makes sense for a horizontal strip (it collapses horizontal
+label padding for a denser row). When `placement` is `'left'` or `'right'`,
+`type="narrow"` is coerced to `type="default"`.
 
 ## Compound Components
 
@@ -742,7 +744,9 @@ Override per-tab/panel:
 
 ### Optimized Lazy Rendering with `renderPanel`
 
-For tabs with expensive content, use the `renderPanel` prop for optimized lazy rendering. This prevents content from being evaluated on every parent render - only the active tab's content is computed, while inactive tabs use cached content.
+For tabs with expensive content, use the `renderPanel` prop for optimized lazy rendering.
+This prevents content from being evaluated on every parent render - only the active tab's
+content is computed, while inactive tabs use cached content.
 
 ```jsx
 <Tabs
@@ -829,7 +833,15 @@ Tabs work seamlessly inside Layout components. When placed in a `Layout` or `Lay
 
 ### Inside a Board (spring-loaded switching)
 
-When `Tabs` is rendered inside a [`Board`](../layout/Board.md), tab switching becomes spring-loaded automatically: while a Board widget is being dragged, hovering a tab header for a moment opens that tab, so a widget can be dropped into it or moved between tabs. This requires no configuration - `Tabs` detects the active Board drag and, for its duration, keeps panels mounted so the tab a widget is dragged out of (and the board owning the in-flight gesture) is not unmounted mid-drag. Spring-loading works with mouse and pen; touch drags capture the pointer and do not trigger it. Outside a `Board` this behavior is inert.
+When `Tabs` is rendered inside a [`Board`](../layout/Board.md), tab
+switching becomes spring-loaded automatically: while a Board widget is being
+dragged, hovering a tab header for a moment opens that tab, so a widget can be
+dropped into it or moved between tabs. This requires no configuration - `Tabs`
+detects the active Board drag and, for its duration, keeps panels mounted so the
+tab a widget is dragged out of (and the board owning the in-flight gesture) is
+not unmounted mid-drag. Spring-loading works with mouse and pen; touch drags
+capture the pointer and do not trigger it. Outside a `Board` this behavior is
+inert.
 
 ## Accessibility