@moneyforward/mfui-components 2.48.1

package/dist/esm/src/SelectBox/SelectBoxOption.d.ts

@@ -0,0 +1,46 @@
+import React from 'react';
+import { type BasedAdditionalProps, type SelectBoxOption } from './SelectBox.types';
+type SelectBoxOptionProps<T extends string | number | undefined = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps> = {
+    /**
+     * The option data to render.
+     */
+    option: SelectBoxOption<T, AdditionalProps>;
+    /**
+     * Whether this option is currently selected.
+     */
+    isSelected: boolean;
+    /**
+     * Index of the currently tabbable option.
+     */
+    tabbableOptionIndex: number;
+    /**
+     * Index of this option in the flat options array.
+     */
+    optionIndex: number;
+    /**
+     * CSS classes from the parent component.
+     */
+    classes: {
+        listItem: string;
+    };
+    /**
+     * Custom render function for the option.
+     */
+    renderOption?: (option: SelectBoxOption<T, AdditionalProps>, isSelected: boolean) => React.ReactNode;
+    /**
+     * Handler called when option receives focus.
+     */
+    onFocus: (optionIndex: number) => void;
+    /**
+     * Handler called when option is clicked.
+     */
+    onClick: (option: SelectBoxOption<T, AdditionalProps>) => void;
+    /**
+     * Handler for keyboard events.
+     */
+    onKeyDown: (event: React.KeyboardEvent<HTMLLIElement>) => void;
+};
+export declare const SelectBoxOptionComponent: (<T extends string | number | undefined = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps>(props: SelectBoxOptionProps<T, AdditionalProps>) => React.ReactElement) & {
+    displayName: string;
+};
+export {};

package/dist/esm/src/SelectBox/SelectBoxOption.js

@@ -0,0 +1,32 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { memo, useMemo, useCallback } from 'react';
+import { Current } from '@moneyforward/mfui-icons-react';
+import { FocusIndicator } from '../FocusIndicator';
+import { Typography } from '../Typography';
+import { cx } from '../../styled-system/css';
+import { isOptionDisabled } from './utils/isSelectableOption';
+/**
+ * Individual option component for SelectBox.
+ * Memoized to prevent unnecessary re-renders when other options change.
+ */
+function SelectBoxOptionComponentInner({ option, isSelected, tabbableOptionIndex, optionIndex, classes, renderOption, onFocus, onClick, onKeyDown, }) {
+    const isDisabled = isOptionDisabled(option);
+    const tabIndex = useMemo(() => (isDisabled ? -1 : optionIndex === tabbableOptionIndex ? 0 : -1), [optionIndex, tabbableOptionIndex, isDisabled]);
+    const handleFocus = useCallback(() => {
+        if (!isDisabled) {
+            onFocus(optionIndex);
+        }
+    }, [onFocus, optionIndex, isDisabled]);
+    const handleClick = useCallback(() => {
+        if (!isDisabled) {
+            onClick(option);
+        }
+    }, [onClick, option, isDisabled]);
+    // Type-safe property access to satisfy eslint rules
+    const optionValue = 'value' in option && option.value !== undefined ? String(option.value) : undefined;
+    const optionLabel = option.label;
+    return (_jsx(FocusIndicator, { position: "inside", children: _jsx("li", { role: "option", "data-value": optionValue, className: cx(classes.listItem, 'mfui-SelectBox__listItem'), "aria-selected": isSelected, "aria-disabled": isDisabled, tabIndex: tabIndex, onFocus: handleFocus, onKeyDown: onKeyDown, onClick: handleClick, children: renderOption ? (renderOption(option, isSelected)) : (_jsxs(_Fragment, { children: [_jsx(Current, { "aria-hidden": true }), _jsx(Typography, { variant: "body", children: optionLabel })] })) }) }));
+}
+export const SelectBoxOptionComponent = memo(SelectBoxOptionComponentInner);
+SelectBoxOptionComponent.displayName = 'SelectBoxOptionComponent';

package/dist/esm/src/SelectBox/SelectBoxOptionGroup.d.ts

