@commercetools/nimbus 0.0.0-canary-20260114153122 → 0.0.0-canary-20260116085607

package/dist/components/combobox/components/combobox.hidden-input.d.ts

@@ -0,0 +1,17 @@
+import { ComboBoxHiddenInputProps } from '../combobox.types';
+/**
+ * # ComboBoxHiddenInput (Internal Component)
+ *
+ * Hidden input element for form submission.
+ * Follows React Aria's pattern for ComboBox form integration.
+ *
+ * By default, submits the selected item's key.
+ * When formValue="text" or allowsCustomOptions=true, submits the text value instead.
+ *
+ * @see https://react-spectrum.adobe.com/react-aria/ComboBox.html#html-forms
+ * @internal
+ */
+export declare const ComboBoxHiddenInput: {
+    <T extends object>(props: ComboBoxHiddenInputProps<T>): import("react/jsx-runtime").JSX.Element | null;
+    displayName: string;
+};

package/dist/components/combobox/components/combobox.input.d.ts

@@ -0,0 +1,20 @@
+import { ComboBoxInputProps } from '../combobox.types';
+/**
+ * # ComboBox.Input (Internal Component)
+ *
+ * Internal text input field for filtering and typing in the combobox.
+ * Automatically rendered by ComboBox.Trigger - not exposed to consumers.
+ *
+ * Consumes React Aria's InputContext which provides all necessary ARIA attributes
+ * (role, aria-autocomplete, aria-controls, aria-expanded, etc.).
+ *
+ * Input width dynamically adjusts to match the text content or placeholder length,
+ * collapsing to 1px when empty to avoid creating blank lines in multi-select mode.
+ *
+ * @internal
+ * @supportsStyleProps
+ */
+export declare const ComboBoxInput: {
+    (props: ComboBoxInputProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/components/combobox/components/combobox.leading-element.d.ts

@@ -1,11 +1,11 @@
 /**
- * This component is needed as proxy around the leading element slot.
- * It measures the width of whatever the user hands over via `leadingElement`
- * and provides this width as css variable on the root element.
+ * # ComboBox.LeadingElement (Internal Component)
  *
- * the css variable is then used in the recipe to update the left-padding of the
- * input.
+ * Internal wrapper component that positions the leading element (icon, avatar, etc.)
+ * within the combobox trigger using CSS Grid's named template area.
+ * Automatically rendered by ComboBox.Trigger when leadingElement prop is provided.
  *
+ * @internal
  * @supportsStyleProps
  */
 export declare const ComboBoxLeadingElement: ({ children, }: {

package/dist/components/combobox/components/combobox.listbox.d.ts

@@ -0,0 +1,27 @@
+import { ComboBoxListBoxProps } from '../combobox.types';
+/**
+ * # ComboBox.ListBox
+ *
+ * Container for the dropdown options list that displays filtered results.
+ * Use the render prop pattern - do NOT manually map over items as this is less performant.
+ * The item is automatically provided from the items passed to ComboBox.Root.
+ *
+ * Automatically injects `id` and `textValue` props to Option components from item metadata.
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.ListBox>
+ *   {(item) => (
+ *     <ComboBox.Option>
+ *       {item.name}
+ *     </ComboBox.Option>
+ *   )}
+ * </ComboBox.ListBox>
+ * ```
+ *
+ * @supportsStyleProps
+ */
+export declare function ComboBoxListBox<T extends object>({ children, ref, ...restProps }: ComboBoxListBoxProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare namespace ComboBoxListBox {
+    var displayName: string;
+}

package/dist/components/combobox/components/combobox.option.d.ts

@@ -1,10 +1,34 @@
 import { ComboBoxOptionProps } from '../combobox.types';
 /**
- * ComboBox.Option - An individual selectable option within the combobox
+ * # ComboBox.Option
+ *
+ * Individual option within the combobox listbox.
+ * Wraps React Aria's ListBoxItem for automatic ARIA management.
+ * Displays a checkmark indicator for selected items in multi-select mode.
+ * Supports render prop pattern for custom rendering.
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root>
+ *   <ComboBox.Option id="1">Option 1</ComboBox.Option>
+ *   <ComboBox.Option id="2">Option 2</ComboBox.Option>
+ * </ComboBox.Root>
+ * ```
+ *
+ * @example Render prop pattern
+ * ```tsx
+ * <ComboBox.Option id="1">
+ *   {({ isSelected, isDisabled }) => (
+ *     <div>
+ *       Option 1 {isSelected && "(Selected)"}
+ *     </div>
+ *   )}
+ * </ComboBox.Option>
+ * ```
  *
  * @supportsStyleProps
  */
-export declare const ComboBoxOption: {
-    <T extends object>({ children, ref, ...props }: ComboBoxOptionProps<T>): import("react/jsx-runtime").JSX.Element;
-    displayName: string;
-};
+export declare function ComboBoxOption<T extends object>({ children, ref, ...props }: ComboBoxOptionProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare namespace ComboBoxOption {
+    var displayName: string;
+}

package/dist/components/combobox/components/combobox.popover.d.ts

@@ -0,0 +1,27 @@
+import { ComboBoxPopoverProps } from '../combobox.types';
+/**
+ * # ComboBox.Popover
+ *
+ * Popover wrapper for the options dropdown list.
+ * Uses Nimbus Popover component which reads from PopoverContext provided by the custom context provider.
+ *
+ * The PopoverContext provides:
+ * - open state
+ * - positioning configuration (fixed strategy, bottom-start placement, --nimbus-combobox-trigger-width CSS var)
+ * - positionReference (trigger ref for proper positioning)
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Popover>
+ *   <ComboBox.ListBox>
+ *     {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+ *   </ComboBox.ListBox>
+ * </ComboBox.Popover>
+ * ```
+ *
+ * @supportsStyleProps
+ */
+export declare const ComboBoxPopover: {
+    ({ children, ref, ...restProps }: ComboBoxPopoverProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/components/combobox/components/combobox.root-context.d.ts

@@ -0,0 +1,13 @@
+import { ComboBoxRootContextValue } from '../combobox.types';
+/**
+ * Context for ComboBox state and configuration.
+ * Uses 'object' as the generic type since different ComboBox instances
+ * can have different item types, and TypeScript can't track this through context.
+ */
+export declare const ComboBoxRootContext: import('react').Context<ComboBoxRootContextValue<object> | null>;
+/**
+ * Hook to access ComboBox context with proper typing.
+ * The generic type T represents the item type used in the ComboBox.
+ * At runtime, the context contains the correct type from ComboBox.Root.
+ */
+export declare const useComboBoxRootContext: <T extends object = object>() => ComboBoxRootContextValue<T>;

package/dist/components/combobox/components/combobox.root.d.ts

@@ -1,12 +1,32 @@
 import { ComboBoxRootProps } from '../combobox.types';
 /**
- * # ComboBox
+ * # ComboBox.Root
  *
- * A combo box combines a text input with a dropdown list, allowing users to filter a list of options to items matching a query.
+ * Root component for ComboBox that provides state management and context for all child components.
+ * Handles selection state, input filtering, menu open/close, and custom option creation.
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root
+ *   items={items}
+ *   getKey={(item) => item.id}
+ *   getTextValue={(item) => item.name}
+ *   onSelectionChange={(keys) => console.log(keys)}
+ * >
+ *   <ComboBox.Trigger>
+ *     <ComboBox.Input />
+ *   </ComboBox.Trigger>
+ *   <ComboBox.Popover>
+ *     <ComboBox.ListBox>
+ *       {(item) => <ComboBox.Option>{item.name}</ComboBox.Option>}
+ *     </ComboBox.ListBox>
+ *   </ComboBox.Popover>
+ * </ComboBox.Root>
+ * ```
  *
  * @supportsStyleProps
  */
-export declare const ComboBoxRoot: {
-    <T extends object>({ children, ref, ...props }: ComboBoxRootProps<T>): import("react/jsx-runtime").JSX.Element;
-    displayName: string;
-};
+export declare function ComboBoxRoot<T extends object>(props: ComboBoxRootProps<T>): import("react/jsx-runtime").JSX.Element;
+export declare namespace ComboBoxRoot {
+    var displayName: string;
+}

package/dist/components/combobox/components/combobox.section.d.ts

@@ -0,0 +1,32 @@
+import { RefAttributes } from 'react';
+import { ComboBoxSectionProps } from '../combobox.types';
+/**
+ * # ComboBox.Section
+ *
+ * Section grouping for options with optional label header.
+ * Wraps React Aria's ListBoxSection component.
+ * Supports both static children and collection rendering with items.
+ *
+ * @example Static children
+ * ```tsx
+ * <ComboBox.ListBox>
+ *   <ComboBox.Section label="Fruits">
+ *     <ComboBox.Option id="apple">Apple</ComboBox.Option>
+ *     <ComboBox.Option id="banana">Banana</ComboBox.Option>
+ *   </ComboBox.Section>
+ * </ComboBox.ListBox>
+ * ```
+ *
+ * @example Collection rendering
+ * ```tsx
+ * <ComboBox.Section label="Fruits" items={fruits}>
+ *   {(item) => <ComboBox.Option id={item.id}>{item.name}</ComboBox.Option>}
+ * </ComboBox.Section>
+ * ```
+ *
+ * @supportsStyleProps
+ */
+export declare function ComboBoxSection<T extends object>({ children, label, items, ref, ...props }: ComboBoxSectionProps<T> & RefAttributes<HTMLDivElement>): import("react/jsx-runtime").JSX.Element;
+export declare namespace ComboBoxSection {
+    var displayName: string;
+}

package/dist/components/combobox/components/combobox.tag-group.d.ts

@@ -0,0 +1,26 @@
+import { ComboBoxTagGroupProps } from '../combobox.types';
+/**
+ * # ComboBox.TagGroup (Internal Component)
+ *
+ * Internal component that displays selected items as tags in multi-select mode.
+ * Automatically rendered by ComboBox.Trigger - not exposed to consumers.
+ *
+ * Consumes React-Aria's TagGroupContext, which is populated by the
+ * TagGroupContextProvider in ComboBox.Root with:
+ * - items: selected items array from collection
+ * - onRemove: handler to remove tags
+ * - size: tag size matching ComboBox size
+ * - aria-label: accessible label for the tag group
+ * - id: generated in ComboBox.Root
+ * - selectionMode: "none" (tags are not selectable)
+ * - disabledKeys: disabled tag keys
+ *
+ * Renders null in single-select mode to avoid unnecessary DOM elements.
+ *
+ * @internal
+ * @supportsStyleProps
+ */
+export declare const ComboBoxTagGroup: {
+    (props: ComboBoxTagGroupProps): import("react/jsx-runtime").JSX.Element | null;
+    displayName: string;
+};

package/dist/components/combobox/components/combobox.trigger.d.ts

@@ -0,0 +1,26 @@
+import { ComboBoxTriggerProps } from '../combobox.types';
+/**
+ * # ComboBox.Trigger
+ *
+ * The trigger element that contains the input field and controls for the combobox.
+ * Automatically renders the tag group (for multi-select), input field, toggle button, and clear button.
+ * Handles click interactions to focus the input when clicking anywhere on the trigger area.
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root>
+ *   <ComboBox.Trigger />
+ *   <ComboBox.Popover>
+ *     <ComboBox.ListBox>
+ *       <ComboBox.Item value="option1">Option 1</ComboBox.Item>
+ *     </ComboBox.ListBox>
+ *   </ComboBox.Popover>
+ * </ComboBox.Root>
+ * ```
+ *
+ * @supportsStyleProps
+ */
+export declare const ComboBoxTrigger: {
+    ({ children, ...restProps }: ComboBoxTriggerProps): import("react/jsx-runtime").JSX.Element;
+    displayName: string;
+};

package/dist/components/combobox/components/index.d.ts

@@ -1,11 +1,6 @@
 export { ComboBoxRoot } from './combobox.root';
-export { ComboBoxOptionGroup } from './combobox.option-group';
+export { ComboBoxTrigger } from './combobox.trigger';
+export { ComboBoxPopover } from './combobox.popover';
+export { ComboBoxListBox } from './combobox.listbox';
 export { ComboBoxOption } from './combobox.option';
-export { ComboBoxLeadingElement } from './combobox.leading-element';
-export { ComboBoxOptions } from './combobox.options';
-export { SingleSelectRoot } from './combobox.single-select-root';
-export { SingleSelectInput } from './combobox.single-select-input';
-export { ComboBoxSingleSelectButtonGroup } from './combobox.single-select-button-group';
-export { MultiSelectRoot } from './combobox.multi-select-root';
-export { ComboBoxButtonGroup } from './combobox.multi-select-button-group';
-export { MultiSelectTagGroup } from './combobox.multi-select-tag-group';
+export { ComboBoxSection } from './combobox.section';

package/dist/components/combobox/index.d.ts

@@ -1,2 +1,2 @@
-export * from './combobox';
+export { ComboBox } from './combobox';
 export * from './combobox.types';

package/dist/components/combobox/utils/collection.d.ts

@@ -0,0 +1,13 @@
+import { Key } from 'react-stately';
+/**
+ * Default key extractor - uses string/number id or object with id property
+ */
+export declare function defaultGetKey<T extends object>(item: T | string | number): Key;
+/**
+ * Default text value extractor - uses string item or object with name property
+ */
+export declare function defaultGetTextValue<T extends object>(item: T | string): string;
+/**
+ * Default getNewOptionData - creates an object with id and name
+ */
+export declare function defaultGetNewOptionData<T extends object>(inputValue: string): T;

package/dist/components/combobox/utils/filters.d.ts

@@ -0,0 +1,339 @@
+import { Node } from 'react-stately';
+/**
+ * Default text-based filter for combobox items
+ * Filters individual items by their text content
+ * Does NOT handle sections - use createSectionAwareFilter for that
+ *
+ * @param nodes - Collection nodes to filter
+ * @param inputValue - Current filter text from input
+ * @returns Filtered collection nodes containing only items that match the input
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root
+ *   items={items}
+ *   filter={filterByText}
+ *   placeholder="Search..."
+ * />
+ * ```
+ *
+ * **Behavior:**
+ * - Case-insensitive substring matching
+ * - Returns all nodes when input is empty or whitespace
+ * - Filters based on Node.textValue property
+ * - Does not preserve sections (use section-aware filter for that)
+ *
+ * **Note:** This filter works on individual items only. For filtering with
+ * sections preserved, use `createSectionAwareFilter` to wrap your custom
+ * filter logic.
+ */
+export declare function filterByText<T extends object>(nodes: Iterable<Node<T>>, inputValue: string): Iterable<Node<T>>;
+/**
+ * Starts-with filter for combobox items
+ * Matches items where textValue begins with the input
+ *
+ * @param nodes - Collection nodes to filter
+ * @param inputValue - Current filter text from input
+ * @returns Filtered collection nodes containing only items that start with the input
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root
+ *   items={items}
+ *   filter={filterByStartsWith}
+ *   placeholder="Type to filter..."
+ * />
+ * ```
+ *
+ * **Behavior:**
+ * - Case-insensitive prefix matching
+ * - More restrictive than substring matching
+ * - Useful for autocomplete-style filtering
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Country/state selection where users type the beginning
+ * - Name lookups where first letters matter
+ * - Command palettes with prefix shortcuts
+ */
+export declare function filterByStartsWith<T extends object>(nodes: Iterable<Node<T>>, inputValue: string): Iterable<Node<T>>;
+/**
+ * Case-sensitive filter for combobox items
+ * Matches items with exact case matching
+ *
+ * @param nodes - Collection nodes to filter
+ * @param inputValue - Current filter text from input
+ * @returns Filtered collection nodes containing only items that match with exact case
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root
+ *   items={programmingLanguages}
+ *   filter={filterByCaseSensitive}
+ *   placeholder="Case-sensitive search..."
+ * />
+ * ```
+ *
+ * **Behavior:**
+ * - Exact case matching (case-sensitive substring)
+ * - More precise than case-insensitive filtering
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Code/variable name search
+ * - File path filtering
+ * - Technical identifiers that are case-sensitive
+ */
+export declare function filterByCaseSensitive<T extends object>(nodes: Iterable<Node<T>>, inputValue: string): Iterable<Node<T>>;
+/**
+ * Word boundary filter for combobox items
+ * Matches items where input appears at word boundaries
+ *
+ * @param nodes - Collection nodes to filter
+ * @param inputValue - Current filter text from input
+ * @returns Filtered collection nodes where input matches at word boundaries
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root
+ *   items={items}
+ *   filter={filterByWordBoundary}
+ *   placeholder="Search by word..."
+ * />
+ * ```
+ *
+ * **Behavior:**
+ * - Matches whole words or word beginnings
+ * - Case-insensitive
+ * - Input "eagle" matches "Bald Eagle" but not "beagle"
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Product search where partial words don't make sense
+ * - Name search with multiple words
+ * - Tag/category filtering
+ */
+export declare function filterByWordBoundary<T extends object>(nodes: Iterable<Node<T>>, inputValue: string): Iterable<Node<T>>;
+/**
+ * Fuzzy matching filter for combobox items
+ * Matches items where all input characters appear in order (but not necessarily consecutive)
+ *
+ * @param nodes - Collection nodes to filter
+ * @param inputValue - Current filter text from input
+ * @returns Filtered collection nodes that match the fuzzy pattern
+ *
+ * @example
+ * ```tsx
+ * <ComboBox.Root
+ *   items={items}
+ *   filter={filterByFuzzy}
+ *   placeholder="Fuzzy search..."
+ * />
+ * ```
+ *
+ * **Behavior:**
+ * - Case-insensitive fuzzy matching
+ * - Input "ble" matches "Bald Eagle"
+ * - All characters must appear in order, but can have gaps
+ * - More forgiving than substring matching
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Quick command/action selection
+ * - File/folder navigation
+ * - Large lists where users know approximate spelling
+ * - Abbreviated lookups (e.g., "nj" for "New Jersey")
+ */
+export declare function filterByFuzzy<T extends object>(nodes: Iterable<Node<T>>, inputValue: string): Iterable<Node<T>>;
+/**
+ * Creates a filter that searches across multiple object properties
+ * Useful when items have structured data with multiple searchable fields
+ *
+ * @param propertyPaths - Array of property paths to search (e.g., ['name', 'description', 'tags'])
+ * @returns A filter function that searches across specified properties
+ *
+ * @example
+ * ```tsx
+ * type Product = {
+ *   name: string;
+ *   category: string;
+ *   description: string;
+ * };
+ *
+ * const productFilter = createMultiPropertyFilter<Product>(['name', 'category', 'description']);
+ *
+ * <ComboBox.Root
+ *   items={products}
+ *   filter={productFilter}
+ *   placeholder="Search products..."
+ * >
+ *   {(item) => <ComboBox.Option textValue={item.name}>{item.name}</ComboBox.Option>}
+ * </ComboBox.Root>
+ * ```
+ *
+ * **Behavior:**
+ * - Searches all specified properties
+ * - Case-insensitive substring matching
+ * - Matches if ANY property contains the input
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Product catalogs with multiple searchable fields
+ * - User directories (search by name, email, department)
+ * - Document search (title, author, tags, content)
+ * - Complex data structures with nested properties
+ *
+ * **Note:** Uses node.value to access the original item data.
+ * If you need to search nested properties, use dot notation: 'address.city'
+ */
+export declare function createMultiPropertyFilter<T extends object>(propertyPaths: string[]): (nodes: Iterable<Node<T>>, inputValue: string) => Iterable<Node<T>>;
+/**
+ * Creates a filter with custom scoring/ranking logic
+ * Returns items sorted by relevance score (highest first)
+ *
+ * @param scoreFn - Function that returns a relevance score for each item (higher = more relevant)
+ * @returns A filter function that sorts results by score
+ *
+ * @example
+ * ```tsx
+ * // Prefer items that start with input, but also include substring matches
+ * const rankedFilter = createRankedFilter<SimpleOption>((node, inputValue) => {
+ *   const text = node.textValue.toLowerCase();
+ *   const input = inputValue.toLowerCase();
+ *
+ *   if (text.startsWith(input)) return 100; // Highest score for prefix match
+ *   if (text.includes(input)) return 50;    // Lower score for substring match
+ *   return 0;                               // No match
+ * });
+ *
+ * <ComboBox.Root
+ *   items={items}
+ *   filter={rankedFilter}
+ *   placeholder="Search..."
+ * />
+ * ```
+ *
+ * **Behavior:**
+ * - Applies custom scoring logic to each item
+ * - Filters out items with score <= 0
+ * - Sorts remaining items by score (descending)
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Search with relevance ranking
+ * - Prioritizing certain match types (prefix vs substring)
+ * - Boosting items based on metadata (popularity, recency, etc.)
+ * - Implementing search algorithms like TF-IDF
+ *
+ * **Score Guidelines:**
+ * - Return 0 or negative for non-matches (will be filtered out)
+ * - Higher scores = better matches
+ * - Consider using score ranges (e.g., 0-100) for consistent behavior
+ */
+export declare function createRankedFilter<T extends object>(scoreFn: (node: Node<T>, inputValue: string) => number): (nodes: Iterable<Node<T>>, inputValue: string) => Iterable<Node<T>>;
+/**
+ * Creates a filter that matches any of multiple input terms (OR logic)
+ * Splits input by spaces and matches if any term matches
+ *
+ * @param baseFilter - The underlying filter to use for each term (defaults to filterByText)
+ * @returns A filter function that matches any term
+ *
+ * @example
+ * ```tsx
+ * const multiTermFilter = createMultiTermFilter();
+ *
+ * <ComboBox.Root
+ *   items={items}
+ *   filter={multiTermFilter}
+ *   placeholder="Search (space-separated terms)..."
+ * />
+ * // Input "eagle bison" matches both "Bald Eagle" and "Bison"
+ * ```
+ *
+ * **Behavior:**
+ * - Splits input by whitespace
+ * - Matches if ANY term matches (OR logic)
+ * - Each term is filtered using the base filter
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Search with multiple keywords
+ * - Tag-based filtering (e.g., "react typescript")
+ * - Alternative spellings or synonyms
+ * - Flexible search where users enter multiple criteria
+ *
+ * **Note:** To require ALL terms to match (AND logic), consider chaining filters
+ * or implementing a custom filter function.
+ */
+export declare function createMultiTermFilter<T extends object>(baseFilter?: (nodes: Iterable<Node<T>>, inputValue: string) => Iterable<Node<T>>): (nodes: Iterable<Node<T>>, inputValue: string) => Iterable<Node<T>>;
+/**
+ * Creates a section-aware filter that preserves section structure
+ * Wraps a custom filter function to work with sections, hiding empty sections
+ *
+ * @param itemFilter - Filter function to apply to individual items
+ * @returns A filter function that preserves sections and hides empty ones
+ *
+ * @example
+ * ```tsx
+ * // Using with built-in filters
+ * const sectionAwareStartsWith = createSectionAwareFilter(
+ *   (nodes, input) => filterByStartsWith(nodes, input)
+ * );
+ *
+ * <ComboBox.Root
+ *   items={sectionsWithItems}
+ *   filter={sectionAwareStartsWith}
+ * >
+ *   {(section) => (
+ *     <ComboBox.Section title={section.name}>
+ *       {section.items.map((item) => (
+ *         <ComboBox.Option key={item.id} textValue={item.name}>
+ *           {item.name}
+ *         </ComboBox.Option>
+ *       ))}
+ *     </ComboBox.Section>
+ *   )}
+ * </ComboBox.Root>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Using with custom filter logic
+ * const customSectionFilter = createSectionAwareFilter(
+ *   (nodes, input) => {
+ *     const lowerInput = input.toLowerCase();
+ *     const filtered: Node<T>[] = [];
+ *     for (const node of nodes) {
+ *       // Custom filtering logic
+ *       if (node.textValue.toLowerCase().startsWith(lowerInput)) {
+ *         filtered.push(node);
+ *       }
+ *     }
+ *     return filtered;
+ *   }
+ * );
+ * ```
+ *
+ * **Behavior:**
+ * - Applies the item filter to items within each section
+ * - Preserves section nodes in the output
+ * - Automatically hides sections that have no matching items
+ * - Returns all nodes when input is empty
+ *
+ * **Use Cases:**
+ * - Categorized combobox options (Animals → Mammals, Birds, etc.)
+ * - Grouped data where sections provide context
+ * - Multi-level hierarchies that need filtering
+ * - Search where maintaining visual grouping is important
+ *
+ * **Important Notes:**
+ * - The item filter receives ONLY item nodes (not section nodes)
+ * - Section nodes are detected by checking node.type === "section"
+ * - Empty sections are automatically excluded from results
+ * - Section order is preserved from the original collection
+ *
+ * **Performance:**
+ * - Filters items separately for each section
+ * - More efficient than flat filtering for large datasets with many sections
+ */
+export declare function createSectionAwareFilter<T extends object>(itemFilter: (nodes: Iterable<Node<T>>, inputValue: string) => Iterable<Node<T>>): (nodes: Iterable<Node<T>>, inputValue: string) => Iterable<Node<T>>;