@cube-dev/ui-kit 0.164.0 → 0.166.0

package/docs/components/data/DataTable.md

@@ -30,9 +30,9 @@ API keys. That is the one with selection, bulk actions, row menus and row links.
 ## It knows nothing about Cube
 
 Measures, dimensions, pivots, drill-downs and calculated fields never reach this
-component as concepts. They arrive as ordinary columns, `render` output and
-`column.header.menu` content — which is what keeps Cloud's column-header menu,
-and everything it knows about the query, in Cloud.
+component as query concepts. They arrive as leaf columns, presentational column
+groups, `render` output and `column.header.menu` content — which is what keeps
+Cloud's column-header menu, and everything it knows about the query, in Cloud.
 
 ## Component
 
@@ -41,9 +41,19 @@ and everything it knows about the query, in Cloud.
 #### Data
 
 - **`data`** `readonly T[]` — The rows.
-- **`columns`** `CubeDataTableColumn<T>[]` — Same shape as `ItemTable`'s, plus `dataType`.
+- **`columns`** `CubeDataTableColumnDefinition<T>[]` — Leaf columns use the same
+  shape as `ItemTable`'s, plus `dataType`; group nodes contain nested `children`.
 - **`rowKey`** `string` (default: `'id'`) — Property to read the row identity from.
 - **`getRowKey`** `(row: T, index: number) => Key` — Wins over `rowKey`.
+- **`getRowChildren`** `(row: T) => readonly T[] | undefined` — Enables nested
+  treegrid rows; `data` contains roots.
+- **`treeColumnKey`** `string` — Indented disclosure column. Defaults to the
+  first visible data column.
+- **`expandedKeys`** `Key[]` — Controlled expansion.
+- **`defaultExpandedKeys`** `Key[]` — Initial expansion. Nothing is expanded by
+  default.
+- **`onExpand`** `(keys, info) => void` — Reports the resulting keys and toggled
+  row metadata.
 - **`pinnedTopRows`** `readonly T[]` — Rows stuck to the top of the scroller. Ordinary rows as far as the columns are concerned.
 - **`pinnedBottomRows`** `readonly T[]` — The same, at the bottom. This is where totals go.
 
@@ -63,10 +73,13 @@ and everything it knows about the query, in Cloud.
 - **`size`** `SizeName` (default: `'small'`) — An analytical grid packs more rows than a list.
 - **`rowSize`** `'small' | 'medium' | 'large'` — Row height as a named step: 28px / 32px / 40px. Rows only; the header keeps answering to `size`. Unset, the height comes from `size`.
 - **`rowHeight`** `number` — An exact height, when none of the named steps is the answer. Wins over both `rowSize` and `size`.
-- **`headerHeight`** `number`
+- **`headerHeight`** `number` — Exact height of each header row in px.
 - **`isStriped`** `boolean` (default: `true`) — Banding is what makes a wide row readable across.
 - **`isHeaderHidden`** `boolean`
 - **`isHeaderSticky`** `boolean` (default: `true`)
+- **`isAutoHeight`** `boolean` (default: `false`) — Shrink-wraps the frame to
+  the rendered rows instead of filling its flex pane. It takes precedence over
+  root height/flex sizing and disables virtualization.
 - **`isRowMoveAnimated`** `boolean` (default: `true`) — Slide rows to their new positions when the order changes, instead of teleporting them. Respects `prefers-reduced-motion`.
 - **`showRowNumbers`** `boolean` (default: `false`) — A continuous count down the side, which stays continuous across pages.
 
