@cube-dev/ui-kit 0.165.0 → 0.167.0

package/docs/Usage.md

@@ -16,7 +16,7 @@ For styling engine internals see the [Tasty documentation](./tasty/usage.md). Ta
 Tasty provides custom units that map to CSS custom properties defined on the Root component. Use these instead of raw pixel values to keep styling consistent.
 
 | Unit | CSS Variable | Example | Computed (defaults) |
-|------|-------------|---------|---------------------|
+| --- | --- | --- | --- |
 | `x` | `var(--gap)` | `2x` → `calc(var(--gap) * 2)` | 16px |
 | `r` | `var(--radius)` | `1r` → `var(--radius)` | 6px |
 | `cr` | `var(--card-radius)` | `1cr` → `var(--card-radius)` | 10px |
@@ -28,7 +28,7 @@ Tasty provides custom units that map to CSS custom properties defined on the Roo
 These CSS custom properties are defined in `src/tokens/base.ts` and applied globally.
 
 | Token | Default | Description |
-|-------|---------|-------------|
+| --- | --- | --- |
 | `$gap` | `8px` | Base spacing unit (used with `x` multiplier) |
 | `$radius` | `6px` | Base border radius (used with `r` multiplier) |
 | `$border-width` | `1px` | Base border width (used with `bw` multiplier) |
@@ -47,20 +47,20 @@ These CSS custom properties are defined in `src/tokens/base.ts` and applied glob
 
 Defined in `src/tokens/spacing.ts`. Values use the `x` unit.
 
-| Token | Value | Computed (gap=8px) |
-|-------|-------|-------------------|
-| `$space-xs` | `0.5x` | 4px |
-| `$space-sm` | `0.75x` | 6px |
-| `$space-md` | `1x` | 8px |
-| `$space-lg` | `1.5x` | 12px |
-| `$space-xl` | `2x` | 16px |
+| Token       | Value   | Computed (gap=8px) |
+| ----------- | ------- | ------------------ |
+| `$space-xs` | `0.5x`  | 4px                |
+| `$space-sm` | `0.75x` | 6px                |
+| `$space-md` | `1x`    | 8px                |
+| `$space-lg` | `1.5x`  | 12px               |
+| `$space-xl` | `2x`    | 16px               |
 
 ## Size Tokens
 
 Defined in `src/tokens/sizes.ts`. Used for component heights and icon sizes.
 
-| Token | Value |
-|-------|-------|
+| Token      | Value  |
+| ---------- | ------ |
 | `$size-xs` | `24px` |
 | `$size-sm` | `28px` |
 | `$size-md` | `32px` |
@@ -71,22 +71,22 @@ Defined in `src/tokens/sizes.ts`. Used for component heights and icon sizes.
 
 Defined in `src/tokens/shadows.ts`. Shadow colors (`#shadow-sm`, `#shadow-md`, `#shadow-lg`) are generated by Glaze and adapt automatically to dark / high-contrast schemes.
 
-| Token | Value |
-|-------|-------|
-| `$item-shadow` | `0 1bw 0.375x #shadow-sm` |
-| `$card-shadow` | `0 0.5x 2x #shadow-md` |
-| `$shadow` | `0 0.5x 2x #shadow-md` |
-| `$dialog-shadow` | `0 1x 4x #shadow-lg` |
+| Token            | Value                     |
+| ---------------- | ------------------------- |
+| `$item-shadow`   | `0 1bw 0.375x #shadow-sm` |
+| `$card-shadow`   | `0 0.5x 2x #shadow-md`    |
+| `$shadow`        | `0 0.5x 2x #shadow-md`    |
+| `$dialog-shadow` | `0 1x 4x #shadow-lg`      |
 
 ## Layout Tokens
 
 Defined in `src/tokens/layout.ts`.
 
-| Token | Value |
-|-------|-------|
+| Token                | Value    |
+| -------------------- | -------- |
 | `$max-content-width` | `1440px` |
-| `$topbar-height` | `48px` |
-| `$sidebar-width` | `200px` |
+| `$topbar-height`     | `48px`   |
+| `$sidebar-width`     | `200px`  |
 
 ## Color Tokens
 
