@cube-dev/ui-kit 0.193.1 → 0.194.0

package/dist/tokens/sizes.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/tokens/sizes.ts
 /**
 * Component size values in pixels.

package/dist/tokens/spacing.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/tokens/spacing.ts
 /**
 * Spacing tokens using tasty multiplier syntax.

package/dist/tokens/typography.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/tokens/typography.ts
 /**
 * Typography presets for headings, text, and special styles.

package/dist/utils/ResizeSensor.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/utils/ResizeSensor.ts
 /**
 * Iterate over each of the provided element(s).

package/dist/utils/colors.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { hslToSrgb, okhslToOklch, okhslToSrgb, okhstToOkhsl, oklabToOkhsl, parseHexAlpha } from "@tenphi/glaze";
 
 //#region src/utils/colors.ts

package/dist/utils/dotize.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/utils/dotize.ts
 /**
 * Flattens a nested object into dot paths: `{ a: { b: 1 } }` becomes

package/dist/utils/is-dev-env.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/utils/is-dev-env.ts
 /**
 * `NODE_ENV` as the environment that is actually running reports it, or

package/dist/utils/modules.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/utils/modules.ts
 function extractModule(promise) {
 	return promise.then((module) => module.default || module);

package/dist/utils/promise.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/utils/promise.ts
 function timeout(ms = 30) {
 	return new Promise((resolve) => {

package/dist/utils/raf.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/utils/raf.ts
 /**
 * Chains N requestAnimationFrame calls and returns a cancel function.

package/dist/utils/random.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/utils/random.ts
 function random(min, max) {
 	const realMin = min < max ? min : max;

package/dist/utils/range.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/utils/range.ts
 function range(count) {
 	return Array.from({ length: count }, (_, i) => i);

package/dist/utils/react/RenderCache.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { useRef } from "react";
 import { Fragment as Fragment$1, jsx } from "react/jsx-runtime";
 

package/dist/utils/react/Slots.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { mergeProps } from "./mergeProps.js";
 import { c } from "react/compiler-runtime";
 import { Children, cloneElement, createContext, useContext } from "react";

package/dist/utils/react/chain.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/utils/react/chain.ts
 /**
 * Calls all functions in the order they were chained with the same arguments.

package/dist/utils/react/disabledProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/utils/react/disabledProps.ts
 /**
 * Tags where `disabled` is a real HTML attribute. Browsers refuse to dispatch

package/dist/utils/react/forwardRefWithGenerics.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/utils/react/forwardRefWithGenerics.tsx
 /**
 * @deprecated Declare a ref prop on a generic component, or preserve an

package/dist/utils/react/index.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { chain } from "./chain.js";
 import { getDisabledElementProps, omitActivationEventProps } from "./disabledProps.js";
 import { forwardRefWithGenerics } from "./forwardRefWithGenerics.js";

package/dist/utils/react/interactions.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { useLayoutEffect as useLayoutEffect$1 } from "./useLayoutEffect.js";
 import { c } from "react/compiler-runtime";
 import { useRef, useState } from "react";

package/dist/utils/react/isTextOnly.js

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

package/dist/utils/react/mapProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/utils/react/mapProps.ts
 /** Converts AriaButtonProps to CubeButtonProps */
 function ariaToCubeButtonProps(props) {

package/dist/utils/react/mergeProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { chain } from "./chain.js";
 import { mergeIds } from "./useId.js";
 import { mergeStyles } from "@tenphi/tasty";

package/dist/utils/react/nullableValue.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/utils/react/nullableValue.ts
 function castNullableStringValue(props) {
 	return castNullableField(props, ["value", "defaultValue"], "string", (v) => String(v));

package/dist/utils/react/overlayKeyPropagation.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/utils/react/overlayKeyPropagation.ts
 /**
 * Keys whose final handling belongs to the overlay around a control, not to

package/dist/utils/react/programmaticFocus.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/utils/react/programmaticFocus.ts
 /**
 * Telling focus the user moved from focus a component moved for them.

package/dist/utils/react/resolveIcon.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/utils/react/resolveIcon.ts
 /**
 * Resolves a dynamic icon prop to its content and slot state.

package/dist/utils/react/sharedStore.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { isDevEnv } from "../is-dev-env.js";
 import { c } from "react/compiler-runtime";

package/dist/utils/react/useBufferedValue.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { useLayoutEffect as useLayoutEffect$1 } from "./useLayoutEffect.js";
 import { useCallback, useRef, useState } from "react";
 

package/dist/utils/react/useCombinedRefs.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { c } from "react/compiler-runtime";
 import { useEffect, useRef } from "react";
 

package/dist/utils/react/useControlledFocusVisible.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { createSharedStore } from "./sharedStore.js";
 import { c } from "react/compiler-runtime";
 import { useEffect } from "react";

package/dist/utils/react/useEventBus.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { c } from "react/compiler-runtime";
 import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef } from "react";
 

package/dist/utils/react/useId.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { useLayoutEffect as useLayoutEffect$1 } from "./useLayoutEffect.js";
 import { c } from "react/compiler-runtime";
 import { useEffect, useRef, useState } from "react";

package/dist/utils/react/useIsDarwin.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { c } from "react/compiler-runtime";
 import { useEffect, useState } from "react";
 

package/dist/utils/react/useKeySymbols.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { useIsDarwin } from "./useIsDarwin.js";
 import { c } from "react/compiler-runtime";
 

package/dist/utils/react/useLayoutEffect.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import * as React$1 from "react";
 
 //#region src/utils/react/useLayoutEffect.tsx

package/dist/utils/react/useLocalStorage.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { c } from "react/compiler-runtime";
 import { useSyncExternalStore } from "react";

package/dist/utils/react/useMergeStyles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { mergeStyles } from "@tenphi/tasty";
 import { useMemo } from "react";
 

package/dist/utils/react/useOverlayEscapeGuard.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { c } from "react/compiler-runtime";
 import { getEventTarget, nodeContains } from "@react-aria/utils";

package/dist/utils/react/usePopoverSync.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { EventBusContext, useEventBus } from "./useEventBus.js";
 import { c } from "react/compiler-runtime";
 import { useContext, useEffect, useEffectEvent, useRef } from "react";

package/dist/utils/react/useQaProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/utils/react/useQaProps.ts
 /**
 * Processes QA props.

package/dist/utils/react/useScheme.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { useSyncExternalStore } from "react";
 
 //#region src/utils/react/useScheme.ts

package/dist/utils/react/useViewportSize.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { c } from "react/compiler-runtime";
 import { useEffect, useState } from "react";
 

package/dist/utils/react/wrapNodeIfPlain.js

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

package/dist/utils/selection.js

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

package/dist/utils/styles.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 import { isSelector, mergeStyles } from "@tenphi/tasty";
 
 //#region src/utils/styles.ts

package/dist/utils/tree.js

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

package/dist/utils/warnings.js

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

package/dist/version.js

@@ -1,6 +1,6 @@
-/** @license MIT | @cube-dev/ui-kit v0.193.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.194.0 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.193.1";
+const VERSION = "0.194.0";
 const TASTY_VERSION = "3.9.9";
 if (typeof window !== "undefined") {
 	const version = VERSION;

package/docs/Usage.md

@@ -11,6 +11,10 @@ For styling engine internals see the [Tasty documentation](./tasty/usage.md). Ta
 - **injector.md** — Low-level style injector: `inject()`, `injectGlobal()`, deduplication, SSR.
 - **tasty-static.md** — Zero-runtime `tastyStatic()`, Babel plugin, Next.js/Vite integration.
 
+## Navigation
+
+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.
+
 ## 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.

package/docs/components/CollectionItem.md

@@ -6,6 +6,10 @@
 
 ListBox, FilterListBox, Select, ComboBox, FilterPicker, Picker, Menu, CommandMenu
 
+The parent component determines an item's semantics. `Menu.Item` and `CommandMenu.Item` can mix commands (`onAction`) with navigation links (`to` or `href`). See [Menu](./actions/Menu.md) for keyboard behavior and inline actions, and [CommandMenu](./actions/CommandMenu.md) for searchable menus.
+
+ListBox, ComboBox, SearchComboBox, Select, Picker and their filtering variants render selection options. Their `.Item` APIs reject navigation props, and the controls ignore destinations even when given an item from another factory. Use a menu or command menu when activating a suggestion should navigate.
+
 ## Usage Patterns
 
 There are two ways to provide items to collection components:
@@ -114,7 +118,7 @@ const items = [{
 - **`onAction`** `() => void` — Callback fired when the item is activated (Menu items)
 - **`wrapper`** `(item: ReactElement) => ReactElement` — Function to wrap the rendered item
 
-Extends all [Item component](./content/Item.md) props.
+Supports [Item component](./content/Item.md) content and styling props. Navigation props are available only on `Menu.Item` and `CommandMenu.Item`.
 
 ### Base Properties
 

package/docs/components/actions/CommandMenu.md

@@ -1,11 +1,11 @@
 # CommandMenu
 
-A searchable, keyboard-first surface for finding and executing application actions. CommandMenu renders the searchable menu content; wrap it in `CommandMenu.Trigger` for a button-anchored popover or place it in a `Dialog` for a global command palette.
+A searchable, keyboard-first surface for finding and executing application commands or opening navigation destinations. CommandMenu renders the searchable menu content; wrap it in `CommandMenu.Trigger` for a button-anchored popover or place it in a `Dialog` for a global command palette.
 
 ## When to use
 
 - Users need to search a large or changing set of application commands
-- The primary result of choosing an item is executing an action
+- Choosing an item executes a command or opens a destination
 - Keyboard-first discovery, aliases (`keywords`), and shortcut hints are important
 - A trigger-based command popover or modal global command palette is needed
 
@@ -38,7 +38,7 @@ Choose a different component when the interaction has another outcome:
 - **`autoFocus`** `boolean | FocusStrategy` (default: `true`) — Whether to auto-focus the search input
 - **`items`** `Iterable<T>` — Collection of items for dynamic content with render function pattern
 - **`disabledKeys`** `Iterable<Key>` — Keys of items that should be disabled
-- **`onAction`** `(key: Key) => void` — Callback fired when an item is selected
+- **`onAction`** `(key: Key) => void` — Callback fired when an item is activated, after its own `onAction()`
 - **`isDisabled`** `boolean` — Whether the command menu is disabled
 - **`header`** `ReactNode` — Optional header content above the search input
 - **`footer`** `ReactNode` — Optional footer content below the menu
@@ -117,7 +117,11 @@ For detailed information about all available item properties, see the [Menu.Item
 - **`hotkeys`** `string` — Keyboard shortcut that triggers this item
 - **`tooltip`** `string | boolean | object` — Tooltip configuration
 - **`isDisabled`** `boolean` — Whether the item is disabled
-- **`onAction`** `() => void` — Callback fired when item is activated
+- **`onAction`** `() => void` — Callback fired when the item is activated, before the CommandMenu's `onAction(key)`
+- **`to`** `string | Path` — Application destination resolved by Root's navigation adapter; takes precedence over `href`
+- **`navigationOptions`** `NavigateOptions` — Options for client navigation, such as `replace`, `state`, `relative` and `preventScrollReset`
+- **`href`** `string` — Native destination when `to` is omitted
+- **`target`**, **`rel`**, **`download`**, **`ping`**, **`referrerPolicy`**, **`hrefLang`** — Native anchor attributes
 
 #### CommandMenu-specific Properties
 
@@ -125,6 +129,36 @@ For detailed information about all available item properties, see the [Menu.Item
 - **`forceMount`** `boolean` — Whether to always show this item regardless of search filter
 - **`textValue`** `string` — Text value for search filtering (if different from children)
 
+#### Mixed Commands and Navigation
+
+The same searchable collection can contain commands and links. Give commands an `onAction` and navigation destinations a `to` or `href`; do not navigate again in the action callback. CommandMenu.Item uses the same navigation behavior as [Menu.Item](./Menu.md#navigation-items): ordinary activation uses Root's navigation adapter, while modified clicks, middle clicks, downloads, external destinations and other targets retain native browser behavior. A `!` prefix on `to` opens a new tab, and an `@` prefix forces native navigation.
+
+```tsx
+<CommandMenu aria-label="Workbooks" onAction={recordActivation}>
+  <CommandMenu.Item key="create" onAction={createWorkbook} keywords={['new']}>
+    Create workbook
+  </CommandMenu.Item>
+  <CommandMenu.Section title="Recent workbooks">
+    <CommandMenu.Item
+      key="saved"
+      to={{ pathname: '/workbooks/saved', search: '?view=table' }}
+      description="Open the saved workbook"
+    >
+      Saved workbook
+    </CommandMenu.Item>
+  </CommandMenu.Section>
+  <CommandMenu.Item key="browse" to="/workbooks">Browse all</CommandMenu.Item>
+</CommandMenu>
+```
+
+Filtering, Arrow keys and Enter use the same primary items for both commands and links. The item's `onAction()` runs first, then the CommandMenu's `onAction(key)`, once each. Space activates the highlighted item only while the search is empty; while typing a query, Space inserts text. Disabled items cannot activate or navigate. Selection modes select commands; navigation items open their destination without becoming selected.
+
+Loading items are disabled by default. Set `isDisabled={false}` to keep a loading item available; `disabledKeys` still applies.
+
+Navigation items expose `menuitem` semantics without a checked state, including when other items are checkboxes or radio choices. Supply `aria-current` to identify a destination that represents the current page.
+
+The primary native anchor covers the complete row and exposes the menu-item semantics and destination, while the original Item row retains its layout and style slots. Padding, gaps and whitespace support native browser link commands. Give icon-only items a meaningful accessible name. Follow [Menu's focus and selector migration guidance](./Menu.md#focus-and-selector-migration) for custom selectors. CommandMenu uses virtual focus: the search input keeps DOM focus and identifies the active primary menu item with `aria-activedescendant`, including when styles hide an individual content slot. Inline actions are unsupported in this virtual-focus mode; use a separate primary item for each command or a DOM-focus Menu when independent row actions are required.
+
 #### Example with Enhanced Search
 
 ```jsx
@@ -167,17 +201,17 @@ Alias for MenuTrigger component. See [Menu.Trigger documentation](./Menu.md#menu
 The CommandMenu component provides comprehensive keyboard support:
 
 - **Search Input Focus**: The search input is automatically focused when the palette opens
-- **Arrow Keys**: Navigate through filtered options while keeping search input focused
-- **Enter**: Select the currently highlighted option
+- **ArrowUp/ArrowDown**: Navigate through enabled filtered items while keeping the search input focused
+- **Enter**: Activate the currently highlighted command or navigation destination
+- **Space**: Activate the highlighted item only when the search is empty; otherwise insert a space into the query
 - **Escape**: Clear search term or close the palette
 - **Tab**: Navigate between focusable elements
 
 ### Screen Reader Support
 
-- Proper ARIA roles and labels for search and menu functionality
-- Live region announcements for state changes
-- Support for `aria-activedescendant` for virtual focus
-- Descriptive labels for loading and empty states
+The named search input has `searchbox` semantics and controls a `menu`, rather than a listbox of form options. Its `aria-activedescendant` points to the actual highlighted menu item, including items inside sections and native navigation anchors. Generated IDs are unique per palette. A plain command retains its consumer-provided DOM `id`; keep explicit IDs non-empty and unique within the page. Empty and loading states clear references to items that are no longer rendered.
+
+Give the palette an `aria-label` or `aria-labelledby` to name its search input, and use `aria-describedby` for search instructions. `searchPlaceholder` supplies the input name when no explicit name is provided. Screen-reader wording and virtual-focus behavior vary by reader and browser; verify the consuming application's browser/reader combination. The [WAI-ARIA active-descendant requirements](https://www.w3.org/TR/wai-aria-1.2/#aria-activedescendant) permit a searchbox to reference an item owned by its controlled menu.
 
 ### Focus Management
 
@@ -441,14 +475,8 @@ The CommandMenu supports enhanced search capabilities:
 ### Performance
 
 - The component uses efficient filtering with React Stately's collection system
-- Search filtering is debounced to prevent excessive re-renders
-- Virtual focus is used to maintain performance with large option sets
-
-### Accessibility Compliance
-
-- Meets WCAG 2.1 AA standards for keyboard navigation
-- Supports screen readers with proper ARIA attributes
-- Implements virtual focus pattern for optimal accessibility
+- Filtering updates as the search value changes
+- Virtual focus keeps the search input focused during item navigation
 
 ### Browser Support