@moneyforward/mfui-components 4.9.0 → 4.10.1

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

@@ -13,6 +13,23 @@ export type DialogProps = {
      * inline text, status indicators, or icons — because the dialog uses
      * `aria-labelledby` to announce the title and screen readers will read the
      * entire subtree. Avoid placing interactive controls inside `title`.
+     * Note that `<Skeleton />` is hidden from assistive technologies, so a
+     * Skeleton-only title contributes nothing to the dialog's accessible name.
+     * Pair it with `<VisuallyHidden>` text to give the dialog an accessible name.
+     *
+     * @example
+     * ```tsx
+     * <Dialog
+     *   title={
+     *     <>
+     *       <VisuallyHidden>Loading title</VisuallyHidden>
+     *       <span style={{ display: 'inline-block', width: '240px', height: '24px' }}>
+     *         <Skeleton />
+     *       </span>
+     *     </>
+     *   }
+     * />
+     * ```
      */
     title: ReactNode;
     /**

package/dist/src/FileDropZone/FileDropZone.js

@@ -75,6 +75,8 @@ fileSelectButtonLabel = 'ファイルを選択', instructionText, fileCountLabel
     const buttonRef = useRef(null);
     const previousValueRef = useRef(value);
     const isUserInitiatedClearRef = useRef(false);
+    // Counts nested dragenter/dragleave pairs so moving over descendants does not drop the highlight
+    const dragDepthRef = useRef(0);
     const displayValues = isControlled ? value : internalValues;
     const errorMessages = (Array.isArray(errorMessage) ? errorMessage : [errorMessage]).filter((message) => Boolean(message));
     const fileBoxMaxWidthStyle = { maxWidth: fileBoxWidth };
@@ -141,25 +143,38 @@ fileSelectButtonLabel = 'ファイルを選択', instructionText, fileCountLabel
         if (isControlled) {
             resetFileInput();
         }
+        dragDepthRef.current = 0;
         setIsDragging(false);
     }, [isControlled, onChange, resetFileInput]);
     const handleDragEnter = useCallback((event) => {
         event.preventDefault();
         event.stopPropagation();
+        dragDepthRef.current += 1;
         setIsDragging(true);
     }, []);
     const handleDragLeave = useCallback((event) => {
         event.preventDefault();
         event.stopPropagation();
-        setIsDragging(false);
+        /*
+         * `dragleave` also bubbles up from descendants, and moving into a child fires its `dragenter`
+         * before the container's `dragleave`. Only clear the highlight once every entered element has
+         * been left, so it stays applied for as long as the pointer is inside the drop zone.
+         */
+        dragDepthRef.current = Math.max(0, dragDepthRef.current - 1);
+        if (dragDepthRef.current === 0) {
+            setIsDragging(false);
+        }
     }, []);
     const handleDragOver = useCallback((event) => {
         event.preventDefault();
         event.stopPropagation();
-    }, []);
+        // eslint-disable-next-line no-param-reassign -- Setting the drop effect on the event is how the copy cursor is requested
+        event.dataTransfer.dropEffect = disabled ? 'none' : 'copy';
+    }, [disabled]);
     const handleDrop = useCallback((event) => {
         event.preventDefault();
         event.stopPropagation();
+        dragDepthRef.current = 0;
         setIsDragging(false);
         if (disabled) {
             return;
@@ -210,11 +225,13 @@ fileSelectButtonLabel = 'ファイルを選択', instructionText, fileCountLabel
         }
     }, [disabled]);
     const handleContainerClick = useCallback((event) => {
-        // Only trigger file input if clicking directly on the container
-        // and not on interactive elements within it
-        if (event.target === event.currentTarget) {
-            handleFileInputTrigger();
+        // A click anywhere in the drop zone opens the file dialog, except on the buttons
+        // and the `extraElement` content, which handle their own clicks
+        const target = event.target;
+        if (target.closest('button, [data-mfui-content="file-drop-zone-extra"]')) {
+            return;
         }
+        handleFileInputTrigger();
     }, [handleFileInputTrigger]);
     const renderDisplayValues = useMemo(() => {
         if (displayValues !== undefined && displayValues.length > 0) {

package/dist/src/Popover/Popover.d.ts

@@ -13,4 +13,4 @@ import { type PopoverProps } from './Popover.types';
  * 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.
  */
-export declare function Popover({ renderTrigger, renderContent, open, onOpenStateChanged, onOpen, onClose, enableAutoFocusOnTrigger, enableAutoFocusOnPopover, minWidth, maxHeight, enableConstrainedContentWidth, contentProps, targetDOMNode, enableAutoUnmount, onBlur, allowedPlacements, enableViewportConstraint, enableAutomaticPortalTargetResolution, enableCenteredLayoutOnNarrowViewport, }: PopoverProps): import("react/jsx-runtime").JSX.Element;
+export declare function Popover({ renderTrigger, renderContent, open, onOpenStateChanged, onOpen, onClose, enableAutoFocusOnTrigger, returnFocusRef, enableAutoFocusOnPopover, minWidth, maxHeight, enableConstrainedContentWidth, contentProps, targetDOMNode, enableAutoUnmount, onBlur, allowedPlacements, enableViewportConstraint, enableAutomaticPortalTargetResolution, enableCenteredLayoutOnNarrowViewport, }: PopoverProps): import("react/jsx-runtime").JSX.Element;

package/dist/src/Popover/Popover.js

@@ -8,6 +8,7 @@ import { useDisclosure } from '../utilities/state/useDisclosure';
 import { Portal, TargetDomNodeProvider, useAutomaticTargetDomNode } from '../Portal';
 import { useOnClickOutside } from '../utilities/dom/useOnClickOutside';
 import { getRootNode } from '../utilities/dom/getRootNode';
+import { getDeepActiveElement } from '../utilities/dom/getDeepActiveElement';
 import { getTargetDomNode } from '../utilities/dom/getTargetDomNode';
 import { popoverSlotRecipe } from '../../styled-system/recipes';
 import { useUpdateEffect } from '../utilities/effect/useUpdateEffect';
@@ -26,9 +27,11 @@ import { cx } from '../../styled-system/css';
  * 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.
  */
-export function Popover({ renderTrigger, renderContent, open, onOpenStateChanged, onOpen, onClose, enableAutoFocusOnTrigger = true, enableAutoFocusOnPopover = true, minWidth, maxHeight, enableConstrainedContentWidth = false, contentProps = {}, targetDOMNode, enableAutoUnmount = true, onBlur, allowedPlacements, enableViewportConstraint = true, enableAutomaticPortalTargetResolution = false, enableCenteredLayoutOnNarrowViewport = false, }) {
-    // Toggle event is the event triggered by open / close the Popover
-    const [toggleEvent, setToggleEvent] = useState();
+export function Popover({ renderTrigger, renderContent, open, onOpenStateChanged, onOpen, onClose, enableAutoFocusOnTrigger = true, returnFocusRef, enableAutoFocusOnPopover = true, minWidth, maxHeight, enableConstrainedContentWidth = false, contentProps = {}, targetDOMNode, enableAutoUnmount = true, onBlur, allowedPlacements, enableViewportConstraint = true, enableAutomaticPortalTargetResolution = false, enableCenteredLayoutOnNarrowViewport = false, }) {
+    // The last open / close request made by the Popover itself: the next open state, its event, and,
+    // for Escape and click outside, how it closed. Read once by the open / close effect below.
+    const [pendingChange, setPendingChange] = useState(null);
+    const usedChangeRef = useRef(null);
     const { isOpen: localIsOpen, toggle: localToggle, open: localOpen, close: localClose, } = useDisclosure({
         value: open,
         onToggle: onOpenStateChanged,
@@ -56,6 +59,82 @@ export function Popover({ renderTrigger, renderContent, open, onOpenStateChanged
         refs.setFloating(node);
         setFloatingElement(node);
     }, [refs]);
+    /*
+     * MEMO: How focus returns to the trigger when the Popover closes
+     *
+     * Popover follows the rules of the native HTML popover:
+     * - After a click outside, focus does not return. The user has moved on to something else, so
+     *   focus is left where the browser put it.
+     * - After Escape, focus returns. Popover's own Escape handler calls `preventDefault()`, which
+     *   would otherwise skip the return, so Escape is tracked separately.
+     * - Focus returns only if it was still inside the Popover, or was lost when the Popover was
+     *   removed. A Popover closed by its parent never takes focus away from where the user is.
+     * - Returning focus does not scroll the page.
+     * Components whose trigger button is not the reference element (the Filter pickers) pass that
+     * button as `returnFocusRef`.
+     * Before, focus always returned to the trigger, except after Escape. Because `focus()` scrolls to
+     * the element by default, a popover that was open lower on the page pulled the page down to its
+     * trigger when the user clicked anywhere else (e.g. the Popover docs page, where `WithMaxHeight`
+     * starts open).
+     *
+     * Options evaluated:
+     * - A. Fix only the story that starts open: one line, but products can hit the same jump.
+     * - B. Hide that story from the docs page: hides the problem instead of fixing it.
+     * - C. (picked) Follow the native popover rules above: fixes the cause for every component in
+     *   one place and matches the HTML standard, Radix and the WAI-ARIA APG (Escape returns focus to
+     *   the menu button or the element that opened the dialog). It changes visible focus behavior:
+     *   no focus after a click outside, and focus after Escape.
+     * - C2. Pass a close reason to `onClose` and let each component decide: works, but adds public
+     *   API and repeats the same rule in menus, pickers and DataTableFilterButton.
+     * - D. Return focus with `preventScroll: true` only: no jump, but focus is still taken away from
+     *   what the user clicked, which the HTML standard does not do.
+     * - E. Rebuild Popover on the native `popover` attribute: the browser handles outside clicks,
+     *   Escape, focus, and stacking itself. Not done yet, see the TODO below.
+     * - F. Native `popover` plus CSS anchor positioning: no positioning library at all, but too
+     *   early (Baseline since January 2026, still partial support in Chrome and Firefox).
+     *
+     * C is the safest fix today, and it already behaves like E, so it does not block E later.
+     *
+     * TODO: Rebuild Popover on the native `popover` attribute (option E)
+     * - Scope: Popover, `useOnClickOutside`, `usePopoverMenuPlacement`, and the Portal helpers
+     *   (around 900 lines), the 12 components built on Popover, and the 22 components that expose
+     *   `targetDOMNode`, which the top layer makes mostly unnecessary (deprecate, then remove in
+     *   a major version).
+     * - Blockers: jsdom does not implement the Popover API (jsdom/jsdom#3721, open since May 2024),
+     *   so tests need a stub or a real browser runner. Top-layer stacking changes the order
+     *   documented in `docs/Layering.mdx`. MFUI has no written browser support policy yet.
+     * - Timing: Popover API is Baseline "newly available" since January 2025, so "widely
+     *   available" (30 months later) from around July 2027. `@floating-ui/dom` already detects
+     *   `:popover-open` elements, so positioning can stay on Floating UI.
+     * - Order: test setup -> Popover core with the same public API -> components and docs ->
+     *   deprecate `targetDOMNode`.
+     *
+     * Resources checked (October 2026):
+     * - HTML Standard, popover light dismiss and the hide popover algorithm: https://html.spec.whatwg.org/multipage/popover.html
+     * - HTML Standard, `activeElement` and focus fixup: https://html.spec.whatwg.org/multipage/interaction.html
+     * - WAI-ARIA APG, Menu pattern (Escape): https://www.w3.org/WAI/ARIA/apg/patterns/menubar/
+     * - WAI-ARIA APG, Dialog pattern (focus on close): https://www.w3.org/WAI/ARIA/apg/patterns/dialog-modal/
+     * - MDN, HTMLElement.focus() `preventScroll`: https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/focus
+     * - MDN, button click focus (Safari does not focus on click): https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/button
+     * - Radix Popover (`hasInteractedOutsideRef`): https://github.com/radix-ui/primitives/blob/main/packages/react/popover/src/popover.tsx
+     * - Floating UI FloatingFocusManager `returnFocus`: https://floating-ui.com/docs/FloatingFocusManager
+     * - Base UI Popover `finalFocus`: https://base-ui.com/react/components/popover
+     * - MDN, Popover API Baseline: https://developer.mozilla.org/en-US/docs/Web/API/Popover_API
+     * - MDN, anchor-name Baseline: https://developer.mozilla.org/en-US/docs/Web/CSS/Reference/Properties/anchor-name
+     * - Can I use, CSS anchor positioning: https://caniuse.com/css-anchor-positioning
+     * - web.dev, Baseline definitions: https://web.dev/baseline
+     * - jsdom Popover API issue: https://github.com/jsdom/jsdom/issues/3721
+     */
+    // Whether focus is still inside the Popover, or was lost to the body when the Popover was
+    // removed. Shadow DOM aware: looks through shadow roots for the element that really has focus,
+    // so it also works when the content is not in the same shadow tree as the trigger.
+    const isFocusInsideOrLost = useCallback(() => {
+        const ownerDocument = refs.reference.current?.ownerDocument ?? document;
+        const activeElement = getDeepActiveElement(ownerDocument);
+        if (!activeElement || activeElement === ownerDocument.body)
+            return true;
+        return !!refs.floating.current?.contains(activeElement);
+    }, [refs.reference, refs.floating]);
     // 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
@@ -63,6 +142,14 @@ export function Popover({ renderTrigger, renderContent, open, onOpenStateChanged
     const previousOpenRef = useRef(localIsOpen);
     useUpdateEffect(() => {
         const wasOpen = previousOpenRef.current;
+        // Use the request only once, and only for the change it asked for. Any other change comes from the
+        // `open` prop, so a later change never reuses an old event (e.g. a prevented Escape).
+        const change = pendingChange && pendingChange !== usedChangeRef.current && pendingChange.nextOpen === localIsOpen
+            ? pendingChange
+            : null;
+        usedChangeRef.current = pendingChange;
+        const toggleEvent = change?.event;
+        const closeSource = change?.source;
         if (!wasOpen && localIsOpen) {
             // Transition: closed -> open
             onOpen?.(toggleEvent);
@@ -73,20 +160,32 @@ export function Popover({ renderTrigger, renderContent, open, onOpenStateChanged
         else if (wasOpen && !localIsOpen) {
             // Transition: open -> closed
             onClose?.(toggleEvent);
-            if (!toggleEvent?.defaultPrevented && enableAutoFocusOnTrigger) {
-                refs.reference.current?.focus();
+            if (enableAutoFocusOnTrigger &&
+                closeSource !== 'outside-press' &&
+                (closeSource === 'escape-key' || !toggleEvent?.defaultPrevented) &&
+                isFocusInsideOrLost()) {
+                // Like the native popover, returning focus does not scroll the page.
+                (returnFocusRef?.current ?? refs.reference.current)?.focus({ preventScroll: true });
             }
         }
         // Update tracker for next invocation
         previousOpenRef.current = localIsOpen;
-    }, [localIsOpen, onOpen, onClose, enableAutoFocusOnPopover, enableAutoFocusOnTrigger]);
+    }, [
+        localIsOpen,
+        onOpen,
+        onClose,
+        enableAutoFocusOnPopover,
+        enableAutoFocusOnTrigger,
+        isFocusInsideOrLost,
+        returnFocusRef,
+    ]);
     const handleKeyDownTrigger = useCallback((event) => {
         switch (event.key) {
             case 'ArrowDown':
             case 'ArrowUp':
                 event.stopPropagation();
                 event.preventDefault();
-                setToggleEvent(event);
+                setPendingChange({ nextOpen: true, event });
                 localOpen();
                 break;
         }
@@ -96,7 +195,7 @@ export function Popover({ renderTrigger, renderContent, open, onOpenStateChanged
             case 'Escape':
                 event.stopPropagation();
                 event.preventDefault();
-                setToggleEvent(event);
+                setPendingChange({ nextOpen: false, event, source: 'escape-key' });
                 localClose();
                 break;
         }
@@ -155,7 +254,7 @@ export function Popover({ renderTrigger, renderContent, open, onOpenStateChanged
     }, [onBlur, refs.reference, refs.floating]);
     // Close the menu when clicking outside the menu
     useOnClickOutside(refs.floating, (event) => {
-        setToggleEvent(undefined);
+        setPendingChange({ nextOpen: false, source: 'outside-press' });
         localClose();
         // Also trigger onBlur when clicking outside, since this represents the user
         // clicking away from the component entirely. We create a synthetic FocusEvent
@@ -170,18 +269,23 @@ export function Popover({ renderTrigger, renderContent, open, onOpenStateChanged
             timeStamp: event.timeStamp,
             nativeEvent: event,
         });
-    }, { ignoreRefs: [refs.reference] });
+    }, 
+    // A closed Popover ignores clicks outside, like the native popover's light dismiss. Without this,
+    // a closed Popover kept mounted by `enableAutoUnmount={false}` reported a close and a blur on every click.
+    // Uses the shown state (`open` first), so a Popover kept open by a parent that refused a close still
+    // asks again on the next click outside.
+    { ignoreRefs: [refs.reference], disabled: !(open ?? localIsOpen) });
     const options = useMemo(() => {
         const toggle = (event) => {
-            setToggleEvent(event);
+            setPendingChange({ nextOpen: !localIsOpen, event });
             localToggle();
         };
         const open = (event) => {
-            setToggleEvent(event);
+            setPendingChange({ nextOpen: true, event });
             localOpen();
         };
         const close = (event) => {
-            setToggleEvent(event);
+            setPendingChange({ nextOpen: false, event });
             localClose();
         };
         return {
@@ -272,5 +376,5 @@ export function Popover({ renderTrigger, renderContent, open, onOpenStateChanged
     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: floatingElement, children: _jsx(PopoverContextProvider, { children: renderContent(options) }) }) }) })) : null] }));
+                    }, onKeyDown: handleKeyDownPopover, children: _jsx(TargetDomNodeProvider, { targetDomNode: floatingElement, children: _jsx("div", { className: cx(classes.contentWrapper, 'mfui-Popover__contentWrapper'), children: _jsx(PopoverContextProvider, { children: renderContent(options) }) }) }) }) })) : null] }));
 }

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

@@ -1,4 +1,4 @@
-import { type ComponentProps, type CSSProperties, type KeyboardEventHandler, type ReactNode, type SyntheticEvent, type FocusEventHandler } from 'react';
+import { type ComponentProps, type CSSProperties, type KeyboardEventHandler, type ReactNode, type RefObject, type SyntheticEvent, type FocusEventHandler } from 'react';
 type Side = 'top' | 'right' | 'bottom' | 'left';
 type Alignment = 'start' | 'end';
 /**
@@ -102,8 +102,10 @@ export type PopoverProps = {
     onOpen?: (event?: SyntheticEvent) => void;
     /**
      * This callback function will be called with the Popover closed.
-     * The default action is focusing on the Trigger.
-     * You can prevent that action by using `event.preventDefault()` in the callback function.
+     * The default action is focusing on the Trigger, like the native HTML popover: not after a click outside, and only
+     * when focus is still inside the Popover. Focusing does not scroll the page.
+     * You can prevent that action by using `event.preventDefault()` in the callback function, except after Escape.
+     * To never return focus, use `enableAutoFocusOnTrigger={false}`.
      *
      * @param event - The trigger event which makes the Popover close, this param can be undefined if you use `toggle` or
      * `close` without passing the event parameter. If you don't pass the event, you can't prevent the default action.
@@ -115,6 +117,17 @@ export type PopoverProps = {
      * @default true - By default, it will automatically focus on the trigger element when the Popover closes.
      */
     enableAutoFocusOnTrigger?: boolean;
