@cube-dev/ui-kit 0.195.0 → 0.196.0

package/docs/components/fields/NumberInput.md

@@ -16,13 +16,14 @@ 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
 - **`prefix`** — Input decoration before the main input
 - **`suffix`** — Input decoration after the main input
-- **`suffixPosition`** `'before' | 'after'` (default: `before`) — Position of suffix relative to validation/loading icons
+- **`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
 - **`minValue`** `number` — Minimum allowed value
 - **`maxValue`** `number` — Maximum allowed value
@@ -31,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
@@ -109,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.
 
@@ -139,6 +141,14 @@ The `mods` prop accepts the following modifiers you can override:
 <NumberInput label="Amount" hideStepper />
 ```
 
+### With a Unit Suffix
+
+A unit sits between the number and the steppers. Pass `suffixPosition="after"` to put the suffix after the steppers instead.
+
+```jsx
+<NumberInput label="Width" defaultValue={40} suffix={<Text>px</Text>} />
+```
+
 ### With Min/Max/Step
 
 ```jsx
@@ -169,17 +179,16 @@ The `mods` prop accepts the following modifiers you can override:
 
 ### 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/TagInput.md

@@ -69,7 +69,7 @@ A multi-value field. The user types a value into a single-line input and commits
 
 **tagProps** - Called per value. Return a theme, an icon or `qa` for the chip. A string `children` replaces the chip's text and also names the value in the input's description and in the "Added"/"Removed" announcements, for values whose label does not come from the options. `isDisabled: true` locks the chip: it has no remove button, the keyboard skips it, and its option cannot be unpicked. An invalid chip stays in the danger theme whatever theme it asks for.
 
-**children / items** - Options turn the input into a combobox. Typing filters them and focuses the option the typed text names, or else the first match. Enter or a click toggles the focused option, and the popover stays open so the user can pick several in a row. A picked option is added as its own key, whatever other options its text resembles. Typed text means "add": pressing Enter on an option that is already a chip refuses it as a duplicate, and unpicking it takes the arrow keys, a click, or an empty input. A picked option shows a checked box. Typed text names an option by its exact label, then by its key, anywhere in the list, before any looser match counts, so `active` finds `active` even when `Active` comes first. Enter, a delimiter, a paste and blur all go by the same rule, and the option the text names stays listed and focused even when the filter would hide it, as when a key is typed, so they always add the same option. Without `allowsCustomValue`, typed text must name an option, and a label in another case or without its accents counts too: `production` adds `Production`. On blur a query that names nothing is dropped. With `allowsCustomValue`, only an exact match counts: `paris` next to an option `Paris` is a value of its own, offered and focused as its own row and added as typed, since a case-sensitive filter treats the two apart. A press on a control outside while the popover shows (a button, a link, another field) is not taken by it: it reaches the control, so a Save button saves on the first click, with the typed text already committed. A press anywhere else, such as the backdrop of a dialog the field sits in, only closes the popover, and the dialog stays open. The typed text is offered as its own option after the matches, the same way [FilterListBox](./FilterListBox.md) does, and custom values already added are listed there too, checked and sorted, so they can be unpicked from the list as well as from their chips. One unpicked in the list stays there, unchecked, until focus leaves the field, so it can be picked back. An option in `disabledKeys` is refused however it is entered. A chip for an option shows the option's label, while the value holds its key. The label is remembered, so it survives server-side filtering (`filter={false}` with changing `items`).
+**children / items** - Options turn the input into a combobox. Typing filters them and focuses the option the typed text names, or else the first match. Enter or a click toggles the focused option, and the popover stays open so the user can pick several in a row. A picked option is added as its own key, whatever other options its text resembles. Typed text means "add": pressing Enter on an option that is already a chip refuses it as a duplicate, and unpicking it takes the arrow keys, a click, or an empty input. A picked option shows a checked box. Typed text names an option by its exact label, then by its key, anywhere in the list, before any looser match counts, so `active` finds `active` even when `Active` comes first. Enter, a delimiter, a paste and blur all go by the same rule, and the option the text names stays listed and focused even when the filter would hide it, as when a key is typed, so they always add the same option. Without `allowsCustomValue`, typed text must name an option, and a label in another case or without its accents counts too: `production` adds `Production`. On blur a query that names nothing is dropped. With `allowsCustomValue`, only an exact match counts: `paris` next to an option `Paris` is a value of its own, offered and focused as its own row and added as typed, since a case-sensitive filter treats the two apart. A press on a control outside while the popover shows (a button, a link, another field) is not taken by it: it reaches the control, so a Save button saves on the first click, with the typed text already committed. A press anywhere else, such as blank space in or the backdrop of a dialog the field sits in, or a control outside the dialog or popover it sits in, only closes the popover, keeps the typed text in the input, and leaves the dialog open. An enabled UI Kit `Button` or `ItemButton` is the exception: it is reached from anywhere. A press on a disabled control never commits the typed text. The typed text is offered as its own option after the matches, the same way [FilterListBox](./FilterListBox.md) does, and custom values already added are listed there too, checked and sorted, so they can be unpicked from the list as well as from their chips. One unpicked in the list stays there, unchecked, until focus leaves the field, so it can be picked back. An option in `disabledKeys` is refused however it is entered. A chip for an option shows the option's label, while the value holds its key. The label is remembered, so it survives server-side filtering (`filter={false}` with changing `items`).
 
 ### Base Properties
 
@@ -79,6 +79,13 @@ Supports [Base properties](../../BaseProperties.md)
 
 Supports all [Field properties](../../FieldProperties.md)
 
+A standalone TagInput renders field chrome by default, so refused values show their reason below the control and the input references that reason through `aria-describedby`, even without a visible `label`. No empty `message` prop is needed. A local rejection takes precedence over the ordinary field error until the draft is edited. With `isBare`, there is no visible message slot; rejection feedback is announced through the live region instead.
+
+```jsx
+<TagInput aria-label="Recipients" defaultValue={['ana@acme.com']} />
+<TagInput isBare aria-label="Inline recipients" defaultValue={['ana@acme.com']} />
+```
+
 ### Styling Properties
 
 #### styles

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).

package/docs/components/overlays/Dialog.md

@@ -183,16 +183,16 @@ The body is the `Content` that is a direct child of the dialog or of a direct-ch
 
 ### Screen Reader Support
 
-- Dialog announces as "dialog" or "alertdialog" based on role
-- Focus is trapped within the dialog when open
+- Dialog announces as "dialog" or "alertdialog" based on role, with its title as its name
+- An alert dialog also reads its `Content`, the message, as its description. A plain dialog reads only its title on open, so a form inside it is not read field by field; link a short description with `aria-describedby` when the title alone is not enough
+- Focus moves into the dialog when it opens: to an input marked `data-autofocus`, or to a submit or primary button, otherwise to the dialog itself. In an alert dialog this never picks a destructive (`danger`) button
+- Focus is contained within the dialog from the moment it opens, including while it animates in. A `panel` dialog does not contain focus, nor does a popover opened by a `DialogTrigger` with `isDismissable={false}`
 - Focus returns to the trigger element when dialog closes
-- Dialog title and content are properly announced
-- State changes and actions are communicated to screen readers
 
 ### ARIA Properties
 
 - `aria-labelledby` - Links dialog to its title element automatically
-- `aria-describedby` - Links dialog to its description content
+- `aria-describedby` - Set automatically only for `role="alertdialog"`, where it links the dialog to its `Content`. A plain dialog links nothing unless you pass `aria-describedby` with the id of the element that describes it. An explicit `aria-describedby` always wins
 - `aria-modal` - Not set. While a modal, fullscreen or tray dialog is open, the page behind it is `aria-hidden` instead, so a screen reader's reading cursor stays in the dialog. Lists, menus and popovers opened from the dialog render outside it and stay readable, which `aria-modal` would prevent. Popover and panel dialogs leave the page readable
 - `role` - Set to "dialog" or "alertdialog" based on content type
 

package/docs/components/overlays/DialogTrigger.md

@@ -19,13 +19,13 @@ DialogTrigger serves as a wrapper around a Dialog and its associated trigger, li
 - **`type`** `'modal' | 'popover' | 'tray' | 'fullscreen' | 'fullscreenTakeover' | 'panel'` (default: `modal`) — The type of Dialog that should be rendered
 - **`mobileType`** `'modal' | 'tray' | 'fullscreen' | 'fullscreenTakeover' | 'panel' | 'popover'` (default: same as `type`) — The Dialog type on mobile
 - **`placement`** `'top' | 'bottom' | 'left' | 'right' | 'top start' | 'top end' | 'bottom start' | 'bottom end' | 'left top' | 'left bottom' | 'right top' | 'right bottom'` — The placement of the dialog relative to its trigger
-- **`hideArrow`** `boolean` (default: `false`) — Whether a popover type Dialog's arrow should be hidden
+- **`hideArrow`** `boolean` — **Deprecated.** Has no effect: popovers render no arrow, so there is nothing to hide
 - **`mobileViewport`** `number` (default: `700`) — The screen breakpoint for the mobile type
-- **`isDismissable`** `boolean` (default: `true`) — Whether passive dismissal (Escape or an outside click) can close the dialog. Explicit dialog actions, such as Submit and Cancel, can still close it.
+- **`isDismissable`** `boolean` (default: `true`) — Whether passive dismissal (Escape or an outside click) can close the dialog. Explicit dialog actions, such as Submit and Cancel, can still close it. A popover that is not dismissable leaves outside presses alone: the control pressed still receives the press, and a text field there can take focus, because such a popover does not hold focus. It stays open when another popover opens, and closes when a modal, tray, fullscreen or panel dialog opens from another `DialogTrigger`.
 - **`isKeyboardDismissDisabled`** `boolean` (default: `false`) — Whether pressing the escape key to close the dialog should be disabled
 - **`isOpen`** `boolean` — Whether the dialog is open (controlled)
 - **`defaultOpen`** `boolean` (default: `false`) — Whether the dialog is open by default (uncontrolled)
-- **`offset`** `number` (default: `8`) — The additional offset applied along the main axis
+- **`offset`** `number` (default: `8`) — The gap between the trigger and a popover, along the main axis. `0` places the popover flush against the trigger
 - **`crossOffset`** `number` (default: `0`) — The additional offset applied along the cross axis
 - **`containerPadding`** `number` (default: `12`) — The padding between the edge of the overlay and the boundary
 - **`shouldFlip`** `boolean` (default: `true`) — Whether the overlay should flip positions when insufficient space
@@ -33,7 +33,7 @@ DialogTrigger serves as a wrapper around a Dialog and its associated trigger, li
 - **`hideOnClose`** `boolean` — Whether to hide the overlay instead of unmounting on close
 - **`onOpenChange`** `function` — Callback fired when the dialog open state changes
 - **`onDismiss`** `function` — Callback fired when the dialog is dismissed
-- **`targetRef`** — The ref of the element the Dialog should visually attach itself to
+- **`targetRef`** — The ref of the element the Dialog should visually attach itself to. A popover closes when this element scrolls, as one attached to its trigger does
 - **`styles`** — The style map for the overlay
 - **`shouldCloseOnInteractOutside`** `(element: Element) => boolean` — Function to determine if a popover type Dialog should close on outside interaction. Asked before every built-in dismiss behaviour, so returning `false` keeps the popover open even for a `Button` / `ItemButton` that would otherwise dismiss it, or for a control the trigger itself owns (a picker's clear button, its custom `actions`) that would otherwise be read as a press on the trigger — and the pressed control still receives its own click. The element passed is the deepest node under the pointer (for a `Button` that is the label inside it, not the `<button>`), so guard with `contains()` rather than an identity check
 - **`shouldRestoreFocus`** `boolean` (default: `true`) — Whether focus returns to the trigger when the dialog closes. Only needed for a surface that claims focus _later_ than the restore (async load, entry animation); an action that focuses the surface it opens is already left alone — see [Focus Management](#best-practices)
@@ -158,7 +158,7 @@ function ControlledDialog() {
 ### Screen Reader Support
 
 - Dialog announces as "dialog" to screen readers
-- Focus is trapped within the dialog when open
+- Focus is contained within the dialog from the moment it opens, including while it animates in. A popover with `isDismissable={false}` does not contain focus, so focus can follow a press outside it
 - Focus returns to trigger element when dialog closes
 - The page behind a modal, fullscreen or tray dialog is hidden from screen readers while it is open; lists, menus and popovers opened from the dialog stay readable. Popover and panel dialogs leave the page readable
 - Proper ARIA attributes are applied automatically
@@ -168,7 +168,7 @@ function ControlledDialog() {
 - `aria-haspopup` - Automatically applied to trigger element
 - `aria-expanded` - Indicates dialog open state
 - `aria-labelledby` - Links dialog to its title
-- `aria-describedby` - Links dialog to its description
+- `aria-describedby` - Set for an alert dialog, linking its message; see [Dialog](./Dialog.md#aria-properties)
 
 ## Best Practices
 

package/docs/components/overlays/Tooltip.md

@@ -39,14 +39,14 @@ Display container for tooltip content. Has a directional arrow dependent on its
 ### Properties
 
 - **`tipStyles`** `Styles` — Custom styles for the tooltip arrow (tip) element
-- **`showIcon`** `boolean` — Controls whether an icon should be displayed in the tooltip
+- **`showIcon`** `boolean` — Deprecated. Has no effect
 - **`placement`** `PlacementAxis` (default: `'top'`) — Position of the tooltip relative to its trigger. Options: `top`, `bottom`, `left`, `right`
 - **`isMaterial`** `boolean` — Enables material-style tooltip with auto pointer events
 - **`isLight`** `boolean` — Uses light color scheme for the tooltip
 - **`isOpen`** `boolean` — Controlled open state of the tooltip
 - **`defaultOpen`** `boolean` — Whether the tooltip is open by default (uncontrolled)
 - **`onOpenChange`** `(isOpen: boolean) => void` — Callback when the tooltip open state changes
-- **`shouldFlip`** `boolean` — Whether the tooltip should flip position when there is insufficient space
+- **`shouldFlip`** `boolean` (default: `true`) — Whether the tooltip moves to the opposite side of its trigger when there is not enough room on the requested one
 
 ### Base Properties
 
@@ -214,14 +214,22 @@ function ControlledExample() {
 
 ### Conditional Tooltip
 
-Show a tooltip only when certain conditions are met:
+Show a tooltip only when certain conditions are met. Empty content (`null`, `undefined` or `''`) turns the tooltip off: nothing opens and the trigger gets no `aria-describedby`.
 
 ```jsx
