@cube-dev/ui-kit 0.163.0 → 0.165.0

package/docs/Usage.md

@@ -142,6 +142,33 @@ The neutral palette uses a `surface` / `surface-text` model. Each surface depth
 | `#overlay` | Dim backdrop (50% transparent) |
 | `#clear` | `transparent` |
 
+### Context Hooks
+
+Tokens a **container** sets to steer a component that cannot resolve the color on
+its own. They ship with a default, so nothing has to be set unless the default is
+wrong.
+
+| Token | Default | Role |
+|-------|---------|------|
+| `#current-fill` | `#surface` | The label color `current.primary` punches out of its `currentcolor` chip — read by that one flavour and nothing else |
+
+`theme="current" type="primary"` fills with the color it **inherits**, so its
+label cannot come from that color too and reads `#current-fill` instead. The page
+(`#surface`) is the right answer almost everywhere, and wrong in exactly one
+place: a container whose own text color is the page paints `#white`, which *is*
+`#surface` in light mode, so the label would vanish into its own chip. Such a container sets
+the token to its own fill, which contrasts with its own text by construction:
+
+```jsx
+<Block fill="#fixed-dark" color="#white" styles={{ '#current-fill': '#fixed-dark' }}>
+  <Button theme="current" type="primary">Legible in both schemes</Button>
+</Block>
+```
+
+Setting it moves the label, the icon slots and the chip's rim together. It also
+takes the alpha suffix like any other token (`#current-fill.5` is the disabled
+label), because it is a declared token rather than a bare custom property.
+
 ### Accent System
 
 Each themed color (default, primary, success, danger, warning, note) provides an `accent-*` family anchored to a fixed white "accent surface text". These tokens stay recognizable across schemes (used for branded buttons, CTAs, etc.):
@@ -179,7 +206,7 @@ For example, a success banner uses `fill: '#success-surface'` + `color: '#succes
 ```ts
 import { resetPaletteConfig, setPaletteConfig } from '@cube-dev/ui-kit';
 
-setPaletteConfig({ hue: 210, themes: { danger: { hue: 12 } } });
+setPaletteConfig({ accent: { hue: 210 }, themes: { danger: '#b91c1c' } });
 resetPaletteConfig();
 ```
 
@@ -188,7 +215,7 @@ Also available: `getPaletteConfig()`, `subscribePaletteConfig()`, the `usePalett
 To theme a *region* instead of the document — a theme preview, or a dark panel inside a light page — use `renderColorTokens()`. It resolves one config and one scheme to flat values you apply via a `tokens` prop, without touching the live palette:
 
 ```tsx
-<Block tokens={renderColorTokens({ hue: 210, scheme: 'dark' })} fill="#surface">
+<Block tokens={renderColorTokens({ accent: { hue: 210 }, scheme: 'dark' })} fill="#surface">
   …
 </Block>
 ```
@@ -306,6 +333,7 @@ Component themes are set via the `theme` prop or `theme=name` modifier:
 | `success` | Success / positive states |
 | `warning` | Warning / caution states |
 | `note` | Informational / note states |
+| `current` | No palette of its own — every color is mixed from the inherited text color (`#current`), so the component adopts whatever its container paints with. Supported by `Button`, `Item` (and `ItemButton`, `Item.Action`, `ItemBadge`) |
 
 ## Recipes
 
