@cube-dev/ui-kit 0.0.0-canary-c325dcb → 0.0.0-canary-162cdb3

package/docs/components/layout/Board.md

@@ -1,473 +0,0 @@
-# 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.
-
-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
-
-- Customizable dashboards where users arrange widgets
-- Report/analytics layouts with resizable tiles
-- Multi-panel workspaces where items move between areas
-- Nested containers whose children can be dragged out
-
-## Component
-
----
-
-## Concepts
-
-- **Layout** — an array of items in grid units. `i` matches a `Board.Widget` `id`; a widget whose `id` has no layout item is not rendered at all. Beyond `{ i, x, y, w, h }` an item may carry `minW`/`maxW`/`minH`/`maxH`, `constraints`, `resizeHandles`, `isDraggable`, `isResizable` and `static` — all of which outrank the same options declared on `Board.Widget` (see [How props interact](#how-props-interact)). `static` pins an item: it cannot be dragged, resized or swapped, and compaction flows around it.
-- **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`, `free`, or `null`. 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. `allowOverlap` also switches compaction off in the reflowing modes — see [How props interact](#how-props-interact).
-- **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.
-
-## How props interact
-
-Several props override, gate, or switch each other off. This is the full set of those relations.
-
-### Grid sizing
-
-| Props | Relation |
-| --- | --- |
-| `rows` + `extraRows` | `rows` wins outright. A fixed matrix renders exactly `rows` rows, so `extraRows` — which only pads a board that hugs its content — has no effect. |
-| `rows` + `maxRows` | `rows` implies a `maxRows` of the same value, but an explicit `maxRows` still wins over that implication. |
-| `rowHeight="stretch"` | Requires `rows`, and a measured height. Without either the board falls back to the default `100`px row rather than collapsing. |
-| `width` | Disables width measurement. An `isAligned` board derives its column count from the measured width, so pass a real value if you use both. |
-| `extraRows` + `maxRows` | `extraRows` is clamped by `maxRows`. |
-| `margin` | The grid gap, not a CSS margin — `Board` deliberately drops `margin` from its style props. `Board.Widget` still accepts it as an ordinary style prop. |
-
-### Collision and compaction
-
-Three props decide what happens when a widget lands on an occupied cell, and they are resolved in this order:
-
-1. **`allowOverlap` wins outright.** It replaces the compactor with a no-op, so `compact="vertical"` / `"horizontal"` **stop reflowing** as well: widgets stay where they are put and may stack. `preventCollision` and `collisionMode` are both dead while it is on, because nothing is ever refused.
-2. **`compact="free"` ignores the `preventCollision` prop entirely.** Free mode derives blocking from `allowOverlap` instead — `free` without `allowOverlap` always blocks, `free` with it always stacks. `preventCollision` only reaches `'vertical'`, `'horizontal'` and `null`.
-3. **`collisionMode` is consulted only where a collision would otherwise refuse the move** — `compact="free"` without `allowOverlap`, or an explicit `preventCollision` on one of the other modes. On a compacting board it does nothing, because there a collision pushes neighbours rather than blocking.
-
-`'swap'` never trades with an item marked `static`, and falls back to `'downscale'`, then `'revert'`, when no exchange fits. A resize is blocked by a collision in exactly the modes above; on a compacting board a resize pushes its neighbours the way a drag does.
-
-### `constraints` replaces the defaults
-
-`constraints` on `Board` is a **replacement**, not an addition. The default is `[gridBounds, minMaxSize]`, so passing your own array turns off grid-bounds clamping _and_ min/max enforcement — `minW`/`maxW`/`minH`/`maxH` (on the layout item, on `Board.Widget`, or in `widgetProps`) stop being applied. Re-include the built-ins to keep them:
-
-```jsx
-import { aspectRatio, Board, gridBounds, minMaxSize } from '@cube-dev/ui-kit';
-
-<Board constraints={[gridBounds, minMaxSize, aspectRatio(16 / 9)]} />;
-```
-
-Per-item and per-widget `constraints` work the other way round: they are applied **in addition** to the board's, and after them. Between those two sources, a layout item's `constraints` replace the widget's rather than adding to them.
-
-Built-ins exported alongside `Board`: `gridBounds`, `minMaxSize`, `containerBounds`, `boundedX`, `boundedY`, `aspectRatio`, `snapToGrid`, `minSize`, `maxSize`.
-
-### Per-widget overrides
-
-Two different shapes, and it matters which one a prop uses.
-
-**Booleans that can only take away.** The board's value is a ceiling:
-
-- **`isDraggable`** — a widget is draggable only when the board's `isDraggable` is `true` **and** neither `Board.Widget` nor `widgetProps` set it to `false` **and** the layout item's `isDraggable` is not `false` **and** the item is not `static`. `isDraggable={false}` on the board cannot be re-enabled per widget.
-- **`isResizable`** — the same chain.
-- **`isSelectable`** — only meaningful while `selectionMode` is not `'none'`; a widget can opt out, never opt in.
-
-**Values with a precedence chain.** The first source that sets it wins:
-
-| Prop | Precedence |
-| --- | --- |
-| `resizeHandles` | layout item → `Board.Widget` → `widgetProps` → `Board` |
-| `minW` / `maxW` / `minH` / `maxH` | layout item → `Board.Widget` → `widgetProps` |
-| `constraints` | layout item → `Board.Widget` → `widgetProps`, then _added_ to the board's |
-| `resizeGripPlacement`, `dragCancel`, `dragHandle`, `selectionCancel` | `Board.Widget` → `widgetProps` → `Board` |
-| `isCard`, `hoverRing`, `isAutoHeight`, `qa` | `Board.Widget` → `widgetProps` (no board-level prop) |
-| `styles`, `mods` | merged, not replaced: `widgetProps` underneath, `Board.Widget` on top, key by key |
-
-`resizeHandles` is the one case where the **layout item outranks `Board.Widget`**. Board's own modifiers always win over `mods`, so a custom modifier can never shadow `selected`, `drag` and the rest.
-
-### Drag guards
-
-`dragHandle` and `dragCancel` both apply — they are not alternatives. A press starts a drag only when it is inside `dragHandle` (if set) _and_ outside `dragCancel`. `dragCancel` already defaults to the interactive-descendant set, so widgets hosting controls need no configuration; pass `''` to let a drag start from anywhere. On a board with `selectionMode` on, `selectionCancel` acts as a third guard; on a board with `selectionMode="none"` it does nothing at all and `dragCancel` is the only guard. None of the three affects keyboard moves — those only run when the widget host itself is focused.
-
-`isAutoHeight` raises the widget's resize floor above `minH`: you cannot drag it shorter than the height its content currently needs.
-
-### Selection
-
-`selectionMode="none"` (the default) switches the whole feature off: `selectedKeys`, `defaultSelectedKeys`, `onSelectionChange`, `selectionCancel`, `allowMarqueeSelection`, `onWidgetsDelete`, and the selection key bindings (<kbd>Space</kbd>, <kbd>Escape</kbd>, <kbd>Delete</kbd>) all do nothing.
-
-| Props | Relation |
-| --- | --- |
-| `selectedKeys` + `defaultSelectedKeys` | `selectedKeys` wins. Keys with no matching layout item are ignored — no error, no flash — so removing a widget needs no selection cleanup. |
-| Controlled vs. uncontrolled | An uncontrolled board prunes keys of removed widgets and reports that through `onSelectionChange`; a controlled board does not, since you own the state. |
-| `allowMarqueeSelection` | Requires `selectionMode="multiple"`. Setting it `true` under `'single'` does nothing. |
-| `selectionMode="single"` | Any multi-key selection collapses to the first key in layout order. |
-| `onWidgetsDelete` | <kbd>Delete</kbd>/<kbd>Backspace</kbd> are only handled when this is set. Board never removes widgets itself. |
-| `extraRows` | Effectively required for the marquee on a board that hugs its content: with no spare rows there is no empty canvas to lasso from. |
-
-### Nested boards
-
-`isAligned` only takes effect inside another `Board`'s widget; on a top-level board it is ignored. Where it does take effect it overrides the board's own grid metrics:
-
-| Prop | Under `isAligned` |
-| --- | --- |
-| `rowHeight` | Ignored — the parent's row height is used verbatim, `'stretch'` included. |
-| `margin` | Ignored — the parent's gap is inherited so widget edges line up. |
-| `cols` | Ignored once the board has been measured; the column count is derived from the measured width at the parent's column pitch. Serves only as the pre-measurement fallback. |
-| `containerPadding` | Defaults to `[0, 0]` instead of `margin`, so the grid origin sits flush. An explicit value still wins. |
-
-An aligned board never shrinks its rows, so pair it with `isAutoHeight` on the container `Board.Widget` or its content is clipped.
-
-`showGridLines` is inherited by a nested board that does not set it, but only in drag-scoped form: an ancestor's `true` reaches descendants as `'drag'` (lines during a drag, not permanently), while `'any-drag'` is inherited verbatim. An explicit `false` opts out of the inheritance; omitting it does not.
-
-`isDroppable={false}` only refuses widgets arriving from _other_ boards; dragging within the board still works.
-
-## Properties
-
-### Board
-
-- **`id`** `string` — Stable board id, used for cross-board drag and exposed as `data-board-id`. Auto-generated when omitted; set it when you need to address a specific board (tests, `onWidgetTransfer` bookkeeping).
-- **`layout`** `LayoutItem[]` — Controlled layout. Wins over `defaultLayout`, and re-seeds the board only when the array reference changes: mutating it in place does nothing, and a gesture previews and commits locally regardless, so pass a new array back from `onLayoutChange` to stay authoritative.
-- **`defaultLayout`** `LayoutItem[]` — Initial layout for uncontrolled usage. Ignored when `layout` is set.
-- **`onLayoutChange`** `(layout: LayoutItem[], info: { reason }) => void` — Called when the layout is committed. `reason` is `'drag'`, `'resize'`, `'transfer'` (a widget arrived from or left for another board) or `'normalize'` (no gesture — a reflow for a changed column count, or an auto-height widget growing). See [Knowing why the layout changed](#knowing-why-the-layout-changed).
-- **`onDragStart` / `onDrag` / `onDragStop`** `(info: BoardInteractionInfo) => void` — Drag lifecycle callbacks. `onDrag` fires on every step; `onDragStop` fires after the layout is committed.
-- **`onResizeStart` / `onResize` / `onResizeStop`** `(info: BoardInteractionInfo) => void` — Resize lifecycle callbacks, mirroring the drag ones.
-- **`cols`** `number` (default: `12`) — Number of columns. On an `isAligned` nested board this is only the pre-measurement fallback — the real count is derived from the measured width.
-- **`rows`** `number` — Render exactly this many rows, whatever the content needs — a fixed `cols × rows` matrix rather than a grid that hugs its widgets. Implies a `maxRows` of the same value (an explicit `maxRows` still wins), so `gridBounds` keeps every drag and resize inside the matrix without a per-widget `maxH`. Overrides `extraRows`, which only pads a content-hugging board.
-- **`rowHeight`** `number | 'stretch'` (default: `100`) — Row height in pixels, or `'stretch'` to divide the board's own measured height into its rows. `'stretch'` is what makes a fixed `rows × cols` matrix fill the box it is given: the board takes its parent's height and each cell an equal share of it, so resizing the container resizes the cells instead of adding or removing them. Requires `rows`: without a declared row count there is no matrix to fill, and dividing by the content extent instead would resize every cell whenever a widget landed on a new row. Unset, or before the parent's height is known, the board keeps its ordinary content-hugging behaviour at the default row height rather than collapsing. Ignored entirely on an `isAligned` nested board, which uses the parent's row height.
-- **`margin`** `[number, number]` (default: `[8, 8]`) — Horizontal/vertical gap between widgets. This is the grid gap, not a CSS margin: `Board` does not accept `margin` as a style prop. Ignored on an `isAligned` nested board, which inherits the parent's gap.
-- **`containerPadding`** `[number, number]` — Inner padding. Defaults to `margin`, or to `[0, 0]` for an aligned nested board (`isAligned`) so its grid lines up with the ancestor board's.
-- **`maxRows`** `number` (default: `Infinity`) — Maximum number of rows. Defaults to `rows` when that is set; an explicit value overrides that.
-- **`extraRows`** `number` (default: `0`) — Empty grid rows kept below the content. The board renders this many rows taller than its widgets need, so there is always somewhere to start a marquee and somewhere to drop a widget past the end. A board hugs its content by default, so on a full grid it has neither. Clamped by `maxRows`, and ignored entirely when `rows` fixes the matrix.
-- **`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). It also **switches compaction off**: with it on, `compact="vertical"`/`"horizontal"` no longer reflow, and `preventCollision`/`collisionMode` have no effect at all, since nothing is ever refused. In `'free'` mode it is what distinguishes stacking from blocking a drop onto an occupied cell.
-- **`preventCollision`** `boolean` (default: `false`) — Block movement into occupied cells instead of pushing. Applies to `'vertical'`, `'horizontal'` and `null` only: `compact="free"` derives blocking from `allowOverlap` and ignores this prop, and `allowOverlap` overrides it everywhere.
-- **`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), there is no slot on the destination to give back, so `'swap'` resolves as `'downscale'`: the incoming widget keeps its size when possible or downscales into the available room to its right and below, and existing destination widgets are never exchanged. A release over an occupied anchor commits whatever the preview was showing rather than cancelling the transfer: the widget holds the last cell it fitted in as you sweep across a destination widget, and enters at the nearest fitting cell when the very first cell it is offered is occupied. 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. A ceiling, not a default: `false` here cannot be re-enabled by a widget, and a `static` layout item is never draggable regardless.
-- **`isResizable`** `boolean` (default: `true`) — Enable resizing for all widgets. Same ceiling semantics as `isDraggable`.
-- **`isDroppable`** `boolean` (default: `true`) — Whether the board accepts widgets dropped from _other_ boards. `false` does not affect dragging within the board.
-- **`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' | 'outside'` — Where a widget's resize grips sit. Unset, **it resolves itself from the widget's content**: a widget holding a nested `Board` gets `'outside'`, and every other widget gets `'inside'`. Set it to override that, per board or per widget.
-
-  - `'inside'` tucks each grip into the widget box. The hit-zone is a band along the edge, inside the widget, so it sits over the widget's own content — which is fine for a leaf widget and is why a container resolves the other way.
-  - `'outside'` puts every grip in the grid gutter beyond the widget's edge, as a padded control of its own: a pill along each edge, and the same corner angle the other two placements draw, stepped off the corner into the square where two gutters cross. The control **is** the hit-zone — one element, so what you see is exactly what you can grab — and it never covers the widget's own content or a neighbour's.
-  - `'corner'` centres a corner grip on the widget's corner, straddling the edge, so it lines up with a control centred on the opposite corner (`cornerChrome`). Its hit-zone reaches half a grip inward, matching the half-dot painted there, and outward as far as half the gutter allows. Edge axes stay `'inside'`.
-
-  Whichever placement applies, grips are revealed on hover, focus or resize, and **only one widget's at a time**: the pointer is inside every ancestor at once, so a container stands down while the pointer is on one of its children. To resize a child you go inside it; to resize its container you go to the container's outer edge.
-
-  An `'outside'` grip needs gutter to sit in — at least 8px of `margin` on each axis. Below that it keeps its size and overhangs the neighbouring widgets, and the board warns in development; raise `margin`, or set `resizeGripPlacement` explicitly to put the grips back inside. The corner angle is the one exception: it shrinks to whatever the gutter leaves it rather than reaching past it onto the diagonal neighbour, and reaches its full size at 12px of `margin`.
-
-  Why the resolution exists: an inner board with no `containerPadding` — which `isAligned` sets — puts its last child's corner on exactly the same point as its host widget's. With both widgets drawing grips in the same place, the container's hit-zone covered the child's and the bottom-right child could not be resized at all. Sending the container's affordance outward and the child's inward leaves the two nothing in common, so nothing has to be arbitrated. Where they do still overlap — an explicit `'corner'` or `'inside'` on a container, or a gutter too thin — a press goes to the **innermost** handle under the pointer, and a container thereby left with no way to resize itself warns in development.
-
-- **`dragCancel`** `string` (default: `BOARD_SELECTION_CANCEL`) — CSS selector for elements that must not start a pointer drag. Defaults to the same set `selectionCancel` uses, because a control inside a widget has to keep its own press whether or not the board supports selection — a board hosting interactive content needs no configuration for buttons, inputs, links and the common ARIA widget roles to stay usable. Pass your own selector to narrow or widen it, or `''` to let a drag start from anywhere. Does not affect keyboard moves. Can be overridden per widget.
-- **`dragHandle`** `string` — CSS selector for the only elements from which a pointer drag may start. Combines with `dragCancel` rather than replacing it: a drag needs a target inside `dragHandle` _and_ outside `dragCancel`. 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 in drag-scoped form: an ancestor's `true` arrives as `'drag'` (a nested board shows lines during a drag, not permanently), while `'any-drag'` is inherited verbatim. An explicit `false` opts out of the inheritance.
-- **`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, which means it takes over three of the board's own metrics: `rowHeight` and `margin` are ignored in favour of the parent's, and `cols` is ignored once the board has been measured (the column count is derived from the measured width at the parent's column pitch, so cells stay parent-sized as the container is resized) — `cols` only serves as the pre-measurement fallback. It never shrinks rows to fit, so pair it with an `isAutoHeight` container so the widget grows to fit its rows at that height.
-
-  Widgets already on the board keep their cells. Narrowing the container lowers the column count, but a widget whose columns now fall outside it is **not** re-flowed into the narrower grid — it holds its position and is clipped by the container's edge, and widening the container brings it back exactly as it was. This is deliberate: resizing a container is not a request to rearrange the widgets inside it, and a layout that reshuffled on the way down could not be restored on the way back up.
-
-- **`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`); keys with no matching layout item are silently ignored. Requires `selectionMode` other than `'none'`.
-- **`defaultSelectedKeys`** `string[]` — Initial selection for uncontrolled usage. Ignored when `selectedKeys` is set. An uncontrolled board also prunes keys of removed widgets and reports that through `onSelectionChange`; a controlled board leaves that to you.
-- **`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. Only active while `selectionMode` is not `'none'`; on a non-selectable board `dragCancel` is the guard instead. 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 — and that holds however the control handles the press, including one that stops propagation or renders in a portal (a menu opened from a widget's toolbar). 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. Requires `selectionMode="multiple"` — setting it `true` under `'single'` or `'none'` does nothing. 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[]` (default: `[gridBounds, minMaxSize]`) — Grid layout constraints. **Replaces** the defaults rather than extending them, so a custom array turns off bounds clamping and `minW`/`maxW`/`minH`/`maxH` enforcement unless you re-include the built-ins. Per-item and per-widget `constraints` are additive on top of these. See [How props interact](#how-props-interact).
-- **`width`** `number` — Explicit width, which **disables the board's own measurement**. Only needed for SSR, tests, or a forced-size export — see [Sizing](#sizing); a board in the document measures itself and does not need this.
-- **`widgetProps`** `Partial<Board.Widget props>` — Default props applied to every widget this board hosts, excluding `id` and `children` (per-widget `Board.Widget` props override these; `styles` and `mods` are merged rather than replaced). Use it to add a card border to every widget (`widgetProps={{ isCard: true }}`) or set shared `styles`/sizing defaults without repeating them on each widget.
-- **`place`** `Styles['place']` — Style prop shorthand for `place-items`/`place-content`.
-- **`scrollMargin`** `Styles['scrollMargin']` — Style prop for scroll margin.
-
-### Board.Widget
-
-- **`id`** `string` (required) — Must match the `i` of a layout item. A widget whose `id` has no layout item is not rendered; `Board.Widget` itself renders nothing, it only registers content and options with the owning `Board`.
-- **`cornerChrome`** `ReactNode` — A control anchored to one corner of the widget and centred on it — a settings button, a badge, a remove affordance. Drawn in the same layer as the corner resize grips, which is the layer that escapes the widget's own clip: chrome hung off the corner from _inside_ a widget is cropped in half by that clip, or by an ancestor's scroll container when the widget sits in the first row. It is also outside the drag gesture, so a press on it can never start a drag and needs no `dragCancel` entry.
-- **`cornerChromePlacement`** `'ne' | 'nw' | 'se' | 'sw'` (default: `'ne'`) — Which corner the chrome sits on. Pair it with a `resizeGripPlacement="corner"` grip on the opposite corner and the two line up.
-- **`mods`** `Record<string, boolean | string | undefined>` — App-defined modifiers for this widget, merged into the ones the board sets, so a `styles` map can match on app state: `mods={{ editing: true }}` with `styles={{ shadow: { editing: '0 0 0 1bw #primary' } }}`. Board's own modifiers always win, so a custom one can never shadow `selected`, `drag` and the rest. Board-level `widgetProps.mods` merge underneath, so a shared default can be set once and overridden per widget — and every modifier rides along on the clone that floats during a drag.
-- **`hoverRing`** `boolean` (default: `true`) — Whether the widget shows the resting ring on hover — the affordance that says it can be picked up. Turn it off for a widget that is scenery rather than a thing to grab (a chromeless layout container, a spacer), where the ring advertises an interaction the widget does not really offer. Selection and drag treatments are unaffected. Can be set for the whole board via `widgetProps`.
-- **`isCard`** `boolean` (default: `false`) — Render this widget as a card by adding a border. Widgets are always filled (`#surface-2`) and rounded (`1cr`); `isCard` adds the border on top. Defaults to `false` (borderless) unless the owning `Board`'s `widgetProps.isCard` opts in; set it per widget to override that default.
-- **`isDraggable`** `boolean` — Disable dragging for this widget. Can only take away: it cannot re-enable dragging on a board with `isDraggable={false}`, nor on a `static` layout item.
-- **`isResizable`** `boolean` — Disable resizing for this widget. Same one-way semantics as `isDraggable`.
-- **`resizeHandles`** `ResizeHandleAxis[]` — Override the board's handles. Overridden in turn by the layout item's own `resizeHandles` — the one option where the layout item outranks `Board.Widget`.
-- **`resizeGripPlacement`** `'inside' | 'corner' | 'outside'` — Override where this widget's grips sit, instead of letting it resolve from the widget's content.
-- **`minW`** `number` — Minimum width in grid columns. Used when the layout item omits `minW`; the resize handle stops here.
-- **`maxW`** `number` — Maximum width in grid columns. Used when the layout item omits `maxW`.
-- **`minH`** `number` — Minimum height in grid rows. Used when the layout item omits `minH`.
-- **`maxH`** `number` — Maximum height in grid rows. Used when the layout item omits `maxH`.
-- **`constraints`** `LayoutConstraint[]` — Per-widget constraints, applied _in addition_ to the board's (unlike the board's own `constraints`, which replace the defaults). A layout item's `constraints` replace these.
-- **`qa`** `string` — Test id for the rendered widget element.
-- **`styles`** `Styles` — Style overrides for the rendered widget element.
-- **Style properties** — `Board.Widget` also accepts container style props directly (e.g. `fill`, `padding`, `radius`, `border`, `shadow`, `color`, `flow`, `gap`), just like `Board`. They are merged into `styles` (a direct prop wins over the same key in the `styles` object). Shared `widgetProps.styles` from the owning `Board` are merged underneath, so a per-widget style only overrides the matching keys instead of replacing the whole default.
-- **`isAutoHeight`** `boolean` (default: `false`) — Grow this widget's height in its board to fit its content (only ever increases, never shrinks). Pair it with a nested `Board isAligned` so the container expands until the inner board's rows fit at the parent's row height. It also pins the widget's resize floor above `minH`: you cannot drag the widget shorter than the height its content currently needs. A grow commits, so it fires the board's `onLayoutChange` with `reason: 'normalize'`.
-- **`dragCancel`** `string` — Override the board's `dragCancel` selector for this widget.
-- **`dragHandle`** `string` — Override the board's `dragHandle` selector for this widget.
-- **`isSelectable`** `boolean` — Disable selection for this widget while the board's `selectionMode` is on. Cannot opt a widget in on a board with `selectionMode="none"`.
-- **`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`.
-
-### 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.
-
-- **`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.
-
-### 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 every `Board` prop, with five of them re-shaped or taken over: `layout` and `defaultLayout` are replaced by `layouts`/`defaultLayouts`, `cols` becomes a per-breakpoint map, `onLayoutChange` gains a second argument, and `width` stays available but defaults to the wrapper's own measurement. `breakpoints` and `cols` are required; the rest:
-
-- **`breakpoints`** `Record<string, number>` — Breakpoint name to minimum container width (px).
-- **`cols`** `Record<string, number>` — Breakpoint name to column count.
-- **`layouts`** `Record<string, LayoutItem[]>` — Controlled per-breakpoint layouts.
-- **`defaultLayouts`** `Record<string, LayoutItem[]>` — Initial per-breakpoint layouts for uncontrolled usage.
-- **`onLayoutChange`** `(currentLayout: LayoutItem[], allLayouts: Record<string, LayoutItem[]>) => void` — Called on commit with the active breakpoint's layout and the full map.
-- **`onBreakpointChange`** `(breakpoint: string, cols: number) => void` — Called when the active breakpoint changes.
-- **`onWidthChange`** `(width: number, cols: number) => void` — Called when the measured container width changes, with the active breakpoint's column count. Mirrors react-grid-layout's `WidthProvider` `onWidthChange`. Not fired while width is unmeasured or when an explicit `width` is provided.
-- **`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.
-
-### 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.
-
-- **`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`.
-- **`card`** — the widget draws a card border (`isCard`).
-- **`no-hover-ring`** — the widget opted out of the resting hover ring (`hoverRing={false}`).
-- **`draggable`** — the widget can be dragged and no drag is in flight.
-- **`drag`** — the widget is being dragged.
-- **`floating`** — this is the clone floating in the drag overlay.
-- **`resizing`** — the widget is being resized.
-- **`static`** — the layout item is `static`.
-- **`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:
-
-```jsx
-<Board
-  selectionMode="multiple"
-  widgetProps={{
-    styles: {
-      border: { '': true, 'pre-selected': '#note-border', selected: '#note-border' },
-      shadow: { '': false, 'pre-selected': '0 0 0 1bw #note.40', selected: '0 0 0 1bw #note' },
-    },
-  }}
-/>
-```
-
-### Data attributes
-
-Supported hooks for tests, E2E, and building your own selection overlay:
-
-- **`data-board-id`** on the board element — the board's `id`.
-- **`data-board-widget-host`** on every widget host — presence only, "this is a widget host".
-- **`data-board-widget-id`** on every widget host — which widget.
-- **`data-selected`** on a selected host.
-- **`data-pre-selected`** on a host a live marquee currently covers.
-- **`data-marquee`** on the board element while a marquee gesture is in progress.
-
-### Base Properties
-
-Supports [Base properties](../../BaseProperties.md).
-
-### Style Properties
-
-These properties allow direct style application without using the `styles` prop:
-
-- **Base:** `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`
-- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `blockMargin`, `inlineMargin`, `inset`, `blockInset`, `inlineInset`, `position`, `scrollMargin`, `blockScrollMargin`, `inlineScrollMargin`, `scrollPadding`, `blockScrollPadding`, `inlineScrollPadding`
-- **Dimension:** `width`, `height`, `blockSize`, `inlineSize`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
-- **Block:** `border`, `blockBorder`, `inlineBorder`, `radius`, `shadow`, `outline`, `padding`, `blockPadding`, `inlinePadding`, `overflow`, `scrollbar`, `textAlign`
-- **Color:** `color`, `fill`, `fade`, `image`
-- **Flow:** `flow`, `place`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
-
-## Examples
-
-### Controlled layout
-
-### Fixed matrix
-
-`rows` with `rowHeight="stretch"` gives a board of a declared size that fills its container: a `cols × rows` matrix whose cells resize with the box rather than a grid that grows a row at a time. Pair it with `compact="free"` for a canvas the author places things on directly.
-
-### 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.
-
-### Free positioning (overlap)
-
-Add `allowOverlap` to let widgets stack on top of each other instead of being blocked from occupied cells.
-
-### Horizontal compaction
-
-### Non-resizable
-
-### Read-only
-
-`isDraggable={false}` together with `isResizable={false}` makes the whole board read-only. Because the board never installs its drag handlers, widget content stays fully interactive — text inside a widget can still be selected.
-
-### Single-axis resize
-
-Set a widget's `resizeHandles` to a single edge to constrain resizing to one axis: `['e']` for horizontal only, `['s']` for vertical only. Edge handles draw a dotted grip revealed on hover, focus, or while resizing.
-
-### Min/max widget size
-
-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.
-
-### Scoped grid lines
-
-Two boards under one `Board.Provider`. With `showGridLines="drag"` only the board taking part in the gesture lights up — the source, plus whichever board the widget is currently over. Switch to `'any-drag'` to light up both from the first pixel of any drag.
-
-### Corner chrome
-
-A control centred on a widget's corner with `cornerChrome`, drawn outside the widget's clip so nothing crops it. With a `resizeGripPlacement="corner"` grip on the opposite corner, the two line up.
-
-### 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.
-
-### Nested board grips
-
-Grip placement resolving itself across a nesting boundary, with no `resizeGripPlacement` set anywhere: the widget holding a `Board` draws its grips outside, in the gutter, and the leaf widgets keep theirs inside. Hover a child and only its grips appear; hover the container's outer edge and only the container's do.
-
-### 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 downscales into an empty cell without exchanging destination widgets, and an occupied anchor commits the previewed cell instead of cancelling. 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.
-
-### Drag cancel
-
-Keep interactive controls inside a widget clickable by excluding them from the drag gesture with `dragCancel`.
-
-### Responsive
-
-`Board.Responsive` swaps the layout and column count per breakpoint.
-
-### Cross-board dragging
-
-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.
-
-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.
-
-### 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.
-
-### 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.
-
-`Tabs` learns about the drag from a context this package owns, which a `Board` implementation living **outside** this package cannot reach — so both behaviours above would silently be missing there. Publish the drag state with `BoardDragActiveProvider` instead, wrapping the subtree your board renders at the same level as your drag registry:
-
-```jsx
-import { BoardDragActiveProvider } from '@cube-dev/ui-kit';
-
-<BoardDragActiveProvider isActive={dragState != null}>{children}</BoardDragActiveProvider>;
-```
-
-You never need it alongside this package's `Board`, which provides it for you.
-
-### 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.
-
-### Interactive content keeps its clicks
-
-### Controlled selection and deleting widgets
-
-### Knowing why the layout changed
-
-`onLayoutChange` reports a `reason` alongside the layout, because a board commits for two different kinds of reason and an app usually needs to tell them apart. `'drag'`, `'resize'` and `'transfer'` are the user arranging their board. `'normalize'` is the board fitting an existing arrangement to a constraint that moved underneath it — the column count changed, or an `isAutoHeight` widget grew to fit its content.
-
-An app that persists every commit without looking writes those normalizations back as if they were edits, which marks a document dirty that nobody touched and can overwrite saved positions with ones the board derived. Persist the gestures and let a normalization pass:
-
-```jsx
-<Board
-  onLayoutChange={(layout, { reason }) => {
-    if (reason === 'normalize') return;
-    save(layout);
-  }}
-/>
-```
-
-### Restyling the selection
-
-## Sizing
-
-**A board measures its own container. You do not need to measure it for it.**
-
-It observes its container with a `ResizeObserver` and derives the column width from that, so the only reason to pass `width` is to _prevent_ measurement — SSR, a test, or an export forced to a fixed size.
-
-The part worth knowing, because it is what makes hand-measuring look necessary: **a board renders no widgets at all until it has a width.** At width 0 a column works out negative (`(0 - margin × (cols - 1) - containerPadding × 2) / cols`), so painting then would put every widget at a nonsense size for a frame. Instead the board renders its own box and nothing inside it, and the widgets appear on the first measured frame. A board briefly hidden (an inactive tab, say) keeps its last non-zero measurement rather than dropping back to zero, so its widgets stay mounted — which is what keeps an in-flight drag alive.
-
-So a consumer that mirrors this — measuring the box itself, feeding the result back in as `width`, and gating its own render on `measured > 0` — is reimplementing behaviour it already has, and pays a `ResizeObserver` and an extra DOM node for it.
-
-## Accessibility
-
-### Keyboard Navigation
-
-| Key | Action |
-| --- | --- |
-| <kbd>Tab</kbd> | Move focus to the next widget. |
-| <kbd>Arrow</kbd> keys | Move the focused widget to the next valid cell in that direction — usually one cell, but it scans further when the adjacent cell cannot produce a valid move. With a selection, moves the whole selection. Honours `collisionMode`, but never resizes anything. |
-| <kbd>Space</kbd> | Toggle the focused widget's selection (`selectionMode` only). |
-| <kbd>Shift</kbd> / <kbd>Cmd</kbd> / <kbd>Ctrl</kbd> + press | Add or remove a widget from the selection. |
-| <kbd>Escape</kbd> | Clear the selection. Only consumed when something is selected. |
-| <kbd>Delete</kbd> / <kbd>Backspace</kbd> | Request deletion of the selection via `onWidgetsDelete`. Only consumed when that handler is set and the selection is non-empty. |
-
-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.
-
-### 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"`.
-
-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.
-
-## 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.
-- **<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.
-
-## Layout helpers
-
-Placement questions the board answers for itself during a gesture, exported so an app can ask them for a widget it adds programmatically. Without these, an app re-implements the scan, and the same drop lands in two different cells depending on whether a pointer or a code path served it.
-
-- **`placeInFreeSlot(others, item, cols, maxRows?)`** — the first position at or below the item's preferred cell where it fits without overlapping `others`, scanning the preferred row first, then down, then up. Never past `maxRows`, and never resizes to fit (only `w` is capped to `cols`). This is the rule the board itself applies when a dragged widget cannot stay where it was dropped.
-- **`distributeEvenly(layout, { cols, rows })`** — tile every item evenly across both axes, keeping the row structure the layout already has: items are grouped into visual rows by their current `y`, `rows` is divided across the groups and `cols` across each group's members. A line holding more items than the grid is wide wraps into sub-rows. This is the one operation that deliberately _grows_ items — every gesture-driven path refuses to, which is why it is a call the app makes rather than a mode the board is in.
-
-## 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`.