@@ -127,7 +140,7 @@ see [Column Colors](#column-colors) for the last two.
 
 #### Virtualization
 
-- **`isVirtualized`** `boolean | 'auto'` (default: `'auto'`) — On when the grid is height-bounded and has more rows than the threshold.
+- **`isVirtualized`** `boolean | 'auto'` (default: `'auto'`) — On when the grid is height-bounded and has more rows than the threshold. Ignored when `isAutoHeight` is enabled.
 - **`virtualizeThreshold`** `number`
 - **`overscan`** `number`
 
@@ -136,6 +149,9 @@ see [Column Colors](#column-colors) for the last two.
 - **`getRowProps`** `(ctx: CubeTableRowContext<T>) => Record<string, any>` — Per-row mods, styles and height.
 - **`storageKey`** `string` — Persists page size, column widths and column order.
 - **`ariaLabel`** `string`
+- **`isChecked`** `boolean` — Base checked-state modifier.
+- **`place`** `string` — Tasty placement shorthand on the root frame.
+- **`scrollMargin`** `string | number` — Scroll margin on the root frame.
 
 #### `dataType`
 
@@ -159,9 +175,10 @@ Customizes the root frame. Every internal part of the grid is a **sub-element**
 reachable from this one prop — the same contract, and the same sub-element
 names, as ItemTable.
 
-`DataTable` adds one: `StateCell`, the full-span cell that carries the empty,
-no-results and error content. It is deliberately not a `Cell`, so it takes none
-of the row's banding or hover paint.
+`DataTable` adds `StateCell`, the full-span cell that carries the empty,
+no-results and error content, and `HeaderGroupCell`, a spanning cell in a
+multi-row header. `StateCell` is deliberately not a `Cell`, so it takes none of
+the row's banding or hover paint.
 
 #### Targeted slots
 
@@ -204,6 +221,72 @@ body into a scroller, pins the header, and lets virtualization engage at all.
 Cell-level, in addition to `ItemTable`'s: `cell-selected`, `last-column`,
 `pinned`.
 
+## Pivoted Results and Column Groups
+
+Pass group nodes in `columns` to render real multi-row headers. Groups may nest
+to any depth; their `children` eventually resolve to ordinary leaf columns, and
+only those leaves participate in sorting, resizing, ranges and copying.
+
+```jsx
+const columns = [
+  { key: 'region', title: 'Region', pin: 'start' },
+  {
+    key: 'organic',
+    title: 'Organic',
+    children: [
+      { key: 'organic_orders', title: 'Orders', dataType: 'number' },
+      { key: 'organic_revenue', title: 'Revenue', dataType: 'number' },
+    ],
+  },
+  {
+    key: 'paid',
+    title: 'Paid',
+    children: [
+      { key: 'paid_orders', title: 'Orders', dataType: 'number' },
+      { key: 'paid_revenue', title: 'Revenue', dataType: 'number' },
+    ],
+  },
+];
+
+<DataTable data={pivotRows} columns={columns} isAutoHeight />;
+```
+
+The data/query layer still owns the pivot calculation. DataTable only renders
+the already-shaped rows and generated column hierarchy. Leaf resizing and
+sorting remain available; drag column reordering is ignored while groups are
+present because moving one leaf cannot preserve an arbitrary hierarchy.
+
+## Tree Rows
+
+Tree mode uses the same nested-data contract as `ItemTable`:
+
+```jsx
+<DataTable
+  data={regions}
+  columns={columns}
+  getRowChildren={(row) => row.children}
+  treeColumnKey="region"
+  defaultExpandedKeys={['americas']}
+/>
+```
+
+Multi-sort is recursive: every sibling collection is sorted by the same
+precedence. Client pagination slices roots and keeps complete subtrees together;
+server pages are rendered exactly as supplied and `total` counts roots. Pinned
+rows remain ordinary non-hierarchical totals.
+
+Only visible descendants participate in cell ranges and virtualization.
+Collapsing a range endpoint makes the effective range inactive; a controlled or
+uncontrolled range is restored when that endpoint becomes visible again. Client
+row numbers remain continuous across root pages, while server tree pages restart
+at 1 because preceding descendant counts are unknown.
+
+The native table exposes `role="treegrid"`, `aria-level`, `aria-expanded`,
+`aria-posinset` and `aria-setsize`. Right/Left expand, collapse or move to the
+parent; Up/Down traverse visible rows, and typeahead reads `treeColumnKey`.
+Customize the hierarchy chrome with `styles.TreeContent`, `styles.TreeToggle`
+and `styles.TreeValue`.
+
 ## Examples
 
 ### Multi-Column Sorting
@@ -241,6 +324,20 @@ competing for a position.
 Above `virtualizeThreshold` a bounded grid virtualizes on its own, so
 `paginationMode="off"` is a reasonable default for a result the user scrolls.
 
+For a compact result that should participate in normal page flow, set
+`isAutoHeight`. The frame then ends at the last rendered row rather than filling
+its flex pane. This renders the complete result and disables virtualization, so
+keep larger results bounded instead.
+
+```jsx
+<DataTable
+  data={summaryRows}
+  columns={columns}
+  paginationMode="off"
+  isAutoHeight
+/>
+```
+
 ### Sorting Moves Rows
 
 When a sort reorders rows, they slide to their new positions over 120ms rather
@@ -401,8 +498,10 @@ elsewhere.
 ## Accessibility
 
 The table is a `role="grid"` with document-absolute `aria-rowindex` /
-`aria-colindex`, and `aria-rowcount` counts pinned rows. Every sorted column
-carries `aria-sort`, not just the first.
+`aria-colindex`, and `aria-rowcount` counts pinned rows and every visible header
+row. Group cells use native `scope="colgroup"` / `colSpan`; ungrouped leaf
+headers span the remaining rows. Every sorted leaf column carries `aria-sort`,
+not just the first.
 
 A header cell takes a tab stop when it is interactive — sortable, carrying a
 menu, or reorderable. `Shift`+`F10` opens the column menu from the keyboard, and

package/docs/components/data/ItemTable.md

@@ -31,6 +31,14 @@ pivots, totals. Use `ListBox` when there is only one column.
 - **`columns`** `CubeItemTableColumn<T>[]` — Column definitions. See below.
 - **`rowKey`** `string` (default: `'id'`) — Property used as the row key.
 - **`getRowKey`** `(row: T, index: number) => Key` — Wins over `rowKey`.
+- **`getRowChildren`** `(row: T) => readonly T[] | undefined` — Enables tree
+  mode. `data` then contains top-level rows and children are read recursively.
+- **`treeColumnKey`** `string` — Column containing indentation and the
+  disclosure control. Defaults to the first visible data column.
+- **`expandedKeys`** `Key[]` — Controlled expanded rows.
+- **`defaultExpandedKeys`** `Key[]` — Initially expanded rows. Defaults to none.
+- **`onExpand`** `(keys, info) => void` — Reports the complete expanded-key list
+  and the toggled row, key, zero-based level, parent key and resulting state.
 - **`isLoading`** `boolean` (default: `false`) — Marks a fetch in flight. What
   the user sees depends on `loadingIndicator`.
 - **`loadingIndicator`** `'overlay' | 'skeleton' | 'none'` (default: `'overlay'`)
@@ -65,6 +73,9 @@ pivots, totals. Use `ListBox` when there is only one column.
   row and drops it from `aria-rowcount`.
 - **`isHeaderSticky`** `boolean` (default: `true`) — Pins the column header
   while the body scrolls.
+- **`isAutoHeight`** `boolean` (default: `false`) — Shrink-wraps the frame to
+  the rendered rows instead of filling its flex pane. It takes precedence over
+  root height/flex sizing and disables virtualization.
 - **`sortMode`** `'client' | 'server' | 'off'` (default: `'client'` when any
   column is sortable, else `'off'`) — `client` reorders `data` itself; `server`
   only reflects `sort` and fires `onSortChange`; `off` removes the affordance.
@@ -96,7 +107,8 @@ pivots, totals. Use `ListBox` when there is only one column.
   toolbar.
 - **`isVirtualized`** `boolean | 'auto'` (default: `'auto'`) — `'auto'` turns
   virtualization on once the row count passes `virtualizeThreshold`. It needs a
-  bounded height to have a viewport to work against.
+  bounded height to have a viewport to work against and is ignored when
+  `isAutoHeight` is enabled.
 - **`virtualizeThreshold`** `number` (default: `50`) — Row count above which
   `'auto'` virtualizes.
 - **`overscan`** `number` (default: `12`) — Rows mounted beyond each viewport
@@ -117,6 +129,10 @@ pivots, totals. Use `ListBox` when there is only one column.
 - **`selectionTooltip`** `string | ((row: T) => string | undefined)` — Explains
   an inert checkbox.
 - **`disabledKeys`** `Key[]` — Rows that cannot be interacted with at all.
+- **`treeSelectionBehavior`** `'cascade' | 'independent'` (default: `'cascade'`
+  in tree mode) — Multiple selection only. Cascade selects eligible descendants
+  and derives checked or indeterminate ancestors; single selection is always
+  independent.
 - **`rowLink`** `(row: T, index: number) => NavigateArg | undefined` — Turns the
   row-header cell into a stretched link covering the whole row. Return
   `undefined` for a row that should not navigate.
@@ -207,6 +223,9 @@ pivots, totals. Use `ListBox` when there is only one column.
 - **`getRowProps`** `(ctx) => { isDimmed?, mods?, styles?, height?, qa?, tooltip? }`
   — Per-row visuals.
 - **`ariaLabel`** `string` — Labels the grid.
+- **`isChecked`** `boolean` — Base checked-state modifier.
+- **`place`** `string` — Tasty placement shorthand on the root frame.
+- **`scrollMargin`** `string | number` — Scroll margin on the root frame.
 
 #### `CubeItemTableColumn<T>`
 
@@ -291,6 +310,8 @@ reachable from this one prop — that is the whole styling contract.
 - `Table` — the `<table>`
 - `Head`, `HeadRow`, `HeaderCell` — the column header
 - `Body`, `Row`, `Cell` — the data rows
+- `TreeContent`, `TreeToggle`, `TreeValue` — indentation, disclosure/leaf
+  placeholder, and the consumer-rendered value in the tree column
 - `SortIndicator` — the sort arrow, inside the header `Item`'s suffix
 - `Foot`, `FootRow`, `FootCell` — pinned totals
 - `StateContent` — the empty / no-results / error content
@@ -390,6 +411,39 @@ Row-level modifiers, set on each `<tr>`: `odd`, `selected`, `focused`, `dimmed`,
 />
 ```
 
+### Tree Rows
+
+Supplying `getRowChildren` changes the root to `role="treegrid"`. Rows keep their
+original objects; keys must be unique across the complete hierarchy.
+
+```jsx
+<ItemTable
+  data={folders}
+  columns={columns}
+  getRowChildren={(row) => row.children}
+  treeColumnKey="name"
+  defaultExpandedKeys={['production']}
+  selectionMode="multiple"
+/>
+```
+
+Client sorting runs independently within every sibling collection. Client
+search retains ancestor paths; a matching parent keeps its complete subtree,
+and required branches open temporarily without changing `expandedKeys`. Client
+pagination counts and slices roots, keeping each subtree on its parent's page.
+Server modes treat the supplied nested page as already processed, and `total`
+counts roots.
+
+The chevron and Right/Left arrows expand or collapse. Up/Down traverse visible
+rows, typeahead uses the tree column, and Left on a collapsed child moves to its
+parent. Ordinary row clicks still activate `onRowAction`/`rowLink`; the
+disclosure does not. Select-all includes collapsed descendants. Disabled and
+unselectable descendants are excluded from cascade.
+
+Tree mode ignores `isReorderable`, because a flat reordered array cannot encode
+parents. `dropOnRow` remains available for folder moves; self/descendant cycles
+are rejected and selected descendants are collapsed under a dragged ancestor.
+
 ### Custom Cells
 
 ```jsx
@@ -668,6 +722,14 @@ DOM and the styles are identical either way — only the number of mounted rows
 changes, so sorting, search, pinned columns and the sticky header all behave the
 same.
 
+For a compact list in normal page flow, set `isAutoHeight`. Its frame then ends
+at the final rendered row instead of filling the surrounding flex pane. The
+complete result is rendered, so keep large lists bounded and virtualized.
+
+```jsx
+<ItemTable data={recentRows} columns={columns} paginationMode="off" isAutoHeight />
+```
+
 ```jsx
 <ItemTable height="420px" paginationMode="off" data={tenThousandRows} columns={columns} />
 ```

package/docs/components/layout/Board.md

@@ -53,7 +53,8 @@ clipped by an ancestor's `overflow: hidden`.
 - **`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.
-- **`rowHeight`** `number` (default: `100`) — Row height in pixels.
+- **`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, so `gridBounds` keeps every drag and resize inside the matrix without a per-widget `maxH`.
+- **`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.
 - **`margin`** `[number, number]` (default: `[8, 8]`) — Horizontal/vertical gap between widgets.
 - **`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.
@@ -61,7 +62,7 @@ clipped by an ancestor's `overflow: hidden`.
 - **`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). `'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 (so a widget displaced next to a neighbour may shrink). 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. It falls back to `'downscale'`, then `'revert'`. No mode ever *grows* a widget: a drag only ever preserves or reduces size. 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.
@@ -87,6 +88,7 @@ clipped by an ancestor's `overflow: hidden`.
 ### Board.Widget
 
 - **`id`** `string` (required) — Must match the `i` of a layout item.
+- **`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.
 - **`isResizable`** `boolean` — Disable resizing for this widget.
@@ -159,6 +161,7 @@ through `widgetProps.styles` or a per-widget `styles` resolves against them.
 - **`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.
@@ -219,6 +222,13 @@ CSS margin.
 
 ### 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.
@@ -252,10 +262,11 @@ 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,
-`'swap'` trades places with the widget already there. Neither ever grows a widget.
-One board per mode below — drag the wide widget onto the row below in the first,
-and drop a widget onto one of its neighbours in the second.
+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
 
@@ -419,6 +430,26 @@ described above. Set `aria-label` on your widgets and this reads correctly.
   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

package/docs/components/overlays/Tooltip.md

@@ -138,6 +138,18 @@ Control where the tooltip appears relative to its trigger:
 </TooltipProvider>
 ```
 
+### Long Content
+
+The tooltip is capped at `36x` wide (or the viewport minus `4x`, whichever is smaller) and wraps
+its content to stay inside that cap. Runs with no spaces — URLs, tokens, identifiers, error strings —
+are broken mid-word rather than allowed to overflow the bubble.
+
+```jsx
+<TooltipProvider title="https://cubecloud.example.com/deployments/12345/schema/files/model/cubes/very_long_cube_name.yml">
+  <Button>Hover me</Button>
+</TooltipProvider>
+```
+
 ### Light Theme
 
 Use the light theme for tooltips on dark backgrounds:

package/docs/tasty/configuration.md

@@ -78,7 +78,7 @@ These docs use `data-schema="dark"` in examples. If your app already standardize
 
 ## Color Space
 
-Controls the CSS color space used for decomposed color token companion variables. When you define `#name` color tokens, tasty generates both `--name-color` (full color) and `--name-color-{suffix}` (decomposed components for alpha composition).
+Controls the CSS color space used for decomposed color token companion variables. When you define `#name` color tokens, tasty generates both `--name-color` (the color) and `--name-color-{suffix}` (its channels, decomposed).
 
 ```jsx
 configure({
@@ -86,13 +86,17 @@ configure({
 });
 ```
 
-| Color Space | Suffix | Components Format | Alpha Syntax |
+| Color Space | Suffix | Components Format | Channel Reference |
 |---|---|---|---|
-| `rgb` | `-rgb` | `255 128 0` | `rgb(var(--name-color-rgb) / .5)` |
-| `hsl` | `-hsl` | `300 100% 25%` | `hsl(var(--name-color-hsl) / .5)` |
-| `oklch` | `-oklch` | `0.42 0.16 328` | `oklch(var(--name-color-oklch) / .5)` |
+| `rgb` | `-rgb` | `255 128 0` | `rgb(var(--name-color-rgb))` |
+| `hsl` | `-hsl` | `300 100% 25%` | `hsl(var(--name-color-hsl))` |
+| `oklch` | `-oklch` | `0.42 0.16 328` | `oklch(var(--name-color-oklch))` |
 
-The `oklch` color space is the default because it provides perceptually uniform color manipulation — alpha fading and color mixing produce more natural-looking results.
+The `oklch` color space is the default because it provides perceptually uniform color manipulation — reaching for a channel to shift lightness or hue produces more natural-looking results.
+
+The companion is there so you can *address the channels*: shift a lightness, animate a hue, build a derived color. It is not how the [opacity suffix](dsl.md#color-tokens--opacity) works — that sets the alpha on `--name-color` itself with relative color syntax, so it needs nothing from the companion and works on any color.
+
+A color the engine cannot evaluate at build time — a `color-mix()`, a `light-dark()`, a `color()` in a space it has no conversion for — has no channels to decompose, so its companion is expressed *by reference* using CSS relative color syntax (`--name-color-oklch: from color-mix(…) l c h`). Reading a channel off it still works; the browser resolves them.
 
 ---
 

package/docs/tasty/dsl.md

@@ -111,7 +111,7 @@ const List = tasty({
 Named color prefixed with `#` that maps to CSS custom properties. Supports opacity with `.N` suffix:
 
 ```jsx
-fill: '#purple.5'  // → var(--purple-color) with 50% opacity
+fill: '#purple.5'  // → oklch(from var(--purple-color) l c h / .5)
 ```
 
 ### Modifier
@@ -133,11 +133,108 @@ Modifiers can also be exposed as top-level component props via `modProps` — se
 color: '#purple',           // Full opacity
 color: '#purple.5',         // 50% opacity
 color: '#purple.05',        // 5% opacity
+color: '#purple.$fade',     // Opacity from a custom property
 fill: '#current',           // → currentcolor
-fill: '#current.5',         // → color-mix(in oklab, currentcolor 50%, transparent)
 color: '(#primary, #secondary)',  // Fallback syntax
 ```
 
+The suffix sets the alpha on the token's color with CSS relative color syntax:
+
+```jsx
+fill: '#purple.5';
+// → oklch(from var(--purple-color) l c h / .5)
+```
+
+The channels are copied over and the alpha slot is written, which asks nothing of
+the color beyond *being* a color. That means the suffix works on every one of
+these:
+
+- a token holding a `color-mix()`, a `light-dark()`, or a `color()` in a space
+  Tasty cannot convert — none of which have channels to decompose
+- `#current`, which resolves to `currentcolor`
+- a `--name-color` variable declared in your own CSS, with no Tasty token
+  definition and no companion variable behind it
+
+Two properties follow from writing the alpha slot rather than compositing:
+
+- **Alpha is replaced, not multiplied.** A token holding `rgb(255 0 0 / .8)`
+  faded to `.5` is alpha `.5`, not `.4`.
+- **The alpha may be a number or a percentage.** `#purple.$fade` emits
+  `/ var(--fade)` unchanged, so it works whether `$fade` holds `.5` or `50%` —
+  which is what `--*-opacity` properties are registered to accept.
+
+### `#current` composes instead
+
+`#current` is the one exception, and the difference is deliberate. A token *names*
+a color, so fading it sets its alpha. `currentcolor` is the color an element
+**inherits**, which an ancestor may already have faded — `#current.4` means "40%
+of what reaches me":
+
+```jsx
+fill: '#current.4';
+// → color-mix(in oklab, currentcolor 40%, transparent)
+```
+
+So a `#current` fade nested inside another one composes: a label at `#current.4`
+with a fill of `#current.18` under it lands at `.072`. Color ramps built on
+`#current` depend on that — replacing would double the opacity of every nested
+step. Because a `color-mix()` percentage cannot be a `<number>`, an opacity
+custom property used as `#current.$fade` must hold a unitless number; a token
+accepts either form.
+
+The space is always `oklch`, whatever [`colorSpace`](configuration.md#color-space)
+is set to: it is unbounded, so a wide-gamut color survives a round trip that a
+gamut-limited space would clamp.
+
+---
+
+## CSS Color Functions
+
+Every CSS color function is recognized as a color, so it lands in the color slot
+of whichever style property you use it in — and tokens inside it are expanded:
+
+```jsx
+fill: 'color-mix(in oklab, #primary 50%, #surface)',
+color: 'light-dark(#dark, #light)',
+color: 'contrast-color(#primary)',
+fill: 'color(display-p3 1 .5 0)',
+border: '1bw solid oklch(from #primary l c h / 50%)',  // relative color syntax
+shadow: '0 0 1x color-mix(in oklab, #dark 20%, transparent)',
+```
+
+`light-dark()` is the one exception to "always a color": CSS lets it pick between
+values of any type, so it is treated as a color only when its arguments are
+colors. `padding: 'light-dark(1x, 2x)'` still reaches the padding slot.
+
+A color token defined as one of these functions takes the
+[opacity suffix](#color-tokens--opacity) like any other:
+
+```jsx
+const Card = tasty({
+  styles: {
+    '#brand': 'color-mix(in oklab, #primary 50%, #surface)',
+    fill: '#brand.5',
+  },
+});
+```
+
+A [replace token](configuration.md#replace-tokens-parse-time-substitution) is
+substituted while parsing, so its color is right there to fade in place. A
+channel function takes the alpha after a slash; a derived function has no alpha
+channel, so it gets wrapped:
+
+```jsx
+configure({
+  replaceTokens: {
+    '#solid': 'hsl(220 90% 50%)',
+    '#adaptive': 'light-dark(#dark, #light)',
+  },
+});
+
+fill: '#solid.5';     // → hsl(220 90% 50% / .5)
+fill: '#adaptive.5';  // → oklch(from light-dark(…) l c h / .5)
+```
+
 ---
 
 ## Built-in Units

package/docs/tasty/styles.md

@@ -254,6 +254,7 @@ Background color with design token support. Preferred over `backgroundColor` and
 | `"#purple.10"` | Token color at 10% opacity |
 | `"#surface #primary.10"` | Background `#surface` with `#primary.10` overlay (two colors enable smooth transitions between both) |
 | `"rgb(255 128 0)"` | CSS color value |
+| `"color-mix(in oklab, #primary 50%, #surface)"` | CSS color function — see [CSS Color Functions](dsl.md#css-color-functions) |
 | `true` | Default fill color |
 
 When two colors are provided, the first sets the background color and the second is applied as an overlay gradient layer. This enables independent CSS transitions on each color. The overlay is only applied when no explicit `image` or `backgroundImage` is set.
@@ -286,9 +287,10 @@ Text color with design token support.
 | `"#current"` | Current inherited color |
 | `"#current.5"` | Current inherited color at 50% opacity |
 | `"(#primary, #secondary)"` | Fallback: use `#primary`, fall back to `#secondary` |
+| `"light-dark(#dark, #light)"` | CSS color function — see [CSS Color Functions](dsl.md#css-color-functions) |
 | `true` | `currentColor` |
 
-When set to a named color token, also sets `$current-color` and `$current-color-{colorSpace}` custom properties for downstream use (suffix depends on the configured `colorSpace`, default `oklch`).
+When set to a named color token, also sets `$current-color` and `$current-color-{colorSpace}` custom properties for downstream use (suffix depends on the configured `colorSpace`, default `oklch`). An opacity suffix does not move the companion: `color="#purple.5"` still reports `#purple`'s channels, since components carry no alpha.
 
 ### `svgFill`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.164.0",
+  "version": "0.166.0",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {
@@ -59,7 +59,7 @@
     "@tabler/icons-react": "^3.31.0",
     "@tanstack/react-virtual": "^3.13.12",
     "@tenphi/glaze": "2.0.0",
-    "@tenphi/tasty": "^3.0.2",
+    "@tenphi/tasty": "^3.1.0",
     "clipboard-copy": "^4.0.1",
     "clsx": "^1.1.1",
     "diff": "^8.0.3",