@cube-dev/ui-kit 0.163.0 → 0.164.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,13 @@ 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).
+
 ## 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/fields/ColorSwatch.md

@@ -0,0 +1,155 @@
+# ColorSwatch
+
+A square of color. It is the smallest piece of the color family —
+[ColorPicker](./ColorPicker.md),
+[ColorInput](./ColorInput.md) and
+[ColorSwatchGroup](./ColorSwatchGroup.md) all draw one, and it is
+exported so a legend, a list row or a table cell can draw the same one.
+
+It is decorative on its own: it carries no text and no accessible name. Pair it
+with the value written out, or put it in a control that names it.
+
+## When to Use
+
+- Next to a color value in a list, a table or a chart legend
+- In the `icon` / `rightIcon` / `prefix` / `suffix` slot of an `Item` or `Button`
+- As the color part of a custom control built on top of the color fields
+
+## Component
+
+---
+
+### Properties
+
+- **`color`** `string | ColorValue | null` — The color to show. Anything the color fields accept — `#7a4dbf`, `rgb(122 77 191)`, `oklch(…)`. `null`, or a string that cannot be parsed, shows the empty state
+- **`size`** `'small' | 'medium' | 'large'` — The edge of the swatch: `20px`, `24px` or `28px`. Left unset, the swatch tracks the control around it (see below)
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md)
+
+### Styling Properties
+
+#### styles
+
+Customizes the swatch itself. `width` and `height` set here win over both the
+`size` prop and the automatic sizing.
+
+### 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`, `margin`, `inset`, `position`, `scrollMargin`
+- **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
+- **Block:** `border`, `radius`, `shadow`, `outline`, `padding`, `paddingInline`, `paddingBlock`, `overflow`, `scrollbar`, `textAlign`
+
+### Modifiers
+
+The `mods` property accepts the following modifiers you can override:
+
+| Modifier | Type      | Description                                                    |
+| -------- | --------- | -------------------------------------------------------------- |
+| `empty`  | `boolean` | No color to show — drawn as the conventional diagonal stroke     |
+
+## Sizes
+
+- `small` — `20px`
+- `medium` — `24px`
+- `large` — `28px`
+
+### Sizing inside a control
+
+Leave `size` off and the swatch sizes itself to whatever it sits in. `Item`,
+`Button` and the text inputs publish their own height as the `$size` custom
+property, and the swatch reads it and lands `8px` inside — `20px` in a `small`
+control, `24px` in a `medium` one, `28px` in a `large` one. Nothing has to be
+passed between the two, so a control that changes size takes its swatch with it.
+
+Outside a control there is nothing to read, and the swatch falls back to
+`medium`.
+
+`ColorInput` and `ColorPicker` deliberately do **not** use this. Their swatch is a
+fixed `20px` badge at every field size — it reads as a value the field is showing
+rather than as part of the control, and a text input hangs its prefix off the border
+with no padding of its own, so a tracking swatch in a large field would sit against
+the edge. Automatic fitting is for a swatch you place yourself, in a `Button` or an
+`Item`, where the host has the padding that makes it work.
+
+## Examples
+
+### Basic Usage
+
+```jsx
+<ColorSwatch color="#7a4dbf" />
+```
+
+### In a control
+
+```jsx
+<Button icon={<ColorSwatch color={color} />}>{color}</Button>
+
+<Item icon={<ColorSwatch color={color} />} suffix={<ColorSwatch color={hover} />}>
+  Accent
+</Item>
+```
+
+### With the value spelled out
+
+The swatch has no accessible name of its own, so the text beside it is what a
+screen reader announces.
+
+```jsx
+<Space gap="1x" placeItems="center start">
+  <ColorSwatch color={value} />
+  <Text>{value}</Text>
+</Space>
+```
+
+### A fixed size
+
+```jsx
+<ColorSwatch size="large" color="#26fcb2" />
+```
+
+### Any other shape
+
+```jsx
+<ColorSwatch color="#26fcb2" radius="round" width="6x" height="6x" />
+```
+
+## Accessibility
+
+`ColorSwatch` renders a plain `div` with no role and no name — a color on its
+own is not information a screen reader can use, and an announced hex is rarely
+what the user wants to hear.
+
+- **Do** put the value, or the name of the thing the color belongs to, next to it
+- **Do** rely on the surrounding control's `aria-label` when the swatch is its icon
+- **Don't** use color as the only way to tell two rows apart
+
+## Best Practices
+
+1. **Do**: let a swatch inside a control size itself
+
+   ```jsx
+   <Button size="small" icon={<ColorSwatch color={color} />}>
+     {color}
+   </Button>
+   ```
+
+2. **Don't**: hand-tune the box to match a control
+
+   ```jsx
+   <Button size="small" icon={<ColorSwatch color={color} width="2.5x" height="2.5x" />}>
+     {color}
+   </Button>
+   ```
+
+3. **Accessibility**: never let the swatch be the only carrier of the meaning
+
+## Related Components
+
+- [ColorPicker](./ColorPicker.md) — a swatch that opens the color popover
+- [ColorInput](./ColorInput.md) — the color as editable text, with a swatch inside
+- [ColorSwatchGroup](./ColorSwatchGroup.md) — a selectable grid of swatches

