@moneyforward/mfui-components 2.48.1

package/dist/cjs/src/MultipleSelectBox/MultipleSelectBox.js

@@ -0,0 +1,278 @@
+"use strict";
+'use client';
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.MultipleSelectBox = MultipleSelectBox;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = require("react");
+const mfui_icons_react_1 = require("@moneyforward/mfui-icons-react");
+const FocusIndicator_1 = require("../FocusIndicator");
+const Typography_1 = require("../Typography");
+const useFocusTrap_1 = require("../utilities/dom/useFocusTrap");
+const recipes_1 = require("../../styled-system/recipes");
+const useDisclosure_1 = require("../utilities/state/useDisclosure");
+const MultipleSelectBoxTrigger_1 = require("./MultipleSelectBoxTrigger");
+const useSearchBox_1 = require("./hooks/useSearchBox");
+const SearchBox_1 = require("../SearchBox");
+const Button_1 = require("../Button");
+const Stack_1 = require("../Stack");
+const Skeleton_1 = require("../Skeleton");
+const useInitialFocusOnOptionPanelOpen_1 = require("./hooks/useInitialFocusOnOptionPanelOpen");
+const useSelectedValues_1 = require("./hooks/useSelectedValues");
+const useOptionKeyboardNavigation_1 = require("./hooks/useOptionKeyboardNavigation");
+const useOptionSelectionManagement_1 = require("./hooks/useOptionSelectionManagement");
+const Popover_1 = require("../Popover");
+const useApplyControls_1 = require("./hooks/useApplyControls");
+const css_1 = require("../../styled-system/css");
+const flattenOptions_1 = require("./utils/flattenOptions");
+const isSelectableOption_1 = require("./utils/isSelectableOption");
+const useVirtualizedMultipleSelectBoxOptions_1 = require("./hooks/useVirtualizedMultipleSelectBoxOptions");
+// How many skeleton items to render while the component is loading.
+const SKELETON_ITEM_COUNT = 4;
+/**
+ * The MultipleSelectBox component.
+ * This component is separated from the SelectBox component because it has a different behavior.
+ * This component switches the variants of looks and behaviors depends on the props: size, invalid, disabled.
+ */
+function MultipleSelectBox({ id, triggerProps, triggerWrapperProps, size, options = [], defaultValue, placeholder, emptyMessage, disabled, invalid, targetDOMNode, name, onChange, value, showDisplayValueAsTag, renderDisplayValue, enableSearchOptions = false, notFoundMessage, searchBoxProps, loading = false, onSearchOptions, clearButtonProps, disableClearButton = false, optionPanelProps, enableAllOptionsControls = false, enableApplyControls = false, selectAllButtonProps, clearAllButtonProps, selectedCountProps, cancelButtonProps, applyButtonProps, renderOption, onOpenStateChanged, enableAutoUnmount = true, onBlur, showGroupOptionDivider, enableVirtualization = false, virtualizationOptions, }) {
+    const classes = (0, recipes_1.multipleSelectBoxSlotRecipe)({ showGroupOptionDivider });
+    const triggerRef = (0, react_1.useRef)(null);
+    const listBoxId = (0, react_1.useId)();
+    const optionPanelRef = (0, react_1.useRef)(null);
+    const listBoxRef = (0, react_1.useRef)(null);
+    const searchInputRef = (0, react_1.useRef)(null);
+    const selectAllButtonRef = (0, react_1.useRef)(null);
+    const clearAllButtonRef = (0, react_1.useRef)(null);
+    const cancelButtonRef = (0, react_1.useRef)(null);
+    const applyButtonRef = (0, react_1.useRef)(null);
+    const flattenedOptions = (0, react_1.useMemo)(() => (0, flattenOptions_1.flattenOptions)(options), [options]);
+    const { localSelectedValuesSet, localSelectedOptions, updateSelectedValues } = (0, useSelectedValues_1.useSelectedValues)({
+        options: flattenedOptions,
+        defaultValue,
+        value,
+        onChange,
+    });
+    const { isOpen: isOptionPanelOpen, toggle: toggleOptionPanel, close: closeOptionPanel, } = (0, useDisclosure_1.useDisclosure)({
+        onToggle: (nextValue) => {
+            onOpenStateChanged?.(nextValue);
+            if (nextValue && enableApplyControls) {
+                updateTemporaryValues([...localSelectedValuesSet]);
+            }
+        },
+        onClose: () => {
+            onOpenStateChanged?.(false);
+            if (enableApplyControls) {
+                initializeTemporaryValues();
+            }
+            triggerRef.current?.focus();
+        },
+    });
+    const { searchText, filteredOptions, onSearchTextChange } = (0, useSearchBox_1.useSearchBox)(flattenedOptions, enableSearchOptions, onSearchOptions);
+    // Determine if virtualization should be enabled
+    const shouldVirtualize = enableVirtualization && !loading && flattenedOptions.length > 0;
+    // Initialize virtualization
+    const { virtualizer, virtualItems, totalSize, isVirtualized } = (0, useVirtualizedMultipleSelectBoxOptions_1.useVirtualizedMultipleSelectBoxOptions)({
+        enabled: shouldVirtualize,
+        parentRef: listBoxRef,
+        flatOptions: filteredOptions.filter((option) => 'value' in option),
+        estimateSize: virtualizationOptions?.estimateSize,
+        overscan: virtualizationOptions?.overscan,
+    });
+    const { temporaryValues, updateTemporaryValues, initializeTemporaryValues, handleCancelButtonClick, handleApplyButtonClick, } = (0, useApplyControls_1.useApplyControls)({
+        onValuesChange: updateSelectedValues,
+        closeOptionPanel,
+    });
+    // Control the focus when the option panel is opened.
+    (0, useInitialFocusOnOptionPanelOpen_1.useInitialFocusOnOptionPanelOpen)({
+        isOptionPanelOpen,
+        selectAllButtonRef,
+        clearAllButtonRef,
+        enableSearchOptions,
+        searchInputRef,
+        localSelectedValuesSet,
+        optionPanelRef,
+        filteredOptions,
+        loading,
+    });
+    // Manage the selection of options
+    const { handleSelectOption, handleSelectAllOptions, handleClearAllOptions } = (0, useOptionSelectionManagement_1.useOptionSelectionManagement)({
+        options: flattenedOptions,
+        selectedValues: enableApplyControls ? temporaryValues : localSelectedValuesSet,
+        updateSelectedValues: enableApplyControls ? updateTemporaryValues : updateSelectedValues,
+    });
+    const handleSelectAll = () => {
+        handleSelectAllOptions(filteredOptions);
+    };
+    const handleClearAll = () => {
+        handleClearAllOptions(filteredOptions);
+    };
+    const { handleOnKeyDown: handleKeyDownMenu } = (0, useFocusTrap_1.useFocusTrap)({
+        onKeyDown: (event) => {
+            if (event.key === 'Escape') {
+                closeOptionPanel();
+            }
+        },
+    });
+    // Create an array of focusable (selectable and not disabled) options from filteredOptions
+    const focusableOptions = (0, react_1.useMemo)(() => filteredOptions.filter((option) => (0, isSelectableOption_1.isSelectableOption)(option) && option.value != null && !(0, isSelectableOption_1.isOptionDisabled)(option)), [filteredOptions]);
+    // Manage the keyboard navigation of options
+    const { handleOptionFocus, createKeyDownHandler, tabbableOptionIndex } = (0, useOptionKeyboardNavigation_1.useOptionKeyboardNavigation)({
+        filteredOptions: focusableOptions,
+        selectedValues: enableApplyControls ? temporaryValues : localSelectedValuesSet,
+        onSelectOption: handleSelectOption,
+        onClosePanel: closeOptionPanel,
+    });
+    // Create a flat structure for virtualization that includes both group headers and options
+    const createVirtualizedItems = (0, react_1.useCallback)(() => {
+        if (!shouldVirtualize)
+            return [];
+        const items = [];
+        filteredOptions.forEach((option) => {
+            if ('options' in option && Array.isArray(option.options)) {
+                // Add group header
+                items.push({
+                    type: 'group',
+                    option,
+                });
+                // Add group options
+                option.options.forEach((nestedOption) => {
+                    items.push({
+                        type: 'option',
+                        option: nestedOption,
+                    });
+                });
+            }
+            else {
+                // Regular option
+                items.push({
+                    type: 'option',
+                    option,
+                });
+            }
+        });
+        return items;
+    }, [filteredOptions, shouldVirtualize]);
+    const virtualizedItems = (0, react_1.useMemo)(() => createVirtualizedItems(), [createVirtualizedItems]);
+    // Render virtualized items - extracted for better maintainability
+    const renderVirtualizedItems = (0, react_1.useCallback)(() => {
+        let focusableIndex = 0;
+        return virtualItems.map((virtualItem) => {
+            const virtualizedItem = virtualizedItems[virtualItem.index];
+            if (!virtualizedItem)
+                return null;
+            const { type, option } = virtualizedItem;
+            if (type === 'group') {
+                return ((0, jsx_runtime_1.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: (0, jsx_runtime_1.jsx)("li", { className: (0, css_1.cx)(classes.listItem, 'mfui-MultipleSelectBox__listItem'), "data-mfui-group-label": "true", "aria-hidden": "true", children: (0, jsx_runtime_1.jsx)(Typography_1.Typography, { variant: "label", children: option.label }) }) }, virtualItem.key));
+            }
+            if ((0, isSelectableOption_1.isSelectableOption)(option) && option.value != null) {
+                const { value, label } = option;
+                const isDisabled = (0, isSelectableOption_1.isOptionDisabled)(option);
+                const selectedSet = enableApplyControls ? temporaryValues : localSelectedValuesSet;
+                const isSelected = (0, isSelectableOption_1.isOptionSelected)(option, selectedSet);
+                // For virtualized items, we need to find the correct focusable index
+                // based on the current filtered and focusable options, not the original flat options
+                let currentFocusableIndex = -1;
+                if (!isDisabled) {
+                    // Find this option's index in the focusableOptions array
+                    const focusableOptionIndex = focusableOptions.findIndex((focusableOpt) => focusableOpt.value === option.value);
+                    currentFocusableIndex = focusableOptionIndex !== -1 ? focusableOptionIndex : focusableIndex;
+                    focusableIndex += 1;
+                }
+                return ((0, jsx_runtime_1.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: (0, jsx_runtime_1.jsx)(FocusIndicator_1.FocusIndicator, { position: "inside", children: (0, jsx_runtime_1.jsx)("li", { role: "option", "data-focusable": !isDisabled, "data-value": value, className: (0, css_1.cx)(classes.listItem, 'mfui-MultipleSelectBox__listItem'), "aria-selected": isSelected, "aria-disabled": isDisabled, tabIndex: isDisabled ? -1 : currentFocusableIndex === tabbableOptionIndex ? 0 : -1, onFocus: () => {
+                                if (!isDisabled)
+                                    handleOptionFocus(currentFocusableIndex);
+                            }, onKeyDown: createKeyDownHandler(option), onClick: () => {
+                                if (isDisabled) {
+                                    return;
+                                }
+                                handleSelectOption(option);
+                            }, children: renderOption ? (renderOption(option, isSelected)) : ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [isSelected ? (0, jsx_runtime_1.jsx)(mfui_icons_react_1.CheckboxChecked, { "aria-hidden": "true" }) : (0, jsx_runtime_1.jsx)(mfui_icons_react_1.CheckboxUnchecked, { "aria-hidden": "true" }), (0, jsx_runtime_1.jsx)(Typography_1.Typography, { variant: "body", children: label })] })) }) }) }, virtualItem.key));
+            }
+            return null;
+        });
+    }, [
+        virtualItems,
+        virtualizedItems,
+        enableApplyControls,
+        temporaryValues,
+        localSelectedValuesSet,
+        classes,
+        handleSelectOption,
+        renderOption,
+        createKeyDownHandler,
+        handleOptionFocus,
+        tabbableOptionIndex,
+        focusableOptions,
+        virtualizer,
+    ]);
+    // Render non-virtualized items - extracted for better maintainability
+    const renderNonVirtualizedItems = (0, react_1.useCallback)(() => {
+        // Map from filteredOptions index to focusableOptions index
+        let focusableIndex = 0;
+        return filteredOptions.map((option, optionIndex) => {
+            if ((0, isSelectableOption_1.isSelectableOption)(option)) {
+                // If selectable but value is null/undefined, skip rendering
+                if (option.value == null) {
+                    return null;
+                }
+                // Only reaches here if isSelectableOption(option) is true and value is not null/undefined
+                const { value, label } = option;
+                const isDisabled = (0, isSelectableOption_1.isOptionDisabled)(option);
+                const selectedSet = enableApplyControls ? temporaryValues : localSelectedValuesSet;
+                const isSelected = (0, isSelectableOption_1.isOptionSelected)(option, selectedSet);
+                // Only increment focusableIndex for selectable and not disabled options
+                let currentFocusableIndex = -1;
+                if (!isDisabled) {
+                    currentFocusableIndex = focusableIndex;
+                    focusableIndex += 1;
+                }
+                return ((0, jsx_runtime_1.jsx)(FocusIndicator_1.FocusIndicator, { position: "inside", children: (0, jsx_runtime_1.jsx)("li", { role: "option", "data-focusable": !isDisabled, className: (0, css_1.cx)(classes.listItem, 'mfui-MultipleSelectBox__listItem'), "aria-selected": isSelected, "aria-disabled": isDisabled, tabIndex: isDisabled ? -1 : currentFocusableIndex === tabbableOptionIndex ? 0 : -1, onFocus: () => {
+                            if (!isDisabled)
+                                handleOptionFocus(currentFocusableIndex);
+                        }, onKeyDown: createKeyDownHandler(option), onClick: () => {
+                            if (isDisabled) {
+                                return;
+                            }
+                            handleSelectOption(option);
+                        }, children: renderOption ? (renderOption(option, isSelected)) : ((0, jsx_runtime_1.jsxs)(jsx_runtime_1.Fragment, { children: [isSelected ? (0, jsx_runtime_1.jsx)(mfui_icons_react_1.CheckboxChecked, { "aria-hidden": "true" }) : (0, jsx_runtime_1.jsx)(mfui_icons_react_1.CheckboxUnchecked, { "aria-hidden": "true" }), (0, jsx_runtime_1.jsx)(Typography_1.Typography, { variant: "body", children: label })] })) }) }, String(value)));
+            }
+            // Only render group label if truly a group label (no value property at all)
+            const { label } = option;
+            return ((0, jsx_runtime_1.jsx)("li", { className: classes.listItem, "data-mfui-group-label": "true", "aria-hidden": "true", children: (0, jsx_runtime_1.jsx)(Typography_1.Typography, { variant: "label", children: label }) }, `group-label-${String(optionIndex)}`));
+        });
+    }, [
+        filteredOptions,
+        enableApplyControls,
+        temporaryValues,
+        localSelectedValuesSet,
+        classes,
+        handleSelectOption,
+        renderOption,
+        createKeyDownHandler,
+        handleOptionFocus,
+        tabbableOptionIndex,
+    ]);
+    return ((0, jsx_runtime_1.jsx)(Popover_1.Popover, { renderTrigger: ({ setTriggerRef, togglePopover, handleTriggerKeyDown, handleTriggerBlur }) => ((0, jsx_runtime_1.jsx)(MultipleSelectBoxTrigger_1.MultipleSelectBoxTrigger, { ref: triggerRef, wrapperRef: setTriggerRef, selectedOptions: localSelectedOptions, id: id, disabled: disabled, triggerProps: triggerProps, triggerWrapperProps: triggerWrapperProps, name: name, placeholder: placeholder, size: size, listBoxId: listBoxId, isOptionPanelOpen: isOptionPanelOpen, invalid: invalid, showDisplayValueAsTag: showDisplayValueAsTag, renderDisplayValue: renderDisplayValue, clearButtonProps: clearButtonProps, disableClearButton: disableClearButton, updateSelectedValues: updateSelectedValues, onClick: togglePopover, onKeyDown: handleTriggerKeyDown, onBlur: handleTriggerBlur })), contentProps: { className: classes.popover }, minWidth: optionPanelProps?.minWidth, allowedPlacements: optionPanelProps?.allowedPlacements, renderContent: () => ((0, jsx_runtime_1.jsxs)("div", { ref: optionPanelRef, className: (0, css_1.cx)(classes.optionPanel, 'mfui-MultipleSelectBox__optionPanel', optionPanelProps?.className), tabIndex: -1, onKeyDown: handleKeyDownMenu, children: [enableSearchOptions || enableAllOptionsControls ? ((0, jsx_runtime_1.jsxs)(Stack_1.VStack, { className: (0, css_1.cx)(classes.menuHeader, 'mfui-MultipleSelectBox__menuHeader'), gap: "8px", children: [enableSearchOptions ? ((0, jsx_runtime_1.jsx)(SearchBox_1.SearchBox, { ref: searchInputRef, enableClearButton: true, value: searchText, textBoxSize: "small", autoComplete: "off", onChange: onSearchTextChange, ...searchBoxProps })) : null, enableAllOptionsControls ? ((0, jsx_runtime_1.jsxs)(Stack_1.HStack, { justifyContent: "space-between", children: [(0, jsx_runtime_1.jsx)(Button_1.Button, { ref: selectAllButtonRef, size: "small", onClick: handleSelectAll, children: selectAllButtonProps?.label ?? 'すべて選択' }), (0, jsx_runtime_1.jsx)(Button_1.Button, { ref: clearAllButtonRef, size: "small", onClick: handleClearAll, children: clearAllButtonProps?.label ?? 'すべて解除' })] })) : null] })) : null, (0, jsx_runtime_1.jsx)("ul", { ref: listBoxRef, role: "listbox", id: listBoxId, className: (0, css_1.cx)(classes.listBox, 'mfui-MultipleSelectBox__listBox'), tabIndex: -1, style: isVirtualized && totalSize > 0
+                        ? {
+                            height: `${String(totalSize)}px`,
+                            position: 'relative',
+                        }
+                        : undefined, children: loading ? (Array.from({ length: SKELETON_ITEM_COUNT }).map((_, index) => ((0, jsx_runtime_1.jsx)("li", { className: (0, css_1.cx)(classes.skeletonItem, 'mfui-MultipleSelectBox__skeletonItem'), children: (0, jsx_runtime_1.jsx)(Skeleton_1.Skeleton, {}) }, index)))) : isVirtualized && virtualItems.length > 0 ? (
+                    // Virtualized rendering with group support
+                    renderVirtualizedItems()) : filteredOptions.length > 0 ? (renderNonVirtualizedItems()) : ((0, jsx_runtime_1.jsx)("li", { className: (0, css_1.cx)(classes.emptyMessage, 'mfui-MultipleSelectBox__emptyMessage'), children: (0, jsx_runtime_1.jsx)(Typography_1.Typography, { variant: "body", children: enableSearchOptions && searchText && notFoundMessage
+                                ? notFoundMessage
+                                : options.length > 0
+                                    ? notFoundMessage
+                                    : emptyMessage }) })) }), enableApplyControls ? ((0, jsx_runtime_1.jsxs)(Stack_1.HStack, { className: (0, css_1.cx)(classes.menuFooter, 'mfui-MultipleSelectBox__menuFooter'), justifyContent: "space-between", alignItems: "center", children: [(0, jsx_runtime_1.jsx)(Typography_1.Typography, { variant: "body", color: "neutral.600", children: selectedCountProps?.render?.(temporaryValues.size) ?? `${String(temporaryValues.size)}件選択中` }), (0, jsx_runtime_1.jsxs)(Stack_1.HStack, { gap: "inline.horizontal", children: [(0, jsx_runtime_1.jsx)(Button_1.Button, { ref: cancelButtonRef, size: "small", priority: "secondary", onClick: handleCancelButtonClick, children: cancelButtonProps?.label ?? 'キャンセル' }), (0, jsx_runtime_1.jsx)(Button_1.Button, { ref: applyButtonRef, size: "small", priority: "primary", onClick: handleApplyButtonClick, children: applyButtonProps?.label ?? '適用' })] })] })) : null] })), open: isOptionPanelOpen, targetDOMNode: targetDOMNode, enableAutoUnmount: enableAutoUnmount, onOpenStateChanged: toggleOptionPanel, onBlur: onBlur }));
+}

package/dist/cjs/src/MultipleSelectBox/MultipleSelectBox.types.d.ts

@@ -0,0 +1,341 @@
+import { type ComponentPropsWithoutRef } from 'react';
+import { type VirtualizerOptions } from '@tanstack/react-virtual';
+import { type SearchBoxProps } from '../SearchBox';
+import { type MultipleSelectBoxTriggerProps, type PassedProps } from './MultipleSelectBoxTrigger/MultipleSelectBoxTrigger.types';
+import { type PopoverProps } from '../Popover';
+export type AllowedValueTypes = string | number | undefined;
+export type VirtualOptionTypes = Pick<VirtualizerOptions<HTMLElement, Element>, 'estimateSize' | 'overscan'>;
+export type MultipleSelectBoxOption<T extends AllowedValueTypes = string, AdditionalProps extends Record<string, unknown> = Record<string, never>> = ({
+    /**
+     * 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 is not used when the options prop is provided.
+     */
+    value?: never;
+    /**
+     * The options to be nested inside the group label.
+     */
+    options?: MultipleSelectBoxOption<T, AdditionalProps>[];
+    /**
+     * Whether this option is disabled.
+     */
+    disabled?: boolean;
+} & 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 is not used 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 FlatMultipleSelectBoxOption<T extends AllowedValueTypes = string, AdditionalProps extends Record<string, unknown> = Record<string, never>> = Extract<MultipleSelectBoxOption<T, AdditionalProps>, {
+    value?: T;
+}>;
+/**
+ * Properties for the "Select All" button
+ */
+export type SelectAllButtonProps = {
+    /**
+     * Label for the "Select All Button"
+     *
+     * @default "すべて選択"
+     */
+    label?: string;
+};
+/**
+ * Properties for the "Clear All Button"
+ */
+export type ClearAllButtonProps = {
+    /**
+     * Label for the "Clear All Button"
+     *
+     * @default "すべて解除"
+     */
+    label?: string;
+};
+/**
+ * Properties for the Selected Count text
+ */
+export type SelectedCountProps = {
+    /**
+     * Function to render the selected count text.
+     * Receives the number of selected items as an argument.
+     *
+     * @param count - The number of selected items
+     *
+     * @returns The text to display
+     *
+     * @default (count) => `${count}件選択中`
+     */
+    render?: (count: number) => React.ReactNode;
+};
+/**
+ * Properties for the "Cancel" button
+ */
+export type CancelButtonProps = {
+    /**
+     * Label for the "Cancel Button"
+     *
+     * @default "キャンセル"
+     */
+    label?: string;
+};
+/**
+ * Properties for the "Apply" button
+ */
+export type ApplyButtonProps = {
+    /**
+     * Label for the "Apply Button"
+     *
+     * @default "適用"
+     */
+    label?: string;
+};
+export type MultipleSelectBoxProps<T extends AllowedValueTypes = string, AdditionalProps extends Record<string, unknown> = Record<string, never>> = {
+    /**
+     * 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 MultipleSelectBoxOption<string, YourType>[];
+     * <MultipleSelectBox options={options} /> // Type inference works automatically!
+     * ```
+     */
+    options?: MultipleSelectBoxOption<T, AdditionalProps>[];
+    /**
+     * Pass the initial selected option values.
+     * Use this prop when you want an uncontrolled component.
+     *
+     * Can be either:
+     * - An array of primitive values (string/number) that match options' values
+     * - An array of MultipleSelectBoxOption objects with both label and value (useful for async scenarios)
+     */
+    defaultValue?: MultipleSelectBoxOption<T, AdditionalProps>['value'][] | MultipleSelectBoxOption<T, AdditionalProps>[];
+    /**
+     * Pass the currently selected option values.
+     * Use this prop when you want a controlled component.
+     * Should use this prop with "onChange" prop to control the selected options.
+     *
+     * Can be either:
+     * - An array of primitive values (string/number) that match options' values
+     * - An array of MultipleSelectBoxOption objects with both label and value (useful for async scenarios)
+     */
+    value?: MultipleSelectBoxOption<T, AdditionalProps>['value'][] | MultipleSelectBoxOption<T, AdditionalProps>[];
+    /**
+     * The message to be displayed in the listbox when the options are empty.
+     */
+    emptyMessage?: string;
+    /**
+     * 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 callback function that is called when the selected option is changed.
+     *
+     * @param values - The array of selected values
+     *
+     * @param options - The array of full option objects that were selected
+     *
+     * @example
+     * ```tsx
+     * <MultipleSelectBox
+     *   onChange={(values, options) => {
+     *     console.log('Selected values:', values);
+     *     console.log('Full options:', options); // Access labels and additional properties
+     *   }}
+     * />
+     * ```
+     */
+    onChange?: (values: MultipleSelectBoxOption<T, AdditionalProps>['value'][], options: MultipleSelectBoxOption<T, AdditionalProps>[]) => void;
+    /**
+     * Whether to enable the all options controls including "Select All" and "Clear All" buttons.
+     *
+     * @default false
+     */
+    enableAllOptionsControls?: boolean;
+    /**
+     * Whether to enable the apply controls in the option panel.
+     * Apply controls include a number of selected options and Cancel and Apply buttons.
+     * When enabled, selection changes will not be applied immediately but only after clicking the Apply button.
+     *
+     * @default false
+     */
+    enableApplyControls?: boolean;
+    /**
+     * Properties for the "Select All Button"
+     */
+    selectAllButtonProps?: SelectAllButtonProps;
+    /**
+     * Properties for the "Clear All Button"
+     */
+    clearAllButtonProps?: ClearAllButtonProps;
+    /**
+     * Properties for the Selected Count text
+     */
+    selectedCountProps?: SelectedCountProps;
+    /**
+     * Properties for the "Cancel" button
+     */
+    cancelButtonProps?: CancelButtonProps;
+    /**
+     * Properties for the "Apply" button
+     */
+    applyButtonProps?: ApplyButtonProps;
+    /**
+     * Custom render function for each option in the list.
+     * This allows you to customize how each option is displayed.
+     *
+     * @param option - The option object being rendered (includes additional properties if defined)
+     *
+     * @param isSelected - Whether the option is currently selected
+     *
+     * @returns A React node representing the custom option display
+     *
+     * @example
+     * ```tsx
+     * // Access additional properties in renderOption
+     * const options = [
+     *   { label: 'A', value: '1', customProp: 'foo' }
+     * ] satisfies MultipleSelectBoxOption<string, { customProp: string }>[];
+     *
+     * <MultipleSelectBox
+     *   options={options}
+     *   renderOption={(option, isSelected) => (
+     *     <div>{option.label} - {option.customProp}</div>
+     *   )}
+     * />
+     * ```
+     */
+    renderOption?: (option: MultipleSelectBoxOption<T, AdditionalProps>, isSelected: boolean) => React.ReactNode;
+    /**
+     * Whether to enable search options 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'>;
+    /**
+     * The properties for the option panel element.
+     *
+     * @property className - The class name of the option panel element.
+     *
+     * @property minWidth - The minimum width of the option panel element.
+     *
+     * @property allowedPlacements - Allowed placements for the popover relative to the trigger element.
+     */
+    optionPanelProps?: Pick<ComponentPropsWithoutRef<'div'>, 'className'> & {
+        minWidth?: PopoverProps['minWidth'];
+        allowedPlacements?: PopoverProps['allowedPlacements'];
+    };
+    /**
+     * Flag to indicate loading state of the options.
+     * When true, the MultipleSelectBox 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 MultipleSelectBox changes.
+     *
+     * @param open - The new open state of the MultipleSelectBox.
+     */
+    onOpenStateChanged?: (open: boolean) => void;
+    /**
+     * The callback function that is called when the MultipleSelectBox 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
+     * <MultipleSelectBox
+     *   onBlur={(event) => {
+     *     console.log('MultipleSelectBox lost focus');
+     *     // Perform validation or other actions
+     *   }}
+     * />
+     * ```
+     */
+    onBlur?: (event: React.FocusEvent<HTMLElement>) => void;
+    /**
+     * 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;
+    /**
+     * 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;
+    /**
+     * 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
+     * <MultipleSelectBox options={largeList} enableVirtualization />
+     * ```
+     */
+    enableVirtualization?: boolean;
+    /**
+     * Configuration for virtualization behavior.
+     * Only applies when `enableVirtualization` is true.
+     *
+     * @example
+     * ```tsx
+     * <MultipleSelectBox
+     *   enableVirtualization
+     *   virtualizationOptions={{
+     *     estimateSize: (index) => 48, // Function returning size in pixels
+     *     overscan: 10                 // Number of items outside visible area
+     *   }}
+     * />
+     * ```
+     */
+    virtualizationOptions?: VirtualOptionTypes;
+} & Pick<MultipleSelectBoxTriggerProps<T, AdditionalProps>, keyof PassedProps<T, AdditionalProps>>;

package/dist/cjs/src/MultipleSelectBox/MultipleSelectBox.types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/cjs/src/MultipleSelectBox/MultipleSelectBoxTrigger/MultipleSelectBoxTrigger.d.ts

@@ -0,0 +1,6 @@
+import React from 'react';
+import { type MultipleSelectBoxTriggerProps } from './MultipleSelectBoxTrigger.types';
+import { type AllowedValueTypes } from '../MultipleSelectBox.types';
+export declare const MultipleSelectBoxTrigger: <T extends AllowedValueTypes = string, AdditionalProps extends Record<string, any> = Record<string, never>>(props: MultipleSelectBoxTriggerProps<T, AdditionalProps> & {
+    ref?: React.ForwardedRef<HTMLButtonElement>;
+}) => React.ReactElement;