@cube-dev/ui-kit 0.146.1 → 0.147.0

package/dist/utils/react/isTextOnly.js

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

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.146.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.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.146.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.0 | 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.146.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.0 | 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.146.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.0 | 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.146.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.0 | 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.146.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.0 | 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.146.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.0 | 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.146.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.0 | 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.146.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.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.146.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.0 | 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.146.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.0 | 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.146.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.0 | 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.146.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.0 | 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.146.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.0 | 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.146.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.0 | 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.146.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.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.146.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.0 | 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.146.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.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.146.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.0 | 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.146.1 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.147.0 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.146.1";
+const VERSION = "0.147.0";
 const TASTY_VERSION = "2.8.0";
 if (typeof window !== "undefined") {
 	const version = VERSION;

package/docs/components/fields/ComboBox.md

@@ -672,7 +672,6 @@ This component supports all [Field properties](../../FieldProperties.md) when us
 - **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
 - **Grouped Item Navigation**: Improve keyboard navigation to allow jumping between section groups (e.g., Ctrl+Arrow to skip to next section)
-- **Empty State Component**: Allow passing custom React components for empty state when no results are found
 - **Prefix/Suffix Slots**: Add more flexible slot-based API for prefix and suffix content
 - **Item Descriptions**: Support for showing secondary text/descriptions in list items
 

package/docs/components/fields/Picker.md

@@ -56,7 +56,6 @@ A versatile selection component that combines a trigger button with a dropdown l
 - **`onClear`** `() => void` — Callback called when the clear button is pressed
 - **`onOpenChange`** `(isOpen: boolean) => void` — Callback called when the popover open state changes
 - **`filter`** `((textValue: string, inputValue: string) => boolean) | false` — Custom filter function for items. Pass `false` to disable filtering.
-- **`emptyLabel`** `ReactNode` — Content shown when no items match the filter or the collection is empty
 
 ### Base Properties
 

package/docs/components/fields/SearchComboBox.md

@@ -0,0 +1,251 @@
+# 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.
+
+## When to Use
+
+- Command palettes, "add item" inputs, or global search where each interaction 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.
+
+## 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 when you need a persistent selection that can be bound to a form
+- [SearchInput](./SearchInput.md) - Use for free-text search without suggestions
+- [ListBox](./ListBox.md) - The underlying list component used in the popover

package/package.json

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