@cube-dev/ui-kit 0.200.1 → 0.202.0

package/docs/components/content/Divider.md

@@ -1,28 +1,44 @@
 # Divider
 
-A horizontal separator. Can be a simple line or include centered text with lines on both sides.
+A line that separates content. It is horizontal by default and vertical with `orientation="vertical"`, and it can show text, such as "or", between two lines. Built on React Aria's `useSeparator`.
 
 ## When to Use
 
 - Separating sections of content
-- Dividing list items or form sections
-- "Or" or other labels between content blocks
+- Separating the items of a toolbar or an action row (vertical)
+- "Or" or another label between two blocks of content
 
-## Properties
+## Component
 
-- **`children`** `ReactNode` — Optional text to display centered between two lines
+---
 
-### Style Defaults
+### Properties
 
-- `display` — `block` (switches to `grid` when text is present)
-- `height` — `1bw` (switches to `auto` when text is present)
-- `fill` — `#border` (switches to `none` when text is present)
-- `preset` — `c1`
-- `gridArea` — `divider`
+- **`children`** `ReactNode` — Text shown between two lines. It also names the separator for screen readers, unless `aria-label` or `aria-labelledby` names it. Screen readers get it only as that name, so keep it to text: a link or button in it would be unreachable.
+- **`orientation`** `'horizontal' | 'vertical'` (default: `'horizontal'`) — The direction of the line. A vertical divider stretches to the height of its flex or grid row, even when the row centers its items. Elsewhere, or to make it shorter, give it a `height`.
 
 ### Base Properties
 
-Supports [Base properties](../../BaseProperties.md).
+Supports [Base properties](../../BaseProperties.md). A divider's `qa` defaults to `Divider`.
+
+### Styling Properties
+
+#### styles
+
+Customizes the root element. Without text, the root is the line itself.
+
+**Sub-elements:**
+
+- `Line` - Each of the two lines around the text.
+
+### Style Defaults
+
+- `fill` — `#border`; `none` with text, where the `Line` sub-elements carry the color
+- `height` — `1bw` when horizontal without text
+- `width` — `1bw` when vertical without text
+- `margin` — `0`
+- `preset` — `c1`
+- `display` — `block`; `grid` with text
 
 ### Style Properties
 
@@ -31,21 +47,87 @@ 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`, `blockMargin`, `inlineMargin`, `inset`, `blockInset`, `inlineInset`, `position`, `scrollMargin`, `blockScrollMargin`, `inlineScrollMargin`, `scrollPadding`, `blockScrollPadding`, `inlineScrollPadding`
 - **Dimension:** `width`, `height`, `blockSize`, `inlineSize`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
-- **Block:** `border`, `blockBorder`, `inlineBorder`, `radius`, `shadow`, `outline`, `padding`, `blockPadding`, `inlinePadding`, `overflow`, `scrollbar`, `textAlign`
+- **Block:** `border`, `blockBorder`, `inlineBorder`, `radius`, `shadow`, `outline`
 - **Color:** `color`, `fill`, `fade`, `image`
-- **Text:** `textTransform`, `fontWeight`, `fontStyle`
-- **Flow:** `flow`, `place`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
 
-## Examples
+### Modifiers
 
-```jsx
-<Divider />
+The `mods` property accepts the following modifiers you can override:
 
-<Divider>or</Divider>
+| Modifier | Type | Description |
+| --- | --- | --- |
+| text | `boolean` | The divider shows text between two lines |
+| vertical | `boolean` | The divider is vertical |
+| sized | `boolean` | It has a `height` or `blockSize` of its own, so a vertical divider follows the row's alignment instead of stretching |
+
+## Examples
+
+### Between sections
 
-<Flow gap="1x">
+```jsx
+<Space flow="column" gap="1x">
   <Paragraph>Section 1</Paragraph>
   <Divider />
   <Paragraph>Section 2</Paragraph>
-</Flow>
+</Space>
+```
+
+### Spacing
+
+```jsx
+<Divider margin="1x 0" />
+```
+
+### With text
+
+```jsx
+<Divider>or</Divider>
+```
+
+### Vertical, in a row of actions
+
+```jsx
+<Space placeItems="center" gap="1.5x">
+  <Button>Edit</Button>
+  <Divider orientation="vertical" />
+  <Button>Delete</Button>
+</Space>
+```
+
+A vertical divider takes the height of its row in a flex or grid container. Give it a `height` when it should be shorter, or when its container is a plain block. A divider with a height follows the row's alignment, so it stays centered in a row that centers its items. A `min max` range counts as a height too; add `alignSelf="stretch"` to stretch within it:
+
+```jsx
+<Space placeItems="center" gap="1.5x">
+  <Button>Edit</Button>
+  <Divider orientation="vertical" height="3x" />
+  <Button>Delete</Button>
+</Space>
 ```