@@ -0,0 +1,52 @@
+import React from 'react';
+import { type BasedAdditionalProps, type SelectBoxOption } from './SelectBox.types';
+type SelectBoxOptionGroupProps<T extends string | number | undefined = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps> = {
+    /**
+     * The group option with nested options.
+     */
+    groupOption: SelectBoxOption<T, AdditionalProps> & {
+        options: (SelectBoxOption<T, AdditionalProps> | null | undefined)[];
+    };
+    /**
+     * Currently selected option.
+     */
+    selectedOption: SelectBoxOption<T, AdditionalProps> | null;
+    /**
+     * Map from option value to its index in flatOptions for O(1) lookup.
+     */
+    valueToIndexMap: Map<string | number, number>;
+    /**
+     * Index of the currently tabbable option.
+     */
+    tabbableOptionIndex: number;
+    /**
+     * CSS classes from the parent component.
+     */
+    classes: {
+        listItem: string;
+    };
+    /**
+     * Custom render function for options.
+     */
+    renderOption?: (option: SelectBoxOption<T, AdditionalProps>, isSelected: boolean) => React.ReactNode;
+    /**
+     * Handler called when option receives focus.
+     */
+    onOptionFocus: (optionIndex: number) => void;
+    /**
+     * Handler called when option is clicked.
+     */
+    onOptionClick: (option: SelectBoxOption<T, AdditionalProps>) => void;
+    /**
+     * Handler for keyboard events on options.
+     */
+    onOptionKeyDown: (option: SelectBoxOption<T, AdditionalProps>) => (event: React.KeyboardEvent<HTMLLIElement>) => void;
+    /**
+     * Utility to find index in flatOptions by value.
+     */
+    findFlatOptionIndexByValue: (valueToIndexMap: Map<string | number, number>, option: SelectBoxOption<T, AdditionalProps>) => number;
+};
+export declare const SelectBoxOptionGroup: (<T extends string | number | undefined = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps>(props: SelectBoxOptionGroupProps<T, AdditionalProps>) => React.ReactElement) & {
+    displayName: string;
+};
+export {};

package/dist/esm/src/SelectBox/SelectBoxOptionGroup.js

@@ -0,0 +1,27 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import { memo } from 'react';
+import { Typography } from '../Typography';
+import { SelectBoxOptionComponent } from './SelectBoxOption';
+/**
+ * Option group component for SelectBox.
+ * Renders a group label followed by its nested options.
+ * Memoized to prevent unnecessary re-renders.
+ */
+function SelectBoxOptionGroupInner({ groupOption, selectedOption, valueToIndexMap, tabbableOptionIndex, classes, renderOption, onOptionFocus, onOptionClick, onOptionKeyDown, findFlatOptionIndexByValue, }) {
+    // Type-safe property access to satisfy eslint rules
+    const groupLabel = groupOption.label;
+    const nestedOptions = groupOption.options;
+    return (_jsxs(_Fragment, { children: [_jsx("li", { className: classes.listItem, "data-mfui-group-label": "true", "aria-hidden": "true", children: _jsx(Typography, { variant: "label", children: groupLabel }) }), nestedOptions.map((nestedOption, index) => {
+                if (!nestedOption)
+                    return null;
+                const flatOptionIndex = findFlatOptionIndexByValue(valueToIndexMap, nestedOption);
+                const optionValue = 'value' in nestedOption && nestedOption.value !== undefined ? nestedOption.value : undefined;
+                const optionLabel = nestedOption.label;
+                const keyValue = optionValue !== undefined ? String(optionValue) : `${optionLabel}-${String(index)}`;
+                const isSelected = selectedOption && 'value' in selectedOption ? selectedOption.value === optionValue : false;
+                return (_jsx(SelectBoxOptionComponent, { option: nestedOption, isSelected: isSelected, tabbableOptionIndex: tabbableOptionIndex, optionIndex: flatOptionIndex, classes: classes, renderOption: renderOption, onFocus: onOptionFocus, onClick: onOptionClick, onKeyDown: onOptionKeyDown(nestedOption) }, keyValue));
+            })] }));
+}
+export const SelectBoxOptionGroup = memo(SelectBoxOptionGroupInner);
+SelectBoxOptionGroup.displayName = 'SelectBoxOptionGroup';

package/dist/esm/src/SelectBox/hooks/useKeyboardNavigation.d.ts