+    /**
+     * The element to return focus to when the Popover closes, instead of the Trigger.
+     * Use it when the element registered by `setTriggerRef` is not the button that opens the Popover.
+     *
+     * This prop is intended for internal MFUI components like the Filter pickers.
+     *
+     * @internal
+     *
+     * @default undefined
+     */
+    returnFocusRef?: RefObject<HTMLElement | null>;
     /**
      * The flag to enable or disable autofocus on the popover element when the Popover opens.
      *

package/dist/src/SectionMessage/SectionMessage.d.ts

@@ -4,6 +4,12 @@
  *
  * This component switches the variants of looks depends on the props `messageType` and `region`.
  *
+ * The wrapper is a live region whose urgency follows `messageType`:
+ * - `error`: sets `role="alert"` — announces immediately to screen readers.
+ * - `neutral` / `info` / `success` / `caution` / `busy` / `progress`: set `role="status"` — announces politely when the user is idle.
+ *
+ * A `role` or `aria-live` passed via props takes precedence over these defaults.
+ *
  * Also extends the props of `<div>` element (the wrapper).
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div

package/dist/src/SectionMessage/SectionMessage.js

@@ -6,12 +6,27 @@ import { sectionMessageSlotRecipe } from '../../styled-system/recipes';
 import { IconButton } from '../IconButton';
 import { ProgressIndicator } from '../ProgressIndicator';
 import { Typography } from '../Typography';
+const messageTypeRoleMap = {
+    neutral: 'status',
+    info: 'status',
+    success: 'status',
+    error: 'alert',
+    caution: 'status',
+    busy: 'status',
+    progress: 'status',
+};
 /**
  * The SectionMessage component is used to display an inline message inside a page or some container.
  * Note: We changed the name of the component from `InlineMessage` to `SectionMessage`.
  *
  * This component switches the variants of looks depends on the props `messageType` and `region`.
  *
+ * The wrapper is a live region whose urgency follows `messageType`:
+ * - `error`: sets `role="alert"` — announces immediately to screen readers.
+ * - `neutral` / `info` / `success` / `caution` / `busy` / `progress`: set `role="status"` — announces politely when the user is idle.
+ *
+ * A `role` or `aria-live` passed via props takes precedence over these defaults.
+ *
  * Also extends the props of `<div>` element (the wrapper).
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/div
@@ -36,5 +51,5 @@ export const SectionMessage = forwardRef(({ messageType = 'neutral', region = 'i
         progress: (_jsx(ProgressIndicator, { ...statusIconA11yProps, className: cx(classes.statusIcon, 'mfui-SectionMessage__statusIcon') })),
     }[messageType];
     const contentIsString = typeof children === 'string';
-    return (_jsxs("div", { ref: ref, className: cx(classes.root, 'mfui-SectionMessage__root', className), ...props, role: "alert", children: [_jsxs("div", { className: cx(classes.topSection, 'mfui-SectionMessage__topSection'), children: [_jsxs("div", { className: cx(classes.content, 'mfui-SectionMessage__content'), children: [StatusIcon, contentIsString ? _jsx(Typography, { variant: "body", children: children }) : children] }), _jsxs("div", { className: cx(classes.rightSection, 'mfui-SectionMessage__rightSection'), children: [_jsx("div", { className: cx(classes.actionSlot, classes.desktopActionSlot, 'mfui-SectionMessage__actionSlot'), "data-mfui-content": "SectionMessage-action-slot-desktop", children: actionSlot }), onClose ? (_jsx(IconButton, { "aria-label": closeButtonProps?.['aria-label'] ?? '閉じる', onClick: onClose, children: _jsx(Close, { "aria-hidden": true, className: cx(classes.closeIcon, 'mfui-SectionMessage__closeIcon') }) })) : null] })] }), actionSlot && !disableResponsive ? (_jsx("div", { className: cx(classes.actionSlot, classes.mobileActionSlot, 'mfui-SectionMessage__actionSlot'), "data-mfui-content": "SectionMessage-action-slot-mobile", children: actionSlot })) : null] }));
+    return (_jsxs("div", { ref: ref, role: messageTypeRoleMap[messageType], className: cx(classes.root, 'mfui-SectionMessage__root', className), ...props, children: [_jsxs("div", { className: cx(classes.topSection, 'mfui-SectionMessage__topSection'), children: [_jsxs("div", { className: cx(classes.content, 'mfui-SectionMessage__content'), children: [StatusIcon, contentIsString ? _jsx(Typography, { variant: "body", children: children }) : children] }), _jsxs("div", { className: cx(classes.rightSection, 'mfui-SectionMessage__rightSection'), children: [_jsx("div", { className: cx(classes.actionSlot, classes.desktopActionSlot, 'mfui-SectionMessage__actionSlot'), "data-mfui-content": "SectionMessage-action-slot-desktop", children: actionSlot }), onClose ? (_jsx(IconButton, { "aria-label": closeButtonProps?.['aria-label'] ?? '閉じる', onClick: onClose, children: _jsx(Close, { "aria-hidden": true, className: cx(classes.closeIcon, 'mfui-SectionMessage__closeIcon') }) })) : null] })] }), actionSlot && !disableResponsive ? (_jsx("div", { className: cx(classes.actionSlot, classes.mobileActionSlot, 'mfui-SectionMessage__actionSlot'), "data-mfui-content": "SectionMessage-action-slot-mobile", children: actionSlot })) : null] }));
 });

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

@@ -9,6 +9,10 @@ export type SectionMessageProps = {
     /**
      * The type of the message
      *
+     * It also determines the live-region role of the wrapper:
+     * `error` sets `role="alert"` (assertive), and every other type sets `role="status"` (polite).
+     * Pass `role` or `aria-live` to override this default.
+     *
      * @default 'neutral'
      */
     messageType?: SectionMessageSlotRecipeVariant['messageType'];

