@cube-dev/ui-kit 0.0.0-canary-bef9600 → 0.0.0-canary-e3f8a1a

package/docs/components/fields/ComboBox.md

@@ -27,19 +27,19 @@ A combobox component that combines a text input with a dropdown list, allowing u
 - **`selectedKey`** `string` — The currently selected key (controlled)
 - **`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
+- **`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)
 - **`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`) — How the popover is triggered
+- **`popoverTrigger`** `'focus' | 'input' | 'manual'` (default: `input`) — When the list opens on its own, see **popoverTrigger** below
 - **`filter`** `((textValue: string, inputValue: string) => boolean) | false` — Custom filter function or false to disable filtering. If not provided, uses default contains filter
 - **`hideTrigger`** `boolean` (default: `false`) — Whether to hide the trigger button
-- **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — ComboBox size
+- **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — ComboBox size, which the options in the list share
 - **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
 - **`necessityIndicator`** `'label' | 'icon'` — How the required state should be indicated
 - **`onSelectionChange`** `(key: Key | null) => void` — Callback fired when the selected option changes
 - **`onInputChange`** `(value: string) => void` — Callback fired when the input text changes
-- **`onOpenChange`** `(isOpen: boolean) => void` — Callback fired when the popover opens or closes
+- **`onOpenChange`** `(isOpen: boolean) => void` — Callback fired when the list shows or hides. Not called on mount, nor while typed text that matches nothing keeps the list hidden
 - **`prefix`** `ReactNode` — Content rendered before the input
 - **`suffix`** `ReactNode` — Content rendered after the input
 - **`suffixPosition`** `'before' | 'after'` (default: `before`) — Position of suffix relative to validation/loading icons
@@ -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`), whose propagation stops 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 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()`.
 
 ```jsx
 <ComboBox
@@ -76,7 +76,7 @@ A combobox component that combines a text input with a dropdown list, allowing u
 </ComboBox>
 ```
 
-**Enter inside a form.** `preventDefault()` stops the browser's form submission and ComboBox's own handling together; it cannot stop just one. With `allowsCustomValue`, the popover closed and text that matches no option, the built-in `Enter` commits the typed value and lets the event through, so the surrounding form submits. A handler that prevents that `Enter` stops both: the form does not submit, and the value is not committed until the input loses focus (when `shouldCommitOnBlur` is on, the default). In earlier versions such a handler stopped only the submit, and the value was still committed on `Enter`. To keep that behavior, commit the value in your handler:
+**Enter inside a form.** `preventDefault()` stops the browser's form submission and ComboBox's own handling together; it cannot stop just one. With `allowsCustomValue` and the popover closed, the built-in `Enter` commits the typed value and lets the event through, so the surrounding form submits. A handler that prevents that `Enter` stops both: the form does not submit, and the value is not committed until the input loses focus (when `shouldCommitOnBlur` is on, the default). In earlier versions such a handler stopped only the submit, and the value was still committed on `Enter`. To keep that behavior, commit the value in your handler:
 
 ```jsx
 const [selectedKey, setSelectedKey] = useState(null);
@@ -106,21 +106,25 @@ const [selectedKey, setSelectedKey] = useState(null);
 
 **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.
 
-**allowsCustomValue** - Enables users to enter values that aren't in the predefined options list. Custom values can be committed by pressing Enter or on blur (controlled by `shouldCommitOnBlur`). **Important**: When enabled, typing in the input will clear the current selection. When disabled (default), typing only filters the options without clearing the selection.
+**allowsCustomValue** - Enables users to enter values that aren't in the predefined options list. Custom values can be committed by pressing Enter or on blur (controlled by `shouldCommitOnBlur`). With the list open, Enter picks the highlighted option; with it closed (press `Escape` first), Enter commits the typed text, even when it is part of an option's label. The text is committed trimmed, and empty or whitespace-only text clears the selection (`null`). **Important**: When enabled, typing in the input will clear the current selection. When disabled (default), typing only filters the options without clearing the selection.
 
-**shouldCommitOnBlur** - When `true` (default), custom values are committed when the input loses focus. When `false`, custom values only commit when Enter is pressed. Only applies when `allowsCustomValue` is enabled.
+**shouldCommitOnBlur** - When `true` (default), custom values are committed when the input loses focus. When `false`, only Enter or picking an option commits, and leaving the input discards the uncommitted text: the input shows the selected option's label again, so the text always agrees with the value. As typing clears the selection, that usually leaves the input empty. Only applies when `allowsCustomValue` is enabled.
+
+**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.
 
-**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`. 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** - 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`.
+
+**Presses in the input** - A press in the input opens a closed list, whether the input already had focus or not, unless `popoverTrigger` is `manual`. The list shows the options the typed text leaves, and text that matches nothing keeps it hidden, so a press that moves the caret does not change what `Enter` commits; the chevron and the arrow keys show every option instead. A press in the input while the list is open only moves the caret; the chevron still toggles the list. A click on the field label only focuses the input.
 
 **Outside presses** - While the list is open, a press on an enabled control outside it reaches the control on the first click, after the typed text settles as it does on `Tab`. The control has to be in the dialog, popover or menu the field sits in, or anywhere on the page when the field is in none; an enabled UI Kit `Button` or `ItemButton` is reached from anywhere. A press anywhere else, such as blank space, a dialog's backdrop or a control outside the field's dialog or popover, only closes the list and keeps the input focused with its text. A press on a disabled control keeps the focus and text too; the list stays open unless the control is only `aria-disabled`.
 
 **popoverTrigger** - Controls how the popover opens:
 
 - `manual` - Only opens via trigger button or arrow keys
-- `input` (default) - Opens when user types + manual triggers
-- `focus` - Opens on input focus + typing + manual triggers
+- `input` (default) - Opens when the user types or presses the input + manual triggers
+- `focus` - Opens on input focus + typing + presses + manual triggers
 
 **filter** - Custom filter function or `false` to disable filtering. By default, uses a contains-based filter. Provide a custom function `(textValue, inputValue) => boolean` to customize filtering logic.
 
@@ -208,8 +212,8 @@ The `mods` property accepts the following modifiers you can override:
 ### Popover Trigger Modes
 
 - `manual` - Only opens via trigger button or arrow keys
-- `input` - Opens when user types + manual triggers (default)
-- `focus` - Opens on input focus + typing + manual triggers
+- `input` - Opens when the user types or presses the input + manual triggers (default)
+- `focus` - Opens on input focus + typing + presses + manual triggers
 
 ### Validation States
 
@@ -366,6 +370,8 @@ const categories = [
 
 ### Loading State
 
+The input shows the selected option's label. A `selectedKey` whose option has not loaded yet shows the key until the option arrives. Once the input has shown a label for the selected key, it keeps that label while the options leave the item out, for example during a refetch or a server-side search.
+
 ```jsx
 <ComboBox isLoading label="Fruit" placeholder="Select a fruit...">
   <ComboBox.Item key="apple">Apple</ComboBox.Item>
