@cube-dev/ui-kit 0.147.0 → 0.147.1

package/docs/components/fields/FilterPicker.md

@@ -1,15 +1,22 @@
 # FilterPicker
 
-A versatile selection component that combines a trigger button with a searchable dropdown. It provides a space-efficient interface for selecting one or multiple items from a filtered list, with support for sections, custom summaries, and various UI states. Built with React Aria's accessibility features and the Cube `tasty` style system.
+A button-triggered field for keeping one or more selected values from a **searchable** list. It is designed for compact filters and preference controls, with sections, checkboxes, select-all, custom summaries, and form integration.
 
 ## When to Use
 
-- Creating filter interfaces where users need to select from predefined options
-- Building advanced search and filtering systems with multiple criteria
-- Implementing tag-based selection systems with multiple categories
-- Designing compact selection interfaces where space is limited
-- Providing searchable selection without taking up permanent screen space
-- Building user preference panels with organized option groups
+- The selected value or values must persist after the popover closes
+- Users need a visible search field to find options
+- A compact button trigger is preferable to an always-visible input
+- Multiple selection, checkboxes, select-all, grouped options, or a custom trigger summary are needed
+- The selection should participate in form state and validation
+
+Choose a different component when the interaction has another shape:
+
+- Use [Picker](./Picker.md) for the same compact single/multiple-selection pattern when the list is manageable without search.
+- Use [Select](./Select.md) for a conventional single-value field with a short predefined list.
+- Use [ComboBox](./ComboBox.md) for an always-visible text input that searches and keeps one selected value.
+- Use [SearchComboBox](./SearchComboBox.md) when choosing a result should fire an action and clear the input rather than persist a value.
+- Use [CommandMenu](../actions/CommandMenu.md) when entries execute application commands instead of becoming field values.
 
 ## Component
 
@@ -854,8 +861,10 @@ When using the dynamic content pattern (`items` prop) without sections, FilterPi
 
 ## Related Components
 
-- [FilterListBox](./FilterListBox.md) - The underlying searchable list component
-- [Select](./Select.md) - Use for simple selection without search functionality
-- [ComboBox](./ComboBox.md) - Use when users need to enter custom values
+- [FilterListBox](./FilterListBox.md) - Use for an always-visible searchable selection list without a trigger
+- [Picker](./Picker.md) - Use for button-triggered single or multiple selection without a search field
+- [Select](./Select.md) - Use for a conventional single-value field with a short predefined list
+- [ComboBox](./ComboBox.md) - Use for an input-based searchable field that keeps one selected value
+- [SearchComboBox](./SearchComboBox.md) - Use for search-and-act flows that clear after each result
 - [ListBox](./ListBox.md) - Use for basic list selection without search
 - [Button](../actions/Button.md) - The underlying trigger component

package/docs/components/fields/Picker.md

@@ -1,14 +1,22 @@
 # Picker
 
-A versatile selection component that combines a trigger button with a dropdown list. It provides a space-efficient interface for selecting one or multiple items from a list, with support for sections, custom summaries, and various UI states.
+A button-triggered field for keeping one or more selected values from a predefined list **without a visible search field**. Picker is suited to compact controls that need multiple selection, checkboxes, select-all, sections, or a custom summary in the trigger.
 
 ## When to Use
 
-- Creating selection interfaces where users need to choose from predefined options
-- Implementing compact selection interfaces where space is limited
-- Building user preference panels with organized option groups
-- When you need single or multiple selection from a list
-- When you don't need search/filter functionality (use ComboBox or FilterPicker for searchable lists)
+- The selected value or values must persist after the popover closes
+- The option set is manageable through scanning or keyboard typeahead, without a search input
+- Multiple selection, checkboxes, select-all, grouped options, or a custom trigger summary are needed
+- A compact button trigger fits a toolbar, filter bar, or preference panel
+- The selection should participate in form state and validation
+
+Choose a different component when the interaction has another shape:
+
+- Use [Select](./Select.md) for a conventional single-value field with a short predefined list.
+- Use [FilterPicker](./FilterPicker.md) when users need a visible search field while keeping single or multiple selections.
+- Use [ComboBox](./ComboBox.md) for an always-visible text input that searches and keeps one selected value.
+- Use [SearchComboBox](./SearchComboBox.md) when choosing a result should fire an action and clear the input.
+- Use [Menu](../actions/Menu.md) with `MenuTrigger` when entries primarily execute actions rather than become field values.
 
 ## Component
 
@@ -938,8 +946,11 @@ Optimize complex item content with the `textValue` prop for better accessibility
 
 ## Related Components
 
-- [ComboBox](./ComboBox.md) - Use when you need search/filter functionality or custom value entry
+- [Select](./Select.md) - Use for a conventional single-value field with a short predefined list
+- [FilterPicker](./FilterPicker.md) - Use for button-triggered single or multiple selection with a visible search field
+- [ComboBox](./ComboBox.md) - Use for an input-based searchable field that keeps one selected value
+- [SearchComboBox](./SearchComboBox.md) - Use for search-and-act flows that clear after each result
 - [ListBox](./ListBox.md) - Use for always-visible list selection without a trigger
