@moneyforward/mfui-components 4.6.0 → 4.8.0

package/dist/src/DataTable/utils/resolveColumnWidths.js

@@ -0,0 +1,41 @@
+/**
+ * The width of a column in pixels when neither `getColumnWidth` nor its header cell declares one.
+ */
+export const DEFAULT_COLUMN_WIDTH = 160;
+/**
+ * Converts the `style.width` of a header cell into pixels.
+ * Only a number or a `px` string is understood, because the column virtualizer needs the width in
+ * pixels before anything is laid out. Any other value counts as not declared.
+ *
+ * @param width - The declared width.
+ *
+ * @returns The width in pixels, or `undefined` when it cannot be resolved without layout.
+ */
+function toPixels(width) {
+    if (typeof width === 'number')
+        return Number.isFinite(width) && width > 0 ? width : undefined;
+    if (typeof width !== 'string')
+        return undefined;
+    const match = /^\s*(\d+(?:\.\d+)?)px\s*$/u.exec(width);
+    return match?.[1] === undefined ? undefined : Number(match[1]);
+}
+/**
+ * Resolves the width of every consumer column, in pixels, for column virtualization.
+ *
+ * Each column takes the first of:
+ *
+ * 1. `getColumnWidth(index)`, when it returns a width.
+ * 2. The `style.width` of the column's `DataTable.HeaderCell`, when it is a number or a `px` string.
+ * 3. {@link DEFAULT_COLUMN_WIDTH}.
+ *
+ * @param declaredColumnWidths - The `style.width` of each header cell, which also gives the number
+ * of consumer columns.
+ *
+ * @param getColumnWidth - The consumer's width callback, which receives the column index counted as
+ * `leftFixedColumnIndex` is, without the selection column.
+ *
+ * @returns The width of each consumer column in pixels.
+ */
+export function resolveColumnWidths(declaredColumnWidths, getColumnWidth) {
+    return declaredColumnWidths.map((declaredWidth, index) => getColumnWidth?.(index) ?? toPixels(declaredWidth) ?? DEFAULT_COLUMN_WIDTH);
+}

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

@@ -4,4 +4,4 @@ import { type MultipleSelectBoxProps, type AllowedValueTypes } from './MultipleS
  * 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.
  */
-export declare function MultipleSelectBox<T extends AllowedValueTypes = string, AdditionalProps extends Record<string, unknown> = Record<string, never>>({ id, triggerProps, triggerWrapperProps, size, options, defaultValue, placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode, name, onChange, value, showDisplayValueAsTag, renderDisplayValue, enableSearchOptions, notFoundMessage, searchBoxProps, loading, onSearchOptions, clearButtonProps, disableClearButton, optionPanelProps, popoverWrapperProps, enableAllOptionsControls, enableApplyControls, showSelectedCount, selectAllButtonProps, clearAllButtonProps, selectedCountProps, cancelButtonProps, applyButtonProps, renderOption, renderPopoverHeader, renderOptionList, renderPopoverFooter, onOpenStateChanged, enableAutoUnmount, onBlur, showGroupOptionDivider, enableVirtualization, virtualizationOptions, infiniteScroll, enableCreateOption, onCreateOption, createOptionProps, }: MultipleSelectBoxProps<T, AdditionalProps>): import("react/jsx-runtime").JSX.Element;
+export declare function MultipleSelectBox<T extends AllowedValueTypes = string, AdditionalProps extends Record<string, unknown> = Record<string, never>>({ id, triggerProps, triggerWrapperProps, size, options, defaultValue, placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode, name, onChange, value, showDisplayValueAsTag, renderDisplayValue, enableSearchOptions, notFoundMessage, searchBoxProps, loading, onSearchOptions, clearButtonProps, disableClearButton, optionPanelProps, popoverWrapperProps, enableAllOptionsControls, enableApplyControls, showSelectedCount, selectAllButtonProps, clearAllButtonProps, selectedCountProps, cancelButtonProps, applyButtonProps, renderOption, renderOptionLabelSlot, renderPopoverHeader, renderOptionList, renderPopoverFooter, onOpenStateChanged, enableAutoUnmount, onBlur, showGroupOptionDivider, enableVirtualization, virtualizationOptions, infiniteScroll, enableCreateOption, onCreateOption, createOptionProps, }: MultipleSelectBoxProps<T, AdditionalProps>): import("react/jsx-runtime").JSX.Element;

package/dist/src/MultipleSelectBox/MultipleSelectBox.js

@@ -26,19 +26,23 @@ import { cx } from '../../styled-system/css';
 import { flattenOptions } from './utils/flattenOptions';
 import { getGroupLabelId } from '../utilities/dom/getGroupLabelId';
 import { OptionGroupLabelDescriptions } from '../shared/OptionGroupLabelDescriptions';
+import { OptionLabel } from '../shared/OptionLabel';
 import { isSelectableOption, isOptionDisabled, isOptionSelected } from './utils/isSelectableOption';
 import { useVirtualizedMultipleSelectBoxOptions } from './hooks/useVirtualizedMultipleSelectBoxOptions';
 import { useInfiniteScroll } from '../utilities/dom/useInfiniteScroll';
 // How many skeleton items to render while the component is loading.
 const SKELETON_ITEM_COUNT = 4;
+// The default for an omitted `options` prop. A default written inline (`options = []`) is a new
+// array on every render, which invalidates every memoized value derived from the options.
+const EMPTY_OPTIONS = [];
 /**
  * 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.
  */