@@ -367,6 +395,39 @@ Icons live in `src/icons/`. Use existing icons when possible; otherwise use `@ta
 - Always wrap tabler icons with `<Icon>` for custom size/color. Never add props directly to tabler icons.
 - To add new icons run: `pnpm add-icons`
 
+Illustrations are not icons and do not live in `src/icons/`: `CubeLogo` and
+`NoDataIcon` are `Icon`-based components under `src/components/other/`. They size
+like an icon, but `NoDataIcon` is a three-tone drawing on the shared cube-face
+tokens (`#loading-face-1` … `#loading-face-3`) rather than a `currentColor`
+glyph, so it ignores `color` and belongs at illustration sizes (`size="8x"` and
+up).
+
+## Hierarchical Table Rows
+
+`ItemTable` and `DataTable` opt into native treegrid behavior with
+`getRowChildren`. Pass roots in `data`; the callback returns already-loaded
+children, and row keys must be globally unique. Expansion is uncontrolled with
+`defaultExpandedKeys` or controlled with `expandedKeys` / `onExpand`.
+
+The shared table engine recursively sorts siblings, paginates roots with their
+complete subtrees, and flattens only expanded rows for rendering and
+virtualization. ItemTable client search preserves ancestor paths and temporarily
+opens branches containing matches. Server modes do not transform nested data.
+
+Use `treeColumnKey` to choose the disclosure/indent column. Its hierarchy chrome
+is customizable through the `TreeContent`, `TreeToggle`, and `TreeValue`
+sub-elements. ItemTable multiple selection cascades by default; DataTable cell
+ranges contain visible rows only. See each component's docs for pagination,
+numbering, selection, and drag/drop limits.
+
+DataTable also accepts nested column definitions for already-shaped pivot
+results. Group nodes create accessible multi-row headers with native column
+spans, while sorting, resizing, ranges and copying continue to operate on their
+leaf columns. Both tables fill an available flex pane by default; use
+`isAutoHeight` for a compact result whose frame should end at its last rendered
+row. Auto-height renders every row, so bounded tables remain the right choice
+for large results.
+
 ## Form System
 
 ### Form Component

package/docs/components/Root.md

@@ -13,7 +13,7 @@ The root application wrapper. Provides theme context, global styles, portal cont
 - **`navigation`** `NavigationAdapter` — Custom navigation adapter for routing
 - **`tracking`** `TrackingProps` — Analytics/tracking event configuration
 - **`tokens`** `Record<string, string>` — Custom design tokens (CSS custom properties)
-- **`palette`** `PaletteConfig` — Tune the generated color palette: brand `hue` / `saturation`, per-status theme seeds, `pastel`, `contrastLevel`. Applied during render, so the first paint is already correct. Describes the whole palette, so dropping a field drops that customization. A convenience wrapper over `setPaletteConfig()` — the palette is process-global, not per tree. See [Theming](../Theming.md)
+- **`palette`** `PaletteConfig` — Tune the generated color palette. Every zone — `accent`, `base` and each status theme — takes the same seed: a color, or `{ hue, saturation }`. Plus the global `surfaceMode`, `pastel` and `contrastLevel`. Applied during render, so the first paint is already correct. Describes the whole palette, so dropping a field drops that customization. A convenience wrapper over `setPaletteConfig()` — the palette is process-global, not per tree. See [Theming](../Theming.md)
 - **`fonts`** `boolean` — Whether to load default fonts
 - **`font`** `string` — Custom font family name
 - **`monospaceFont`** `string` — Custom monospace font family name

package/docs/components/actions/Button.md

@@ -15,8 +15,8 @@ A versatile action component that triggers commands and navigates users.
 
 ## Properties
 
-- **`type`** `'primary' | 'outline' | 'outline-2' | 'clear' | 'link' | 'current'` (default: `outline`) — Visual style variant of the button (`outline-2` is identical to `outline` but uses `#surface-3` as the base fill; not available for the `special` theme. `current` derives its colors from the inherited text color and ignores `theme`)
-- **`theme`** `'default' | 'danger' | 'success' | 'warning' | 'note' | 'special'` (default: `default`) — Semantic colour palette theme
+- **`type`** `'primary' | 'outline' | 'outline-2' | 'clear' | 'link'` (default: `outline`) — Visual style variant of the button (`outline-2` is identical to `outline` but uses `#surface-3` as the base fill; not available for the `special` theme)
+- **`theme`** `'default' | 'danger' | 'success' | 'warning' | 'note' | 'special' | 'current'` (default: `default`) — Semantic colour palette theme. `current` is not a brand palette: it mixes every color from the inherited text color, so the button adopts the color of whatever container it sits in
 - **`size`** `'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'inline' | number` (default: `medium`) — Button size. Use `'inline'` for link-type buttons or a number/string for custom sizes (e.g. `64` or `'8x'`)
 - **`icon`** — Icon rendered before the content. Can be: ReactNode, `true` (empty slot), or function `({ loading, selected, ...mods }) => ReactNode | true`
 - **`rightIcon`** — Icon rendered after the content. Can be: ReactNode, `true` (empty slot), or function `({ loading, selected, ...mods }) => ReactNode | true`