-- [Select](./Select.md) - Use for native select behavior
+- [Menu](../actions/Menu.md) - Use with MenuTrigger for action-oriented dropdowns
 - [Button](../actions/Button.md) - The underlying trigger component
 - [Dialog](../overlays/Dialog.md) - The popover container component

package/docs/components/fields/SearchComboBox.md

@@ -1,15 +1,21 @@
 # SearchComboBox
 
-A search-styled combobox for "search and act" flows. The user types a query, picks a suggestion (or optionally submits raw text), a callback fires, and the input clears so they can search again. Unlike [ComboBox](./ComboBox.md), it does not hold a persistent selection and cannot be connected to a form.
+A single-line input for **search-and-act** flows. The user types a query, chooses a suggestion (or optionally submits the raw text), an action fires, and the input clears for the next query. SearchComboBox does not represent a selected value and cannot be connected to a form.
 
 ## When to Use
 
-- Command palettes, "add item" inputs, or global search where each interaction is a discrete action
+- "Add item" inputs, resource launchers, or focused searches where every result choice is a discrete action
 - Server-driven suggestions where results are fetched based on the query (use `filter={false}`)
 - When you want the input to reset after every pick instead of showing the selected label
 - When you optionally want to submit a free-form query that matches no suggestion
 
-For a field that keeps a selected value (e.g. inside a form), use [ComboBox](./ComboBox.md) instead.
+Choose a different component when the interaction has another outcome:
+
+- Use [ComboBox](./ComboBox.md) when the input should keep one selected value and participate in a form.
+- Use [FilterPicker](./FilterPicker.md) when a button should open a searchable list and keep one or more selected values.
+- Use [CommandMenu](../actions/CommandMenu.md) for a searchable, keyboard-first palette of application commands, usually opened from a trigger or dialog.
+- Use [CommandTextArea](./CommandTextArea.md) when suggestions insert tokens into multiline free-form text.
+- Use [SearchInput](./SearchInput.md) when users submit free text without choosing suggestions.
 
 ## Component
 
@@ -246,6 +252,9 @@ useEffect(() => {
 
 ## Related Components
 
-- [ComboBox](./ComboBox.md) - Use when you need a persistent selection that can be bound to a form
+- [ComboBox](./ComboBox.md) - Use for an input-based searchable field that keeps one selected value
+- [FilterPicker](./FilterPicker.md) - Use when searched items become persistent single or multiple field values
+- [CommandMenu](../actions/CommandMenu.md) - Use for searchable, keyboard-first application commands in a popover or dialog
+- [CommandTextArea](./CommandTextArea.md) - Use when suggestions insert tokens into multiline free-form text
 - [SearchInput](./SearchInput.md) - Use for free-text search without suggestions
 - [ListBox](./ListBox.md) - The underlying list component used in the popover

package/docs/components/fields/Select.md

@@ -1,14 +1,22 @@
 # Select
 
-A select allows users to choose a single option from a list of predefined choices. It provides a compact interface for selection with a dropdown menu that displays available options when activated.
+A conventional field for keeping one selected value from a predefined list. Select uses a compact button trigger and supports keyboard typeahead, but it does not show a search input or support multiple selection.
 
 ## When to Use
 
-- Allow users to select one option from a predefined list
-- Provide selection in forms where space is limited
-- Offer choices where only one selection is allowed
-- Create dropdown menus for navigation or filtering
-- Present structured options in a compact interface
+- Exactly one value should persist after the dropdown closes
+- The option set is short enough to scan or navigate with keyboard typeahead
+- A familiar compact field is preferable to an always-visible list
+- The value should participate in form state and validation
+
+Choose a different component when the interaction has another shape:
+
+- Use [Picker](./Picker.md) when you need multiple selection, checkboxes, select-all, or a custom trigger summary.
+- Use [FilterPicker](./FilterPicker.md) when users need a visible search field, especially for multiple selection.
+- Use [ComboBox](./ComboBox.md) for an always-visible text input that searches and keeps one selected value.
+- Use [SearchComboBox](./SearchComboBox.md) when choosing a result should fire an action and clear the input.
+- Use [Menu](../actions/Menu.md) with `MenuTrigger` for navigation or actions that do not represent a field value.
+- Use [RadioGroup](./RadioGroup.md) when a small set of choices should remain visible for direct comparison.
 
 ## Component
 
@@ -581,8 +589,11 @@ This component supports all [Field properties](../../FieldProperties.md) when us
 
 ## Related Components
 
-- [ComboBox](./ComboBox.md) - For searchable selection with filtering capabilities
-- [FilterPicker](./FilterPicker.md) - Alternative with different interaction patterns
+- [Picker](./Picker.md) - For richer button-triggered selection, including multiple values
+- [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
 - [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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cube-dev/ui-kit",
-  "version": "0.147.0",
+  "version": "0.147.1",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {