@cube-dev/ui-kit 0.187.2 → 0.188.0

package/dist/utils/react/wrapNodeIfPlain.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.187.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.188.0 | Cube Dev Team */
 import { Fragment, isValidElement } from "react";
 
 //#region src/utils/react/wrapNodeIfPlain.ts

package/dist/utils/selection.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.187.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.188.0 | Cube Dev Team */
 //#region src/utils/selection.ts
 /**
 * Deduplicate/toggle keys in a selection: if a key appears twice it is

package/dist/utils/styles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.187.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.188.0 | Cube Dev Team */
 //#region src/utils/styles.ts
 /**
 * Split properties into style and non-style properties.

package/dist/utils/tree.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.187.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.188.0 | Cube Dev Team */
 //#region src/utils/tree.ts
 function toFlatTree(tree, includingFolders) {
 	return tree.reduce((result, node) => {

package/dist/utils/warnings.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.187.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.188.0 | Cube Dev Team */
 import { isDevEnvOrTest } from "./is-dev-env.js";
 
 //#region src/utils/warnings.ts

package/dist/version.js

@@ -1,6 +1,6 @@
-/** @license MIT | @cube-dev/ui-kit v0.187.2 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.188.0 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.187.2";
+const VERSION = "0.188.0";
 const TASTY_VERSION = "3.9.3";
 if (typeof window !== "undefined") {
 	const version = VERSION;

package/docs/components/actions/Action.md

@@ -11,7 +11,7 @@ A low-level action element that can render as `<button>`, `<a>`, or `<span>`. Wh
 ## Properties
 
 - **`to`** `NavigateArg` — Navigation target (renders as `<a>` when provided)
-- **`label`** `string` — Accessible label for screen readers
+- **`label`** `string` — **Deprecated.** Use `aria-label` for the accessible name and `children` for visible text
 - **`htmlType`** `'button' | 'submit' | 'reset'` — HTML button type
 - **`download`** `string` — Download attribute for link mode
 - **`onPress`** `() => void` — Press event handler (React Aria)

package/docs/components/actions/Button.md

@@ -21,7 +21,7 @@ A versatile action component that triggers commands and navigates users.
 - **`icon`** — Icon rendered before the content. Can be: ReactNode, `true` (empty slot), or function `({ loading, selected, ...mods }) => ReactNode | true`
 - **`rightIcon`** — Icon rendered after the content. Can be: ReactNode, `true` (empty slot), or function `({ loading, selected, ...mods }) => ReactNode | true`
 - **`children`** `ReactNode` — Button label or custom content
-- **`label`** `string` — Accessible label for the button (used as `aria-label`)
+- **`label`** `string` — **Deprecated.** Use `children` for visible text and `aria-label` for the accessible name of an icon-only button
 - **`tooltip`** `string | boolean | object` — Tooltip content. Use a string for simple text, `true` for auto tooltip on overflow, or an object with `{ title, auto, placement, ...tooltipProps }`
 - **`defaultTooltipPlacement`** `Placement` (default: `top`) — Default placement for the button's tooltip
 - **`isLoading`** `boolean` (default: `false`) — Show loading spinner and disable interactions
@@ -222,7 +222,7 @@ A disabled button keeps showing its tooltip. Browsers stop dispatching mouse eve
 
 - Announces role "button".
 - Announces state changes such as "pressed", "disabled", or "selected".
-- Provide `label`/`aria-label` when the button has no visible text.
+- Provide `aria-label` when the button has no visible text.
 
 ### ARIA Properties
 
@@ -254,6 +254,8 @@ There are three ways to keep the popover open when a Button is pressed:
    </div>
    ```
 
+   On a wrapper, `data-popover-keep` also tells any popover opened from inside it (a field's listbox, a menu) that a click in the wrapper is not outside, so that popover stays open. When only presses should be ignored, use `data-popover-keep-on-press` instead. A modern `DialogForm` marks its `<form>` this way.
+
 3. **Custom non-Cube triggers.** Call `useDismissParentPopover()` yourself if your control should dismiss the popover but does not extend `Button` / `ItemButton`:
    ```jsx
    const dismiss = useDismissParentPopover();

package/docs/components/actions/ItemButton.md

@@ -208,6 +208,7 @@ Like `Button`, an `ItemButton` press inside an open popover **dismisses that pop
     Toggle Mode
   </ItemButton>
   ```
+- **Presses only via `data-popover-keep-on-press`** — the same opt-out without making a click in the subtree count as inside a popover opened from it. See [Button](./Button.md).
 - **Custom non-Cube triggers** — call `useDismissParentPopover()` directly if you build a control on top of something other than `Button` / `ItemButton`.
 
 The dismiss is dispatched via the EventBus, which defers with `setTimeout(0)` — so synchronous `onPress` handlers (and the React state updates they trigger) flush BEFORE the popover closes. This makes the "open a hoisted modal from a popover footer" pattern work without flicker: the modal mounts first, then the popover closes behind it.

package/docs/components/actions/Link.md

@@ -308,7 +308,7 @@ These options are passed to the router's `navigate` function and have no effect
 
 - Renders as an `<a>` element when `to` is a string/object; as a `<button>` when `to` is a number or omitted.
 - Keyboard interaction and focus management are handled by React Aria.
-- Provide `label`/`aria-label` when there is no visible text.
+- Provide `aria-label` when there is no visible text.
 
 ### ARIA Properties
 

package/docs/components/content/InfoBadge.md

@@ -27,7 +27,7 @@ Every field's `labelTooltip` prop already renders an `InfoBadge` next to the lab
 
 ### Accessibility
 
-The accessible name is the tooltip text when it's plain text. Rich tooltip content can't serve as a name, so a localized `More information` label is used instead — pass `aria-label` or `label` to override it.
+The accessible name is the tooltip text when it's plain text. Rich tooltip content can't serve as a name, so a localized `More information` label is used instead — pass `aria-label` to override it (`label` still works but is deprecated).
 
 ### Base Properties
 

package/docs/components/content/Item.md

@@ -32,7 +32,7 @@ A foundational component that provides a standardized layout and styling for ite
 - **`actions`** `ReactNode | true` — Inline action buttons displayed on the right side. Use `Item.Action` for consistent styling
 - **`autoHideActions`** `boolean` (default: `false`) — When true, actions are hidden by default and shown only on hover, focus, or focus-within
 - **`preserveActionsSpace`** `boolean` (default: `false`) — When true, preserves the actions width when hidden (only changes opacity). Only applies when `autoHideActions` is true
-- **`disableActionsFocus`** `boolean` (default: `true`) — When true, action buttons are not focusable via keyboard
+- **`disableActionsFocus`** `boolean` (default: `false`) — When true, action buttons are not focusable via keyboard
 - **`hotkeys`** `string` — Keyboard shortcut displayed as a badge (e.g. `"cmd+s"`)
 - **`tooltip`** `string | boolean | object` (default: `true`) — Tooltip content. `true` enables auto tooltip on overflow, a string shows fixed tooltip text, an object supports advanced configuration `{ title, auto, placement, ...tooltipProps }`
 - **`highlight`** `string` — Text to highlight within the item label

package/docs/components/data/DataTable.md

@@ -142,6 +142,24 @@ Per column, on `CubeDataTableColumn`: `isReorderable`, `color` and `colorScope`
 
 Presentational, not a Cube type. `number` right-aligns the column and switches it to tabular figures, so digits line up down the column and a total lines up with the rows above it.
 
+The figures sit under the column's own `cellStyles`, so those still apply in either form. A function is still called per cell, and its result is merged over the figures.
+
+#### Column `cellStyles`
+
+Tasty styles for one column's body cells, exactly as in ItemTable: tokens, units, presets and state maps all work, and a state key asks about the cell itself. In the table-level `cellStyles` a bare key asks about the table instead, so a map copied from there that keys on `shape=card` or `column-dividers` matches nothing in a column; `@own(...)` asks about the cell in both. Values read as tasty, not CSS: `paddingLeft: 24` sets all four sides (the others to 0), so set one side with the CSS longhand and a unit (`paddingInlineStart: '24px'`); a bare number takes a unit on tasty's own properties (pass `lineHeight: '1.2'` for a unitless one) but not on plain CSS ones (`borderRadius: '4px'`, or `radius`); colors inside `border` / `outline` must be tokens (`'1px solid #red'`); a vendor key needs its CSS name in quotes (`'-webkit-line-clamp': 2`), since a capitalised `WebkitLineClamp` reads as a sub-element; and `textOverflow: 'ellipsis'` also adds `overflow: hidden` and `white-space: nowrap`. The function form runs per cell with the cell's context, which is how a pinned row is styled apart from the body:
+
+```jsx
+{
+  key: 'orders',
+  title: 'Orders',
+  dataType: 'number',
+  cellStyles: (ctx) =>
+    ctx.section === 'pinnedBottom' ? { color: '#surface-text-soft-2' } : undefined,
+}
+```
+
+Cells with equal styles share one class, so a function that returns a few distinct objects costs a few classes, however many rows there are. A column's own styles win over the table's cell paint, its `color` tint and the table-level `cellStyles` below.
+
 Loading, empty and error states, pagination, footer slots, virtualization, column resize and persistence all behave exactly as they do in `ItemTable` — they come from the shared renderer.
 
 ### Base Properties

package/docs/components/data/ItemTable.md

@@ -144,7 +144,7 @@ interface CubeItemTableColumn<T> {
   compare?: (a, b, rowA, rowB) => number;  // client-side comparator
 
   render?: (value, row, i, ctx) => ReactNode;
-  cellStyles?: Styles | ((ctx) => Styles | undefined);
+  cellStyles?: Styles | ((ctx) => Styles | undefined); // tasty styles for this column's body cells
   cellProps?: (ctx) => Record<string, any> | undefined;
 
   align?: 'start' | 'center' | 'end';
@@ -156,6 +156,8 @@ interface CubeItemTableColumn<T> {
 }
 ```
 
+**`cellStyles` is tasty, not inline CSS.** Tokens, units, presets, recipes and state maps all work, and a state key asks about the cell itself, so `{ color: { '': '#surface-text', '@own(pinned=bottom)': '#surface-text-soft-2' } }` dims only a pinned row. That differs from the table-level `cellStyles` slot, where a bare key asks about the table: a map copied from there that keys on `shape=card` or `column-dividers` matches nothing in a column, while `@own(...)` asks about the cell in both. Values read as tasty too, not CSS: `paddingLeft: 24` sets all four sides (the others to 0), so set one side with the CSS longhand and a unit (`paddingInlineStart: '24px'`); a bare number takes a unit on tasty's own properties (pass `lineHeight: '1.2'` for a unitless one) but not on plain CSS ones (`borderRadius: '4px'`, or `radius`); colors inside `border` / `outline` must be tokens (`'1px solid #red'`); a vendor key needs its CSS name in quotes (`'-webkit-line-clamp': 2`), since a capitalised `WebkitLineClamp` reads as a sub-element; and `textOverflow: 'ellipsis'` also adds `overflow: hidden` and `white-space: nowrap`. The function form runs per cell with the same `ctx` as `render`, for styles that depend on the row: `(ctx) => ctx.row.status === 'failed' ? { color: '#danger-text' } : undefined`. Cells with equal styles share one class, so a function that returns a few distinct objects costs a few classes, not one per cell. A column's own styles win over the table's cell paint, its `color` tint and the table-level `cellStyles`.
+
 **The value pipeline is the escape hatch.** `getValue`, `format` and `compare` exist so a column whose displayed text differs from its raw value stays sortable, searchable and copyable. `render` is for appearance only — sorting and searching never see its output, which is why an object-valued column with no `format` renders empty rather than `"[object Object]"`.
 
 #### `CubeTableColumnHeader`

package/docs/components/fields/ComboBox.md

@@ -52,10 +52,56 @@ A combobox component that combines a text input with a dropdown list, allowing u
 - **`containerPadding`** `number` (default: `8`) — Minimum padding in pixels between the popover and viewport edges
 - **`onFocus`** `() => void` — Callback fired when focus enters the ComboBox
 - **`onBlur`** `() => void` — Callback fired when focus leaves the ComboBox
-- **`onKeyDown`** `(e: KeyboardEvent) => void` — Callback fired when a key is pressed on the input
+- **`onKeyDown`** `(e: KeyboardEvent) => void` — Callback fired when a key is pressed on the input, before the component's own key handling. Call `e.preventDefault()` to skip that handling for the key, see **onKeyDown** below
 
 #### 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()`.
+
+```jsx
+<ComboBox
+  label="Assignee"
+  onKeyDown={(e) => {
+    // Enter is ours while the popover is closed
+    if (e.key === 'Enter' && !isOpen) {
+      e.preventDefault();
+      submit();
+    }
+  }}
+  onOpenChange={setIsOpen}
+>
+  {users.map((user) => (
+    <ComboBox.Item key={user.id}>{user.name}</ComboBox.Item>
+  ))}
+</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:
+
+```jsx
+const [selectedKey, setSelectedKey] = useState(null);
+
+<ComboBox
+  allowsCustomValue
+  label="Tag"
+  selectedKey={selectedKey}
+  onSelectionChange={setSelectedKey}
+  onKeyDown={(e) => {
+    if (e.key === 'Enter' && !isOpen) {
+      // Stops the form submit and the built-in commit
+      e.preventDefault();
+      // so commit the typed value here
+      setSelectedKey(e.currentTarget.value.trim() || null);
+    }
+  }}
+  onOpenChange={setIsOpen}
+>
+  {tags.map((tag) => (
+    <ComboBox.Item key={tag}>{tag}</ComboBox.Item>
+  ))}
+</ComboBox>;
+```
+
 **defaultInputValue** - Sets the initial input value in uncontrolled mode. This is useful when you want to display a specific text in the input field on mount without selecting any option. When both `defaultInputValue` and `defaultSelectedKey` are provided, `defaultInputValue` takes priority. The value can be changed by the user and is not enforced after initial render.
 
 **sortSelectedToTop** - When using the `items` prop (data-driven mode), the selected item will automatically appear at the top of the list when the popover opens. This is enabled by default when using `items`, but disabled when using JSX children. Set to `false` to maintain the original order.
@@ -524,6 +570,8 @@ const [selectedKey, setSelectedKey] = useState(null);
 - `End` - Moves focus to the last option (when popover is open)
 - Typing - Filters options based on input value
 
+An `onKeyDown` handler runs before all of these and can skip any of them for a key by calling `e.preventDefault()`.
+
 ### Screen Reader Support
 
 - Input announces as "combobox" with appropriate expanded/collapsed state

package/docs/components/fields/FilterPicker.md

@@ -166,7 +166,7 @@ These properties allow direct style application without using the `styles` prop:
 The `mods` property accepts the following modifiers you can override:
 
 - **`placeholder`** `boolean` — Applied when no selection is made
-- **`selected`** `boolean` — Applied when items are selected
+- **`selected`** `boolean` — Not set by the component. Pass `mods={{ selected: true }}` to give the trigger its brand-tinted selected fill, e.g. while a filter is active. Holding a value doesn't set it
 
 ## Sub-components
 
@@ -324,8 +324,8 @@ const categories = [
 
 ### Button Types
 
-- `outline` - Default outlined button style; `isSelected` adds brand-tinted fill
-- `clear` - Transparent background button; `isSelected` adds brand-tinted fill
+- `outline` - Default outlined button style; `mods={{ selected: true }}` adds a brand-tinted fill
+- `clear` - Transparent background button; `mods={{ selected: true }}` adds a brand-tinted fill
 - `primary` - Primary brand color button
 
 ### Sizes

package/docs/components/fields/NumberInput.md

@@ -38,6 +38,31 @@ A number input component that allows users to enter numeric values and increment
 - **`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
+- **`onKeyDown`** `(e: KeyboardEvent) => void` — Callback fired when a key is pressed in the input. See [Keyboard Events](#keyboard-events)
+- **`onKeyUp`** `(e: KeyboardEvent) => void` — Callback fired when a key is released in the input
+
+#### Keyboard Events
+
+`onKeyDown` and `onKeyUp` are attached to the `<input>` by React Aria's `useNumberField`, which handles some keys itself and runs that handling **before** your `onKeyDown`:
+
+- `ArrowUp` / `ArrowDown` and `PageUp` / `PageDown` step the value, unless a modifier key is held
+- `Home` / `End` set the value to `minValue` / `maxValue`, when those are set
+- `Enter` commits the typed number, firing `onChange` when the value changed
+
+Because they run first, `e.preventDefault()` in `onKeyDown` cannot cancel them: it cancels only what the browser would do with the key, such as submitting a surrounding form on `Enter`. That makes NumberInput the exception among the fields with built-in key handling (`ComboBox`, `SearchComboBox`, `TagInput` and `CommandTextArea` run your handler first and skip their own handling for a key you prevent), and it is what makes an `Enter` handler work here: by the time it runs, the typed number is committed and any `onChange` for it has fired.
+
+```jsx
+<NumberInput
+  label="Limit"
+  onChange={setLimit}
+  onKeyDown={(e) => {
+    // `onChange` has already been called with the committed number.
+    if (e.key === 'Enter') onCommit();
+  }}
+/>
+```
+
+The handler receives React Aria's keyboard event rather than a plain React one. Keys other than `Enter` continue to ancestors as usual; `Enter` stops at the input unless you call `e.continuePropagation()`.
 
 ### Base Properties
 
@@ -137,7 +162,9 @@ The `mods` prop accepts the following modifiers you can override:
 - `Tab` – Moves focus to the input field
 - `Shift + Tab` – Moves focus away from the input
 - Arrow keys – Increment/decrement value
+- `PageUp`/`PageDown` – Increment/decrement value
 - `Home`/`End` – Set to min/max value
+- `Enter` – Commits the typed value
 - Standard text editing shortcuts
 
 ### Screen Reader Support

package/docs/components/fields/PasswordInput.md

@@ -31,6 +31,30 @@ A password input is a specialized text field that masks user input to protect se
 - **`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
+- **`onKeyDown`** `(e: KeyboardEvent) => void` — Callback fired when a key is pressed in the input. See [Keyboard Events](#keyboard-events)
+- **`onKeyUp`** `(e: KeyboardEvent) => void` — Callback fired when a key is released in the input
+
+#### Keyboard Events
+
+`onKeyDown` and `onKeyUp` are attached to the `<input>` by React Aria's `useTextField`. PasswordInput has no key handling of its own, so the handler simply receives the event: `e.preventDefault()` cancels only what the browser would do with the key, such as typing the character or submitting a surrounding form on `Enter`. The visibility toggle is a separate button and never sees the input's keys.
+
+The handler receives React Aria's keyboard event rather than a plain React one, and once you pass `onKeyDown` the key stops at the input: React Aria stops its propagation after your handler. A parent's `onKeyDown` no longer sees it, and neither does a surrounding `Dialog`, so `Escape` stops closing it. Call `e.continuePropagation()` for the keys that should travel on:
+
+```jsx
+<PasswordInput
+  label="Password"
+  onKeyDown={(e) => {
+    if (e.key === 'Enter') {
+      e.preventDefault(); // keep a surrounding form from submitting
+      signIn();
+    } else {
+      e.continuePropagation(); // let Escape still close a Dialog
+    }
+  }}
+/>
+```
+
+The fields that do handle keys themselves (`ComboBox`, `SearchComboBox`, `TagInput`, `CommandTextArea`) run your `onKeyDown` first and skip their own handling for a key you prevent. `NumberInput` is the exception: React Aria runs its stepping and `Enter` commit before your handler.
 
 ### Base Properties
 

package/docs/components/fields/Picker.md

@@ -155,7 +155,7 @@ These properties allow direct style application without using the `styles` prop:
 The `mods` property accepts the following modifiers you can override:
 
 - **`placeholder`** `boolean` — Applied when no selection is made
-- **`selected`** `boolean` — Applied when items are selected
+- **`selected`** `boolean` — Not set by the component. Pass `mods={{ selected: true }}` to give the trigger its brand-tinted selected fill, e.g. while a filter is active. Holding a value doesn't set it
 
 ## Sub-components
 
@@ -324,8 +324,8 @@ For large datasets or dynamic content, use the `items` prop with a render functi
 
 The trigger button supports various visual styles via the `type` prop:
 
-- **`outline`** (default) — Outlined button with border. Use case: Standard form inputs. `isSelected` adds brand-tinted fill.
-- **`clear`** — Transparent background. Use case: Toolbar actions, compact interfaces. `isSelected` adds brand-tinted fill.
+- **`outline`** (default) — Outlined button with border. Use case: Standard form inputs. `mods={{ selected: true }}` adds a brand-tinted fill.
+- **`clear`** — Transparent background. Use case: Toolbar actions, compact interfaces. `mods={{ selected: true }}` adds a brand-tinted fill.
 - **`primary`** — Primary brand color. Use case: Emphasized selections
 
 ### Trigger Button Themes

package/docs/components/fields/SearchComboBox.md

@@ -46,7 +46,7 @@ Choose a different component when the interaction has another outcome:
 - **`onOpenChange`** `(isOpen: boolean) => void` — Fired when the popover opens or closes
 - **`onFocus`** `() => void` — Fired when focus enters the component
 - **`onBlur`** `() => void` — Fired when focus leaves the component
-- **`onKeyDown`** `(e: KeyboardEvent) => void` — Fired when a key is pressed on the input
+- **`onKeyDown`** `(e: KeyboardEvent) => void` — Fired when a key is pressed on the input, before the component's own key handling. Call `e.preventDefault()` to skip that handling for the key: a prevented `Enter` selects nothing and does not call `onSubmit`, a prevented `ArrowDown` does not open the popover. The event is React Aria's keyboard event, whose propagation stops at the input unless the handler calls `e.continuePropagation()`
 - **`prefix`** `ReactNode` — Content rendered before the input
 - **`suffix`** `ReactNode` — Content rendered after the input
 - **`suffixPosition`** `'before' | 'after'` (default: `before`) — Position of suffix relative to status icons
@@ -229,6 +229,8 @@ useEffect(() => {
 - `Home` / `End` - Moves focus to the first / last suggestion (when the popover is open)
 - Typing - Filters suggestions based on the input value
 
+An `onKeyDown` handler runs before all of these and can skip any of them for a key by calling `e.preventDefault()`.
+
 ### ARIA Properties
 
 - `role="combobox"` - Identifies the input as a combobox

package/docs/components/fields/TagInput.md

@@ -377,13 +377,15 @@ const [recipients, setRecipients] = useState(['ana@acme.com']);
 - The input's description reads the current values ("Selected: …") and says that Backspace moves to them, so the user hears what is already added and how to reach it
 - Focus on a chip reads its label, its position and React Aria's hint to press Delete or Backspace to remove it
 - A polite live region announces "Added …" and "Removed …" when the user adds or removes a value. Changes made from outside the field are not announced
-- The chips are a grid named "Selected values" followed by the field's label. Each chip is a row, and its remove button reads "Remove" followed by the chip's label. An invalid chip is described by its validation message, not only by its color
+- The chips, the popover trigger, the clear button and the options listbox are named after the field, however the field is named. With a visible label or `aria-labelledby`, they point at the same elements: the grid reads "Selected values" followed by the field's name, the trigger "Show options" followed by it, and the listbox the field's name alone. An `aria-label` has no element to point at, so its text is joined in: "Selected values, …", "Show options, …", "Clear text, …", and the listbox takes the `aria-label`. Next to a visible label or `aria-labelledby` it comes first, as it does on the input itself: with `aria-label="Values"` and `aria-labelledby` pointing at "Primary key", the input reads "Values Primary key" and the grid "Selected values, Values Primary key". Each row of a table whose fields are labelled by a header and a row cell so gets its own names
+- Each chip is a row, and its remove button reads "Remove" followed by the chip's label. An invalid chip is described by its validation message, not only by its color
 - A rejected value marks the input invalid. With a visible label its message is shown under the field and announced as an alert, again for each new attempt. Without one, the message is announced through the live region
 - A disabled field's chips are out of the Tab order, and so are locked chips. A read-only field's chips stay focusable, without remove buttons
-- The clear button is named "Clear text" followed by the field's label. Escape does the same from the keyboard
+- The clear button is named "Clear text" followed by the field's name. Escape does the same from the keyboard
 
 ### ARIA Properties
 
+- `aria-label` / `aria-labelledby` - Name the input when there is no visible label, and through it the chips, the buttons and the listbox. Pass one of them, or `label`
 - `aria-describedby` - Adds the summary of current values and the Backspace hint to the input's own descriptions, such as one passed in `aria-describedby`
 - `aria-invalid` - Set while a typed value is rejected, or when the field is invalid
 - `role="combobox"`, `aria-expanded`, `aria-controls`, `aria-activedescendant`, `aria-autocomplete="list"` - Set when options are given. `aria-activedescendant` follows both arrow keys and clicks

package/docs/components/fields/TextArea.md

@@ -59,6 +59,30 @@ These properties allow direct style application without using the `styles` prop:
 - **`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
+- **`onKeyDown`** `(e: KeyboardEvent) => void` — Callback fired when a key is pressed in the textarea. See [Keyboard Events](#keyboard-events)
+- **`onKeyUp`** `(e: KeyboardEvent) => void` — Callback fired when a key is released in the textarea
+
+### Keyboard Events
+
+`onKeyDown` and `onKeyUp` are attached to the `<textarea>` by React Aria's `useTextField`. TextArea has no key handling of its own, so the handler simply receives the event: `e.preventDefault()` cancels only what the browser would do with the key, such as inserting a newline on `Enter`.
+
+The handler receives React Aria's keyboard event rather than a plain React one, and once you pass `onKeyDown` the key stops at the textarea: React Aria stops its propagation after your handler. A parent's `onKeyDown` no longer sees it, and neither does a surrounding `Dialog`, so `Escape` stops closing it. Call `e.continuePropagation()` for the keys that should travel on:
+
+```jsx
+<TextArea
+  label="Comment"
+  onKeyDown={(e) => {
+    if (e.key === 'Enter' && (e.metaKey || e.ctrlKey)) {
+      e.preventDefault(); // no newline
+      send();
+    } else {
+      e.continuePropagation(); // let Escape still close a Dialog
+    }
+  }}
+/>
+```
+
+The fields that do handle keys themselves (`ComboBox`, `SearchComboBox`, `TagInput`, `CommandTextArea`) run your `onKeyDown` first and skip their own handling for a key you prevent. `NumberInput` is the exception: React Aria runs its stepping and `Enter` commit before your handler.
 
 ### Base Properties
 

package/docs/components/fields/TextInput.md

@@ -39,6 +39,30 @@ A text input component that allows users to input custom text entries with a key
 - **`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
+- **`onKeyDown`** `(e: KeyboardEvent) => void` — Callback fired when a key is pressed in the input. See [Keyboard Events](#keyboard-events)
+- **`onKeyUp`** `(e: KeyboardEvent) => void` — Callback fired when a key is released in the input
+
+#### Keyboard Events
+
+`onKeyDown` and `onKeyUp` are attached to the `<input>` by React Aria's `useTextField`. TextInput has no key handling of its own, so the handler simply receives the event: `e.preventDefault()` cancels only what the browser would do with the key, such as typing the character or submitting a surrounding form on `Enter`.
+
+The handler receives React Aria's keyboard event rather than a plain React one, and once you pass `onKeyDown` the key stops at the input: React Aria stops its propagation after your handler. A parent's `onKeyDown` no longer sees it, and neither does a surrounding `Dialog`, so `Escape` stops closing it. Call `e.continuePropagation()` for the keys that should travel on:
+
+```jsx
+<TextInput
+  label="Name"
+  onKeyDown={(e) => {
+    if (e.key === 'Enter') {
+      e.preventDefault(); // keep a surrounding form from submitting
+      commit();
+    } else {
+      e.continuePropagation(); // let Escape still close a Dialog
+    }
+  }}
+/>
+```
+
+The fields that do handle keys themselves (`ComboBox`, `SearchComboBox`, `TagInput`, `CommandTextArea`) run your `onKeyDown` first and skip their own handling for a key you prevent. `NumberInput` is the exception: React Aria runs its stepping and `Enter` commit before your handler.
 
 ### Base Properties
 

package/docs/components/navigation/Tabs.md

@@ -203,13 +203,18 @@ The `width` style prop (inherited from Item) is useful for file-style tabs where
 
 Optional wrapper for tabs when using explicit panel placement.
 
+- **`qa`** `string` — `data-qa` attribute on the `role="tablist"` element
+- **`qaVal`** `string` — `data-qaval` attribute on the `role="tablist"` element
+
 ```jsx
-<Tabs.List>
+<Tabs.List qa="ReportTabs">
   <Tab key="tab1" title="Tab 1" />
   <Tab key="tab2" title="Tab 2" />
 </Tabs.List>
 ```
 
+`Tabs.List` also works without `Tabs.Panel`, so wrap the tabs in it whenever a test needs a stable selector for the tab list. The `qa` prop on `Tabs` itself lands on the outer wrapper, not on the tab list.
+
 ### Tabs.Panel
 
 Explicit panel definition for advanced layout control.
@@ -676,7 +681,7 @@ When both are in the same slot:
 
 ### Navigation-Only Tabs
 
-Use tabs without panel content for navigation purposes.
+Use tabs without panel content for navigation purposes. Use this only when each tab leads to a different page or route; content that belongs to a tab goes in a panel (`renderPanel` or `Tab` children), so the tab can point screen readers at it.
 
 ```jsx
 const [view, setView] = useState('overview');
@@ -877,7 +882,7 @@ When `Tabs` is rendered inside a [`Board`](../layout/Board.md), tab switching be
 - `aria-label` - Set via `label` prop on Tabs
 - `aria-selected` - Managed automatically for active tab
 - `aria-disabled` - Applied when `isDisabled` is true
-- `aria-controls` - Links tabs to their panels automatically
+- `aria-controls` - Links the selected tab to its panel automatically; omitted for a tab that has no panel
 - `aria-labelledby` - Links panels to their tabs automatically
 - `aria-haspopup` - Set to "menu" when tab has a menu
 

package/docs/components/overlays/AlertDialog.md

@@ -15,8 +15,8 @@ A modal dialog for important messages that require user acknowledgment. Extends
 - **`danger`** `boolean` — Applies danger styling for destructive actions
 - **`noActions`** `boolean` — Hide the action buttons entirely
 - **`actions`** `object` — Customize buttons:
-  - `confirm` — Confirm button props or `false` to hide (default: `{ label: 'Ok', type: 'primary' }`)
-  - `cancel` — Cancel button props or `true` to show (default: hidden, uses `{ label: 'Cancel' }`)
+  - `confirm` — Confirm button props or `false` to hide (default: `{ children: 'Ok', type: 'primary' }`)
+  - `cancel` — Cancel button props or `true` to show (default: hidden, uses `{ children: 'Cancel' }`). Set a button's text with `children`; `label` still works but is deprecated
   - `secondary` — Optional secondary button props
 - **`size`** `'S' | 'M' | 'L' | 'small' | 'medium' | 'large'` — The size of the dialog
 - **`isDismissable`** `boolean` (default: `false`) — Whether the dialog is dismissable
@@ -50,7 +50,7 @@ These properties allow direct style application without using the `styles` prop:
     title="Confirm Delete"
     content="Are you sure you want to delete this item?"
     actions={{
-      confirm: { label: 'Delete', type: 'danger' },
+      confirm: { children: 'Delete', type: 'danger' },
       cancel: true,
     }}
   />

package/docs/components/overlays/DialogForm.md

@@ -21,8 +21,8 @@ The examples below use modern controllers. See [Modern Form](../form/ModernForm.
 - **`form`** `FormController<T> | CubeFormInstance<T>` — Modern controller (recommended) or legacy instance. Omitting it selects legacy behavior.
 - **`title`** `string` — Dialog title
 - **`danger`** `boolean` — Give the submit button the danger theme
-- **`submitProps`** `CubeButtonProps` (legacy) / `Omit<CubeSubmitButtonProps<T>, 'form'>` (modern) — Customize the submit button, including its label and modern `disableOnInvalid`
-- **`cancelProps`** `CubeButtonProps` — Customize the cancel button, including its label
+- **`submitProps`** `CubeButtonProps` (legacy) / `Omit<CubeSubmitButtonProps<T>, 'form'>` (modern) — Customize the submit button, including its text (`children`) and modern `disableOnInvalid`
+- **`cancelProps`** `CubeButtonProps` — Customize the cancel button, including its text (`children`)
 - **`preserve`** `boolean` (default: `false`) — Retain values when the editing session ends. Keep the controller mounted above the dialog to retain a draft across dialog unmounts.
 - **`noActions`** `boolean` — Hide the default submit/cancel buttons
 - **`children`** `ReactNode | ((dismiss: () => void) => ReactNode)` — Fields, or a render function for custom actions
@@ -80,7 +80,7 @@ function EditProfile({ initialProfile, save }) {
       <DialogForm
         form={form}
         title="Edit profile"
-        submitProps={{ label: 'Save' }}
+        submitProps={{ children: 'Save' }}
         onSubmit={(values, { signal }) => save(values, signal)}
       >
         <TextInput name="name" label="Name" isRequired />

package/docs/components/overlays/UseDialogContainer.md

@@ -184,10 +184,7 @@ function UserFormDialog({ onSubmit, initialData, onCancel }) {
       onSubmit={onSubmit}
       onDismiss={onCancel}
       submitProps={{
-        label: 'Save User'
-      }}
-      cancelProps={{
-        label: 'Cancel'
+        children: 'Save User'
       }}
     >
       <TextInput
@@ -270,11 +267,11 @@ function ConfirmDialog({ message, onConfirm, onCancel, danger }) {
       danger={danger}
       actions={{
         confirm: {
-          label: 'Confirm',
+          children: 'Confirm',
           onPress: onConfirm
         },
         cancel: {
-          label: 'Cancel',
+          children: 'Cancel',
           onPress: onCancel
         }
       }}
@@ -289,7 +286,7 @@ function InfoDialog({ title, content }) {
       content={content}
       actions={{
         confirm: {
-          label: 'OK'
+          children: 'OK'
         },
         cancel: false
       }}

package/package.json

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