@@ -118,7 +118,7 @@ When the attribute is absent, the scheme falls back to `@media (prefers-color-sc
 The neutral palette uses a `surface` / `surface-text` model. Each surface depth has its own AAA text color, plus a soft (AA) variant for secondary copy:
 
 | Token | Role |
-|-------|------|
+| --- | --- |
 | `#surface` | Primary background |
 | `#surface-2` | Slightly recessed background (cards, inputs) |
 | `#surface-3` | Deepest background (panels, code blocks) |
@@ -132,7 +132,7 @@ The neutral palette uses a `surface` / `surface-text` model. Each surface depth
 ### Other Neutral Tokens
 
 | Token | Role |
-|-------|------|
+| --- | --- |
 | `#border` | Default border color |
 | `#placeholder` | Input placeholder text |
 | `#focus` | Focus ring color |
@@ -144,20 +144,13 @@ The neutral palette uses a `surface` / `surface-text` model. Each surface depth
 
 ### 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.
+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:
+`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' }}>
@@ -165,16 +158,14 @@ the token to its own fill, which contrasts with its own text by construction:
 </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.
+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.):
 
 | Token (default theme; prefixed in others) | Role |
-|-------|------|
+| --- | --- |
 | `#accent-surface` | Saturated brand fill (button bg) |
 | `#accent-surface-2`, `#accent-surface-3` | Darker / more saturated variants |
 | `#accent-surface-text` | Near-white text on accent fill |
@@ -187,15 +178,15 @@ In the `default` theme these tokens are unprefixed (`#accent-surface`). In color
 
 Each colored theme (`primary`, `purple`, `success`, `danger`, `warning`, `note`) also provides its own tinted `<theme>-surface` (banner / chip background) and `<theme>-surface-text` (banner text).
 
-The hues below are the *defaults*; each is tunable at runtime (see [Theming](./Theming.md)).
+The hues below are the _defaults_; each is tunable at runtime (see [Theming](./Theming.md)).
 
-| Group | Default hue | Purpose |
-|-------|-------------|---------|
-| `#primary-*` / `#purple-*` | 280.3° | Primary actions, brand color |
-| `#success-*` | 156.9° | Success states, confirmations |
-| `#danger-*` | 23.1° | Errors, destructive actions |
-| `#warning-*` | 84.3° | Warning states, caution |
-| `#note-*` | 302.3° | Informational notes |
+| Group                      | Default hue | Purpose                       |
+| -------------------------- | ----------- | ----------------------------- |
+| `#primary-*` / `#purple-*` | 280.3°      | Primary actions, brand color  |
+| `#success-*`               | 156.9°      | Success states, confirmations |
+| `#danger-*`                | 23.1°       | Errors, destructive actions   |
+| `#warning-*`               | 84.3°       | Warning states, caution       |
+| `#note-*`                  | 302.3°      | Informational notes           |
 
 For example, a success banner uses `fill: '#success-surface'` + `color: '#success-surface-text'`, while a primary button uses `fill: '#primary-accent-surface'` + `color: '#primary-accent-surface-text'`.
 
@@ -212,7 +203,7 @@ resetPaletteConfig();
 
 Also available: `getPaletteConfig()`, `subscribePaletteConfig()`, the `usePaletteConfig()` hook, a `<Root palette={…}>` prop, `DEFAULT_PALETTE_CONFIG`, and `invalidatePaletteTokens()` for when you drive `glaze.configure(...)` yourself after mount. The palette is process-global — one palette per process, not per tree or per request.
 
-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:
+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({ accent: { hue: 210 }, scheme: 'dark' })} fill="#surface">
@@ -226,27 +217,27 @@ Full contract, caveats and a live playground: [Theming](./Theming.md).
 
 The previous token names continue to work as aliases (defined at the bottom of `src/tokens/colors.ts`). New code should prefer the Glaze tokens, but existing components do not need to be migrated:
 