@@ -0,0 +1,77 @@
+import { type KeyboardEventHandler } from 'react';
+import { type BasedAdditionalProps, type SelectBoxOption } from '../SelectBox.types';
+type UseKeyboardNavigationProps<T extends string | number | undefined = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps> = {
+    /**
+     * Whether the option panel is currently open.
+     */
+    isOptionPanelOpen: boolean;
+    /**
+     * Whether the component is in loading state.
+     */
+    loading: boolean;
+    /**
+     * Whether search functionality is enabled.
+     */
+    enableSearchOptions: boolean;
+    /**
+     * Currently selected option.
+     */
+    localSelectedOption: SelectBoxOption<T, AdditionalProps> | null;
+    /**
+     * Flat array of all selectable options.
+     */
+    flatOptions: SelectBoxOption<T, AdditionalProps>[];
+    /**
+     * Filtered options (after search and other filters).
+     */
+    filteredOptions: (SelectBoxOption<T, AdditionalProps> | null | undefined)[];
+    /**
+     * Auto-scroll configuration for selected options.
+     */
+    enableAutoScrollToSelectedOption?: boolean | ScrollIntoViewOptions;
+    /**
+     * Callback when an option is selected.
+     */
+    onSelectOption: (option: SelectBoxOption<T, AdditionalProps>) => void;
+    /**
+     * Callback to close the option panel.
+     */
+    onCloseOptionPanel: () => void;
+    /**
+     * Reference to the option panel container.
+     */
+    optionPanelRef: React.RefObject<HTMLDivElement | null>;
+    /**
+     * Reference to the search input element.
+     */
+    searchInputRef: React.RefObject<HTMLInputElement | null>;
+    /**
+     * Scroll to a specific option index (for virtualization).
+     */
+    scrollToIndex?: (index: number, options?: {
+        align?: 'start' | 'center' | 'end' | 'auto';
+        behavior?: 'auto' | 'smooth';
+    }) => void;
+    /**
+     * Whether the option list is virtualized.
+     */
+    isVirtualized?: boolean;
+};
+/**
+ * Hook to manage keyboard navigation and interaction for options in SelectBox
+ *
+ * This hook handles:
+ * - Tracking which option should be tabbable
+ * - Arrow key navigation between options
+ * - Enter/Space key selection
+ * - Escape key to close panel
+ * - Focus management and auto-scrolling
+ *
+ * @returns Object with handlers and state for option keyboard navigation
+ */
+export declare function useKeyboardNavigation<T extends string | number | undefined = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps>({ isOptionPanelOpen, loading, enableSearchOptions, localSelectedOption, flatOptions, filteredOptions, enableAutoScrollToSelectedOption, onSelectOption, onCloseOptionPanel, optionPanelRef, searchInputRef, scrollToIndex, isVirtualized, }: UseKeyboardNavigationProps<T, AdditionalProps>): {
+    tabbableOptionIndex: number;
+    handleOptionFocus: (optionIndex: number) => void;
+    createKeyDownHandler: (option: SelectBoxOption<T, AdditionalProps>) => KeyboardEventHandler<HTMLLIElement>;
+};
+export {};

package/dist/esm/src/SelectBox/hooks/useKeyboardNavigation.js

