@cube-dev/ui-kit 0.147.0 → 0.147.1

package/dist/icons/UpIcon.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { wrapIcon } from "./wrap-icon.js";
 import { jsx } from "react/jsx-runtime";
 import { IconChevronUp } from "@tabler/icons-react";

package/dist/icons/UserGroupIcon.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { wrapIcon } from "./wrap-icon.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 

package/dist/icons/UserIcon.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { wrapIcon } from "./wrap-icon.js";
 import { jsx, jsxs } from "react/jsx-runtime";
 

package/dist/icons/UserLockIcon.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { wrapIcon } from "./wrap-icon.js";
 import { jsx } from "react/jsx-runtime";
 

package/dist/icons/ViewIcon.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { wrapIcon } from "./wrap-icon.js";
 import { jsx } from "react/jsx-runtime";
 

package/dist/icons/WarningFilledIcon.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { wrapIcon } from "./wrap-icon.js";
 import { jsx } from "react/jsx-runtime";
 import { IconAlertTriangleFilled } from "@tabler/icons-react";

package/dist/icons/WarningIcon.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { wrapIcon } from "./wrap-icon.js";
 import { jsx } from "react/jsx-runtime";
 import { IconAlertTriangle } from "@tabler/icons-react";

package/dist/icons/wrap-icon.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { Icon } from "./Icon.js";
 import { jsx } from "react/jsx-runtime";
 

package/dist/index.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { extractStyles } from "./utils/styles.js";
 import { chain } from "./utils/react/chain.js";
 import { forwardRefWithGenerics } from "./utils/react/forwardRefWithGenerics.js";

package/dist/provider.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { EventBusProvider } from "./utils/react/useEventBus.js";
 import { defaultNavigationAdapter } from "./providers/navigationAdapter.default.js";
 import { createContext, useContext, useMemo } from "react";

package/dist/providers/TrackingProvider.js

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