-| Legacy | Resolves to |
-|-------|------------|
-| `#text` | `#surface-text-soft` |
-| `#dark` / `#dark-01` | `#surface-text` |
-| `#dark-02` | `#surface-text-soft` |
-| `#dark-03` | `#surface-text-soft-2` |
-| `#dark-04` | `#placeholder` |
-| `#dark-05` | `#border` |
-| `#minor` | `#surface-text-soft.65` |
-| `#shadow` | `#shadow-md` |
-| `#light` | `#surface-3` |
-| `#dark-bg` | `#surface-2` |
-| `#primary` / `#purple` | `#primary-accent-surface` |
-| `#primary-text` / `#purple-text` | `#primary-accent-text` |
-| `#primary-bg` / `#purple-bg` | `#primary-surface` |
-| `#primary-icon` / `#purple-icon` | `#primary-accent-icon` |
-| `#<status>` | `#<status>-accent-surface` |
-| `#<status>-text` | `#<status>-accent-text` |
-| `#<status>-bg` | `#<status>-surface` |
-| `#<status>-icon` | `#<status>-accent-icon` |
-| `#<status>-disabled` | `#disabled` |
+| Legacy                           | Resolves to                |
+| -------------------------------- | -------------------------- |
+| `#text`                          | `#surface-text-soft`       |
+| `#dark` / `#dark-01`             | `#surface-text`            |
+| `#dark-02`                       | `#surface-text-soft`       |
+| `#dark-03`                       | `#surface-text-soft-2`     |
+| `#dark-04`                       | `#placeholder`             |
+| `#dark-05`                       | `#border`                  |
+| `#minor`                         | `#surface-text-soft.65`    |
+| `#shadow`                        | `#shadow-md`               |
+| `#light`                         | `#surface-3`               |
+| `#dark-bg`                       | `#surface-2`               |
+| `#primary` / `#purple`           | `#primary-accent-surface`  |
+| `#primary-text` / `#purple-text` | `#primary-accent-text`     |
+| `#primary-bg` / `#purple-bg`     | `#primary-surface`         |
+| `#primary-icon` / `#purple-icon` | `#primary-accent-icon`     |
+| `#<status>`                      | `#<status>-accent-surface` |
+| `#<status>-text`                 | `#<status>-accent-text`    |
+| `#<status>-bg`                   | `#<status>-surface`        |
+| `#<status>-icon`                 | `#<status>-accent-icon`    |
+| `#<status>-disabled`             | `#disabled`                |
 
 `#white`, `#black`, and `#clear` are not defined in the palette — `#white` and `#black` are tasty's built-in named colors, and `#clear` is an alias for `transparent`.
 
@@ -259,74 +250,95 @@ Defined in `src/tokens/typography.ts`.
 ### Headings
 
 | Preset | Size | Line Height | Weight |
-|--------|------|-------------|--------|
-| `h1` | 36px | 44px | 600 |
-| `h2` | 24px | 32px | 600 |
-| `h3` | 20px | 28px | 600 |
-| `h4` | 18px | 24px | 600 |
-| `h5` | 16px | 22px | 600 |
-| `h6` | 14px | 20px | 600 |
+| ------ | ---- | ----------- | ------ |
+| `h1`   | 36px | 44px        | 600    |
+| `h2`   | 24px | 32px        | 600    |
+| `h3`   | 20px | 28px        | 600    |
+| `h4`   | 18px | 24px        | 600    |
+| `h5`   | 16px | 22px        | 600    |
+| `h6`   | 14px | 20px        | 600    |
 
 ### Text
 
-| Preset | Size | Line Height | Weight | Notes |
-|--------|------|-------------|--------|-------|
-| `t1` | 18px | 24px | 400 | |
-| `t2` | 16px | 22px | 400 | |
-| `t2m` | 16px | 22px | 500 | Medium weight variant |
-| `t3` | 14px | 20px | 400 | Base text size |
-| `t3m` | 14px | 20px | 500 | Medium weight variant |
-| `t4` | 12px | 18px | 500 | Small text |
-| `t4m` | 12px | 18px | 600 | Small text, semi-bold |
+| Preset | Size | Line Height | Weight | Notes                 |
+| ------ | ---- | ----------- | ------ | --------------------- |
+| `t1`   | 18px | 24px        | 400    |                       |
+| `t2`   | 16px | 22px        | 400    |                       |
+| `t2m`  | 16px | 22px        | 500    | Medium weight variant |
+| `t3`   | 14px | 20px        | 400    | Base text size        |
+| `t3m`  | 14px | 20px        | 500    | Medium weight variant |
+| `t4`   | 12px | 18px        | 500    | Small text            |
+| `t4m`  | 12px | 18px        | 600    | Small text, semi-bold |
 
 ### Paragraph
 
 Paragraph presets have slightly increased line heights compared to text presets at the same size, optimized for multi-line reading.
 
 | Preset | Size | Line Height | Weight |