@@ -0,0 +1,218 @@
+'use client';
+/* eslint-disable @typescript-eslint/no-unnecessary-condition */
+import { useState, useCallback, useEffect } from 'react';
+import { findSiblingElements } from '../../utilities/dom/findSiblingElements';
+import { escapeAttributeSelector } from '../utils/getFlatOptions';
+import { isOptionDisabled } from '../utils/isSelectableOption';
+const DEFAULT_SCROLL_OPTIONS = {
+    behavior: 'auto',
+    block: 'center',
+};
+/**
+ * Hook to manage keyboard navigation and interaction for options in SelectBox
+ *
+ * This hook handles:
+ * - Tracking which option should be tabbable
+ * - Arrow key navigation between options
+ * - Enter/Space key selection
+ * - Escape key to close panel
+ * - Focus management and auto-scrolling
+ *
+ * @returns Object with handlers and state for option keyboard navigation
+ */
+export function useKeyboardNavigation({ isOptionPanelOpen, loading, enableSearchOptions, localSelectedOption, flatOptions, filteredOptions, enableAutoScrollToSelectedOption, onSelectOption, onCloseOptionPanel, optionPanelRef, searchInputRef, scrollToIndex, isVirtualized = false, }) {
+    const getDefaultTabbableIndex = useCallback(() => {
+        if (!flatOptions || flatOptions.length === 0)
+            return 0;
+        const selectedIndex = localSelectedOption
+            ? flatOptions.findIndex((option) => option.value === localSelectedOption.value)
+            : -1;
+        return selectedIndex !== -1 ? selectedIndex : 0;
+    }, [flatOptions, localSelectedOption]);
+    const [tabbableOptionIndex, setTabbableOptionIndex] = useState(getDefaultTabbableIndex());
+    useEffect(() => {
+        setTabbableOptionIndex(getDefaultTabbableIndex());
+    }, [getDefaultTabbableIndex]);
+    const resetTabbableIndex = useCallback(() => {
+        setTabbableOptionIndex(getDefaultTabbableIndex());
+    }, [getDefaultTabbableIndex]);
+    const handleOptionFocus = useCallback((optionIndex) => {
+        setTabbableOptionIndex(optionIndex);
+        // Don't do auto-scroll on focus change - let selection handle its own scrolling
+        // This prevents interference between focus events (from clicks) and selection logic
+        // Auto-scroll should only happen when an option is actually selected, not just focused
+    }, []);
+    useEffect(() => {
+        if (!isOptionPanelOpen)
+            return;
+        // When loading, focus on the option panel root div to enable ESC key functionality
+        if (loading) {
+            optionPanelRef.current?.focus({ preventScroll: true });
+            return;
+        }
+        // When search is enabled, focus the search input regardless of the selected option
+        if (enableSearchOptions) {
+            searchInputRef.current?.focus({ preventScroll: true });
+        }
+        // Handle auto-scroll independently of search input focus
+        // This allows both features to work together
+        if (filteredOptions.length > 0 && optionPanelRef.current && flatOptions && flatOptions.length > 0) {
+            const focusIndex = localSelectedOption
+                ? flatOptions.findIndex((option) => option.value === localSelectedOption.value)
+                : 0;
+            // Ensure target index is within bounds
+            const targetIndex = Math.min(focusIndex === -1 ? 0 : focusIndex, flatOptions.length - 1);
+            // For virtualized lists, scroll to the target index first
+            if (isVirtualized && scrollToIndex) {
+                // Double-check index is valid before scrolling
+                if (targetIndex >= 0 && targetIndex < flatOptions.length) {
+                    scrollToIndex(targetIndex, { align: 'center', behavior: 'auto' });
+                    // Wait for virtualizer to render the option, then focus/scroll
+                    requestAnimationFrame(() => {
+                        const targetValue = flatOptions[targetIndex]?.value;
+                        const valueString = targetValue !== undefined ? String(targetValue) : '';
+                        const targetOption = optionPanelRef.current?.querySelector(`[role="option"][data-value="${escapeAttributeSelector(valueString)}"]`);
+                        if (targetOption && targetOption.getAttribute('aria-disabled') !== 'true' && !enableSearchOptions) {
+                            targetOption.focus({ preventScroll: true });
+                            handleOptionFocus(targetIndex);
+                        }
+                    });
+                }
+            }
+            else {
+                // Non-virtualized: use existing DOM-based logic
+                const optionNodes = optionPanelRef.current?.querySelectorAll('[role="option"]');
+                if (optionNodes && optionNodes.length > 0) {
+                    // Ensure we don't exceed the bounds of available options
+                    const finalTargetIndex = Math.min(targetIndex, optionNodes.length - 1);
+                    // Only focus if the option is not disabled
+                    const targetOption = optionNodes[finalTargetIndex];
+                    if (targetOption && targetOption.getAttribute('aria-disabled') !== 'true') {
+                        // Only focus the option element if search is not enabled
+                        // This prevents conflicting focus management
+                        if (!enableSearchOptions) {
+                            targetOption.focus({ preventScroll: true });
+                            handleOptionFocus(finalTargetIndex);
+                        }
+                        // Auto-scroll to the selected option if enabled
+                        // This works independently of focus, allowing it to work with search
+                        if (enableAutoScrollToSelectedOption && typeof targetOption.scrollIntoView === 'function') {
+                            const scrollOptions = enableAutoScrollToSelectedOption === true ? DEFAULT_SCROLL_OPTIONS : enableAutoScrollToSelectedOption;
+                            setTimeout(() => {
+                                targetOption.scrollIntoView(scrollOptions);
+                            }, 0);
+                        }
+                    }
+                    else {
+                        // Find the first non-disabled option
+                        for (const [i, option] of optionNodes.entries()) {
+                            if (option && option.getAttribute('aria-disabled') !== 'true') {
+                                // Only focus the option element if search is not enabled
+                                if (!enableSearchOptions) {
+                                    option.focus({ preventScroll: true });
+                                    handleOptionFocus(i);
+                                }
+                                // Auto-scroll to the selected option if enabled
+                                if (enableAutoScrollToSelectedOption && typeof option.scrollIntoView === 'function') {
+                                    const scrollOptions = enableAutoScrollToSelectedOption === true
+                                        ? DEFAULT_SCROLL_OPTIONS
+                                        : enableAutoScrollToSelectedOption;
+                                    setTimeout(() => {
+                                        option.scrollIntoView(scrollOptions);
+                                    }, 0);
+                                }
+                                break;
+                            }
+                        }
+                    }
+                }
+            }
+        }
+    }, [
+        isOptionPanelOpen,
+        loading,
+        enableSearchOptions,
+        localSelectedOption,
+        flatOptions,
+        filteredOptions.length,
+        handleOptionFocus,
+        searchInputRef,
+        optionPanelRef,
+        enableAutoScrollToSelectedOption,
+        isVirtualized,
+        scrollToIndex,
+    ]);
+    const createKeyDownHandler = useCallback((option) => (event) => {
+        switch (event.key) {
+            case 'Tab':
+                // Don't prevent default Tab key behavior - let natural Tab flow work
+                resetTabbableIndex();
+                break;
+            case 'ArrowDown':
+            case 'ArrowUp':
+                event.preventDefault();
+                if (isVirtualized && scrollToIndex) {
+                    // Safety check: ensure flatOptions exists
+                    if (!flatOptions || flatOptions.length === 0)
+                        break;
+                    // For virtualized lists: calculate next/prev index from flatOptions array
+                    const currentFlatIndex = flatOptions.findIndex((opt) => opt.value === option.value);
+                    // Get all enabled option indices
+                    const enabledIndices = flatOptions
+                        .map((opt, index) => (!isOptionDisabled(opt) ? index : -1))
+                        .filter((index) => index !== -1);
+                    if (enabledIndices.length === 0)
+                        break;
+                    const currentPos = enabledIndices.indexOf(currentFlatIndex);
+                    const isArrowDown = event.key === 'ArrowDown';
+                    // Calculate next/previous enabled index with wrapping
+                    const nextPos = isArrowDown
+                        ? (currentPos + 1) % enabledIndices.length
+                        : currentPos === 0
+                            ? enabledIndices.length - 1
+                            : currentPos - 1;
+                    const targetIndex = enabledIndices[nextPos];
+                    if (targetIndex === undefined)
+                        break;
+                    // Scroll to the target index
+                    scrollToIndex(targetIndex, { align: 'center', behavior: 'auto' });
+                    // Wait for virtualizer to render the option, then focus
+                    requestAnimationFrame(() => {
+                        const targetValue = flatOptions[targetIndex]?.value;
+                        const valueString = targetValue !== undefined ? String(targetValue) : '';
+                        const selector = `[role="option"][data-value="${escapeAttributeSelector(valueString)}"]`;
+                        optionPanelRef.current?.querySelector(selector)?.focus();
+                    });
+                }
+                else {
+                    // Non-virtualized: use existing DOM-based navigation
+                    const siblingElements = findSiblingElements(event.currentTarget, '[role="option"]:not([aria-disabled="true"])');
+                    const currentIndex = siblingElements.indexOf(event.currentTarget);
+                    const nextIndex = event.key === 'ArrowDown'
+                        ? currentIndex === siblingElements.length - 1
+                            ? 0
+                            : currentIndex + 1
+                        : currentIndex === 0
+                            ? siblingElements.length - 1
+                            : currentIndex - 1;
+                    siblingElements[nextIndex]?.focus();
+                }
+                break;
+            case 'Escape':
+                event.preventDefault();
+                onCloseOptionPanel();
+                resetTabbableIndex();
+                break;
+            case 'Enter':
+            case ' ':
+                event.preventDefault();
+                onSelectOption(option);
+                break;
+        }
+    }, [onSelectOption, onCloseOptionPanel, resetTabbableIndex, isVirtualized, scrollToIndex, flatOptions, optionPanelRef]);
+    return {
+        tabbableOptionIndex,
+        handleOptionFocus,
+        createKeyDownHandler,
+    };
+}

