@moneyforward/mfui-components 4.5.0 → 4.7.0

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

@@ -44,6 +44,8 @@ export type PageHeaderProps = {
     showBackButton?: boolean;
     /**
      * It's for controlling the back button.
+     *
+     * The default `aria-label` is `戻る`, but set it to `{destination}へ戻る` (e.g. `請求書一覧へ戻る`) so that users know where the button navigates to.
      */
     backButtonProps?: Omit<IconButtonProps, 'outlined' | 'children'>;
     /**

package/dist/src/Popover/Popover.js

@@ -40,6 +40,15 @@ export function Popover({ renderTrigger, renderContent, open, onOpenStateChanged
         constrainToTriggerWidth: enableConstrainedContentWidth,
         enableCenteredLayoutOnNarrowViewport,
     });
+    // Mirrors `refs.floating.current` into state so `TargetDomNodeProvider` below can be
+    // given it directly, instead of reading a ref's `.current` during render (unsafe: a
+    // ref update never triggers the re-render needed to pass a fresh value to context
+    // consumers). `refs.setFloating` still runs so floating-ui keeps positioning it.
+    const [floatingElement, setFloatingElement] = useState(null);
+    const setFloatingRef = useCallback((node) => {
+        refs.setFloating(node);
+        setFloatingElement(node);
+    }, [refs]);
     // Fire onOpen / onClose *only* when the open state actually changes.
     // We keep a ref of the previous open state so a new toggleEvent while already
     // open does not retrigger `onOpen`, which previously caused unexpected focus
@@ -253,8 +262,8 @@ export function Popover({ renderTrigger, renderContent, open, onOpenStateChanged
             });
         };
     }, [isPopoverOpen, refs.reference, refs.floating]);
-    return (_jsxs(_Fragment, { children: [renderTrigger(options), shouldRenderTheContent ? (_jsx(Portal, { targetDOMNode: targetElement, children: _jsx("div", { ref: refs.setFloating, id: contentProps.id, tabIndex: contentProps.tabIndex ?? 0, "data-mfui-content": "popover-portal-content", "data-mfui-popover-depth": nestingDepth, className: cx(classes.root, 'mfui-Popover__root', contentProps.className), style: {
+    return (_jsxs(_Fragment, { children: [renderTrigger(options), shouldRenderTheContent ? (_jsx(Portal, { targetDOMNode: targetElement, children: _jsx("div", { ref: setFloatingRef, id: contentProps.id, tabIndex: contentProps.tabIndex ?? 0, "data-mfui-content": "popover-portal-content", "data-mfui-popover-depth": nestingDepth, className: cx(classes.root, 'mfui-Popover__root', contentProps.className), style: {
                         ...floatingStyles,
                         ...(!enableAutoUnmount && !isPopoverOpen && { display: 'none' }),
-                    }, onKeyDown: handleKeyDownPopover, children: _jsx(TargetDomNodeProvider, { targetDomNode: refs.floating.current, children: _jsx(PopoverContextProvider, { children: renderContent(options) }) }) }) })) : null] }));
+                    }, onKeyDown: handleKeyDownPopover, children: _jsx(TargetDomNodeProvider, { targetDomNode: floatingElement, children: _jsx(PopoverContextProvider, { children: renderContent(options) }) }) }) })) : null] }));
 }

package/dist/src/SelectBox/SelectBox.js

@@ -33,12 +33,15 @@ 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;
     const classes = selectBoxSlotRecipe({ size, showGroupOptionDivider });
@@ -47,7 +50,7 @@ export const SelectBox = forwardRef((props, ref) => {
     const optionPanelRef = useRef(null);
     const scrollWrapperRef = useRef(null);
     const searchInputRef = useRef(null);
-    const [localSelectedOption, setLocalSelectedOption] = useState(() => defaultValue ?? null);
+    const [localSelectedOption, setLocalSelectedOption] = useState(() => value ?? defaultValue ?? null);
     const { isOpen: isOptionPanelOpen, toggle: toggleOptionPanel, close: closeOptionPanel, } = useDisclosure({
         value: false,
         onToggle: onOpenStateChanged,
@@ -63,17 +66,16 @@ export const SelectBox = forwardRef((props, ref) => {
             resetSearchText();
         }
     }, [isOptionPanelOpen, resetSearchText]);
-    const selectedOption = useMemo(() => {
-        if (value === undefined)
-            return null;
-        return value;
-    }, [value]);
-    useEffect(() => {
-        // Only update when value prop is explicitly provided (controlled mode)
+    // Adjusted during render (React's documented pattern for resyncing state to a
+    // changed prop) rather than in an effect, so the UI never flashes the stale value
+    // for one frame. Only fires when value prop is explicitly provided (controlled mode).
+    const [prevValue, setPrevValue] = useState(value);
+    if (value !== prevValue) {
+        setPrevValue(value);
         if (value !== undefined) {
-            setLocalSelectedOption(selectedOption);
+            setLocalSelectedOption(value);
         }
-    }, [selectedOption, value]);
+    }
     useUpdateEffect(() => {
         if (value === undefined) {
             setLocalSelectedOption(null);
@@ -216,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,
@@ -385,6 +387,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);
@@ -392,6 +400,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/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,22 +30,41 @@ export function useKeyboardNavigation({ isOptionPanelOpen, loading, enableSearch
             : -1;
         return selectedIndex !== -1 ? selectedIndex : 0;
     }, [flatOptions, localSelectedOption]);
-    const [tabbableOptionIndex, setTabbableOptionIndex] = useState(getDefaultTabbableIndex());
-    useEffect(() => {
-        setTabbableOptionIndex(getDefaultTabbableIndex());
-    }, [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 });
@@ -214,5 +234,6 @@ export function useKeyboardNavigation({ isOptionPanelOpen, loading, enableSearch
         tabbableOptionIndex,
         handleOptionFocus,
         createKeyDownHandler,
+        resetTabbableIndex,
     };
 }

package/dist/src/SplitView/hooks/useSplitViewPanelVisibility.js

@@ -19,8 +19,11 @@ export function useSplitViewPanelVisibility(isOpen, controlledPanelSlot) {
     if (wasRightPanelVisibleOnMountRef.current === null) {
         wasRightPanelVisibleOnMountRef.current = isRightPanelVisible;
     }
-    // Initialize hasRightPanelBeenVisible based on initial render state
-    const [hasRightPanelBeenVisible, setHasRightPanelBeenVisible] = useState(() => wasRightPanelVisibleOnMountRef.current ?? false);
+    // Initialize hasRightPanelBeenVisible based on initial render state. Reads
+    // `isRightPanelVisible` directly rather than the ref just written above — on first
+    // render (the only render this initial value matters for) they're the same value, and
+    // this avoids passing a ref's `.current` into a function call during render.
+    const [hasRightPanelBeenVisible, setHasRightPanelBeenVisible] = useState(isRightPanelVisible);
     // Track previous visibility state
     // Note: This ref is updated in useSplitViewAnimation hook to ensure correct timing
     const previousIsRightPanelVisibleRef = useRef(isRightPanelVisible);

package/dist/src/SubNavigation/SubNavigation.js

@@ -1,6 +1,6 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { DisclosureBasicCollapsed, Lock } from '@moneyforward/mfui-icons-react';
-import { forwardRef } from 'react';
+import { forwardRef, useId } from 'react';
 import { cx } from '../../styled-system/css';
 import { subNavigationSlotRecipe } from '../../styled-system/recipes';
 import { FocusIndicator } from '../FocusIndicator';
@@ -30,6 +30,7 @@ SubNavigation.displayName = 'SubNavigation';
  * - a disclosure button with children
  *
  * This function is splitted from the SubNavigation component to allow for recursive rendering for deep nesting.
+ * It is called inside loops, so it must not call hooks. Create them in the rendered components instead.
  *
  * @param navigationItem - The navigation item to render.
  *
@@ -44,57 +45,117 @@ SubNavigation.displayName = 'SubNavigation';
  * @returns The rendered navigation item.
  */
 const renderNavigationItem = (navigationItem, customLinkComponent, classes, nestLevel, renderNavigationLabel) => {
-    const { label, href, labelIcon, statusSlot, locked, lockIconProps, children } = navigationItem;
-    if (children === undefined) {
+    if (navigationItem.children === undefined) {
         return (_jsx(NavigationLink, { navigationItem: navigationItem, customLinkComponent: customLinkComponent, classes: classes, renderNavigationLabel: renderNavigationLabel }));
     }
-    if (href) {
+    const nestedNavigationList = (_jsx(NestedNavigationList, { parentNavigationItem: navigationItem, customLinkComponent: customLinkComponent, classes: classes, nestLevel: nestLevel + 1, renderNavigationLabel: renderNavigationLabel }));
+    if (navigationItem.href) {
         // The the parent item will be rendered as a link with separated disclosure icon button.
-        return (_jsxs(_Fragment, { children: [_jsx(NavigationLink, { navigationItem: navigationItem, customLinkComponent: customLinkComponent, classes: classes, renderNavigationLabel: renderNavigationLabel }), _jsx(NestedNavigationList, { summarySlot: _jsx("div", { "data-mfui-content": "sub-navigation-disclosure-icon", className: cx(classes.disclosureIcon, 'mfui-SubNavigation__disclosureIcon'), children: _jsx(DisclosureBasicCollapsed, { role: "img", "aria-label": label }) }), nestedNavigationItems: children, customLinkComponent: customLinkComponent, classes: classes, nestLevel: nestLevel + 1, renderNavigationLabel: renderNavigationLabel })] }));
+        return (_jsxs(_Fragment, { children: [_jsx(NavigationLink, { navigationItem: navigationItem, customLinkComponent: customLinkComponent, classes: classes, renderNavigationLabel: renderNavigationLabel }), nestedNavigationList] }));
     }
     // The the parent item will be rendered as a disclosure button with an icon.
-    return (_jsx(NestedNavigationList, { summarySlot: _jsxs(_Fragment, { children: [_jsx(NavigationLabelGroup, { label, labelIcon, locked, lockIconProps, statusSlot, classes, renderNavigationLabel }), _jsx("div", { "data-mfui-content": "sub-navigation-disclosure-icon", className: cx(classes.disclosureIcon, 'mfui-SubNavigation__disclosureIcon'), children: _jsx(DisclosureBasicCollapsed, { "aria-hidden": "true" }) })] }), nestedNavigationItems: children, customLinkComponent: customLinkComponent, classes: classes, nestLevel: nestLevel + 1, renderNavigationLabel: renderNavigationLabel }));
+    return nestedNavigationList;
 };
 /**
- * This is a group of a text label, an optional icon, and a status.
+ * Create the IDs only when the item has a description.
+ * Without a description, the item keeps its accessible name from its content.
+ *
+ * @param hasDescription - Whether the item has a description.
+ *
+ * @returns The IDs, or `undefined` when the item has no description.
+ */
+function useLabelIds(hasDescription) {
+    const id = useId();
+    if (!hasDescription)
+        return undefined;
+    return { label: `${id}-label`, status: `${id}-status`, description: `${id}-description` };
+}
+/**
+ * Get the ARIA attributes for the element that contains the NavigationLabelGroup.
+ *
+ * @param labelIds - The IDs from `useLabelIds`.
+ *
+ * @param hasStatus - Whether the status is displayed.
+ *
+ * @returns The ARIA attributes. Empty when the item has no description.
+ */
+function getLabelAriaProps(labelIds, hasStatus) {
+    if (!labelIds)
+        return {};
+    return {
+        'aria-labelledby': hasStatus ? `${labelIds.label} ${labelIds.status}` : labelIds.label,
+        'aria-describedby': labelIds.description,
+    };
+}
+/**
+ * This is a group of a text label, an optional description, an optional icon, and a status.
  * This is used for all navigation links and parent items for disclosure buttons in SubNavigation.
  */
-function NavigationLabelGroup({ label, labelIcon, locked, lockIconProps, statusSlot, classes, renderNavigationLabel, }) {
+function NavigationLabelGroup({ label, description, labelIcon, locked, lockIconProps, statusSlot, labelIds, classes, renderNavigationLabel, }) {
     // If locked=true, display <Lock /> icon in preference to any other status of the statusSlot option.
     const renderStatus = () => {
         if (locked) {
-            return (_jsx("div", { className: cx(classes.statusSlot, 'mfui-SubNavigation__statusSlot'), children: _jsx(Lock, { role: "img", "aria-label": lockIconProps?.['aria-label'] ?? 'ロックされています' }) }));
+            return (_jsx("span", { id: labelIds?.status, className: cx(classes.statusSlot, 'mfui-SubNavigation__statusSlot'), children: _jsx(Lock, { role: "img", "aria-label": lockIconProps?.['aria-label'] ?? 'ロックされています' }) }));
         }
         if (statusSlot) {
-            return _jsx("div", { className: cx(classes.statusSlot, 'mfui-SubNavigation__statusSlot'), children: statusSlot });
+            return (_jsx("span", { id: labelIds?.status, className: cx(classes.statusSlot, 'mfui-SubNavigation__statusSlot'), children: statusSlot }));
         }
         return null;
     };
-    return (_jsxs(_Fragment, { children: [labelIcon ? (_jsx("div", { "aria-hidden": "true", className: cx(classes.labelIcon, 'mfui-SubNavigation__labelIcon'), children: labelIcon })) : null, renderNavigationLabel ? (renderNavigationLabel(label)) : (_jsx(Typography, { variant: "strongControlLabel", className: cx(classes.label, 'mfui-SubNavigation__label'), children: label })), renderStatus()] }));
+    const labelText = renderNavigationLabel ? (renderNavigationLabel(label)) : (_jsx(Typography, { variant: "strongControlLabel", className: cx(classes.label, 'mfui-SubNavigation__label'), children: label }));
+    return (_jsxs(_Fragment, { children: [_jsxs("span", { className: cx(classes.labelContainer, 'mfui-SubNavigation__labelContainer'), children: [labelIcon ? (_jsx("span", { "aria-hidden": "true", className: cx(classes.labelIcon, 'mfui-SubNavigation__labelIcon'), children: labelIcon })) : null, _jsxs("span", { className: cx(classes.labelContent, 'mfui-SubNavigation__labelContent'), children: [labelIds ? _jsx("span", { id: labelIds.label, children: labelText }) : labelText, description ? (_jsx(Typography, { variant: "helpMessage", id: labelIds?.description, "data-mfui-content": "sub-navigation-description", className: cx(classes.description, 'mfui-SubNavigation__description'), children: description })) : null] })] }), renderStatus()] }));
 }
 /**
  * This is a link that has NavigationLabelGroup.
  * This is used for all navigation links in SubNavigation.
  */
 function NavigationLink({ navigationItem, customLinkComponent, classes, renderNavigationLabel, }) {
-    const { label, href, isCurrent, isExternal, labelIcon, statusSlot, locked, lockIconProps } = navigationItem;
+    const { label, description, href, isCurrent, isExternal, labelIcon, statusSlot, locked, lockIconProps } = navigationItem;
+    const labelIds = useLabelIds(!!description);
+    const labelAriaProps = getLabelAriaProps(labelIds, !!locked || !!statusSlot);
+    const labelGroup = (_jsx(NavigationLabelGroup, { label,
+        description,
+        labelIcon,
+        locked,
+        lockIconProps,
+        statusSlot,
+        labelIds,
+        classes,
+        renderNavigationLabel }));
     if (navigationItem.children === undefined && navigationItem.onClick) {
         const { onClick } = navigationItem;
-        return (_jsx(FocusIndicator, { children: _jsx("button", { type: "button", className: cx(classes.link, 'mfui-SubNavigation__link'), "aria-current": isCurrent ? 'page' : undefined, onClick: () => {
+        return (_jsx(FocusIndicator, { children: _jsx("button", { type: "button", className: cx(classes.link, 'mfui-SubNavigation__link'), "aria-current": isCurrent ? 'page' : undefined, ...labelAriaProps, onClick: () => {
                     onClick(navigationItem.href);
-                }, children: _jsx(NavigationLabelGroup, { label, labelIcon, locked, lockIconProps, statusSlot, classes, renderNavigationLabel }) }) }));
+                }, children: labelGroup }) }));
     }
     if (customLinkComponent && !isExternal) {
         const Tag = customLinkComponent;
-        return (_jsx(FocusIndicator, { children: _jsx(Tag, { href: href, className: cx(classes.link, 'mfui-SubNavigation__link'), "aria-current": isCurrent ? 'page' : undefined, children: _jsx(NavigationLabelGroup, { label, labelIcon, locked, lockIconProps, statusSlot, classes, renderNavigationLabel }) }) }));
+        return (_jsx(FocusIndicator, { children: _jsx(Tag, { href: href, className: cx(classes.link, 'mfui-SubNavigation__link'), "aria-current": isCurrent ? 'page' : undefined, ...labelAriaProps, children: labelGroup }) }));
     }
-    return (_jsx(FocusIndicator, { children: _jsx("a", { href: href, target: isExternal ? '_blank' : undefined, className: cx(classes.link, 'mfui-SubNavigation__link'), "aria-current": isCurrent ? 'page' : undefined, rel: "noreferrer", children: _jsx(NavigationLabelGroup, { label, labelIcon, locked, lockIconProps, statusSlot, classes, renderNavigationLabel }) }) }));
+    return (_jsx(FocusIndicator, { children: _jsx("a", { href: href, target: isExternal ? '_blank' : undefined, className: cx(classes.link, 'mfui-SubNavigation__link'), "aria-current": isCurrent ? 'page' : undefined, rel: "noreferrer", ...labelAriaProps, children: labelGroup }) }));
 }
 /**
  * This is a details element that contains a list of nested navigation links.
+ *
+ * - When the parent item has `href`, the summary is only the disclosure icon button next to the parent link.
+ * - Otherwise, the summary is the disclosure button with the label of the parent item.
  */
-function NestedNavigationList({ summarySlot, nestedNavigationItems, customLinkComponent, classes, nestLevel, renderNavigationLabel, }) {
+function NestedNavigationList({ parentNavigationItem, customLinkComponent, classes, nestLevel, renderNavigationLabel, }) {
+    const { label, description, href, labelIcon, statusSlot, locked, lockIconProps, children } = parentNavigationItem;
+    // With href, the description belongs to the parent link, not to the disclosure icon button.
+    const labelIds = useLabelIds(!href && !!description);
+    const labelAriaProps = getLabelAriaProps(labelIds, !!locked || !!statusSlot);
     // Check whether all descendants have isCurrent=true by calling itself recursively.
-    const isCurrentPathInChildren = (children) => children?.some(({ isCurrent, children }) => isCurrent || (children && isCurrentPathInChildren(children))) || false;
-    return (_jsxs("details", { open: isCurrentPathInChildren(nestedNavigationItems), className: cx(classes.details, 'mfui-SubNavigation__details'), children: [_jsx(FocusIndicator, { children: _jsx("summary", { className: cx(classes.summary, 'mfui-SubNavigation__summary'), children: summarySlot }) }), _jsx("ul", { className: cx(classes.list, 'mfui-SubNavigation__list'), children: nestedNavigationItems.map((nestedNavigationItem, index) => (_jsx("li", { className: cx(classes.nestedListItem, 'mfui-SubNavigation__nestedListItem'), "data-mfui-nest-level": nestLevel, children: nestedNavigationItem.children === undefined ? (_jsx(NavigationLink, { navigationItem: nestedNavigationItem, customLinkComponent: customLinkComponent, classes: classes, renderNavigationLabel: renderNavigationLabel })) : (renderNavigationItem(nestedNavigationItem, customLinkComponent, classes, nestLevel + 1, renderNavigationLabel)) }, index))) })] }));
+    const isCurrentPathInChildren = (children) => children?.some(({ isCurrent, children }) => !!isCurrent || !!(children && isCurrentPathInChildren(children))) ??
+        false;
+    const summarySlot = href ? (_jsx("span", { "data-mfui-content": "sub-navigation-disclosure-icon", className: cx(classes.disclosureIcon, 'mfui-SubNavigation__disclosureIcon'), children: _jsx(DisclosureBasicCollapsed, { role: "img", "aria-label": label }) })) : (_jsxs(_Fragment, { children: [_jsx(NavigationLabelGroup, { label,
+                description,
+                labelIcon,
+                locked,
+                lockIconProps,
+                statusSlot,
+                labelIds,
+                classes,
+                renderNavigationLabel }), _jsx("span", { "data-mfui-content": "sub-navigation-disclosure-icon", className: cx(classes.disclosureIcon, 'mfui-SubNavigation__disclosureIcon'), children: _jsx(DisclosureBasicCollapsed, { "aria-hidden": "true" }) })] }));
+    return (_jsxs("details", { open: isCurrentPathInChildren(children), className: cx(classes.details, 'mfui-SubNavigation__details'), children: [_jsx(FocusIndicator, { children: _jsx("summary", { className: cx(classes.summary, 'mfui-SubNavigation__summary'), ...labelAriaProps, children: summarySlot }) }), _jsx("ul", { className: cx(classes.list, 'mfui-SubNavigation__list'), children: children.map((nestedNavigationItem, index) => (_jsx("li", { className: cx(classes.nestedListItem, 'mfui-SubNavigation__nestedListItem'), "data-mfui-nest-level": nestLevel, children: nestedNavigationItem.children === undefined ? (_jsx(NavigationLink, { navigationItem: nestedNavigationItem, customLinkComponent: customLinkComponent, classes: classes, renderNavigationLabel: renderNavigationLabel })) : (renderNavigationItem(nestedNavigationItem, customLinkComponent, classes, nestLevel, renderNavigationLabel)) }, index))) })] }));
 }

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

@@ -76,12 +76,12 @@ type BaseSubNavigationProps = {
     customLinkComponent?: ElementType;
     /**
      * Custom render function for each navigation item's label.
-     * Receives the item's raw `label` string and returns a ReactNode rendered inside
-     * the default `<Typography variant="strongControlLabel">` wrapper.
-     * When omitted, the label string is rendered directly (default behavior).
+     * Receives the item's raw `label` string and returns a ReactNode that replaces
+     * the default `<Typography variant="strongControlLabel">` label.
+     * When omitted, the label string is rendered with the default label style.
      *
-     * Use this to truncate long labels or otherwise customize how labels are displayed
-     * without losing the built-in semantic markup.
+     * Use this to truncate long labels or otherwise customize how labels are displayed.
+     * It only affects the label, not the item's `description`.
      *
      * To show a tooltip on both hover and focus, wrap the entire link with a `Tooltip`
      * via `customLinkComponent` instead — placing a `Tooltip` inside `renderNavigationLabel`
@@ -90,7 +90,7 @@ type BaseSubNavigationProps = {
      *
      * @param label - The label string of the navigation item.
      *
-     * @returns ReactNode - Custom content rendered inside the label wrapper.
+     * @returns ReactNode - Custom content rendered in place of the default label.
      *
      * @example
      * ```tsx
@@ -184,6 +184,18 @@ type BaseNavigationItem = {
      * The text label briefly describing the linked page.
      */
     label: string;
+    /**
+     * A short supplementary text displayed below the text label.
+     *
+     * Screen readers announce it as the item's description, after the label and the status.
+     * Only plain text is accepted because the item itself is a link or a button.
+     *
+     * @example
+     * ```tsx
+     * <SubNavigation navigationItems={[{ label: '請求書', description: '作成・送付', href: '/invoices' }]} />
+     * ```
+     */
+    description?: string;
     /**
      * Whether the navigation item is the current page.
      *

package/dist/src/Tabs/Tabs.js

@@ -1,6 +1,6 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useMemo, useRef, useState } from 'react';
+import { useMemo, useState } from 'react';
 import { tabsSlotRecipe } from '../../styled-system/recipes';
 import { useCalculatedSelectedTabId } from './hooks/useCalculatedSelectedTabId';
 import { useTabRegistry } from './hooks/useTabRegistry';
@@ -13,7 +13,10 @@ import { cx } from '../../styled-system/css';
 function Base({ selectedTabId, onSelectedTabChange, targetDOMNode, enableAutoUnmount = true, children, className, style, }) {
     const classNames = tabsSlotRecipe();
     const [shouldShowMenu, setShouldShowMenu] = useState(false);
-    const wrapperRef = useRef(null);
+    // State (not a ref) so `getTargetDomNode` below can be given the wrapper element
+    // without reading a ref's `.current` during render (unsafe: a ref update never
+    // triggers the re-render needed to pass a fresh value into context).
+    const [wrapperElement, setWrapperElement] = useState(null);
     const { tabs, registerTab, updateTab, unregisterTab } = useTabRegistry();
     const { calculatedSelectedTabId, setCalculatedSelectedTab } = useCalculatedSelectedTabId({
         selectedTabId,
@@ -26,7 +29,7 @@ function Base({ selectedTabId, onSelectedTabChange, targetDOMNode, enableAutoUnm
         tabs,
         shouldShowMenu,
         setShouldShowMenu,
-        targetDOMNode: getTargetDomNode(targetDOMNode, wrapperRef.current),
+        targetDOMNode: getTargetDomNode(targetDOMNode, wrapperElement),
         registerTab,
         updateTab,
         unregisterTab,
@@ -38,12 +41,13 @@ function Base({ selectedTabId, onSelectedTabChange, targetDOMNode, enableAutoUnm
         shouldShowMenu,
         setShouldShowMenu,
         targetDOMNode,
+        wrapperElement,
         registerTab,
         updateTab,
         unregisterTab,
         enableAutoUnmount,
     ]);
-    return (_jsx(TabContext.Provider, { value: contextValue, children: _jsx("div", { ref: wrapperRef, className: cx(classNames.root, 'mfui-Tabs__root', className), style: style, children: children }) }));
+    return (_jsx(TabContext.Provider, { value: contextValue, children: _jsx("div", { ref: setWrapperElement, className: cx(classNames.root, 'mfui-Tabs__root', className), style: style, children: children }) }));
 }
 /**
  * The Tabs component manages the tabs, tab lists, and tab panels within a tab section.

package/dist/src/Tabs/hooks/useCalculatedSelectedTabId.js

@@ -1,4 +1,4 @@
-import { useEffect, useState } from 'react';
+import { useState } from 'react';
 /**
  * Custom hook to manage the selected tab ID based on provided options.
  * Automatically updates the selected tab ID when the `selectedTabId` prop changes.
@@ -12,11 +12,13 @@ import { useEffect, useState } from 'react';
 export function useCalculatedSelectedTabId({ selectedTabId, onSelectedTabChange, tabs, }) {
     // implement
     const [calculatedSelectedTabId, setCalculatedSelectedTabId] = useState(selectedTabId);
-    // TODO use useUpdateEffect later, after the PR has this hook is merged
-    // Automatically update the selected tabId if the selectedTabId prop changes
-    useEffect(() => {
+    // Adjusted during render (React's documented pattern for resyncing state to a changed
+    // prop) rather than in an effect, so the UI never flashes the stale tab for one frame.
+    const [prevSelectedTabId, setPrevSelectedTabId] = useState(selectedTabId);
+    if (selectedTabId !== prevSelectedTabId) {
+        setPrevSelectedTabId(selectedTabId);
         setCalculatedSelectedTabId(selectedTabId);
-    }, [selectedTabId]);
+    }
     return {
         // If still nothing, we pick the first tabId from the tab list
         calculatedSelectedTabId: calculatedSelectedTabId ?? tabs[0]?.id,

package/dist/src/Toast/ToastContainer/ToastContainer.js

@@ -1,6 +1,6 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react';
 import { Toast } from '../Toast';
 import { toastSlotRecipe } from '../../../styled-system/recipes';
 import { cx } from '../../../styled-system/css';
@@ -34,6 +34,15 @@ export function ToastContainer({ items, onItemClose }) {
     const [containerHeight, setContainerHeight] = useState(0);
     const [activeElement, setActiveElement] = useState(null);
     const [isMobile, setIsMobile] = useState(false);
+    // Mirrors `firstItemRef.current` into state so `TargetDomNodeProvider` below can be
+    // given it directly, instead of reading a ref's `.current` during render (unsafe: a
+    // ref update never triggers the re-render needed to pass a fresh value to context
+    // consumers).
+    const [firstItemElement, setFirstItemElement] = useState(null);
+    const setFirstItemRef = useCallback((node) => {
+        firstItemRef.current = node;
+        setFirstItemElement(node);
+    }, []);
     // Detect viewport width for responsive CONTAINER_GAP
     useLayoutEffect(() => {
         const checkViewportWidth = () => {
@@ -114,7 +123,7 @@ export function ToastContainer({ items, onItemClose }) {
         };
     }, [items, activeElement, onItemClose]);
     const containerGap = isMobile ? CONTAINER_GAP_MOBILE : CONTAINER_GAP_DESKTOP;
-    return (_jsx(TargetDomNodeProvider, { targetDomNode: firstItemRef.current, children: _jsx("div", { style: { height: containerHeight === 0 ? 0 : `calc(${containerHeight.toString()}px + ${containerGap})` }, className: cx(classes.container, 'mfui-ToastContainer__container'), children: items.map(({ key, onClose, duration, ...props }, index) => (_jsx(Toast, { ref: [firstItemRef, secondItemRef][index] ?? null, ...props, style: {
+    return (_jsx(TargetDomNodeProvider, { targetDomNode: firstItemElement, children: _jsx("div", { style: { height: containerHeight === 0 ? 0 : `calc(${containerHeight.toString()}px + ${containerGap})` }, className: cx(classes.container, 'mfui-ToastContainer__container'), children: items.map(({ key, onClose, duration, ...props }, index) => (_jsx(Toast, { ref: [setFirstItemRef, secondItemRef][index] ?? null, ...props, style: {
                     zIndex: 1000 - index,
                 }, activeElement: activeElement, 
                 // If index is 0, set the duration to the first item. Otherwise, the duration will be `undefined`.

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

@@ -1,6 +1,6 @@
 'use client';
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { forwardRef, useId, useRef, isValidElement, cloneElement, useEffect, useMemo } from 'react';
+import { forwardRef, useId, useRef, isValidElement, cloneElement, useEffect, useMemo, useState } from 'react';
 import { getOverflowAncestors } from '@floating-ui/react-dom';
 import { cx } from '../../styled-system/css';
 import { tooltipSlotRecipe } from '../../styled-system/recipes';
@@ -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
@@ -52,9 +58,14 @@ export const Tooltip = forwardRef(({ children, open, onOpenStateChanged, content
     // Allow consumers to control the content id so an external element (e.g. a form field)
     // can reference the single accessible copy of the content via its own aria-describedby.
     const tooltipId = contentProps?.id ?? generatedId;
+    // Mirrors `rootRef.current` into state so it can be read below without reading a
+    // ref's `.current` during render (unsafe: a ref update never triggers the re-render
+    // needed to pass a fresh value onward). `rootRef` itself is kept for the effects and
+    // `useOnClickOutside` call further down, which read it safely outside of render.
+    const [rootElement, setRootElement] = useState(null);
     // Use automatic target resolution matching Portal.tsx pattern
     // Resolution order: explicit prop → parent context → document.body fallback
-    const targetElement = useAutomaticTargetDomNode(targetDOMNode, rootRef.current);
+    const targetElement = useAutomaticTargetDomNode(targetDOMNode, rootElement);
     const { open: calculatedOpen, rootAttributes, tooltipAttributes, closeImmediate, closeWithManager, } = useTooltipDisplayController({
         trigger,
         wrapperProps,
@@ -89,7 +100,7 @@ export const Tooltip = forwardRef(({ children, open, onOpenStateChanged, content
         ignoreRefs: [tooltipRef],
         disabled: !calculatedOpen || !hasClickTrigger || open !== undefined,
     });
-    const triggerRef = mergeRefs(setTriggerReference, rootRef, ref);
+    const triggerRef = mergeRefs(setTriggerReference, rootRef, setRootElement, ref);
     const classes = tooltipSlotRecipe();
     const ariaDescribedBy = !hideFromScreenReader && content != null ? tooltipId : undefined;
     return (_jsxs(_Fragment, { children: [_jsx("div", { ref: triggerRef, ...wrapperProps, className: cx(classes.root, 'mfui-Tooltip__root', className), ...rootAttributes, children: isValidElement(children) ? (cloneElement(children, ariaDescribedBy ? { 'aria-describedby': ariaDescribedBy } : undefined)) : (_jsx("span", { ...(ariaDescribedBy ? { 'aria-describedby': ariaDescribedBy } : undefined), children: children })) }), !calculatedOpen && !hideFromScreenReader && content != null && (_jsx(Portal, { targetDOMNode: targetElement, children: _jsx("div", { "data-mfui-tooltip-hidden": true, id: tooltipId, style: {