@cube-dev/ui-kit 0.81.0 → 0.82.0

package/es/components/fields/ComboBox/ComboBox.js

@@ -1,16 +1,16 @@
 /**
  * @license MIT
  * author: Cube Dev Team
- * @cube-dev/ui-kit v0.81.0
+ * @cube-dev/ui-kit v0.82.0
  * Released under the MIT license.
  */
 
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
-import { cloneElement, forwardRef, useEffect, useMemo, } from 'react';
-import { useButton, useComboBox, useFilter, useHover, useOverlayPosition, } from 'react-aria';
-import { Section as BaseSection, useComboBoxState } from 'react-stately';
-import { useEvent } from '../../../_internal/index';
-import { CloseIcon, DownIcon, LoadingIcon } from '../../../icons';
+import React, { cloneElement, forwardRef, useCallback, useEffect, useId, useMemo, useRef, useState, } from 'react';
+import { useFilter, useKeyboard, useOverlay, useOverlayPosition, } from 'react-aria';
+import { Section as BaseSection, Item } from 'react-stately';
+import { useEvent } from '../../../_internal';
+import { CloseIcon, DirectionIcon, LoadingIcon } from '../../../icons';
 import { useProviderProps } from '../../../provider';
 import { BASE_STYLES, COLOR_STYLES, extractStyles, OUTER_STYLES, tasty, } from '../../../tasty';
 import { generateRandomId } from '../../../utils/random';
@@ -19,12 +19,12 @@ import { useFocus } from '../../../utils/react/interactions';
 import { useEventBus } from '../../../utils/react/useEventBus';
 import { ItemAction } from '../../actions';
 import { useFieldProps, useFormProps, wrapWithField } from '../../form';
-import { Item } from '../../Item';
-import { OverlayWrapper } from '../../overlays/OverlayWrapper';
+import { DisplayTransition } from '../../helpers';
+import { Portal } from '../../portal';
 import { InvalidIcon } from '../../shared/InvalidIcon';
 import { ValidIcon } from '../../shared/ValidIcon';
-import { DEFAULT_INPUT_STYLES, INPUT_WRAPPER_STYLES } from '../index';
-import { ListBoxPopup } from '../Select';
+import { ListBox } from '../ListBox/ListBox';
+import { DEFAULT_INPUT_STYLES, INPUT_WRAPPER_STYLES, } from '../TextInput/TextInputBase';
 const ComboBoxWrapperElement = tasty({
     styles: INPUT_WRAPPER_STYLES,
 });
@@ -32,91 +32,435 @@ const InputElement = tasty({
     as: 'input',
     styles: DEFAULT_INPUT_STYLES,
 });
