@cube-dev/ui-kit 0.187.2 → 0.189.0

package/docs/components/content/Result.md

@@ -1,11 +1,12 @@
 # Result
 
-An empty state or result display with icon, title, and optional content. Supports status presets with built-in icons.
+An empty state or result display with icon, title, and optional content. Supports status presets with built-in icons and an actions slot. The `large` size with the `stacked` layout is the vertical card used as the body of a confirmation or result dialog.
 
 ## When to Use
 
 - Empty states (no data, no results)
 - Success/error feedback after actions
+- Confirmation and result dialogs (payment complete, action failed)
 - 404, 403, 500 error pages
 - Informational messages
 
@@ -19,9 +20,35 @@ An empty state or result display with icon, title, and optional content. Support
 - **`title`** `ReactNode` — Main title text
 - **`subtitle`** `ReactNode` — Secondary text below the title
 - **`subTitle`** `ReactNode` — Deprecated: use `subtitle` instead
-- **`icon`** `ReactNode` — Custom icon (overrides status icon)
-- **`isCompact`** `boolean` (default: `false`) — Compact horizontal layout
-- **`children`** `ReactNode` — Additional block content, e.g. a set of action buttons
+- **`icon`** `ReactNode` — Custom icon that replaces the status icon
+- **`size`** `'medium' | 'large'` (default: `'medium'`) — Visual scale: the icon size and the title and subtitle presets. Does not change the layout. Ignored when `isCompact` is set
+- **`layout`** `'default' | 'stacked'` (default: `'default'`) — Arrangement of the block. `stacked` fills the container and stacks the actions to the full width, as in a confirmation or result dialog. Ignored when `isCompact` is set
+- **`isCompact`** `boolean` (default: `false`) — Compact horizontal layout. Overrides `size` and `layout`
+- **`actions`** `ReactNode` — Action buttons as `Result.Action` elements: a centered row by default, a full-width column in the `stacked` layout
+- **`children`** `ReactNode` — Free content between the text and the actions
+
+The elements render in this order: icon, title, subtitle, children, actions.
+
+### Result.Action
+
+A `Button` for the `actions` slot. It takes every `Button` prop, and its `size` follows the Result's `size` unless you set one: `medium` buttons in a medium Result, `large` in a large one, `medium` when `isCompact`. A `type="link"` action keeps the `inline` size of a link `Button`. Set `type` on each action as on any `Button`.
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md).
+
+### Styling Properties
+
+#### styles
+
+Customizes the root element of the component.
+
+**Sub-elements:**
+
+- `Icon` - The status icon wrapper. Colored by the `status` modifier, padded on every side by `3x`, or a quarter of `--icon-size` when that is larger (an icon above `12x`), so the room never drops below the spacing between the other blocks, and that room is the whole distance to the title (no padding when `isCompact`). Wraps a custom `icon` too, with the same room and without a status color. Not rendered for a status without an icon (`404`, `403`, `500`)
+- `Title` - The text block holding the title and the subtitle
+- `Content` - The free `children` block
+- `Actions` - The `actions` block
 
 ### Style Defaults
 
@@ -29,15 +56,13 @@ An empty state or result display with icon, title, and optional content. Support
 - `flow` — `column`
 - `placeContent` — `center` (switches to `start` when `isCompact`)
 - `placeItems` — `center` (switches to `start` when `isCompact`)
