@cube-dev/ui-kit 0.195.0 → 0.196.0

package/docs/ComplexLayout.md

@@ -201,7 +201,7 @@ Panels support four rendering modes via the `mode` prop:
 
 - **`default`** — Standard panel, pushes content (Content Push: Yes, Overlay: No)
 - **`sticky`** — Floats over content (Content Push: No, Overlay: No)
-- **`overlay`** — With dismissable backdrop (Content Push: Yes, Overlay: Yes)
+- **`overlay`** — With dismissable backdrop, floats over content (Content Push: No, Overlay: Yes)
 - **`dialog`** — Renders as modal dialog (Content Push: No, Overlay: Dialog)
 
 ### Sticky Panel

package/docs/CreateComponent.md

@@ -425,6 +425,8 @@ export function Action(
 
 ## Form Integration
 
+Call `wrapWithField` consistently: it renders stable field chrome by default and handles `isBare` as the explicit opt-out. Do not infer presentation from a label, form binding or message content. Pass React Aria's label props to the wrapper so a supplied label remains associated with the control in both modes. Inner controls whose parent owns the field chrome should receive `isBare` to avoid nested fields.
+
 For input components that need to integrate with forms, see the [Field documentation](./components/form/Field.md) for comprehensive guidance on:
 
 - Form state management

package/docs/FieldProperties.md

@@ -20,16 +20,41 @@ For modern forms, follow the [use-case guide](./components/form/ModernForm.md).
 ## Labels & Description
 
 - **`label`** `ReactNode` — Label text displayed above or beside the input.
-- **`labelPosition`** `'top' | 'side' | 'split'` (default: `top`) — Position of the label relative to the input.
-- **`description`** `ReactNode` — Description text placed below the label. A field without a label shows it too, unless it is `isBare`.
-- **`isBare`** `boolean` — For inline use: a field without a `label` renders the bare control. Without `isBare`, such a field renders the field wrapper when it is bound to a form, whose validation errors need a place, or is passed `description`, `errorMessage` or `message`. A text prop counts whatever it holds at the moment, so the input keeps its place and its focus when a message comes and goes. A wrapped field is laid out by its wrapper, as a labelled one is: layout props on the input such as `flexGrow`, `width` or `gridArea` stay on the input, so set them in `fieldStyles` to place the field, or pass `isBare`. With `isBare` the texts are not shown, and the control keeps its invalid state (`aria-invalid` and the invalid styles). The error text is not linked to anything, though, so a screen reader says the field is invalid without saying why: show the reason some other way, such as a tooltip or a message for the whole row, and point `aria-describedby` at it. No effect on a field with a `label`.
-- **`forceField`** `boolean` — **Deprecated.** A field without a `label` now renders the field wrapper by itself when it is bound to a form or is passed `description`, `errorMessage` or `message`; set `isBare` to keep the bare control instead. `forceField` still forces the wrapper and warns once in development.
+- **`labelPosition`** `'top' | 'side' | 'split'` (default: `top`) — Position of the label relative to the input. Side and split layouts reserve a label column only when a label is present.
+- **`description`** `ReactNode` — Help text. It appears below a top label or the control when there is no visible label, and beside the control with a side or split label. It remains independent of the error message.
+- **`isBare`** `boolean` (default: `false`) — Render the control without field layout, description or message text. A supplied `label` remains as a visually hidden accessible label; label tooltips, suffixes and extra content are omitted. Form binding, invalid state and control styles still apply. Use this explicitly for inline controls or when a parent already renders their field chrome. Provide `aria-describedby` when the error is explained elsewhere. With `isBare` omitted or `false`, field chrome always renders, including for standalone inputs without a label. Message values never choose whether the wrapper exists, so adding or removing messages keeps the control mounted and focused. Layout props on the control stay there; use `fieldStyles` to place the entire field.
+- **`forceField`** `boolean` — **Deprecated.** Fields render chrome by default, so remove this prop. It has no presentation effect; `isBare` is the explicit opt-out even if `forceField` is also supplied.
 - **`extra`** `ReactNode` — Additional content displayed next to the label.
 - **`labelTooltip`** `ReactNode` — Content of an info badge shown next to the label. Only rendered when the field has a label. (Formerly `tooltip`. On most fields `tooltip` is gone; on `Select` and `Checkbox` it is the control's own tooltip, as on `Item` and `Button`.)
 - **`labelSuffix`** `ReactNode` — Content displayed after the label text.
 - **`labelProps`** `object` — Additional HTML props passed to the label element.
 - **`labelStyles`** `Styles` — Tasty styles for the label element.
 
+## Field presentation
+
+```jsx
+// Default chrome gives generated errors a place, even without a visible label.
+<TagInput aria-label="Recipients" />
+
+// A row that owns the label and error opts its inner control out explicitly.
+<TextInput isBare aria-label="Amount" aria-describedby="row-error" />
+
+// Suppress only the error slot; keep the label and description.
+<TextInput name="name" label="Name" description="Shown on invoices" errorMessage={null} />
+```
+
+The field wrapper stays in place when a label, description or message appears or disappears. Changing `isBare` changes the presentation structure and may remount the control; keep that mode stable while editing. Individual checkbox and radio options keep their group's inline presentation.
+
+### Field sizing and alignment
+
+Set `fieldStyles` to size the entire field, including its label, description and feedback. Control-level `width`, `styles` and `wrapperStyles` continue to size the control itself:
+
+```jsx
+<TextInput label="Name" fieldStyles={{ width: '40x' }} />
+```
+
+Fields without labels no longer reserve an empty side or split label column. If a row should intentionally align with neighbouring side labels, add `fieldStyles={{ padding: '$full-label-width left' }}`. For a nameless legacy `Form.Item`, put that padding on the item's `styles` instead; it owns the wrapper. Remove deprecated `forceField` when migrating these rows.
+
 ## Necessity Indicators
 
 - **`isRequired`** `boolean` (default: `false`) — Whether user input is required before form submission. Marks the label, sets `aria-required` on the input, and adds a `required` validation rule.
@@ -79,8 +104,8 @@ For modern forms, follow the [use-case guide](./components/form/ModernForm.md).
 - **`rulesKey`** `string` — Manual modern function revision. Skips validator/transform source comparison; declarative constraints are always compared. Update it when a function or its captures change.
 - **`errorPolicy`** `'first' | 'all'` — Modern rule error collection policy, inherited from the controller by default.
 - **`showValid`** `boolean` — Whether to show the valid state icon after successful validation.
-- **`errorMessage`** `ReactNode` — Error message always displayed in danger state, regardless of validation state.
-- **`message`** `ReactNode` — _(deprecated)_ Use `errorMessage` for errors and `description` for help text.
+- **`errorMessage`** `ReactNode` — Error text displayed in danger state, regardless of validation state. `undefined` allows the form-generated error or the deprecated `message` fallback. An explicit `null`, `false` or empty string suppresses the error text and its fallback, while the control retains its invalid state. The description remains visible.
+- **`message`** `ReactNode` — _(deprecated)_ Fallback text used only when `errorMessage` is `undefined`. Use `errorMessage` for errors and `description` for help text. `message={null}` does not suppress a generated `errorMessage`.
 
 ## Styling
 

package/docs/Theming.md

@@ -414,7 +414,7 @@ Note the distinction from `contrastLevel`: the level is a config seed the app su
 
 ## `<Root palette>`
 
-`<Root>` accepts the same config as a prop, applied during render so the first paint is already correct:
+`<Root>` accepts the same config as a prop. The first mount applies it during render, so the first paint (and SSR output) is already correct. A later change applies in a layout effect, which still lands before paint and does not update other components while `<Root>` renders, so the prop alone is enough — there is no need to call `setPaletteConfig()` before changing it:
 
 ```tsx
 <Root palette={{ accent: userBrandColor }}>
@@ -429,6 +429,7 @@ Removing the prop entirely is the one thing that does _not_ reset the palette
 This is a convenience wrapper over `setPaletteConfig()`, not a separate scope. **The palette is process-global** — Glaze's own config is, and so is the single `body` rule the tokens are injected into. One palette per process, not per tree and not per request:
 
 - Two `<Root>`s with different `palette` props will fight over the same tokens.
+- `<Root>`'s layout effect runs after its descendants' layout effects in the same commit, so a `setPaletteConfig()` call from a descendant's layout effect in a commit that also mounts `<Root>` or changes its `palette` loses to the prop. Call it from a passive effect or an event handler instead. A `<Root>` that mounts while another tree is already rendered also applies its palette during its first render, which updates that tree mid-render and makes React warn.
 - Under SSR, apply the palette in code that runs on **both** server and client. A client-only `setPaletteConfig` disposes and replaces the server-rendered token block on the first render, which is visible as a flash. Per-request palettes are not supported.
 
 ## Caveats

package/docs/Usage.md

@@ -496,3 +496,5 @@ Inputs subscribe to their own values and errors. For other reactive UI, use `For
 ### Shared field integration
 
 Built-in inputs have field support; they do not need a `Field` wrapper. Modern `name` and `field` bindings, and legacy string `name` bindings, connect through `useFieldProps`. Custom controls use that hook and `wrapWithField`. [Field Properties](./FieldProperties.md) documents shared labels, validation, state, and presentation props.
+
+Fields render stable chrome by default, including without a visible label. Use `isBare` for inline controls or when a parent owns the field layout and feedback; a supplied label remains accessible but visually hidden. Message content never chooses whether the wrapper exists. `errorMessage={null}` suppresses error text and its fallback while preserving the description and invalid state.

package/docs/components/Root.md

@@ -13,7 +13,7 @@ The root application wrapper. Provides theme context, global styles, portal cont
 - **`navigation`** `NavigationAdapter` — Custom navigation adapter for routing
 - **`tracking`** `TrackingProps` — Analytics/tracking event configuration
 - **`tokens`** `Record<string, string>` — Custom design tokens (CSS custom properties)
-- **`palette`** `PaletteConfig` — Tune the generated color palette. Every zone — `accent`, `base` and each status theme — takes the same seed: a color, or `{ hue, saturation }`. Plus the global `surfaceMode`, `pastel` and `contrastLevel`. Applied during render, so the first paint is already correct. Describes the whole palette, so dropping a field drops that customization. A convenience wrapper over `setPaletteConfig()` — the palette is process-global, not per tree. See [Theming](../Theming.md)
+- **`palette`** `PaletteConfig` — Tune the generated color palette. Every zone — `accent`, `base` and each status theme — takes the same seed: a color, or `{ hue, saturation }`. Plus the global `surfaceMode`, `pastel` and `contrastLevel`. The first mount applies it during render, so the first paint is already correct; a later change applies in a layout effect, still before paint. Describes the whole palette, so dropping a field drops that customization. A convenience wrapper over `setPaletteConfig()` — the palette is process-global, not per tree. See [Theming](../Theming.md)
 - **`fonts`** `boolean` — Whether to load default fonts
 - **`font`** `string` — Custom font family name
 - **`monospaceFont`** `string` — Custom monospace font family name

package/docs/components/actions/Button.md

@@ -25,7 +25,7 @@ A versatile action component that triggers commands and navigates users.
 - **`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
 - **`isDisabled`** `boolean` (default: `false`) — Disables the button. Unlike fields, a button doesn't inherit this from `<Provider isDisabled>` or `<Form isDisabled>`, so actions such as Cancel stay live in a disabled form; pass it to each button you want disabled. Of the buttons, only `Form.Submit` and `Form.Reset` inherit it. `ItemButton` behaves like `Button`, and `ItemAction` inherits only its parent item's disabled state
-- **`isLoading`** `boolean` (default: `false`) — Show loading spinner and disable interactions
+- **`isLoading`** `boolean` (default: `false`) — Show loading spinner and disable interactions. A button that is only loading keeps the focus it has, so a keyboard press that starts the work does not drop focus to the page; it is marked `aria-disabled` and `aria-busy` and Tab skips it until loading ends. A button that is also `isDisabled` is natively disabled
 - **`isSelected`** `boolean` (default: `false`) — Marks the button as pressed / selected (toggle)
 - **`to`** `string` — Destination URL or route; prefix with `!` to open in new tab, `@` to bypass router
 - **`htmlType`** `'button' | 'submit' | 'reset'` — HTML button type attribute
@@ -198,6 +198,10 @@ import { IconPlus } from '@tabler/icons-react';
 
 A disabled button keeps showing its tooltip. Browsers stop dispatching mouse events on elements carrying the native `disabled` attribute, so a button that has a tooltip is marked with `aria-disabled` instead and kept inert: `onPress` never fires and clicks (including the ones Enter and Space produce) do nothing. Such a button also stays in the tab order, so keyboard users can focus it, see its focus ring and read the tooltip, and the keys that would open a `MenuTrigger` menu do nothing. Buttons rendered as links (`to`) are always marked this way, since `disabled` is not a valid attribute on an anchor.
 
+Only a tooltip you pass counts: a string, or an object with a `title` and no `auto: true`. The automatic tooltip that shows a truncated label depends on the layout, so a disabled button with only that one stays natively disabled, and whether it is a Tab stop does not change with the window width.
+
+Give a disabled button its own `tooltip` rather than wrapping it in a `TooltipProvider`: a natively disabled button receives neither hover nor focus, so a tooltip around it never opens.
+
 ### Custom Size
 
 ```jsx
@@ -229,7 +233,9 @@ A disabled button keeps showing its tooltip. Browsers stop dispatching mouse eve
 
 - `aria-label`, `aria-labelledby` – Accessible name.
 - `aria-pressed` – Derived from `isSelected`. Not emitted when the button renders as a link (`to`) or when the call site sets its own `role` — a button acting as a tab or an option wants `aria-selected` / `aria-current` instead. An explicit `aria-pressed` always wins.
-- `aria-disabled` – Announces the disabled state whenever the native `disabled` attribute cannot be used: on links, and on buttons that carry a tooltip.
+- `aria-disabled` – Announces the disabled state whenever the native `disabled` attribute cannot be used: on links, on buttons that carry a tooltip you passed, and on buttons that are only loading.
+- `aria-busy` – Set while `isLoading`.
+- `aria-describedby` – An open tooltip is added to the button's own description, after it.
 - Additional ARIA attributes supported by React Aria's `useButton`.
 
 ## Behaviour Inside Popovers

package/docs/components/actions/ButtonSplit.md

@@ -50,7 +50,33 @@ These properties allow direct style application without using the `styles` prop:
 
 ### Context Inheritance
 
-`type`, `theme`, `size`, and `isDisabled` set on `Button.Split` are inherited by all child `Button` components via context. Explicitly passed props on individual buttons always take precedence.
+`type`, `theme`, `size`, and `isDisabled` set on `Button.Split` are inherited via context by every `Button` in the split, including a `Button` that a `DialogTrigger` or `Menu.Trigger` in the split uses as its trigger. A `type`, `theme` or `size` passed to an individual `Button` takes precedence. `isDisabled` does not: a disabled split disables every `Button` in it, whatever that `Button`'s own `isDisabled`.
+
+Inheritance stops at the overlay. Buttons in a popover, dialog or menu opened from the split keep their own defaults, so a confirm popover's Cancel button is neither restyled nor disabled by the split. A `Button.Split` rendered inside such an overlay styles its own Buttons as usual.
+
+```jsx
+<Button.Split type="primary" size="small" isDisabled={isShipping}>
+  <DialogTrigger type="popover">
+    <Button>Ship</Button>
+    <Dialog>
+      <Content>Ship these changes?</Content>
+      <Footer>
+        {/* not restyled or disabled by the split: each keeps its own props */}
+        <Button type="primary" onPress={ship}>
+          Ship now
+        </Button>
+        <Button>Cancel</Button>
+      </Footer>
+    </Dialog>
+  </DialogTrigger>
+  <Menu.Trigger placement="bottom end">
+    <Button aria-label="More ship options" icon={<DirectionIcon to="down" />} />
+    <Menu onAction={onShipOption}>
+      <Menu.Item key="schedule">Schedule…</Menu.Item>
+    </Menu>
+  </Menu.Trigger>
+</Button.Split>
+```
 
 ## Modes
 

package/docs/components/actions/Link.md

@@ -59,7 +59,7 @@ These properties allow direct style application without using the `styles` prop:
 <Link to="../parent-page">Parent</Link>
 ```
 
-A string is external only when it starts with a URL scheme (`https:`, `mailto:`, `tel:`) or with `//`. A colon later in a path or query, as in `/models/cube:orders` or `..?thread=a:b`, stays router navigation. Write a relative path whose first segment holds a colon as `./cube:orders`.
+A string is external only when it starts with a URL scheme (`https:`, `mailto:`, `tel:`) or with `//`. A colon later in a path or query, as in `/models/cube:orders` or `..?thread=a:b`, stays router navigation. Write a relative path whose first segment holds a colon as `./cube:orders`. Leading and trailing spaces and control characters are dropped first, as the browser's URL parser drops them, so `" https://cube.dev"` is external and `" /pricing"` navigates to `/pricing`. A no-break space is kept, as the parser keeps it.
 
 ### 2) Open in a new tab (`!` prefix)
 

package/docs/components/actions/Menu.md

@@ -178,7 +178,7 @@ For detailed information about all available item properties, see [Item document
 
 #### Navigation Items
 
-Navigation items render native anchors. An ordinary click or Enter/Space activation uses the navigation adapter passed to [Root](../Root.md) and closes the menu. Without a custom adapter, activation stays native and preserves the anchor's attributes. Modified clicks, middle clicks, downloads, other targets, and external destinations retain browser link behavior. Right-click offers the browser's link commands. Disabled links have no destination and cannot navigate.
+Navigation items render native anchors. An ordinary click or Enter/Space activation uses the navigation adapter passed to [Root](../Root.md) and closes the menu. Without a custom adapter, activation stays native and preserves the anchor's attributes. Modified clicks, middle clicks, downloads, other targets, and external destinations retain browser link behavior. A `to` or `href` is told external the same way as a [Link](./Link.md) `to`, after dropping the spaces and control characters the browser drops around a URL. Right-click offers the browser's link commands. Disabled links have no destination and cannot navigate.
 
 Loading items are disabled by default. Set `isDisabled={false}` to keep a loading item available; `disabledKeys` still applies.
 
@@ -213,7 +213,7 @@ An item's `onAction()` and the Menu's `onAction(key)` compose: when both are sup
 
 Use the item callback for a command that belongs to that item, or handle commands centrally using the Menu callback and item keys. Supplying both is useful for additional observation, such as recording an activation; avoid executing the same command in both callbacks.
 
-The native link target covers the complete row, including padding, gaps and whitespace. Right-click anywhere on that target offers the browser's link commands. Independent controls in the prefix, suffix or actions slots retain their own targets. The primary native anchor owns menu-item semantics and keyboard focus, while Item's original list element owns layout and styling. Command content has no link destination.
+The native link target covers the complete row, including padding, gaps and whitespace. The icon, label and description pass pointer presses through to it, so it receives every click, modified click, middle click and right-click on the row, however long the text. Right-click anywhere on that target offers the browser's link commands. Independent controls in the prefix, suffix or actions slots retain their own targets. The primary native anchor owns menu-item semantics and keyboard focus, while Item's original list element owns layout and styling. Command content has no link destination.
 
 #### Inline Actions
 
@@ -273,6 +273,8 @@ Do not use the forwarded row ref or a role selector as a proxy for the primary f
 
 Use named style slots or their `data-element` markers for content styling. Selectors that depend on the Label, Description or Icon being a particular HTML tag need to allow their native anchor host. A private native target is also a child of the row; use slot markers instead of child-position selectors for content.
 
+In tests, click a navigation row, or a command row with inline actions, through its role, as `getByRole('menuitem', { name })`, rather than through its label, description or icon. Those slots let presses through to the primary anchor, so a click on them fails: a browser test reports that the anchor "intercepts pointer events", and jsdom's user-event rejects an element with `pointer-events: none`.
+
 #### Example with Rich Items
 
 ```jsx

package/docs/components/content/InfoBadge.md

@@ -29,6 +29,8 @@ Every field's `labelTooltip` prop already renders an `InfoBadge` next to the lab
 
 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).
 
+A non-interactive badge is exposed as `role="img"` with that name and is not a Tab stop. When `aria-label` replaces a plain-text tooltip as the name, the tooltip text becomes the badge's description, so screen reader users still get it. Rich tooltip content on a non-interactive badge opens on hover only; make the badge interactive (`to` or `onPress`) when keyboard users need to read it.
+
 ### Base Properties
 
 Supports [Base properties](../../BaseProperties.md).

package/docs/components/content/ItemBadge.md

@@ -17,6 +17,10 @@ A non-interactive badge indicator for list items. Similar to `ItemAction` but wi
 - **`isSelected`** `boolean` (default: `false`) — Selected state (for checkmark)
 - **`tooltip`** `string | object` — Tooltip content shown on hover for icon-only badges. A string shows tooltip text; an object supports `{ title, ...tooltipProps }` for advanced configuration.
 
+### Accessibility
+
+A badge is never focusable. An icon-only badge with a name — `aria-label`, or a plain-text `tooltip` — is exposed as `role="img"` with that name. When the name is not the tooltip text, the tooltip text also becomes the badge's description (`aria-description`), so screen reader users get it without hovering. Rich tooltip content has no plain text, so it is available on hover only. Pass `role` to use another role.
+
 ### Base Properties
 
 Supports [Base properties](../../BaseProperties.md).

package/docs/components/content/Layout.md

@@ -226,6 +226,7 @@ Footer area with support for inverted content order (primary actions on right).
 
 - **`invertOrder`** `boolean` (default: `false`) — Reverse child order (primary on right)
 - **`children`** `ReactNode` — Footer content
+- **`role`** `string` — Overrides the landmark role. The footer of a top-level Layout is `contentinfo`; a footer inside a panel or a nested Layout gets `role="none"`, so it adds no landmark. To name such a footer, pass `role="group"` with an `aria-label`.
 
 ---
 
@@ -265,7 +266,7 @@ Collapsible side panel with resizing, transitions, and multiple rendering modes.
 - **`onSizeChange`** `(size: number) => void` — Size change callback
 - **`sizeStorageKey`** `string` — localStorage key for persisting size
 - **`hasTransition`** `boolean` (default: `false`) — Enable slide animation
-- **`isDismissable`** `boolean` (default: `true`) — Allow dismissing overlay/dialog by click or Escape
+- **`isDismissable`** `boolean` (default: `true`) — Allow dismissing overlay/dialog by click or Escape, and an overlay panel by focus moving into the main content
 - **`overlayStyles`** `Styles` — Styles for the overlay backdrop in overlay mode
 - **`isDialogOpen`** `boolean` — Controlled dialog state (mode="dialog")
 - **`defaultIsDialogOpen`** `boolean` (default: `false`) — Initial dialog state
@@ -278,7 +279,7 @@ Collapsible side panel with resizing, transitions, and multiple rendering modes.
 
 - `default` — Standard panel that pushes content aside (propagates size, no overlay)
 - `sticky` — Panel floats over content without affecting layout (no size propagation, no overlay)
-- `overlay` — Panel with dismissable backdrop overlay (propagates size, with overlay)
+- `overlay` — Panel floats over content with a dismissable backdrop overlay (no size propagation, with overlay)
 - `dialog` — Panel renders as a modal dialog (no size propagation, overlay via Dialog)
 
 **Modifiers:**
@@ -634,6 +635,8 @@ In `overlay` mode, a semi-transparent backdrop appears behind the panel. The pan
 - Pressing Escape anywhere in the Layout
 - Moving focus to the main content area
 
+Focus closes the panel only when it enters the main content from outside it, for example with a programmatic `focus()`, `Tab` from a control before the Layout, or `Shift+Tab` out of the panel when no other panel comes before it; moving between controls of the main content does not. Panels come after the main content in tab order, so `Tab` from the panel's last control leaves the Layout and keeps the panel open. Focus moving inside the panel, into a popover, menu or dialog opened from it, or into another `Layout.Panel` of the same Layout keeps it open. Other panels of the same Layout can sit under the backdrop; a click on them then closes the overlay panel, but `Tab` still reaches their controls. Opening the panel moves focus to its first control, unless focus already moved elsewhere as it opened (for example to a field with `autoFocus` inside it), so a menu or dialog that opened it can close without handing focus back to the main content. A panel already open when its Layout first renders leaves page focus alone. Closing the panel returns focus to the element that had it when the panel opened, if focus is still in the panel or was lost with it; focus moved elsewhere, by the user or in `onOpenChange`, stays there. If that element is gone by then, as a menu item is, move focus yourself in `onOpenChange`.
+
 ```jsx
 function OverlayPanelExample() {
   const [isPanelOpen, setIsPanelOpen] = useState(true);
@@ -669,7 +672,7 @@ You can customize the overlay styles using the `overlayStyles` prop:
 </Layout.Panel>
 ```
 
-To prevent dismissing the overlay by clicking or pressing Escape, set `isDismissable={false}`:
+To prevent dismissing the overlay by clicking, pressing Escape or moving focus to the main content, set `isDismissable={false}`:
 
 ```jsx
 <Layout.Panel mode="overlay" isDismissable={false}>
@@ -788,7 +791,9 @@ function ApplicationShell() {
 ### Keyboard Navigation
 
 - `Tab` - Navigate between interactive elements
-- Focus management is handled automatically when panels open/close
+- An overlay panel closes on Escape or when focus enters the main content from outside it; focus moving inside it or into another panel of the same Layout keeps it open
+- Panels come after the main content in tab order, so `Tab` from a panel's last control leaves the Layout
+- An overlay panel moves focus to its first control when it opens and returns it to the opener when it closes; in `dialog` mode the dialog manages focus, and other modes leave focus alone
 - Resize handlers can be focused and resized using arrow keys:
   - `Arrow keys` - Resize panel by 10px
   - `Shift + Arrow keys` - Resize panel by 50px
@@ -798,7 +803,7 @@ function ApplicationShell() {
 
 - `Layout.Header` uses semantic heading elements (`h1`-`h6`) based on `level` prop
 - `Layout.Toolbar` has `role="toolbar"` for proper announcement
-- `Layout.Footer` has `role="contentinfo"` for landmark navigation
+- `Layout.Footer` of a top-level Layout has `role="contentinfo"` for landmark navigation; footers inside panels and nested Layouts add no landmark
 - Breadcrumbs use Link components with proper navigation semantics
 - Panel close buttons have accessible labels
 

package/docs/components/fields/ComboBox.md

@@ -27,19 +27,19 @@ A combobox component that combines a text input with a dropdown list, allowing u
 - **`selectedKey`** `string` — The currently selected key (controlled)
 - **`defaultSelectedKey`** `string` — The key of the initially selected item (uncontrolled)
 - **`allowsCustomValue`** `boolean` (default: `false`) — Whether the combo box allows custom values to be entered
-- **`shouldCommitOnBlur`** `boolean` (default: `true`) — Whether to commit custom value on blur in allowsCustomValue mode
-- **`clearOnBlur`** `boolean` (default: `false`) — Whether to clear selection and input on blur (only applies to non-custom-value mode)
+- **`shouldCommitOnBlur`** `boolean` (default: `true`) — Whether to commit custom value on blur in allowsCustomValue mode. When `false`, blur discards the uncommitted text
+- **`clearOnBlur`** `boolean` (default: `false`) — Whether to clear selection and input on blur when the text names no selectable item (only applies to non-custom-value mode)
 - **`isClearable`** `boolean` (default: `false`) — Whether the combo box is clearable using ESC keyboard button or clear button inside the input
 - **`sortSelectedToTop`** `boolean` (default: `true when items provided, false otherwise`) — Whether to sort selected item to the top when popover opens (only works with items prop)
-- **`popoverTrigger`** `'focus' | 'input' | 'manual'` (default: `input`) — How the popover is triggered
+- **`popoverTrigger`** `'focus' | 'input' | 'manual'` (default: `input`) — When the list opens on its own, see **popoverTrigger** below
 - **`filter`** `((textValue: string, inputValue: string) => boolean) | false` — Custom filter function or false to disable filtering. If not provided, uses default contains filter
 - **`hideTrigger`** `boolean` (default: `false`) — Whether to hide the trigger button
-- **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — ComboBox size
+- **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — ComboBox size, which the options in the list share
 - **`listGap`** `number` — Space between options, in pixels. Defaults to a hairline (`1bw`)
 - **`necessityIndicator`** `'label' | 'icon'` — How the required state should be indicated
 - **`onSelectionChange`** `(key: Key | null) => void` — Callback fired when the selected option changes
 - **`onInputChange`** `(value: string) => void` — Callback fired when the input text changes
-- **`onOpenChange`** `(isOpen: boolean) => void` — Callback fired when the popover opens or closes
+- **`onOpenChange`** `(isOpen: boolean) => void` — Callback fired when the list shows or hides. Not called on mount, nor while typed text that matches nothing keeps the list hidden
 - **`prefix`** `ReactNode` — Content rendered before the input
 - **`suffix`** `ReactNode` — Content rendered after the input
 - **`suffixPosition`** `'before' | 'after'` (default: `before`) — Position of suffix relative to validation/loading icons
@@ -56,7 +56,7 @@ A combobox component that combines a text input with a dropdown list, allowing u
 
 #### Notable Properties
 
-**onKeyDown** - Runs before ComboBox's own key handling, listed under [Keyboard Navigation](#keyboard-navigation). Calling `e.preventDefault()` takes the key over: ComboBox skips its handling for that event, so a prevented `ArrowDown` does not open the popover or move focus, and a prevented `Enter` does not select the focused option or commit a custom value. Without `preventDefault()` the built-in handling runs as usual after your handler. The event is React Aria's keyboard event (`KeyboardEvent` from `@react-types/shared`), whose propagation stops at the input unless you call `e.continuePropagation()`.
+**onKeyDown** - Runs before ComboBox's own key handling, listed under [Keyboard Navigation](#keyboard-navigation). Calling `e.preventDefault()` takes the key over: ComboBox skips its handling for that event, so a prevented `ArrowDown` does not open the popover or move focus, and a prevented `Enter` does not select the focused option or commit a custom value. Without `preventDefault()` the built-in handling runs as usual after your handler. The event is React Aria's keyboard event (`KeyboardEvent` from `@react-types/shared`). `Escape` and `Tab` go on to ancestors, so a surrounding `Dialog` still closes on `Escape` and keeps `Tab` inside, unless ComboBox acts on them: `Escape` that closes the list or clears the value stops at the input. Other keys stop at the input unless you call `e.continuePropagation()`.
 
 ```jsx
 <ComboBox
@@ -76,7 +76,7 @@ A combobox component that combines a text input with a dropdown list, allowing u
 </ComboBox>
 ```
 
-**Enter inside a form.** `preventDefault()` stops the browser's form submission and ComboBox's own handling together; it cannot stop just one. With `allowsCustomValue`, the popover closed and text that matches no option, the built-in `Enter` commits the typed value and lets the event through, so the surrounding form submits. A handler that prevents that `Enter` stops both: the form does not submit, and the value is not committed until the input loses focus (when `shouldCommitOnBlur` is on, the default). In earlier versions such a handler stopped only the submit, and the value was still committed on `Enter`. To keep that behavior, commit the value in your handler:
+**Enter inside a form.** `preventDefault()` stops the browser's form submission and ComboBox's own handling together; it cannot stop just one. With `allowsCustomValue` and the popover closed, the built-in `Enter` commits the typed value and lets the event through, so the surrounding form submits. A handler that prevents that `Enter` stops both: the form does not submit, and the value is not committed until the input loses focus (when `shouldCommitOnBlur` is on, the default). In earlier versions such a handler stopped only the submit, and the value was still committed on `Enter`. To keep that behavior, commit the value in your handler:
 
 ```jsx
 const [selectedKey, setSelectedKey] = useState(null);
@@ -106,17 +106,25 @@ const [selectedKey, setSelectedKey] = useState(null);
 
 **sortSelectedToTop** - When using the `items` prop (data-driven mode), the selected item will automatically appear at the top of the list when the popover opens. This is enabled by default when using `items`, but disabled when using JSX children. Set to `false` to maintain the original order.
 
-**allowsCustomValue** - Enables users to enter values that aren't in the predefined options list. Custom values can be committed by pressing Enter or on blur (controlled by `shouldCommitOnBlur`). **Important**: When enabled, typing in the input will clear the current selection. When disabled (default), typing only filters the options without clearing the selection.
+**allowsCustomValue** - Enables users to enter values that aren't in the predefined options list. Custom values can be committed by pressing Enter or on blur (controlled by `shouldCommitOnBlur`). With the list open, Enter picks the highlighted option; with it closed (press `Escape` first), Enter commits the typed text, even when it is part of an option's label. The text is committed trimmed, and empty or whitespace-only text clears the selection (`null`). **Important**: When enabled, typing in the input will clear the current selection. When disabled (default), typing only filters the options without clearing the selection.
 
-**shouldCommitOnBlur** - When `true` (default), custom values are committed when the input loses focus. When `false`, custom values only commit when Enter is pressed. Only applies when `allowsCustomValue` is enabled.
+**shouldCommitOnBlur** - When `true` (default), custom values are committed when the input loses focus. When `false`, only Enter or picking an option commits, and leaving the input discards the uncommitted text: the input shows the selected option's label again, so the text always agrees with the value. As typing clears the selection, that usually leaves the input empty. Only applies when `allowsCustomValue` is enabled.
 
-**clearOnBlur** - When `true`, clears both the selection and input when the input loses focus. When `false` (default), the input reverts to showing the current selection. Only applies to non-custom-value mode. Useful for search-like scenarios where you want to reset after each interaction.
+**isReadOnly** - The list doesn't open, from the chevron, the arrow keys, a press in the input or focus, and neither keys nor blur change the value or the text. The clear button is hidden.
+
+**clearOnBlur** - When `true`, text that names no selectable item clears both the selection and the input when the input loses focus. When `false` (default), the input reverts to showing the current selection, and empty text still clears it. Only applies to non-custom-value mode. Useful for search-like scenarios where you want to reset after each interaction.
+
+**Blur** - Without `allowsCustomValue`, leaving the input selects the item the text names exactly, or else the only item it still matches, unless that item is in `disabledKeys`. The exact match follows the filter's rules for case, accents and locale. Among items sharing the label, the selected one wins, then the first enabled one. Empty text clears the selection. Other text reverts to the selection, or clears with `clearOnBlur`; a disabled item that is already selected stays selected. Blur reports only what it changes: leaving a field without editing it calls neither `onSelectionChange` nor `onInputChange`.
+
+**Presses in the input** - A press in the input opens a closed list, whether the input already had focus or not, unless `popoverTrigger` is `manual`. The list shows the options the typed text leaves, and text that matches nothing keeps it hidden, so a press that moves the caret does not change what `Enter` commits; the chevron and the arrow keys show every option instead. A press in the input while the list is open only moves the caret; the chevron still toggles the list. A click on the field label only focuses the input.
+
+**Outside presses** - While the list is open, a press on an enabled control outside it reaches the control on the first click, after the typed text settles as it does on `Tab`. The control has to be in the dialog, popover or menu the field sits in, or anywhere on the page when the field is in none; an enabled UI Kit `Button` or `ItemButton` is reached from anywhere. A press anywhere else, such as blank space, a dialog's backdrop or a control outside the field's dialog or popover, only closes the list and keeps the input focused with its text. A press on a disabled control keeps the focus and text too; the list stays open unless the control is only `aria-disabled`.
 
 **popoverTrigger** - Controls how the popover opens:
 
 - `manual` - Only opens via trigger button or arrow keys
-- `input` (default) - Opens when user types + manual triggers
-- `focus` - Opens on input focus + typing + manual triggers
+- `input` (default) - Opens when the user types or presses the input + manual triggers
+- `focus` - Opens on input focus + typing + presses + manual triggers
 
 **filter** - Custom filter function or `false` to disable filtering. By default, uses a contains-based filter. Provide a custom function `(textValue, inputValue) => boolean` to customize filtering logic.
 
@@ -204,8 +212,8 @@ The `mods` property accepts the following modifiers you can override:
 ### Popover Trigger Modes
 
 - `manual` - Only opens via trigger button or arrow keys
-- `input` - Opens when user types + manual triggers (default)
-- `focus` - Opens on input focus + typing + manual triggers
+- `input` - Opens when the user types or presses the input + manual triggers (default)
+- `focus` - Opens on input focus + typing + presses + manual triggers
 
 ### Validation States
 
@@ -362,6 +370,8 @@ const categories = [
 
 ### Loading State
 
+The input shows the selected option's label. A `selectedKey` whose option has not loaded yet shows the key until the option arrives. Once the input has shown a label for the selected key, it keeps that label while the options leave the item out, for example during a refetch or a server-side search.
+
 ```jsx
 <ComboBox isLoading label="Fruit" placeholder="Select a fruit...">
   <ComboBox.Item key="apple">Apple</ComboBox.Item>
@@ -561,11 +571,11 @@ const [selectedKey, setSelectedKey] = useState(null);
 
 ### Keyboard Navigation
 
-- `Tab` - Moves focus to/from the combobox input
+- `Tab` - Moves focus to/from the combobox input and closes the popover. The chevron and clear buttons are not Tab stops
 - `ArrowDown` - Opens popover (if closed) or moves focus to next option
 - `ArrowUp` - Opens popover (if closed) or moves focus to previous option
-- `Enter` - Selects the focused option and closes popover
-- `Escape` - Closes popover (if open) or clears input (if clearable and popover closed)
+- `Enter` - Selects the focused option and closes popover. Pressed right after typing, it picks the first match. With `allowsCustomValue` and the popover closed, commits the typed text. Ignored while an input method (IME) is composing text
+- `Escape` - Closes popover (if open) or clears input (if clearable and popover closed); otherwise it goes on, so a surrounding dialog closes
 - `Home` - Moves focus to the first option (when popover is open)
 - `End` - Moves focus to the last option (when popover is open)
 - Typing - Filters options based on input value
@@ -584,10 +594,11 @@ An `onKeyDown` handler runs before all of these and can skip any of them for a k
 ### ARIA Properties
 
 - `role="combobox"` - Identifies the input as a combobox
-- `aria-expanded` - Indicates whether the popover is open or closed
+- `aria-expanded` - Indicates whether the list is shown
 - `aria-haspopup="listbox"` - Indicates the combobox has a listbox popup
+- `aria-autocomplete="list"` - Indicates that typing filters the options
 - `aria-controls` - References the listbox ID when popover is open
-- `aria-activedescendant` - References the currently focused option
+- `aria-activedescendant` - References the currently focused option, while it is shown
 - `aria-label` - Provides accessible label when no visible label exists
 - `aria-required` - Indicates required fields
 - `aria-invalid` - Indicates validation errors

package/docs/components/fields/FilterListBox.md

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

package/docs/components/fields/FilterPicker.md

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

package/docs/components/fields/ListBox.md

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