@cube-dev/ui-kit 0.201.0 → 0.203.0

package/docs/components/data/ItemTable.md

@@ -22,6 +22,8 @@ Use `DataTable` instead when a _cell_ is the unit of interest — query results,
 - **`columns`** `CubeItemTableColumn<T>[]` — Column definitions. See below.
 - **`rowKey`** `string` (default: `'id'`) — Property used as the row key.
 - **`getRowKey`** `(row: T, index: number) => Key` — Wins over `rowKey`.
+- **`sections`** `readonly CubeItemTableSection[]` — Ordered `{ key, title }` captions for a flat list. Empty sections are omitted. Requires `getSectionKey`.
+- **`getSectionKey`** `(row: T) => Key` — Assigns every displayed record to a declared section key.
 - **`getRowChildren`** `(row: T) => readonly T[] | undefined` — Enables tree mode. `data` then contains top-level rows and children are read recursively.
 - **`treeColumnKey`** `string` — Column containing indentation and the disclosure control. Defaults to the first visible data column.
 - **`expandedKeys`** `Key[]` — Controlled expanded rows.
@@ -201,6 +203,7 @@ Customizes the root frame. Every internal part of the table is a **sub-element**
 - `TreeContent`, `TreeToggle`, `TreeValue` — indentation, disclosure/leaf placeholder, and the consumer-rendered value in the tree column
 - `SortIndicator` — the sort arrow, inside the header `Item`'s suffix
 - `Foot`, `FootRow`, `FootCell` — pinned totals
+- `SectionRow`, `SectionCell`, `SectionContent`, `SectionLabel` — full-width list section captions, separate from record hover/selection styles; labels stay visible while scrolling horizontally
 - `StateContent` — the empty / no-results / error content
 
 ```jsx
@@ -579,6 +582,28 @@ Deliberately distinct, and not interchangeable:
 
 Unselectable rows are excluded from every scope. Pressing the header checkbox while everything in scope is selected clears the **whole** selection, not just the scope — leaving keys selected on other pages behind an unchecked-looking box is how people delete things they did not mean to.
 
+### Section Headers
+
+Use `sections` to divide a flat list into labeled zones while sharing its column headers, column widths and scroll area:
+
+```jsx
+<ItemTable
+  data={items}
+  columns={columns}
+  sections={[
+    { key: 'favorites', title: 'Favorites' },
+    { key: 'other', title: 'Other items' },
+  ]}
+  getSectionKey={(item) => item.isFavorite ? 'favorites' : 'other'}
+/>
+```
+
+The array defines section order. Client sorting applies within each section; clearing the sort restores source order within each section. Search filters records, then empty sections disappear. Captions do not consume page slots or affect footer counts, selection, bulk actions, links or row actions. A section continuing onto another client page repeats its caption there. Keyboard row navigation skips captions, and virtualization measures them separately from records. Accessible captions are structural grid rows, so `aria-rowcount` and document-absolute row indices include them; pagination summaries still count records only. Sectioned records keep keys resolved from their source positions, including when `getRowKey` uses its index argument.
+
+`title` accepts a React node. Captions scroll with the list and can be customized with `styles.SectionCell` and `styles.SectionRow`. For example, `styles={{ SectionCell: { preset: 't3m' } }}` changes their typography without changing column headers or record cells.
+
+This first version applies to flat tables with client, infinite or no pagination. Infinite mode groups the currently loaded records; the caller still owns loading. Tree mode, row drag/drop and server pagination keep their existing behavior and ignore section props with a development warning. These modes need hierarchy, drop-boundary or unseen-section metadata that ordinary captions do not provide. Missing paired props, duplicate section keys or a displayed record returning an undeclared key also warn and fall back to the ordinary list, preserving all records.
+
 ### Row Links and Row Actions
 
 `rowLink` turns the row-header cell into a stretched anchor covering the whole row:

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

@@ -28,7 +28,7 @@ A combobox component that combines a text input with a dropdown list, allowing u
 - **`defaultSelectedKey`** `string` — The key of the initially selected item (uncontrolled)
 - **`allowsCustomValue`** `boolean` (default: `false`) — Whether the combo box allows custom values to be entered
 - **`shouldCommitOnBlur`** `boolean` (default: `true`) — Whether to commit custom value on blur in allowsCustomValue mode. When `false`, blur discards the uncommitted text
-- **`clearOnBlur`** `boolean` (default: `false`) — Whether to clear selection and input on blur when the text names no selectable item (only applies to non-custom-value mode)
+- **`clearOnBlur`** `boolean` (default: `false`) — Whether to clear selection and input on blur, or on `Enter` with the popover closed, when the text names no selectable item (only applies to non-custom-value mode)
 - **`isClearable`** `boolean` (default: `false`) — Whether the combo box is clearable using ESC keyboard button or clear button inside the input
 - **`sortSelectedToTop`** `boolean` (default: `true when items provided, false otherwise`) — Whether to sort selected item to the top when popover opens (only works with items prop)
 - **`popoverTrigger`** `'focus' | 'input' | 'manual'` (default: `input`) — When the list opens on its own, see **popoverTrigger** below
@@ -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, settle the typed text 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
@@ -102,6 +102,8 @@ const [selectedKey, setSelectedKey] = useState(null);
 </ComboBox>;
 ```
 