-|--------|------|-------------|--------|
-| `p1` | 18px | 28px | 400 |
-| `p2` | 16px | 24px | 400 |
-| `p3` | 14px | 22px | 400 |
-| `p4` | 12px | 20px | 500 |
+| ------ | ---- | ----------- | ------ |
+| `p1`   | 18px | 28px        | 400    |
+| `p2`   | 16px | 24px        | 400    |
+| `p3`   | 14px | 22px        | 400    |
+| `p4`   | 12px | 20px        | 500    |
 
 ### Markdown / Prose
 
 Largest line heights, designed for long-form content blocks.
 
 | Preset | Size | Line Height | Weight |
-|--------|------|-------------|--------|
-| `m1` | 18px | 32px | 400 |
-| `m2` | 16px | 28px | 400 |
-| `m3` | 14px | 24px | 400 |
+| ------ | ---- | ----------- | ------ |
+| `m1`   | 18px | 32px        | 400    |
+| `m2`   | 16px | 28px        | 400    |
+| `m3`   | 14px | 24px        | 400    |
 
 ### Snippet / Monospace
 
 Sized to parallel `t2`–`t4`. Each preset sets `font-family` to `var(--font-mono)` (the design-system monospace stack from `Root`).
 
-| Preset | Size | Line Height | Weight | Notes |
-|--------|------|-------------|--------|-------|
-| `s2` | 16px | 22px | 400 | Larger code / snippet text |
-| `s3` | 14px | 20px | 400 | Default snippet size (matches Prism) |
-| `s4` | 12px | 18px | 400 | Compact code / snippet text |
+| Preset | Size | Line Height | Weight | Notes                                |
+| ------ | ---- | ----------- | ------ | ------------------------------------ |
+| `s2`   | 16px | 22px        | 400    | Larger code / snippet text           |
+| `s3`   | 14px | 20px        | 400    | Default snippet size (matches Prism) |
+| `s4`   | 12px | 18px        | 400    | Compact code / snippet text          |
 
 ### Special Presets
 