+
+A vertical divider with text needs a row about `8x` tall or more. In a shorter row the lines shrink to nothing and only the text is left.
+
+## Accessibility
+
+### Screen Reader Support
+
+- A horizontal divider without text is an `<hr>`, which screen readers announce as a separator.
+- A vertical divider, or one with text, is a `div` with `role="separator"`. A vertical one carries `aria-orientation="vertical"`.
+- ARIA treats a separator's content as presentational, so a text divider is named by its text through `aria-labelledby`: its accessible name is its text, and the text is hidden from screen readers so it is not read a second time. An `aria-label` or `aria-labelledby` you pass replaces that name.
+
+## Best Practices
+
+1. **Do**: put spacing on the divider or its container
+
+   ```jsx
+   <Divider margin="2x 0" />
+   ```
+
+2. **Don't**: draw a separator with a bordered empty element; it is invisible to screen readers
+
+   ```jsx
+   <Block styles={{ border: 'top' }} />
+   ```
+
+## Related Components
+
+- [Space](../layout/Space.md) - Lays out the content a divider separates

package/docs/components/content/Tree.md

@@ -25,8 +25,8 @@ The component's data shape (`treeData`) and the public callback shape are design
 - **`defaultExpandedKeys`** `string[]` — Default expanded keys (uncontrolled).
 - **`expandedKeys`** `string[]` — Controlled expanded keys.
 - **`autoExpandParent`** `boolean` (default: `false`) — Auto-expand parents of currently expanded keys. Useful for filtering.
-- **`defaultCheckedKeys`** `string[]` — Default checked keys (uncontrolled).
-- **`checkedKeys`** `string[] | { checked: string[]; halfChecked?: string[] }` — Controlled checked keys. Pass the object form to receive the same shape back from `onCheck`.
+- **`defaultCheckedKeys`** `string[]` — Default checked keys (uncontrolled). A parent key checks its whole subtree, as in AntD.
+- **`checkedKeys`** `string[] | { checked: string[]; halfChecked?: string[] }` — Controlled checked keys. In the array form, a parent key checks its whole subtree, as in AntD. Pass the object form to receive the same shape back from `onCheck`; it is taken as given.
 - **`defaultSelectedKeys`** `string[]` — Default selected keys (uncontrolled).
 - **`selectedKeys`** `string[]` — Controlled selected keys.
 - **`height`** `number` — Fixed height in pixels. When omitted, the tree fills the available vertical space and scrolls internally.
@@ -53,6 +53,7 @@ The component's data shape (`treeData`) and the public callback shape are design
 
 - **`key`** `string` — Unique identifier of the node.
 - **`title`** `ReactNode` — Visible label.
+- **`textValue`** `string` — Plain-text label, for a `title` that is not a string. It names the row's checkbox and is what `FilterPicker`'s tree mode searches and summarises.
 - **`children`** `CubeTreeNodeData[]` — Children. Pass `undefined` together with `isLeaf={false}` for lazy nodes.
 - **`isLeaf`** `boolean` — Force leaf rendering (no expand toggle, no `loadData` call).
 - **`isDisabled`** `boolean` — Disable interactions on this row (focus / select / expand / check).
@@ -200,7 +201,7 @@ Pass the matching keys via `expandedKeys` and set `autoExpandParent` to keep the
 
 ### Per-node Disabling
 
-Disable the entire row, just the checkbox, or hide the checkbox via node-level flags.
+Disable the entire row, just the checkbox, or hide the checkbox via node-level flags. Such a node with no eligible nodes below it keeps its own checked state. Above eligible nodes, its state follows them, and the cascade passes through it: checking its parent checks the eligible nodes below it.
 
 ```jsx
 const data = [
@@ -268,7 +269,7 @@ Tree implements the [`treegrid` ARIA pattern](https://www.w3.org/WAI/ARIA/apg/pa
 ### Screen Reader Support
 
 - Each row reports `aria-level`, `aria-posinset` and `aria-setsize`. Expandable rows also report `aria-expanded`, including a lazy row (`isLeaf: false`) whose children have not loaded yet.
-- When `isCheckable` is enabled, the row carries `aria-checked` (`true`, `false`, or `mixed` for the indeterminate state).
+- When `isCheckable` is enabled, each row's checkbox carries the checked state (`checked`, `not checked`, or `mixed` for the indeterminate state), named by the node's `textValue` or string `title`. The row itself takes no `aria-checked`, which `row` does not support; it has `data-checked` and `data-indeterminate` for tests.
 - Disabled rows expose `aria-disabled="true"`.
 
 ### ARIA Properties

package/docs/components/data/ItemTable.md

@@ -212,7 +212,7 @@ const Compact = tasty(ItemTable, {
 });
 ```
 
-Rows publish their paint as inherited custom properties — `#row-base`, `#row-overlay`, `#row-text` and `$dim` — which cells consume. That is what lets a pinned (and therefore opaque) cell match its row's state without duplicating the state matrix.
+Rows publish their paint as inherited custom properties — `#row-base`, `#row-overlay`, `$row-overlay-weight`, `#row-text` and `$dim` — which cells consume. `#row-overlay` is an opaque color that cells mix into `#row-base` at `$row-overlay-weight` (a percentage), so each cell paints one solid background color. That is what lets a pinned (and therefore opaque) cell match its row's state without duplicating the state matrix.
 
 Geometry runs through tokens too: `$row-height`, `$header-height`, `$cell-padding-x` (16px) and `$cell-padding-y`. Height lives on the **cells**, not the `<tr>` — table layout ignores `min-height` on a row and sizes it from its cells instead.
 