-- `gap` — `3x` (switches to `2x 1x` when `isCompact`)
-- `padding` — `6x 4x` (switches to `0` when `isCompact`)
+- `gap` — `0`; `Content` and `Actions` keep `3x` from the block above with a top margin (`2x 1x` and no margins when `isCompact`)
+- `padding` — `6x 4x` (`0` when `isCompact`; `1.5x` when `layout="stacked"`, and `0` for a stacked Result inside a `Dialog`, whose `Content` already pads it. The `@in-dialog` state is the Result's own, so `styles={{ padding: { 'layout=stacked & @in-dialog': '1x' } }}` sets it and keeps the rest of the default padding)
 - `textAlign` — `center` (switches to `left` when `isCompact`)
-- `width` — `max 80ch` (caps the readable line length; override via the `width` prop)
+- `boxSizing` — `border-box`
+- `width` — `max 80ch` (caps the readable line length; override via the `width` prop). `100%` up to `80ch` when `layout="stacked"`, so the stacked actions share one width wherever the card sits
 - `margin` — `0 auto` (centers Result horizontally within its parent; switches to `0` when `isCompact`)
-
-### Base Properties
-
-Supports [Base properties](../../BaseProperties.md).
+- `--icon-size` — `6x` (`10x` when `size="large"`)
 
 ### Style Properties
 
@@ -50,8 +75,51 @@ These properties allow direct style application without using the `styles` prop:
 - **Color:** `color`, `fill`, `fade`, `image`
 - **Flow:** `flow`, `place`, `placeItems`, `placeContent`, `alignItems`, `alignContent`, `justifyItems`, `justifyContent`, `align`, `justify`, `gap`, `columnGap`, `rowGap`, `gridColumns`, `gridRows`, `gridTemplate`, `gridAreas`
 
+### Modifiers
+
+The root element exposes these modifiers as `data-*` attributes:
+
+| Modifier | Type | Description |
+| --- | --- | --- |
+| `compact` | `boolean` | Set by `isCompact`: horizontal icon + title layout |
+| `size` | `'medium' \| 'large'` | Set by `size`; `medium` when `isCompact` |
+| `layout` | `'default' \| 'stacked'` | Set by `layout`; `default` when `isCompact` |
+| `status` | `CubeResultStatus` | Set by `status`, `info` by default; drives the icon color. Not set when a custom `icon` is passed |
+
+## Variants
+
+### Sizes
+
+The size scales the content and never changes the arrangement. `isCompact` has its own scale and ignores it.
+
+- `medium` - Default. Icon `6x`, title `h4`, subtitle `t2m`
+- `large` - Icon `10x`, title `h2`, subtitle `t2`, `Result.Action` buttons `large`
+
+### Layouts
+
+The layout arranges the block and never changes the scale. `isCompact` has its own arrangement and ignores it.
+
+- `default` - A centered column capped at `80ch`, actions in a centered row that wraps
+- `stacked` - Fills the container up to `80ch` with a `1.5x` padding of its own (none inside a `Dialog`), actions stacked to the full width, free `children` stretched. Combine with `size="large"` for the vertical card of a confirmation or result dialog
+
 ## Examples
 
+### Basic Usage
+
+```jsx
+<Result
+  status="success"
+  title="Successfully Purchased Cloud Server ECS!"
+  subtitle="Cloud server configuration takes 1-5 minutes, please wait."
+  actions={
+    <>
+      <Result.Action type="primary">Go Console</Result.Action>
+      <Result.Action>Buy Again</Result.Action>
+    </>
+  }
+/>
+```
+
 ### Info
 
 ### Warning
@@ -60,14 +128,136 @@ These properties allow direct style application without using the `styles` prop:
 
 ### Custom Icon
 
+```jsx
+<Result
+  title="Access is denied!"
+  subtitle="Request access from the administrator."
+  icon={
+    <Icon color="#warning">
+      <IconLock />
+    </Icon>
+  }
+  actions={<Result.Action>Request</Result.Action>}
+/>
+```
+
 ### Custom Title
 
 ### Compact
 
+### Large
+
+The `large` size scales the icon and the text. The actions stay in a centered row.
+
+```jsx
+<Result
+  size="large"
+  status="success"
+  title="Payment complete"
+  subtitle="Charged $1,234.00 to Visa **** 4242"
+  actions={
+    <>
+      <Result.Action type="primary">
+        Done
+      </Result.Action>
+      <Result.Action>
+        View invoice
+      </Result.Action>
+    </>
+  }
+/>
+```
+
+### Stacked
+
+The `stacked` layout fills the container and stacks the actions to the full width. With `size="large"` it is the vertical card for confirmation and result dialogs.
+
+```jsx
+<Result
+  size="large"
+  layout="stacked"
+  status="success"
+  title="Payment complete"
+  subtitle="Charged $1,234.00 to Visa **** 4242"
+  actions={
+    <Result.Action type="primary">
+      Done
+    </Result.Action>
+  }
+/>
+```
+
+Free `children` (an alert, details) stretch to the full width in this layout.
+
+### In a Dialog
+
+Inside a `Dialog` the stacked large Result is the whole body: no `Header` and no `Footer`. Its title takes the dialog `title` slot, so the dialog is labelled by it automatically.
+
+```jsx
+<DialogContainer isOpen={isOpen} onDismiss={close}>
+  <Dialog size="S">
+    <Content>
+      <Result
+        size="large"
+        layout="stacked"
+        status="success"
+        title="Payment complete"
+        subtitle="Charged $1,234.00 to Visa **** 4242"
+        actions={
+          <Result.Action type="primary" onPress={close}>
+            Done
+          </Result.Action>
+        }
+      />
+    </Content>
+  </Dialog>
+</DialogContainer>
+```
+
 ### Width Limit
 
 The default `width: max 80ch` keeps long copy in a comfortable reading column even inside a much wider parent. Override the cap by passing your own `width`.
 
+## Accessibility
+
+### Keyboard Navigation
+
+- The component itself is not focusable; the `Result.Action` buttons keep the keyboard behavior of `Button`
+
+### Screen Reader Support
+
+- The title renders as an `h2` heading and the subtitle as an `h3`, so the result is reachable through heading navigation
+- Inside a `Dialog` without a `Header`, the title takes the dialog's `title` slot and becomes its accessible name
+
+## Best Practices
+
+1. **Do**: Put `Result.Action` buttons in `actions` and keep `children` for content
+
+   ```jsx
+   <Result title="Payment failed" actions={<Result.Action>Update card</Result.Action>}>
+     <Alert>Nothing was charged.</Alert>
+   </Result>
+   ```
+
+2. **Don't**: Combine a Result with a dialog `Header`. Both titles would take the dialog `title` slot and share one id
+
+   ```jsx
+   <Dialog>
+     <Header>
+       <Title>Payment</Title>
+     </Header>
+     <Content>
+       <Result size="large" layout="stacked" title="Payment complete" />
+     </Content>
+   </Dialog>
+   ```
+
+## Related Components
+
+- [Dialog](../overlays/Dialog.md) - Host for the stacked large Result card
+- [AlertDialog](../overlays/AlertDialog.md) - Confirmation with a header and footer instead of a result card
+- [Alert](./Alert.md) - Inline status message for the `children` slot
+
 ## Differences from Ant Design
 
 | There are differences | Ant Design property | Cube UIKit property |
@@ -76,4 +266,4 @@ The default `width: max 80ch` keeps long copy in a comfortable reading column ev
 |          No           |       `title`       |       `title`       |
 |          Yes          |     `subTitle`      |     `subtitle`      |
 |          No           |       `icon`        |       `icon`        |
-|          Yes          |       `extra`       |     `children`      |
+|          Yes          |       `extra`       |      `actions`      |

package/docs/components/content/Title.md

@@ -11,6 +11,7 @@ A heading component for section titles. Renders as `h1`–`h6` based on the `lev
 ## Properties
 
 - **`level`** `1 | 2 | 3 | 4 | 5 | 6` (default: `1`) — Heading level (maps to `h1`–`h6` tag and corresponding preset `h1`–`h6`)
+- **`slot`** `string` (default: `'title'`) — The slot to read provided props from, e.g. the `title` slot a `Dialog` labels itself with. Pass another name to opt out
 - **`ellipsis`** `boolean` — Truncate overflow with ellipsis
 - **`nowrap`** `boolean` — Prevent text wrapping
 - **`monospace`** `boolean` — Use monospace font

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