package/dist/esm/src/SelectBox/hooks/useSearchBox.d.ts

@@ -0,0 +1,28 @@
+import { type BasedAdditionalProps, type SelectBoxOption } from '../SelectBox.types';
+/**
+ * Custom hook to handle search functionality within a SelectBox component.
+ *
+ * @param options - Array of SelectBox options (can include nested group options).
+ *
+ * @param enableSearchOptions - Indicates if the SelectBox component is searchable.
+ *
+ * @param onSearchOptions - Handler executed when the search text changes. When
+ * provided, client-side filtering is disabled as it's assumed that the caller
+ * will handle the filtering.
+ *
+ * @returns Object containing the filtered options, search text, and handler to update search text.
+ */
+export declare const useSearchBox: <T extends string | number | undefined = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps>(options: (SelectBoxOption<T, AdditionalProps> | null | undefined)[], enableSearchOptions: boolean, onSearchOptions?: (text: string) => void) => {
+    /**
+     * Handler for search input change events.
+     */
+    onSearchTextChange: (event: React.ChangeEvent<HTMLInputElement>) => void;
+    /**
+     * Filtered options based on search text (client-side filtering only when onSearchOptions is not provided).
+     */
+    filteredOptions: (SelectBoxOption<T, AdditionalProps> | null | undefined)[];
+    /**
+     * Current search text value.
+     */
+    searchText: string;
+};