@@ -591,12 +591,18 @@ Unselectable rows are excluded from every scope. Pressing the header checkbox wh
 />
 ```
 
+When no visible column is marked `isRowHeader`, a table with `rowLink` uses its first visible data column eligible for the row header. Set `isRowHeader={false}` on a column to exclude it from that default. Selection and action columns do not affect the choice. If no data column is eligible, the table renders no row links.
+
 Because it is a real `<a href>`, ⌘-click, middle-click and "Open in new tab" all work natively — none of which an `onClick` handler can give you. The anchor sits below the cells' own content in the stacking order, so a button or `⋮` trigger inside a cell still takes its own clicks, and its accessible name comes from the row-header cell rather than being announced as "link".
 
 The row-header cell is styled as a link — `#purple-text` at weight 600, matching the kit's `Link`, with an underline while the row is hovered. The anchor itself is invisible, so without that the row would give no sign that it navigates.
 
 `onRowAction` is the non-navigational alternative — Enter, or a click that did not land on a control inside a cell. Use one or the other, not both.
 
+Flat tables with row links, row actions or exposed row menus have a resting body-row tab stop. Up/Down move between interactive rows, Home/End move to the first/last, and Enter activates the focused row's link or action. Down from a focused column header enters the body. Disabled rows are skipped; making a row unselectable only disables its checkbox. In-cell controls keep their own keys and Tab behavior. Reorderable rows retain their drag shortcuts.
+
+Keyboard focus emphasizes the row background, including selected rows, matching the kit's list items. Controls inside a row keep their own focus appearance.
+
 ### Row Menu
 
 `rowMenu` supplies `Menu.Item` children, and `rowContextMenu` decides where they are exposed. The split is deliberate: `rowMenu` alone renders nothing, so a row never grows a `⋮` nobody asked for.
@@ -624,6 +630,8 @@ The row-header cell is styled as a link — `#purple-text` at weight 600, matchi
 
 A row whose resolver returns `null` gets no trigger, and right-clicking it falls through to the browser's own context menu — more useful than an empty popover.
 
+From a focused flat row, Tab reaches its visible `⋮` trigger; Shift+F10 opens its context menu, including in `'context-only'` mode. Closing restores the opening row or control, or a surviving neighbor if the row was removed. A menu action that focuses another control keeps that focus.
+
 ### Bulk Actions
 
 `bulkActions` implies `selectionMode="multiple"` — a bulk action with no way to select rows is a contradiction, not a configuration.

package/docs/components/fields/Checkbox.md

@@ -24,7 +24,7 @@ Checkboxes allow users to select multiple items from a list of individual items,
 - **`onChange`** `function` — Callback fired when the checkbox value changes
 - **`onFocus`** `function` — Callback fired when the checkbox receives focus
 - **`onBlur`** `function` — Callback fired when the checkbox loses focus
-- **`tooltip`** `string | TooltipProviderProps` — Tooltip shown on hover over the box and its inline label, in or out of a group, including while disabled. A string, or `TooltipProvider` props such as `title` and `placement`. It also opens when the checkbox takes keyboard focus, and describes its input to screen readers. The info badge next to a field label is `labelTooltip`
+- **`tooltip`** `string | TooltipProviderProps` — Tooltip shown on hover over the box and its inline label, in or out of a group, including while disabled. A string, or `TooltipProvider` props such as `title` and `placement`. It also opens when the checkbox takes keyboard focus, and describes its input to screen readers. A disabled checkbox with a tooltip stays in the Tab order, marked `aria-disabled` rather than natively disabled, so the keyboard reaches the tooltip too, and a plain `<form>` submits it when it is checked. The info badge next to a field label is `labelTooltip`
 
 ### Base Properties
 
@@ -50,12 +50,8 @@ Customizes the checkbox input element specifically.
 
 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`, `blockMargin`, `inlineMargin`, `inset`, `blockInset`, `inlineInset`, `position`, `scrollMargin`, `blockScrollMargin`, `inlineScrollMargin`, `scrollPadding`, `blockScrollPadding`, `inlineScrollPadding`
 - **Dimension:** `width`, `height`, `blockSize`, `inlineSize`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
-- **Block:** `border`, `blockBorder`, `inlineBorder`, `radius`, `shadow`, `outline`, `padding`, `blockPadding`, `inlinePadding`, `overflow`, `scrollbar`, `textAlign`
-- **Color:** `color`, `fill`, `fade`, `image`
-- **Flow:** `flow`, `place`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
 
 ### Modifiers
 
@@ -66,6 +62,7 @@ The `mods` property accepts the following modifiers you can override:
 - **`invalid`** `boolean` — Whether the checkbox has validation errors
 - **`valid`** `boolean` — Whether the checkbox is valid
 - **`disabled`** `boolean` — Whether the checkbox is disabled
+- **`readonly`** `boolean` — Whether the checkbox is read-only, on its own or through its group: a recessed box with a dark check instead of the brand fill, and no hover state
 - **`hovered`** `boolean` — Whether the checkbox is being hovered
 - **`focused`** `boolean` — Whether the checkbox has focus
 - **`side-label`** `boolean` — Whether the label is positioned to the side
@@ -105,7 +102,7 @@ The `mods` property accepts the following modifiers you can override:
 
 ### With a Tooltip
 
-A disabled checkbox still shows its tooltip, which makes it a good place to say why the option is unavailable.
+A disabled checkbox still shows its tooltip, which makes it a good place to say why the option is unavailable. While it has a tooltip, it stays focusable and is marked `aria-disabled` instead of natively disabled, so keyboard users can read the reason too; `Space` and clicks still change nothing. Without a tooltip, a disabled checkbox is natively disabled and `Tab` skips it.
 
 ```jsx
 <Checkbox isDisabled tooltip="Available on the Team plan">
@@ -113,6 +110,8 @@ A disabled checkbox still shows its tooltip, which makes it a good place to say
 </Checkbox>
 ```
 
+Prefer `tooltip` to wrapping the checkbox in `TooltipProvider`: while disabled, a checkbox takes no trigger props from a wrapper, so that tooltip never opens.
+
 ### With Validation
 
 ```jsx
@@ -139,9 +138,9 @@ A disabled checkbox still shows its tooltip, which makes it a good place to say
 
 ### Keyboard Navigation
 
-- `Tab` - Moves focus to the checkbox
+- `Tab` - Moves focus to the checkbox. A disabled checkbox takes focus only while it has a `tooltip`, which then opens
 - `Space` - Toggles the checkbox state
-- `Enter` does not toggle the checkbox. Inside a form with a submit button, the browser submits the form instead.
+- `Enter` does not toggle the checkbox. Inside a form with a submit button, the browser submits the form instead, unless the checkbox is disabled.
 
 ### Screen Reader Support
 

package/docs/components/fields/ColorInput.md

@@ -78,25 +78,23 @@ Customizes the color swatch shown inside the input.
 
 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`, `blockMargin`, `inlineMargin`, `inset`, `blockInset`, `inlineInset`, `position`, `scrollMargin`, `blockScrollMargin`, `inlineScrollMargin`, `scrollPadding`, `blockScrollPadding`, `inlineScrollPadding`
 - **Dimension:** `width`, `height`, `blockSize`, `inlineSize`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
-- **Block:** `border`, `blockBorder`, `inlineBorder`, `radius`, `shadow`, `outline`, `padding`, `blockPadding`, `inlinePadding`, `overflow`, `scrollbar`, `textAlign`
-- **Color:** `color`, `fill`, `fade`, `image`
 
 ### Modifiers
 
 The `mods` property accepts the following modifiers you can override:
 
-| Modifier   | Type      | Description                        |
-| ---------- | --------- | ---------------------------------- |
-| `focused`  | `boolean` | The text input has focus           |
-| `hovered`  | `boolean` | The pointer is over the input      |
-| `disabled` | `boolean` | The picker is disabled             |
-| `valid`    | `boolean` | The field is in the valid state    |
-| `invalid`  | `boolean` | The field is in the invalid state  |
-| `prefix`   | `boolean` | A prefix (the swatch) is rendered  |
-| `suffix`   | `boolean` | A suffix (the trigger) is rendered |
+| Modifier | Type | Description |
+| --- | --- | --- |
+| `focused` | `boolean` | The text input has focus |
+| `hovered` | `boolean` | The pointer is over the input |
+| `disabled` | `boolean` | The picker is disabled |
+| `readonly` | `boolean` | The picker is read-only: a recessed fill and a softer border, except in high contrast, no hover state |
+| `valid` | `boolean` | The field is in the valid state |
+| `invalid` | `boolean` | The field is in the invalid state |
+| `prefix` | `boolean` | A prefix (the swatch) is rendered |
+| `suffix` | `boolean` | A suffix (the trigger) is rendered |
 
 The swatch carries its own `empty` modifier while there is no color to show.
 
@@ -196,7 +194,7 @@ const [color, setColor] = useState('okhst(264 80% 60%)');
 - `Tab` — moves focus to the text input, then to the popover trigger
 - `Enter` — commits and normalizes the typed color without leaving the field
 - `Space` / `Enter` on the trigger — opens the popover
-- `Escape` — closes the popover
+- `Escape` — closes the popover. In the text input it closes a surrounding `Dialog`, as in other fields
 - `Left` / `Right`, `Home` / `End` on a channel slider — moves that channel
 - `Left` / `Right` on the space switcher — moves between HST, LCH and RGB
 

package/docs/components/fields/ColorPicker.md

@@ -28,7 +28,8 @@ Use [ColorInput](./ColorInput.md) instead when the color has to be readable and
 - **`type`** `CubeItemProps['type']` (default: `outline`) — Visual type of the trigger
 - **`theme`** `CubeItemProps['theme']` (default: `default`) — Theme of the trigger
 - **`size`** `CubeItemProps['size']` — Size of the trigger
-- **`triggerTooltip`** `CubeItemProps['tooltip']` — Tooltip for the trigger, separate from `labelTooltip`
+- **`tooltip`** `CubeItemProps['tooltip']` — Tooltip for the trigger, separate from `labelTooltip`
+- **`triggerTooltip`** `CubeItemProps['tooltip']` — _(deprecated)_ Use `tooltip`.
 - **`swatches`** `Array<string | { color: string; label?: string }>` — Colors to offer under the editor, as a [ColorSwatchGroup](./ColorSwatchGroup.md)
 - **`swatchColumns`** `number` — How many swatches per row. Defaults to a single row
 - **`isOpen`** `boolean` — Whether the popover is open (controlled)
@@ -68,7 +69,6 @@ These properties allow direct style application without using the `styles` prop:
 
 - **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `blockMargin`, `inlineMargin`, `inset`, `blockInset`, `inlineInset`, `position`, `scrollMargin`, `blockScrollMargin`, `inlineScrollMargin`, `scrollPadding`, `blockScrollPadding`, `inlineScrollPadding`
 - **Dimension:** `width`, `height`, `blockSize`, `inlineSize`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
-- **Block:** `border`, `blockBorder`, `inlineBorder`, `radius`, `shadow`, `outline`, `padding`, `blockPadding`, `inlinePadding`, `overflow`, `scrollbar`, `textAlign`
 
 ### Modifiers
 

package/docs/components/fields/ColorSwatchGroup.md

@@ -49,11 +49,10 @@ These properties allow direct style application without using the `styles` prop:
 
 - **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `blockMargin`, `inlineMargin`, `inset`, `blockInset`, `inlineInset`, `position`, `scrollMargin`, `blockScrollMargin`, `inlineScrollMargin`, `scrollPadding`, `blockScrollPadding`, `inlineScrollPadding`
 - **Dimension:** `width`, `height`, `blockSize`, `inlineSize`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
-- **Block:** `border`, `blockBorder`, `inlineBorder`, `radius`, `shadow`, `outline`, `padding`, `blockPadding`, `inlinePadding`, `overflow`, `scrollbar`, `textAlign`
 
-### Style Props on the group
+### Styling the group
 
-`ColorSwatchGroup` and `ColorPicker` both take the outer and block style props, so `radius`, `border`, `padding` and `shadow` work directly on them.
+`ColorSwatchGroup` and `ColorPicker` take only the style props above, which place and size their outer element. Give the group its `radius`, `border`, `padding` or `shadow` through `styles`.
 
 ### Modifiers
 

package/docs/components/fields/ComboBox.md

@@ -56,7 +56,7 @@ A combobox component that combines a text input with a dropdown list, allowing u
 
 #### Notable Properties
 
-**onKeyDown** - Runs before ComboBox's own key handling, listed under [Keyboard Navigation](#keyboard-navigation). Calling `e.preventDefault()` takes the key over: ComboBox skips its handling for that event, so a prevented `ArrowDown` does not open the popover or move focus, and a prevented `Enter` does not select the focused option or commit a custom value. Without `preventDefault()` the built-in handling runs as usual after your handler. The event is React Aria's keyboard event (`KeyboardEvent` from `@react-types/shared`). `Escape` and `Tab` go on to ancestors, so a surrounding `Dialog` still closes on `Escape` and keeps `Tab` inside, unless ComboBox acts on them: `Escape` that closes the list or clears the value stops at the input. Other keys stop at the input unless you call `e.continuePropagation()`.
+**onKeyDown** - Runs before ComboBox's own key handling, listed under [Keyboard Navigation](#keyboard-navigation). Calling `e.preventDefault()` takes the key over: ComboBox skips its handling for that event, so a prevented `ArrowDown` does not open the popover or move focus, and a prevented `Enter` does not select the focused option or commit a custom value. Without `preventDefault()` the built-in handling runs as usual after your handler. The event is React Aria's keyboard event (`KeyboardEvent` from `@react-types/shared`). `Escape` and `Tab` go on to ancestors, so a surrounding `Dialog` still closes on `Escape` and moves focus on `Tab`, unless ComboBox acts on them or you prevent them: `Escape` that closes the list or clears the value stops at the input, and so does an `Escape` or `Tab` you prevent. Other keys stop at the input unless you call `e.continuePropagation()`.
 
 ```jsx
 <ComboBox