-export function MultipleSelectBox({ id, triggerProps, triggerWrapperProps, size, options = [], defaultValue, 
+export function MultipleSelectBox({ id, triggerProps, triggerWrapperProps, size, options = EMPTY_OPTIONS, defaultValue, 
 // eslint-disable-next-line @typescript-eslint/no-deprecated
-placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode, name, onChange, value, showDisplayValueAsTag, renderDisplayValue, enableSearchOptions = false, notFoundMessage, searchBoxProps, loading = false, onSearchOptions, clearButtonProps, disableClearButton = false, optionPanelProps, popoverWrapperProps, enableAllOptionsControls = false, enableApplyControls = false, showSelectedCount = false, selectAllButtonProps, clearAllButtonProps, selectedCountProps, cancelButtonProps, applyButtonProps, renderOption, renderPopoverHeader, renderOptionList, renderPopoverFooter, onOpenStateChanged, enableAutoUnmount = true, onBlur, showGroupOptionDivider, enableVirtualization = false, virtualizationOptions, infiniteScroll, enableCreateOption = false, onCreateOption, createOptionProps, }) {
+placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode, name, onChange, value, showDisplayValueAsTag, renderDisplayValue, enableSearchOptions = false, notFoundMessage, searchBoxProps, loading = false, onSearchOptions, clearButtonProps, disableClearButton = false, optionPanelProps, popoverWrapperProps, enableAllOptionsControls = false, enableApplyControls = false, showSelectedCount = false, selectAllButtonProps, clearAllButtonProps, selectedCountProps, cancelButtonProps, applyButtonProps, renderOption, renderOptionLabelSlot, renderPopoverHeader, renderOptionList, renderPopoverFooter, onOpenStateChanged, enableAutoUnmount = true, onBlur, showGroupOptionDivider, enableVirtualization = false, virtualizationOptions, infiniteScroll, enableCreateOption = false, onCreateOption, createOptionProps, }) {
     const classes = multipleSelectBoxSlotRecipe({ showGroupOptionDivider });
     const triggerRef = useRef(null);
     const listBoxId = useId();
@@ -187,7 +191,7 @@ placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode,
     // Create an array of focusable (selectable and not disabled) options from filteredOptions
     const focusableOptions = useMemo(() => filteredOptions.filter((option) => isSelectableOption(option) && option.value != null && !isOptionDisabled(option)), [filteredOptions]);
     // Manage the keyboard navigation of options
-    const { handleOptionFocus, createKeyDownHandler, tabbableOptionIndex } = useOptionKeyboardNavigation({
+    const { handleOptionFocus, createKeyDownHandler, tabbableOptionIndex, resetTabbableIndex } = useOptionKeyboardNavigation({
         filteredOptions: focusableOptions,
         selectedValues: enableApplyControls ? temporaryValues : localSelectedValuesSet,
         onSelectOption: handleSelectOption,
@@ -211,7 +215,7 @@ placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode,
                     }, children: _jsx("li", { role: "presentation", className: cx(classes.listItem, 'mfui-MultipleSelectBox__listItem'), "data-mfui-group-label": "true", children: _jsx(Typography, { variant: "label", children: option.label }) }) }, virtualItem.key));
             }
             if (isSelectableOption(option) && option.value != null) {
-                const { value, label } = option;
+                const { value } = option;
                 const isDisabled = isOptionDisabled(option);
                 const selectedSet = enableApplyControls ? temporaryValues : localSelectedValuesSet;
                 const isSelected = isOptionSelected(option, selectedSet);
@@ -238,7 +242,7 @@ placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode,
                                     return;
                                 }
                                 handleSelectOption(option);
-                            }, children: renderOption ? (renderOption(option, isSelected)) : (_jsxs(_Fragment, { children: [isSelected ? _jsx(CheckboxChecked, { "aria-hidden": "true" }) : _jsx(CheckboxUnchecked, { "aria-hidden": "true" }), _jsx(Typography, { variant: "body", children: label })] })) }) }) }, virtualItem.key));
+                            }, children: renderOption ? (renderOption(option, isSelected)) : (_jsxs(_Fragment, { children: [isSelected ? _jsx(CheckboxChecked, { "aria-hidden": "true" }) : _jsx(CheckboxUnchecked, { "aria-hidden": "true" }), _jsx(OptionLabel, { option: option, isSelected: isSelected, renderOptionLabelSlot: renderOptionLabelSlot, slotContentName: "multiple-select-box-option-label-slot" })] })) }) }) }, virtualItem.key));
             }
             return null;
         });
@@ -251,6 +255,7 @@ placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode,
         classes,
         handleSelectOption,
         renderOption,
+        renderOptionLabelSlot,
         createKeyDownHandler,
         handleOptionFocus,
         tabbableOptionIndex,
@@ -271,7 +276,7 @@ placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode,
                     return null;
                 }
                 // Only reaches here if isSelectableOption(option) is true and value is not null/undefined
-                const { value, label } = option;
+                const { value } = option;
                 const isDisabled = isOptionDisabled(option);
                 const selectedSet = enableApplyControls ? temporaryValues : localSelectedValuesSet;
                 const isSelected = isOptionSelected(option, selectedSet);
@@ -289,7 +294,7 @@ placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode,
                                 return;
                             }
                             handleSelectOption(option);
-                        }, children: renderOption ? (renderOption(option, isSelected)) : (_jsxs(_Fragment, { children: [isSelected ? _jsx(CheckboxChecked, { "aria-hidden": "true" }) : _jsx(CheckboxUnchecked, { "aria-hidden": "true" }), _jsx(Typography, { variant: "body", children: label })] })) }) }, String(value)));
+                        }, children: renderOption ? (renderOption(option, isSelected)) : (_jsxs(_Fragment, { children: [isSelected ? _jsx(CheckboxChecked, { "aria-hidden": "true" }) : _jsx(CheckboxUnchecked, { "aria-hidden": "true" }), _jsx(OptionLabel, { option: option, isSelected: isSelected, renderOptionLabelSlot: renderOptionLabelSlot, slotContentName: "multiple-select-box-option-label-slot" })] })) }) }, String(value)));
             }
             // Only render group label if truly a group label (no value property at all)
             const { label } = option;