-| Preset | Description |
-|--------|-------------|
-| `c1` | 14px, weight 600, uppercase — section captions |
-| `c2` | 12px, weight 600, uppercase — small captions |
-| `tag` | 12px, weight 600 — tag/badge text |
-| `strong` | Inherits everything, applies bold weight |
-| `em` | Inherits everything, applies italic style |
-| `default` | Aliases `t3` values — the base text style |
+| Preset    | Description                                    |
+| --------- | ---------------------------------------------- |
+| `c1`      | 14px, weight 600, uppercase — section captions |
+| `c2`      | 12px, weight 600, uppercase — small captions   |
+| `tag`     | 12px, weight 600 — tag/badge text              |
+| `strong`  | Inherits everything, applies bold weight       |
+| `em`      | Inherits everything, applies italic style      |
+| `default` | Aliases `t3` values — the base text style      |
+
+## Resolving Tokens Outside CSS
+
+Some surfaces cannot take a `var(--…)` reference — a third-party iframe (Stripe Elements), a CodeMirror or Monaco theme object, a Vega spec. Those take colors, lengths and font descriptors as values, so they need the token _resolved_. `resolveTokenValue()` and its siblings read that value out of the DOM, from the element `Root` declares the tokens on, and refuse to hand back a placeholder.
+
+```ts
+import { resolvePresetValues, resolveTokenValue, resolveTokenValues } from '@cube-dev/ui-kit';
+
+resolveTokenValue('#purple'); // 'oklch(0.571 0.0971 280.3)'
+resolveTokenValue('$space-md'); // '8px'
+resolveTokenValues(['#surface', '#surface-text', '#border']); // keyed by the tokens as written
+resolvePresetValues('s3'); // { fontFamily: 'ui-monospace, …', fontSize: '14px', lineHeight: '20px', … }
+```
+
+`useTokenValue()`, `useTokenValues()` and `usePresetValues()` are the same three readers as hooks, re-resolved whenever the palette is re-seeded or the scheme / contrast tier flips. The object `useTokenValues()` returns keeps its identity while the values do, so it is safe as a dependency of the theme object built from it.
+
+So these helpers do not inspect the value. They read `$tokens-applied`, a marker the token block declares alongside the tokens, which answers the question that matters — _are the kit's tokens in effect on this element?_ Off that surface every read returns `null` (or `fallback`) and warns once in development; on it, the computed value is taken as the truth.
+
+All six take `{ element, fallback }`. Pass `element` to read a _local_ override instead of the document — a subtree carrying its own `tokens` prop (`renderColorTokens()`), or one under a `data-schema` / `data-contrast` that differs from the document's. Pass `fallback` for the value to use when a token cannot be resolved, including during SSR, where there is no DOM to read.
+
+**Why `getComputedStyle` by hand does not work.** `Root` declares the token block on `<body>`, so `<html>`, a detached node, and a tree that has not mounted `Root` yet are all outside it — and a token read from outside does not come back empty. Tasty registers `@property` rules with real `initial-value`s, so `--gap` reads `4px` there rather than the kit's `8px`, `--radius` reads `6px`, `--transition` reads `80ms`. The value looks entirely ordinary and is simply wrong. Inspecting it cannot help in the other direction either: `#clear` really is `transparent` and `$h2-letter-spacing` really is `0px`, indistinguishable from an unset property of the same type.
 
 ## Themes
 
 Component themes are set via the `theme` prop or `theme=name` modifier:
 
 | Theme | Purpose |
-|-------|---------|
+| --- | --- |
 | `default` | Standard appearance |
 | `danger` | Destructive / error actions |
 | `special` | Highlighted / promoted actions |
@@ -340,7 +352,7 @@ Component themes are set via the `theme` prop or `theme=name` modifier:
 Reusable style presets applied via the `recipe` style property. Defined in `src/components/Root.tsx`.
 
 | Recipe | Purpose |
-|--------|---------|
+| --- | --- |
 | `reset` | Zero out margin, padding, border, outline; set `box-sizing: border-box` |
 | `button` | Base button appearance: no native styling, `touch-action: manipulation` |
 | `input` | Base input appearance: no native styling, inherit color |
@@ -353,7 +365,7 @@ Reusable style presets applied via the `recipe` style property. Defined in `src/
 These are data-attribute modifiers used in component style maps (via the `mods` prop):
 
 | Modifier | Description |
-|----------|-------------|
+| --- | --- |
 | `disabled` | Disabled state |
 | `hovered` | Hover state |
 | `focused` | Focus state |
@@ -395,38 +407,17 @@ 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).
+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.
+`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
 
@@ -457,7 +448,7 @@ Returns a `CubeFormInstance` with:
 Async rule-based system. Each rule is an object with one of these properties:
 
 | Rule | Description |
-|------|-------------|
+| --- | --- |
 | `required` | Field must have a value |
 | `type` | Type check: `email`, `url`, `number`, `integer`, `date`, `hex`, etc. |
 | `pattern` | Regex pattern match |

package/docs/Utilities.md