@@ -82,7 +82,6 @@ The `mods` prop accepts the following modifiers you can override:
 - `outline` – Border with transparent background; `isSelected` adds brand-tinted fill.
 - `clear` – No border, transparent background; `isSelected` adds brand-tinted fill.
 - `link` – Styled as a textual link.
-- `current` – Fill, border and label are mixed from the inherited text color (`#current`), so the button adopts the color of whatever container it sits in. The resting chip is a `#current.03` fill inside a `#current.08` border, and hover, pressed and selected step the same alpha ramp up from there; the label stays fully opaque. The focus ring stays `#primary-accent-text`, like every other type. Theme-agnostic — there is a single variant, and `theme` has no effect. Use it inside colored containers (alerts, banners, dark overlays, tooltips). `Item` has a `current` type too, shaped like its neutral `item` type instead: borderless and invisible at rest.
 
 ### Themes. `theme` prop
 
@@ -92,6 +91,13 @@ The `mods` prop accepts the following modifiers you can override:
 - `warning` – Yellow/amber palette for caution or attention.
 - `note` – Violet palette for informational context.
 - `special` – White palette for dark backgrounds.
+- `current` – Not a palette at all: fill, border and label are mixed from the inherited text color (`#current`), so the button adopts the color of whatever container it sits in and keeps adopting it if that color changes. Every `type` has a `current` flavour, so the shape is still yours to pick — `outline` is the resting `#current.03` chip inside a `#current.08` border, `primary` escalates the same construction to a filled chip, `clear` paints nothing at rest, `link` is the label alone. `primary` is the one flavour that needs a second color: the fill is the inherited color at full strength, so the label is punched out of it with `#current-fill`, which defaults to `#surface`. A container whose own text color collides with the page (a `Banner` labels itself `#white`, and `#surface` is white in light mode) should override `#current-fill` with its own fill, which contrasts with its own text by construction; ordinary containers need nothing. The label stays fully opaque and the focus ring stays `#primary-accent-text`, like every other theme. Use it inside colored containers (alerts, banners, dark overlays, tooltips), where a brand theme would either clash with the container or have to be picked to match it.
+
+  ```jsx
+  <Alert theme="note">
+    <Button theme="current" type="outline">Adopts the note color</Button>
+  </Alert>
+  ```
 
 ### Sizes. `size` prop
 

package/docs/components/actions/ItemAction.md

@@ -1,6 +1,6 @@
 # ItemAction
 
-A compact action button designed for use inside `Item`, `ItemButton`, and `ItemCard`. Automatically inherits `type` and `theme` from its parent context.
+A compact action button designed for use inside `Item`, `ItemButton`, and `ItemCard`. Defaults to the `current` theme, so it takes its colors from whatever row hosts it.
 
 ## When to Use
 