@@ -304,6 +309,7 @@ placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode,
         classes,
         handleSelectOption,
         renderOption,
+        renderOptionLabelSlot,
         createKeyDownHandler,
         handleOptionFocus,
         tabbableOptionIndex,
@@ -373,7 +379,13 @@ placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode,
                     : undefined, children: renderListContent() }), isVirtualized ? renderInfiniteScrollLoading() : null, isVirtualized ? renderInfiniteScrollError('div') : null, _jsx(OptionGroupLabelDescriptions, { groups: rendersHiddenGroupLabels ? optionGroupLabels : [] })] }));
     const createOptionAreaNode = isCreateOptionVisible ? (_jsxs("div", { className: cx(classes.createOptionArea, 'mfui-MultipleSelectBox__createOptionArea'), children: [_jsxs("button", { "data-mfui-content": "create-new-option", type: "button", className: cx(classes.createOptionButton, 'mfui-MultipleSelectBox__createOptionButton'), disabled: isCreating, onClick: handleCreateOption, children: [_jsx(Add, { "aria-hidden": true }), createOptionProps?.renderLabel?.(searchText.trim()) ?? (_jsxs(_Fragment, { children: [_jsx(Typography, { variant: "strongBody", children: searchText.trim() }), _jsx(Typography, { variant: "body", children: "\u3092\u8FFD\u52A0" })] }))] }), createError ? (_jsx("div", { className: cx(classes.createOptionErrorMessage, 'mfui-MultipleSelectBox__createOptionErrorMessage'), children: _jsx(HelpMessage, { messageType: "error", children: createOptionProps?.renderErrorMessage?.(searchText.trim()) ??
                         `${searchText.trim()}を追加できませんでした。` }) })) : null] })) : null;
+    const handleOpenStateChanged = (open) => {
+        // Every opening starts from the first selected option, not from the option focused last time.
+        if (open)
+            resetTabbableIndex();
+        toggleOptionPanel();
+    };
     return (_jsx(Popover, { renderTrigger: ({ setTriggerRef, togglePopover, handleTriggerKeyDown, handleTriggerBlur }) => (_jsx(MultipleSelectBoxTrigger, { ref: triggerRef, wrapperRef: setTriggerRef, selectedOptions: localSelectedOptions, id: id, disabled: disabled, triggerProps: triggerProps, triggerWrapperProps: triggerWrapperProps, name: name, 
             // eslint-disable-next-line @typescript-eslint/no-deprecated
-            placeholder: placeholder, size: size, listBoxId: listBoxId, isOptionPanelOpen: isOptionPanelOpen, invalid: invalid, required: required, caution: caution, showDisplayValueAsTag: showDisplayValueAsTag, renderDisplayValue: renderDisplayValue, clearButtonProps: clearButtonProps, disableClearButton: disableClearButton, updateSelectedValues: updateSelectedValues, onClick: togglePopover, onKeyDown: handleTriggerKeyDown, onBlur: handleTriggerBlur })), contentProps: { className: classes.popover }, minWidth: optionPanelProps?.minWidth, maxHeight: popoverWrapperProps?.maxHeight, allowedPlacements: optionPanelProps?.allowedPlacements, renderContent: () => (_jsxs("div", { ref: optionPanelRef, className: cx(classes.optionPanel, 'mfui-MultipleSelectBox__optionPanel', optionPanelProps?.className), tabIndex: -1, onKeyDown: handleKeyDownMenu, children: [enableSearchOptions || enableAllOptionsControls ? (_jsx(VStack, { className: cx(classes.menuHeader, 'mfui-MultipleSelectBox__menuHeader'), gap: "8px", children: renderPopoverHeader ? (renderPopoverHeader({ searchNode, allOptionsControlsNode })) : (_jsxs(_Fragment, { children: [searchNode, allOptionsControlsNode] })) })) : null, renderOptionList ? (renderOptionList({ optionsNode, createOptionAreaNode })) : (_jsxs(_Fragment, { children: [optionsNode, createOptionAreaNode] })), enableApplyControls || showSelectedCount ? (_jsx(HStack, { className: cx(classes.menuFooter, 'mfui-MultipleSelectBox__menuFooter'), justifyContent: "space-between", alignItems: "center", children: renderPopoverFooter ? (renderPopoverFooter({ selectedCountNode, applyControlsNode })) : (_jsxs(_Fragment, { children: [selectedCountNode, applyControlsNode] })) })) : null] })), open: isOptionPanelOpen, targetDOMNode: targetDOMNode, enableAutoUnmount: enableAutoUnmount, onOpenStateChanged: toggleOptionPanel, onBlur: onBlur }));
+            placeholder: placeholder, size: size, listBoxId: listBoxId, isOptionPanelOpen: isOptionPanelOpen, invalid: invalid, required: required, caution: caution, showDisplayValueAsTag: showDisplayValueAsTag, renderDisplayValue: renderDisplayValue, clearButtonProps: clearButtonProps, disableClearButton: disableClearButton, updateSelectedValues: updateSelectedValues, onClick: togglePopover, onKeyDown: handleTriggerKeyDown, onBlur: handleTriggerBlur })), contentProps: { className: classes.popover }, minWidth: optionPanelProps?.minWidth, maxHeight: popoverWrapperProps?.maxHeight, allowedPlacements: optionPanelProps?.allowedPlacements, renderContent: () => (_jsxs("div", { ref: optionPanelRef, className: cx(classes.optionPanel, 'mfui-MultipleSelectBox__optionPanel', optionPanelProps?.className), tabIndex: -1, onKeyDown: handleKeyDownMenu, children: [enableSearchOptions || enableAllOptionsControls ? (_jsx(VStack, { className: cx(classes.menuHeader, 'mfui-MultipleSelectBox__menuHeader'), gap: "8px", children: renderPopoverHeader ? (renderPopoverHeader({ searchNode, allOptionsControlsNode })) : (_jsxs(_Fragment, { children: [searchNode, allOptionsControlsNode] })) })) : null, renderOptionList ? (renderOptionList({ optionsNode, createOptionAreaNode })) : (_jsxs(_Fragment, { children: [optionsNode, createOptionAreaNode] })), enableApplyControls || showSelectedCount ? (_jsx(HStack, { className: cx(classes.menuFooter, 'mfui-MultipleSelectBox__menuFooter'), justifyContent: "space-between", alignItems: "center", children: renderPopoverFooter ? (renderPopoverFooter({ selectedCountNode, applyControlsNode })) : (_jsxs(_Fragment, { children: [selectedCountNode, applyControlsNode] })) })) : null] })), open: isOptionPanelOpen, targetDOMNode: targetDOMNode, enableAutoUnmount: enableAutoUnmount, onOpenStateChanged: handleOpenStateChanged, onBlur: onBlur }));
 }

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

@@ -4,6 +4,7 @@ import { type SearchBoxProps } from '../SearchBox';
 import { type MultipleSelectBoxTriggerProps, type PassedProps } from './MultipleSelectBoxTrigger/MultipleSelectBoxTrigger.types';
 import { type PopoverProps } from '../Popover';
 import { type InfiniteScrollDirection } from '../utilities/dom/useInfiniteScroll';
+import { type RenderOptionLabelSlot } from '../shared/OptionLabel';
 export type AllowedValueTypes = string | number | undefined;
 export type VirtualOptionTypes = Pick<VirtualizerOptions<HTMLElement, Element>, 'estimateSize' | 'overscan'>;
 export type InfiniteScrollConfig = {
@@ -313,6 +314,38 @@ export type MultipleSelectBoxProps<T extends AllowedValueTypes = string, Additio
      * ```
      */
     renderOption?: (option: MultipleSelectBoxOption<T, AdditionalProps>, isSelected: boolean) => React.ReactNode;
+    /**
+     * The function to customize the label area of each option in the list, such as adding an icon or tags.
+     *
+     * Unlike `renderOption`, only the label text is replaced. The checkbox and the
+     * hover, focus, pressed, and disabled styles of the option are kept.
+     *
+     * - The `label` of the option is still required and is used for search and the trigger.
+     * - The slot content becomes the accessible name of the option. Include the same words as `label`,
+     *   as text or as the accessible name of an image, so that what users read matches what they can type.
+     * - Return only non-interactive content, because the option itself is the interactive element.
+     * - Ignored when `renderOption` is provided.
+     * - Define the function outside the component or wrap it in `useCallback`, so that the options are
+     *   not re-rendered every time the parent renders.
+     *
+     * @param option - The option object being rendered (includes additional properties if defined)
+     *
+     * @param state.isSelected - Whether the option is currently selected
+     *
+     * @example
+     * ```tsx
+     * <MultipleSelectBox
+     *   options={options}
+     *   renderOptionLabelSlot={(option) => (
+     *     <>
+     *       <Icon aria-hidden />
+     *       <span>{option.label}</span>
+     *     </>
+     *   )}
+     * />
+     * ```
+     */
+    renderOptionLabelSlot?: RenderOptionLabelSlot<MultipleSelectBoxOption<T, AdditionalProps>>;
     /**
      * Customize the popover header content.
      *

package/dist/src/MultipleSelectBox/hooks/useOptionKeyboardNavigation.d.ts

@@ -34,5 +34,6 @@ export declare function useOptionKeyboardNavigation<T extends AllowedValueTypes
     tabbableOptionIndex: number;
     handleOptionFocus: (optionIndex: number) => void;
     createKeyDownHandler: (option: MultipleSelectBoxOption<T, AdditionalProps>) => KeyboardEventHandler<HTMLLIElement>;
+    resetTabbableIndex: () => void;
 };
 export {};

package/dist/src/MultipleSelectBox/hooks/useOptionKeyboardNavigation.js

@@ -25,25 +25,31 @@ export function useOptionKeyboardNavigation({ filteredOptions, selectedValues, o
         // Fallback to 0 if no enabled option is found
         return Math.max(tabbableIndex, 0);
     }, [filteredOptions, selectedValues]);
-    // State to track which option should be tabbable
-    const [tabbableOptionIndex, setTabbableOptionIndex] = useState(getDefaultTabbableIndex());
-    // Adjusted during render (React's documented pattern for resyncing state to changed
-    // props) rather than in an effect, so the UI never flashes the stale index for one frame.
-    const [prevFilteredOptions, setPrevFilteredOptions] = useState(filteredOptions);
-    const [prevSelectedValues, setPrevSelectedValues] = useState(selectedValues);
-    if (filteredOptions !== prevFilteredOptions || selectedValues !== prevSelectedValues) {
-        setPrevFilteredOptions(filteredOptions);
-        setPrevSelectedValues(selectedValues);
-        setTabbableOptionIndex(getDefaultTabbableIndex());
-    }
-    // Update tabbable index when selected values change
+    // The focused option is stored by its value, and the tabbable index is calculated during render.
+    // Storing the index and resetting it whenever `filteredOptions` is a different array would set
+    // state during render, which loops forever when `filteredOptions` is a new array on every render
+    // (e.g. `options` is omitted). The focused option stays tabbable while it is in `filteredOptions`,
+    // including after it is toggled, so the tabbable option is always the focused one. The caller
+    // forgets it with `resetTabbableIndex` whenever the option panel opens, so every opening starts
+    // from the first selected option, or the first option when nothing is selected.
+    const [focusedOption, setFocusedOption] = useState(null);
+    const focusedOptionIndex = focusedOption
+        ? filteredOptions.findIndex((option) => isSelectableOption(option) && option.value === focusedOption.value)
+        : -1;
+    const tabbableOptionIndex = focusedOptionIndex !== -1 ? focusedOptionIndex : getDefaultTabbableIndex();
     const resetTabbableIndex = useCallback(() => {
-        setTabbableOptionIndex(getDefaultTabbableIndex());
-    }, [getDefaultTabbableIndex]);
+        setFocusedOption(null);
+    }, []);
     // Handler for when an option receives focus
     const handleOptionFocus = useCallback((optionIndex) => {
-        setTabbableOptionIndex(optionIndex);
-    }, []);
+        const option = filteredOptions[optionIndex];
+        if (!option || !isSelectableOption(option)) {
+            setFocusedOption(null);
+            return;
+        }
+        // Keep the current object when the same option is focused again, so React can skip the re-render.
+        setFocusedOption((previous) => previous && previous.value === option.value ? previous : { value: option.value });
+    }, [filteredOptions]);
     // Create keyboard event handler for an option
     const createKeyDownHandler = useCallback((option) => (event) => {
         const siblingElements = findSiblingElements(event.currentTarget, '[role="option"]:not([aria-disabled="true"])');
@@ -81,5 +87,6 @@ export function useOptionKeyboardNavigation({ filteredOptions, selectedValues, o
         tabbableOptionIndex,
         handleOptionFocus,
         createKeyDownHandler,
+        resetTabbableIndex,
     };
 }

package/dist/src/SelectBox/SelectBox.js

@@ -33,14 +33,17 @@ const DEFAULT_SCROLL_OPTIONS = {
 };
 // How many skeleton items to render while the component is loading.
 const SKELETON_ITEM_COUNT = 4;
+// The default for an omitted `options` prop. A default written inline (`options = []`) is a new
+// array on every render, which invalidates every memoized value derived from the options.
+const EMPTY_OPTIONS = [];
 /**
  * The general-purpose SelectBox component.
  * This component switches the variants of looks and behaviors depends on the props: size, invalid, caution, disabled.
  */
 export const SelectBox = forwardRef((props, ref) => {
-    const { id, triggerProps, clearButtonProps, enableClearButton = false, size, options = [], defaultValue, 
+    const { id, triggerProps, clearButtonProps, enableClearButton = false, size, options = EMPTY_OPTIONS, defaultValue, 
     // eslint-disable-next-line @typescript-eslint/no-deprecated
-    placeholder, emptyMessage, disabled, invalid, caution = false, required, 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, infiniteScroll, } = props;
+    placeholder, emptyMessage, disabled, invalid, caution = false, required, targetDOMNode, name, onChange, onBlur, value, enableSearchOptions = false, notFoundMessage, searchBoxProps, loading = false, onSearchOptions, renderDisplayValue, renderOption, renderOptionLabelSlot, renderPopoverContent, enableAutoScrollToSelectedOption, popoverContentProps, popoverWrapperProps, onOpenStateChanged, showGroupOptionDivider, triggerWrapperProps, enableAutoUnmount = true, enableConstrainedPopoverWidth = false, enableVirtualization = false, virtualizationOptions, infiniteScroll, } = props;
     const classes = selectBoxSlotRecipe({ size, showGroupOptionDivider });
     const triggerRef = useRef(null);
     const listBoxId = useId();
@@ -215,7 +218,7 @@ export const SelectBox = forwardRef((props, ref) => {
     });
     // Cleanup timeout on unmount
     useEffect(() => cleanup, [cleanup]);
-    const { tabbableOptionIndex, handleOptionFocus, createKeyDownHandler } = useKeyboardNavigation({
+    const { tabbableOptionIndex, handleOptionFocus, createKeyDownHandler, resetTabbableIndex } = useKeyboardNavigation({
         isOptionPanelOpen,
         loading,
         enableSearchOptions,
@@ -269,7 +272,7 @@ export const SelectBox = forwardRef((props, ref) => {
                 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, groupLabelId: groupLabelId, renderOption: renderOption, onFocus: handleOptionFocus, onClick: handleSelectOption, onKeyDown: (event) => {
+            }, children: _jsx(SelectBoxOptionComponent, { option: option, isSelected: localSelectedOption?.value === option.value, tabbableOptionIndex: tabbableOptionIndex, optionIndex: originalIndex ?? virtualItem.index, classes: classes, groupLabelId: groupLabelId, renderOption: renderOption, renderOptionLabelSlot: renderOptionLabelSlot, onFocus: handleOptionFocus, onClick: handleSelectOption, onKeyDown: (event) => {
                     handleTypeAhead(event.nativeEvent);
                     createKeyDownHandler(option)(event);
                 } }) }, virtualItem.key));
@@ -280,6 +283,7 @@ export const SelectBox = forwardRef((props, ref) => {
         tabbableOptionIndex,
         classes,
         renderOption,
+        renderOptionLabelSlot,
         handleOptionFocus,
         handleSelectOption,
         handleTypeAhead,
@@ -294,14 +298,14 @@ export const SelectBox = forwardRef((props, ref) => {
                 return null;
             if ('options' in option && Array.isArray(option.options)) {
                 currentGroupLabelId = getGroupLabelId(listBoxId, optionIndex);
-                return (_jsx(React.Fragment, { children: _jsx(SelectBoxOptionGroup, { groupOption: option, selectedOption: localSelectedOption, valueToIndexMap: valueToIndexMap, tabbableOptionIndex: tabbableOptionIndex, classes: classes, groupLabelId: currentGroupLabelId, hasHiddenGroupLabel: rendersHiddenGroupLabels, renderOption: renderOption, findFlatOptionIndexByValue: (_, option) => findFlatOptionIndexByValue(valueToIndexMap, option), onOptionFocus: handleOptionFocus, onOptionClick: handleSelectOption, onOptionKeyDown: (option) => (event) => {
+                return (_jsx(React.Fragment, { children: _jsx(SelectBoxOptionGroup, { groupOption: option, selectedOption: localSelectedOption, valueToIndexMap: valueToIndexMap, tabbableOptionIndex: tabbableOptionIndex, classes: classes, groupLabelId: currentGroupLabelId, hasHiddenGroupLabel: rendersHiddenGroupLabels, renderOption: renderOption, renderOptionLabelSlot: renderOptionLabelSlot, 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, groupLabelId: currentGroupLabelId, renderOption: renderOption, onFocus: handleOptionFocus, onClick: handleSelectOption, onKeyDown: (event) => {
+                return (_jsx(SelectBoxOptionComponent, { option: option, isSelected: localSelectedOption?.value === option.value, tabbableOptionIndex: tabbableOptionIndex, optionIndex: flatOptionIndex, classes: classes, groupLabelId: currentGroupLabelId, renderOption: renderOption, renderOptionLabelSlot: renderOptionLabelSlot, onFocus: handleOptionFocus, onClick: handleSelectOption, onKeyDown: (event) => {
                         handleTypeAhead(event.nativeEvent);
                         createKeyDownHandler(option)(event);
                     } }, option.value ?? `option-${option.label}-${String(optionIndex)}`));
@@ -317,6 +321,7 @@ export const SelectBox = forwardRef((props, ref) => {
         listBoxId,
         rendersHiddenGroupLabels,
         renderOption,
+        renderOptionLabelSlot,
         handleOptionFocus,
         handleSelectOption,
         handleTypeAhead,
@@ -384,6 +389,12 @@ export const SelectBox = forwardRef((props, ref) => {
     };
     const hasSelectedValue = value !== undefined || localSelectedOption !== null;
     const showClearButton = enableClearButton && hasSelectedValue;
+    const handleOpenStateChanged = (open) => {
+        // Every opening starts from the selected option, not from the option focused last time.
+        if (open)
+            resetTabbableIndex();
+        toggleOptionPanel();
+    };
     // 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, 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, 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": isOptionPanelOpen ? listBoxId : undefined, "aria-describedby": triggerProps?.['aria-describedby'], "aria-expanded": isOptionPanelOpen, "aria-haspopup": "listbox", "aria-invalid": invalid, "aria-required": required, className: cx(classes.trigger, 'mfui-SelectBox__trigger', triggerProps?.className), "data-placeholder": !!placeholder && !localSelectedOption, "data-selected": !!localSelectedOption, "data-mfui-has-clear-button": showClearButton, "data-mfui-caution": caution && !invalid ? true : undefined, onClick: togglePopover, onKeyDown: (event) => {
                             handleTypeAhead(event.nativeEvent);
@@ -391,6 +402,6 @@ export const SelectBox = forwardRef((props, ref) => {
                         }, onBlur: handleTriggerBlur, children: [_jsx("span", { "data-mfui-content": "select-box-trigger-display-value", children: renderTriggerLabel() }), _jsx(DropdownIcon, { "aria-hidden": "true", focusable: false }), _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' : size === 'large' ? 'large' : '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 }));
+                        } }) })) : null] })), contentProps: { className: classes.popover }, enableAutoUnmount: enableAutoUnmount, onOpenStateChanged: handleOpenStateChanged, onBlur: onBlur }));
 });
 SelectBox.displayName = 'SelectBox';

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

@@ -4,6 +4,7 @@ import { type SelectBoxSlotRecipeVariant } from '../../styled-system/recipes';
 import { type SearchBoxProps } from '../SearchBox';
 import { type PopoverProps } from '../Popover';
 import { type InfiniteScrollDirection } from '../utilities/dom/useInfiniteScroll';
+import { type RenderOptionLabelSlot } from '../shared/OptionLabel';
 type AllowedValueTypes = string | number | undefined;
 export type VirtualOptionTypes = Pick<VirtualizerOptions<HTMLElement, Element>, 'estimateSize' | 'overscan'>;
 export type InfiniteScrollConfig = {
@@ -349,6 +350,38 @@ export type SelectBoxProps<T extends AllowedValueTypes = string, AdditionalProps
      * ```
      */
     renderOption?: (option: SelectBoxOption<T, AdditionalProps>, isSelected: boolean) => React.ReactNode;
+    /**
+     * The function to customize the label area of each option in the list, such as adding an icon or tags.
+     *
+     * Unlike `renderOption`, only the label text is replaced. The selected mark and the
+     * hover, focus, pressed, and disabled styles of the option are kept.
+     *
+     * - The `label` of the option is still required and is used for search, type-ahead, and the trigger.
+     * - The slot content becomes the accessible name of the option. Include the same words as `label`,
+     *   as text or as the accessible name of an image, so that what users read matches what they can type.
+     * - Return only non-interactive content, because the option itself is the interactive element.
+     * - Ignored when `renderOption` is provided.
+     * - Define the function outside the component or wrap it in `useCallback`, so that the options are
+     *   not re-rendered every time the parent renders.
+     *
+     * @param option - The option object being rendered (includes additional properties if defined)
+     *
+     * @param state.isSelected - Whether the option is currently selected
+     *
+     * @example
+     * ```tsx
+     * <SelectBox
+     *   options={options}
+     *   renderOptionLabelSlot={(option) => (
+     *     <>
+     *       <Icon aria-hidden />
+     *       <span>{option.label}</span>
+     *     </>
+     *   )}
+     * />
+     * ```
+     */
+    renderOptionLabelSlot?: RenderOptionLabelSlot<SelectBoxOption<T, AdditionalProps>>;
     /**
      * The function to customize how the popover is rendered.
      * - `searchNode` is the search input element. It's available only when `enableSearchOptions` is `true`.

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

@@ -1,5 +1,5 @@
 import React from 'react';
-import { type BasedAdditionalProps, type SelectBoxOption } from './SelectBox.types';
+import { type BasedAdditionalProps, type SelectBoxOption, type SelectBoxProps } from './SelectBox.types';
 type SelectBoxOptionProps<T extends string | number | undefined = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps> = {
     /**
      * The option data to render.
@@ -32,6 +32,10 @@ type SelectBoxOptionProps<T extends string | number | undefined = string, Additi
      * Custom render function for the option.
      */
     renderOption?: (option: SelectBoxOption<T, AdditionalProps>, isSelected: boolean) => React.ReactNode;
+    /**
+     * Custom render function for the label area of the option.
+     */
+    renderOptionLabelSlot?: SelectBoxProps<T, AdditionalProps>['renderOptionLabelSlot'];
     /**
      * Handler called when option receives focus.
      */

package/dist/src/SelectBox/SelectBoxOption.js

@@ -3,14 +3,14 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 import { memo, useMemo, useCallback } from 'react';
 import { Current } from '@moneyforward/mfui-icons-react';
 import { FocusIndicator } from '../FocusIndicator';
-import { Typography } from '../Typography';
+import { OptionLabel } from '../shared/OptionLabel';
 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, groupLabelId, renderOption, onFocus, onClick, onKeyDown, }) {
+function SelectBoxOptionComponentInner({ option, isSelected, tabbableOptionIndex, optionIndex, classes, groupLabelId, renderOption, renderOptionLabelSlot, onFocus, onClick, onKeyDown, }) {
     const isDisabled = isOptionDisabled(option);
     const tabIndex = useMemo(() => (isDisabled ? -1 : optionIndex === tabbableOptionIndex ? 0 : -1), [optionIndex, tabbableOptionIndex, isDisabled]);
     const handleFocus = useCallback(() => {
@@ -25,8 +25,7 @@ function SelectBoxOptionComponentInner({ option, isSelected, tabbableOptionIndex
     }, [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, "aria-describedby": groupLabelId, 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 })] })) }) }));
+    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, "aria-describedby": groupLabelId, tabIndex: tabIndex, onFocus: handleFocus, onKeyDown: onKeyDown, onClick: handleClick, children: renderOption ? (renderOption(option, isSelected)) : (_jsxs(_Fragment, { children: [_jsx(Current, { "aria-hidden": true }), _jsx(OptionLabel, { option: option, isSelected: isSelected, renderOptionLabelSlot: renderOptionLabelSlot, slotContentName: "select-box-option-label-slot" })] })) }) }));
 }
 export const SelectBoxOptionComponent = memo(SelectBoxOptionComponentInner);
 SelectBoxOptionComponent.displayName = 'SelectBoxOptionComponent';

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

@@ -1,5 +1,5 @@
 import React from 'react';
-import { type BasedAdditionalProps, type SelectBoxOption } from './SelectBox.types';
+import { type BasedAdditionalProps, type SelectBoxOption, type SelectBoxProps } from './SelectBox.types';
 type SelectBoxOptionGroupProps<T extends string | number | undefined = string, AdditionalProps extends BasedAdditionalProps = BasedAdditionalProps> = {
     /**
      * The group option with nested options.
@@ -38,6 +38,10 @@ type SelectBoxOptionGroupProps<T extends string | number | undefined = string, A
      * Custom render function for options.
      */
     renderOption?: (option: SelectBoxOption<T, AdditionalProps>, isSelected: boolean) => React.ReactNode;
+    /**
+     * Custom render function for the label area of options.
+     */
+    renderOptionLabelSlot?: SelectBoxProps<T, AdditionalProps>['renderOptionLabelSlot'];
     /**
      * Handler called when option receives focus.
      */

package/dist/src/SelectBox/SelectBoxOptionGroup.js

@@ -8,7 +8,7 @@ import { SelectBoxOptionComponent } from './SelectBoxOption';
  * Renders a group label followed by its nested options.
  * Memoized to prevent unnecessary re-renders.
  */
-function SelectBoxOptionGroupInner({ groupOption, selectedOption, valueToIndexMap, tabbableOptionIndex, classes, groupLabelId, hasHiddenGroupLabel, renderOption, onOptionFocus, onOptionClick, onOptionKeyDown, findFlatOptionIndexByValue, }) {
+function SelectBoxOptionGroupInner({ groupOption, selectedOption, valueToIndexMap, tabbableOptionIndex, classes, groupLabelId, hasHiddenGroupLabel, renderOption, renderOptionLabelSlot, onOptionFocus, onOptionClick, onOptionKeyDown, findFlatOptionIndexByValue, }) {
     // Type-safe property access to satisfy eslint rules
     const groupLabel = groupOption.label;
     const nestedOptions = groupOption.options;
@@ -23,7 +23,7 @@ function SelectBoxOptionGroupInner({ groupOption, selectedOption, valueToIndexMa
                 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, groupLabelId: groupLabelId, renderOption: renderOption, onFocus: onOptionFocus, onClick: onOptionClick, onKeyDown: onOptionKeyDown(nestedOption) }, keyValue));
+                return (_jsx(SelectBoxOptionComponent, { option: nestedOption, isSelected: isSelected, tabbableOptionIndex: tabbableOptionIndex, optionIndex: flatOptionIndex, classes: classes, groupLabelId: groupLabelId, renderOption: renderOption, renderOptionLabelSlot: renderOptionLabelSlot, onFocus: onOptionFocus, onClick: onOptionClick, onKeyDown: onOptionKeyDown(nestedOption) }, keyValue));
             })] }));
 }
 export const SelectBoxOptionGroup = memo(SelectBoxOptionGroupInner);

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

@@ -73,5 +73,6 @@ export declare function useKeyboardNavigation<T extends string | number | undefi
     tabbableOptionIndex: number;
     handleOptionFocus: (optionIndex: number) => void;
     createKeyDownHandler: (option: SelectBoxOption<T, AdditionalProps>) => KeyboardEventHandler<HTMLLIElement>;
+    resetTabbableIndex: () => void;
 };
 export {};

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

@@ -2,6 +2,7 @@
 /* eslint-disable @typescript-eslint/no-unnecessary-condition */
 import { useState, useCallback, useEffect } from 'react';
 import { findSiblingElements } from '../../utilities/dom/findSiblingElements';
+import { getDeepActiveElement } from '../../utilities/dom/getDeepActiveElement';
 import { escapeAttributeSelector } from '../utils/getFlatOptions';
 import { isOptionDisabled } from '../utils/isSelectableOption';
 const DEFAULT_SCROLL_OPTIONS = {
@@ -29,28 +30,41 @@ export function useKeyboardNavigation({ isOptionPanelOpen, loading, enableSearch
             : -1;
         return selectedIndex !== -1 ? selectedIndex : 0;
     }, [flatOptions, localSelectedOption]);
-    const [tabbableOptionIndex, setTabbableOptionIndex] = useState(getDefaultTabbableIndex());
-    // Adjusted during render (React's documented pattern for resyncing state to changed
-    // props) rather than in an effect, so the UI never flashes the stale index for one frame.
-    const [prevFlatOptions, setPrevFlatOptions] = useState(flatOptions);
-    const [prevLocalSelectedOption, setPrevLocalSelectedOption] = useState(localSelectedOption);
-    if (flatOptions !== prevFlatOptions || localSelectedOption !== prevLocalSelectedOption) {
-        setPrevFlatOptions(flatOptions);
-        setPrevLocalSelectedOption(localSelectedOption);
-        setTabbableOptionIndex(getDefaultTabbableIndex());
-    }
+    // The focused option is stored by its value, and the tabbable index is calculated during render.
+    // Storing the index and resetting it whenever `flatOptions` is a different array would set state
+    // during render, which loops forever when `flatOptions` is a new array on every render (e.g.
+    // `options` is omitted). The focused option stays tabbable while it is in `flatOptions`. The
+    // caller forgets it with `resetTabbableIndex` whenever the option panel opens, so every opening
+    // starts from the selected option, or the first option when nothing is selected.
+    const [focusedOption, setFocusedOption] = useState(null);
+    const focusedOptionIndex = focusedOption
+        ? flatOptions.findIndex((option) => option.value === focusedOption.value)
+        : -1;
+    const tabbableOptionIndex = focusedOptionIndex !== -1 ? focusedOptionIndex : getDefaultTabbableIndex();
     const resetTabbableIndex = useCallback(() => {
-        setTabbableOptionIndex(getDefaultTabbableIndex());
-    }, [getDefaultTabbableIndex]);
+        setFocusedOption(null);
+    }, []);
     const handleOptionFocus = useCallback((optionIndex) => {
-        setTabbableOptionIndex(optionIndex);
+        const option = flatOptions[optionIndex];
+        if (!option) {
+            setFocusedOption(null);
+            return;
+        }
+        // Keep the current object when the same option is focused again, so React can skip the re-render.
+        setFocusedOption((previous) => previous && previous.value === option.value ? previous : { value: option.value });
         // 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
-    }, []);
+    }, [flatOptions]);
     useEffect(() => {
         if (!isOptionPanelOpen)
             return;
+        // The effect also runs when the options change while the panel is open (e.g. infinite scroll
+        // loaded more). Don't take the focus away from an option the user has already moved to.
+        const activeElement = getDeepActiveElement();
+        if (activeElement?.getAttribute('role') === 'option' && optionPanelRef.current?.contains(activeElement)) {
+            return;
+        }
         // When loading, focus on the option panel root div to enable ESC key functionality
         if (loading) {
             optionPanelRef.current?.focus({ preventScroll: true });
@@ -220,5 +234,6 @@ export function useKeyboardNavigation({ isOptionPanelOpen, loading, enableSearch
         tabbableOptionIndex,
         handleOptionFocus,
         createKeyDownHandler,
+        resetTabbableIndex,
     };
 }

package/dist/src/Tooltip/Tooltip.d.ts

@@ -9,6 +9,12 @@ export declare const DEFAULT_MAX_WIDTH = "268px";
  * - `className`: Applied to the root wrapper element that contains the trigger children
  * - `contentProps.className`: Applied to the floating tooltip content element
  *
+ * ## Layering
+ *
+ * The tooltip content is drawn on the `--mfui-z-index-tooltip` layer (`10000`), above every other layer MFUI renders.
+ * To place it above an application overlay with a higher `z-index`, set `z-index` through `contentProps.className`.
+ * See the "Layering" page in Storybook for the full layer order.
+ *
  * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span
  *
  * @example

package/dist/src/Tooltip/Tooltip.js

@@ -22,6 +22,12 @@ export const DEFAULT_MAX_WIDTH = '268px';
  * - `className`: Applied to the root wrapper element that contains the trigger children
  * - `contentProps.className`: Applied to the floating tooltip content element
  *
+ * ## Layering
+ *
+ * The tooltip content is drawn on the `--mfui-z-index-tooltip` layer (`10000`), above every other layer MFUI renders.
+ * To place it above an application overlay with a higher `z-index`, set `z-index` through `contentProps.className`.
+ * See the "Layering" page in Storybook for the full layer order.
+ *
  * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span
  *
  * @example