feat(FilterListBox): controllable search (#816)

Author: tenphi

.changeset/tender-trees-sleep.md

@@ -0,0 +1,5 @@
+---
+"@cube-dev/ui-kit": patch
+---
+
+Support controllable filtering in FilterListBox and FilterPicker.

src/components/fields/FilterListBox/FilterListBox.test.tsx

@@ -354,6 +354,66 @@ describe('<FilterListBox />', () => {
   });
 
   describe('Search functionality', () => {
+    it('should work with controlled search and filter={false} for external filtering', async () => {
+      const onSearchChange = jest.fn();
+
+      const { getByPlaceholderText, getByText, queryByText, rerender } = render(
+        <FilterListBox
+          label="Select a fruit"
+          searchPlaceholder="Search..."
+          searchValue=""
+          filter={false}
+          onSearchChange={onSearchChange}
+        >
+          {basicItems}
+        </FilterListBox>,
+      );
+
+      const searchInput = getByPlaceholderText('Search...');
+
+      // Initially all options should be visible
+      expect(getByText('Apple')).toBeInTheDocument();
+      expect(getByText('Banana')).toBeInTheDocument();
+      expect(getByText('Cherry')).toBeInTheDocument();
+
+      // Type in search - should call onSearchChange but NOT filter internally
+      await act(async () => {
+        await userEvent.type(searchInput, 'app');
+      });
+
+      // onSearchChange should be called for each character as user types
+      expect(onSearchChange).toHaveBeenCalledTimes(3);
+      expect(onSearchChange).toHaveBeenCalledWith('a');
+      expect(onSearchChange).toHaveBeenCalledWith('p');
+
+      // All items should still be visible because filter={false} disables internal filtering
+      expect(getByText('Apple')).toBeInTheDocument();
+      expect(getByText('Banana')).toBeInTheDocument();
+      expect(getByText('Cherry')).toBeInTheDocument();
+
+      // Simulate external filtering by providing only matching items
+      const filteredItems = [
+        <FilterListBox.Item key="apple">Apple</FilterListBox.Item>,
+      ];
+
+      rerender(
+        <FilterListBox
+          label="Select a fruit"
+          searchPlaceholder="Search..."
+          searchValue="app"
+          filter={false}
+          onSearchChange={onSearchChange}
+        >
+          {filteredItems}
+        </FilterListBox>,
+      );
+
+      // Now only Apple should be visible (externally filtered)
+      expect(getByText('Apple')).toBeInTheDocument();
+      expect(queryByText('Banana')).not.toBeInTheDocument();
+      expect(queryByText('Cherry')).not.toBeInTheDocument();
+    });
+
     it('should filter options based on search input', async () => {
       const { getByPlaceholderText, getByText, queryByText } = render(
         <FilterListBox label="Select a fruit" searchPlaceholder="Search...">

src/components/fields/FilterListBox/FilterListBox.tsx

@@ -5,6 +5,7 @@ import React, {
   ReactElement,
   ReactNode,
   RefObject,
+  useCallback,
   useLayoutEffect,
   useMemo,
   useRef,
@@ -115,8 +116,11 @@ export interface CubeFilterListBoxProps<T>
   searchPlaceholder?: string;
   /** Whether the search input should have autofocus */
   autoFocus?: boolean;
-  /** Custom filter function for determining if an option should be included in search results */
-  filter?: FilterFn;
+  /**
+   * Custom filter function for determining if an option should be included in search results.
+   * Pass `false` to disable internal filtering completely (useful for external filtering).
+   */
+  filter?: FilterFn | false;
   /** Custom label to display when no results are found after filtering */
   emptyLabel?: ReactNode;
   /** Custom styles for the search input */
@@ -160,6 +164,18 @@ export interface CubeFilterListBoxProps<T>
    * These are merged with customValueProps for new custom values.
    */
   newCustomValueProps?: Partial<CubeItemProps<T>>;
+
+  /**
+   * Controlled search value. When provided, the search input becomes controlled.
+   * Use with `onSearchChange` to manage the search state externally.
+   */
+  searchValue?: string;
+
+  /**
+   * Callback fired when the search input value changes.
+   * Use with `searchValue` for controlled search input.
+   */
+  onSearchChange?: (value: string) => void;
 }
 
 const PROP_STYLES = [...BASE_STYLES, ...OUTER_STYLES, ...COLOR_STYLES];
@@ -247,6 +263,8 @@ export const FilterListBox = forwardRef(function FilterListBox<
     allValueProps,
     customValueProps,
     newCustomValueProps,
+    searchValue: controlledSearchValue,
+    onSearchChange,
     ...otherProps
   } = props;
 
@@ -386,13 +404,30 @@ export const FilterListBox = forwardRef(function FilterListBox<
     (props as any)['aria-label'] ||
     (typeof label === 'string' ? label : undefined);
 
-  const [searchValue, setSearchValue] = useState('');
+  // Controlled/uncontrolled search value pattern
+  const [internalSearchValue, setInternalSearchValue] = useState('');
+  const isSearchControlled = controlledSearchValue !== undefined;
+  const searchValue = isSearchControlled
+    ? controlledSearchValue
+    : internalSearchValue;
+
+  const handleSearchChange = useCallback(
+    (value: string) => {
+      if (!isSearchControlled) {
+        setInternalSearchValue(value);
+      }
+      onSearchChange?.(value);
+    },
+    [isSearchControlled, onSearchChange],
+  );
+
   const { contains } = useFilter({ sensitivity: 'base' });
 
-  // Choose the text filter function: user-provided `filter` prop (if any)
+  // Choose the text filter function: user-provided `filter` prop (if any),
   // or the default `contains` helper from `useFilter`.
+  // When filter={false}, disable filtering completely.
   const textFilterFn = useMemo<FilterFn>(
-    () => filter || contains,
+    () => (filter === false ? () => true : filter || contains),
     [filter, contains],
   );
 
@@ -774,7 +809,7 @@ export const FilterListBox = forwardRef(function FilterListBox<
         if (searchValue) {
           // Clear the current search if any text is present.
           e.preventDefault();
-          setSearchValue('');
+          handleSearchChange('');
         } else {
           // Notify parent that Escape was pressed on an empty input.
           if (onEscape) {
@@ -893,7 +928,7 @@ export const FilterListBox = forwardRef(function FilterListBox<
         }
         onChange={(e) => {
           const value = e.target.value;
-          setSearchValue(value);
+          handleSearchChange(value);
         }}
         {...keyboardProps}
         {...modAttrs(mods)}