@@ -36,7 +36,7 @@ function extractStyles(
 ### Predefined style lists
 
 | List | Contains |
-|------|----------|
+| --- | --- |
 | `BASE_STYLES` | `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition` |
 | `POSITION_STYLES` | `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position` |
 | `DIMENSION_STYLES` | `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex` |
@@ -144,7 +144,7 @@ function filterBaseProps(
 ### What passes through
 
 | Category | Examples |
-|----------|----------|
+| --- | --- |
 | DOM ids | `id` |
 | Base props | `role`, `as`, `children`, `style`, `className`, `href`, `target`, `tabIndex`, `hidden`, `disabled` |
 | ARIA attributes | `aria-label`, `aria-describedby`, etc. |

package/docs/components/CollectionItem.md

@@ -85,6 +85,7 @@ const items = [{
 ```
 
 **Always provide explicit `textValue` for:**
+
 - Icons/images without text
 - Formatted/complex content
 - Non-readable keys (UUIDs)

package/docs/components/actions/Banner.md

@@ -48,6 +48,7 @@ Supports [Base properties](../../BaseProperties.md)
 Customizes the root element of the component.
 
 **Sub-elements:**
+
 - `Label` - The main text content area
 - `Actions` - Container for action buttons
 

package/docs/components/actions/Button.md

@@ -195,13 +195,7 @@ import { IconPlus } from '@tabler/icons-react';
 </Button>;
 ```
 
-A disabled button keeps showing its tooltip. Browsers stop dispatching mouse
-events on elements carrying the native `disabled` attribute, so a button that
-has a tooltip is marked with `aria-disabled` instead and kept inert: `onPress`
-never fires and clicks (including the ones Enter and Space produce) do nothing.
-Such a button also stays in the tab order, so keyboard users can focus it and
-read the tooltip. Buttons rendered as links (`to`) are always marked this way,
-since `disabled` is not a valid attribute on an anchor.
+A disabled button keeps showing its tooltip. Browsers stop dispatching mouse events on elements carrying the native `disabled` attribute, so a button that has a tooltip is marked with `aria-disabled` instead and kept inert: `onPress` never fires and clicks (including the ones Enter and Space produce) do nothing. Such a button also stays in the tab order, so keyboard users can focus it and read the tooltip. Buttons rendered as links (`to`) are always marked this way, since `disabled` is not a valid attribute on an anchor.
 
 ### Custom Size
 
@@ -234,35 +228,21 @@ since `disabled` is not a valid attribute on an anchor.
 
 - `aria-label`, `aria-labelledby` – Accessible name.
 - `aria-pressed` – Managed automatically when `isSelected` is used.
-- `aria-disabled` – Announces the disabled state whenever the native `disabled`
-  attribute cannot be used: on links, and on buttons that carry a tooltip.
+- `aria-disabled` – Announces the disabled state whenever the native `disabled` attribute cannot be used: on links, and on buttons that carry a tooltip.
 - Additional ARIA attributes supported by React Aria's `useButton`.
 
 ## Behaviour Inside Popovers
 
-By default, pressing a `Button` inside an open popover (any overlay that
-uses `usePopoverSync` — including the popovers rendered by `FilterPicker`,
-`Picker`, `ComboBox`, `Select`, `MenuTrigger`, and
-`DialogTrigger type="popover"`) **dismisses that popover** after the user's
-`onPress` runs. This matches the common UX where a popover is a transient
-surface: any action inside it should close it.
+By default, pressing a `Button` inside an open popover (any overlay that uses `usePopoverSync` — including the popovers rendered by `FilterPicker`, `Picker`, `ComboBox`, `Select`, `MenuTrigger`, and `DialogTrigger type="popover"`) **dismisses that popover** after the user's `onPress` runs. This matches the common UX where a popover is a transient surface: any action inside it should close it.
 
-Modal / tray / fullscreen Dialogs are **not** affected — a Button inside a
-modal Dialog does not auto-close it.
+Modal / tray / fullscreen Dialogs are **not** affected — a Button inside a modal Dialog does not auto-close it.
 
 ### Opt-outs
 
 There are three ways to keep the popover open when a Button is pressed:
 
-1. **Automatic for popover triggers.** Buttons that act as popover triggers
-   already carry `data-popover-trigger` (applied by `MenuTrigger`,
-   `DialogTrigger type="popover"`, `FilterPicker`, `Picker`, `ComboBox`,
-   `Select`). Modal-type `DialogTrigger` children are **not** marked, so they
-   correctly dismiss the parent popover and let the modal take over.
-2. **Manual via `data-popover-keep`.** Add the attribute to the button
-   (toggle case) or to any ancestor element (subtree case — useful when a
-   custom inline editor inside a popover footer should not collapse on
-   every interaction):
+1. **Automatic for popover triggers.** Buttons that act as popover triggers already carry `data-popover-trigger` (applied by `MenuTrigger`, `DialogTrigger type="popover"`, `FilterPicker`, `Picker`, `ComboBox`, `Select`). Modal-type `DialogTrigger` children are **not** marked, so they correctly dismiss the parent popover and let the modal take over.
+2. **Manual via `data-popover-keep`.** Add the attribute to the button (toggle case) or to any ancestor element (subtree case — useful when a custom inline editor inside a popover footer should not collapse on every interaction):
 
    ```jsx
    <Button data-popover-keep onPress={() => setMode((m) => !m)}>
@@ -274,9 +254,7 @@ There are three ways to keep the popover open when a Button is pressed:
    </div>
    ```
 
-3. **Custom non-Cube triggers.** Call `useDismissParentPopover()` yourself if
-   your control should dismiss the popover but does not extend `Button` /
-   `ItemButton`:
+3. **Custom non-Cube triggers.** Call `useDismissParentPopover()` yourself if your control should dismiss the popover but does not extend `Button` / `ItemButton`:
    ```jsx
    const dismiss = useDismissParentPopover();
    <MyCustomPressable
@@ -289,13 +267,7 @@ There are three ways to keep the popover open when a Button is pressed:
 
 ### Async `onPress`
 
-The dismiss is dispatched via the EventBus, which defers with `setTimeout(0)`.
-This means synchronous `onPress` handlers (and any React state updates they
-trigger) flush **before** the popover closes — including the common case of
-opening a hoisted modal via `useDialogContainer` from a popover footer (the
-modal mounts first, then the popover closes behind it). If your `onPress` is
-async and `await`s before opening another overlay, the popover will close
-first and the new overlay will appear after — usually fine, but worth noting.
+The dismiss is dispatched via the EventBus, which defers with `setTimeout(0)`. This means synchronous `onPress` handlers (and any React state updates they trigger) flush **before** the popover closes — including the common case of opening a hoisted modal via `useDialogContainer` from a popover footer (the modal mounts first, then the popover closes behind it). If your `onPress` is async and `await`s before opening another overlay, the popover will close first and the new overlay will appear after — usually fine, but worth noting.
 
 ## Best Practices
 

package/docs/components/actions/ButtonSplit.md

@@ -180,11 +180,13 @@ Use `actionProps`, `triggerProps`, and `menuProps` to customise individual parts
 ## Best Practices
 
 1. **Do**: Use strict mode for standard action+trigger patterns.
+
    ```jsx
    <Button.Split actions={actions} defaultActionKey="deploy" type="primary" />
    ```
 
 2. **Do**: Set `type` and `theme` on the wrapper instead of repeating on each child.
+
    ```jsx
    <Button.Split type="primary">
      <Button>Save</Button>

package/docs/components/actions/CommandMenu.md

@@ -129,8 +129,8 @@ For detailed information about all available item properties, see the [Menu.Item
 
 ```jsx
 <CommandMenu searchPlaceholder="Search commands...">
-  <CommandMenu.Item 
-    key="save" 
+  <CommandMenu.Item
+    key="save"
     icon={<IconSave />}
     hotkeys="cmd+s"
     keywords={["write", "disk", "persist"]}
@@ -138,8 +138,8 @@ For detailed information about all available item properties, see the [Menu.Item
   >
     Save Document
   </CommandMenu.Item>
-  <CommandMenu.Item 
-    key="help" 
+  <CommandMenu.Item
+    key="help"
     icon={<IconHelp />}
     forceMount={true}
     description="Always visible help option"
@@ -358,10 +358,10 @@ function CommandMenuDialogContent({ onClose, ...args }) {
 
   return (
     <Dialog size="medium" isDismissable={false}>
-      <CommandMenu 
-        width="100%" 
-        height="max(40x, 90vh)" 
-        size="medium" 
+      <CommandMenu
+        width="100%"
+        height="max(40x, 90vh)"
+        size="medium"
         onAction={handleAction}
         {...args}
       >