@cube-dev/ui-kit 0.146.1 → 0.147.1

package/docs/components/fields/SearchComboBox.md

@@ -0,0 +1,260 @@
+# SearchComboBox
+
+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
+
+- "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
+
+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
+
+---
+
+### Properties
+
+- **`children`** `ReactNode` — SearchComboBox.Item elements that define the available suggestions
+- **`items`** `Iterable<T>` — Items for the listbox (alternative to children, enables data-driven mode)
+- **`placeholder`** `string` — Placeholder text when the input is empty
+- **`icon`** `ReactElement | null` — Icon rendered before the input. Defaults to a search icon; pass `null` to remove it
+- **`inputValue`** `string` — The current input value in controlled mode
+- **`defaultInputValue`** `string` — The default input value in uncontrolled mode
+- **`emptyLabel`** `ReactNode` (default: context-aware `No results found` / `Loading…`) — Label shown when the list is empty
+- **`filter`** `((textValue: string, inputValue: string) => boolean) | false` — Custom filter function, or `false` to disable internal filtering for external/server-side filtering
+- **`isClearable`** `boolean` (default: `true`) — Whether the input is clearable via the clear button or Escape key
+- **`hideTrigger`** `boolean` (default: `true`) — Whether the dropdown trigger button is hidden (search-field look)
+- **`popoverTrigger`** `'focus' | 'input' | 'manual'` (default: `input`) — How the popover is triggered
+- **`isLoading`** `boolean` (default: `false`) — Whether items are being loaded (e.g. from a server)
+- **`loadingDelay`** `number` (default: `1000`) — Delay in ms before the loading indicator appears
+- **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Size of the component
+- **`disabledKeys`** `Iterable<Key>` — Keys of suggestions that cannot be selected
+- **`onSelect`** `(key: string, textValue: string) => void` — Fired when a suggestion is picked; the input clears afterwards
+- **`onSubmit`** `(value: string) => void` — Opt-in. Fired when Enter is pressed with no focused/available option; the input clears afterwards
+- **`onInputChange`** `(value: string) => void` — Fired when the input text changes
+- **`onClear`** `() => void` — Fired when the input is cleared
+- **`onOpenChange`** `(isOpen: boolean) => void` — Fired when the popover opens or closes
+- **`onFocus`** `() => void` — Fired when focus enters the component
+- **`onBlur`** `() => void` — Fired when focus leaves the component
+- **`onKeyDown`** `(e: KeyboardEvent) => void` — Fired when a key is pressed on the input
+- **`prefix`** `ReactNode` — Content rendered before the input
+- **`suffix`** `ReactNode` — Content rendered after the input
+- **`suffixPosition`** `'before' | 'after'` (default: `before`) — Position of suffix relative to status icons
+- **`direction`** `'top' | 'bottom'` (default: `bottom`) — Preferred direction for the dropdown
+- **`shouldFlip`** `boolean` (default: `true`) — Whether the dropdown flips to fit in the viewport
+- **`overlayOffset`** `number` (default: `8`) — Distance between input and dropdown in pixels
+- **`containerPadding`** `number` (default: `8`) — Minimum padding between the popover and viewport edges
+
+#### Notable Properties
+
+**onSelect vs onSubmit** — `onSelect(key, textValue)` fires when a suggestion from the list is chosen. When the popover has visible suggestions, pressing Enter selects the highlighted one (or the first visible one when nothing is highlighted). `onSubmit(value)` is an opt-in escape hatch: only when there are no visible suggestions and the user presses Enter is the raw trimmed text submitted. Without `onSubmit`, Enter with no visible suggestion is a no-op. Both callbacks clear the input afterwards.
+
+**filter** — By default the list is filtered client-side with a contains match. Pass a custom `(textValue, inputValue) => boolean`, or set `filter={false}` to disable internal filtering entirely and provide already-filtered `items` yourself (server-side filtering).
+
+**isLoading + loadingDelay** — While `isLoading` is `true`, the previous results stay visible. The loading indicator (and the `Loading…` empty label) only appear after `loadingDelay` has elapsed, so fast responses never flash a loading state.
+
+### Base Properties
+
+Supports [Base properties](../../BaseProperties.md)
+
+### Field Properties
+
+Supports the layout-related [Field properties](../../FieldProperties.md) (`label`, `description`, `message`, `labelPosition`, etc.). Note that SearchComboBox is not form-connected: it does not accept `name`/`rules` and does not participate in form state or validation.
+
+### Styling Properties
+
+#### styles
+
+Customizes the root wrapper element of the SearchComboBox (the input container).
+
+**Sub-elements:**
+- `Prefix` - Container for prefix content and icons
+- `Suffix` - Container for suffix content, status icons, and action buttons
+- `InputIcon` - Container for the left icon
+
+#### inputStyles
+
+Customizes the text input element where users type.
+
+#### triggerStyles
+
+Customizes the dropdown trigger button (visible when `hideTrigger={false}`).
+
+#### listBoxStyles
+
+Customizes the dropdown list container that displays suggestions.
+
+#### overlayStyles
+
+Customizes the popover overlay wrapper that contains the list.
+
+#### optionStyles
+
+Customizes individual option items in the dropdown list.
+
+#### sectionStyles
+
+Customizes section containers when using grouped suggestions.
+
+#### headingStyles
+
+Customizes section heading elements within grouped suggestions.
+
+### Style Properties
+
+These properties allow direct style application without using the `styles` prop:
+
+- **Base:** `display`, `font`, `preset`, `hide`, `whiteSpace`, `opacity`, `transition`
+- **Position:** `gridArea`, `order`, `gridColumn`, `gridRow`, `placeSelf`, `alignSelf`, `justifySelf`, `zIndex`, `margin`, `inset`, `position`, `scrollMargin`
+- **Dimension:** `width`, `height`, `flexBasis`, `flexGrow`, `flexShrink`, `flex`
+- **Block:** `border`, `radius`, `shadow`, `outline`
+- **Color:** `color`, `fill`, `fade`, `image`
+
+### Modifiers
+
+The `mods` property accepts the following modifiers you can override:
+
+- **`invalid`** `boolean` — Applied when validation state is invalid
+- **`valid`** `boolean` — Applied when validation state is valid
+- **`disabled`** `boolean` — Applied when the component is disabled
+- **`focused`** `boolean` — Applied when the input has focus
+- **`loading`** `boolean` — Applied when the loading indicator is visible
+- **`prefix`** `boolean` — Applied when prefix content is present
+- **`suffix`** `boolean` — Applied when suffix content is present
+- **`clearable`** `boolean` — Applied when the clear button is visible
+
+## Variants
+
+### Sizes
+
+### With Trigger Button
+
+## Examples
+
+### Clears on Select
+
+```jsx
+<SearchComboBox
+  label="Add a fruit"
+  placeholder="Search a fruit..."
+  onSelect={(key, textValue) => addFruit(key, textValue)}
+>
+  <SearchComboBox.Item key="apple">Apple</SearchComboBox.Item>
+  <SearchComboBox.Item key="banana">Banana</SearchComboBox.Item>
+</SearchComboBox>
+```
+
+### Submit Free-form Text
+
+```jsx
+<SearchComboBox
+  label="Search or add a tag"
+  placeholder="Type and press Enter..."
+  onSubmit={(value) => addTag(value)}
+>
+  <SearchComboBox.Item key="apple">Apple</SearchComboBox.Item>
+  <SearchComboBox.Item key="banana">Banana</SearchComboBox.Item>
+</SearchComboBox>
+```
+
+### Custom Empty Label
+
+```jsx
+<SearchComboBox
+  label="Search a fruit"
+  emptyLabel="No fruit matches your search"
+>
+  <SearchComboBox.Item key="apple">Apple</SearchComboBox.Item>
+  <SearchComboBox.Item key="banana">Banana</SearchComboBox.Item>
+</SearchComboBox>
+```
+
+### Server-side Filtering
+
+Set `filter={false}` and drive `items` from your own (debounced) fetch. Toggle `isLoading` while the request is in flight — the indicator only appears if it takes longer than `loadingDelay`.
+
+```jsx
+const [value, setValue] = useState('');
+const [isLoading, setIsLoading] = useState(false);
+const [results, setResults] = useState([]);
+
+useEffect(() => {
+  if (!value.trim()) {
+    setResults([]);
+    return;
+  }
+  setIsLoading(true);
+  const handle = setTimeout(async () => {
+    setResults(await fetchCountries(value));
+    setIsLoading(false);
+  }, 400); // debounce is your responsibility
+  return () => clearTimeout(handle);
+}, [value]);
+
+<SearchComboBox
+  filter={false}
+  label="Country"
+  placeholder="Search countries..."
+  inputValue={value}
+  isLoading={isLoading}
+  items={results}
+  emptyLabel={value.trim() ? 'No countries found' : 'Type to search'}
+  onInputChange={setValue}
+  onSelect={(key) => selectCountry(key)}
+>
+  {(item) => <SearchComboBox.Item key={item.key}>{item.name}</SearchComboBox.Item>}
+</SearchComboBox>
+```
+
+## Accessibility
+
+### Keyboard Navigation
+
+- `Tab` - Moves focus to/from the input
+- `ArrowDown` - Opens the popover (if closed) or moves focus to the next suggestion
+- `ArrowUp` - Opens the popover (if closed) or moves focus to the previous suggestion
+- `Enter` - Selects the highlighted suggestion, falling back to the first visible suggestion; when no suggestion is visible, submits the raw text via `onSubmit`
+- `Escape` - Closes the popover (if open) or clears the input (if clearable and popover closed)
+- `Home` / `End` - Moves focus to the first / last suggestion (when the popover is open)
+- Typing - Filters suggestions based on the input value
+
+### ARIA Properties
+
+- `role="combobox"` - Identifies the input as a combobox
+- `aria-expanded` - Indicates whether the popover is open
+- `aria-haspopup="listbox"` - Indicates the combobox has a listbox popup
+- `aria-controls` - References the listbox ID when the popover is open
+- `aria-activedescendant` - References the currently focused suggestion
+- `aria-label` - Provides an accessible label when no visible label exists
+
+## Best Practices
+
+1. **Do**: Debounce server requests before updating `items`
+   ```jsx
+   <SearchComboBox filter={false} isLoading={isLoading} items={results} />
+   ```
+
+2. **Do**: Provide a meaningful `emptyLabel` for both the empty and loading states
+   ```jsx
+   <SearchComboBox emptyLabel={query ? 'No results' : 'Type to search'} />
+   ```
+
+3. **Don't**: Use SearchComboBox to capture a persistent value in a form — use [ComboBox](./ComboBox.md) instead
+
+## Related Components
+
+- [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.146.1",
+  "version": "0.147.1",
   "type": "module",
   "description": "UIKit for Cube Projects",
   "repository": {