-const TriggerElement = tasty({
-    as: 'button',
-    type: 'neutral',
+const ComboBoxOverlayElement = tasty({
+    qa: 'ComboBoxOverlay',
     styles: {
         display: 'grid',
-        placeItems: 'center',
-        placeContent: 'center',
-        placeSelf: 'stretch',
-        radius: '(1r - 1bw) right',
+        gridRows: '1sf',
+        gridColumns: '1sf',
+        width: '$min-width max-content 50vw',
+        height: 'initial max-content (50vh - $size)',
+        overflow: 'auto',
+        background: '#white',
+        radius: '1cr',
+        shadow: '0 .5x 2x #shadow',
         padding: '0',
-        width: '3x',
-        boxSizing: 'border-box',
-        color: {
-            '': '#dark-02',
-            hovered: '#dark-02',
-            pressed: '#purple',
-            disabled: '#dark.30',
+        border: '#border',
+        hide: {
+            '': false,
+            hidden: true,
         },
-        border: 'left',
-        reset: 'button',
-        margin: 0,
-        fill: {
-            '': '#dark.0',
-            hovered: '#dark.04',
-            pressed: '#purple.10',
-            disabled: '#clear',
+        transition: 'translate $transition ease-out, scale $transition ease-out, theme $transition ease-out',
+        translate: {
+            '': '0 0',
+            'open & [data-placement="top"]': '0 0',
+            '!open & [data-placement="top"]': '0 10%',
+            'open & ([data-placement="bottom"] | ![data-placement]': '0 0',
+            '!open & ([data-placement="bottom"] | ![data-placement])': '0 -10%',
         },
-        cursor: 'pointer',
+        scale: {
+            '': '1 1',
+            '!open': '1 .9',
+        },
+        opacity: {
+            '': 1,
+            '!open': 0.001,
+        },
+        '$min-width': 'min 30x',
     },
 });
 const PROP_STYLES = [...BASE_STYLES, ...OUTER_STYLES, ...COLOR_STYLES];
+function useComboBoxState({ selectedKey, defaultSelectedKey, inputValue, defaultInputValue, comboBoxId, }) {
+    // Get event bus for menu synchronization
+    const { emit, on } = useEventBus();
+    // Internal state for uncontrolled mode
+    const [internalSelectedKey, setInternalSelectedKey] = useState(defaultSelectedKey ?? null);
+    const [internalInputValue, setInternalInputValue] = useState(defaultInputValue ?? '');
+    const isControlledKey = selectedKey !== undefined;
+    const isControlledInput = inputValue !== undefined;
+    const effectiveSelectedKey = isControlledKey
+        ? selectedKey
+        : internalSelectedKey;
+    const effectiveInputValue = isControlledInput
+        ? inputValue
+        : internalInputValue;
+    // Popover state
+    const [isPopoverOpen, setIsPopoverOpen] = useState(false);
+    // Listen for other menus opening and close this one if needed
+    useEffect(() => {
+        const unsubscribe = on('popover:open', (data) => {
+            if (data.menuId !== comboBoxId && isPopoverOpen) {
+                setIsPopoverOpen(false);
+            }
+        });
+        return unsubscribe;
+    }, [on, comboBoxId, isPopoverOpen]);
+    // Emit event when this combobox opens
+    useEffect(() => {
+        if (isPopoverOpen) {
+            emit('popover:open', { menuId: comboBoxId });
+        }
+    }, [isPopoverOpen, emit, comboBoxId]);
+    return {
+        effectiveSelectedKey,
+        effectiveInputValue,
+        isPopoverOpen,
+        setIsPopoverOpen,
+        setInternalSelectedKey,
+        setInternalInputValue,
+        isControlledKey,
+        isControlledInput,
+    };
+}
+function useComboBoxFiltering({ children, effectiveInputValue, filter, }) {
+    const [isFilterActive, setIsFilterActive] = useState(false);
+    const { contains } = useFilter({ sensitivity: 'base' });
+    const textFilterFn = useMemo(() => (filter === false ? () => true : filter || contains), [filter, contains]);
+    // Filter children based on input value
+    const filteredChildren = useMemo(() => {
+        const term = effectiveInputValue.trim();
+        if (!isFilterActive || !term || !children) {
+            return children;
+        }
+        const nodeMatches = (node) => {
+            if (!node?.props)
+                return false;
+            const textValue = node.props.textValue ||
+                (typeof node.props.children === 'string' ? node.props.children : '') ||
+                String(node.props.children || '');
+            return textFilterFn(textValue, term);
+        };
+        const filterChildren = (childNodes) => {
+            if (!childNodes)
+                return null;
+            const childArray = Array.isArray(childNodes) ? childNodes : [childNodes];
+            const filteredNodes = [];
+            childArray.forEach((child) => {
+                if (!child || typeof child !== 'object') {
+                    return;
+                }
+                if (child.type === BaseSection ||
+                    child.type?.displayName === 'Section') {
+                    const sectionChildren = Array.isArray(child.props.children)
+                        ? child.props.children
+                        : [child.props.children];
+                    const filteredSectionChildren = sectionChildren.filter((sectionChild) => {
+                        return (sectionChild &&
+                            typeof sectionChild === 'object' &&
+                            nodeMatches(sectionChild));
+                    });
+                    if (filteredSectionChildren.length > 0) {
+                        filteredNodes.push(cloneElement(child, {
+                            key: child.key,
+                            children: filteredSectionChildren,
+                        }));
+                    }
+                }
+                else if (child.type === Item) {
+                    if (nodeMatches(child)) {
+                        filteredNodes.push(child);
+                    }
+                }
+                else if (nodeMatches(child)) {
+                    filteredNodes.push(child);
+                }
+            });
+            return filteredNodes;
+        };
+        return filterChildren(children);
+    }, [isFilterActive, children, effectiveInputValue, textFilterFn]);
+    return {
+        filteredChildren,
+        isFilterActive,
+        setIsFilterActive,
+    };
+}
+function useCompositeFocus({ wrapperRef, popoverRef, onFocus, onBlur, isDisabled, }) {
+    const wasInsideRef = useRef(false);
+    const rafRef = useRef(null);
+    const checkFocus = useCallback(() => {
+        if (isDisabled)
+            return;
+        const activeElement = document.activeElement;
+        const isInside = (wrapperRef.current?.contains(activeElement) ?? false) ||
+            (popoverRef.current?.contains(activeElement) ?? false);
+        if (isInside !== wasInsideRef.current) {
+            wasInsideRef.current = isInside;
+            if (isInside) {
+                onFocus?.();
+            }
+            else {
+                onBlur?.();
+            }
+        }
+    }, [wrapperRef, popoverRef, onFocus, onBlur, isDisabled]);
+    const handleFocusOrBlur = useCallback((e) => {
+        // Cancel any pending check
+        if (rafRef.current !== null) {
+            cancelAnimationFrame(rafRef.current);
+        }
+        // Schedule focus check for next frame
+        rafRef.current = requestAnimationFrame(() => {
+            rafRef.current = null;
+            checkFocus();
+        });
+    }, [checkFocus]);
+    // Cleanup on unmount
+    useEffect(() => {
+        return () => {
+            if (rafRef.current !== null) {
+                cancelAnimationFrame(rafRef.current);
+            }
+        };
+    }, []);
+    return {
+        compositeFocusProps: {
+            onFocus: handleFocusOrBlur,
+            onBlur: handleFocusOrBlur,
+        },
+    };
+}
+function useComboBoxKeyboard({ isPopoverOpen, listStateRef, hasResults, allowsCustomValue, effectiveInputValue, isClearable, onSelectionChange, onClearValue, onOpenPopover, onClosePopover, inputRef, setIsFilterActive, onKeyDown, }) {
+    const { keyboardProps } = useKeyboard({
+        onKeyDown: (e) => {
+            // Call user's handler first
+            onKeyDown?.(e);
+            if (e.key === 'ArrowDown' || e.key === 'ArrowUp') {
+                e.preventDefault();
+                // Open popover if closed
+                if (!isPopoverOpen) {
+                    // If opening with no filtered results, disable filter to show all items
+                    if (!hasResults) {
+                        setIsFilterActive(false);
+                    }
+                    onOpenPopover();
+                    return;
+                }
+                const listState = listStateRef.current;
+                if (!listState)
+                    return;
+                const { selectionManager, collection, disabledKeys } = listState;
+                // Helper to collect visible item keys (supports sections)
+                const collectVisibleKeys = (nodes, out) => {
+                    for (const node of nodes) {
+                        if (node.type === 'item') {
+                            if (!disabledKeys?.has(node.key)) {
+                                out.push(node.key);
+                            }
+                        }
+                        else if (node.childNodes) {
+                            collectVisibleKeys(node.childNodes, out);
+                        }
+                    }
+                };
+                const visibleKeys = [];
+                collectVisibleKeys(collection, visibleKeys);
+                if (visibleKeys.length === 0)
+                    return;
+                const isArrowDown = e.key === 'ArrowDown';
+                const currentKey = selectionManager.focusedKey;
+                let nextKey = null;
+                if (currentKey == null) {
+                    nextKey = isArrowDown
+                        ? visibleKeys[0]
+                        : visibleKeys[visibleKeys.length - 1];
+                }
+                else {
+                    const currentIndex = visibleKeys.indexOf(currentKey);
+                    if (currentIndex !== -1) {
+                        const newIndex = currentIndex + (isArrowDown ? 1 : -1);
+                        if (newIndex >= 0 && newIndex < visibleKeys.length) {
+                            nextKey = visibleKeys[newIndex];
+                        }
+                    }
+                    else {
+                        nextKey = isArrowDown
+                            ? visibleKeys[0]
+                            : visibleKeys[visibleKeys.length - 1];
+                    }
+                }
+                if (nextKey != null) {
+                    if (listState.lastFocusSourceRef) {
+                        listState.lastFocusSourceRef.current = 'keyboard';
+                    }
+                    selectionManager.setFocusedKey(nextKey);
+                }
+            }
+            else if (e.key === 'Enter') {
+                if (!hasResults) {
+                    e.preventDefault();
+                    if (allowsCustomValue) {
+                        const value = effectiveInputValue;
+                        onSelectionChange(value ?? null);
+                    }
+                    else {
+                        onSelectionChange(null);
+                    }
+                    return;
+                }
+                if (isPopoverOpen) {
+                    const listState = listStateRef.current;
+                    if (!listState)
+                        return;
+                    const keyToSelect = listState.selectionManager.focusedKey;
+                    if (keyToSelect != null) {
+                        e.preventDefault();
+                        listState.selectionManager.select(keyToSelect, e);
+                        // Ensure the popover closes even if selection stays the same
+                        onClosePopover();
+                        inputRef.current?.focus();
+                    }
+                }
+            }
+            else if (e.key === 'Escape') {
+                if (isPopoverOpen) {
+                    e.preventDefault();
+                    onClosePopover();
+                    inputRef.current?.focus();
+                }
+                else if (effectiveInputValue && isClearable) {
+                    e.preventDefault();
+                    onClearValue();
+                }
+            }
+            else if (e.key === 'Home' || e.key === 'End') {
+                if (isPopoverOpen) {
+                    e.preventDefault();
+                    const listState = listStateRef.current;
+                    if (!listState)
+                        return;
+                    const { selectionManager, collection, disabledKeys } = listState;
+                    // Helper to collect visible item keys (supports sections)
+                    const collectVisibleKeys = (nodes, out) => {
+                        for (const node of nodes) {
+                            if (node.type === 'item') {
+                                if (!disabledKeys?.has(node.key)) {
+                                    out.push(node.key);
+                                }
+                            }
+                            else if (node.childNodes) {
+                                collectVisibleKeys(node.childNodes, out);
+                            }
+                        }
+                    };
+                    const visibleKeys = [];
+                    collectVisibleKeys(collection, visibleKeys);
+                    if (visibleKeys.length === 0)
+                        return;
+                    const targetKey = e.key === 'Home'
+                        ? visibleKeys[0]
+                        : visibleKeys[visibleKeys.length - 1];
+                    if (listState.lastFocusSourceRef) {
+                        listState.lastFocusSourceRef.current = 'keyboard';
+                    }
+                    selectionManager.setFocusedKey(targetKey);
+                }
+            }
+        },
+    });
+    return { keyboardProps };
+}
+const ComboBoxInput = forwardRef(function ComboBoxInput({ inputRef, id, value, placeholder, isDisabled, isReadOnly, autoFocus, size, mods, inputStyles, keyboardProps, focusProps, onChange, onFocus, isPopoverOpen, hasResults, comboBoxId, listStateRef, isLoading, allowsCustomValue, }, ref) {
+    const combinedRef = useCombinedRefs(ref, inputRef);
+    return (_jsx(InputElement, { ref: combinedRef, qa: "Input", id: id, type: "text", value: value, placeholder: placeholder, isDisabled: isDisabled, readOnly: isReadOnly, autoFocus: autoFocus, "data-autofocus": autoFocus ? '' : undefined, onChange: onChange, onFocus: onFocus, onBlur: focusProps.onBlur, ...keyboardProps, styles: inputStyles, mods: mods, "data-size": size, role: "combobox", "aria-expanded": isPopoverOpen && hasResults, "aria-haspopup": "listbox", "aria-controls": isPopoverOpen && hasResults
+            ? `ComboBoxListBox-${comboBoxId}`
+            : undefined, "aria-activedescendant": isPopoverOpen &&
+            hasResults &&
+            listStateRef.current?.selectionManager.focusedKey != null
+            ? `ListBoxItem-${listStateRef.current?.selectionManager.focusedKey}`
+            : undefined }));
+});
+function ComboBoxOverlay({ isOpen, triggerRef, popoverRef, listBoxRef, direction, shouldFlip, overlayOffset, comboBoxWidth, comboBoxId, overlayStyles, listBoxStyles, optionStyles, sectionStyles, headingStyles, effectiveSelectedKey, isDisabled, disabledKeys, items, children, listStateRef, onSelectionChange, onClose, label, ariaLabel, compositeFocusProps, }) {
+    // Overlay positioning
+    const { overlayProps: overlayPositionProps, placement, updatePosition, } = useOverlayPosition({
+        targetRef: triggerRef,
+        overlayRef: popoverRef,
+        placement: `${direction} start`,
+        shouldFlip,
+        isOpen,
+        offset: overlayOffset,
+    });
+    // Overlay behavior (dismiss on outside click, escape)
+    const { overlayProps: overlayBehaviorProps } = useOverlay({
+        onClose,
+        shouldCloseOnBlur: true,
+        isOpen,
+        isDismissable: true,
+        shouldCloseOnInteractOutside: (el) => {
+            const menuTriggerEl = el.closest('[data-popover-trigger]');
+            if (!menuTriggerEl)
+                return true;
+            if (menuTriggerEl === triggerRef?.current)
+                return true;
+            return false;
+        },
+    }, popoverRef);
+    // Update position when overlay opens
+    useLayoutEffect(() => {
+        if (isOpen) {
+            // Use double RAF to ensure layout is complete before positioning
+            requestAnimationFrame(() => {
+                requestAnimationFrame(() => {
+                    updatePosition?.();
+                });
+            });
+        }
+    }, [isOpen, updatePosition]);
+    // Extract primary placement direction for consistent styling
+    const placementDirection = placement?.split(' ')[0] || direction;
+    const overlayContent = (_jsx(DisplayTransition, { exposeUnmounted: true, isShown: isOpen, children: ({ phase, isShown, ref: transitionRef }) => (_jsx(ComboBoxOverlayElement, { ...mergeProps(overlayPositionProps, overlayBehaviorProps, compositeFocusProps), ref: (value) => {
+                transitionRef(value);
+                popoverRef.current = value;
+            }, "data-placement": placementDirection, "data-phase": phase, mods: {
+                open: isShown,
+                hidden: phase === 'unmounted',
+            }, styles: overlayStyles, style: {
+                '--min-width': comboBoxWidth ? `${comboBoxWidth}px` : undefined,
+                ...overlayPositionProps.style,
+            }, children: _jsx(ListBox, { ref: listBoxRef, focusOnHover: true, disableSelectionToggle: true, id: `ComboBoxListBox-${comboBoxId}`, "aria-label": ariaLabel || (typeof label === 'string' ? label : 'Options'), selectedKey: effectiveSelectedKey, selectionMode: "single", isDisabled: isDisabled, disabledKeys: disabledKeys, shouldUseVirtualFocus: true, items: items, styles: listBoxStyles, optionStyles: optionStyles, sectionStyles: sectionStyles, headingStyles: headingStyles, stateRef: listStateRef, mods: {
+                    popover: true,
+                }, onSelectionChange: onSelectionChange, children: children }) })) }));
+    return _jsx(Portal, { children: overlayContent });
+}
+// ============================================================================
+// Main Component: ComboBox
+// ============================================================================
 export const ComboBox = forwardRef(function ComboBox(props, ref) {
     props = useProviderProps(props);
     props = useFormProps(props);
     props = useFieldProps(props, {
         valuePropsMapper: ({ value, onChange }) => {
             return {
-                selectedKey: !props.allowsCustomValue ? value ?? null : undefined,
-                inputValue: props.allowsCustomValue ? value ?? '' : undefined,
-                onInputChange(val) {
-                    if (!props.allowsCustomValue) {
-                        return;
-                    }
-                    onChange(val);
-                },
+                // Form value maps to selectedKey (the committed value) in both modes
+                selectedKey: value ?? null,
                 onSelectionChange(val) {
-                    if (val == null && props.allowsCustomValue) {
-                        return;
-                    }
+                    // Commit selection changes to the form
                     onChange(val);
                 },
             };
         },
     });
-    let { qa, label, extra, labelStyles, isRequired, necessityIndicator, validationState, icon, prefix, isDisabled, multiLine, autoFocus, wrapperRef, inputRef, triggerRef, popoverRef, listBoxRef, isLoading, loadingIndicator, overlayOffset = 8, inputStyles, optionStyles, triggerStyles, listBoxStyles, overlayStyles, wrapperStyles, suffix, hideTrigger, message, description, size = 'medium', autoComplete = 'off', direction = 'bottom', shouldFlip = true, menuTrigger = 'input', suffixPosition = 'before', loadingState, filter, styles, labelSuffix, selectedKey, defaultSelectedKey, isClearable, ...otherProps } = props;
-    let isAsync = loadingState != null;
-    let { contains } = useFilter({ sensitivity: 'base' });
-    let comboBoxStateProps = {
-        ...props,
-        defaultFilter: filter || contains,
-        filter: undefined,
-        allowsEmptyCollection: isAsync,
-        menuTrigger,
-    };
-    let state = useComboBoxState(comboBoxStateProps);
+    let { qa, label, extra, labelStyles, isRequired, necessityIndicator, validationState, id, icon, prefix, isDisabled, autoFocus, wrapperRef, inputRef, triggerRef, popoverRef, listBoxRef, isLoading, inputStyles, optionStyles, triggerStyles, listBoxStyles, overlayStyles, fieldStyles, suffix, hideTrigger, message, description, size = 'medium', direction = 'bottom', shouldFlip = true, popoverTrigger = 'input', suffixPosition = 'before', filter, styles, labelSuffix, selectedKey, defaultSelectedKey, inputValue, defaultInputValue, onInputChange, isClearable, onClear, placeholder, allowsCustomValue, shouldCommitOnBlur = true, clearOnBlur, items, children: renderChildren, sectionStyles, headingStyles, isReadOnly, overlayOffset = 8, onSelectionChange: externalOnSelectionChange, sortSelectedToTop: sortSelectedToTopProp, onFocus, onBlur, onKeyDown, ...otherProps } = props;
+    // Generate ID for label-input linking if not provided
+    const generatedId = useId();
+    const inputId = id || generatedId;
     // Generate a unique ID for this combobox instance
     const comboBoxId = useMemo(() => generateRandomId(), []);
-    // Get event bus for menu synchronization
-    const { emit, on } = useEventBus();
-    // Listen for other menus opening and close this one if needed
-    useEffect(() => {
-        const unsubscribe = on('popover:open', (data) => {
-            // If another menu is opening and this combobox is open, close this one
-            if (data.menuId !== comboBoxId && state.isOpen) {
-                state.close();
-            }
-        });
-        return unsubscribe;
-    }, [on, comboBoxId, state]);
-    // Emit event when this combobox opens
-    useEffect(() => {
-        if (state.isOpen) {
-            emit('popover:open', { menuId: comboBoxId });
-        }
-    }, [state.isOpen, emit, comboBoxId]);
+    // State management hook
+    const { effectiveSelectedKey, effectiveInputValue, isPopoverOpen, setIsPopoverOpen, setInternalSelectedKey, setInternalInputValue, isControlledKey, isControlledInput, } = useComboBoxState({
+        selectedKey,
+        defaultSelectedKey,
+        inputValue,
+        defaultInputValue,
+        comboBoxId,
+    });
+    // Track if sortSelectedToTop was explicitly provided
+    const sortSelectedToTopExplicit = sortSelectedToTopProp !== undefined;
+    // Default to true if items are provided, false otherwise
+    const sortSelectedToTop = sortSelectedToTopProp ?? (items ? true : false);
+    // Cache for sorted items array when using `items` prop
+    const cachedItemsOrder = useRef(null);
+    const selectionWhenClosed = useRef(null);
     styles = extractStyles(otherProps, PROP_STYLES, styles);
     ref = useCombinedRefs(ref);
     wrapperRef = useCombinedRefs(wrapperRef);
@@ -124,62 +468,320 @@ export const ComboBox = forwardRef(function ComboBox(props, ref) {
     triggerRef = useCombinedRefs(triggerRef);
     popoverRef = useCombinedRefs(popoverRef);
     listBoxRef = useCombinedRefs(listBoxRef);
-    let { overlayProps, placement, updatePosition } = useOverlayPosition({
-        targetRef: triggerRef,
-        overlayRef: popoverRef,
-        scrollRef: listBoxRef,
-        placement: `${direction} end`,
-        shouldFlip: shouldFlip,
-        isOpen: state.isOpen,
-        onClose: state.close,
-        offset: overlayOffset,
+    // Sort items with selected on top if enabled
+    const getSortedItems = useCallback(() => {
+        if (!items)
+            return items;
+        if (!sortSelectedToTop)
+            return items;
+        // Reuse cached order if available
+        if (cachedItemsOrder.current) {
+            return cachedItemsOrder.current;
+        }
+        // Warn if explicitly requested but not supported
+        if (sortSelectedToTopExplicit && !items) {
+            console.warn('ComboBox: sortSelectedToTop only works with the items prop. ' +
+                'Sorting will be skipped when using JSX children.');
+            return items;
+        }
+        const selectedKey = isPopoverOpen
+            ? effectiveSelectedKey
+            : selectionWhenClosed.current;
+        if (!selectedKey)
+            return items;
+        const itemsArray = Array.isArray(items) ? items : Array.from(items);
+        const selectedItem = itemsArray.find((item) => {
+            const key = item?.key ?? item?.id;
+            return key != null && String(key) === String(selectedKey);
+        });
+        if (!selectedItem)
+            return items;
+        const sorted = [
+            selectedItem,
+            ...itemsArray.filter((item) => {
+                const key = item?.key ?? item?.id;
+                return key == null || String(key) !== String(selectedKey);
+            }),
+        ];
+        if (isPopoverOpen) {
+            cachedItemsOrder.current = sorted;
+        }
+        return sorted;
+    }, [
+        items,
+        sortSelectedToTop,
+        sortSelectedToTopExplicit,
+        effectiveSelectedKey,
+        isPopoverOpen,
+    ]);
+    const sortedItems = getSortedItems();
+    // Preserve the original `children` (may be a render function) before we
+    // potentially overwrite it.
+    let children = renderChildren;
+    const renderFn = renderChildren;
+    if (sortedItems && typeof renderFn === 'function') {
+        try {
+            const itemsArray = Array.from(sortedItems);
+            children = itemsArray.map((item, idx) => {
+                const rendered = renderFn(item);
+                if (React.isValidElement(rendered) &&
+                    rendered.key == null) {
+                    return React.cloneElement(rendered, {
+                        key: rendered?.key ?? item?.key ?? idx,
+                    });
+                }
+                return rendered;
+            });
+        }
+        catch {
+            // If conversion fails, proceed with the original children
+        }
+    }
+    // Invalidate cached sorting whenever items change
+    useEffect(() => {
+        cachedItemsOrder.current = null;
+    }, [items]);
+    // Capture selection when popover closes
+    useEffect(() => {
+        if (!isPopoverOpen) {
+            selectionWhenClosed.current =
+                effectiveSelectedKey != null ? String(effectiveSelectedKey) : null;
+            cachedItemsOrder.current = null;
+        }
+    }, [isPopoverOpen, effectiveSelectedKey]);
+    // Filtering hook
+    const { filteredChildren, isFilterActive, setIsFilterActive } = useComboBoxFiltering({
+        children,
+        effectiveInputValue,
+        filter,
     });
-    let { labelProps, inputProps, listBoxProps, buttonProps: triggerProps, } = useComboBox({
-        ...comboBoxStateProps,
-        inputRef,
-        buttonRef: triggerRef,
-        listBoxRef,
-        popoverRef,
-        menuTrigger,
-    }, state);
-    let { isFocused, focusProps } = useFocus({ isDisabled });
-    let { hoverProps, isHovered } = useHover({ isDisabled });
-    // Get props for the button based on the trigger props from useComboBox
-    let { buttonProps, isPressed: isTriggerPressed } = useButton(triggerProps, triggerRef);
-    let { hoverProps: triggerHoverProps, isHovered: isTriggerHovered } = useHover({ isDisabled });
-    let { focusProps: triggerFocusProps, isFocused: isTriggerFocused } = useFocus({ isDisabled }, true);
-    useLayoutEffect(() => {
-        if (state.isOpen) {
-            updatePosition();
+    // Freeze filtered children during close animation to prevent visual jumps
+    const frozenFilteredChildrenRef = useRef(null);
+    useEffect(() => {
+        // Update frozen children only when popover is open
+        if (isPopoverOpen) {
+            frozenFilteredChildrenRef.current = filteredChildren;
+        }
+    }, [isPopoverOpen, filteredChildren]);
+    // Use frozen children during close animation, fresh children when open
+    const displayedFilteredChildren = isPopoverOpen
+        ? filteredChildren
+        : frozenFilteredChildrenRef.current ?? filteredChildren;
+    const { isFocused, focusProps } = useFocus({ isDisabled });
+    // Composite blur handler - fires when focus leaves the entire component
+    const handleCompositeBlur = useEvent(() => {
+        // Always disable filter on blur
+        setIsFilterActive(false);
+        // In allowsCustomValue mode with shouldCommitOnBlur, commit the input value
+        if (allowsCustomValue &&
+            shouldCommitOnBlur &&
+            effectiveInputValue &&
+            effectiveSelectedKey == null) {
+            externalOnSelectionChange?.(effectiveInputValue);
+            if (!isControlledKey) {
+                setInternalSelectedKey(effectiveInputValue);
+            }
+            // Call user's onBlur callback
+            onBlur?.();
+            return;
+        }
+        // In clearOnBlur mode (only for non-custom-value mode), clear selection and input
+        if (clearOnBlur && !allowsCustomValue) {
+            externalOnSelectionChange?.(null);
+            if (!isControlledKey) {
+                setInternalSelectedKey(null);
+            }
+            if (!isControlledInput) {
+                setInternalInputValue('');
+            }
+            onInputChange?.('');
+            // Call user's onBlur callback
+            onBlur?.();
+            return;
+        }
+        // Reset input to show current selection (or empty if none)
+        const nextValue = effectiveSelectedKey != null ? getItemLabel(effectiveSelectedKey) : '';
+        if (!isControlledInput) {
+            setInternalInputValue(nextValue);
         }
-    }, [state.isOpen, state.collection.size]);
+        onInputChange?.(nextValue);
+        // Call user's onBlur callback
+        onBlur?.();
+    });
+    // Composite focus hook - handles focus tracking across wrapper and portaled popover
+    const { compositeFocusProps } = useCompositeFocus({
+        wrapperRef,
+        popoverRef,
+        onFocus,
+        onBlur: handleCompositeBlur,
+        isDisabled,
+    });
     let isInvalid = validationState === 'invalid';
     let validationIcon = isInvalid ? InvalidIcon : ValidIcon;
     let validation = cloneElement(validationIcon);
+    // Ref to access internal ListBox state
+    const listStateRef = useRef(null);
+    const focusInitAttemptsRef = useRef(0);
+    // Helper to get label from collection item
+    const getItemLabel = useCallback((key) => {
+        const item = listStateRef.current?.collection?.getItem(key);
+        return item?.textValue || String(key);
+    }, []);
+    // Selection change handler
+    const handleSelectionChange = useEvent((selection) => {
+        // Extract single key from selection (we only support single selection)
+        const key = Array.isArray(selection) ? selection[0] : selection;
+        // Update selected key
+        if (!isControlledKey) {
+            setInternalSelectedKey(key ?? null);
+        }
+        // Update input value to show selected item label
+        if (key != null) {
+            setIsFilterActive(false);
+            const label = getItemLabel(key);
+            if (!isControlledInput) {
+                setInternalInputValue(label);
+            }
+            onInputChange?.(label);
+        }
+        else {
+            // Clear input when selection is cleared
+            if (!isControlledInput) {
+                setInternalInputValue('');
+            }
+            onInputChange?.('');
+            setIsFilterActive(false);
+        }
+        externalOnSelectionChange?.(key);
+        // Close popover after selection
+        setIsPopoverOpen(false);
+        // Focus input
+        setTimeout(() => {
+            inputRef.current?.focus();
+        }, 0);
+    });
+    // Input change handler
+    const handleInputChange = useEvent((e) => {
+        const value = e.target.value;
+        // Update input value
+        if (!isControlledInput) {
+            setInternalInputValue(value);
+        }
+        onInputChange?.(value);
+        const trimmed = value.trim();
+        setIsFilterActive(trimmed.length > 0);
+        // Only clear selection in allowsCustomValue mode
+        // In normal mode, typing just filters - selection stays until explicitly changed
+        if (allowsCustomValue && effectiveSelectedKey != null) {
+            if (!isControlledKey) {
+                setInternalSelectedKey(null);
+            }
+            externalOnSelectionChange?.(null);
+        }
+        // Open popover based on trigger
+        if (popoverTrigger !== 'manual' && value && !isPopoverOpen) {
+            setIsPopoverOpen(true);
+        }
+    });
+    // Initialize input value from defaultInputValue or defaultSelectedKey (uncontrolled mode only, one-time)
+    const [hasInitialized, setHasInitialized] = useState(false);
+    useEffect(() => {
+        // Only initialize once, in uncontrolled input mode
+        if (hasInitialized || isControlledInput)
+            return;
+        // Priority 1: defaultInputValue takes precedence
+        if (defaultInputValue !== undefined) {
+            setInternalInputValue(defaultInputValue);
+            setHasInitialized(true);
+            return;
+        }
+        // Priority 2: fall back to defaultSelectedKey's label
+        if (defaultSelectedKey) {
+            // Wait for collection to be ready
+            if (!listStateRef.current?.collection)
+                return;
+            const label = getItemLabel(defaultSelectedKey);
+            setInternalInputValue(label);
+            setHasInitialized(true);
+        }
+    }, [
+        hasInitialized,
+        isControlledInput,
+        defaultInputValue,
+        defaultSelectedKey,
+        getItemLabel,
+        children,
+    ]);
+    // Sync input value with controlled selectedKey
+    useEffect(() => {
+        // Only run when selectedKey is controlled but inputValue is uncontrolled
+        if (!isControlledKey || isControlledInput)
+            return;
+        // Wait for collection to be ready
+        if (!listStateRef.current?.collection)
+            return;
+        // Get the expected label for the current selection
+        const expectedLabel = effectiveSelectedKey != null ? getItemLabel(effectiveSelectedKey) : '';
+        // Update the input value to match the selected key's label
+        setInternalInputValue(expectedLabel);
+    }, [isControlledKey, isControlledInput, effectiveSelectedKey, getItemLabel]);
+    // Input focus handler
+    const handleInputFocus = useEvent((e) => {
+        // Call focus props handler if it exists
+        focusProps.onFocus?.(e);
+        if (popoverTrigger === 'focus' && !isPopoverOpen) {
+            setIsPopoverOpen(true);
+        }
+    });
+    // Input blur handler - just handles internal focus props
+    const handleInputBlur = useEvent((e) => {
+        focusProps.onBlur?.(e);
+    });
     // Clear button logic
-    let hasValue = props.allowsCustomValue
-        ? state.inputValue !== ''
-        : state.selectedKey != null;
-    let showClearButton = isClearable && hasValue && !isDisabled && !props.isReadOnly;
+    let hasValue = allowsCustomValue
+        ? effectiveInputValue !== ''
+        : effectiveSelectedKey != null;
+    let showClearButton = isClearable && hasValue && !isDisabled && !isReadOnly;
+    const hasResults = Boolean(displayedFilteredChildren &&
+        (Array.isArray(displayedFilteredChildren)
+            ? displayedFilteredChildren.length > 0
+            : displayedFilteredChildren !== null));
     // Clear function
     let clearValue = useEvent(() => {
-        // Always clear input value in state so UI resets to placeholder
-        state.setInputValue('');
-        // Notify external input value only when custom value mode is enabled
-        if (props.allowsCustomValue) {
-            props.onInputChange?.('');
+        // Clear input
+        if (!isControlledInput) {
+            setInternalInputValue('');
         }
-        props.onSelectionChange?.(null);
-        state.setSelectedKey(null);
-        // Close the popup if it's open
-        if (state.isOpen) {
-            state.close();
+        onInputChange?.('');
+        // Clear selection
+        if (!isControlledKey) {
+            setInternalSelectedKey(null);
         }
-        // Focus back to the input
+        externalOnSelectionChange?.(null);
+        // Close popover
+        if (isPopoverOpen) {
+            setIsPopoverOpen(false);
+        }
+        // Focus input
         inputRef.current?.focus();
-        props.onClear?.();
+        onClear?.();
+    });
+    // Keyboard navigation hook
+    const { keyboardProps } = useComboBoxKeyboard({
+        isPopoverOpen,
+        listStateRef,
+        hasResults,
+        allowsCustomValue,
+        effectiveInputValue,
+        isClearable,
+        onSelectionChange: handleSelectionChange,
+        onClearValue: clearValue,
+        onOpenPopover: () => setIsPopoverOpen(true),
+        onClosePopover: () => setIsPopoverOpen(false),
+        inputRef,
+        setIsFilterActive,
+        onKeyDown,
     });
-    let comboBoxWidth = wrapperRef?.current?.offsetWidth;
     if (icon) {
         icon = _jsx("div", { "data-element": "InputIcon", children: icon });
         if (prefix) {
@@ -193,7 +795,7 @@ export const ComboBox = forwardRef(function ComboBox(props, ref) {
         invalid: isInvalid,
         valid: validationState === 'valid',
         disabled: isDisabled,
-        hovered: isHovered,
+        hovered: false,
         focused: isFocused,
         loading: isLoading,
         prefix: !!prefix,
@@ -203,84 +805,98 @@ export const ComboBox = forwardRef(function ComboBox(props, ref) {
         isInvalid,
         validationState,
         isDisabled,
-        isHovered,
         isFocused,
         isLoading,
         prefix,
         showClearButton,
     ]);
-    // If input is not full and the user presses Enter, pick the first option.
-    let onKeyPress = useEvent((e) => {
-        if (!props.onSelectionChange) {
-            return;
+    const comboBoxWidth = wrapperRef?.current?.offsetWidth;
+    const shouldShowPopover = Boolean(isPopoverOpen && hasResults);
+    // Close popover if no results
+    useEffect(() => {
+        if (isPopoverOpen && !hasResults) {
+            setIsPopoverOpen(false);
         }
-        if (e.key === 'Enter') {
-            if (!props.allowsCustomValue) {
-                if (state.isOpen) {
-                    // If there is a selected option then do nothing. It will be selected on Enter anyway.
-                    if (listBoxRef.current?.querySelector('li[aria-selected="true"]')) {
-                        return;
-                    }
-                    const option = [...state.collection][0]?.key;
-                    if (option && selectedKey !== option) {
-                        props.onSelectionChange?.(option);
-                        e.stopPropagation();
-                        e.preventDefault();
-                    }
+    }, [isPopoverOpen, hasResults]);
+    const ensureInitialFocus = useCallback(() => {
+        if (!shouldShowPopover)
+            return;
+        const listState = listStateRef.current;
+        if (!listState)
+            return;
+        const { selectionManager, collection, disabledKeys, lastFocusSourceRef } = listState;
+        if (!selectionManager || !collection)
+            return;
+        const collectFirstKey = () => {
+            for (const node of collection) {
+                if (node.type === 'item') {
+                    if (!disabledKeys?.has(node.key))
+                        return node.key;
                 }
-                else if (inputRef.current?.value &&
-                    ![...state.collection]
-                        .map((i) => i.textValue)
-                        .includes(inputRef.current?.value)) {
-                    // If the input value is not in the collection, we need to prevent the submitting of the form.
-                    // Also, we reset value manually.
-                    e.preventDefault();
-                    props.onSelectionChange?.(null);
+                else if (node.childNodes) {
+                    for (const child of node.childNodes) {
+                        if (child.type === 'item' && !disabledKeys?.has(child.key)) {
+                            return child.key;
+                        }
+                    }
                 }
-                // If a custom value is allowed, we need to check if the input value is in the collection.
             }
-            else if (props.allowsCustomValue) {
-                const inputValue = inputRef?.current?.value;
-                const item = [...state.collection].find((item) => item.textValue.toLowerCase() === inputValue?.toLowerCase());
-                props.onSelectionChange?.(item ? item.key : inputRef?.current?.value ?? '');
-            }
-        }
-    });
-    let onBlur = useEvent((e) => {
-        // If the input value is not in the collection, we need to reset the value.
-        if (!props.allowsCustomValue &&
-            inputRef.current?.value &&
-            ![...state.collection]
-                .map((i) => i.textValue)
-                .includes(inputRef.current?.value)) {
-            props.onSelectionChange?.(null);
+            return null;
+        };
+        if (lastFocusSourceRef)
+            lastFocusSourceRef.current = 'keyboard';
+        if (selectionManager.focusedKey == null) {
+            const keyToFocus = effectiveSelectedKey != null ? effectiveSelectedKey : collectFirstKey();
+            if (keyToFocus != null)
+                selectionManager.setFocusedKey(keyToFocus);
         }
-    });
-    useEffect(() => {
-        inputRef.current?.addEventListener('keydown', onKeyPress, true);
-        inputRef.current?.addEventListener('blur', onBlur, true);
-        return () => {
-            inputRef.current?.removeEventListener('keydown', onKeyPress, true);
-            inputRef.current?.removeEventListener('blur', onBlur, true);
+    }, [shouldShowPopover, effectiveSelectedKey]);
+    useLayoutEffect(() => {
+        if (!shouldShowPopover)
+            return;
+        focusInitAttemptsRef.current = 0;
+        const tick = () => {
+            if (!shouldShowPopover)
+                return;
+            ensureInitialFocus();
+            focusInitAttemptsRef.current += 1;
+            // Try a few frames to wait for collection to mount
+            if (focusInitAttemptsRef.current < 8 &&
+                listStateRef.current?.selectionManager?.focusedKey == null) {
+                requestAnimationFrame(tick);
+            }
         };
-    }, []);
-    let allInputProps = useMemo(() => mergeProps(inputProps, hoverProps, focusProps), [inputProps, hoverProps, focusProps]);
-    let comboBoxField = (_jsxs(ComboBoxWrapperElement, { ref: wrapperRef, qa: qa || 'ComboBox', mods: mods, styles: wrapperStyles, style: {
+        requestAnimationFrame(() => requestAnimationFrame(tick));
+    }, [shouldShowPopover, ensureInitialFocus]);
+    const comboBoxField = (_jsxs(ComboBoxWrapperElement, { ref: wrapperRef, qa: qa || 'ComboBox', mods: mods, styles: styles, style: {
             zIndex: isFocused ? 1 : 'initial',
-        }, "data-size": size, children: [prefix ? _jsx("div", { "data-element": "Prefix", children: prefix }) : null, _jsx(InputElement, { ref: inputRef, qa: "Input", autoFocus: autoFocus, "data-autofocus": autoFocus ? '' : undefined, ...allInputProps, autoComplete: autoComplete, styles: inputStyles, mods: mods, "data-size": size }), _jsxs("div", { "data-element": "Suffix", children: [suffixPosition === 'before' ? suffix : null, validationState || isLoading ? (_jsxs(_Fragment, { children: [validationState && !isLoading ? validation : null, isLoading ? _jsx(LoadingIcon, {}) : null] })) : null, suffixPosition === 'after' ? suffix : null, showClearButton && (_jsx(ItemAction, { icon: _jsx(CloseIcon, {}), size: size, theme: validationState === 'invalid' ? 'danger' : undefined, qa: "ComboBoxClearButton", "data-no-trigger": hideTrigger ? '' : undefined, onPress: clearValue })), !hideTrigger ? (_jsx(TriggerElement, { "data-popover-trigger": true, qa: "ComboBoxTrigger", ...mergeProps(buttonProps, triggerFocusProps, triggerHoverProps), ref: triggerRef, mods: {
-                            pressed: isTriggerPressed,
-                            focused: isTriggerFocused,
-                            hovered: isTriggerHovered,
+        }, "data-size": size, ...compositeFocusProps, children: [prefix ? _jsx("div", { "data-element": "Prefix", children: prefix }) : null, _jsx(ComboBoxInput, { inputRef: inputRef, id: inputId, value: effectiveInputValue, placeholder: placeholder, isDisabled: isDisabled, isReadOnly: isReadOnly, autoFocus: autoFocus, size: size, mods: mods, inputStyles: inputStyles, keyboardProps: keyboardProps, focusProps: { ...focusProps, onBlur: handleInputBlur }, isPopoverOpen: isPopoverOpen, hasResults: hasResults, comboBoxId: comboBoxId, listStateRef: listStateRef, isLoading: isLoading, allowsCustomValue: allowsCustomValue, onChange: handleInputChange, onFocus: handleInputFocus }), _jsxs("div", { "data-element": "Suffix", children: [suffixPosition === 'before' ? suffix : null, validationState || isLoading ? (_jsxs(_Fragment, { children: [validationState && !isLoading ? validation : null, isLoading ? _jsx(LoadingIcon, {}) : null] })) : null, suffixPosition === 'after' ? suffix : null, showClearButton && (_jsx(ItemAction, { icon: _jsx(CloseIcon, {}), size: size, theme: validationState === 'invalid' ? 'danger' : undefined, qa: "ComboBoxClearButton", "data-no-trigger": hideTrigger ? '' : undefined, "aria-label": "Clear value", onPress: clearValue })), !hideTrigger ? (_jsx(ItemAction, { ref: triggerRef, "data-popover-trigger": true, icon: _jsx(DirectionIcon, { to: isPopoverOpen ? 'up' : 'down' }), qa: "ComboBoxTrigger", mods: {
+                            pressed: isPopoverOpen,
                             disabled: isDisabled,
                             loading: isLoading,
-                        }, "data-size": size, isDisabled: isDisabled, styles: triggerStyles, children: _jsx(DownIcon, {}) })) : null] }), _jsx(OverlayWrapper, { isOpen: state.isOpen && !isDisabled, children: _jsx(ListBoxPopup, { ...listBoxProps, shouldUseVirtualFocus: true, listBoxRef: listBoxRef, popoverRef: popoverRef, overlayProps: overlayProps, placement: placement, state: state, listBoxStyles: listBoxStyles, overlayStyles: overlayStyles, optionStyles: optionStyles, minWidth: comboBoxWidth, triggerRef: triggerRef }) })] }));
-    return wrapWithField(comboBoxField, ref, mergeProps({ ...props, styles }, { labelProps }));
-});
-const ComboBoxSectionComponent = Object.assign(BaseSection, {
-    displayName: 'Section',
+                        }, "data-size": size, isDisabled: isDisabled, styles: triggerStyles, "aria-expanded": isPopoverOpen, "aria-haspopup": "listbox", "aria-label": "Show options", onPress: () => {
+                            if (!isDisabled) {
+                                const willOpen = !isPopoverOpen;
+                                setIsPopoverOpen(willOpen);
+                                if (willOpen) {
+                                    inputRef.current?.focus();
+                                    // If opening with no filtered results, disable filter to show all items
+                                    if (!hasResults) {
+                                        setIsFilterActive(false);
+                                    }
+                                }
+                            }
+                        } })) : null] }), _jsx(ComboBoxOverlay, { isOpen: shouldShowPopover, triggerRef: wrapperRef, popoverRef: popoverRef, listBoxRef: listBoxRef, direction: direction, shouldFlip: shouldFlip, overlayOffset: overlayOffset, comboBoxWidth: comboBoxWidth, comboBoxId: comboBoxId, overlayStyles: overlayStyles, listBoxStyles: listBoxStyles, optionStyles: optionStyles, sectionStyles: sectionStyles, headingStyles: headingStyles, effectiveSelectedKey: effectiveSelectedKey, isDisabled: isDisabled, disabledKeys: props.disabledKeys, items: sortedItems, listStateRef: listStateRef, label: label, ariaLabel: props['aria-label'], compositeFocusProps: compositeFocusProps, onSelectionChange: handleSelectionChange, onClose: () => setIsPopoverOpen(false), children: displayedFilteredChildren })] }));
+    const { children: _, ...propsWithoutChildren } = props;
+    const finalProps = {
+        ...propsWithoutChildren,
+        styles: fieldStyles,
+        labelProps: { ...props.labelProps, for: inputId },
+    };
+    return wrapWithField(comboBoxField, ref, mergeProps(finalProps, {}));
 });
 ComboBox.Item = Item;
-ComboBox.Section = ComboBoxSectionComponent;
+ComboBox.Section = BaseSection;
 Object.defineProperty(ComboBox, 'cubeInputType', {
     value: 'ComboBox',
     enumerable: false,