@moneyforward/mfui-components 4.3.1 → 4.6.0

package/dist/src/SubNavigation/SubNavigation.js

@@ -1,17 +1,28 @@
 import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { DisclosureBasicCollapsed, Lock } from '@moneyforward/mfui-icons-react';
+import { forwardRef, useId } from 'react';
 import { cx } from '../../styled-system/css';
 import { subNavigationSlotRecipe } from '../../styled-system/recipes';
 import { FocusIndicator } from '../FocusIndicator';
 import { Typography } from '../Typography';
 /**
  * This component is for the navigation links under the main navigation.
+ *
+ * The root element is a `<nav>` landmark. Name it with `aria-label` or `aria-labelledby` when the
+ * page has other navigation landmarks. No name is applied by default because the right name
+ * depends on what the navigation is for on each page.
+ *
+ * @example
+ * ```tsx
+ * <SubNavigation navigationItems={items} aria-label="設定" />
+ * ```
  */
-export function SubNavigation({ orientation = 'vertical', navigationItems, customLinkComponent, renderNavigationLabel, headerSlot, className, }) {
+export const SubNavigation = forwardRef(({ orientation = 'vertical', navigationItems, customLinkComponent, renderNavigationLabel, headerSlot, className, ...rest }, ref) => {
     const hasLabelIcon = navigationItems.some(({ labelIcon }) => !!labelIcon);
     const classes = subNavigationSlotRecipe({ orientation, hasLabelIcon });
-    return (_jsxs("nav", { className: cx(classes.root, 'mfui-SubNavigation__root', className), children: [headerSlot ? (_jsx("div", { className: cx(classes.subNavigationHeader, 'mfui-SubNavigation__subNavigationHeader'), children: headerSlot })) : null, _jsx("ul", { className: cx(classes.list, 'mfui-SubNavigation__list'), children: navigationItems.map((navigationItem, index) => (_jsx("li", { className: cx(classes.listItem, 'mfui-SubNavigation__listItem'), children: renderNavigationItem(navigationItem, customLinkComponent, classes, 0, renderNavigationLabel) }, index))) })] }));
-}
+    return (_jsxs("nav", { ...rest, ref: ref, className: cx(classes.root, 'mfui-SubNavigation__root', className), children: [headerSlot ? (_jsx("div", { className: cx(classes.subNavigationHeader, 'mfui-SubNavigation__subNavigationHeader'), children: headerSlot })) : null, _jsx("ul", { className: cx(classes.list, 'mfui-SubNavigation__list'), children: navigationItems.map((navigationItem, index) => (_jsx("li", { className: cx(classes.listItem, 'mfui-SubNavigation__listItem'), children: renderNavigationItem(navigationItem, customLinkComponent, classes, 0, renderNavigationLabel) }, index))) })] }));
+});
+SubNavigation.displayName = 'SubNavigation';
 /**
  * Render a navigation item based on the following conditions:
  * - a link without children
@@ -19,6 +30,7 @@ export function SubNavigation({ orientation = 'vertical', navigationItems, custo
  * - 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.
  *
@@ -33,57 +45,117 @@ export function SubNavigation({ orientation = 'vertical', navigationItems, custo
  * @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

@@ -33,6 +33,32 @@ type HorizontalSubNavigationProps = BaseSubNavigationProps & {
  * Common properties for both vertical and horizontal SubNavigation.
  */
 type BaseSubNavigationProps = {
+    /**
+     * The accessible name of the `<nav>` landmark.
+     *
+     * Set this when the page has other navigation landmarks (e.g. `MainNavigation`, `Breadcrumbs`).
+     * Describe this page's navigation (e.g. `"設定"`). Avoid including the role name;
+     * assistive technology already announces it.
+     */
+    'aria-label'?: string;
+    /**
+     * The ID of the element that names the `<nav>` landmark.
+     * Use this instead of `aria-label` when a visible heading already names the navigation.
+     *
+     * @example
+     * ```tsx
+     * function SettingsNavigation() {
+     *   const headingId = useId();
+     *   return (
+     *     <>
+     *       <h2 id={headingId}>設定</h2>
+     *       <SubNavigation navigationItems={items} aria-labelledby={headingId} />
+     *     </>
+     *   );
+     * }
+     * ```
+     */
+    'aria-labelledby'?: string;
     /**
      * The component to use as the link element instead of the general anchor element `<a>`.
      * The custom component must extend the HTMLAnchorElement interface.
@@ -50,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`
@@ -64,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
@@ -109,7 +135,7 @@ type BaseSubNavigationProps = {
      * For overriding styles if you need.
      */
     className?: string;
-};
+} & Omit<ComponentPropsWithoutRef<'nav'>, 'children' | 'className' | 'aria-label' | 'aria-labelledby'>;
 /**
  * The union that discriminates whether each navigation item has children.
  */
@@ -158,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/Tabs/hooks/useTabRegistry.js

@@ -44,14 +44,14 @@ function areTabListsEqual(a, b) {
     });
 }
 /**
- * Sorts the entries in place so they follow the order the tabs appear in the document.
+ * Returns the entries ordered by the position their elements appear in the document.
  * Entries whose element is not in the document yet keep their relative order, because
- * `Array#sort` is stable and the comparator reports them as equal.
+ * `Array#toSorted` is stable and the comparator reports them as equal.
  *
- * @param entries - The registered entries, sorted in place.
+ * @param entries - The registered entries to order.
  */
 function sortByDocumentPosition(entries) {
-    entries.sort((a, b) => {
+    return entries.toSorted((a, b) => {
         const aElement = a.elementRef.current;
         const bElement = b.elementRef.current;
         if (!aElement?.isConnected || !bElement?.isConnected)
@@ -81,7 +81,7 @@ export function useTabRegistry() {
     const entriesRef = useRef([]);
     const { registerTab, updateTab, unregisterTab } = useMemo(() => {
         const publish = () => {
-            sortByDocumentPosition(entriesRef.current);
+            entriesRef.current = sortByDocumentPosition(entriesRef.current);
             const nextTabs = entriesRef.current.map((entry) => entry.props);
             setTabs((previousTabs) => (areTabListsEqual(previousTabs, nextTabs) ? previousTabs : nextTabs));
         };

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/ToggleSwitch/index.d.ts

@@ -1,2 +1,2 @@
 export * from './ToggleSwitch';
-export * from './ToggleSwitch.types';
+export type * from './ToggleSwitch.types';

package/dist/src/ToggleSwitch/index.js

@@ -1,2 +1 @@
 export * from './ToggleSwitch';
-export * from './ToggleSwitch.types';

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: {

package/dist/src/Tooltip/hooks/useTooltipDisplayController.js

@@ -79,98 +79,87 @@ export function useTooltipDisplayController({ trigger, wrapperProps, tooltipOpen
             return updatedWrapperProps;
         if (tooltipOpen)
             return updatedWrapperProps;
-        Object.assign(updatedWrapperProps, {
-            onMouseDown: (event) => {
-                isMouseTriggered.current = true;
-                wrapperProps.onMouseDown?.(event);
-            },
-            onMouseUp: (event) => {
-                isMouseTriggered.current = false;
-                wrapperProps.onMouseUp?.(event);
-            },
-            onKeyDown: (event) => {
-                if (event.key === 'Enter' && open) {
-                    closeWithManager();
-                }
-                wrapperProps.onKeyDown?.(event);
-            },
-        });
+        // Assigned directly (not via `Object.assign`) so the compiler can see these
+        // ref-closing handlers are only ever stored as props, never invoked here.
+        updatedWrapperProps.onMouseDown = (event) => {
+            isMouseTriggered.current = true;
+            wrapperProps.onMouseDown?.(event);
+        };
+        updatedWrapperProps.onMouseUp = (event) => {
+            isMouseTriggered.current = false;
+            wrapperProps.onMouseUp?.(event);
+        };
+        updatedWrapperProps.onKeyDown = (event) => {
+            if (event.key === 'Enter' && open) {
+                closeWithManager();
+            }
+            wrapperProps.onKeyDown?.(event);
+        };
         if (triggers.includes('hover')) {
-            Object.assign(updatedWrapperProps, {
-                onMouseEnter: (event) => {
-                    if (!isEventFromTrigger(event))
-                        return;
-                    triggerSource.current = 'hover';
-                    isHoveringTrigger.current = true;
-                    cancelClose(); // Cancel any pending close
-                    openWithManager('delayed');
-                    wrapperProps.onMouseEnter?.(event);
-                },
-                onMouseLeave: (event) => {
-                    if (triggerSource.current !== 'hover')
-                        return;
-                    if (!isEventFromTrigger(event))
-                        return;
-                    isHoveringTrigger.current = false;
-                    // Only start close timer if also not hovering tooltip
-                    // Use queueMicrotask to avoid race conditions with rapid mouse events
-                    queueMicrotask(() => {
-                        closeWithDelayIfNotHovering();
-                    });
-                    wrapperProps.onMouseLeave?.(event);
-                },
-            });
-        }
-        if (triggers.includes('click')) {
-            Object.assign(updatedWrapperProps, {
-                onClick: (event) => {
-                    if (!isEventFromTrigger(event))
-                        return;
-                    if (!open) {
-                        triggerSource.current = 'click';
-                        openWithManager('immediate');
-                    }
-                    else {
-                        closeWithManager();
-                    }
-                    wrapperProps.onClick?.(event);
-                },
-            });
-        }
-        else {
-            // When click is not a trigger, clicking should close the tooltip if it's open
-            Object.assign(updatedWrapperProps, {
-                onClick: (event) => {
-                    if (!isEventFromTrigger(event))
-                        return;
-                    if (open) {
-                        closeWithManager();
-                    }
-                    wrapperProps.onClick?.(event);
-                },
-            });
+            updatedWrapperProps.onMouseEnter = (event) => {
+                if (!isEventFromTrigger(event))
+                    return;
+                triggerSource.current = 'hover';
+                isHoveringTrigger.current = true;
+                cancelClose(); // Cancel any pending close
+                openWithManager('delayed');
+                wrapperProps.onMouseEnter?.(event);
+            };
+            updatedWrapperProps.onMouseLeave = (event) => {
+                if (triggerSource.current !== 'hover')
+                    return;
+                if (!isEventFromTrigger(event))
+                    return;
+                isHoveringTrigger.current = false;
+                // Only start close timer if also not hovering tooltip
+                // Use queueMicrotask to avoid race conditions with rapid mouse events
+                queueMicrotask(() => {
+                    closeWithDelayIfNotHovering();
+                });
+                wrapperProps.onMouseLeave?.(event);
+            };
         }
-        if (triggers.includes('focus')) {
-            Object.assign(updatedWrapperProps, {
-                onFocus: (event) => {
-                    if (!isEventFromTrigger(event))
-                        return;
-                    // onFocus event is triggered before onClick event when the mouse is clicked, so we need to skip it
-                    if (isMouseTriggered.current)
-                        return;
-                    triggerSource.current = 'focus';
+        // When click is not a trigger, clicking should still close the tooltip if it's open.
+        updatedWrapperProps.onClick = triggers.includes('click')
+            ? (event) => {
+                if (!isEventFromTrigger(event))
+                    return;
+                if (!open) {
+                    triggerSource.current = 'click';
                     openWithManager('immediate');
-                    wrapperProps.onFocus?.(event);
-                },
-                onBlur: (event) => {
-                    if (triggerSource.current !== 'focus')
-                        return;
-                    if (!isEventFromTrigger(event))
-                        return;
+                }
+                else {
                     closeWithManager();
-                    wrapperProps.onBlur?.(event);
-                },
-            });
+                }
+                wrapperProps.onClick?.(event);
+            }
+            : (event) => {
+                if (!isEventFromTrigger(event))
+                    return;
+                if (open) {
+                    closeWithManager();
+                }
+                wrapperProps.onClick?.(event);
+            };
+        if (triggers.includes('focus')) {
+            updatedWrapperProps.onFocus = (event) => {
+                if (!isEventFromTrigger(event))
+                    return;
+                // onFocus event is triggered before onClick event when the mouse is clicked, so we need to skip it
+                if (isMouseTriggered.current)
+                    return;
+                triggerSource.current = 'focus';
+                openWithManager('immediate');
+                wrapperProps.onFocus?.(event);
+            };
+            updatedWrapperProps.onBlur = (event) => {
+                if (triggerSource.current !== 'focus')
+                    return;
+                if (!isEventFromTrigger(event))
+                    return;
+                closeWithManager();
+                wrapperProps.onBlur?.(event);
+            };
         }
         return updatedWrapperProps;
     }, [