+Without `allowsCustomValue`, the built-in `Enter` on a closed popover settles text that matches an option, or names the selection, as blur does, then lets the form submit (see `Enter` under [Keyboard Navigation](#keyboard-navigation)). A handler that prevents it leaves the text unsettled until blur.
+
 **defaultInputValue** - Sets the initial input value in uncontrolled mode. This is useful when you want to display a specific text in the input field on mount without selecting any option. When both `defaultInputValue` and `defaultSelectedKey` are provided, `defaultInputValue` takes priority. The value can be changed by the user and is not enforced after initial render.
 
 **sortSelectedToTop** - When using the `items` prop (data-driven mode), the selected item will automatically appear at the top of the list when the popover opens. This is enabled by default when using `items`, but disabled when using JSX children. Set to `false` to maintain the original order.
@@ -112,7 +114,7 @@ const [selectedKey, setSelectedKey] = useState(null);
 
 **isReadOnly** - The list doesn't open, from the chevron, the arrow keys, a press in the input or focus, and neither keys nor blur change the value or the text. The clear button is hidden.
 
-**clearOnBlur** - When `true`, text that names no selectable item clears both the selection and the input when the input loses focus. When `false` (default), the input reverts to showing the current selection, and empty text still clears it. Only applies to non-custom-value mode. Useful for search-like scenarios where you want to reset after each interaction.
+**clearOnBlur** - When `true`, text that names no selectable item clears both the selection and the input when the input loses focus, or on `Enter` with the popover closed. When `false` (default), the input reverts to showing the current selection, and empty text still clears it. Only applies to non-custom-value mode. Useful for search-like scenarios where you want to reset after each interaction.
 
 **Blur** - Without `allowsCustomValue`, leaving the input selects the item the text names exactly, or else the only item it still matches, unless that item is in `disabledKeys`. The exact match follows the filter's rules for case, accents and locale. Among items sharing the label, the selected one wins, then the first enabled one. Empty text clears the selection. Other text reverts to the selection, or clears with `clearOnBlur`; a disabled item that is already selected stays selected. Blur reports only what it changes: leaving a field without editing it calls neither `onSelectionChange` nor `onInputChange`.
 
@@ -182,11 +184,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 +194,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
@@ -574,7 +574,7 @@ const [selectedKey, setSelectedKey] = useState(null);
 - `Tab` - Moves focus to/from the combobox input and closes the popover. The chevron and clear buttons are not Tab stops
 - `ArrowDown` - Opens popover (if closed) or moves focus to next option
 - `ArrowUp` - Opens popover (if closed) or moves focus to previous option
-- `Enter` - Selects the focused option and closes popover. Pressed right after typing, it picks the first match. With `allowsCustomValue` and the popover closed, commits the typed text. Ignored while an input method (IME) is composing text
+- `Enter` - Selects the focused option and closes popover. With the popover open, pressed right after typing, it picks the first match. With the popover closed and without `allowsCustomValue`, settles the typed text as leaving the input does (see **Blur**) and lets a surrounding form submit the result; text that matches no option and does not name the selection, or no text, clears the selection instead and does not submit. With `allowsCustomValue` and the popover closed, commits the typed text. Ignored while an input method (IME) is composing text
 - `Escape` - Closes popover (if open) or clears input (if clearable and popover closed); otherwise it goes on, so a surrounding dialog closes
 - `Home` - Moves focus to the first option (when popover is open)
 - `End` - Moves focus to the last option (when popover is open)
@@ -720,6 +720,8 @@ An `onKeyDown` handler runs before all of these and can skip any of them for a k
 
 This component supports all [Field properties](../../FieldProperties.md) when used within a Form. It integrates seamlessly with the form validation system and supports both controlled and uncontrolled modes.
 
+When the browser submits the form itself, as a plain `<form>` or a Form with `action` does,, `name` submits the selected key through a hidden input, not the label the input shows. With `allowsCustomValue` that is the committed text. Nothing selected submits an empty string, and a disabled ComboBox submits nothing.
+
 ### Form Example
 
 ```jsx

package/docs/components/fields/CommandTextArea.md

@@ -37,6 +37,8 @@ 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.
+- **`shape`** `'default' | 'plain'` (default: `default`) — Shape of the field box. `plain` is square with no border at rest, for a field set flush in a container that draws its edges, such as a toolbar or a panel header. Its border keeps its width and shows on focus and in a valid or invalid state, so nothing shifts
+- **`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 +69,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 +114,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

package/docs/components/fields/HueSlider.md

@@ -21,7 +21,6 @@ The HueSlider component allows users to select a hue value (0-359 degrees) from
 - **`orientation`** `'horizontal' | 'vertical'` (default: `horizontal`) — The orientation of the slider
 - **`gradation`** `string[]` — Labels to display at gradation marks along the slider track
 - **`formatOptions`** `Intl.NumberFormatOptions` — Options for formatting the displayed value label
-- **`inputWidth`** `string` — Width of the slider input area
 - **`showValueLabel`** `boolean` (default: `true`) — Whether to show the current value label
 - **`getValueLabel`** — Function to format the value label
 - **`onChange`** `function` — Callback fired when the hue value changes
@@ -40,7 +39,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:**
 
@@ -70,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`
 
 ### Modifiers
 

package/docs/components/fields/ListBox.md

@@ -105,11 +105,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/NumberInput.md

@@ -22,6 +22,7 @@ A number input component that allows users to enter numeric values and increment
 - **`icon`** `ReactElement` — Icon element rendered before the input
 - **`prefix`** — Input decoration before the main input
 - **`suffix`** — Input decoration after the main input
+- **`tooltip`** `string | TooltipProviderProps` — The input's own tooltip, opened on hover over the field box and on keyboard focus. A disabled input with a tooltip stays focusable, so the keyboard reaches it too. See [TextInput](./TextInput.md#with-a-tooltip) for the behaviour. A disabled number input with a tooltip doesn't step from the keys, the wheel or the steppers
 - **`suffixPosition`** `'before' | 'after'` (default: `before`) — Position of `suffix` relative to the stepper buttons. `before` keeps a unit next to the number (`40 px ⌃⌄`); `after` places the suffix after the steppers. The validation/loading icon always comes before both
 - **`actions`** `ReactNode` — Controls placed last, after the steppers and `suffix` whatever `suffixPosition` is
 - **`hideStepper`** `boolean` (default: `false`) — Whether to hide the stepper buttons
@@ -30,6 +31,7 @@ A number input component that allows users to enter numeric values and increment
 - **`step`** `number` — Amount to increment or decrement the value
 - **`formatOptions`** `Intl.NumberFormatOptions` — Options for formatting the displayed number value
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Input size
+- **`shape`** `'default' | 'plain'` (default: `default`) — Shape of the field box. `plain` is square with no border at rest, for a field set flush in a container that draws its edges, such as a toolbar or a panel header. Its border keeps its width and shows on focus and in a valid or invalid state, so nothing shifts
 - **`autoComplete`** `string` (default: `off`) — HTML [`autocomplete`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) token that tells the browser what to autofill (`cc-number`, `one-time-code`, …). A number field opts out of autofill by default.
 - **`isWheelDisabled`** `boolean` — Whether scrolling the mouse wheel changes the value
 - **`decrementAriaLabel`** `string` — Custom aria-label for the decrement button, in place of the translated "Decrease {label}"
@@ -51,7 +53,7 @@ A number input component that allows users to enter numeric values and increment
 - `Home` / `End` set the value to `minValue` / `maxValue`, when those are set
 - `Enter` commits the typed number, firing `onChange` when the value changed
 
-Because they run first, `e.preventDefault()` in `onKeyDown` cannot cancel them: it cancels only what the browser would do with the key, such as submitting a surrounding form on `Enter`. That makes NumberInput the exception among the fields with built-in key handling (`ComboBox`, `SearchComboBox`, `TagInput` and `CommandTextArea` run your handler first and skip their own handling for a key you prevent), and it is what makes an `Enter` handler work here: by the time it runs, the typed number is committed and any `onChange` for it has fired.
+Because they run first, `e.preventDefault()` in `onKeyDown` cannot cancel them: it cancels what the browser would do with the key, such as submitting a surrounding form on `Enter`, and keeps an `Escape` or `Tab` at the input (below). That makes NumberInput the exception among the fields with built-in key handling (`ComboBox`, `SearchComboBox`, `TagInput` and `CommandTextArea` run your handler first and skip their own handling for a key you prevent), and it is what makes an `Enter` handler work here: by the time it runs, the typed number is committed and any `onChange` for it has fired.
 
 ```jsx
 <NumberInput
@@ -64,7 +66,7 @@ Because they run first, `e.preventDefault()` in `onKeyDown` cannot cancel them:
 />
 ```
 
-The handler receives React Aria's keyboard event rather than a plain React one. Keys other than `Enter` continue to ancestors as usual; `Enter` stops at the input unless you call `e.continuePropagation()`.
+The handler receives React Aria's keyboard event rather than a plain React one. Keys other than `Enter` continue to ancestors as usual; `Enter` stops at the input unless you call `e.continuePropagation()`. As in every field, an `Escape` or `Tab` your handler prevents stays at the input, so a surrounding `Dialog` neither closes nor moves focus on it.
 
 ### Base Properties
 
@@ -78,7 +80,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:**
 
@@ -97,11 +99,8 @@ Customizes the input element itself.
 
 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
 
@@ -109,11 +108,13 @@ The `mods` prop accepts the following modifiers you can override:
 
 - **`focused`** `boolean` — Forces focus ring appearance.
 - **`disabled`** `boolean` — Forces disabled appearance.
+- **`readonly`** `boolean` — Set while `isReadOnly`: a recessed fill and a softer border, except in high contrast, and no hover state.
 - **`invalid`** `boolean` — Forces invalid state styling.
 - **`valid`** `boolean` — Forces valid state styling.
 - **`hovered`** `boolean` — Forces hover appearance.
 - **`prefix`** `boolean` — Indicates presence of prefix content.
 - **`suffix`** `boolean` — Indicates presence of suffix content.
+- **`shape`** `'default' | 'plain'` — Set from `shape`: `plain` drops the radius, and the border colour at rest.
 
 ## Variants
 
@@ -215,6 +216,8 @@ A unit sits between the number and the steppers. Pass `suffixPosition="after"` t
 
 This component supports all [Field properties](../../FieldProperties.md) when used within a Form.
 
+When the browser submits the form itself, as a plain `<form>` or a Form with `action` does,, `name` submits the number through a hidden input: `1234.5`, not the formatted `1,234.5` the input shows. An empty field submits an empty string, and a disabled NumberInput submits nothing.
+
 ## Suggested Improvements
 
 - Provide `maxValue`/`minValue` indicator with value range