package/dist/src/Skeleton/Skeleton.d.ts

@@ -1,5 +1,8 @@
-import { type SkeletonProps } from './Skeleton.types';
 /**
  * The Skeleton component is used to indicate loading state of content before the data gets loaded.
+ *
+ * The root element is decorative and hidden from assistive technologies with `aria-hidden="true"` by default.
  */
-export declare const Skeleton: import("react").ForwardRefExoticComponent<SkeletonProps & import("react").RefAttributes<HTMLDivElement>>;
+export declare const Skeleton: import("react").ForwardRefExoticComponent<{
+    className?: string;
+} & Omit<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLDivElement>, HTMLDivElement>, "ref">, "children"> & import("react").RefAttributes<HTMLDivElement>>;

package/dist/src/Skeleton/Skeleton.js

@@ -4,8 +4,11 @@ import { cx } from '../../styled-system/css';
 import { skeletonSlotRecipe } from '../../styled-system/recipes';
 /**
  * The Skeleton component is used to indicate loading state of content before the data gets loaded.
+ *
+ * The root element is decorative and hidden from assistive technologies with `aria-hidden="true"` by default.
  */
-export const Skeleton = forwardRef(({ className }, ref) => {
+export const Skeleton = forwardRef(({ className, ...props }, ref) => {
     const classes = skeletonSlotRecipe();
-    return _jsx("div", { ref: ref, className: cx(classes.root, 'mfui-Skeleton__root', className) });
+    // `aria-hidden` is placed before the spread so that consumers can override it.
+    return _jsx("div", { ref: ref, "aria-hidden": "true", className: cx(classes.root, 'mfui-Skeleton__root', className), ...props });
 });

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

@@ -1,9 +1,17 @@
+import { type ComponentPropsWithoutRef } from 'react';
 /**
  * The props for the Skeleton component.
+ *
+ * The root element is decorative and is rendered with `aria-hidden="true"` by default, so it is
+ * omitted from the accessibility tree. Expose the loading state on a surrounding element instead
+ * (e.g. `role="status"` with visually hidden text, or `aria-busy`).
+ * Pass `aria-hidden={false}` to override the default.
+ *
+ * `children` is not accepted because the root is hidden from assistive technologies.
  */
 export type SkeletonProps = {
     /**
      * The additional class name for the root element.
      */
     className?: string;
-};
+} & Omit<ComponentPropsWithoutRef<'div'>, 'children'>;

package/dist/src/VisuallyHidden/VisuallyHidden.d.ts

@@ -0,0 +1,17 @@
+/**
+ * The VisuallyHidden component hides its content visually while keeping it available to assistive technologies.
+ *
+ * Use it to provide text for screen readers that is not shown on screen, for example an accessible name
+ * for a heading that only renders a `<Skeleton />` while loading.
+ * Use it instead of `aria-label` on role-less elements such as `<span>` or `<div>`, where `aria-label` is prohibited.
+ *
+ * Do not combine it with `aria-hidden` or `display: none`, because that removes the content from the accessibility tree.
+ *
+ * Also extends the props of `<span>` element.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span
+ */
+export declare const VisuallyHidden: import("react").ForwardRefExoticComponent<{
+    children?: import("react").ReactNode;
+    className?: string;
+} & Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLSpanElement>, HTMLSpanElement>, "ref"> & import("react").RefAttributes<HTMLSpanElement>>;

package/dist/src/VisuallyHidden/VisuallyHidden.js

@@ -0,0 +1,21 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { forwardRef } from 'react';
+import { cx } from '../../styled-system/css';
+import { visuallyHiddenSlotRecipe } from '../../styled-system/recipes';
+/**
+ * The VisuallyHidden component hides its content visually while keeping it available to assistive technologies.
+ *
+ * Use it to provide text for screen readers that is not shown on screen, for example an accessible name
+ * for a heading that only renders a `<Skeleton />` while loading.
+ * Use it instead of `aria-label` on role-less elements such as `<span>` or `<div>`, where `aria-label` is prohibited.
+ *
+ * Do not combine it with `aria-hidden` or `display: none`, because that removes the content from the accessibility tree.
+ *
+ * Also extends the props of `<span>` element.
+ *
+ * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/span
+ */
+export const VisuallyHidden = forwardRef(({ className, children, ...props }, ref) => {
+    const classes = visuallyHiddenSlotRecipe();
+    return (_jsx("span", { ref: ref, className: cx(classes.root, 'mfui-VisuallyHidden__root', className), ...props, children: children }));
+});

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

@@ -0,0 +1,19 @@
+import { type ComponentPropsWithoutRef, type ReactNode } from 'react';
+/**
+ * The props for the VisuallyHidden component.
+ *
+ * Also extends the props of `<span>` element.
+ */
+export type VisuallyHiddenProps = {
+    /**
+     * The content that is hidden visually but still exposed to assistive technologies.
+     *
+     * Keep it to non-interactive content such as text. Focusable elements would receive keyboard
+     * focus while staying invisible, which confuses sighted keyboard users.
+     */
+    children?: ReactNode;
+    /**
+     * The additional class name for the root element.
+     */
+    className?: string;
+} & ComponentPropsWithoutRef<'span'>;

package/dist/src/VisuallyHidden/VisuallyHidden.types.js

@@ -0,0 +1 @@
+export {};

package/dist/src/VisuallyHidden/index.d.ts

@@ -0,0 +1,2 @@
+export { VisuallyHidden } from './VisuallyHidden';
+export type { VisuallyHiddenProps } from './VisuallyHidden.types';

package/dist/src/VisuallyHidden/index.js

@@ -0,0 +1 @@
+export { VisuallyHidden } from './VisuallyHidden';

package/dist/src/index.d.ts

@@ -61,3 +61,4 @@ export * from './Toast';
 export * from './ToggleSwitch';
 export * from './Tooltip';
 export * from './Typography';
+export * from './VisuallyHidden';

package/dist/src/index.js

@@ -61,3 +61,4 @@ export * from './Toast';
 export * from './ToggleSwitch';
 export * from './Tooltip';
 export * from './Typography';
+export * from './VisuallyHidden';

package/dist/src/utilities/dom/usePopoverMenuPlacement.js

@@ -105,7 +105,6 @@ export function usePopoverMenuPlacement({ minWidth, maxHeight, allowedPlacements
                     Object.assign(elements.floating.style, {
                         maxWidth: `${String(viewportWidth - horizontalMargin * 2)}px`,
                         maxHeight: maxHeightPx,
-                        overflow: 'hidden',
                         minWidth: 'auto', // Reset minWidth for centered layout
                     });
                 }
@@ -114,8 +113,6 @@ export function usePopoverMenuPlacement({ minWidth, maxHeight, allowedPlacements
                     Object.assign(elements.floating.style, {
                         // Vertical padding for Popover height (12px) matching token: padding-main-container-vertical-comfort
                         maxHeight: maxHeightPx,
-                        // Prevent root element from scrolling; child elements handle overflow
-                        overflow: 'hidden',
                         // Constrain width to exactly match the trigger element
                         minWidth: referenceWidthPx,
                         maxWidth: referenceWidthPx,
@@ -128,8 +125,6 @@ export function usePopoverMenuPlacement({ minWidth, maxHeight, allowedPlacements
                         maxWidth: `calc(${String(Math.max(0, availableWidth))}px - 14px)`,
                         // Vertical padding for Popover height (12px) matching token: padding-main-container-vertical-comfort
                         maxHeight: maxHeightPx,
-                        // Prevent root element from scrolling; child elements handle overflow
-                        overflow: 'hidden',
                         // Make the menu to be resized at least to the width of the trigger
                         minWidth: minWidth ?? referenceWidthPx,
                     });

package/dist/src/utilities/env/isProduction.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Returns whether the code runs in a production build, so that development-only warnings can be skipped.
+ *
+ * The read is written so that `tsc` emits it in the dot form `process.env.NODE_ENV`, which bundlers replace with a
+ * string literal. In a production bundle, the check therefore folds to a constant even when the browser has no
+ * `process` global.
+ *
+ * When nothing replaces the read and `process` is not defined, such as on the Storybook Vite dev server for
+ * unbundled source, the bare read throws a `ReferenceError`. That environment is treated as non-production:
+ * that is where the development warnings are meant to be seen.
+ *
+ * @returns `true` only when `NODE_ENV` is `'production'`.
+ */
+export declare function isProduction(): boolean;

package/dist/src/utilities/env/isProduction.js

@@ -0,0 +1,22 @@
+/**
+ * Returns whether the code runs in a production build, so that development-only warnings can be skipped.
+ *
+ * The read is written so that `tsc` emits it in the dot form `process.env.NODE_ENV`, which bundlers replace with a
+ * string literal. In a production bundle, the check therefore folds to a constant even when the browser has no
+ * `process` global.
+ *
+ * When nothing replaces the read and `process` is not defined, such as on the Storybook Vite dev server for
+ * unbundled source, the bare read throws a `ReferenceError`. That environment is treated as non-production:
+ * that is where the development warnings are meant to be seen.
+ *
+ * @returns `true` only when `NODE_ENV` is `'production'`.
+ */
+export function isProduction() {
+    try {
+        // The cast lets `noPropertyAccessFromIndexSignature` accept the dot form, which bundlers only replace in this form.
+        return process.env.NODE_ENV === 'production';
+    }
+    catch {
+        return false;
+    }
+}

package/dist/src/utilities/react/isComponentOrWrapped.js

@@ -1,4 +1,5 @@
 import { isValidElement } from 'react';
+import { isProduction } from '../env/isProduction';
 /**
  * Checks if a React element is of a specific component type or wraps that component.
  *
@@ -79,7 +80,7 @@ export function isComponentOrWrapped(element, targetComponent) {
                 const result = element.type(element.props);
                 if (isValidElement(result) && result.type === targetComponent) {
                     // Warn in development about better practice
-                    if (process.env['NODE_ENV'] !== 'production' && targetDisplayName) {
+                    if (!isProduction() && targetDisplayName) {
                         console.warn(`[MFUI] Wrapper component detected without displayName. ` +
                             `This may cause issues if your wrapper uses React hooks. ` +
                             `Please set displayName="${targetDisplayName}" on your wrapper component.`);