package/dist/esm/src/SelectBox/hooks/useSearchBox.js

@@ -0,0 +1,83 @@
+'use client';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+/**
+ * Custom hook to handle search functionality within a SelectBox component.
+ *
+ * @param options - Array of SelectBox options (can include nested group options).
+ *
+ * @param enableSearchOptions - Indicates if the SelectBox component is searchable.
+ *
+ * @param onSearchOptions - Handler executed when the search text changes. When
+ * provided, client-side filtering is disabled as it's assumed that the caller
+ * will handle the filtering.
+ *
+ * @returns Object containing the filtered options, search text, and handler to update search text.
+ */
+export const useSearchBox = (options, enableSearchOptions, onSearchOptions) => {
+    const [searchText, setSearchText] = useState('');
+    const debounceRef = useRef(null);
+    const previousSearchTextRef = useRef('');
+    const filteredOptions = useMemo(() => {
+        // If not searchable or if onSearchOptions is provided, return all options without filtering
+        if (!enableSearchOptions || onSearchOptions) {
+            return options;
+        }
+        // Only perform client-side filtering if onSearchOptions is not provided
+        const searchTerm = searchText.trim().toLocaleLowerCase();
+        if (!searchTerm) {
+            return options;
+        }
+        return options
+            .map((option) => {
+            if (!option)
+                return null;
+            if ('options' in option && Array.isArray(option.options)) {
+                const filteredNestedOptions = option.options.filter((nestedOption) => nestedOption.label.toLocaleLowerCase().includes(searchTerm));
+                if (filteredNestedOptions.length === 0)
+                    return null;
+                if (filteredNestedOptions.length === option.options.length)
+                    return option;
+                return { ...option, options: filteredNestedOptions };
+            }
+            return option.label.toLocaleLowerCase().includes(searchTerm) ? option : null;
+        })
+            .filter(Boolean);
+    }, [enableSearchOptions, options, searchText, onSearchOptions]);
+    const handleSearchTextChange = useCallback((event) => {
+        setSearchText(event.target.value);
+    }, []);
+    useEffect(() => {
+        if (!enableSearchOptions || !onSearchOptions)
+            return;
+        // Skip if searchText hasn't changed (prevents initial mount and unnecessary calls)
+        if (searchText === previousSearchTextRef.current) {
+            return;
+        }
+        previousSearchTextRef.current = searchText;
+        if (debounceRef.current) {
+            clearTimeout(debounceRef.current);
+        }
+        debounceRef.current = setTimeout(() => {
+            onSearchOptions(searchText);
+        }, 300);
+        return () => {
+            if (debounceRef.current) {
+                clearTimeout(debounceRef.current);
+            }
+        };
+    }, [searchText, onSearchOptions, enableSearchOptions]);
+    return {
+        /**
+         * Handler for search input change events.
+         */
+        onSearchTextChange: handleSearchTextChange,
+        /**
+         * Filtered options based on search text (client-side filtering only when onSearchOptions is not provided).
+         */
+        filteredOptions,
+        /**
+         * Current search text value.
+         */
+        searchText,
+    };
+};