-<TooltipProvider title={hasError ? "Fix errors first" : null}>
-  <Button isDisabled={hasError}>Submit</Button>
+<TooltipProvider title={isShared ? 'Visible to your whole team' : null}>
+  <Button>Share</Button>
 </TooltipProvider>
 ```
 
+A disabled `Button` receives neither hover nor focus, so a `TooltipProvider` around it never opens. Give the button its own `tooltip` instead; it then stays hoverable and focusable while disabled:
+
+```jsx
+<Button isDisabled={hasError} tooltip={hasError ? 'Fix errors first' : undefined}>
+  Submit
+</Button>
+```
+
 ### Focus-Only Trigger
 
 Show tooltip only on focus, not on hover:
@@ -238,7 +246,10 @@ Show tooltip only on focus, not on hover:
 
 - `Tab` - Moves focus to the trigger element, showing the tooltip after the delay
 - `Shift + Tab` - Moves focus away from the trigger, hiding the tooltip
+- `Escape` - Hides the tooltip
 - Tooltips automatically appear on focus for keyboard users
+- Pressing the trigger hides the tooltip, unless `shouldCloseOnPress` is `false`
+- When the page or an element containing the trigger scrolls, the tooltip follows the trigger while it stays in view, and hides once it is scrolled out of view
 
 ### Screen Reader Support
 
@@ -249,7 +260,7 @@ Show tooltip only on focus, not on hover:
 
 ### ARIA Properties
 
-- `aria-describedby` - Automatically set on the trigger to reference the tooltip
+- `aria-describedby` - Automatically set on the trigger to reference the tooltip while it is open. `Button`, `ItemBadge`, `ItemAction`, `Checkbox`, `Radio` and `Item` rows (`ItemButton`, list and menu items) add it after their own `aria-describedby` rather than replacing it
 - All standard ARIA labeling props are supported
 
 ### Best Practices

package/docs/components/overlays/TooltipTrigger.md

@@ -24,6 +24,8 @@ Lower-level component that wraps a trigger element and a `Tooltip`. Use when you
 - **`trigger`** `'focus'` — When set, opens the tooltip only on focus instead of both focus and hover
 - **`shouldCloseOnPress`** `boolean` (default: `true`) — Whether the tooltip closes when the trigger is pressed
 
+A `Tooltip` with empty content (`null`, `undefined` or `''`) never opens. When the page or an element containing the trigger scrolls, an open tooltip follows its trigger while the trigger stays in view, and closes once it is scrolled out of view. Set `shouldFlip` on the `Tooltip` itself.
+
 ### Base Properties
 
 Supports [Base properties](../../BaseProperties.md).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.195.0",
+  "version": "0.196.0",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {