@moneyforward/mfui-components 4.5.0 → 4.6.0

package/dist/src/NumberBox/NumberBox.js

@@ -1,6 +1,6 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { forwardRef, useCallback, useEffect, useLayoutEffect, useReducer, useRef, useState } from 'react';
+import { forwardRef, useCallback, useLayoutEffect, useReducer, useRef, useState } from 'react';
 import { cx } from '../../styled-system/css';
 import { mergeRefs } from '../utilities/dom/mergeRefs';
 import { TextBox } from '../TextBox';
@@ -149,13 +149,17 @@ export const NumberBox = forwardRef(({ onChange, value, defaultValue, textAlign
     const pendingCursorRef = useRef(null);
     const [cursorRestoreToken, requestCursorRestore] = useReducer((count) => count + 1, 0);
     const [displayValue, setDisplayValue] = useState(() => formatWithCommas(sanitizeInput(String(value ?? defaultValue ?? ''))));
-    // Sync with controlled value
-    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 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) {
             const sanitized = sanitizeInput(String(value));
             setDisplayValue(formatWithCommas(sanitized));
         }
-    }, [value]);
+    }
     // Restore cursor position after display value update
     useLayoutEffect(() => {
         if (pendingCursorRef.current !== null && inputRef.current) {

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

@@ -47,7 +47,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 +63,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);

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

@@ -30,9 +30,15 @@ export function useKeyboardNavigation({ isOptionPanelOpen, loading, enableSearch
         return selectedIndex !== -1 ? selectedIndex : 0;
     }, [flatOptions, localSelectedOption]);
     const [tabbableOptionIndex, setTabbableOptionIndex] = useState(getDefaultTabbableIndex());
-    useEffect(() => {
+    // 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());
-    }, [getDefaultTabbableIndex]);
+    }
     const resetTabbableIndex = useCallback(() => {
         setTabbableOptionIndex(getDefaultTabbableIndex());
     }, [getDefaultTabbableIndex]);

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.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';
@@ -52,9 +52,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 +94,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: {