package/dist/providers/navigationAdapter.default.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 //#region src/providers/navigationAdapter.default.ts
 /**
 * Converts a Path object to a string URL

package/dist/tokens/base.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 //#region src/tokens/base.ts
 /**
 * Base design system tokens.

package/dist/tokens/colors.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { PALETTE_TOKENS } from "./palette.js";
 
 //#region src/tokens/colors.ts

package/dist/tokens/index.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { BASE_TOKENS } from "./base.js";
 import { COLOR_TOKENS } from "./colors.js";
 import { LAYOUT_TOKENS } from "./layout.js";

package/dist/tokens/layout.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 //#region src/tokens/layout.ts
 /**
 * Layout-related tokens for common UI dimensions.

package/dist/tokens/palette.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { glaze } from "@tenphi/glaze";
 
 //#region src/tokens/palette.ts

package/dist/tokens/shadows.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 //#region src/tokens/shadows.ts
 /**
 * Shadow tokens using tasty shorthand syntax.

package/dist/tokens/sizes.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | 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.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | 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.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | 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.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 //#region src/utils/ResizeSensor.ts
 /**
 * Iterate over each of the provided element(s).

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

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 //#region src/utils/is-dev-env.ts
 function isDevEnv() {
 	if (typeof window !== "undefined" && window.localStorage) try {

package/dist/utils/modules.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | 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.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | 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.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | 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.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | 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.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | 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.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | 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.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { mergeProps } from "./mergeProps.js";
 import { Children, cloneElement, createContext, useContext, useMemo } from "react";
 import { jsx } from "react/jsx-runtime";

package/dist/utils/react/chain.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | 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/forwardRefWithGenerics.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 //#region src/utils/react/forwardRefWithGenerics.tsx
 /**
 * A helper for creating forwardRef components with generic types.

package/dist/utils/react/index.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { chain } from "./chain.js";
 import { forwardRefWithGenerics } from "./forwardRefWithGenerics.js";
 import { isTextOnly } from "./isTextOnly.js";

package/dist/utils/react/interactions.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { useState } from "react";
 import { useFocus, useFocusVisible } from "react-aria";
 

package/dist/utils/react/isTextOnly.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | 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.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | 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.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | 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.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | 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/resolveIcon.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | 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.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { useSyncExternalStore } from "react";
 

package/dist/utils/react/useCombinedRefs.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { useEffect, useRef } from "react";
 
 //#region src/utils/react/useCombinedRefs.ts

package/dist/utils/react/useControlledFocusVisible.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { createSharedStore } from "./sharedStore.js";
 import { useEffect } from "react";
 import { useFocusVisible } from "react-aria";

package/dist/utils/react/useEventBus.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import React, { createContext, useCallback, useContext, useEffect, useMemo, useRef } from "react";
 
 //#region src/utils/react/useEventBus.ts

package/dist/utils/react/useId.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { useLayoutEffect as useLayoutEffect$1 } from "./useLayoutEffect.js";
 import { useEffect, useRef, useState } from "react";
 import { useSSRSafeId } from "@react-aria/ssr";

package/dist/utils/react/useIsDarwin.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { useEffect, useState } from "react";
 
 //#region src/utils/react/useIsDarwin.ts

package/dist/utils/react/useKeySymbols.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { useIsDarwin } from "./useIsDarwin.js";
 import { useMemo } from "react";
 

package/dist/utils/react/useLayoutEffect.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | 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.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { useEvent } from "../../_internal/hooks/use-event.js";
 import { useCallback, useSyncExternalStore } from "react";
 

package/dist/utils/react/useMergeStyles.js

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

package/dist/utils/react/usePopoverSync.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { EventBusContext, useEventBus } from "./useEventBus.js";
 import { useCallback, useContext, useEffect, useRef } from "react";
 

package/dist/utils/react/useQaProps.js

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

package/dist/utils/react/useViewportSize.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { useEffect, useState } from "react";
 
 //#region src/utils/react/useViewportSize.ts

package/dist/utils/react/wrapNodeIfPlain.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 import { isValidElement } from "react";
 import { isFragment } from "react-is";
 

package/dist/utils/selection.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | 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.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 //#region src/utils/styles.ts
 /**
 * Split properties into style and non-style properties.

package/dist/utils/tree.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | 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.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 //#region src/utils/warnings.ts
 const SUGGESTED_PROP_MAP = {
 	disabled: "isDisabled",

package/dist/version.js

@@ -1,6 +1,6 @@
-/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.1 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.147.0";
+const VERSION = "0.147.1";
 const TASTY_VERSION = "2.8.0";
 if (typeof window !== "undefined") {
 	const version = VERSION;

package/docs/components/actions/CommandMenu.md

@@ -1,14 +1,20 @@
 # CommandMenu
 
-A searchable menu interface that combines the functionality of Menu and ListBox components. It provides a command-line-like experience for users to quickly find and execute actions through a searchable interface.
+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.
 
 ## When to use
 
-- **Quick action access**: Enable users to quickly find and execute commands or actions
-- **Large command sets**: When you have many available actions that benefit from search filtering
-- **Keyboard-first workflows**: For power users who prefer keyboard navigation
-- **Command-line interfaces**: When building developer tools or admin interfaces
-- **Global search**: As a global command palette accessible via keyboard shortcuts
+- Users need to search a large or changing set of application commands
+- The primary result of choosing an item is executing an action
+- Keyboard-first discovery, aliases (`keywords`), and shortcut hints are important
+- A trigger-based command popover or modal global command palette is needed
+
+Choose a different component when the interaction has another outcome:
+
+- Use [Menu](./Menu.md) with `MenuTrigger` for a short contextual action list that does not need a search field.
+- Use [SearchComboBox](../fields/SearchComboBox.md) for a focused single-line search-and-act input that may submit raw text and clears after each result.
+- Use [FilterPicker](../fields/FilterPicker.md) when users are searching to keep one or more selected field values.
+- Use [CommandTextArea](../fields/CommandTextArea.md) when a command or mention should be inserted into multiline text rather than executed immediately.
 
 ## Examples
 
@@ -423,10 +429,12 @@ The CommandMenu supports enhanced search capabilities:
 
 ## Related Components
 
-- [Menu](./Menu.md) - For static menu options without search
-- [ListBox](../fields/ListBox.md) - For searchable selection lists
-- [Dialog](../overlays/Dialog.md) - For modal command palette usage
-- [MenuTrigger](./Menu.md) - For trigger-based command palette usage
+- [Menu](./Menu.md) - Use with MenuTrigger for short contextual action lists without visible search
+- [SearchComboBox](../fields/SearchComboBox.md) - Use for focused search-and-act inputs that clear after each result
+- [FilterPicker](../fields/FilterPicker.md) - Use when searched items become persistent field values
+- [CommandTextArea](../fields/CommandTextArea.md) - Use when suggestions insert text at the caret
+- [Dialog](../overlays/Dialog.md) - Use as the container for a modal global command palette
+- [MenuTrigger](./Menu.md) - Use through CommandMenu.Trigger for a button-anchored command popover
 
 ## Technical Notes
 

package/docs/components/actions/Menu.md

@@ -1,14 +1,21 @@
 # Menu
 
-A versatile dropdown menu component that displays a list of actions or options. Built with React Aria for accessibility and supports single/multiple selection, sections, keyboard navigation, and custom styling.
+An action-oriented menu for short, scannable sets of commands, navigation destinations, or toggles. `Menu` renders the menu content; combine it with `MenuTrigger` to open a dropdown from a button or use the trigger variants for context menus. It supports keyboard typeahead, but does not show a search field.
 
 ## When to Use
 
-- Display a list of actions that can be performed (like Cut, Copy, Paste)
-- Create context menus for right-click interactions
-- Build dropdown menus for navigation or settings
-- Implement selection lists with single or multiple selection modes
-- Group related options using sections with dividers
+- A button or context-menu gesture should reveal a short list of related actions
+- Items execute commands or navigate rather than populate a form field
+- Mutually exclusive menu options or independent toggles need menu-item selection states
+- Related actions need sections, submenus, icons, or keyboard shortcut hints
+
+Choose a different component when the interaction has another shape:
+
+- Use [CommandMenu](./CommandMenu.md) when users need a visible search field to discover or filter commands.
+- Use [Select](../fields/Select.md) for a conventional single-value form field.
+- Use [Picker](../fields/Picker.md) for persistent single or multiple field values without search.
+- Use [FilterPicker](../fields/FilterPicker.md) for persistent single or multiple field values with search.
+- Use [SearchComboBox](../fields/SearchComboBox.md) for a focused search-and-act input that clears after each result.
 
 ## Component
 
@@ -466,16 +473,21 @@ The Menu component is typically used with MenuTrigger for dropdown functionality
 </MenuTrigger>
 ```
 
+`Menu` is the content and selection model; `MenuTrigger` supplies the button-triggered popover behavior. Use `CommandMenu.Trigger` instead when the opened content needs a visible command-search input.
+
 ## Suggested Improvements
 
 - Enhancement 1: Implement virtual scrolling for large item lists
 - Enhancement 2: Add animation presets for menu transitions
 - Enhancement 3: Support for item templates and custom renderers
-- Enhancement 4: Built-in search/filter functionality
+- Enhancement 4: For built-in search/filter functionality, use CommandMenu
 - Enhancement 5: Add support for icons in section headers
 
 ## Related Components
 
-- [Button](./Button.md) - Common trigger element for menus
-- [ListBox](../fields/ListBox.md) - Alternative for selection-focused interfaces
-- [ComboBox](../fields/ComboBox.md) - Combines input with menu selection 
+- [CommandMenu](./CommandMenu.md) - Use for searchable, keyboard-first command discovery
+- [Button](./Button.md) - Common trigger element for MenuTrigger
+- [Select](../fields/Select.md) - Use for a conventional persistent single-value field
+- [Picker](../fields/Picker.md) - Use for persistent single or multiple selection without search
+- [FilterPicker](../fields/FilterPicker.md) - Use for persistent single or multiple selection with search
+- [ListBox](../fields/ListBox.md) - Use for an always-visible selection-focused interface

package/docs/components/fields/CommandTextArea.md

@@ -1,17 +1,22 @@
 # CommandTextArea
 
-A multiline text input (built on `TextArea` / `TextInputBase`) that shows a
-command-autocomplete popover when the text matches a configurable trigger. The
-focus always stays in the textarea; arrow keys, Enter/Tab, and Escape drive the
-list only while it is open. Selecting an option inserts the option's literal
-value (e.g. `/clear`) into the text and fires `onCommand`.
+A multiline free-form field with inline token autocomplete. Typing a configured
+trigger such as `/` or `@` opens suggestions at the caret; choosing one inserts
+its literal value into the text and fires `onCommand`. The field value remains
+the complete textarea string rather than a selected option key.
 
 ## When to Use
 
-- Chat or prompt inputs where users type slash commands (`/clear`, `/help`).
-- Inputs that need token-based autocomplete (`@mentions`, snippets) without
-  giving up free-form, multiline editing.
-- Any textarea that should "feel like a textarea" but offer inline suggestions.
+- Chat or prompt inputs where slash commands (`/clear`, `/help`) are inserted into the message
+- Multiline editors that need inline `@mentions`, snippets, variables, or other triggered tokens
+- Cases where focus and the text caret must remain in a normal textarea while suggestions are open
+
+Choose a different component when the interaction has another outcome:
+
+- Use [SearchComboBox](./SearchComboBox.md) for a separate single-line search-and-act input that clears after a result is chosen.
+- Use [ComboBox](./ComboBox.md) when the field should keep one selected option rather than a free-form text document.
+- Use [CommandMenu](../actions/CommandMenu.md) when users should search for and immediately execute application commands instead of inserting text.
+- Use [TextArea](./TextArea.md) when no inline suggestions are needed.
 
 ## Component
 
@@ -149,5 +154,7 @@ This component supports all [Field properties](../../FieldProperties.md) when us
 ## Related Components
 
 - [TextArea](./TextArea.md) — The base multiline field this builds on.
-- [ComboBox](./ComboBox.md) — Single-value select with search (different semantics: commits a `selectedKey`).
+- [SearchComboBox](./SearchComboBox.md) — Single-line search-and-act input that clears after each result.
+- [ComboBox](./ComboBox.md) — Searchable field that commits one selected key instead of inserting text.
+- [CommandMenu](../actions/CommandMenu.md) — Searchable command surface that executes actions instead of editing text.
 - [ListBox](./ListBox.md) — The virtual-focus list rendered inside the popover.