@moneyforward/mfui-components 2.48.1

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

@@ -0,0 +1,307 @@
+'use client';
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import React, { forwardRef, useCallback, useEffect, useId, useMemo, useRef, useState } from 'react';
+import { Dropdown as DropdownIcon } from '@moneyforward/mfui-icons-react';
+import { ClearButton } from '../shared/ClearButton';
+import { FocusIndicator } from '../FocusIndicator';
+import { selectBoxSlotRecipe } from '../../styled-system/recipes';
+import { Typography } from '../Typography';
+import { SearchBox } from '../SearchBox';
+import { useSearchBox } from './hooks/useSearchBox';
+import { Skeleton } from '../Skeleton';
+import { useFocusTrap } from '../utilities/dom/useFocusTrap';
+import { Popover } from '../Popover';
+import { useDisclosure } from '../utilities/state/useDisclosure';
+import { cx } from '../../styled-system/css';
+import { useUpdateEffect } from '../utilities/effect/useUpdateEffect';
+import { useTypeAhead } from './hooks/useTypeAhead';
+import { getFlatOptions, escapeAttributeSelector } from './utils/getFlatOptions';
+import { buildValueToIndexMap, findFlatOptionIndexByValue } from './utils/findFlatOptionIndexByValue';
+import { findOptionByValue } from './utils/findOptionByValue';
+import { useKeyboardNavigation } from './hooks/useKeyboardNavigation';
+import { SelectBoxOptionComponent } from './SelectBoxOption';
+import { SelectBoxOptionGroup } from './SelectBoxOptionGroup';
+import { isOptionDisabled } from './utils/isSelectableOption';
+import { useVirtualizedOptions } from './hooks/useVirtualizedOptions';
+const DEFAULT_SCROLL_OPTIONS = {
+    behavior: 'auto',
+    block: 'center',
+};
+// How many skeleton items to render while the component is loading.
+const SKELETON_ITEM_COUNT = 4;
+/**
+ * The general-purpose SelectBox component.
+ * This component switches the variants of looks and behaviors depends on the props: size, invalid, disabled.
+ */
+export const SelectBox = forwardRef((props, ref) => {
+    const { id, triggerProps, clearButtonProps, enableClearButton = false, size, options = [], defaultValue, placeholder, emptyMessage, disabled, invalid, targetDOMNode, name, onChange, onBlur, value, enableSearchOptions = false, notFoundMessage, searchBoxProps, loading = false, onSearchOptions, renderDisplayValue, renderOption, renderPopoverContent, enableAutoScrollToSelectedOption, popoverContentProps, popoverWrapperProps, onOpenStateChanged, showGroupOptionDivider, triggerWrapperProps, enableAutoUnmount = true, enableConstrainedPopoverWidth = false, enableVirtualization = false, virtualizationOptions, } = props;
+    const classes = selectBoxSlotRecipe({ size, showGroupOptionDivider });
+    const triggerRef = useRef(null);
+    const listBoxId = useId();
+    const optionPanelRef = useRef(null);
+    const scrollWrapperRef = useRef(null);
+    const searchInputRef = useRef(null);
+    const [localSelectedOption, setLocalSelectedOption] = useState(() => {
+        if (defaultValue === undefined)
+            return null;
+        if (typeof defaultValue === 'string' || typeof defaultValue === 'number') {
+            return findOptionByValue(options, defaultValue);
+        }
+        return defaultValue;
+    });
+    const { isOpen: isOptionPanelOpen, toggle: toggleOptionPanel, close: closeOptionPanel, } = useDisclosure({
+        value: false,
+        onToggle: onOpenStateChanged,
+        onClose: () => {
+            triggerRef.current?.focus();
+        },
+    });
+    const { searchText, onSearchTextChange, filteredOptions } = useSearchBox(options, enableSearchOptions, onSearchOptions);
+    const selectedOption = useMemo(() => {
+        if (value === undefined)
+            return null;
+        if (typeof value === 'string' || typeof value === 'number') {
+            return findOptionByValue(options, value);
+        }
+        return value;
+    }, [options, value]);
+    useEffect(() => {
+        // Only update when value prop is explicitly provided (controlled mode)
+        if (value !== undefined) {
+            setLocalSelectedOption(selectedOption);
+        }
+    }, [selectedOption, value]);
+    useUpdateEffect(() => {
+        if (value === undefined) {
+            setLocalSelectedOption(null);
+        }
+    }, [value]);
+    const flatOptions = useMemo(() => getFlatOptions(filteredOptions), [filteredOptions]);
+    // Build value-to-index map for O(1) lookups
+    const valueToIndexMap = useMemo(() => buildValueToIndexMap(flatOptions), [flatOptions]);
+    // Determine if virtualization should be enabled
+    const shouldVirtualize = enableVirtualization && !loading && flatOptions.length > 0;
+    // Create a flat structure for virtualization that includes both group headers and options
+    const createVirtualizedItems = useCallback(() => {
+        if (!shouldVirtualize)
+            return [];
+        const items = [];
+        filteredOptions.forEach((option) => {
+            if (!option)
+                return;
+            if ('options' in option && Array.isArray(option.options)) {
+                // Add group header
+                items.push({
+                    type: 'group',
+                    option,
+                });
+                // Add group options
+                option.options.forEach((nestedOption) => {
+                    const flatOptionIndex = findFlatOptionIndexByValue(valueToIndexMap, nestedOption);
+                    items.push({
+                        type: 'option',
+                        option: nestedOption,
+                        originalIndex: flatOptionIndex,
+                    });
+                });
+            }
+            else {
+                // Regular option
+                const flatOptionIndex = findFlatOptionIndexByValue(valueToIndexMap, option);
+                items.push({
+                    type: 'option',
+                    option,
+                    originalIndex: flatOptionIndex,
+                });
+            }
+        });
+        return items;
+    }, [filteredOptions, shouldVirtualize, valueToIndexMap]);
+    const virtualizedItems = useMemo(() => createVirtualizedItems(), [createVirtualizedItems]);
+    // Initialize virtualization
+    const { virtualizer, virtualItems, totalSize, scrollToIndex, isVirtualized } = useVirtualizedOptions({
+        enabled: shouldVirtualize,
+        parentRef: scrollWrapperRef,
+        flatOptions,
+        estimateSize: virtualizationOptions?.estimateSize,
+        overscan: virtualizationOptions?.overscan,
+    });
+    const handleSelectOption = useCallback((option) => {
+        if (isOptionDisabled(option))
+            return;
+        setLocalSelectedOption(option);
+        onChange?.(option.value, option);
+        closeOptionPanel();
+    }, [onChange, closeOptionPanel]);
+    const { handleTypeAhead, cleanup } = useTypeAhead({
+        options: flatOptions,
+        scrollToIndex,
+        isVirtualized,
+        onSelectOption: (selectedOption) => {
+            if (selectedOption.value !== undefined) {
+                const selector = `[role="option"][data-value="${escapeAttributeSelector(selectedOption.value)}"]`;
+                const targetOption = scrollWrapperRef.current?.querySelector(selector);
+                if (isOptionPanelOpen && flatOptions.length > 0 && targetOption) {
+                    // Focus the target option for keyboard navigation
+                    targetOption.focus({ preventScroll: true });
+                    // Don't handle scrolling here when enableAutoScrollToSelectedOption is active
+                    // The scrolling should be handled by the keyboard navigation or click handlers
+                    // This prevents TypeAhead from interfering with click selection
+                    if (!enableAutoScrollToSelectedOption) {
+                        // Only do TypeAhead scrolling when auto-scroll is disabled
+                        setTimeout(() => {
+                            if (typeof targetOption.scrollIntoView === 'function') {
+                                targetOption.scrollIntoView(DEFAULT_SCROLL_OPTIONS);
+                            }
+                        }, 0);
+                    }
+                    // Don't return early - let the selection logic below handle it
+                    // This was the key issue: early return prevented selection when panel was open
+                }
+            }
+            // Handle selection only when panel is closed (original behavior)
+            // When panel is open, clicks should handle selection, not TypeAhead
+            if (!isOptionPanelOpen) {
+                handleSelectOption(selectedOption);
+            }
+        },
+    });
+    // Cleanup timeout on unmount
+    useEffect(() => cleanup, [cleanup]);
+    const { tabbableOptionIndex, handleOptionFocus, createKeyDownHandler } = useKeyboardNavigation({
+        isOptionPanelOpen,
+        loading,
+        enableSearchOptions,
+        localSelectedOption,
+        flatOptions,
+        filteredOptions,
+        enableAutoScrollToSelectedOption,
+        onSelectOption: handleSelectOption,
+        onCloseOptionPanel: closeOptionPanel,
+        optionPanelRef,
+        searchInputRef,
+        scrollToIndex,
+        isVirtualized,
+    });
+    const { handleOnKeyDown: handleKeyDownMenu } = useFocusTrap({
+        onKeyDown: (event) => {
+            if (event.key === 'Escape') {
+                closeOptionPanel();
+            }
+        },
+    });
+    // Decide what displays on the trigger element.
+    const renderTriggerLabel = () => {
+        if (renderDisplayValue) {
+            return renderDisplayValue(localSelectedOption);
+        }
+        if (placeholder && !localSelectedOption) {
+            return _jsx(Typography, { variant: "controlLabel", children: placeholder });
+        }
+        return (_jsx(Typography, { variant: "controlLabel", children: localSelectedOption ? localSelectedOption.label : placeholder }));
+    };
+    const searchNode = enableSearchOptions ? (_jsx("div", { className: cx(classes.menuHeader, 'mfui-SelectBox__menuHeader'), children: _jsx(SearchBox, { ref: searchInputRef, enableClearButton: true, value: searchText, textBoxSize: "small", autoComplete: "off", onChange: onSearchTextChange, ...searchBoxProps }) })) : null;
+    // Render virtualized items - extracted for better maintainability
+    const renderVirtualizedItems = useCallback(() => virtualItems.map((virtualItem) => {
+        const virtualizedItem = virtualizedItems[virtualItem.index];
+        if (!virtualizedItem)
+            return null;
+        const { type, option, originalIndex } = virtualizedItem;
+        if (type === 'group') {
+            return (_jsx("div", { ref: virtualizer?.measureElement, "data-index": virtualItem.index, style: {
+                    position: 'absolute',
+                    top: 0,
+                    left: 0,
+                    width: '100%',
+                    transform: `translateY(${String(virtualItem.start)}px)`,
+                }, children: _jsx("li", { className: cx(classes.listItem, 'mfui-SelectBox__listItem'), "data-mfui-group-label": "true", "aria-hidden": "true", children: _jsx(Typography, { variant: "label", children: option.label }) }) }, virtualItem.key));
+        }
+        return (_jsx("div", { ref: virtualizer?.measureElement, "data-index": virtualItem.index, style: {
+                position: 'absolute',
+                top: 0,
+                left: 0,
+                width: '100%',
+                transform: `translateY(${String(virtualItem.start)}px)`,
+            }, children: _jsx(SelectBoxOptionComponent, { option: option, isSelected: localSelectedOption?.value === option.value, tabbableOptionIndex: tabbableOptionIndex, optionIndex: originalIndex ?? virtualItem.index, classes: classes, renderOption: renderOption, onFocus: handleOptionFocus, onClick: handleSelectOption, onKeyDown: (event) => {
+                    handleTypeAhead(event.nativeEvent);
+                    createKeyDownHandler(option)(event);
+                } }) }, virtualItem.key));
+    }), [
+        virtualItems,
+        virtualizedItems,
+        localSelectedOption,
+        tabbableOptionIndex,
+        classes,
+        renderOption,
+        handleOptionFocus,
+        handleSelectOption,
+        handleTypeAhead,
+        createKeyDownHandler,
+        virtualizer,
+    ]);
+    // Render non-virtualized items - extracted for better maintainability
+    const renderNonVirtualizedItems = useCallback(() => filteredOptions.map((option, optionIndex) => {
+        if (!option)
+            return null;
+        if ('options' in option && Array.isArray(option.options)) {
+            return (_jsx(React.Fragment, { children: _jsx(SelectBoxOptionGroup, { groupOption: option, selectedOption: localSelectedOption, valueToIndexMap: valueToIndexMap, tabbableOptionIndex: tabbableOptionIndex, classes: classes, renderOption: renderOption, findFlatOptionIndexByValue: (_, option) => findFlatOptionIndexByValue(valueToIndexMap, option), onOptionFocus: handleOptionFocus, onOptionClick: handleSelectOption, onOptionKeyDown: (option) => (event) => {
+                        handleTypeAhead(event.nativeEvent);
+                        createKeyDownHandler(option)(event);
+                    } }) }, `group-label-${option.label}-${String(optionIndex)}`));
+        }
+        if (!('options' in option)) {
+            const flatOptionIndex = findFlatOptionIndexByValue(valueToIndexMap, option);
+            return (_jsx(SelectBoxOptionComponent, { option: option, isSelected: localSelectedOption?.value === option.value, tabbableOptionIndex: tabbableOptionIndex, optionIndex: flatOptionIndex, classes: classes, renderOption: renderOption, onFocus: handleOptionFocus, onClick: handleSelectOption, onKeyDown: (event) => {
+                    handleTypeAhead(event.nativeEvent);
+                    createKeyDownHandler(option)(event);
+                } }, option.value ?? `option-${option.label}-${String(optionIndex)}`));
+        }
+        return null;
+    }), [
+        filteredOptions,
+        localSelectedOption,
+        valueToIndexMap,
+        tabbableOptionIndex,
+        classes,
+        renderOption,
+        handleOptionFocus,
+        handleSelectOption,
+        handleTypeAhead,
+        createKeyDownHandler,
+    ]);
+    // Render empty message - extracted for better maintainability
+    const renderEmptyMessage = useCallback(() => (_jsx("li", { className: cx(classes.emptyMessage, 'mfui-SelectBox__emptyMessage'), children: _jsx(Typography, { variant: "body", children: enableSearchOptions && searchText && notFoundMessage
+                ? notFoundMessage
+                : options.length > 0
+                    ? notFoundMessage
+                    : emptyMessage }) })), [classes.emptyMessage, enableSearchOptions, searchText, notFoundMessage, options.length, emptyMessage]);
+    const optionsNode = (_jsx("div", { ref: scrollWrapperRef, className: cx(classes.scrollWrapper, 'mfui-SelectBox__scrollWrapper'), children: _jsx("ul", { role: "listbox", id: listBoxId, className: cx(classes.listBox, 'mfui-SelectBox__listBox'), tabIndex: -1, style: isVirtualized
+                ? {
+                    height: `${String(totalSize)}px`,
+                    position: 'relative',
+                }
+                : undefined, children: loading
+                ? Array.from({ length: SKELETON_ITEM_COUNT }).map((_, index) => (_jsx("li", { className: cx(classes.skeletonItem, 'mfui-SelectBox__skeletonItem'), children: _jsx(Skeleton, {}) }, index)))
+                : isVirtualized && virtualItems.length > 0
+                    ? // Virtualized rendering with group support
+                        renderVirtualizedItems()
+                    : filteredOptions.length > 0
+                        ? renderNonVirtualizedItems()
+                        : renderEmptyMessage() }) }));
+    const handleClearValue = () => {
+        setLocalSelectedOption(null);
+        onChange?.(undefined, null);
+        closeOptionPanel();
+    };
+    const hasSelectedValue = value !== undefined ? value !== '' : localSelectedOption !== null;
+    const showClearButton = enableClearButton && hasSelectedValue;
+    // Use Popover's centralized blur handling instead of custom logic
+    return (_jsx(Popover, { open: isOptionPanelOpen, targetDOMNode: targetDOMNode, minWidth: popoverContentProps?.minWidth, maxHeight: popoverWrapperProps?.maxHeight, allowedPlacements: popoverContentProps?.allowedPlacements, enableConstrainedContentWidth: enableConstrainedPopoverWidth, renderContent: () => (_jsx("div", { ref: optionPanelRef, id: listBoxId, className: cx(classes.optionPanel, 'mfui-SelectBox__optionPanel', popoverContentProps?.className), tabIndex: -1, onKeyDown: handleKeyDownMenu, children: renderPopoverContent ? (renderPopoverContent({ searchNode, optionsNode })) : (_jsxs(_Fragment, { children: [searchNode, optionsNode] })) })), renderTrigger: ({ setTriggerRef, togglePopover, isPopoverOpen, handleTriggerKeyDown, handleTriggerBlur }) => (_jsxs("div", { ref: setTriggerRef, ...triggerWrapperProps, className: cx(classes.triggerWrapper, 'mfui-SelectBox__triggerWrapper', triggerWrapperProps?.className), children: [_jsx(FocusIndicator, { children: _jsxs("button", { ref: triggerRef, id: id, type: "button", role: "combobox", disabled: disabled, "aria-label": triggerProps?.['aria-label'], "aria-controls": listBoxId, "aria-expanded": isPopoverOpen, "aria-haspopup": "listbox", "aria-invalid": invalid, className: cx(classes.trigger, 'mfui-SelectBox__trigger', triggerProps?.className), "data-placeholder": !!placeholder && !localSelectedOption, "data-selected": !!localSelectedOption, "data-mfui-has-clear-button": showClearButton, onClick: togglePopover, onKeyDown: (event) => {
+                            handleTypeAhead(event.nativeEvent);
+                            handleTriggerKeyDown(event);
+                        }, onBlur: handleTriggerBlur, children: [_jsx("span", { "data-mfui-content": "select-box-trigger-display-value", children: renderTriggerLabel() }), _jsx(DropdownIcon, {}), _jsx("input", { ref: ref, type: "hidden", value: localSelectedOption?.value ?? '', name: name, disabled: disabled })] }) }), showClearButton ? (_jsx("div", { className: cx(classes.clearButtonWrapper, 'mfui-SelectBox__clearButtonWrapper'), children: _jsx(ClearButton, { size: size === 'small' ? 'small' : 'default', "aria-label": clearButtonProps?.['aria-label'] ?? '値をクリアする', "data-mfui-content": "select-box-clear-button", onClick: (event) => {
+                            event.stopPropagation();
+                            handleClearValue();
+                        } }) })) : null] })), contentProps: { className: classes.popover }, enableAutoUnmount: enableAutoUnmount, onOpenStateChanged: toggleOptionPanel, onBlur: onBlur }));
+});
+SelectBox.displayName = 'SelectBox';

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

@@ -0,0 +1,358 @@
+import { type ComponentPropsWithoutRef } from 'react';
+import { type VirtualizerOptions } from '@tanstack/react-virtual';
+import { type SelectBoxSlotRecipeVariant } from '../../styled-system/recipes';
+import { type SearchBoxProps } from '../SearchBox';
+import { type PopoverProps } from '../Popover';
+type AllowedValueTypes = string | number | undefined;
+export type VirtualOptionTypes = Pick<VirtualizerOptions<HTMLElement, Element>, 'estimateSize' | 'overscan'>;
+export type BasedAdditionalProps = Record<string, unknown>;
+export type SelectBoxOption<T extends AllowedValueTypes = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps> = ({
+    /**
+     * The label to be displayed in the list.
+     *
+     * This would be the group label of the nested list when options prop is provided.
+     */
+    label: string;
+    /**
+     * This must be omitted when the options prop is provided.
+     */
+    value?: never;
+    /**
+     * The options to be nested under the group label.
+     */
+    options?: SelectBoxOption<T, AdditionalProps>[];
+} & AdditionalProps) | ({
+    /**
+     * The label to be displayed in the list.
+     */
+    label: string;
+    /**
+     * The value to be returned when the option is selected.
+     *
+     * This must be unique for each option since it's used to identify the option in the list.
+     */
+    value?: T;
+    /**
+     * This must be omitted when the value prop is provided.
+     */
+    options?: never;
+    /**
+     * Whether this option is disabled.
+     */
+    disabled?: boolean;
+} & AdditionalProps);
+/**
+ * A flattened option type representing an individual selectable option (not a group).
+ * Used for keyboard navigation and virtualization.
+ */
+export type FlatOption<T extends AllowedValueTypes = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps> = Extract<SelectBoxOption<T, AdditionalProps>, {
+    value?: T;
+}>;
+export type SelectBoxProps<T extends AllowedValueTypes = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps> = {
+    /**
+     * The id of this component.
+     * This prop is used to relate the component to the corresponding label.
+     *
+     * @example
+     * ```tsx
+     * <label htmlFor="select-box-label">Label</label>
+     * <SelectBox id="select-box-label" />
+     * ```
+     */
+    id?: string;
+    /**
+     * Configuration for automatically scrolling to the selected option when opening the dropdown.
+     * When set to false or undefined, no auto-scrolling occurs.
+     * When set to true, uses default settings (smooth behavior, center alignment).
+     * When an object is provided, allows customizing the scroll behavior.
+     *
+     * Please note that enabling this feature will make force the whole page to be scrolled to the selected option.
+     *
+     * @example
+     * ```tsx
+     * // Default smooth scroll to center
+     * <SelectBox enableAutoScrollToSelectedOption={true} />
+     *
+     * // Custom scroll behavior
+     * <SelectBox enableAutoScrollToSelectedOption={{ behavior: 'auto', block: 'nearest' }} />
+     * ```
+     */
+    enableAutoScrollToSelectedOption?: boolean | ScrollIntoViewOptions;
+    /**
+     * The properties for the popover content panel.
+     *
+     * @property className - The class name of the popover content panel.
+     *
+     * @property minWidth - The minimum width of the popover content panel.
+     *
+     * @property allowedPlacements - Allowed placements for the popover relative to the trigger element.
+     */
+    popoverContentProps?: Pick<ComponentPropsWithoutRef<'div'>, 'className'> & {
+        minWidth?: PopoverProps['minWidth'];
+        allowedPlacements?: PopoverProps['allowedPlacements'];
+    };
+    /**
+     * The properties for the popover wrapper element.
+     *
+     * @property maxHeight - The maximum height of the popover wrapper element.
+     */
+    popoverWrapperProps?: {
+        maxHeight?: PopoverProps['maxHeight'];
+    };
+    /**
+     * The properties for the trigger element.
+     *
+     * @property aria-label - The alternative text for the trigger element.
+     *
+     * @property className - The class name of the trigger element.
+     */
+    triggerProps?: Pick<ComponentPropsWithoutRef<'button'>, 'aria-label' | 'className'>;
+    /**
+     * Whether you let user to clear the content or not.
+     * This will add the Clear button if current SelectBox has value.
+     *
+     * @default false
+     */
+    enableClearButton?: boolean;
+    /**
+     * The properties for the clear button.
+     * If this prop is not passed, the default values for each property will be applied.
+     *
+     * @property aria-label - The alternative text for the clear button. Default is '値をクリアする'.
+     *
+     * @default undefined
+     */
+    clearButtonProps?: Pick<ComponentPropsWithoutRef<'button'>, 'aria-label'>;
+    /**
+     * The size of the SelectBox component.
+     */
+    size?: SelectBoxSlotRecipeVariant['size'];
+    /**
+     * The selectable options for the list
+     *
+     * It should be an array of objects with `label` and `value` properties.
+     *
+     * **Tip**: Use `satisfies` for automatic type inference when using additional properties:
+     * ```tsx
+     * const options = [...] satisfies SelectBoxOption<string, YourType>[];
+     * <SelectBox options={options} /> // Type inference works automatically!
+     * ```
+     */
+    options?: SelectBoxOption<T, AdditionalProps>[];
+    /**
+     * Pass the initial selected option value.
+     * Use this prop when you want an uncontrolled component.
+     *
+     * Can be either:
+     * - A primitive value (string/number) that matches an option's value
+     * - A SelectBoxOption object with both label and value (useful for async scenarios)
+     */
+    defaultValue?: SelectBoxOption<T, AdditionalProps>['value'] | SelectBoxOption<T, AdditionalProps>;
+    /**
+     * Pass the currently selected option value.
+     * Use this prop when you want a controlled component.
+     * Should use this prop with "onChange" prop to control the selected option.
+     *
+     * Can be either:
+     * - A primitive value (string/number) that matches an option's value
+     * - A SelectBoxOption object with both label and value (useful for async scenarios)
+     */
+    value?: SelectBoxOption<T, AdditionalProps>['value'] | SelectBoxOption<T, AdditionalProps>;
+    /**
+     * Text to be displayed when options are not selected.
+     * If you want to show placeholder even if using `renderDisplayValue`, please render placeholder in `renderDisplayValue` function.
+     */
+    placeholder?: string;
+    /**
+     * The message to be displayed in the listbox when the options are empty.
+     */
+    emptyMessage?: string;
+    /**
+     * Whether the trigger is disabled.
+     */
+    disabled?: boolean;
+    /**
+     * Whether the trigger is invalid.
+     */
+    invalid?: boolean;
+    /**
+     * Whether the popover width should be constrained to match the trigger element width.
+     *
+     * When enabled, the popover will have the same width as the trigger element,
+     * preventing it from expanding beyond the trigger boundaries even if option
+     * labels are longer. This is useful for maintaining consistent visual alignment
+     * in forms and handling very long option text.
+     *
+     * @default false
+     */
+    enableConstrainedPopoverWidth?: boolean;
+    /**
+     * The DOM node where the dropdown menu should be rendered.
+     *
+     * If provided, the menu is rendered inside this node. Otherwise, a suitable
+     * DOM node is chosen automatically.
+     */
+    targetDOMNode?: HTMLElement | null;
+    /**
+     * The name of the input element.
+     *
+     * It's used to identify the input element in the form.
+     */
+    name?: string;
+    /**
+     * The callback function that is called when the selected option is changed.
+     *
+     * @param value - The value of the selected option
+     *
+     * @param option - The full option object that was selected (includes additional properties if defined)
+     *
+     * @example
+     * ```tsx
+     * <SelectBox
+     *   onChange={(value, option) => {
+     *     console.log('Selected value:', value);
+     *     console.log('Full option:', option); // Access additional option properties
+     *   }}
+     * />
+     * ```
+     */
+    onChange?: (value: SelectBoxOption<T, AdditionalProps>['value'], option: SelectBoxOption<T, AdditionalProps> | null) => void;
+    /**
+     * The callback function that is called when the SelectBox loses focus.
+     * This will only fire when the user truly leaves the component (not when the popover opens).
+     *
+     * @param event - The blur event from the trigger element
+     *
+     * @example
+     * ```tsx
+     * <SelectBox
+     *   onBlur={(event) => {
+     *     console.log('SelectBox lost focus');
+     *     // Perform validation or other actions
+     *   }}
+     * />
+     * ```
+     */
+    onBlur?: (event: React.FocusEvent<HTMLElement>) => void;
+    /**
+     * The function to customize what displays inside the trigger button.
+     * - Return only elements that are allowed to be contained inside the `<button>` element.
+     * - When the `placeholder` prop is set and no option is selected, the `placeholder` is prioritized over the `renderDisplayValue` prop.
+     */
+    renderDisplayValue?: (selectedOption: SelectBoxOption<T, AdditionalProps> | null) => React.ReactNode;
+    /**
+     * The function to customize how the options are rendered in the list.
+     *
+     * @param option - The option object being rendered (includes additional properties if defined)
+     *
+     * @param isSelected - Whether the option is currently selected
+     *
+     * @example
+     * ```tsx
+     * // Access additional properties in renderOption
+     * const options = [
+     *   { label: 'A', value: '1', customProp: 'foo' }
+     * ] satisfies SelectBoxOption<string, { customProp: string }>[];
+     *
+     * <SelectBox
+     *   options={options}
+     *   renderOption={(option, isSelected) => (
+     *     <div>{option.label} - {option.customProp}</div>
+     *   )}
+     * />
+     * ```
+     */
+    renderOption?: (option: SelectBoxOption<T, AdditionalProps>, isSelected: boolean) => React.ReactNode;
+    /**
+     * The function to customize how the popover is rendered.
+     * - `searchNode` is the search input element. It's available only when `enableSearchOptions` is `true`.
+     * - `optionsNode` is the list of options.
+     */
+    renderPopoverContent?: (nodes: {
+        optionsNode: React.ReactNode;
+        searchNode: React.ReactNode | null;
+    }) => React.ReactNode;
+    /**
+     * The flag to enable search functionality
+     */
+    enableSearchOptions?: boolean;
+    /**
+     * The message to be displayed when the options are not found.
+     */
+    notFoundMessage?: string;
+    /**
+     * The properties for the SearchBox component.
+     */
+    searchBoxProps?: Pick<SearchBoxProps, 'clearButtonProps' | 'placeholder'>;
+    /**
+     * Flag to indicate loading state of the options.
+     * When true, the SelectBox will display skeleton placeholders
+     * in the options list.
+     */
+    loading?: boolean;
+    /**
+     * Handler executed when text is entered in the search box.
+     * The handler is debounced by 300ms.
+     *
+     * When this prop is provided, client-side filtering is disabled as it's
+     * assumed that filtering will be handled by the prop.
+     */
+    onSearchOptions?: (text: string) => void;
+    /**
+     * Callback fired when the open state of the SelectBox changes.
+     *
+     * @param open - The new open state of the SelectBox.
+     */
+    onOpenStateChanged?: (open: boolean) => void;
+    /**
+     * Flag to show a divider between group options in the list.
+     * When true, a divider is shown between group options except the first one.
+     *
+     * @default false
+     */
+    showGroupOptionDivider?: boolean;
+    /**
+     * The properties for the trigger wrapper element.
+     *
+     * @property className - The class name of the trigger wrapper div.
+     */
+    triggerWrapperProps?: Pick<ComponentPropsWithoutRef<'div'>, 'className'>;
+    /**
+     * Enable auto unmounting of the popover content when it's not displayed.
+     * When true, the popover content will return null instead of hiding via CSS.
+     *
+     * @default true
+     */
+    enableAutoUnmount?: boolean;
+    /**
+     * Enable virtualization for large option lists.
+     * When enabled, only visible options are rendered to improve performance.
+     *
+     * Recommended for lists with 100+ options.
+     *
+     * @default false
+     *
+     * @example
+     * ```tsx
+     * <SelectBox options={largeList} enableVirtualization />
+     * ```
+     */
+    enableVirtualization?: boolean;
+    /**
+     * Configuration for virtualization behavior.
+     * Only applies when `enableVirtualization` is true.
+     *
+     * @example
+     * ```tsx
+     * <SelectBox
+     *   enableVirtualization
+     *   virtualizationOptions={{
+     *     estimateSize: (index) => 48, // Function returning size in pixels
+     *     overscan: 10                 // Number of items outside visible area
+     *   }}
+     * />
+     * ```
+     */
+    virtualizationOptions?: VirtualOptionTypes;
+};
+export {};

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

@@ -0,0 +1 @@
+export {};