@moneyforward/mfui-components 3.36.1 → 3.37.0

package/dist/src/DataTable/DataTable.d.ts

@@ -78,6 +78,8 @@ export declare const DataTable: import("react").ForwardRefExoticComponent<Omit<D
      * This component should be used inside the `DataTable` component.
      *
      * It renders and extends the props of `td` element.
+     * When the `isRowHeader` prop is provided, it renders `th scope="row"` instead,
+     * which exposes the cell as the row header to assistive technology.
      *
      * When the `onClickCell` prop is provided, the cell is rendered as an interactive cell.
      * Otherwise, the cell is rendered as a default cell.
@@ -92,6 +94,8 @@ export declare const DataTable: import("react").ForwardRefExoticComponent<Omit<D
      *
      * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/td
      *
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/th
+     *
      * @see https://react.dev/reference/rules/rules-of-hooks
      *
      * @example

package/dist/src/DataTable/DataTable.js

@@ -123,6 +123,8 @@ export const DataTable = Object.assign(Base, {
      * This component should be used inside the `DataTable` component.
      *
      * It renders and extends the props of `td` element.
+     * When the `isRowHeader` prop is provided, it renders `th scope="row"` instead,
+     * which exposes the cell as the row header to assistive technology.
      *
      * When the `onClickCell` prop is provided, the cell is rendered as an interactive cell.
      * Otherwise, the cell is rendered as a default cell.
@@ -137,6 +139,8 @@ export const DataTable = Object.assign(Base, {
      *
      * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/td
      *
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/th
+     *
      * @see https://react.dev/reference/rules/rules-of-hooks
      *
      * @example

package/dist/src/DataTable/DataTableCell/DataTableCell.js

@@ -10,7 +10,7 @@ import { cx } from '../../../styled-system/css';
 import { useFixedColumns } from '../../utilities/dom/useFixedColumns';
 import { handleCheckboxCellClick } from '../utils/handleCheckbox';
 import { mergeRefs } from '../../utilities/dom/mergeRefs';
-export const DataTableCell = forwardRef(({ onClickCell, children, type = 'text', className, isRowHighlighted, disabled = false, depth = 0, columnIndex, disclosureIconProps: nestingIconProps, style, ...props }, ref) => {
+export const DataTableCell = forwardRef(({ onClickCell, children, type = 'text', className, isRowHighlighted, isRowHeader = false, disabled = false, depth = 0, columnIndex, disclosureIconProps: nestingIconProps, style, ...props }, ref) => {
     const { size, leftFixedColumnIndex, rightFixedColumnIndex, loading, enableRowSelection, showVerticalBorder, layout, } = useDataTableContext();
     const { cellRef, isFixedColumn, isEdgeFixedColumn, fixedPositionStyles } = useFixedColumns({
         enableRowSelection,
@@ -27,6 +27,11 @@ export const DataTableCell = forwardRef(({ onClickCell, children, type = 'text',
         isCheckboxCell: enableRowSelection && columnIndex === 0,
         verticalBorder: showVerticalBorder,
         layout,
+        // Passing `false` would emit a class for the unused `false` variant value, changing the
+        // class list of every existing cell. `undefined` keeps normal cells byte identical.
+        // The variants above deliberately keep passing `false`: retrofitting the same guard would
+        // itself change the class list of already shipped cells, which is what this guard avoids.
+        isRowHeader: isRowHeader || undefined,
     });
     const handleClick = (event) => {
         onClickCell?.(event);
@@ -48,7 +53,10 @@ export const DataTableCell = forwardRef(({ onClickCell, children, type = 'text',
         return (_jsx("div", { className: cx(classes.defaultCell, 'mfui-DataTableCell__defaultCell', 
             /* TODO: Remove in v5.0.0 */ 'mfui-DataGridCell__defaultCell'), children: _jsx(CellContent, { depth: depth, disclosureIconProps: nestingIconProps, classes: classes, children: children }) }));
     })();
-    return (_jsx("td", { ref: mergeRefs(ref, cellRef), className: cx(classes.root, 'mfui-DataTableCell__root', 
+    // A row header identifies its row, so it must be a `th` for assistive technology.
+    // `scope` is only interpreted on `th`, which is why it cannot be passed to a plain cell.
+    const Tag = isRowHeader ? 'th' : 'td';
+    return (_jsx(Tag, { ref: mergeRefs(ref, cellRef), scope: isRowHeader ? 'row' : undefined, className: cx(classes.root, 'mfui-DataTableCell__root', 
         /* TODO: Remove in v5.0.0 */ 'mfui-DataGridCell__root', className), style: { ...style, ...fixedPositionStyles, zIndex: isFixedColumn ? 1 : undefined }, ...props, children: cellContent }));
 });
 DataTableCell.displayName = 'DataTableCell';

package/dist/src/DataTable/DataTableCell/DataTableCell.types.d.ts

@@ -34,6 +34,38 @@ export type DataTableCellProps = {
      * @default undefined
      */
     onClickCell?: (event?: React.MouseEvent<HTMLButtonElement>) => void;
+    /**
+     * Whether the cell is the row header, which identifies the row it belongs to.
+     *
+     * If `true`, the cell is rendered as `<th scope="row">` instead of `<td>`.
+     * This lets assistive technology announce the identifying cell of the row
+     * alongside every other cell in that row, so screen reader users navigating
+     * a wide table cell-by-cell can still tell which row they are in
+     * (e.g. 'Amount: ¥125,000, invoice_2026.pdf').
+     *
+     * Unlike `isRowHighlighted`, **this prop is intended to be passed by you.**
+     *
+     * The appearance is identical to a normal cell.
+     *
+     * Use it only when a column actually identifies the row, such as a file name or an
+     * invoice number. Set it on at most one cell per row. When every column holds an
+     * equally weighted attribute, there is no row header and marking one only makes
+     * the announcement verbose. The checkbox cell rendered by `enableRowSelection` is
+     * never the row header, so the row header is the second cell in that case.
+     *
+     * @default false
+     *
+     * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/th
+     *
+     * @example
+     * ```tsx
+     * <DataTable.Row>
+     *   <DataTable.Cell isRowHeader>invoice_2026.pdf</DataTable.Cell>
+     *   <DataTable.Cell type="amount">¥125,000</DataTable.Cell>
+     * </DataTable.Row>
+     * ```
+     */
+    isRowHeader?: boolean;
     /**
      * **Do not pass this prop manually.**
      *

package/dist/src/DataTable/DataTableHeaderCell/DataTableHeaderCell.js

@@ -57,7 +57,11 @@ export const DataTableHeaderCell = forwardRef(({ children, type = 'text', sortBu
     // Actions are rendered as siblings of the sort button (never inside it)
     // to avoid nesting interactive elements.
     const cellContentWithActions = actions ? (_jsxs("div", { className: cx(classes.container, 'mfui-DataTableHeaderCell__container'), children: [cellContent, _jsx("div", { className: cx(classes.actionsContainer, 'mfui-DataTableHeaderCell__actionsContainer'), children: actions })] })) : (cellContent);
-    return (_jsx("th", { ref: mergeRefs(ref, cellRef), className: cx(classes.root, 'mfui-DataTableHeaderCell__root', 
+    return (_jsx("th", { ref: mergeRefs(ref, cellRef), 
+        // `th` also appears in the body now that `DataTable.Cell` supports `isRowHeader`, so the
+        // scope is stated explicitly rather than left to the auto-scope algorithm, whose result
+        // is harder to predict with `colSpan` / `rowSpan` and fixed columns.
+        scope: "col", className: cx(classes.root, 'mfui-DataTableHeaderCell__root', 
         /* TODO: Remove in v5.0.0 */ 'mfui-DataGridHeaderCell__root', className), "aria-sort": sortOrder, style: fixedPositionStyles, ...props, children: cellContentWithActions }));
 });
 DataTableHeaderCell.displayName = 'DataTableHeaderCell';

package/dist/src/DataTable/DataTableRow/DataTableRow.types.d.ts

@@ -47,6 +47,13 @@ export type DataTableRowProps = {
      * This prop will be passed to the `onClick` and `onKeyDown` of the `tr` element.
      * When the element is clicked, the event is passed to the `onClickRow` prop, but event isn't passed when the Enter or Space key is pressed.
      *
+     * Note that this callback is NOT called when the click originates from an interactive
+     * descendant inside the row — e.g. a button, link, input (including `Checkbox`), select,
+     * label, or an element with an interactive ARIA role such as `checkbox` or `menuitem`.
+     * Handle those interactions on the descendant itself (e.g. the `Checkbox`'s `onChange`).
+     * Likewise, Enter or Space triggers this callback only while the row itself is focused,
+     * not while a focusable descendant is focused.
+     *
      * @default undefined
      */
     onClickRow?: (event: React.MouseEvent<HTMLTableRowElement> | React.KeyboardEvent<HTMLTableRowElement>) => void;

package/dist/src/MainNavigation/BaseMainNavigation.d.ts

@@ -3,4 +3,4 @@ import { type MainNavigationProps } from './MainNavigation.types';
  * The component for the main navigation on the normal viewport.
  * This component must only be used in MainNavigation.tsx, do not export it.
  */
-export declare function BaseMainNavigation({ className, featureShortcut, navigationItems, enableCollapsible, width, customLinkComponent, disableResponsive, isCollapsed: controlledIsCollapsed, onCollapsedChange, collapseButtonProps, expandButtonProps, }: MainNavigationProps): import("react/jsx-runtime").JSX.Element;
+export declare function BaseMainNavigation({ className, featureShortcut, navigationItems, enableCollapsible, nestedNavigationDisplay, width, customLinkComponent, disableResponsive, isCollapsed: controlledIsCollapsed, onCollapsedChange, collapseButtonProps, expandButtonProps, }: MainNavigationProps): import("react/jsx-runtime").JSX.Element;

package/dist/src/MainNavigation/BaseMainNavigation.js

@@ -1,6 +1,6 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { DisclosureBasicCollapsed, DisclosureBasicExpanded, Lock, PaneExpansionToLeft, PaneExpansionToRight, } from '@moneyforward/mfui-icons-react';
+import { DisclosureBasicCollapsed, DisclosureBasicExpanded, DisclosurePopoverCollapsed, DisclosurePopoverExpanded, Lock, PaneExpansionToLeft, PaneExpansionToRight, } from '@moneyforward/mfui-icons-react';
 import { useId, useState, useRef } from 'react';
 import { cx } from '../../styled-system/css';
 import { FocusIndicator } from '../FocusIndicator';
@@ -13,7 +13,7 @@ import { Popover } from '../Popover';
  * The component for the main navigation on the normal viewport.
  * This component must only be used in MainNavigation.tsx, do not export it.
  */
-export function BaseMainNavigation({ className, featureShortcut, navigationItems, enableCollapsible = false, width = 'normal', customLinkComponent, disableResponsive, isCollapsed: controlledIsCollapsed, onCollapsedChange, collapseButtonProps, expandButtonProps, }) {
+export function BaseMainNavigation({ className, featureShortcut, navigationItems, enableCollapsible = false, nestedNavigationDisplay = 'accordion', width = 'normal', customLinkComponent, disableResponsive, isCollapsed: controlledIsCollapsed, onCollapsedChange, collapseButtonProps, expandButtonProps, }) {
     const [localIsCollapsed, setLocalIsCollapsed] = useState(controlledIsCollapsed ?? false);
     const [openPopoverIndex, setOpenPopoverIndex] = useState(null);
     const isControlled = controlledIsCollapsed !== undefined;
@@ -38,7 +38,7 @@ export function BaseMainNavigation({ className, featureShortcut, navigationItems
                                 return null;
                             }
                             if (navigation.children) {
-                                return (_jsx(NestedNavigationItemRenderer, { navigation: navigation, originalIndex: index, classes: classes, InternalLinkTag: InternalLinkTag, isCollapsed: isCollapsed, openPopoverIndex: openPopoverIndex, setOpenPopoverIndex: setOpenPopoverIndex }, index));
+                                return (_jsx(NestedNavigationItemRenderer, { navigation: navigation, originalIndex: index, navId: navId, classes: classes, InternalLinkTag: InternalLinkTag, isCollapsed: isCollapsed, nestedNavigationDisplay: nestedNavigationDisplay, openPopoverIndex: openPopoverIndex, setOpenPopoverIndex: setOpenPopoverIndex }, index));
                             }
                             return (_jsx("li", { className: cx(classes.listItem, 'mfui-BaseMainNavigation__listItem'), children: _jsx(Tooltip, { className: cx(classes.listItemTooltip, 'mfui-BaseMainNavigation__listItemTooltip'), content: navigation.label, disabled: !isCollapsed, placement: "right", children: _jsx(FocusIndicator, { position: "inside", children: _jsx(NavigationLink, { tag: InternalLinkTag, isExternal: navigation.isExternal, href: navigation.href, className: cx(classes.listItemAnchor, 'mfui-BaseMainNavigation__listItemAnchor'), "aria-label": isCollapsed ? navigation.label : undefined, "aria-current": navigation.isCurrent ? 'page' : undefined, children: _jsxs("div", { className: cx(classes.labelGroup, 'mfui-BaseMainNavigation__labelGroup'), children: [_jsxs("div", { className: cx(classes.iconAndLabel, 'mfui-BaseMainNavigation__iconAndLabel'), children: [_jsx("div", { "aria-hidden": "true", className: cx(classes.listItemAnchorIcon, 'mfui-BaseMainNavigation__listItemAnchorIcon'), children: navigation.icon }), isCollapsed ? null : _jsx(Typography, { variant: "controlLabel", children: navigation.label })] }), navigation.locked ? (_jsx(Lock, { className: cx(classes.lockIcon, 'mfui-BaseMainNavigation__lockIcon'), "aria-label": navigation.lockIconProps?.['aria-label'] ?? 'ロックされています' })) : null, !isCollapsed && navigation.statusSlot && navigation.locked !== true
                                                         ? navigation.statusSlot
@@ -47,7 +47,7 @@ export function BaseMainNavigation({ className, featureShortcut, navigationItems
                             if (!('isGroupMenu' in navigation && navigation.isGroupMenu)) {
                                 return null;
                             }
-                            return (_jsx(NestedNavigationItemRenderer, { navigation: navigation, originalIndex: index, classes: classes, InternalLinkTag: InternalLinkTag, isCollapsed: isCollapsed, openPopoverIndex: openPopoverIndex, setOpenPopoverIndex: setOpenPopoverIndex }, index));
+                            return (_jsx(NestedNavigationItemRenderer, { navigation: navigation, originalIndex: index, navId: navId, classes: classes, InternalLinkTag: InternalLinkTag, isCollapsed: isCollapsed, nestedNavigationDisplay: nestedNavigationDisplay, openPopoverIndex: openPopoverIndex, setOpenPopoverIndex: setOpenPopoverIndex }, index));
                         }) })), !isCollapsed &&
                         navigationItems.map((navigation, index) => {
                             const isGroupLabel = navigation.children && 'isGroupLabel' in navigation && navigation.isGroupLabel;
@@ -60,21 +60,23 @@ export function BaseMainNavigation({ className, featureShortcut, navigationItems
 }
 /**
  * The component for rendering a parent navigation item with children.
- * Handles both collapsed (popover) and expanded (details/summary) states.
+ * Handles both popover and details/summary display modes.
  * This component must only be used in BaseMainNavigation.tsx, do not export it.
  */
-function NestedNavigationItemRenderer({ navigation, originalIndex, classes, InternalLinkTag, isCollapsed, openPopoverIndex, setOpenPopoverIndex, }) {
-    const popoverPortalTargetId = `nested-popover-portal-target-${String(originalIndex)}`;
+function NestedNavigationItemRenderer({ navigation, originalIndex, navId, classes, InternalLinkTag, isCollapsed, nestedNavigationDisplay, openPopoverIndex, setOpenPopoverIndex, }) {
+    // Scope the ID to this navigation instance so multiple MainNavigation components
+    // on the same page (e.g. the Storybook docs page) don't portal into each other.
+    const popoverPortalTargetId = `${navId}-nested-popover-portal-target-${String(originalIndex)}`;
     const hasCurrentChildren = navigation.children.some((child) => child.isCurrent);
-    return (_jsx("li", { className: cx(classes.listItem, 'mfui-BaseMainNavigation__listItem'), "data-mfui-popover-portal-target-id": popoverPortalTargetId, children: isCollapsed ? (_jsx(CollapsedNestedNavigationItem, { navigation: navigation, classes: classes, InternalLinkTag: InternalLinkTag, hasCurrentChildren: hasCurrentChildren, popoverPortalTargetId: popoverPortalTargetId, isOpen: openPopoverIndex === originalIndex, onOpenChange: (isOpen) => {
+    return (_jsx("li", { className: cx(classes.listItem, 'mfui-BaseMainNavigation__listItem'), "data-mfui-popover-portal-target-id": popoverPortalTargetId, children: isCollapsed || nestedNavigationDisplay === 'popover' ? (_jsx(PopoverNestedNavigationItem, { navigation: navigation, classes: classes, InternalLinkTag: InternalLinkTag, isCollapsed: isCollapsed, hasCurrentChildren: hasCurrentChildren, popoverPortalTargetId: popoverPortalTargetId, isOpen: openPopoverIndex === originalIndex, onOpenChange: (isOpen) => {
                 setOpenPopoverIndex(isOpen ? originalIndex : null);
             } })) : (_jsxs("details", { open: ('isOpenByDefault' in navigation && navigation.isOpenByDefault) || hasCurrentChildren, className: cx(classes.parentDetails, 'mfui-BaseMainNavigation__parentDetails'), children: [_jsx(FocusIndicator, { position: "inside", children: _jsxs("summary", { className: cx(classes.parentSummary, 'mfui-BaseMainNavigation__parentSummary'), children: [_jsx("div", { "aria-hidden": "true", className: cx(classes.parentSummaryIcon, 'mfui-BaseMainNavigation__parentSummaryIcon'), children: navigation.icon }), _jsx(Typography, { variant: "controlLabel", children: navigation.label }), _jsx(DisclosureBasicCollapsed, { className: "mfui-BaseMainNavigation__icon_collapsed", "aria-hidden": "true", "data-mfui-content": "main-navigation-icon-collapsed" }), _jsx(DisclosureBasicExpanded, { className: "mfui-BaseMainNavigation__icon_expanded", "aria-hidden": "true", "data-mfui-content": "main-navigation-icon-expanded" })] }) }), _jsx("ul", { className: cx(classes.childrenList, 'mfui-BaseMainNavigation__childrenList'), children: navigation.children.map((child, childIndex) => (_jsx("li", { className: cx(classes.childrenListItem, 'mfui-BaseMainNavigation__childrenListItem'), children: _jsx(FocusIndicator, { position: "inside", children: _jsx(NavigationLink, { tag: InternalLinkTag, isExternal: child.isExternal, href: child.href, className: cx(classes.childrenListItemAnchor, 'mfui-BaseMainNavigation__childrenListItemAnchor'), "aria-current": child.isCurrent ? 'page' : undefined, children: _jsx(Typography, { variant: "controlLabel", children: child.label }) }) }) }, childIndex))) })] })) }));
 }
 /**
- * The component for displaying nested navigation in collapsed state with popover.
+ * The component for displaying nested navigation with a popover.
  * This component must only be used in BaseMainNavigation.tsx, do not export it.
  */
-function CollapsedNestedNavigationItem({ navigation, classes, InternalLinkTag, hasCurrentChildren, popoverPortalTargetId, isOpen, onOpenChange, }) {
+function PopoverNestedNavigationItem({ navigation, classes, InternalLinkTag, isCollapsed, hasCurrentChildren, popoverPortalTargetId, isOpen, onOpenChange, }) {
     const popoverContentRef = useRef(null);
     const handleKeyDown = (event) => {
         if (event.key === 'Enter' || event.key === ' ') {
@@ -87,9 +89,18 @@ function CollapsedNestedNavigationItem({ navigation, classes, InternalLinkTag, h
     const handleClick = () => {
         onOpenChange(!isOpen);
     };
-    return (_jsx(Popover, { enableAutoFocusOnPopover: false, enableAutoFocusOnTrigger: false, open: isOpen, targetDOMNode: document.querySelector(`[data-mfui-popover-portal-target-id="${popoverPortalTargetId}"]`), allowedPlacements: ['right-start', 'right', 'right-end'], contentProps: {
+    // The expanded trigger shows the label and the disclosure chevron inline,
+    // while the collapsed trigger is icon-only and exposes the label via aria-label and a tooltip.
+    const isExpanded = !isCollapsed;
+    const DisclosureIcon = isOpen ? DisclosurePopoverExpanded : DisclosurePopoverCollapsed;
+    const popoverContentId = `${popoverPortalTargetId}-content`;
+    return (_jsx(Popover, { enableAutoFocusOnPopover: false, enableAutoFocusOnTrigger: false, open: isOpen, 
+        // `document` is unavailable during server-side prerendering.
+        targetDOMNode: typeof document === 'undefined'
+            ? undefined
+            : document.querySelector(`[data-mfui-popover-portal-target-id="${popoverPortalTargetId}"]`), allowedPlacements: ['right-start', 'right', 'right-end'], contentProps: {
             tabIndex: -1,
-        }, renderTrigger: ({ setTriggerRef }) => (_jsx(Tooltip, { className: cx(classes.listItemTooltip, 'mfui-BaseMainNavigation__listItemTooltip'), content: navigation.label, disabled: isOpen, placement: "right", children: _jsx(FocusIndicator, { position: "inside", children: _jsx("button", { ref: setTriggerRef, type: "button", className: cx(classes.listItemAnchor, 'mfui-BaseMainNavigation__listItemAnchor'), "data-mfui-current": hasCurrentChildren ? 'page' : undefined, "aria-current": hasCurrentChildren ? true : undefined, "aria-label": navigation.label, onClick: handleClick, onKeyDown: handleKeyDown, children: _jsx("div", { className: cx(classes.labelGroup, 'mfui-BaseMainNavigation__labelGroup'), children: _jsx("div", { className: cx(classes.iconAndLabel, 'mfui-BaseMainNavigation__iconAndLabel'), children: _jsx("div", { "aria-hidden": "true", className: cx(classes.listItemAnchorIcon, 'mfui-BaseMainNavigation__listItemAnchorIcon'), children: navigation.icon }) }) }) }) }) })), renderContent: () => (_jsx("div", { ref: popoverContentRef, className: cx(classes.popoverChildrenList, 'mfui-BaseMainNavigation__popoverChildrenList'), tabIndex: -1, children: navigation.children.map((child, childIndex) => (_jsx("div", { className: cx(classes.childrenListItem, 'mfui-BaseMainNavigation__childrenListItem'), children: _jsx(FocusIndicator, { position: "inside", children: _jsx(NavigationLink, { tag: InternalLinkTag, isExternal: child.isExternal, href: child.href, className: cx(classes.childrenListItemAnchor, 'mfui-BaseMainNavigation__childrenListItemAnchor'), "aria-current": child.isCurrent ? 'page' : undefined, onClick: () => {
+        }, renderTrigger: ({ setTriggerRef }) => (_jsx(Tooltip, { className: cx(classes.listItemTooltip, 'mfui-BaseMainNavigation__listItemTooltip'), content: navigation.label, disabled: isExpanded || isOpen, placement: "right", children: _jsx(FocusIndicator, { position: "inside", children: _jsx("button", { ref: setTriggerRef, type: "button", className: cx(classes.listItemAnchor, classes.popoverTrigger, 'mfui-BaseMainNavigation__listItemAnchor', 'mfui-BaseMainNavigation__popoverTrigger'), "data-mfui-current": hasCurrentChildren ? 'page' : undefined, "aria-current": hasCurrentChildren ? true : undefined, "aria-expanded": isOpen, "aria-controls": isOpen ? popoverContentId : undefined, "aria-label": isExpanded ? undefined : navigation.label, onClick: handleClick, onKeyDown: handleKeyDown, children: _jsxs("div", { className: cx(classes.labelGroup, 'mfui-BaseMainNavigation__labelGroup'), children: [_jsxs("div", { className: cx(classes.iconAndLabel, 'mfui-BaseMainNavigation__iconAndLabel'), children: [_jsx("div", { "aria-hidden": "true", className: cx(classes.listItemAnchorIcon, 'mfui-BaseMainNavigation__listItemAnchorIcon'), children: navigation.icon }), isExpanded ? _jsx(Typography, { variant: "controlLabel", children: navigation.label }) : null] }), isExpanded ? (_jsx(DisclosureIcon, { "aria-hidden": "true", className: cx(classes.popoverTriggerDisclosureIcon, 'mfui-BaseMainNavigation__popoverTriggerDisclosureIcon') })) : null] }) }) }) })), renderContent: () => (_jsx("div", { id: popoverContentId, ref: popoverContentRef, className: cx(classes.popoverChildrenList, 'mfui-BaseMainNavigation__popoverChildrenList'), tabIndex: -1, children: navigation.children.map((child, childIndex) => (_jsx("div", { className: cx(classes.childrenListItem, 'mfui-BaseMainNavigation__childrenListItem'), children: _jsx(FocusIndicator, { position: "inside", children: _jsx(NavigationLink, { tag: InternalLinkTag, isExternal: child.isExternal, href: child.href, className: cx(classes.childrenListItemAnchor, 'mfui-BaseMainNavigation__childrenListItemAnchor'), "aria-current": child.isCurrent ? 'page' : undefined, onClick: () => {
                             onOpenChange(false);
                         }, children: _jsx(Typography, { variant: "controlLabel", children: child.label }) }) }) }, childIndex))) })), onOpenStateChanged: onOpenChange }));
 }

package/dist/src/MainNavigation/MainNavigation.js

@@ -9,7 +9,7 @@ import { NarrowViewportMainNavigation } from './NarrowViewportMainNavigation';
  * When the viewport is narrow, the navigation will be displayed as a drawer.
  * When the viewport is not narrow, the navigation will be displayed as a sidebar.
  */
-export const MainNavigation = forwardRef(({ className, featureShortcut, navigationItems, disableResponsive = false, width = 'normal', customLinkComponent, enableCollapsible, isCollapsed, onCollapsedChange, collapseButtonProps, expandButtonProps, }, ref) => {
+export const MainNavigation = forwardRef(({ className, featureShortcut, navigationItems, disableResponsive = false, width = 'normal', customLinkComponent, enableCollapsible, nestedNavigationDisplay, isCollapsed, onCollapsedChange, collapseButtonProps, expandButtonProps, }, ref) => {
     const commonProps = {
         className,
         featureShortcut,
@@ -17,5 +17,5 @@ export const MainNavigation = forwardRef(({ className, featureShortcut, navigati
         width,
         customLinkComponent,
     };
-    return (_jsxs(_Fragment, { children: [_jsx(BaseMainNavigation, { ...commonProps, enableCollapsible: enableCollapsible, disableResponsive: disableResponsive, isCollapsed: isCollapsed, onCollapsedChange: onCollapsedChange, collapseButtonProps: collapseButtonProps, expandButtonProps: expandButtonProps }), !disableResponsive && _jsx(NarrowViewportMainNavigation, { ...commonProps, ref: ref })] }));
+    return (_jsxs(_Fragment, { children: [_jsx(BaseMainNavigation, { ...commonProps, enableCollapsible: enableCollapsible, nestedNavigationDisplay: nestedNavigationDisplay, disableResponsive: disableResponsive, isCollapsed: isCollapsed, onCollapsedChange: onCollapsedChange, collapseButtonProps: collapseButtonProps, expandButtonProps: expandButtonProps }), !disableResponsive && _jsx(NarrowViewportMainNavigation, { ...commonProps, ref: ref })] }));
 });

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

@@ -85,6 +85,8 @@ type ParentNavigationItem = {
      * Whether the nested navigation is open by default.
      * When set to true, the parent navigation item is expanded on initial render,
      * regardless of whether any child has `isCurrent: true`.
+     * This property has no effect when the nested navigation is shown in a popover —
+     * i.e. when `MainNavigation` has `nestedNavigationDisplay="popover"`, or while the navigation is collapsed.
      *
      * @default false
      */
@@ -193,6 +195,20 @@ export type MainNavigationProps = {
      * @default false
      */
     enableCollapsible?: boolean;
+    /**
+     * How nested navigation items display their children in the normal viewport navigation.
+     *
+     * - `'accordion'`: Children expand below the parent item while the navigation is expanded.
+     *   When the navigation is collapsed, children are always shown in a popover.
+     * - `'popover'`: Children are shown in a popover to the right in both expanded and collapsed states.
+     *
+     * Prefer `'accordion'` while the navigation is expanded unless the design requires a popover.
+     * When set to `'popover'`, `isOpenByDefault` on navigation items has no effect.
+     * The narrow viewport navigation always displays nested items as an accordion regardless of this property.
+     *
+     * @default 'accordion'
+     */
+    nestedNavigationDisplay?: 'accordion' | 'popover';
     /**
      * The width of the navigation.
      *
@@ -265,5 +281,5 @@ export type MainNavigationRef = {
     openMainNavigation: () => void;
     closeMainNavigation: () => void;
 };
-export type NarrowViewportMainNavigationProps = Omit<MainNavigationProps, 'enableCollapsible'>;
+export type NarrowViewportMainNavigationProps = Omit<MainNavigationProps, 'enableCollapsible' | 'nestedNavigationDisplay'>;
 export {};

package/dist/src/MultipleSelectBox/MultipleSelectBox.js

@@ -24,6 +24,8 @@ import { useApplyControls } from './hooks/useApplyControls';
 import { useCreateOption } from './hooks/useCreateOption';
 import { cx } from '../../styled-system/css';
 import { flattenOptions } from './utils/flattenOptions';
+import { getGroupLabelId } from '../utilities/dom/getGroupLabelId';
+import { OptionGroupLabelDescriptions } from '../shared/OptionGroupLabelDescriptions';
 import { isSelectableOption, isOptionDisabled, isOptionSelected } from './utils/isSelectableOption';
 import { useVirtualizedMultipleSelectBoxOptions } from './hooks/useVirtualizedMultipleSelectBoxOptions';
 import { useInfiniteScroll } from '../utilities/dom/useInfiniteScroll';
@@ -80,11 +82,50 @@ placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode,
     });
     // Determine if virtualization should be enabled
     const shouldVirtualize = enableVirtualization && !loading && flattenedOptions.length > 0;
+    // The options reference their group label with `aria-describedby`. A virtualized option list can
+    // unmount the visible label row, so there the referenced element is rendered outside the list
+    // instead - see `OptionGroupLabelDescriptions`. Only one of the two ever carries the id.
+    const rendersHiddenGroupLabels = shouldVirtualize;
+    const optionGroupLabels = useMemo(() => 
+    // Same check as `isSelectableOption`, inlined because its type guard narrows the negative branch
+    // to `never` here. A group label is any entry without a value, including one that carries no
+    // nested options - `flattenOptions` keeps those.
+    filteredOptions.flatMap((option, optionIndex) => 'value' in option ? [] : [{ id: getGroupLabelId(listBoxId, optionIndex), label: option.label }]), [filteredOptions, listBoxId]);
+    // Create the row structure for virtualization: one row per entry of the already flat option list,
+    // group labels included. The nested options of a group entry are not expanded here - `filteredOptions`
+    // is the output of `flattenOptions`, so they are already present as their own entries.
+    const createVirtualizedItems = useCallback(() => {
+        if (!shouldVirtualize)
+            return [];
+        const items = [];
+        // An option is described by the group label it is rendered under, which is the last group label
+        // rendered before it.
+        let currentGroupLabelId;
+        filteredOptions.forEach((option, optionIndex) => {
+            if ('options' in option && Array.isArray(option.options)) {
+                currentGroupLabelId = getGroupLabelId(listBoxId, optionIndex);
+                items.push({
+                    type: 'group',
+                    option,
+                    groupLabelId: currentGroupLabelId,
+                });
+            }
+            else {
+                items.push({
+                    type: 'option',
+                    option,
+                    groupLabelId: currentGroupLabelId,
+                });
+            }
+        });
+        return items;
+    }, [filteredOptions, shouldVirtualize, listBoxId]);
+    const virtualizedItems = useMemo(() => createVirtualizedItems(), [createVirtualizedItems]);
     // Initialize virtualization
     const { virtualizer, virtualItems, totalSize, isVirtualized } = useVirtualizedMultipleSelectBoxOptions({
         enabled: shouldVirtualize,
         parentRef: scrollWrapperRef,
-        flatOptions: filteredOptions.filter((option) => 'value' in option),
+        rowCount: virtualizedItems.length,
         estimateSize: virtualizationOptions?.estimateSize,
         overscan: virtualizationOptions?.overscan,
     });
@@ -152,37 +193,6 @@ placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode,
         onSelectOption: handleSelectOption,
         onClosePanel: closeOptionPanel,
     });
-    // Create a flat structure for virtualization that includes both group headers and options
-    const createVirtualizedItems = useCallback(() => {
-        if (!shouldVirtualize)
-            return [];
-        const items = [];
-        filteredOptions.forEach((option) => {
-            if ('options' in option && Array.isArray(option.options)) {
-                // Add group header
-                items.push({
-                    type: 'group',
-                    option,
-                });
-                // Add group options
-                option.options.forEach((nestedOption) => {
-                    items.push({
-                        type: 'option',
-                        option: nestedOption,
-                    });
-                });
-            }
-            else {
-                // Regular option
-                items.push({
-                    type: 'option',
-                    option,
-                });
-            }
-        });
-        return items;
-    }, [filteredOptions, shouldVirtualize]);
-    const virtualizedItems = useMemo(() => createVirtualizedItems(), [createVirtualizedItems]);
     // Render virtualized items - extracted for better maintainability
     const renderVirtualizedItems = useCallback(() => {
         let focusableIndex = 0;
@@ -190,7 +200,7 @@ placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode,
             const virtualizedItem = virtualizedItems[virtualItem.index];
             if (!virtualizedItem)
                 return null;
-            const { type, option } = virtualizedItem;
+            const { type, option, groupLabelId } = virtualizedItem;
             if (type === 'group') {
                 return (_jsx("div", { ref: virtualizer?.measureElement, "data-index": virtualItem.index, style: {
                         position: 'absolute',
@@ -198,7 +208,7 @@ placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode,
                         left: 0,
                         width: '100%',
                         transform: `translateY(${String(virtualItem.start)}px)`,
-                    }, children: _jsx("li", { className: cx(classes.listItem, 'mfui-MultipleSelectBox__listItem'), "data-mfui-group-label": "true", "aria-hidden": "true", children: _jsx(Typography, { variant: "label", children: option.label }) }) }, virtualItem.key));
+                    }, children: _jsx("li", { role: "presentation", className: cx(classes.listItem, 'mfui-MultipleSelectBox__listItem'), "data-mfui-group-label": "true", children: _jsx(Typography, { variant: "label", children: option.label }) }) }, virtualItem.key));
             }
             if (isSelectableOption(option) && option.value != null) {
                 const { value, label } = option;
@@ -220,7 +230,7 @@ placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode,
                         left: 0,
                         width: '100%',
                         transform: `translateY(${String(virtualItem.start)}px)`,
-                    }, children: _jsx(FocusIndicator, { position: "inside", children: _jsx("li", { role: "option", "data-focusable": !isDisabled, "data-value": value, className: cx(classes.listItem, 'mfui-MultipleSelectBox__listItem'), "aria-selected": isSelected, "aria-disabled": isDisabled, tabIndex: isDisabled ? -1 : currentFocusableIndex === tabbableOptionIndex ? 0 : -1, onFocus: () => {
+                    }, children: _jsx(FocusIndicator, { position: "inside", children: _jsx("li", { role: "option", "data-focusable": !isDisabled, "data-value": value, className: cx(classes.listItem, 'mfui-MultipleSelectBox__listItem'), "aria-selected": isSelected, "aria-disabled": isDisabled, "aria-describedby": groupLabelId, tabIndex: isDisabled ? -1 : currentFocusableIndex === tabbableOptionIndex ? 0 : -1, onFocus: () => {
                                 if (!isDisabled)
                                     handleOptionFocus(currentFocusableIndex);
                             }, onKeyDown: createKeyDownHandler(option), onClick: () => {
@@ -251,6 +261,9 @@ placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode,
     const renderNonVirtualizedItems = useCallback(() => {
         // Map from filteredOptions index to focusableOptions index
         let focusableIndex = 0;
+        // An option is described by the group label it is rendered under, which is the last group label
+        // rendered before it.
+        let currentGroupLabelId;
         return filteredOptions.map((option, optionIndex) => {
             if (isSelectableOption(option)) {
                 // If selectable but value is null/undefined, skip rendering
@@ -268,7 +281,7 @@ placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode,
                     currentFocusableIndex = focusableIndex;
                     focusableIndex += 1;
                 }
-                return (_jsx(FocusIndicator, { position: "inside", children: _jsx("li", { role: "option", "data-focusable": !isDisabled, className: cx(classes.listItem, 'mfui-MultipleSelectBox__listItem'), "aria-selected": isSelected, "aria-disabled": isDisabled, tabIndex: isDisabled ? -1 : currentFocusableIndex === tabbableOptionIndex ? 0 : -1, onFocus: () => {
+                return (_jsx(FocusIndicator, { position: "inside", children: _jsx("li", { role: "option", "data-focusable": !isDisabled, className: cx(classes.listItem, 'mfui-MultipleSelectBox__listItem'), "aria-selected": isSelected, "aria-disabled": isDisabled, "aria-describedby": currentGroupLabelId, tabIndex: isDisabled ? -1 : currentFocusableIndex === tabbableOptionIndex ? 0 : -1, onFocus: () => {
                             if (!isDisabled)
                                 handleOptionFocus(currentFocusableIndex);
                         }, onKeyDown: createKeyDownHandler(option), onClick: () => {
@@ -280,7 +293,8 @@ placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode,
             }
             // Only render group label if truly a group label (no value property at all)
             const { label } = option;
-            return (_jsx("li", { className: classes.listItem, "data-mfui-group-label": "true", "aria-hidden": "true", children: _jsx(Typography, { variant: "label", children: label }) }, `group-label-${String(optionIndex)}`));
+            currentGroupLabelId = getGroupLabelId(listBoxId, optionIndex);
+            return (_jsx("li", { id: rendersHiddenGroupLabels ? undefined : currentGroupLabelId, role: "presentation", className: classes.listItem, "data-mfui-group-label": "true", children: _jsx(Typography, { variant: "label", children: label }) }, `group-label-${String(optionIndex)}`));
         });
     }, [
         filteredOptions,
@@ -293,6 +307,8 @@ placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode,
         createKeyDownHandler,
         handleOptionFocus,
         tabbableOptionIndex,
+        listBoxId,
+        rendersHiddenGroupLabels,
     ]);
     // Render infinite scroll error message with retry button
     const renderInfiniteScrollError = useCallback((as = 'li') => {
@@ -345,7 +361,7 @@ placeholder, emptyMessage, disabled, invalid, required, caution, targetDOMNode,
                                                 ? resolvedNotFoundMessage
                                                 : emptyMessage }) }, "empty"),
                                 !isVirtualized && renderInfiniteScrollError(),
-                            ].filter(Boolean) }), isVirtualized ? renderInfiniteScrollLoading() : null, isVirtualized ? renderInfiniteScrollError('div') : null] }));
+                            ].filter(Boolean) }), isVirtualized ? renderInfiniteScrollLoading() : null, isVirtualized ? renderInfiniteScrollError('div') : null, _jsx(OptionGroupLabelDescriptions, { groups: rendersHiddenGroupLabels ? optionGroupLabels : [] })] }));
     const createOptionAreaNode = isCreateOptionVisible ? (_jsxs("div", { className: cx(classes.createOptionArea, 'mfui-MultipleSelectBox__createOptionArea'), children: [_jsxs("button", { "data-mfui-content": "create-new-option", type: "button", className: cx(classes.createOptionButton, 'mfui-MultipleSelectBox__createOptionButton'), disabled: isCreating, onClick: handleCreateOption, children: [_jsx(Add, { "aria-hidden": true }), createOptionProps?.renderLabel?.(searchText.trim()) ?? (_jsxs(_Fragment, { children: [_jsx(Typography, { variant: "strongBody", children: searchText.trim() }), _jsx(Typography, { variant: "body", children: "\u3092\u8FFD\u52A0" })] }))] }), createError ? (_jsx("div", { className: cx(classes.createOptionErrorMessage, 'mfui-MultipleSelectBox__createOptionErrorMessage'), children: _jsx(HelpMessage, { messageType: "error", children: createOptionProps?.renderErrorMessage?.(searchText.trim()) ??
                         `${searchText.trim()}を追加できませんでした。` }) })) : null] })) : null;
     return (_jsx(Popover, { renderTrigger: ({ setTriggerRef, togglePopover, handleTriggerKeyDown, handleTriggerBlur }) => (_jsx(MultipleSelectBoxTrigger, { ref: triggerRef, wrapperRef: setTriggerRef, selectedOptions: localSelectedOptions, id: id, disabled: disabled, triggerProps: triggerProps, triggerWrapperProps: triggerWrapperProps, name: name, 

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

@@ -1,7 +1,7 @@
 import { useVirtualizer } from '@tanstack/react-virtual';
 import { type RefObject } from 'react';
-import { type FlatMultipleSelectBoxOption, type VirtualOptionTypes } from '../MultipleSelectBox.types';
-export type UseVirtualizedMultipleSelectBoxOptionsParams<T extends string | number = string, AdditionalProps extends Record<string, unknown> = Record<string, never>> = {
+import { type VirtualOptionTypes } from '../MultipleSelectBox.types';
+export type UseVirtualizedMultipleSelectBoxOptionsParams = {
     /**
      * Enable virtualization for the option list
      */
@@ -11,9 +11,10 @@ export type UseVirtualizedMultipleSelectBoxOptionsParams<T extends string | numb
      */
     parentRef: RefObject<HTMLElement | null>;
     /**
-     * Flat array of all options
+     * Number of rows the option list renders. Group labels are rows too, so this is not the number of
+     * options: sizing the scroll area by the option count alone makes the last rows unreachable.
      */
-    flatOptions: FlatMultipleSelectBoxOption<T, AdditionalProps>[];
+    rowCount: number;
 } & Partial<VirtualOptionTypes>;
 export type UseVirtualizedMultipleSelectBoxOptionsReturn = {
     /**
@@ -54,10 +55,10 @@ export type UseVirtualizedMultipleSelectBoxOptionsReturn = {
  * const { virtualItems, totalSize, scrollToIndex, isVirtualized } = useVirtualizedMultipleSelectBoxOptions({
  *   enabled: true,
  *   parentRef: optionPanelRef,
- *   flatOptions,
+ *   rowCount: virtualizedItems.length,
  *   estimateSize: () => 36, // or (index) => index < 10 ? 40 : 36 for dynamic sizing
  *   overscan: 5,
  * });
  * ```
  */
-export declare function useVirtualizedMultipleSelectBoxOptions<T extends string | number = string, AdditionalProps extends Record<string, unknown> = Record<string, never>>({ enabled, parentRef, flatOptions, estimateSize, overscan, }: UseVirtualizedMultipleSelectBoxOptionsParams<T, AdditionalProps>): UseVirtualizedMultipleSelectBoxOptionsReturn;
+export declare function useVirtualizedMultipleSelectBoxOptions({ enabled, parentRef, rowCount, estimateSize, overscan, }: UseVirtualizedMultipleSelectBoxOptionsParams): UseVirtualizedMultipleSelectBoxOptionsReturn;

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

@@ -13,17 +13,17 @@ import { useCallback } from 'react';
  * const { virtualItems, totalSize, scrollToIndex, isVirtualized } = useVirtualizedMultipleSelectBoxOptions({
  *   enabled: true,
  *   parentRef: optionPanelRef,
- *   flatOptions,
+ *   rowCount: virtualizedItems.length,
  *   estimateSize: () => 36, // or (index) => index < 10 ? 40 : 36 for dynamic sizing
  *   overscan: 5,
  * });
  * ```
  */
-export function useVirtualizedMultipleSelectBoxOptions({ enabled, parentRef, flatOptions, estimateSize = () => 36, overscan = 5, }) {
+export function useVirtualizedMultipleSelectBoxOptions({ enabled, parentRef, rowCount, estimateSize = () => 36, overscan = 5, }) {
     const shouldVirtualize = enabled;
     // Always call useVirtualizer to maintain hook order, but with 0 count when disabled
     const virtualizer = useVirtualizer({
-        count: shouldVirtualize ? flatOptions.length : 0,
+        count: shouldVirtualize ? rowCount : 0,
         getScrollElement: () => 
         // The parentRef itself is the scrollable element (option panel div)
         parentRef.current ?? null,