package/docs/components/layout/Board.md

@@ -61,13 +61,15 @@ 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.
 - **`isDraggable`** `boolean` (default: `true`) — Enable dragging for all widgets.
 - **`isResizable`** `boolean` (default: `true`) — Enable resizing for all widgets.
 - **`isDroppable`** `boolean` (default: `true`) — Whether the board accepts widgets dropped from other boards.
 - **`resizeHandles`** `ResizeHandleAxis[]` (default: `['se']`) — Which resize handles to show. Corner handles (`ne`/`nw`/`se`/`sw`) show an angle grip; edge handles (`n`/`s`/`e`/`w`) show a dotted grip. Both are revealed on hover/focus/resize. A single edge (e.g. `['e']` or `['s']`) gives a horizontally- or vertically-only resizable widget.
+- **`resizeGripPlacement`** `'inside' | 'corner'` (default: `'inside'`) — Where the corner grips sit. `'inside'` tucks each one into the widget box; `'corner'` centres it on the widget's corner, so it lines up with a control centred on the opposite corner. Only affects corner handles — a dotted edge grip always stays inside. A corner-placed grip is drawn *outside* the widget (a widget clips its own content, which would otherwise cut the grip in half), so it needs the board to have at least half a grip's worth of `containerPadding` to show in full against the board's edge. Its hit-zone moves out with it and overhangs by the same half-grip, so the whole visible grip is grabbable and hovering it keeps it revealed — the trade is a ~5px band just outside each corner where a press starts a resize rather than a marquee. Can be overridden per widget.
 - **`dragCancel`** `string` — CSS selector for elements that must not start a pointer drag (e.g. form controls inside a widget: `"input,textarea,button,a,.no-drag"`). Does not affect keyboard moves — those only run when the widget host itself is focused. Can be overridden per widget.
 - **`dragHandle`** `string` — CSS selector for the only elements from which a pointer drag may start. Can be overridden per widget.