@@ -15,8 +15,8 @@ A compact action button designed for use inside `Item`, `ItemButton`, and `ItemC
 ## Properties
 
 - **`icon`** `ReactNode | 'checkmark'` — Icon element or `'checkmark'` for a selection indicator
-- **`type`** `'primary' | 'outline' | 'clear'` (default: `'clear'`) — Visual type. Inherits from parent context.
-- **`theme`** `'default' | 'danger' | 'success' | 'warning' | 'note' | 'special'` (default: `'default'`) — Color theme. Inherits from parent context.
+- **`type`** `'primary' | 'outline' | 'clear'` (default: `'clear'`) — Visual type. `clear` is borderless and paints nothing at rest, so a row full of actions does not read as busy.
+- **`theme`** `'current' | 'default' | 'danger' | 'success' | 'warning' | 'note' | 'special'` (default: `'current'`) — Color theme. `current` derives every color from the inherited `currentcolor`, so the action tracks whatever row hosts it without being told the row's type or theme. Name any other theme to have the action paint itself instead.
 - **`isLoading`** `boolean` (default: `false`) — Shows loading spinner
 - **`isSelected`** `boolean` (default: `false`) — Selected state (works with `icon="checkmark"`)
 - **`isDisabled`** `boolean` (default: `false`) — Disables the action. Inherits from parent; use `isDisabled={false}` to override.

package/docs/components/actions/MenuTrigger.md

@@ -19,6 +19,8 @@ Wraps a trigger element and a `Menu` to create a dropdown menu. Positions the me
 - **`offset`** `number` (default: `8`) — Distance from trigger in pixels
 - **`crossOffset`** `number` (default: `0`) — Cross-axis offset in pixels
 - **`containerPadding`** `number` — Minimum padding from viewport edges in pixels
+- **`mobileType`** `'popover' | 'tray'` (default: `'popover'`) — Overlay variant on mobile screens. `'tray'` opts into the bottom-sheet overlay
+- **`shouldRestoreFocus`** `boolean` (default: `true`) — Whether focus returns to the trigger when the menu closes. See [Focus restoration](#focus-restoration)
 
 Extends React Aria `AriaMenuTriggerProps` and `PositionProps`.
 
@@ -31,11 +33,61 @@ Supports [Base properties](../../BaseProperties.md).
 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`, `margin`, `inset`, `position`
+- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `scrollMargin`
 - **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
 - **Block:** `border`, `radius`, `shadow`, `outline`, `padding`, `paddingInline`, `paddingBlock`, `overflow`, `scrollbar`, `textAlign`
 - **Color:** `color`, `fill`, `fade`, `image`
-- **Flow:** `flow`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
+- **Flow:** `flow`, `place`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
+
+## Focus restoration
+
+When the menu closes, focus returns to the trigger — **unless the action that
+closed it moved focus somewhere else**. An item whose action opens a panel, a
+dialog or an inline editor just focuses that surface; a single `focus()` call
+from a mount effect is enough, and the menu leaves it alone:
+
+```jsx
+function Panel() {
+  const ref = useRef(null);
+
+  // One call. No retry loop, no racing the closing menu.
+  useEffect(() => {
+    ref.current?.focus({ preventScroll: true });
+  }, []);
+
+  return (
+    <div ref={ref} tabIndex={-1}>
+      …
+    </div>
+  );
+}
+
+<MenuTrigger>
+  <Button icon={<MoreIcon />} aria-label="Actions" />
+  <Menu onAction={(key) => key === 'configure' && setPanelOpen(true)}>
+    <Menu.Item key="configure">Configure…</Menu.Item>
+  </Menu>
+</MenuTrigger>;
+```
+
+Focusing the surface's own container rather than its first tabbable child
+matters when a header carries a close button — `<FocusScope autoFocus>` would
+land the user on ✕, with <kbd>Enter</kbd> already meaning "close the thing that
+just opened".
+
+`shouldRestoreFocus={false}` covers the remaining case: a surface that claims
+focus *later* than the menu's restore — after an async load, an entry
+animation, or a `requestAnimationFrame`. Without it the trigger takes focus
+first and the user sees a flash.
+
+```jsx
+<MenuTrigger shouldRestoreFocus={false}>
+  <Button icon={<MoreIcon />} aria-label="Actions" />
+  <Menu onAction={openPanelThatFocusesAfterItsData}>
+    <Menu.Item key="configure">Configure…</Menu.Item>
+  </Menu>
+</MenuTrigger>
+```
 
 ## Examples
 

