@cube-dev/ui-kit 0.196.0 → 0.198.0

package/docs/CreateComponent.md

@@ -19,6 +19,10 @@ Form-aware inputs use `useFieldProps` for both legacy instances and modern contr
 
 The [compiled custom-control example](https://github.com/cube-js/cube-ui-kit/blob/main/typecheck/consumer/modern-form-examples.tsx) shows explicit DOM forwarding, async validation, and default adoption. Shared input rule props accept existing legacy validators; use `ModernValidationRule` for strict modern success/error return types, and adapt legacy validators that resolve data before migrating them.
 
+## Style forwarding through overlays
+
+Forward consumer styles to the element that owns them. DialogContainer's `styles` targets the overlay content shell, while Dialog owns its own root styles. Layout.Panel keeps these channels explicit: `dialogProps.styles` for the shell and `dialogStyles` for its implicit Dialog, separate from inline panel `styles`. Avoid selectors that reach through the overlay to override its child.
+
 ## Core Concepts
 
 ### 1. Base Properties with `filterBaseProps`
@@ -425,7 +429,7 @@ 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.
+Call `wrapWithField(control, props)` consistently: it renders the field chrome when the field has something to show, and `isBare` decides when set. Attach the field's ref to the control's own root, as the `Action` above does; the chrome takes none, so the ref reaches the control with or without it, and `labelRef` reaches the label. `useFieldProps` works out whether a field without a label needs the chrome, and asks for it with `isBare={false}`; a control that shows messages of its own asks the same way after it, with `isBare: props.isBare ?? false`, as `TagInput` does. A control that shows the errors of its `validate` passes `showsValidateErrors: true` to `useFieldProps`, so a `validate` asks too. Never infer presentation from 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, written after any spread of the parent's resolved props, which can carry `isBare={false}`.
 
 For input components that need to integrate with forms, see the [Field documentation](./components/form/Field.md) for comprehensive guidance on:
 

package/docs/FieldProperties.md

@@ -22,28 +22,32 @@ For modern forms, follow the [use-case guide](./components/form/ModernForm.md).
 - **`label`** `ReactNode` — Label text displayed above or beside the input.
 - **`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.
+- **`isBare`** `boolean` — 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 for an inline control that would otherwise show its chrome but has no room for it, or when a parent already renders that chrome. Provide `aria-describedby` when the error is explained elsewhere. Unset, a field renders its chrome when there is something to show: a non-empty `label`, a form binding, or a `description`, `errorMessage`, `message`, `fieldStyles`, `fieldProps` or `isHidden` prop, whatever it holds. On `TextInput`, `TextArea`, `PasswordInput` and `NumberInput`, which show the errors of a `validate`, that prop counts too. Otherwise it renders only the control. `TagInput` always has something to show: its refusal messages. Pass `isBare={false}` to render the chrome anyway. Layout props on the control stay there; use `fieldStyles` to place the entire field.
+- **`forceField`** `boolean` — **Deprecated.** Use `isBare={false}`. Renders the chrome even with nothing to show; an explicit `isBare` wins.
 - **`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.
+- **`labelRef`** `Ref<HTMLElement>` — The label element, visible or visually hidden with `isBare`; `null` without a `label`. A field's own `ref` is its control's, with or without the field chrome, so a bare field's is never `null`. Reach the field wrapper with `fieldProps={{ ref }}`.
 
 ## Field presentation
 
 ```jsx
-// Default chrome gives generated errors a place, even without a visible label.
-<TagInput aria-label="Recipients" />
+// Nothing to show: only the control renders, with no field wrapper.
+<TextInput aria-label="Search" />
 
-// A row that owns the label and error opts its inner control out explicitly.
-<TextInput isBare aria-label="Amount" aria-describedby="row-error" />
+// A form binding gives generated errors a place, even without a visible label.
+<TextInput name="email" aria-label="Email" rules={[{ required: true, message: 'Enter an email' }]} />
+
+// A bound control in a row that owns the label and error opts out explicitly.
+<TextInput isBare name="amount" 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.
+The field wrapper stays in place when a description or message appears or disappears: a text prop counts whatever it holds, so pass `errorMessage={error}` rather than spreading the prop in only while there is an error. Adding or removing a `label` (an empty one counts as none) or a form binding, or changing `isBare`, changes the presentation structure and may remount the control; keep them stable while editing, or pass `isBare={false}` to keep the wrapper. Individual checkbox and radio options keep their group's inline presentation.
 
 ### Field sizing and alignment
 

package/docs/Theming.md

@@ -261,7 +261,7 @@ setPaletteConfig({ themes: { danger: '#b91c1c', success: { hue: 150 } } });
 
 A status color behaves like the brand's in the ways that matter — the light, normal-contrast fill reproduces it, dark and high contrast adapt, and the softened APCA floors apply instead of the white-anchored ladder's WCAG ones, including the cap that keeps the `#white` label on a `type="primary"` button readable.
 
-**One thing is deliberately different: its chroma becomes the theme's seed.** An accent color's does not, because all four status themes inherit the accent's saturation and raising it would re-chromatise every one of them. Nothing inherits from a status theme, so there is nothing to protect — and moving the seed is what holds the rest of the theme in proportion to the fill. The tinted banner surface, the border and the text ramp are authored as factors of the seed (`0.2`, `0.3`, `0.25`), so with the seed left at `100` beside a muted fill the banner would read as fully tinted under a washed-out button. Moving it keeps the shipped `1.0 : 0.2 : 0.3 : 0.25` ratio exactly.
+**One thing is deliberately different: its chroma becomes the theme's seed.** An accent color's does not, because all four status themes inherit the accent's saturation and raising it would re-chromatise every one of them. Nothing inherits from a status theme, so there is nothing to protect — and moving the seed is what holds the rest of the theme in proportion to the fill. The tinted banner surface, the border and the text ramp are authored as factors of the seed (`0.2`, `0.3`, `0.25`), so with the seed left at `100` beside a muted fill the banner would read as fully tinted under a washed-out button. Moving it keeps the shipped `1.0 : 0.2 : 0.3 : 0.25` ratio exactly, and Alert's own fill and border (`0.6` each, the fill `0.4` in dark) follow the same way.
 
 Two consequences worth stating. A vivid status color under a muted palette gives one vivid theme beside muted siblings — that is the point of naming a color. And under `pastel` the flat ceiling can hold the fill below the color's own chroma while the banner still sits at `0.2` of it, so the ratio drifts slightly; turn pastel off for an exact color, exactly as with the brand.
 

package/docs/Usage.md

@@ -15,6 +15,10 @@ For styling engine internals see the [Tasty documentation](./tasty/usage.md). Ta
 
 Pass your router's `useHref` and `useNavigate` hooks through `Root`'s `navigation` adapter. `Menu.Item`, like `Button`, `ItemButton`, and `Link`, accepts `to` destinations. Its label and description expose native anchors for modified-click, middle-click and link context-menu commands; the complete row supports ordinary click and keyboard activation. Use `navigationOptions` for router options and `target`, `rel`, or `download` for native link behavior. Nested providers and overlays inherit the adapter unless they explicitly supply another one.
 
+## Overlay sizing
+
+DialogContainer accepts `type="tray"` and `styles` for its overlay content shell. Its child Dialog has separate styles and size bounds. Layout.Panel exposes those same channels through `dialogProps.styles` and `dialogStyles` in dialog mode; inline panel styles and stored width remain independent. Keep the tray type and change dimensions to expand it without remounting its content.
+
 ## React Compiler
 
 UI Kit ships components optimized with React Compiler and requires React and React DOM 19.3 or newer. Your application does not need to enable Compiler to use this build. Adoption is incremental: functions with known compatibility diagnostics remain unoptimized, and the legacy form's mutable render paths are explicitly excluded.
@@ -215,6 +219,8 @@ The hues below are the _defaults_; each is tunable at runtime (see [Theming](./T
 
 For example, a success banner uses `fill: '#success-surface'` + `color: '#success-surface-text'`, while a primary button uses `fill: '#primary-accent-surface'` + `color: '#primary-accent-surface-text'`.
 
+The four status themes (`success`, `danger`, `warning`, `note`) add one more pair, `<theme>-alert-surface` and `<theme>-alert-border`, which `Alert` uses. They carry three times the saturation of `<theme>-surface` (twice in dark), so an alert's theme reads at a glance, and they keep `#dark-02` text at AA (AAA in high contrast). `primary`, `purple` and the unprefixed default theme do not have them. The shared `<theme>-surface` / `<theme>-border` stay quieter because the Item family and table tints sit on them.
+
 ### Runtime Theming
 
 `setPaletteConfig()` re-seeds the palette after the kit has mounted; every token re-resolves and `<Root>` re-injects the token block. No component re-render is involved, because every color compiles to a CSS custom property.
@@ -377,7 +383,7 @@ So these helpers do not inspect the value. They read `$tokens-applied`, a marker
 
 All six take `{ element, fallback }`. Pass `element` to read a _local_ override instead of the document — a subtree carrying its own `tokens` prop (`renderColorTokens()`), or one under a `data-scheme` / `data-contrast` that differs from the document's. Pass `fallback` for the value to use when a token cannot be resolved, including during SSR, where there is no DOM to read.
 
-**Why `getComputedStyle` by hand does not work.** `Root` declares the token block on `<body>`, so `<html>`, a detached node, and a tree that has not mounted `Root` yet are all outside it — and a token read from outside does not come back empty. Tasty registers `@property` rules with real `initial-value`s, so `--gap` reads `4px` there rather than the kit's `8px`, `--radius` reads `6px`, `--transition` reads `80ms`. The value looks entirely ordinary and is simply wrong. Inspecting it cannot help in the other direction either: `#clear` really is `transparent` and `$h2-letter-spacing` really is `0px`, indistinguishable from an unset property of the same type.
+**Why `getComputedStyle` by hand does not work.** `Root` declares the token block on `<body>`, so `<html>`, a detached node, and a tree that has not mounted `Root` yet are all outside it — and a token read from outside does not come back empty. Tasty registers `@property` rules with real `initial-value`s, so `--gap` reads `8px` there, `--radius` reads `6px`, `--transition` reads `80ms`. Those are tasty's defaults, matching the kit's own values only by coincidence: the value looks entirely ordinary, and for a token the kit sets differently it is simply wrong. Inspecting it cannot help in the other direction either: `#clear` really is `transparent` and `$h2-letter-spacing` really is `0px`, indistinguishable from an unset property of the same type.
 
 ## Themes
 
@@ -497,4 +503,4 @@ Inputs subscribe to their own values and errors. For other reactive UI, use `For
 
 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.
+Fields render their chrome when there is something to show: a label, a form binding, or a description, message, field styles or props, or `isHidden`, and on `TextInput`, `TextArea`, `PasswordInput` and `NumberInput` a `validate`. A field with none of them renders only the control. Use `isBare` for an inline control with no room for its chrome, or when a parent owns the field layout and feedback; a supplied label remains accessible but visually hidden. `isBare={false}` renders the chrome anyway. 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/content/Alert.md

@@ -12,7 +12,7 @@ An alert message with theme variants. Used for announcements, warnings, and info
 
 ## Properties
 
-- **`theme`** `'note' | 'success' | 'danger' | 'warning' | 'disabled'` (default: `'note'`) — Visual theme
+- **`theme`** `'note' | 'success' | 'danger' | 'warning' | 'special' | 'disabled'` (default: `'note'`) — Visual theme
 - **`type`** — Deprecated, use `theme` instead
 - **`shape`** `'card' | 'sharp'` (default: `'card'`) — `card` shows border radius and border; `sharp` removes both
 
@@ -23,7 +23,8 @@ An alert message with theme variants. Used for announcements, warnings, and info
 - `padding` — `1.5x`
 - `preset` — `t3`
 - `radius` — `1cr` (switches to `0` when `shape="sharp"`)
-- `color` — `#dark-02`
+- `color` — `#dark-02` (`special` uses its white `#primary-accent-surface-text`, the same label a primary button carries on that fill; `disabled` its soft label)
+- `fill` / `border` — per theme. `note`, `success`, `danger` and `warning` use Alert's own `#<theme>-alert-surface` / `#<theme>-alert-border`, a stronger tint than the shared `#<theme>-surface` / `#<theme>-border` the Item family uses. These two tokens exist only on those four themes.
 
 ### Base Properties
 

package/docs/components/content/Layout.md

@@ -266,12 +266,14 @@ 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
+- **`hideOnClose`** `boolean` (default: `false`) — Hide the closed panel instead of unmounting its content, so the content keeps its state (an unsent draft, scroll position, a request in flight) until the panel reopens. The hidden panel takes no space, no focus and no resize handle. The content mounts once, even when the panel starts closed, so mount effects and a native `autoFocus` do not run again on reopen. Content that mounts while closed is hidden: `autoFocus` does nothing and measurements read zero until the panel opens. In dialog mode the dialog is kept the same way, and moves focus itself as a dialog that mounts on open does: to an autofocused kit control on every open, and on close back to its opener, or to the trigger of the menu or popover it sat in once that has closed ([what still differs](../overlays/DialogContainer.md#focus-with-hideonclose)); `dialogProps.hideOnClose` takes precedence
 - **`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
 - **`onDialogOpenChange`** `(isOpen: boolean) => void` — Dialog state callback
-- **`dialogProps`** `CubeDialogContainerProps` — Props for dialog mode
+- **`dialogProps`** `CubeDialogContainerProps` — Props for DialogContainer in dialog mode, including `type="tray"` and overlay-shell `styles`
+- **`dialogStyles`** `Styles` — Styles for the inner Dialog root in dialog mode; inline panel `styles` remain independent
 - **`innerRef`** `ForwardedRef<HTMLDivElement>` — Ref for the inner content element
 - **`innerProps`** `HTMLAttributes<HTMLDivElement>` — Props to spread on the Inner sub-element
 
@@ -289,6 +291,7 @@ Collapsible side panel with resizing, transitions, and multiple rendering modes.
 - `horizontal` `boolean` — Left or right panel
 - `has-transition` `boolean` — Transition enabled
 - `offscreen` `boolean` — Panel is collapsed
+- `hidden` `boolean` — Closed panel kept mounted by `hideOnClose`
 
 ---
 
@@ -497,6 +500,35 @@ function ResizablePanelExample() {
 }
 ```
 
+### Expandable Panel Tray
+
+```jsx
+const dimensions = {
+  width: expanded ? '100dvw' : '(100dvw - 2x)',
+  height: expanded ? '100dvh' : '60dvh',
+};
+
+<Layout height="100dvh">
+  <Layout.Panel
+    side="right"
+    mode="dialog"
+    isDialogOpen={isOpen}
+    onDialogOpenChange={setIsOpen}
+    dialogProps={{ type: 'tray', styles: dimensions }}
+    dialogStyles={dimensions}
+  >
+    <Button onPress={() => setExpanded(!expanded)}>
+      {expanded ? 'Collapse' : 'Expand'}
+    </Button>
+    <Button onPress={() => setIsOpen(false)}>Close chat</Button>
+    {/* Conversation and composer */}
+  </Layout.Panel>
+  <Layout.Content>{/* Page content */}</Layout.Content>
+</Layout>
+```
+
+`dialogProps.styles` sizes the overlay shell; `dialogStyles` sizes its Dialog root. Both have independent default bounds. Keep the native tray type while expanding its dimensions to preserve mounted content, input selection and local state. Switching tray to a modal/fullscreen type remounts the overlay subtree. The tray retains native modal focus, backdrop and dismissal behavior in either size. Layout.Panel suppresses the built-in visible Close button; provide your own Close action. Its inline size and `sizeStorageKey` are independent of these dialog styles.
+
 ### Persistent Panel Size
 
 Use `sizeStorageKey` to persist panel size to localStorage. The size is automatically restored on mount.
@@ -561,6 +593,51 @@ function PanelWithTransitionExample() {
 }
 ```
 
+### Keep Panel Content Mounted
+
+With `hideOnClose`, a closed panel is hidden instead of unmounted, so an unsent message or a running request survives closing it. The content does not remount on reopen, so move focus yourself when the panel opens, without scrolling: the panel enters from offscreen. In dialog mode the dialog moves focus in itself, and back to its opener on close, or to the trigger of the menu or popover it sat in once that has closed ([what still differs](../overlays/DialogContainer.md#focus-with-hideonclose)). Menus and popovers opened from the panel stay open when code closes it, so close them first.
+
+```jsx
+function ChatPanelExample() {
+  const [isOpen, setIsOpen] = useState(false);
+  const messageRef = useRef(null);
+
+  useEffect(() => {
+    if (isOpen) messageRef.current?.focus({ preventScroll: true });
+  }, [isOpen]);
+
+  return (
+    <Layout height="100dvh">
+      <Layout.Panel
+        hideOnClose
+        hasTransition
+        side="right"
+        size={320}
+        isOpen={isOpen}
+        onOpenChange={setIsOpen}
+      >
+        <Layout.PanelHeader
+          isClosable
+          title="Chat"
+          onClose={() => setIsOpen(false)}
+        />
+        <Layout.Content>
+          <TextArea label="Message" inputRef={messageRef} />
+        </Layout.Content>
+      </Layout.Panel>
+      <Layout.Toolbar>
+        <Button onPress={() => setIsOpen(!isOpen)}>
+          {isOpen ? 'Close' : 'Open'} Chat
+        </Button>
+      </Layout.Toolbar>
+      <Layout.Content>
+        <Text>Main content area</Text>
+      </Layout.Content>
+    </Layout>
+  );
+}
+```
+
 ### Multiple Panels
 
 ```jsx

package/docs/components/content/TextItem.md

@@ -2,6 +2,8 @@
 
 A text component with built-in overflow handling and auto-tooltips. When text is truncated, a tooltip automatically appears on hover showing the full content. Also supports text highlighting for search results.
 
+TextItem renders one line truncated with an ellipsis, so Text's `ellipsis` and `nowrap` props don't apply.
+
 ## When to Use
 
 - Display text that may overflow its container with automatic tooltip fallback
@@ -21,8 +23,6 @@ A text component with built-in overflow handling and auto-tooltips. When text is
 - **`tooltip`** `string | boolean | TooltipProviderProps` (default: `true`) — Tooltip configuration. `true` enables auto tooltip on overflow, a string shows fixed tooltip text, an object supports advanced configuration.
 - **`tooltipPlacement`** `Placement` (default: `top`) — Default tooltip placement
 - **`monospace`** `boolean` — Use monospace font
-- **`ellipsis`** `boolean` — Truncate overflow with ellipsis
-- **`nowrap`** `boolean` — Prevent text wrapping
 - **`italic`** `string` — Font style (e.g. `'italic'`)
 - **`weight`** `string | number` — Font weight
 - **`transform`** `string` — Text transform (e.g. `'uppercase'`, `'capitalize'`)

package/docs/components/fields/ComboBox.md

@@ -479,7 +479,7 @@ const fruits = [
 
 ### Virtualized List
 
-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. Virtualization is disabled when sections are present.
+A flat list is virtualized automatically, whether its options come from the `items` prop or from static children: only visible items are rendered in the DOM, providing smooth scrolling even with thousands of items. Virtualization is disabled when sections are present.
 
 ```jsx
 const items = Array.from({ length: 1000 }, (_, i) => ({
@@ -743,7 +743,6 @@ function Example() {
 
 ## Suggested Improvements
 
-- **Virtual Scrolling**: Add support for virtualizing long lists to improve performance with thousands of items
 - **Multi-Select Mode**: Add ability to select multiple items with tag-based display
 - **Async Loading**: Built-in support for async data loading with loading states per scroll position (partial support via `isLoading` prop)
 - **Custom Option Rendering**: Allow more flexibility in rendering option content beyond text

package/docs/components/fields/FilterListBox.md

@@ -742,7 +742,7 @@ useEffect(() => {
 
 ### Virtualization
 
-When FilterListBox contains many items without sections, virtualization is automatically enabled to improve performance. Only visible items are rendered in the DOM, providing smooth scrolling even with large datasets.
+When FilterListBox has no sections, virtualization is automatically enabled to improve performance. Only visible items are rendered in the DOM, providing smooth scrolling even with large datasets.
 
 ```jsx
 const items = Array.from({ length: 1000 }, (_, i) => ({
@@ -763,14 +763,14 @@ const items = Array.from({ length: 1000 }, (_, i) => ({
 
 **Key features:**
 
-- Automatically enabled for large lists without sections
+- Automatically enabled for lists without sections
 - Handles items with varying heights
 - Works seamlessly with filtering
 - Maintains performance with thousands of items
 
 **Limitations:**
 
-- Virtualization is disabled when sections are present
+- Virtualization is disabled when sections are present, and for a reorderable list while the search is empty
 - For sectioned large lists, consider flattening or alternative approaches
 
 ## Performance

package/docs/components/fields/FilterPicker.md

@@ -251,7 +251,7 @@ The most common pattern for FilterPicker is to provide static children using `Fi
 
 ### Dynamic Content Pattern
 
-For large datasets or dynamic content, use the `items` prop with a render function. This pattern enables automatic virtualization for performance:
+For dynamic content, use the `items` prop with a render function. Virtualization does not depend on it: any flat list without sections is virtualized, with static children too, unless `isReorderable` is set and the search is empty.
 
 ```jsx
 <FilterPicker
@@ -302,18 +302,14 @@ const categories = [
 
 **Key Benefits:**
 
-- **Virtualization**: Automatically enabled for large lists without sections
-- **Performance**: Only renders visible items in the DOM
 - **Dynamic Content**: Perfect for data fetched from APIs or changing datasets
-- **Memory Efficient**: Handles thousands of items smoothly
 - **Selected Items Sorting**: When using the `items` prop, selected items are automatically sorted to the top when the popover reopens (can be controlled with `sortSelectedToTop`)
 
 **When to Use:**
 
-- Lists with 50+ items
 - Dynamic data from APIs
 - Content that changes frequently
-- When virtualization performance is needed
+- When selected items should sort to the top
 
 ## Variants
 
@@ -620,9 +616,10 @@ const [keyOrder, setKeyOrder] = useState([
 
 ### ARIA Properties
 
-- `aria-label` - Provides accessible label for the trigger button
+- `aria-labelledby` - References the field label, when there is one
+- `aria-label` - Labels the trigger when there is no visible label
 - `aria-expanded` - Indicates whether the popover is open
-- `aria-haspopup` - Indicates the button controls a listbox
+- `aria-controls` - References the popover while it is open
 - `aria-describedby` - Associates help text and descriptions
 
 ## Best Practices
@@ -652,10 +649,9 @@ const [keyOrder, setKeyOrder] = useState([
    </FilterPicker.Section>
    ```
 
-4. **Do**: Use dynamic content pattern for large datasets
+4. **Do**: Use the `items` prop for large, dynamic datasets
 
    ```jsx
-   // ✅ For large lists (50+ items)
    <FilterPicker items={largeDataset}>
      {(item) => <FilterPicker.Item key={item.id}>{item.name}</FilterPicker.Item>}
    </FilterPicker>
@@ -903,7 +899,7 @@ const handleSearchChange = useCallback((value) => {
 
 ### Optimization Tips
 
-- **Use Dynamic Content Pattern**: For large datasets (50+ items), use the `items` prop with render function to enable automatic virtualization
+- **Use Dynamic Content Pattern**: For large, dynamic datasets, use the `items` prop with a render function. A flat list is virtualized either way, unless `isReorderable` is set and the search is empty
 - **Avoid Sections for Large Lists**: Virtualization is disabled when sections are present, so avoid sections for very large datasets
 - **Use `textValue` prop**: For complex option content, provide searchable text that includes more context than just the visible label
 - **Implement custom filter functions**: For specific search needs or performance-critical filtering
@@ -912,7 +908,7 @@ const handleSearchChange = useCallback((value) => {
 
 ### Virtualization
 
-When using the dynamic content pattern (`items` prop) without sections, FilterPicker automatically enables virtualization:
+FilterPicker automatically virtualizes any flat list without sections, whether it uses the `items` prop or static children, unless `isReorderable` is set and the search is empty:
 
 ```jsx
 // ✅ Virtualization enabled - excellent performance with large datasets

package/docs/components/fields/ListBox.md

@@ -9,7 +9,7 @@ A versatile list selection component that allows users to select one or more ite
 - Display structured data with sections and descriptions
 - Create custom selection interfaces that need to remain visible
 - Build form controls that require persistent option visibility
-- Handle lists of any size (virtualization is automatic for flat lists)
+- Handle lists of any size (virtualization is automatic for flat lists that are not reorderable)
 - When you need rich option content (icons, descriptions, badges, hotkeys)
 - For multiple selection with clear visual feedback (checkboxes)
 - When options should always be visible (for searchable lists, consider FilterListBox)
@@ -34,7 +34,7 @@ A versatile list selection component that allows users to select one or more ite
 - **`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
+- **`focusOnHover`** `boolean` (default: `false`) — Whether moving the pointer over an option will move DOM focus to that option
 - **`shouldUseVirtualFocus`** `boolean` (default: `false`) — Whether to use virtual focus instead of DOM focus
 - **`isFocusWithin`** `boolean` — For a list whose focused option is moved from an input outside it: whether focus is within that input's component
 - **`isCheckable`** `boolean` (default: `false`) — Whether to show checkboxes for multiple selection mode
@@ -188,16 +188,16 @@ The `mods` property accepts the following modifiers you can override:
 **listGap** (`number`, default: a hairline, `1bw`)
 
 - The space between options, in pixels
-- Use it rather than a margin in `optionStyles`: a flat list is virtualized and positions its options itself, so it ignores their margins
+- Use it rather than a margin in `optionStyles`: a virtualized list positions its options itself, so it ignores their margins
 - Card-like options (`type="outline"`, `shape="card"`) usually want `4` or more, so each one reads as its own choice
 - FilterListBox, Picker, FilterPicker, ComboBox, SearchComboBox, TagInput and CommandTextArea pass it to their ListBox. Select takes it too
 
 ### Focus and Interaction
 
-**focusOnHover** (`boolean`, default: `true`)
+**focusOnHover** (`boolean`, default: `false`)
 
 - When `true`, moving the pointer over an option will move DOM focus to that option
-- Set to `false` for components that keep DOM focus outside (e.g., searchable FilterListBox)
+- Leave it `false` for components that keep DOM focus outside (e.g., searchable FilterListBox)
 
 **shouldUseVirtualFocus** (`boolean`, default: `false`)
 
@@ -725,7 +725,8 @@ const [keyOrder, setKeyOrder] = useState([
 - `aria-labelledby` - Associates with external label element
 - `aria-describedby` - Associates with description text
 - `aria-multiselectable` - Indicates multiple selection capability
-- `aria-activedescendant` - Tracks focused item for screen readers
+
+Options take DOM focus, so the list sets no `aria-activedescendant`. With `shouldUseVirtualFocus`, DOM focus stays on a control outside the list, and that control must set `aria-activedescendant` to the focused option, as FilterListBox's search input does.
 
 ## Best Practices
 
@@ -740,7 +741,7 @@ const [keyOrder, setKeyOrder] = useState([
 2. **Don't**: Use ListBox for very large datasets without considering virtualization
 
    ```jsx
-   // ✅ Virtualization is automatic for lists without sections
+   // ✅ Virtualization is automatic for lists without sections that are not reorderable
    <ListBox height="300px">
      {hugeArray.map(item => <ListBox.Item key={item.id}>{item.name}</ListBox.Item>)}
    </ListBox>
@@ -796,7 +797,7 @@ const [keyOrder, setKeyOrder] = useState([
    ```
 
 8. **Accessibility**: Always provide meaningful labels and descriptions
-9. **Performance**: Virtualization is automatic when there are no sections
+9. **Performance**: Virtualization is automatic when there are no sections and `isReorderable` is not set
 10. **UX**: Consider FilterListBox for searchable lists with many options
 
 ## Integration with Forms
@@ -827,7 +828,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. 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.
+A flat list is virtualized automatically, whether its options come from the `items` prop or from static children: 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) => ({
@@ -840,7 +841,7 @@ const items = Array.from({ length: 1000 }, (_, i) => ({
 </ListBox>
 ```
 
-**Note**: Virtualization is disabled when sections are present. For very large datasets, prefer a flat list structure.
+**Note**: Virtualization is disabled when sections are present or `isReorderable` is set. For very large datasets, prefer a flat list structure.
 
 ### Optimization Tips
 

package/docs/components/fields/NumberInput.md

@@ -37,7 +37,7 @@ A number input component that allows users to enter numeric values and increment
 - **`inputProps`** `Props` — Direct props passed to the native input element, merged over the props React Aria generates: a key you set wins, and event handlers are chained rather than replaced
 - **`wrapperProps`** `Props` — Direct props passed to the input wrapper element, merged with the `group` props React Aria puts there: event handlers are chained
 - **`validate`** `(value: number) => ValidationError | true | null | undefined` — Client-side validation. React Aria sets `aria-invalid` from the returned errors at once; the invalid style and the message follow after the user edits or leaves the field, so an empty field does not open in red. A typed number is checked once it commits, on blur or `Enter`. An explicit `errorMessage` replaces the returned message, and an explicit `isInvalid` (or a form's validation) takes over from `validate` entirely
-- **`onChange`** `function` — Callback fired when the input value changes
+- **`onChange`** `(value: number) => void` — Callback fired when a new value is committed, not on each keystroke: when the field loses focus or `Enter` is pressed after typing, and at once when a stepper button, the mouse wheel or one of the keys in [Keyboard Events](#keyboard-events) changes it. Committing an empty field passes `NaN`
 - **`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)
@@ -219,7 +219,6 @@ This component supports all [Field properties](../../FieldProperties.md) when us
 
 - Provide `maxValue`/`minValue` indicator with value range
 - Support for input masks and formatting
-- Built-in debouncing for onChange events
 
 ## Related Components
 

package/docs/components/fields/Picker.md

@@ -52,7 +52,7 @@ Choose a different component when the interaction has another shape:
 - **`clearLabel`** `string` — Accessible name for the built-in clear button. Defaults to a localized "Clear value".
 - **`onClear`** `() => void` — Callback called when the clear button is pressed
 - **`actions`** `ReactNode` — Custom actions rendered inside the trigger, to the left of the built-in clear button and dropdown caret
-- **`sortSelectedToTop`** `boolean` — Sort selected items to the top when the popover opens (only works with `items` prop)
+- **`sortSelectedToTop`** `boolean` — Sort selected items to the top when the popover opens. Only works with the `items` prop, where it is on by default
 - **`renderSummary`** `((args: { selectedLabels, selectedKeys, selectionMode }) => ReactNode) | false` — Custom renderer for the summary shown inside the trigger
 - **`header`** `ReactNode` — Custom header content in the popover
 - **`footer`** `ReactNode` — Custom footer content in the popover
@@ -264,7 +264,7 @@ Groups related items together under an optional section heading. Sections provid
 </Picker>
 ```
 
-**Note:** Sections disable virtualization. For large datasets (50+ items), use a flat structure with the `items` prop instead.
+**Note:** Sections disable virtualization. For large datasets (50+ items), use a flat structure instead.
 
 ## Content Patterns
 
@@ -284,7 +284,7 @@ The most common pattern for Picker is to provide static children using `Picker.I
 
 ### Dynamic Content Pattern
 
-For large datasets or dynamic content, use the `items` prop with a render function. This pattern enables automatic virtualization for performance:
+For dynamic content, use the `items` prop with a render function. Virtualization does not depend on it: any flat list without sections is virtualized, with static children too.
 
 ```jsx
 <Picker
@@ -301,17 +301,14 @@ For large datasets or dynamic content, use the `items` prop with a render functi
 
 **Key Benefits:**
 
-- **Virtualization**: Automatically enabled for large lists without sections
-- **Performance**: Only renders visible items in the DOM
 - **Dynamic Content**: Perfect for data fetched from APIs or changing datasets
-- **Memory Efficient**: Handles thousands of items smoothly
+- **Sorting**: Selected items move to the top when the popover opens (`sortSelectedToTop`, on by default with `items` and unavailable without it)
 
 **When to Use:**
 
-- Lists with 50+ items
 - Dynamic data from APIs
 - Content that changes frequently
-- When virtualization performance is needed
+- When selected items should sort to the top
 
 ## Variants
 
@@ -730,7 +727,7 @@ The trigger also sets `aria-expanded`, and `aria-controls` while the popover is
    </Picker>
    ```
 
-4. **Do**: Use the `items` prop for large datasets to enable virtualization
+4. **Do**: Use the `items` prop for large, dynamic datasets
 
    ```jsx
    <Picker items={largeDataset} label="Select Item">
@@ -977,11 +974,10 @@ const fruits = [
 
 ### Optimization Tips
 
-1. **Use Dynamic Content Pattern for Large Lists**
+1. **Use the Dynamic Content Pattern for Dynamic Data**
 
-   - For lists with 50+ items, use the `items` prop with a render function
-   - This enables automatic virtualization for better performance
-   - Only visible items are rendered in the DOM
+   - For dynamic lists, use the `items` prop with a render function
+   - A flat list is virtualized either way: only visible items are rendered in the DOM
 
 2. **Avoid Sections with Large Datasets**
 
@@ -999,7 +995,7 @@ const fruits = [
 
 ### Virtualization
 
-Virtualization is automatically enabled when using the `items` prop without sections:
+Virtualization is automatically enabled for any flat list without sections, whether it uses the `items` prop or static children:
 
 ```jsx
 // ✅ Virtualized - excellent performance with thousands of items

package/docs/components/fields/Select.md

@@ -69,7 +69,7 @@ Choose a different component when the interaction has another shape:
 - **`isOpen`** `boolean` — Whether the dropdown is open (controlled)
 - **`defaultOpen`** `boolean` — Whether the dropdown is open by default (uncontrolled)
 - **`selectionMode`** `'single'` — Selection mode for the select
-- **`onSelectionChange`** `(key: Key) => void` — Callback fired when the selected option changes
+- **`onSelectionChange`** `(key: Key | null) => void` — Callback fired when the selected option changes. Clearing the selection passes `null`
 - **`onOpenChange`** `(isOpen: boolean) => void` — Callback fired when the dropdown opens or closes
 - **`onFocus`** `(e: FocusEvent) => void` — Callback fired when the select receives focus
 - **`onBlur`** `(e: FocusEvent) => void` — Callback fired when the select loses focus
@@ -541,20 +541,23 @@ Opened with a pointer, the list focuses the selected option, or the list itself
 
 ### Screen Reader Support
 
-- Component announces as "combobox" or "listbox" to screen readers
+- The trigger announces as a button with a listbox popup, named by the value it shows and its label, and described by its description and error message
 - Current selection is announced when changed
 - Available options are announced during navigation
 - Dropdown state (open/closed) is communicated
 
 ### ARIA Properties
 
+The trigger button carries:
+
 - `aria-label` - Provides accessible label when no visible label exists
-- `aria-labelledby` - References external label elements
-- `aria-describedby` - References additional descriptive text
+- `aria-labelledby` - References the selected value, the label and any `aria-labelledby` you pass
+- `aria-describedby` - References the description and the error message, and your own descriptive text
+- `aria-haspopup="listbox"` - Indicates that the trigger opens a list
 - `aria-expanded` - Indicates if dropdown is open
-- `aria-activedescendant` - References the currently focused option
-- `aria-required` - Indicates if selection is required
-- `aria-invalid` - Indicates validation state
+- `aria-controls` - References the list while it is open
+
+The open list is a `listbox`. Options take DOM focus as you move through them, so the trigger has no `aria-activedescendant`.
 
 ## Best Practices
 
@@ -663,7 +666,6 @@ function Example() {
 - Add support for multi-selection mode with visual badges
 - Implement virtual scrolling for very large option lists (1000+ items)
 - Built-in async loading support with loading states per scroll position
-- Enhanced keyboard shortcuts for power users (e.g., type to jump to option)
 - Custom empty state component when no options are available
 - Support for option groups with visual separators beyond sections
 
@@ -673,7 +675,7 @@ function Example() {
 - [FilterPicker](./FilterPicker.md) - For button-triggered selection with a visible search field
 - [ComboBox](./ComboBox.md) - For an input-based searchable field that keeps one selected value
 - [SearchComboBox](./SearchComboBox.md) - For search-and-act flows that clear after each result
-- [ListBox](./ListBox.md) - The underlying list component used in Select
+- [ListBox](./ListBox.md) - A standalone, always-visible list. Select renders its own list, not ListBox
 - [RadioGroup](./RadioGroup.md) - For visible selection options with fewer choices
 - [Menu](../actions/Menu.md) - For action-oriented or navigation dropdowns
 - [Item](../content/Item.md) - The base component used for rendering items