-- **`showGridLines`** `boolean | 'drag'` (default: `false`) — Show grid lines behind the widgets. `true` always, `'drag'` only while a widget is being dragged or resized. A nested board that does not set this inherits an enabled ancestor's grid lines, showing its own while a drag is in progress.
+- **`showGridLines`** `boolean | 'drag' | 'any-drag'` (default: `false`) — Show grid lines behind the widgets. `true` always; `false` never; `'drag'` only while *this* board is part of the active gesture — it owns the drag (as its source, or as the board the widget is currently over) or one of its own widgets is being resized; `'any-drag'` while any drag is in flight anywhere under a shared `Board.Provider`, so every board advertises itself as somewhere the widget could land. Under one `Board.Provider`, `'drag'` keeps boards a widget cannot land in quiet, and `'any-drag'` is the opt-in for the noisier, more informative version. A nested board that does not set this inherits an enabled ancestor's setting, at the ancestor's own scope.
 - **`isAligned`** `boolean` (default: `false`) — Align a nested board with its ancestor `Board`'s layout. Only takes effect when the board is nested inside another `Board`'s widget. When set, every cell matches the parent's cell size exactly: the board inherits the parent's column pitch (deriving its own column count from its measured width so cells stay parent-sized as the container is resized) and uses the parent's row height verbatim. It never shrinks rows to fit — pair it with an `isAutoHeight` container so the widget grows to fit its rows at that height. `cols`/`rowHeight` then act as fallbacks used only until the parent metrics resolve.
 - **`selectionMode`** `'none' | 'single' | 'multiple'` (default: `'none'`) — Whether widgets can be selected, and how many at a time. `'multiple'` also enables the marquee and rigid group movement.
 - **`selectedKeys`** `string[]` — Controlled selection. Keys are layout item ids (`LayoutItem.i`).
@@ -89,6 +91,7 @@ clipped by an ancestor's `overflow: hidden`.
 - **`isDraggable`** `boolean` — Disable dragging for this widget.
 - **`isResizable`** `boolean` — Disable resizing for this widget.
 - **`resizeHandles`** `ResizeHandleAxis[]` — Override the board's handles.
+- **`resizeGripPlacement`** `'inside' | 'corner'` — Override the board's grip placement.
 - **`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`.
@@ -237,7 +240,22 @@ 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).
+Show grid lines behind the widgets while dragging or resizing (or always). With
+several boards under one `Board.Provider`, `'drag'` lights up only the board the
+drag belongs to; `'any-drag'` lights up all of them.
+
+### Corner resize grip
+
+Centre the resize grip on the widget's corner with `resizeGripPlacement="corner"`,
+so it lines up with a control centred on the opposite corner.
+
+### 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.
 
 ### Card widgets
 

package/docs/components/other/NoDataIcon.md

@@ -0,0 +1,48 @@
+# NoDataIcon
+
+The empty isometric crate — the kit's "nothing here yet" illustration.
+
+It is an **illustration, not a member of the icon set**, which is why it lives in `Other/` rather than under `Content/Icons`. It is still built on `Icon`, so it sizes and accepts style props exactly like one.
+
+## When to Use
+
+- An empty table, list, or card grid — "No invoices yet", "No deployments yet"
+- A full-page empty state, paired with a short line of copy
+- Anywhere `LoadingAnimation` would sit if the same view were still loading
+
+## Sizing
+
+`size` maps onto `font-size` and drives both axes; the artwork is square.
+
+```jsx
+<NoDataIcon size="8x" />
+```
+
+Unlike a glyph icon, the drawing is full-bleed in its viewBox rather than inset in a 24×24 grid, so it is meant for illustration sizes — `size="8x"` (64px) and up. At icon sizes it will read as noticeably heavier than the glyphs around it.
+
+## Colour
+
+Not a `currentColor` glyph, so it **ignores `color`**. The three faces come from the shared isometric cube-face tokens (`#loading-face-1` … `#loading-face-3`) that [`LoadingAnimation`](../status/LoadingAnimation.md) also draws from, so an empty table and a loading table read as the same object lit the same way.
+
+That ramp is positioned by a WCAG floor against `#surface`, so each face keeps the same separation from the page in light, dark, and high contrast, and follows a re-seeded brand hue as a tint rather than as a colour. Recolouring one face and not the others would break the shading, which is why there is no prop for it.
+
+## Properties
+
+- **`size`** `Styles['fontSize']` — Icon size; drives both axes
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+### Style Properties
+
+Accepts the same style props as `Icon` — outer, base, and color style props.
+
+## Examples
+
+```jsx
+<Flow gap="1x" placeItems="center">
+  <NoDataIcon size="8x" />
+  <Paragraph>No invoices yet.</Paragraph>
+</Flow>
+```