package/docs/components/actions/SubMenuTrigger.md

@@ -31,11 +31,11 @@ Supports [Base properties](../../BaseProperties.md).
 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`, `margin`, `inset`, `position`
+- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `scrollMargin`
 - **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
 - **Block:** `border`, `radius`, `shadow`, `outline`, `padding`, `paddingInline`, `paddingBlock`, `overflow`, `scrollbar`, `textAlign`
 - **Color:** `color`, `fill`, `fade`, `image`
-- **Flow:** `flow`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
+- **Flow:** `flow`, `place`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
 
 ## Examples
 

package/docs/components/content/CopySnippet.md

@@ -15,6 +15,7 @@ A code block with copy-to-clipboard functionality and syntax highlighting. Exten
 - **`title`** `string` (default: `'Code example'`) — Accessible title used in the copy toast message
 - **`prefix`** `string` (default: `''`) — Prefix for each line of code (e.g. `'$ '` for bash snippets)
 - **`nowrap`** `boolean` — Force single-line display even for multi-line code
+- **`isWrapped`** `boolean` — Soft-wrap long content onto multiple lines instead of scrolling it horizontally. The block grows to fit, so even a single long line stays fully readable, and unbreakable runs (URLs, tokens, identifiers) wrap too. Useful for error messages and logs. Ignored when `nowrap` is set (a different axis: `nowrap` collapses newlines into one scrolling line, `isWrapped` breaks long lines).
 - **`serif`** `boolean` — Use serif (non-monospace) font for the code
 - **`hideText`** `string | string[] | boolean` — Hide sensitive text with bullet characters. `true` hides all text, a string hides that substring, an array hides multiple substrings. A toggle button appears to reveal hidden content.
 - **`actions`** `ReactNode` — Additional action buttons displayed alongside the copy button. Use `CopySnippet.Button` for consistent styling.
@@ -49,14 +50,13 @@ These properties allow direct style application without using the `styles` prop:
 ```jsx
 <CopySnippet code="const x = 1;" language="javascript" />
 
-<CopySnippet
-  code={'{\n  "key": "value"\n}'}
-  language="json"
-  multiline
-/>
+<CopySnippet code={'{\n  "key": "value"\n}'} language="json" />
 
 <CopySnippet
   code={'<button type="button" class="primary">Save</button>'}
   language="html"
 />