package/dist/esm/src/SelectBox/hooks/useTypeAhead.d.ts

@@ -0,0 +1,21 @@
+import { type BasedAdditionalProps, type SelectBoxOption } from '../SelectBox.types';
+type UseTypeAheadProps<T extends string | number | undefined = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps> = {
+    options: SelectBoxOption<T, AdditionalProps>[];
+    onSelectOption: (selectedOption: SelectBoxOption<T, AdditionalProps>, selectedIndex: number) => void;
+    /**
+     * Scroll to a specific option index (for virtualization).
+     */
+    scrollToIndex?: (index: number, options?: {
+        align?: 'start' | 'center' | 'end' | 'auto';
+        behavior?: 'auto' | 'smooth';
+    }) => void;
+    /**
+     * Whether the option list is virtualized.
+     */
+    isVirtualized?: boolean;
+};
+export declare const useTypeAhead: <T extends string | number | undefined = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps>({ options, onSelectOption, scrollToIndex, isVirtualized, }: UseTypeAheadProps<T, AdditionalProps>) => {
+    handleTypeAhead: (event: KeyboardEvent) => void;
+    cleanup: () => void;
+};
+export {};

package/dist/esm/src/SelectBox/hooks/useTypeAhead.js

@@ -0,0 +1,52 @@
+import { useCallback, useRef, useState } from 'react';
+import { isOptionDisabled } from '../utils/isSelectableOption';
+// Timeout duration for clearing the typed text
+// It's approximately the same as the timeout of default type-ahead behavior of <select> elements in browsers
+const TIMEOUT_DURATION = 500; // milliseconds
+export const useTypeAhead = ({ options, onSelectOption, scrollToIndex, isVirtualized = false, }) => {
+    const [typeAheadText, setTypeAheadText] = useState('');
+    const timeoutRef = useRef(null);
+    const handleTypeAhead = useCallback((event) => {
+        // Only handle printable characters
+        if (event.key.length !== 1)
+            return;
+        // Clear previous timeout
+        if (timeoutRef.current) {
+            clearTimeout(timeoutRef.current);
+        }
+        // Update type-ahead text
+        const newText = typeAheadText + event.key.toLowerCase();
+        setTypeAheadText(newText);
+        // Safety check: ensure options has items
+        if (options.length === 0)
+            return;
+        // Filter out disabled options
+        const enabledOptions = options.filter((option) => !isOptionDisabled(option));
+        // Find the first option that starts with the typed text
+        const matchingIndex = enabledOptions.findIndex((option) => option.label.toLowerCase().startsWith(newText));
+        const matchingOption = enabledOptions[matchingIndex];
+        if (matchingOption) {
+            // Find the original index in the full options array
+            const originalIndex = options.indexOf(matchingOption);
+            // For virtualized lists, scroll to the matched option first
+            if (isVirtualized && scrollToIndex) {
+                scrollToIndex(originalIndex, { align: 'center', behavior: 'auto' });
+            }
+            onSelectOption(matchingOption, originalIndex);
+        }
+        // Clear the type-ahead text after 500ms
+        timeoutRef.current = setTimeout(() => {
+            setTypeAheadText('');
+        }, TIMEOUT_DURATION);
+    }, [options, onSelectOption, typeAheadText, isVirtualized, scrollToIndex]);
+    // Clear timeout on unmount
+    const cleanup = useCallback(() => {
+        if (timeoutRef.current) {
+            clearTimeout(timeoutRef.current);
+        }
+    }, []);
+    return {
+        handleTypeAhead,
+        cleanup,
+    };
+};