@cube-dev/ui-kit 0.127.3 → 0.128.0

package/dist/tokens/sizes.js

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

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.0 | 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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.0 | 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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.0 | 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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.0 | Cube Dev Team */
 import React, { createContext, useCallback, useContext, useEffect, 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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.0 | Cube Dev Team */
 import { mergeStyles } from "@tenphi/tasty";
 import { useMemo } from "react";
 

package/dist/utils/react/useQaProps.js

@@ -1,4 +1,4 @@
-/** @license MIT | @cube-dev/ui-kit v0.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.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.127.3 | Cube Dev Team */
+/** @license MIT | @cube-dev/ui-kit v0.128.0 | Cube Dev Team */
 //#region src/version.ts
-const VERSION = "0.127.3";
+const VERSION = "0.128.0";
 if (typeof window !== "undefined") {
 	const version = VERSION;
 	window.CubeUIKit = window.CubeUIKit || { version };

package/docs/components/fields/FilterListBox.md

@@ -28,7 +28,7 @@ A searchable list selection component that combines a ListBox with an integrated
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — FilterListBox size
 - **`searchPlaceholder`** `string` (default: `Search...`) — Placeholder text in the search input
 - **`filter`** `((textValue: string, inputValue: string) => boolean) | false` — Custom filter function or `false` to disable filtering
-- **`emptyLabel`** `ReactNode` (default: `No items` / `No results found`) — Label displayed when no items match
+- **`emptyLabel`** `ReactNode` (default: context-aware: `No items` or `No results found`) — Label shown when the list is empty. When provided, overrides both defaults for any empty state
 - **`allowsCustomValue`** `boolean` (default: `false`) — Whether to allow custom values not in the options list
 - **`isCheckable`** `boolean` (default: `false`) — Whether to show checkboxes for multiple selection
 - **`shouldFocusWrap`** `boolean` (default: `false`) — Whether keyboard navigation should wrap around
@@ -44,6 +44,7 @@ A searchable list selection component that combines a ListBox with an integrated
 - **`onOptionClick`** `(key: Key) => void` — Callback when an option is clicked
 - **`items`** `Iterable<T>` — Array of items for dynamic content with render function pattern
 - **`isLoading`** `boolean` (default: `false`) — Whether the FilterListBox is in a loading state (shows loading icon in search input)
+- **`isLoadingItems`** `boolean` (default: `false`) — Whether items are currently loading. Shows a loading icon in the search input suffix
 - **`autoFocus`** `boolean` — Whether the search input should have autofocus
 - **`customValueProps`** `Partial<CubeItemProps>` — Props to apply to existing custom values (already selected but not in predefined options)
 - **`newCustomValueProps`** `Partial<CubeItemProps>` — Props to apply to new custom values appearing in search results (merged with `customValueProps`)
@@ -142,6 +143,7 @@ The `mods` property accepts the following modifiers you can override:
 - `disabled` `boolean` — Applied when `isDisabled={true}`
 - `focused` `boolean` — Applied when the FilterListBox has focus
 - `loading` `boolean` — Applied when `isLoading={true}`
+- `loading-items` `boolean` — Applied when `isLoadingItems={true}`
 - `searchable` `boolean` — Always true for FilterListBox
 - `prefix` `boolean` — Applied when loading icon is shown
 
@@ -622,36 +624,44 @@ Use `customValueProps` to style existing custom values and `newCustomValueProps`
 - `customValueProps` - Applied to custom values that are already selected
 - `newCustomValueProps` - Applied to new custom values appearing when typing in search (merged with `customValueProps`)
 
-### External Filtering
+### Server-Side / Dynamic Search
 
-For server-side filtering or complex custom logic, use `filter={false}` with controlled search:
+For server-side filtering, use `filter={false}` with controlled search and dynamic `items`. Items are replaced when the server responds, and `isLoadingItems` shows a subtle spinner in the search input while the fetch is in flight.
 
 ```jsx
+const [items, setItems] = useState(initialItems);
 const [searchValue, setSearchValue] = useState('');
-const [filteredItems, setFilteredItems] = useState(allItems);
+const [isLoadingItems, setIsLoadingItems] = useState(false);
 
-useEffect(() => {
-  // Your custom filtering logic (e.g., API call, complex algorithm)
-  const filtered = customFilterLogic(allItems, searchValue);
-  setFilteredItems(filtered);
-}, [searchValue, allItems]);
+const handleSearchChange = useCallback((value) => {
+  setSearchValue(value);
+  setIsLoadingItems(true);
+  debouncedFetch(value)
+    .then(setItems)
+    .finally(() => setIsLoadingItems(false));
+}, []);
 
 <FilterListBox
+  items={items}
   searchValue={searchValue}
-  onSearchChange={setSearchValue}
+  onSearchChange={handleSearchChange}
   filter={false}
+  isLoadingItems={isLoadingItems}
 >
-  {filteredItems.map(item => (
+  {(item) => (
     <FilterListBox.Item key={item.id}>{item.name}</FilterListBox.Item>
-  ))}
+  )}
 </FilterListBox>
 ```
 
-**When to use:**
-- Server-side filtering for large datasets
-- Complex custom search algorithms
-- Debounced API calls
-- Multi-field search logic
+**How it works:**
+- **`filter={false}`** disables client-side filtering so items appear exactly as the server returns them
+- **`searchValue` + `onSearchChange`** give you control over the search input; debounce and fetch on your side
+- **`items`** is reactive — replace it with server results and the list updates automatically
+- **`isLoadingItems`** shows a loading spinner in the search input suffix while fetching. While loading, stale items that do not text-match the current search are hidden client-side so the user only sees relevant suggestions
+- **Selected custom values** (with `allowsCustomValue` in multi-select) are filtered against the search input too, so they don't appear when they don't match
+- **`emptyLabel`** can be used to customize the empty state message (e.g. `"Loading items..."` during initial load)
+- Debouncing is the consumer's responsibility (300-500ms is typical)
 
 ### Escape Key Handling
 

package/docs/components/fields/FilterPicker.md

@@ -24,6 +24,7 @@ A versatile selection component that combines a trigger button with a searchable
 - **`selectionMode`** `'single' | 'multiple'` (default: `single`) — Selection mode for the picker
 - **`allowsCustomValue`** `boolean` (default: `false`) — Whether to allow entering custom values that are not present in the predefined options
 - **`isClearable`** `boolean` (default: `false`) — Whether the filter picker is clearable using a clear button in the rightIcon slot
+- **`isLoadingItems`** `boolean` (default: `false`) — Whether items are currently loading. Shows a loading spinner in the search input suffix inside the popover. Unlike `isLoading`, does not disable the trigger.
 - **`disallowEmptySelection`** `boolean` (default: `false`) — Whether to disallow empty selection
 - **`disabledKeys`** `Key[]` — Array of keys for disabled items
 - **`items`** `Iterable<T>` — Array of items to render when using the render function pattern for large datasets with dynamic content
@@ -33,7 +34,7 @@ A versatile selection component that combines a trigger button with a searchable
 - **`theme`** `'default' | 'special'` (default: `default`) — Button theme
 - **`size`** `'small' | 'medium' | 'large'` (default: `medium`) — Size of the picker component
 - **`searchPlaceholder`** `string` — Placeholder text in the search input
-- **`emptyLabel`** `string` — Custom label to display when no results are found after filtering
+- **`emptyLabel`** `ReactNode` (default: context-aware: `No items` or `No results found`) — Label shown when the list is empty. When provided, overrides both defaults for any empty state
 - **`filter`** `((textValue: string, inputValue: string) => boolean) | false` — Custom filter function for determining if an option should be included in search results
 - **`header`** `ReactNode` — Custom header content
 - **`footer`** `ReactNode` — Custom footer content
@@ -455,6 +456,22 @@ const categories = [
 </FilterPicker>
 ```
 
+### Loading Items
+
+Use `isLoadingItems` to indicate that items are currently being fetched. Unlike `isLoading`, the trigger stays enabled so users can still open the popover and interact with items that have already loaded. A loading spinner appears in the search input suffix.
+
+```jsx
+<FilterPicker
+  label="Loading Items"
+  placeholder="Select a fruit..."
+  isLoadingItems={true}
+  selectionMode="multiple"
+>
+  <FilterPicker.Item key="apple">Apple</FilterPicker.Item>
+  <FilterPicker.Item key="banana">Banana</FilterPicker.Item>
+</FilterPicker>
+```
+
 ### Complex Example
 
 ```jsx
@@ -714,78 +731,60 @@ The clear button:
 - Calls the optional `onClear` callback
 - Is hidden when the picker is disabled or read-only
 
-### External Filtering
-
-FilterPicker provides two approaches for implementing external filtering when you need to control the filtering logic outside the component:
+### Server-Side / Dynamic Search
 
-#### Approach 1: Disabled Internal Filtering
-
-Use `filter={false}` to disable internal filtering while providing pre-filtered items:
-
-```jsx
-const [externalSearch, setExternalSearch] = useState('');
-
-const filteredFruits = useMemo(() => {
-  if (!externalSearch.trim()) return allFruits;
-  return allFruits.filter((fruit) =>
-    fruit.label.toLowerCase().includes(externalSearch.toLowerCase())
-  );
-}, [externalSearch]);
-
-<FilterPicker
-  label="Select Fruits"
-  placeholder="Choose fruits..."
-  selectionMode="multiple"
-  filter={false}
-  items={filteredFruits}
-  searchPlaceholder="Type to search..."
->
-  {(fruit) => (
-    <FilterPicker.Item key={fruit.key}>{fruit.label}</FilterPicker.Item>
-  )}
-</FilterPicker>
-```
-
-#### Approach 2: Controlled Search Input
-
-Use `searchValue` and `onSearchChange` for complete control over the search behavior:
+When items come from a backend API, use `filter={false}` with controlled search to let the server handle filtering. Items are replaced when the response arrives, and `isLoadingItems` shows a subtle spinner in the search input while the fetch is in flight.
 
 ```jsx
+const [items, setItems] = useState(initialItems);
 const [searchValue, setSearchValue] = useState('');
+const [isLoadingItems, setIsLoadingItems] = useState(false);
 
-// Simulate debounced search
-const [processedSearch, setProcessedSearch] = useState('');
-useEffect(() => {
-  const timer = setTimeout(() => setProcessedSearch(searchValue), 300);
-  return () => clearTimeout(timer);
-}, [searchValue]);
-
-const filteredFruits = useMemo(() => {
-  if (!processedSearch.trim()) return allFruits;
-  return allFruits.filter((fruit) =>
-    fruit.label.toLowerCase().includes(processedSearch.toLowerCase())
-  );
-}, [processedSearch]);
+const handleSearchChange = useCallback((value) => {
+  setSearchValue(value);
+  setIsLoadingItems(true);
+  debouncedFetch(value)
+    .then(setItems)
+    .finally(() => setIsLoadingItems(false));
+}, []);
 
 <FilterPicker
-  label="Select Fruits"
-  placeholder="Choose fruits..."
-  selectionMode="multiple"
+  items={items}
   searchValue={searchValue}
+  onSearchChange={handleSearchChange}
   filter={false}
-  items={filteredFruits}
-  onSearchChange={setSearchValue}
+  sortSelectedToTop={false}
+  isLoadingItems={isLoadingItems}
+  placeholder="Search items..."
+  selectionMode="multiple"
+  onOpenChange={(isOpen) => {
+    if (!isOpen) {
+      setSearchValue('');
+      setItems(initialItems);
+    }
+  }}
 >
-  {(fruit) => (
-    <FilterPicker.Item key={fruit.key}>{fruit.label}</FilterPicker.Item>
+  {(item) => (
+    <FilterPicker.Item key={item.id} textValue={item.name}>
+      {item.name}
+    </FilterPicker.Item>
   )}
 </FilterPicker>
 ```
 
-**When to use each approach:**
-- **`filter={false}`**: Simpler approach when you just need to pre-filter items without controlling the search input itself. Good for server-side filtering or custom filter logic.
-- **Controlled Search**: Use when you need full control over the search input (debouncing, external UI sync, clearing from outside, or tracking search analytics).
-- **Combine Both**: You can use both together for maximum control - controlled search input with external filtering.
+**How it works:**
+- **`filter={false}`** disables client-side filtering so items are shown exactly as the server returns them
+- **`searchValue` + `onSearchChange`** give you control over the search input; debounce and fetch on your side
+- **`items`** is a reactive prop — replace it with server results and the list updates automatically
+- **`isLoadingItems`** shows a loading spinner in the search input suffix while fetching. While loading, stale items that do not text-match the current search are hidden client-side so the user only sees relevant suggestions
+- **Selected custom values** (with `allowsCustomValue` in multi-select) are filtered against the search input too, so they don't appear when they don't match
+- **`sortSelectedToTop={false}`** is recommended when the server controls item order
+- **`emptyLabel`** can be used to customize the empty state message (e.g. `"Loading items..."` during initial load)
+- **Reset on close** — use `onOpenChange` to restore the initial item set and clear the search when the popover closes, ensuring the trigger label resolves correctly
+
+**Tips:**
+- Debouncing is the consumer's responsibility (300-500ms is typical)
+- During the debounce delay, old items remain visible — if you want instant client-side feedback while waiting, use a filter function instead of `false`
 
 ## Performance
 

package/package.json

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