@@ -182,11 +182,8 @@ Customizes section heading elements within grouped options.
 
 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`, `blockMargin`, `inlineMargin`, `inset`, `blockInset`, `inlineInset`, `position`, `scrollMargin`, `blockScrollMargin`, `inlineScrollMargin`, `scrollPadding`, `blockScrollPadding`, `inlineScrollPadding`
 - **Dimension:** `width`, `height`, `blockSize`, `inlineSize`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
-- **Block:** `border`, `blockBorder`, `inlineBorder`, `radius`, `shadow`, `outline`
-- **Color:** `color`, `fill`, `fade`, `image`
 
 ### Modifiers
 
@@ -195,6 +192,7 @@ The `mods` property accepts the following modifiers you can override:
 - **`invalid`** `boolean` — Applied when validation state is invalid
 - **`valid`** `boolean` — Applied when validation state is valid
 - **`disabled`** `boolean` — Applied when the combobox is disabled
+- **`readonly`** `boolean` — Applied when the combobox is read-only: a recessed fill and a softer border, except in high contrast
 - **`focused`** `boolean` — Applied when the input has focus
 - **`loading`** `boolean` — Applied when the combobox is in loading state
 - **`prefix`** `boolean` — Applied when prefix content is present

package/docs/components/fields/CommandTextArea.md

@@ -37,6 +37,7 @@ Choose a different component when the interaction has another outcome:
 - **`autoSize`** `boolean` (default: `false`) — Resize to fit content.
 - **`rows`** `number` (default: `3`) — Visible rows.
 - **`maxRows`** `number` (default: `10`) — Max visible rows when `autoSize` is true.
+- **`tooltip`** `string | TooltipProviderProps` — The input's own tooltip, opened on hover over the field box and on keyboard focus. It closes on the first key, so it never covers the suggestions. See [TextInput](./TextInput.md#with-a-tooltip) for the behaviour
 
 Each option's value is the **literal string to insert**. For commands, set the item's `textValue` (and `key`) to the full `/clear` — the slash is part of both the active token and the inserted value, so `/cle` becomes `/clear ` with no duplication. This decouples insertion from the trigger, so non-command autocomplete (e.g. a `@mention` resolving to `@john`) works the same way.
 
@@ -67,11 +68,8 @@ Supports all [Field properties](../../FieldProperties.md) (`label`, `name`, `isR
 
 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`, `blockMargin`, `inlineMargin`, `inset`, `blockInset`, `inlineInset`, `position`, `scrollMargin`, `blockScrollMargin`, `inlineScrollMargin`, `scrollPadding`, `blockScrollPadding`, `inlineScrollPadding`
 - **Dimension:** `width`, `height`, `blockSize`, `inlineSize`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
-- **Block:** `border`, `blockBorder`, `inlineBorder`, `radius`, `shadow`, `outline`, `padding`, `blockPadding`, `inlinePadding`, `overflow`, `scrollbar`, `textAlign`
-- **Color:** `color`, `fill`, `fade`, `image`
 
 ## Examples
 
@@ -115,8 +113,8 @@ These properties allow direct style application without using the `styles` prop:
 - `Tab` — Moves focus into / out of the textarea.
 - `ArrowUp` / `ArrowDown` — Move the highlighted option (only while the popover is open; otherwise moves the caret).
 - `Home` / `End` — Jump to the first / last option while open.
-- `Enter` / `Tab` — Insert the highlighted option while open; otherwise insert a newline / submit.
-- `Escape` — Close the popover without changing the text.
+- `Enter` / `Tab` — Insert the highlighted option while open; otherwise insert a newline / submit. A `Tab` that inserts an option keeps focus in the textarea, inside a `Dialog` too.
+- `Escape` — Close the popover without changing the text. With the popover closed, `Escape` goes on to a surrounding `Dialog` and closes it, unless your `onKeyDown` prevents it.
 
 ### Screen Reader Support
 

package/docs/components/fields/DatePicker.md

@@ -79,12 +79,8 @@ Customizes the calendar trigger button.
 
 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`, `blockMargin`, `inlineMargin`, `inset`, `blockInset`, `inlineInset`, `position`, `scrollMargin`, `blockScrollMargin`, `inlineScrollMargin`, `scrollPadding`, `blockScrollPadding`, `inlineScrollPadding`
 - **Dimension:** `width`, `height`, `blockSize`, `inlineSize`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
-- **Block:** `border`, `blockBorder`, `inlineBorder`, `radius`, `shadow`, `outline`, `padding`, `blockPadding`, `inlinePadding`, `overflow`, `scrollbar`, `textAlign`
-- **Color:** `color`, `fill`, `fade`, `image`
-- **Flow:** `flow`, `place`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
 
 ### Modifiers
 
@@ -93,6 +89,7 @@ The `mods` property accepts the following modifiers you can override:
 - **`opened`** `boolean` — Whether the calendar is open
 - **`focused`** `boolean` — Whether the input has focus
 - **`disabled`** `boolean` — Whether the date picker is disabled
+- **`readonly`** `boolean` — Whether the date picker is read-only: a recessed fill and a softer border, except in high contrast
 - **`invalid`** `boolean` — Whether the date picker has validation errors
 - **`valid`** `boolean` — Whether the date picker is valid
 - **`hovered`** `boolean` — Whether the date picker is being hovered

package/docs/components/fields/FileInput.md

@@ -38,7 +38,7 @@ Supports all [Field properties](../../FieldProperties.md)
 
 #### styles
 
-Customizes the root element of the component.
+Styles the input element. Its style props place and size the field: see [Field properties](../../FieldProperties.md).
 
 **Sub-elements:**
 
@@ -51,12 +51,8 @@ Customizes the root element of the component.
 
 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`, `blockMargin`, `inlineMargin`, `inset`, `blockInset`, `inlineInset`, `position`, `scrollMargin`, `blockScrollMargin`, `inlineScrollMargin`, `scrollPadding`, `blockScrollPadding`, `inlineScrollPadding`
 - **Dimension:** `width`, `height`, `blockSize`, `inlineSize`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
-- **Block:** `border`, `blockBorder`, `inlineBorder`, `radius`, `shadow`, `outline`, `padding`, `blockPadding`, `inlinePadding`, `overflow`, `scrollbar`, `textAlign`
-- **Color:** `color`, `fill`, `fade`, `image`
-- **Flow:** `flow`, `place`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
 
 ### Modifiers
 

package/docs/components/fields/FilterListBox.md

@@ -137,11 +137,8 @@ Customizes the footer area when footer prop is provided.
 
 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`, `blockMargin`, `inlineMargin`, `inset`, `blockInset`, `inlineInset`, `position`, `scrollMargin`, `blockScrollMargin`, `inlineScrollMargin`, `scrollPadding`, `blockScrollPadding`, `inlineScrollPadding`
 - **Dimension:** `width`, `height`, `blockSize`, `inlineSize`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
-- **Block:** `border`, `blockBorder`, `inlineBorder`, `radius`, `shadow`, `outline`
-- **Color:** `color`, `fill`, `fade`, `image`
 
 ### Modifiers
 

package/docs/components/fields/FilterPicker.md

@@ -8,6 +8,7 @@ A button-triggered field for keeping one or more selected values from a **search
 - Users need a visible search field to find options
 - A compact button trigger is preferable to an always-visible input
 - Multiple selection, checkboxes, select-all, grouped options, or a custom trigger summary are needed
+- The options form a tree, such as groups and their members, and parents should be checkable as a whole (`treeData`)
 - The selection should participate in form state and validation
 
 Choose a different component when the interaction has another shape:
@@ -57,7 +58,8 @@ Choose a different component when the interaction has another shape:
 - **`listBoxStyles`** `Styles` — Custom styles for the dropdown list container within the popover
 - **`popoverStyles`** `Styles` — Custom styles for the popover dialog that contains the FilterListBox
 - **`triggerStyles`** `Styles` — Custom styles for the trigger button element
-- **`triggerTooltip`** `string | TooltipProps` — Tooltip for the trigger button (separate from `labelTooltip`)
+- **`tooltip`** `string | TooltipProps` — Tooltip for the trigger button (separate from `labelTooltip`)
+- **`triggerTooltip`** `string | TooltipProps` — _(deprecated)_ Use `tooltip`.
 - **`triggerDescription`** `string` — Description for the trigger button (separate from field description)
 - **`prefix`** `ReactNode` — Content to show before the trigger button text
 - **`suffix`** `ReactNode` — Content to show after the trigger button text
@@ -78,6 +80,10 @@ Choose a different component when the interaction has another shape:
 - **`onClear`** `() => void` — Callback called when the clear button is pressed
 - **`actions`** `ReactNode` — Custom actions rendered inside the trigger, to the left of the built-in clear button and dropdown caret
 - **`onOpenChange`** `(isOpen: boolean) => void` — Callback called when the popover open state changes
+- **`treeData`** `CubeTreeNodeData[]` — Tree-shaped options. The popover shows a checkable `Tree` in place of the list, and `items` and `children` are not used. Tree mode is always multiple selection, and the value is every fully checked key, parents included
+- **`expandedKeys`** `string[]` — Expanded nodes in tree mode (controlled). A search expands nodes on its own and restores these when it clears
+- **`defaultExpandedKeys`** `string[]` — Initially expanded nodes in tree mode (uncontrolled), read once when the picker mounts
+- **`onExpand`** `(expandedKeys: string[]) => void` — Called when the user expands or collapses a node in tree mode, outside a search
 - **`isReorderable`** `boolean` (default: `false`) — Enable drag-and-drop item reordering in the dropdown list
 - **`onReorder`** `(newOrder: string[]) => void` — Callback when items are reordered via drag-and-drop or keyboard (Alt+Arrow)
 