+
+// Wrap a long single-line error instead of scrolling it sideways
+<CopySnippet code={longErrorMessage} language="bash" isWrapped />
 ```

package/docs/components/content/InlineInput.md

@@ -261,7 +261,7 @@ When `InlineInput` is embedded in a host that already owns keyboard activation (
 
 ### Focus Management
 
-When entering edit mode, focus is taken explicitly by a `FocusScope` with `autoFocus`. This makes the transition deterministic even when triggered from a closing menu (which would otherwise restore focus to the menu trigger). The text content is selected automatically.
+When entering edit mode, focus is taken explicitly by a `FocusScope` with `autoFocus`, and the text content is selected automatically. On top of that, a blur arriving in the same tick as a programmatic `startEditing()` re-focuses the input instead of committing, so hosts that drive editing through the imperative ref stay in edit mode even if something else grabs focus as the input mounts. The guard clears on the user's first keystroke, so later click-aways commit normally.
 
 When leaving edit mode, focus is not restored automatically — the host is responsible for moving focus back to a meaningful element (e.g. the parent button or row).
 

package/docs/components/content/Item.md

@@ -22,8 +22,8 @@ A foundational component that provides a standardized layout and styling for ite
 - **`suffix`** `ReactNode` — Element rendered after the content (before rightIcon)
 - **`description`** `ReactNode` — Description text displayed with the item
 - **`descriptionPlacement`** `'inline' | 'block'` (default: `inline`) — How the description is positioned relative to the main content. Defaults to `'block'` for `type="card"` and `type="header"`
-- **`type`** `'item' | 'header' | 'primary' | 'outline' | 'outline-2' | 'clear' | 'link' | 'card' | 'current'` (default: `item`) — Visual style variant
-- **`theme`** `'default' | 'danger' | 'success' | 'warning' | 'note' | 'special'` (default: `default`) — Semantic colour palette theme
+- **`type`** `'item' | 'header' | 'primary' | 'outline' | 'outline-2' | 'clear' | 'link' | 'card'` (default: `item`) — Visual style variant
+- **`theme`** `'default' | 'danger' | 'success' | 'warning' | 'note' | 'special' | 'current'` (default: `default`) — Semantic colour palette theme. `current` is not a brand palette: it mixes every color from the inherited text color, so the item adopts the color of whatever container it sits in
 - **`size`** `'xsmall' | 'small' | 'medium' | 'large' | 'xlarge' | 'inline' | number` (default: `medium`) — Item size. Accepts custom number or string values
 - **`shape`** `'card' | 'button' | 'sharp' | 'pill'` (default: `button`) — Shape of the item border radius. Defaults to `'card'` for `type="card"`
 - **`isSelected`** `boolean` (default: `false`) — Marks the item as selected
@@ -84,8 +84,8 @@ The `mods` property accepts the following modifiers:
 - **`disabled`** `boolean` — Applied when isDisabled is true or when loading
 - **`loading`** `boolean` — Applied when isLoading is true
 - **`size`** `string` — Applied based on size prop value (xsmall, small, medium, large, xlarge, inline)
-- **`type`** `string` — Applied based on type prop value (item, header, primary, outline, outline-2, clear, link, card, current)
-- **`theme`** `string` — Applied based on theme prop value (default, danger, success, special, warning, note)
+- **`type`** `string` — Applied based on type prop value (item, header, primary, outline, outline-2, clear, link, card)
+- **`theme`** `string` — Applied based on theme prop value (default, danger, success, special, warning, note, current)
 - **`shape`** `string` — Applied based on shape prop value (card, button, sharp, pill)
 
 ## Variants
@@ -99,8 +99,7 @@ The `mods` property accepts the following modifiers:
 - `outline-2` - Same as `outline` but uses `#surface-3` as the base fill, designed to sit on `#surface-2` containers without blending in (not available for the `special` theme)
 - `clear` - Transparent item with minimal styling; `isSelected` adds brand-tinted fill
 - `link` - Link-styled item appearance (does not support icons or loading state)
-- `card` - Card appearance for notifications (supports `default`, `success`, `danger`, `warning`, `note` themes; defaults to `shape="card"`, `descriptionPlacement="block"`, uses semantic heading tags via `level` prop, and has `.5x` padding)
-- `current` - Same shape as `item` — no border, nothing painted at rest — but every color is derived from the inherited text color (`#current`) instead of the fixed `#surface-text`, so the item adopts the color of whatever container it sits in. The fill steps in on hover (`.04`), pressed (`.06`) and selected (`.09` → `.15`); the label stays fully opaque. Theme-agnostic: only supports the `default` theme (any other theme warns, since there is nothing for it to change). Use it inside colored containers — alerts, banners, dark overlays, tooltips. `Button` has a `current` type too, shaped like a standalone control instead: a resting `#current.03` chip inside a `#current.08` border
+- `card` - Card appearance for notifications (supports `default`, `success`, `danger`, `warning`, `note`, `current` themes; defaults to `shape="card"`, `descriptionPlacement="block"`, uses semantic heading tags via `level` prop, and has `.5x` padding)
 
 ### Themes
 
@@ -110,6 +109,7 @@ The `mods` property accepts the following modifiers:
 - `warning` - Yellow/amber theme for caution or attention
 - `note` - Violet theme for informational context
 - `special` - Special theme with unique styling (not available for `card` or `header` types)
+- `current` - Not a palette at all: every color is derived from the inherited text color (`#current`) instead of a brand ramp, so the item adopts the color of whatever container it sits in. Every type except `header` has a `current` flavour, so the shape is still yours to pick — `item` keeps its borderless shape (nothing painted at rest, the fill stepping in on hover, pressed and selected), `outline` adds the chip and border, `primary` escalates it further. `primary` is the one flavour that needs a second color: its fill is the inherited color at full strength, so the label is punched out of it with `#current-fill` (default `#surface`) — a container whose own text color collides with the page, such as a `Banner` labelling itself `#white`, should override `#current-fill` with its own fill. The label stays fully opaque. Use it inside colored containers — alerts, banners, dark overlays, tooltips
 
 ### Sizes
 
@@ -257,17 +257,17 @@ Like headers, card labels use semantic heading tags (h1-h6) controlled by the `l
 </Item>
 ```
 
-### Current Type
+### Current Theme
 
-Use `type="current"` inside a container that paints its own text color. The fill and label are mixed from that inherited color, so the item matches the container without picking a theme — and keeps matching it if the container's color changes:
+Use `theme="current"` inside a container that paints its own text color. The fill and label are mixed from that inherited color, so the item matches the container without picking a brand theme — and keeps matching it if the container's color changes. Every type composes with it:
 
 ```jsx
 <Block fill="#note-surface" color="#note-accent-text" padding="1.5x" radius="1cr">
-  <Item type="current" icon={<IconInfo />}>Adopts the note color</Item>
+  <Item theme="current" icon={<IconInfo />}>Adopts the note color</Item>
 </Block>
 
 <Block fill="#fixed-dark" color="#white" padding="1.5x" radius="1cr">
-  <Item type="current" icon={<IconInfo />}>Adopts white on a dark banner</Item>
+  <Item theme="current" type="outline" icon={<IconInfo />}>An outlined chip on a dark banner</Item>
 </Block>
 ```
 

package/docs/components/content/ItemBadge.md

@@ -11,8 +11,8 @@ A non-interactive badge indicator for list items. Similar to `ItemAction` but wi
 ## Properties
 
 - **`icon`** `ReactNode | 'checkmark'` — Icon or checkmark display
-- **`type`** `'primary' | 'outline' | 'clear'` (default: `'clear'`) — Visual type. `isSelected` applies brand-tinted fill to `outline` and `clear`. Inherits from parent context.
-- **`theme`** `'default' | 'danger' | 'success' | 'special'` (default: `'default'`) — Color theme. Inherits from parent context.
+- **`type`** `'primary' | 'outline' | 'clear'` (default: `'clear'`) — Visual type. `isSelected` applies brand-tinted fill to `outline` and `clear`.
+- **`theme`** `'current' | 'default' | 'danger' | 'success' | 'special'` (default: `'current'`) — Color theme. `current` derives every color from the inherited `currentcolor`, so the badge tracks whatever row hosts it. Name any other theme to have the badge paint itself instead.
 - **`isLoading`** `boolean` (default: `false`) — Show loading spinner
 - **`isSelected`** `boolean` (default: `false`) — Selected state (for checkmark)
 - **`tooltip`** `string | object` — Tooltip content shown on hover for icon-only badges. A string shows tooltip text; an object supports `{ title, ...tooltipProps }` for advanced configuration.

package/docs/components/content/PrismCode.md

@@ -12,6 +12,7 @@ Syntax-highlighted code block using Prism. Supports multiple languages.
 
 - **`code`** `string` (default: `''`) — The code snippet to highlight
 - **`language`** `string` (default: `'javascript'`) — Language for syntax highlighting (`javascript`, `typescript`, `json`, `yaml`, `bash`, `sql`, `css`, `html`, etc.)
+- **`isWrapped`** `boolean` — Soft-wrap long lines onto multiple lines instead of scrolling them horizontally. Unbreakable runs (URLs, tokens, identifiers) wrap too. Useful for error messages and logs.
 
 ### Style Defaults
 

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