@@ -565,11 +571,11 @@ const [selectedKey, setSelectedKey] = useState(null);
 
 ### Keyboard Navigation
 
-- `Tab` - Moves focus to/from the combobox input
+- `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
-- `Escape` - Closes popover (if open) or clears input (if clearable and popover closed)
+- `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
+- `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)
 - Typing - Filters options based on input value
@@ -588,10 +594,11 @@ An `onKeyDown` handler runs before all of these and can skip any of them for a k
 ### ARIA Properties
 
 - `role="combobox"` - Identifies the input as a combobox
-- `aria-expanded` - Indicates whether the popover is open or closed
+- `aria-expanded` - Indicates whether the list is shown
 - `aria-haspopup="listbox"` - Indicates the combobox has a listbox popup
+- `aria-autocomplete="list"` - Indicates that typing filters the options
 - `aria-controls` - References the listbox ID when popover is open
-- `aria-activedescendant` - References the currently focused option
+- `aria-activedescendant` - References the currently focused option, while it is shown
 - `aria-label` - Provides accessible label when no visible label exists
 - `aria-required` - Indicates required fields
 - `aria-invalid` - Indicates validation errors

package/docs/components/fields/FilterListBox.md

@@ -36,8 +36,8 @@ A searchable list selection component that combines a ListBox with an integrated
 - **`description`** `string` — Field description
 - **`header`** `ReactNode` — Custom header content
 - **`footer`** `ReactNode` — Custom footer content
-- **`showSelectAll`** `boolean` (default: `false`) — Whether to show "Select All" option in multiple mode
-- **`selectAllLabel`** `string` (default: `All`) — Label for the "Select All" option
+- **`showSelectAll`** `boolean` (default: `false`) — Whether to show "Select All" checkbox in multiple mode. Under a search it selects or deselects only the options shown, and selected options the search hides stay selected
+- **`selectAllLabel`** `string` (default: `Select All`) — Label for the "Select All" checkbox
 - **`searchValue`** `string` — Controlled search input value
 - **`onSearchChange`** `(value: string) => void` — Callback when search input changes
 - **`onSelectionChange`** `(keys: Key | Key[] | 'all' | null) => void` — Callback when selection changes

package/docs/components/fields/FilterPicker.md

@@ -50,8 +50,8 @@ Choose a different component when the interaction has another shape:
 - **`renderSummary`** `((args: { selectedLabels, selectedKeys, selectionMode }) => ReactNode) | false` — Custom renderer for the summary shown inside the trigger when there is a selection
 - **`isCheckable`** `boolean` (default: `false`) — Whether to show checkboxes for multiple selection mode
 - **`shouldFocusWrap`** `boolean` (default: `false`) — Whether keyboard navigation should wrap around
-- **`showSelectAll`** `boolean` (default: `false`) — Whether to show the "Select All" option in multiple selection mode
-- **`selectAllLabel`** `string` (default: `All`) — Label for the "Select All" option
+- **`showSelectAll`** `boolean` (default: `false`) — Whether to show the "Select All" checkbox in multiple selection mode. Under a search it selects or deselects only the options shown, and selected options the search hides stay selected
+- **`selectAllLabel`** `string` (default: `All`) — Label for the "Select All" checkbox
 - **`description`** `string` — Field description
 - **`message`** `string` — Help or error message
 - **`listBoxStyles`** `Styles` — Custom styles for the dropdown list container within the popover

package/docs/components/fields/ListBox.md

@@ -31,7 +31,7 @@ A versatile list selection component that allows users to select one or more ite
 - **`shape`** `'card' | 'plain' | 'popover'` (default: `card`) — Visual shape of the ListBox
 - **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
 - **`filter`** `(nodes: Iterable<Node>) => Iterable<Node>` — Filter function for the list items
-- **`emptyLabel`** `ReactNode` (default: `No items`) — Label shown when no items are available
+- **`emptyLabel`** `ReactNode` (default: `No items`) — Label shown when no items are available. The empty listbox stays in the document, described by this label
 - **`header`** `ReactNode` — Custom header content
 - **`footer`** `ReactNode` — Custom footer content
 - **`focusOnHover`** `boolean` (default: `true`) — Whether moving the pointer over an option will move DOM focus to that option
@@ -41,13 +41,13 @@ A versatile list selection component that allows users to select one or more ite
 - **`shouldFocusWrap`** `boolean` (default: `false`) — Whether keyboard navigation should wrap around
 - **`description`** `string` — Field description
 - **`message`** `string` — Help or error message
-- **`showSelectAll`** `boolean` (default: `false`) — Whether to show the "Select All" option in multiple selection mode
-- **`selectAllLabel`** `string` (default: `Select All`) — Label for the "Select All" option
+- **`showSelectAll`** `boolean` (default: `false`) — Whether to show the "Select All" checkbox in multiple selection mode
+- **`selectAllLabel`** `string` (default: `Select All`) — Label for the "Select All" checkbox
 - **`onSelectionChange`** `(keys: Key | Key[] | 'all' | null) => void` — Callback when selection changes
 - **`onEscape`** `() => void` — Callback when Escape key is pressed
 - **`onOptionClick`** `(key: Key) => void` — Callback when an option is clicked (non-checkbox area)
 - **`items`** `Iterable<T>` — Array of items for dynamic content with render function pattern
-- **`disableSelectionToggle`** `boolean` (default: `false`) — When true, clicking an already-selected item keeps it selected instead of toggling it off
+- **`disableSelectionToggle`** `boolean` (default: `false`) — When true, clicking an already-selected item keeps it selected instead of toggling it off (single selection mode)
 - **`isReorderable`** `boolean` (default: `false`) — Enable drag-and-drop item reordering. Disables virtualization when active
 - **`onReorder`** `(newOrder: string[]) => void` — Callback when items are reordered via drag-and-drop or keyboard (Alt+Arrow)
 
@@ -137,18 +137,21 @@ The `mods` property accepts the following modifiers you can override:
 
 **showSelectAll** (`boolean`, default: `false`)
 
-- When `true` in multiple selection mode, displays a "Select All" option in the header
-- The checkbox shows three states: unchecked (none selected), indeterminate (some selected), checked (all selected)
+- When `true` in multiple selection mode, displays a "Select All" checkbox above the list
+- The checkbox shows three states: unchecked (none selected), indeterminate (some selected), checked (every selectable item the list shows is selected, however it got there). Disabled items don't count
+- A press while it is not checked selects every item, reported as `'all'`. A press while it is checked takes the items the list shows out of the selection, so selected keys that are not among its items stay selected
+- Under a `filter` that hides items, it acts on the items shown: a press adds them to the selection or, once all of them are selected, removes them. Selected items the filter hides stay selected
+- It sits outside the listbox as its own Tab stop: `Tab` / `Shift+Tab` reach it and `Space` toggles it
 - Only works with `selectionMode="multiple"`
 
 **selectAllLabel** (`ReactNode`, default: `'Select All'`)
 
-- Custom label for the "Select All" option
+- Custom label for the "Select All" checkbox
 - Only used when `showSelectAll={true}`
 
 **allValueProps** (`Partial<CubeItemProps>`)
 
-- Props to customize the styling and behavior of the "Select All" option
+- Props to customize the styling and behavior of the "Select All" checkbox
 - Accepts any Item props like `styles`, `icon`, etc.
 
 **disallowEmptySelection** (`boolean`, default: `false`)
@@ -163,7 +166,7 @@ The `mods` property accepts the following modifiers you can override:
 
 **disableSelectionToggle** (`boolean`, default: `false`)
 
-- When `true`, clicking an already-selected item keeps it selected instead of toggling it off
+- When `true`, clicking an already-selected item keeps it selected instead of toggling it off, and `onSelectionChange` reports that item again. Applies in single selection mode, set or by default
 - Useful when embedding ListBox inside components like ComboBox
 
 **disabledKeys** (`Key[]`)
@@ -700,6 +703,7 @@ const [keyOrder, setKeyOrder] = useState([
 ### Keyboard Navigation
 
 - `Tab` - Moves focus to/from the ListBox. A disabled ListBox is not in the Tab order
+- `Tab` / `Shift+Tab` - Reach the "Select All" checkbox (with `showSelectAll`), which `Space` toggles
 - `Arrow Keys` - Navigate between options
 - `Space/Enter` - Select/deselect the focused option
 - `Home/End` - Move to first/last option
@@ -823,7 +827,7 @@ function Example() {
 
 ### Virtualization
 
-For large datasets, use the `items` prop with a render function. This enables automatic virtualization — only visible items are rendered in the DOM, providing smooth scrolling even with thousands of items.
+For large datasets, use the `items` prop with a render function. This enables automatic virtualization — only visible items are rendered in the DOM, providing smooth scrolling even with thousands of items. Moving focus to an option that isn't rendered (`End`, `Home`, `Page Down`, typeahead, or the selected option when the list takes focus) scrolls the list to it.
 
 ```jsx
 const items = Array.from({ length: 1000 }, (_, i) => ({

package/docs/components/fields/NumberInput.md

@@ -16,7 +16,7 @@ A number input component that allows users to enter numeric values and increment
 
 ### Properties
 
-- **`value`** `number` — The numeric value in controlled mode
+- **`value`** `number | null` — The numeric value in controlled mode. `null` clears the field and keeps it controlled
 - **`defaultValue`** `number` — The default numeric value in uncontrolled mode
 - **`placeholder`** `string` — Placeholder text when input is empty
 - **`icon`** `ReactElement` — Icon element rendered before the input
@@ -32,10 +32,11 @@ A number input component that allows users to enter numeric values and increment
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Input size
 - **`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
-- **`incrementAriaLabel`** `string` — Custom aria-label for the increment button
+- **`decrementAriaLabel`** `string` — Custom aria-label for the decrement button, in place of the translated "Decrease {label}"
+- **`incrementAriaLabel`** `string` — Custom aria-label for the increment button, in place of the translated "Increase {label}"
 - **`inputProps`** `Props` — Direct props passed to the native input element, merged over the props React Aria generates: a key you set wins, and event handlers are chained rather than replaced
-- **`wrapperProps`** `Props` — Direct props passed to the input wrapper element
+- **`wrapperProps`** `Props` — Direct props passed to the input wrapper element, merged with the `group` props React Aria puts there: event handlers are chained
+- **`validate`** `(value: number) => ValidationError | true | null | undefined` — Client-side validation. React Aria sets `aria-invalid` from the returned errors at once; the invalid style and the message follow after the user edits or leaves the field, so an empty field does not open in red. A typed number is checked once it commits, on blur or `Enter`. An explicit `errorMessage` replaces the returned message, and an explicit `isInvalid` (or a form's validation) takes over from `validate` entirely
 - **`onChange`** `function` — Callback fired when the input value changes
 - **`onBlur`** `function` — Callback fired when the input loses focus
 - **`onFocus`** `function` — Callback fired when the input receives focus
@@ -110,7 +111,7 @@ The `mods` prop accepts the following modifiers you can override:
 - **`disabled`** `boolean` — Forces disabled appearance.
 - **`invalid`** `boolean` — Forces invalid state styling.
 - **`valid`** `boolean` — Forces valid state styling.
-- **`loading`** `boolean` — Displays loading spinner.
+- **`hovered`** `boolean` — Forces hover appearance.
 - **`prefix`** `boolean` — Indicates presence of prefix content.
 - **`suffix`** `boolean` — Indicates presence of suffix content.
 
@@ -178,17 +179,16 @@ A unit sits between the number and the steppers. Pass `suffixPosition="after"` t
 
 ### Screen Reader Support
 
-- Announces role "spinbutton"
-- Announces label, description, and validation messages
-- Announces min/max/step constraints
+- Announces a text field described as "Number field", with its label, description and validation messages
+- The stepper buttons are named after the field ("Increase Quantity", "Decrease Quantity"), translated with the UI Kit locale. With a label that is not text, the name is "Increase" or "Decrease" and the label is read after it. They are not in the `Tab` order, and pressing one does not close a popover the field sits in
 - State changes like "invalid" or "required" are announced
-- Loading state is announced to screen readers
+- The loading indicator is visual only: `isLoading` is not announced
 
 ### ARIA Properties
 
 - `aria-label`, `aria-labelledby` – Accessible name for the input
 - `aria-describedby` – Links to description and error messages
-- `aria-invalid` – Managed automatically based on `isInvalid`
+- `aria-invalid` – Managed automatically based on `isInvalid` and `validate`
 - `aria-required` – Set when `isRequired` is true
 - Additional ARIA attributes supported by React Aria's `useNumberField`
 

package/docs/components/fields/PasswordInput.md

@@ -16,7 +16,7 @@ A password input is a specialized text field that masks user input to protect se
 
 ### Properties
 
-- **`value`** `string` — The password value in controlled mode
+- **`value`** `string | null` — The password value in controlled mode. `null` clears the field and keeps it controlled
 - **`defaultValue`** `string` — The default password value in uncontrolled mode
 - **`isBuffered`** `boolean` (default: `true`) — Whether typed text is held locally until the controlled `value` catches up. This is what keeps the caret in place when the value round-trips through a store that re-renders a pass late; `onChange` still fires on every keystroke. Set to `false` for a caller that must see the field snap back to its own `value` the moment it declines a keystroke.
 - **`placeholder`** `string` — Placeholder text when input is empty
@@ -26,7 +26,7 @@ A password input is a specialized text field that masks user input to protect se
 - **`suffixPosition`** `'before' | 'after'` (default: `after`) — Position of suffix relative to validation/loading icons
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Input size
 - **`autoComplete`** `string` — HTML [`autocomplete`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) token that tells the browser what to autofill (`current-password`, `new-password`, `off`, …). The lowercase `autocomplete` alias is deprecated.
-- **`inputProps`** `Props` — Direct props passed to the native input element, merged over the props React Aria generates: a key you set wins, and event handlers are chained rather than replaced
+- **`inputProps`** `Props` — Direct props passed to the native input element, merged over the props React Aria generates: a key you set wins, and event handlers are chained rather than replaced. The explicit `isDisabled`, `maxLength`, `minLength`, `autoFocus` and `autoComplete` props win over the same attributes in `inputProps` when they are set; one left unset keeps the `inputProps` value
 - **`wrapperProps`** `Props` — Direct props passed to the input wrapper element
 - **`onChange`** `function` — Callback fired when the input value changes
 - **`onBlur`** `function` — Callback fired when the input loses focus
@@ -186,8 +186,8 @@ The `mods` property accepts the following modifiers you can override:
 
 ### Keyboard Navigation
 
-- `Tab` - Moves focus to the password input
-- `Shift + Tab` - Moves focus to the toggle button
+- `Tab` - Moves focus to the password input, then to the toggle button, which comes after it
+- `Shift + Tab` - Moves focus from the toggle button back to the input
 - `Enter` - Toggles password visibility when toggle button is focused
 - `Space` - Toggles password visibility when toggle button is focused
 - All standard text input keyboard shortcuts work for text entry
@@ -195,8 +195,7 @@ The `mods` property accepts the following modifiers you can override:
 ### Screen Reader Support
 
 - Component announces as "password" input type to screen readers
-- Toggle button announces its purpose ("Toggle masking", "Show password", "Hide password")
-- Current visibility state is communicated when changed
+- The toggle is a toggle button named "Show password" (translated with the UI Kit locale). Its name stays the same, and `aria-pressed` reports whether the password is shown: "Show password, pressed" while it is visible, "Show password, not pressed" while it is masked
 - Validation errors and requirements are announced
 
 ### ARIA Properties
@@ -206,7 +205,7 @@ The `mods` property accepts the following modifiers you can override:
 - `aria-describedby` - References additional descriptive text
 - `aria-invalid` - Indicates validation state
 - `aria-required` - Indicates if password entry is required
-- Toggle button includes appropriate `aria-label` for its function
+- The toggle button has `aria-label="Show password"` and `aria-pressed`, `true` while the password is shown
 
 ## Best Practices
 

package/docs/components/fields/Picker.md

@@ -629,9 +629,9 @@ The Picker component is built with React Aria hooks and provides comprehensive a
 
 ### Screen Reader Support
 
-- Trigger button announces as "button" with current selection state
-- When empty: announces placeholder text
-- When selected: announces selected item(s) or count
+- The trigger is a button named by the field `label` (or `aria-label`), so its name does not change with the selection
+- The value the trigger shows is its description, announced after the name: the selected item(s), the `renderSummary` output, or the placeholder while empty (for example "Status, button, Open")
+- With `renderSummary={false}` the trigger shows no value, so it has no value description
 - Popover opening/closing is announced to screen readers
 - Item selection changes are announced immediately
 - Loading state announces "loading" to users
@@ -644,9 +644,10 @@ The component automatically manages ARIA attributes:
 
 - **`aria-label`** — Labels the trigger when no visible label exists
 - **`aria-labelledby`** — Associates the label with the trigger
-- **`aria-describedby`** — Associates help text and error messages
+- **`aria-describedby`** — Associates the displayed value, then help text and error messages
+- **`aria-haspopup="dialog"`** — The trigger opens a popover dialog that holds the list
 
-The following ARIA attributes are automatically managed by React Aria and do not need to be set manually: `aria-expanded`, `aria-haspopup`, `aria-invalid`, `aria-required`, `aria-disabled`.
+The trigger also sets `aria-expanded`, and `aria-controls` while the popover is open; none of these need to be set manually. A disabled Picker disables the trigger button.
 
 ### Best Practices for Accessibility
 

package/docs/components/fields/RadioGroup.md

@@ -29,7 +29,7 @@ If the control is not a field — a toolbar that swaps which view is on screen,
 ### Properties
 
 - **`children`** — Radio elements that define the available options
-- **`value`** `string` — The currently selected value (controlled)
+- **`value`** `string | null` — The currently selected value (controlled). `null` selects nothing and keeps the group controlled
 - **`defaultValue`** `string` — The default selected value (uncontrolled)
 - **`type`** `'radio' | 'button' | 'tabs'` (default: `radio`) — Visual type for all radios in the group (button/tabs default to horizontal)
 - **`orientation`** `undefined | 'vertical' | 'horizontal'` (default: `undefined`) — Orientation of the radio group. When unset it is derived from `type`: `horizontal` for `button` and `tabs`, `vertical` otherwise

package/docs/components/fields/SearchInput.md

@@ -16,7 +16,7 @@ A search input provides a specialized text field for search functionality, featu
 
 ### Properties
 
-- **`value`** `string` — The search value in controlled mode
+- **`value`** `string | null` — The search value in controlled mode. `null` clears the field and keeps it controlled
 - **`defaultValue`** `string` — The default search value in uncontrolled mode
 - **`isBuffered`** `boolean` (default: `true`) — Whether typed text is held locally until the controlled `value` catches up. This is what keeps the caret in place when the value round-trips through a store that re-renders a pass late; `onChange` still fires on every keystroke. Set to `false` for a caller that must see the field snap back to its own `value` the moment it declines a keystroke.
 - **`placeholder`** `string` — Placeholder text when input is empty
@@ -24,14 +24,15 @@ A search input provides a specialized text field for search functionality, featu
 - **`prefix`** `ReactNode` — Content rendered before the input
 - **`suffix`** — Input decoration after the main input (before clear button)
 - **`suffixPosition`** `'before' | 'after'` (default: `after`) — Position of suffix relative to validation/loading state icons
-- **`isClearable`** `boolean` (default: `false`) — Whether the search input shows a clear button
+- **`isClearable`** `boolean` (default: `false`) — Whether the search input shows a clear button while it has text. `Escape` clears the input either way
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Input size
 - **`autoComplete`** `string` — HTML [`autocomplete`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) token that tells the browser what to autofill (`off` to suppress autofill on a filter field). The lowercase `autocomplete` alias is deprecated.
 - **`inputProps`** `Props` — Direct props passed to the native input element, merged over the props React Aria generates: a key you set wins, and event handlers are chained rather than replaced
 - **`wrapperProps`** `Props` — Direct props passed to the input wrapper element
+- **`inputRef`** `RefObject<HTMLInputElement>` — Ref to the native input element. It is the same element the clear button returns focus to
 - **`onChange`** `function` — Callback fired when the search value changes
 - **`onSubmit`** `function` — Callback fired when search is submitted
-- **`onClear`** `function` — Callback fired when search is cleared
+- **`onClear`** `function` — Callback fired after the text is cleared, by the clear button or by `Escape`. Not called when there was no text to clear
 - **`onBlur`** `function` — Callback fired when the input loses focus
 - **`onFocus`** `function` — Callback fired when the input receives focus
 
@@ -179,8 +180,8 @@ const [searchValue, setSearchValue] = useState('');
 
 ### Keyboard Navigation
 
-- `Tab` - Moves focus to the search input
-- `Escape` - Clears the search input (when `isClearable` is true)
+- `Tab` - Moves focus to the search input. The clear button is skipped: it is not in the `Tab` order
+- `Escape` - Clears the search input and calls `onClear`, whether or not `isClearable` is set, as in a native search field. With the input already empty, `Escape` is left to the surrounding UI, so a `Dialog` closes on the next press
 - `Enter` - Submits search or triggers onSubmit callback
 - All standard text input keyboard shortcuts work for text entry
 
@@ -189,7 +190,7 @@ const [searchValue, setSearchValue] = useState('');
 - Component announces as "search" input type to screen readers
 - Search icon and clear button have appropriate labels
 - Current search value and results count are announced when available
-- Loading states and validation errors are communicated
+- `isInvalid` sets `aria-invalid` on the input. The loading indicator is visual only: `isLoading` is not announced
 
 ### ARIA Properties
 

package/docs/components/fields/Select.md

@@ -35,7 +35,7 @@ Choose a different component when the interaction has another shape:
 - **`suffixPosition`** `string` (default: `before`) — Position of suffix relative to validation icons
 - **`type`** `string` (default: `outline`) — Visual style variant of the select
 - **`theme`** `string` (default: `default`) — Theme variant affecting overall styling
-- **`size`** `string` (default: `medium`) — Size of the select component
+- **`size`** `string` (default: `medium`) — Size of the trigger and of the options in its list (a `small` trigger opens `medium` options)
 - **`direction`** `string` (default: `bottom`) — Preferred direction for the dropdown menu
 - **`isClearable`** `boolean` (default: `false`) — Whether the select is clearable using a clear button in the rightIcon slot
 - **`clearLabel`** `string` — Accessible name for the built-in clear button. Defaults to a localized "Clear value".
@@ -48,10 +48,10 @@ Choose a different component when the interaction has another shape:
 - **`disabledKeys`** `Iterable<Key>` — Keys of items that are disabled
 - **`children`** `ReactNode | (item: T) => ReactElement` — Static child items or render function for dynamic items
 - **`triggerRef`** `RefObject<HTMLButtonElement>` — Ref for the trigger button element
-- **`popoverRef`** `RefObject<HTMLInputElement>` — Ref for the popover overlay element
+- **`popoverRef`** `RefObject<HTMLElement | null>` — Ref for the popover overlay element
 - **`listBoxRef`** `RefObject<HTMLElement>` — Ref for the list box element
-- **`loadingIndicator`** `ReactNode` — Custom loading indicator element
-- **`hideTrigger`** `boolean` (default: `false`) — Whether to hide the trigger button
+- **`isLoading`** `boolean` — Shows a loading indicator in the trigger and fixes the value until loading ends
+- **`loadingIndicator`** `ReactNode` — Replaces the default loading icon shown while `isLoading` is set
 - **`styles`** `Styles` — Styles for the root wrapper element
 - **`inputStyles`** `Styles` — Styles for the input trigger element
 - **`listBoxStyles`** `Styles` — Styles for the dropdown list container
@@ -59,7 +59,8 @@ Choose a different component when the interaction has another shape:
 - **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
 - **`overlayStyles`** `Styles` — Styles for the dropdown overlay wrapper
 - **`triggerStyles`** `Styles` — Styles for the trigger button element
-- **`inputProps`** `Props` — Additional props for the input element
+- **`inputProps`** `Props` — Additional props for the trigger button element
+- **`autoFocus`** `boolean` — Focuses the trigger when it mounts
 - **`triggerDescription`** `ReactNode` — Description text displayed within the trigger button (different from field-level description)
 - **`descriptionPlacement`** `'inline' | 'block'` — Controls how the trigger description is positioned
 - **`hotkeys`** `string` — Keyboard shortcut that triggers the select when pressed
@@ -83,6 +84,8 @@ Choose a different component when the interaction has another shape:
 
 **onClear** - Callback fired when the clear button is pressed, allowing you to perform custom actions when the selection is cleared.
 
+**isReadOnly** and **isLoading** - The trigger stays focusable and keeps its accessible name, but the value can't change: the list doesn't open, typeahead and the arrow keys don't pick another option, and the clear button is hidden. If either one, or `isDisabled`, turns on while the list is open, the list closes.
+
 **actions** - Your own controls inside the trigger, rendered to the left of the built-in clear button and dropdown caret. Pressing one runs its handler without opening or closing the popover — including while the popover is open — so an action can do something the clear button cannot, such as restoring a default selection instead of emptying it. Use `Select.Action` so they match the trigger's size and theme. Actions follow the trigger's disabled state but not `isReadOnly`; pass `isDisabled` yourself for an action that changes the value.
 
 **tooltip** - Enables tooltip display on the trigger button. Can be:
@@ -524,15 +527,18 @@ const groups = [
 ### Keyboard Navigation
 
 - `Tab` - Moves focus to the select
-- `Space/Enter` - Opens the dropdown
-- `Arrow Down` - Opens dropdown and moves to first/next option
-- `Arrow Up` - Moves to previous option (when open)
+- `Space/Enter` - Opens the dropdown on the selected option, or the first one
+- `Arrow Down` - Opens the dropdown on the selected option, or the first one; moves to the next option when open
+- `Arrow Up` - Opens the dropdown on the last option; moves to the previous option when open
+- `Page Down/Page Up` - Moves about one visible page of options
 - `Home` - Moves to first option
 - `End` - Moves to last option
 - `Escape` - Closes dropdown without selecting
 - `Enter` - Selects focused option and closes dropdown
 - Typing - Navigates to options starting with typed character
 
+Opened with a pointer, the list focuses the selected option, or the list itself when nothing is selected. The focused option is scrolled into view as the list opens.
+
 ### Screen Reader Support
 
 - Component announces as "combobox" or "listbox" to screen readers

package/docs/components/fields/TextArea.md

@@ -37,7 +37,7 @@ These properties allow direct style application without using the `styles` prop:
 - **`autoSize`** `boolean` (default: `false`) — Whether the textarea should automatically resize based on content
 - **`maxRows`** `number` (default: `10`) — Maximum number of visible rows when `autoSize` is enabled
 - **`rows`** `number` (default: `3`) — Number of visible text rows
-- **`value`** `string` — The text value in controlled mode
+- **`value`** `string | null` — The text value in controlled mode. `null` clears the field and keeps it controlled
 - **`defaultValue`** `string` — The default text value in uncontrolled mode
 - **`isBuffered`** `boolean` (default: `true`) — Whether typed text is held locally until the controlled `value` catches up. This is what keeps the caret in place when the value round-trips through a store that re-renders a pass late; `onChange` still fires on every keystroke. Set to `false` for a caller that must see the field snap back to its own `value` the moment it declines a keystroke.
 - **`placeholder`** `string` — Placeholder text when input is empty
@@ -50,11 +50,12 @@ These properties allow direct style application without using the `styles` prop:
 - **`autoComplete`** `string` — HTML [`autocomplete`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) token that tells the browser what to autofill (`street-address`, `off`, …). The lowercase `autocomplete` alias is deprecated.
 - **`maxLength`** `number` — Maximum number of characters allowed
 - **`minLength`** `number` — Minimum number of characters required
-- **`inputProps`** `Props` — Direct HTML props passed to the inner textarea element, merged over the props React Aria generates: a key you set wins, and event handlers are chained rather than replaced
+- **`inputProps`** `Props` — Direct HTML props passed to the inner textarea element, merged over the props React Aria generates: a key you set wins, and event handlers are chained rather than replaced. The explicit `isDisabled`, `maxLength`, `minLength`, `autoFocus` and `autoComplete` props win over the same attributes in `inputProps` when they are set; one left unset keeps the `inputProps` value. Set the row count with `rows`, which always applies
 - **`wrapperProps`** `Props` — Additional HTML props passed to the input wrapper container
 - **`inputRef`** `RefObject<HTMLTextAreaElement>` — Ref to the inner textarea element
 - **`wrapperRef`** `RefObject<HTMLDivElement>` — Ref to the input wrapper container
-- **`loadingIndicator`** `ReactNode` — Custom loading indicator element
+- **`loadingIndicator`** `ReactNode` — Rendered in place of the default loading icon while `isLoading` is set
+- **`validate`** `(value: string) => ValidationError | true | null | undefined` — Client-side validation. React Aria sets `aria-invalid` from the returned errors at once; the invalid style and the message follow after the user edits or leaves the field, so an empty field does not open in red. An explicit `errorMessage` replaces the returned message, and an explicit `isInvalid` (or a form's validation) takes over from `validate` entirely
 - **`inputStyles`** `Styles` — Custom styles for the textarea element
 - **`onChange`** `function` — Callback fired when the input value changes
 - **`onBlur`** `function` — Callback fired when the input loses focus

package/docs/components/fields/TextInput.md

@@ -16,7 +16,7 @@ A text input component that allows users to input custom text entries with a key
 
 ### Properties
 
-- **`value`** `string` — The text value in controlled mode
+- **`value`** `string | null` — The text value in controlled mode. `null` clears the field and keeps it controlled
 - **`defaultValue`** `string` — The default text value in uncontrolled mode
 - **`isBuffered`** `boolean` (default: `true`) — Whether typed text is held locally until the controlled `value` catches up. This is what keeps the caret in place when the value round-trips through a store that re-renders a pass late; `onChange` still fires on every keystroke. Set to `false` for a caller that must see the field snap back to its own `value` the moment it declines a keystroke.
 - **`placeholder`** `string` — Placeholder text when input is empty
@@ -32,10 +32,11 @@ A text input component that allows users to input custom text entries with a key
 - **`autoComplete`** `string` — HTML [`autocomplete`](https://developer.mozilla.org/en-US/docs/Web/HTML/Attributes/autocomplete) token that tells the browser what to autofill (`email`, `username`, `off`, …). The lowercase `autocomplete` alias is deprecated.
 - **`maxLength`** `number` — Maximum number of characters allowed
 - **`minLength`** `number` — Minimum number of characters required
-- **`inputProps`** `Props` — Direct HTML props passed to the inner input element, merged over the props React Aria generates: a key you set wins, and event handlers are chained rather than replaced
+- **`inputProps`** `Props` — Direct HTML props passed to the inner input element, merged over the props React Aria generates: a key you set wins, and event handlers are chained rather than replaced. The explicit `isDisabled`, `maxLength`, `minLength`, `autoFocus`, `rows` and `autoComplete` props win over the same attributes in `inputProps` when they are set; one left unset keeps the `inputProps` value
 - **`inputRef`** `RefObject<HTMLInputElement | HTMLTextAreaElement>` — Ref to the inner input element
 - **`wrapperRef`** `RefObject<HTMLDivElement>` — Ref to the input wrapper container
-- **`loadingIndicator`** `ReactNode` — Custom loading indicator element
+- **`loadingIndicator`** `ReactNode` — Rendered in place of the default loading icon while `isLoading` is set
+- **`validate`** `(value: string) => ValidationError | true | null | undefined` — Client-side validation. React Aria sets `aria-invalid` from the returned errors at once; the invalid style and the message follow after the user edits or leaves the field, so an empty field does not open in red. An explicit `errorMessage` replaces the returned message, and an explicit `isInvalid` (or a form's validation) takes over from `validate` entirely
 - **`onChange`** `function` — Callback fired when the input value changes
 - **`onBlur`** `function` — Callback fired when the input loses focus
 - **`onFocus`** `function` — Callback fired when the input receives focus
@@ -110,10 +111,12 @@ These properties allow direct style application without using the `styles` prop:
 The `mods` prop accepts the following modifiers you can override:
 
 - **`focused`** `boolean` — Forces focus ring appearance.
+- **`hovered`** `boolean` — Forces hover appearance.
 - **`disabled`** `boolean` — Forces disabled appearance.
 - **`invalid`** `boolean` — Forces invalid state styling.
 - **`valid`** `boolean` — Forces valid state styling.
-- **`loading`** `boolean` — Displays loading spinner.
+- **`loadable`** `boolean` — Set when a `loadingIndicator` is given. The loading icon itself follows `isLoading`, which has no modifier.
+- **`multiline`** `boolean` — Set for a multiline input.
 - **`prefix`** `boolean` — Indicates presence of prefix content.
 - **`suffix`** `boolean` — Indicates presence of suffix content.
 
@@ -189,18 +192,22 @@ import { IconMail } from '@tabler/icons-react';
 - `Shift + Tab` – Moves focus away from the input
 - Standard text editing shortcuts (Ctrl+A, Ctrl+C, etc.)
 
+### Pointer
+
+A press anywhere inside the field's border focuses the input, including the prefix and suffix areas and their icons. Presses on interactive content there, such as a button in `suffix`, stay with that content.
+
 ### Screen Reader Support
 
 - Announces role "textbox" or "searchbox" for search inputs
 - Announces label, description, and validation messages
 - State changes like "invalid" or "required" are announced
-- Loading state is announced to screen readers
+- The loading indicator is visual only: `isLoading` is not announced, so announce a long-running check yourself if users need to hear it
 
 ### ARIA Properties
 
 - `aria-label`, `aria-labelledby` – Accessible name for the input
 - `aria-describedby` – Links to description and error messages
-- `aria-invalid` – Managed automatically based on `isInvalid`
+- `aria-invalid` – Managed automatically based on `isInvalid` and `validate`
 - `aria-required` – Set when `isRequired` is true
 - Additional ARIA attributes supported by React Aria's `useTextField`
 

package/docs/components/overlays/AlertDialog.md

@@ -12,7 +12,7 @@ A modal dialog for important messages that require user acknowledgment. Extends
 
 - **`title`** `string` — Dialog title
 - **`content`** `ReactNode` — Dialog body content
-- **`danger`** `boolean` — Applies danger styling for destructive actions
+- **`danger`** `boolean` — Marks the confirm action as destructive. It gets danger styling, and the dialog opens with focus on Cancel, or on the dialog itself when there is no Cancel, so a reflexive Enter does not run it. An explicit `autoFocus` on `actions.confirm` still puts focus there. Without `danger`, the confirm button takes focus
 - **`noActions`** `boolean` — Hide the action buttons entirely
 - **`actions`** `object` — Customize buttons:
   - `confirm` — Confirm button props or `false` to hide (default: `{ children: 'Ok', type: 'primary' }`)
@@ -66,6 +66,12 @@ These properties allow direct style application without using the `styles` prop:
 />
 ```
 
+## Accessibility
+
+- The dialog has `role="alertdialog"`. Its title is its name, and its `content` is its description (`aria-describedby`), so a screen reader reads the message when the dialog opens
+- Focus starts on the confirm button, or on Cancel (the dialog itself without one) when `danger` is set and the confirm action does not set `autoFocus`
+- Focus stays inside the dialog until it closes, then returns to the element that opened it
+
 ## Imperative API
 
 `useAlertDialogAPI()` opens an alert dialog from code, such as an event handler, with no `DialogTrigger` to render. It works anywhere under `<Root>`. A dialog belongs to the component that calls the hook and closes when that component unmounts; see [The dialog's owner](#the-dialogs-owner).