@@ -155,11 +161,8 @@ Customizes the footer area when footer prop is provided.
 
 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`, `blockMargin`, `inlineMargin`, `inset`, `blockInset`, `inlineInset`, `position`, `scrollMargin`, `blockScrollMargin`, `inlineScrollMargin`, `scrollPadding`, `blockScrollPadding`, `inlineScrollPadding`
 - **Dimension:** `width`, `height`, `blockSize`, `inlineSize`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
-- **Block:** `border`, `blockBorder`, `inlineBorder`, `radius`, `shadow`, `outline`
-- **Color:** `color`, `fill`, `fade`, `image`
 
 ### Modifiers
 
@@ -268,7 +271,7 @@ For dynamic content, use the `items` prop with a render function. Virtualization
 
 ### Dynamic Sections Pattern
 
-For hierarchical data with sections, use the `items` prop with nested render functions. Each section contains a `children` array of items.
+For grouped options (sections), use the `items` prop with nested render functions. Each section contains a `children` array of items. Sections are one level of grouping; for a real tree, with parents that expand and check their children, see [Tree Options](#tree-options).
 
 ```jsx
 const categories = [
@@ -318,6 +321,8 @@ const categories = [
 - `single` - Allows selecting only one item at a time
 - `multiple` - Allows selecting multiple items
 
+With `treeData`, the picker is always `multiple`.
+
 ### Button Types
 
 - `outline` - Default outlined button style; `mods={{ selected: true }}` adds a brand-tinted fill
@@ -524,6 +529,52 @@ const DEFAULT_KEY = 'apple';
 </FilterPicker>
 ```
 
+### Tree Options
+
+Pass `treeData` to pick from a tree. The popover shows a checkable Tree under the same header, search and footer, and `items` and `children` are not used.
+
+- **Value.** Tree mode is always multiple selection. `selectedKeys` is every fully checked key, parents included, in tree order. A parent key passed without its children checks its whole subtree.
+- **Cascade.** Checking a parent checks its children, and a parent with only some of them checked is half-checked. The cascade runs over the whole tree, so unchecking a node during a search keeps the nodes the search hides as they were.
+- **Search.** A node that matches keeps its whole subtree. The ancestors of deeper matches stay with only their matching branches, and every node with a match below it opens. This expansion belongs to the search: it starts over whenever the query changes, and clearing the search brings back the nodes the user had open. Nodes match on `textValue`, else on `title` when it is a string, else on `key`.
+- **Summary.** The default trigger summary lists the topmost checked nodes: "Design" rather than "Design, Dieter Rams, Susan Kare". `renderSummary` receives every checked key, conducted over the tree and in tree order, as `onSelectionChange` reports them.
+- **Disabling.** Disable a node with its own `isDisabled` or `isCheckboxDisabled`; `disabledKeys` does not apply. A disabled node's key in the value still checks its subtree, and Enter or Space on a row whose checkbox is disabled does nothing. The cascade passes through a disabled node: checking its parent checks the enabled nodes below it, and its own state follows them.
+- **Expansion.** Uncontrolled expansion starts from `defaultExpandedKeys`, read once when the picker mounts, and is kept across opening and closing the popover. For nodes that arrive later, pass `expandedKeys`.
+- **List-only props.** These apply to the flat list and have no effect with `treeData`: `items`, `children`, `disabledKeys`, `allowsCustomValue`, `showSelectAll`, `selectAllLabel`, `isCheckable`, `disallowEmptySelection`, `sortSelectedToTop`, `isReorderable`, `onReorder`, `onOptionClick`, `focusOnHover`, `listGap`, `listStyles`, `optionStyles`, `sectionStyles` and `headingStyles`.
+
+```jsx
+const userGroups = [
+  {
+    key: 'engineering',
+    title: 'Engineering',
+    children: [
+      { key: 'engineering:ada', title: 'Ada Lovelace' },
+      { key: 'engineering:grace', title: 'Grace Hopper' },
+    ],
+  },
+  {
+    key: 'design',
+    title: 'Design',
+    children: [
+      { key: 'design:dieter', title: 'Dieter Rams' },
+      { key: 'design:susan', title: 'Susan Kare' },
+    ],
+  },
+  { key: 'contractors', title: 'Contractors', isLeaf: true },
+];
+
+<FilterPicker
+  label="User groups"
+  placeholder="Select user groups..."
+  searchPlaceholder="Search groups and members..."
+  treeData={userGroups}
+  defaultSelectedKeys={['design', 'engineering:ada']}
+  defaultExpandedKeys={['engineering']}
+  onSelectionChange={(keys) => console.log(keys)}
+/>
+```
+
+Keys must be unique across the whole tree. When one person belongs to several groups, give each occurrence its own key (`engineering:ada`, `support:ada`) and map the keys back to people in `onSelectionChange`.
+
 ### Loading Items
 
 Use `isLoadingItems` to indicate that items are currently being fetched. Unlike `isLoading`, the trigger stays enabled so users can still open the popover and interact with items that have already loaded. A loading spinner appears in the search input suffix.
@@ -606,6 +657,16 @@ const [keyOrder, setKeyOrder] = useState([
 - `Home/End` - Navigate to first/last option
 - `Alt+ArrowUp` / `Alt+ArrowDown` - Reorder the focused item (when `isReorderable`)
 
+With `treeData`, focus stays in the search input and the keys drive the active row:
+
+- `Arrow Up/Down` - Move the active row
+- `Home/End`, `Page Up/Page Down` - Move the active row to the first or last row
+- `Arrow Right` - Expands the active row, or moves to its first child when it is open. With text in the search, only when the caret is at the end
+- `Arrow Left` - Collapses the active row, or moves to its parent. With text in the search, only when the caret is at the start
+- `Space` - Toggles the active row while the search is empty; otherwise types a space
+- `Enter` - Toggles the active row and closes the popover
+- `Escape` - Clears the search, then closes the popover
+
 ### Screen Reader Support
 
 - Trigger button announces current selection state
@@ -622,6 +683,8 @@ const [keyOrder, setKeyOrder] = useState([
 - `aria-controls` - References the popover while it is open
 - `aria-describedby` - Associates help text and descriptions
 
+In tree mode, the search input is a `combobox` with `aria-haspopup="tree"`, `aria-controls` naming the tree while it has rows, and `aria-activedescendant` naming the active row. Each row reports its level, position and expansion, and its checkbox reports checked, not checked or mixed. Nothing in the tree is a tab stop, so `Tab` moves from the search to the footer.
+
 ## Best Practices
 
 1. **Do**: Provide clear, descriptive labels for the trigger