@moneyforward/mfui-components 4.6.0 → 4.8.0

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

@@ -72,7 +72,7 @@ export declare const DataTable: import("react").ForwardRefExoticComponent<Omit<D
      * Body.displayName = 'CustomDataTableBody'; // Will cause hooks violation
      * ```
      */
-    Body: import("react").ForwardRefExoticComponent<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLTableSectionElement>, HTMLTableSectionElement>, "ref"> & import("react").RefAttributes<HTMLTableSectionElement>>;
+    Body: import("react").ForwardRefExoticComponent<Omit<import("./DataTableBody").DataTableBodyProps, "ref"> & import("react").RefAttributes<HTMLTableSectionElement>>;
     /**
      * The `DataTableCell` component.
      * This component should be used inside the `DataTable` component.

package/dist/src/DataTable/DataTable.js

@@ -1,6 +1,6 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { Children, isValidElement, useMemo, useRef, forwardRef } from 'react';
+import { Children, isValidElement, useCallback, useMemo, useRef, useState, forwardRef } from 'react';
 import { DataTableProvider } from './DataTableProvider';
 import { dataTableSlotRecipe } from '../../styled-system/recipes';
 import { DataTableBody } from './DataTableBody';
@@ -15,9 +15,54 @@ import { cx } from '../../styled-system/css';
 import { isComponentOrWrapped } from '../utilities/react/isComponentOrWrapped';
 import { mergeRefs } from '../utilities/dom/mergeRefs';
 import { useTableEdgeCellMarkers } from '../utilities/dom/useTableEdgeCellMarkers';
-const Base = forwardRef(({ className, size = 'medium', enableRowSelection = false, enableRowClickSelection = false, fixedHeader = false, showVerticalBorder = false, leftFixedColumnIndex, rightFixedColumnIndex, layout = 'default', wrapperProps, loading = false, emptyStateSlot, children, ...props }, ref) => {
-    const classes = dataTableSlotRecipe({ layout });
+import { useVirtualizedColumns } from './hooks/useVirtualizedColumns';
+import { flattenChildren } from '../utilities/react/flattenChildren';
+import { resolveColumnWidths } from './utils/resolveColumnWidths';
+const Base = forwardRef(({ className, size = 'medium', enableRowSelection = false, enableRowClickSelection = false, fixedHeader = false, showVerticalBorder = false, leftFixedColumnIndex, rightFixedColumnIndex, layout = 'default', wrapperProps, loading = false, emptyStateSlot, enableColumnVirtualization = false, columnVirtualizationOptions, children, ...props }, ref) => {
+    const classes = dataTableSlotRecipe({ layout, columnVirtualization: enableColumnVirtualization });
     const tableRef = useRef(null);
+    // A virtualized body needs the element that owns `overflow: auto`, which is the wrapper below.
+    // A ref object would still be `null` when the body's layout effects run, because host refs are
+    // attached child-first, so the element is held in state and the body re-renders once it lands.
+    const [scrollElement, setScrollElement] = useState(null);
+    // A virtualized body mounts only a window of its rows, so the row count it publishes here is what
+    // keeps `aria-rowcount` honest. It stays `null` while no body is virtualized.
+    const [virtualizedRowCount, setVirtualizedRowCount] = useState(null);
+    const [headerRowCount, setHeaderRowCount] = useState(0);
+    const registerHeaderRow = useCallback(() => {
+        setHeaderRowCount((count) => count + 1);
+        return () => {
+            setHeaderRowCount((count) => count - 1);
+        };
+    }, []);
+    // The header row counts all of its cells, mounted or not, and the column virtualizer windows that count.
+    const [numberColumns, setNumberColumns] = useState(0);
+    // The header row holds the element of every column, mounted or not, so it reports the
+    // `style.width` of each header cell for the `<colgroup>` of a table that windows its columns.
+    const [declaredColumnWidths, setDeclaredColumnWidths] = useState([]);
+    const reportDeclaredColumnWidths = useCallback((widths) => {
+        // The header row reports a new array on every render of its children, which must not re-render
+        // the whole table when no width changed.
+        setDeclaredColumnWidths((current) => current.length === widths.length && current.every((width, index) => width === widths[index]) ? current : widths);
+    }, []);
+    const columnWidths = resolveColumnWidths(enableColumnVirtualization ? declaredColumnWidths : [], columnVirtualizationOptions?.getColumnWidth);
+    // No single row owns the columns, so the window is computed here once and every row applies it
+    // to its own cells. The header and the body therefore always mount the same columns.
+    const columnWindow = useVirtualizedColumns({
+        enabled: enableColumnVirtualization,
+        scrollElement,
+        tableRef,
+        columnCount: numberColumns,
+        selectionColumnCount: enableRowSelection ? 1 : 0,
+        columnWidths,
+        leftFixedColumnIndex,
+        rightFixedColumnIndex,
+        overscan: columnVirtualizationOptions?.overscan,
+    });
+    // A consumer `<colgroup>` replaces the table's own. Only an element of type `'colgroup'` among the
+    // direct children (Fragments expanded) is detected, as documented on `enableColumnVirtualization`.
+    const hasConsumerColgroup = useMemo(() => enableColumnVirtualization &&
+        flattenChildren(children).some((child) => isValidElement(child) && child.type === 'colgroup'), [enableColumnVirtualization, children]);
     // `:first-child` / `:last-child` cannot tell which grid column a cell renders in, so the
     // table-edge spacing of the cell recipes misfires on the rows a `rowSpan` extends into.
     // This marks the displaced cells so that spacing can be cancelled on them.
@@ -29,6 +74,7 @@ const Base = forwardRef(({ className, size = 'medium', enableRowSelection = fals
         const bodyElement = Children.toArray(children).find((child) => isValidElement(child) &&
             (isComponentOrWrapped(child, DataTableBody) ||
                 (typeof child.type !== 'string' &&
+                    typeof child.type !== 'symbol' &&
                     'displayName' in child.type &&
                     child.type.displayName === 'DataGridBody')));
         if (!bodyElement || !isValidElement(bodyElement))
@@ -38,16 +84,23 @@ const Base = forwardRef(({ className, size = 'medium', enableRowSelection = fals
             const bodyChildren = Children.toArray(bodyElement.props.children);
             return bodyChildren.some((child) => isValidElement(child) &&
                 (isComponentOrWrapped(child, DataTableRow) ||
+                    // A `Fragment` has a symbol as its type, which `in` cannot search.
                     (typeof child.type !== 'string' &&
+                        typeof child.type !== 'symbol' &&
                         'displayName' in child.type &&
                         child.type.displayName === 'DataGridRow')));
         }
         return false;
     }, [children, loading]);
     const shouldShowEmptyState = !hasRows && !!emptyStateSlot && !loading;
-    return (_jsx(DataTableProvider, { size: size, enableRowSelection: enableRowSelection, enableRowClickSelection: enableRowClickSelection, fixedHeader: fixedHeader, showVerticalBorder: showVerticalBorder, leftFixedColumnIndex: leftFixedColumnIndex, rightFixedColumnIndex: rightFixedColumnIndex, loading: loading, layout: layout, children: _jsxs("div", { ...wrapperProps, className: cx(classes.wrapper, 'mfui-DataTable__wrapper', 
-            /* TODO: Remove in v5.0.0 */ 'mfui-DataGrid__wrapper', wrapperProps?.className), children: [_jsx("table", { ref: mergeRefs(ref, tableRef), className: cx(classes.table, 'mfui-DataTable__table', 
-                    /* TODO: Remove in v5.0.0 */ 'mfui-DataGrid__table', className), ...props, children: children }), shouldShowEmptyState ? (_jsx("div", { className: cx(classes.emptyState, 'mfui-DataTable__emptyState', 
+    // A virtualized body holds only a window of its rows, so the mounted rows are not the row count.
+    // This is spread before `props` so that a consumer-supplied `aria-rowcount` still wins.
+    const ariaRowCountProps = virtualizedRowCount !== null ? { 'aria-rowcount': virtualizedRowCount + headerRowCount } : undefined;
+    // The same holds for the columns: only a window of the cells of each row is mounted.
+    const ariaColCountProps = columnWindow !== null && numberColumns > 0 ? { 'aria-colcount': numberColumns } : undefined;
+    return (_jsx(DataTableProvider, { size: size, enableRowSelection: enableRowSelection, enableRowClickSelection: enableRowClickSelection, fixedHeader: fixedHeader, showVerticalBorder: showVerticalBorder, leftFixedColumnIndex: leftFixedColumnIndex, rightFixedColumnIndex: rightFixedColumnIndex, loading: loading, layout: layout, scrollElement: scrollElement, virtualizedRowCount: virtualizedRowCount, setVirtualizedRowCount: setVirtualizedRowCount, headerRowCount: headerRowCount, registerHeaderRow: registerHeaderRow, columnWindow: columnWindow, reportDeclaredColumnWidths: reportDeclaredColumnWidths, numberColumns: numberColumns, setNumberColumns: setNumberColumns, children: _jsxs("div", { ...wrapperProps, ref: setScrollElement, className: cx(classes.wrapper, 'mfui-DataTable__wrapper', 
+            /* TODO: Remove in v5.0.0 */ 'mfui-DataGrid__wrapper', wrapperProps?.className), children: [_jsxs("table", { ref: mergeRefs(ref, tableRef), className: cx(classes.table, 'mfui-DataTable__table', 
+                    /* TODO: Remove in v5.0.0 */ 'mfui-DataGrid__table', className), ...ariaRowCountProps, ...ariaColCountProps, ...props, children: [enableColumnVirtualization && !hasConsumerColgroup ? (_jsxs("colgroup", { children: [enableRowSelection ? (_jsx("col", { className: cx(classes.selectionColumn, 'mfui-DataTable__selectionColumn') })) : null, columnWidths.map((width, index) => (_jsx("col", { style: { width } }, index)))] })) : null, children] }), shouldShowEmptyState ? (_jsx("div", { className: cx(classes.emptyState, 'mfui-DataTable__emptyState', 
                     /* TODO: Remove in v5.0.0 */ 'mfui-DataGrid__emptyState'), role: "status", "aria-live": "polite", children: emptyStateSlot })) : null] }) }));
 });
 Base.displayName = 'DataTable';

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

@@ -1,4 +1,5 @@
 import { type ComponentPropsWithRef, type ComponentPropsWithoutRef, type ReactNode } from 'react';
+import { type VirtualizerOptions } from '@tanstack/react-virtual';
 import { type DataTableSize } from './DataTableProvider';
 import { type DataTableSlotRecipeVariant } from '../../styled-system/recipes';
 /**
@@ -18,6 +19,19 @@ export type CellDataType = 'text' | 'amount';
  * @param checkbox - The built-in selection checkbox element.
  */
 export type DataTableSelectionCheckboxWrapper = (checkbox: ReactNode) => ReactNode;
+/**
+ * The options for the column virtualization of the `DataTable` component.
+ */
+export type DataTableColumnVirtualizationOptions = {
+    /**
+     * Returns the width of a column in pixels.
+     *
+     * `index` counts the columns as `leftFixedColumnIndex` does, without the selection column.
+     * Return `undefined` to fall back to the `style.width` of the column's `DataTable.HeaderCell`,
+     * and then to 160px.
+     */
+    getColumnWidth?: (index: number) => number | undefined;
+} & Pick<VirtualizerOptions<HTMLElement, Element>, 'overscan'>;
 /**
  * The props for the `DataTable` component.
  *
@@ -142,4 +156,91 @@ export type DataTableProps = {
      * @default undefined
      */
     emptyStateSlot?: ReactNode;
+    /**
+     * Whether to render only the columns near the viewport (column virtualization).
+     *
+     * When enabled, the header row and every row mount a window of their cells instead of all of them,
+     * and reserve the width of the columns they leave out with a spacer cell on each side of the window.
+     * This removes the DOM and mount cost of a wide table, and composes with `enableVirtualization` on
+     * `DataTable.Body` to window a table in both directions.
+     *
+     * The first column, the columns up to `leftFixedColumnIndex` and the columns from
+     * `rightFixedColumnIndex` are always mounted; only the columns between them are windowed.
+     *
+     * Layout:
+     *
+     * - The table switches to `table-layout: fixed`, because the cells of a row stay in their columns only
+     *   when every column takes its width from a `<col>`. A `tableLayout` you set through `style` or
+     *   `className` still wins.
+     * - The table renders a `<colgroup>` with one `<col>` per column, including the selection column when
+     *   `enableRowSelection` is `true`. Each column takes the first width of:
+     *   1. `columnVirtualizationOptions.getColumnWidth(index)`, when it returns a width.
+     *   2. The `style.width` of the column's `DataTable.HeaderCell`, when it is a number or a `px` string.
+     *      Other units (`%`, `rem`, `calc()`) are ignored, because the window is computed in pixels before
+     *      anything is laid out.
+     *   3. 160px.
+     * - Content wider than its column overflows the cell under the fixed layout instead of widening the
+     *   column. Truncate it, e.g. with `text-overflow: ellipsis`, or give the column a wider width.
+     * - To declare the columns yourself, render a `<colgroup>` as a direct child of `DataTable` (a
+     *   Fragment around it is fine). The table then renders none of its own. It detects yours by the
+     *   element type `'colgroup'` only, so a `<colgroup>` rendered by your own component is not detected
+     *   and the table would end up with two (a warning is logged in development). Keep the widths of
+     *   your `<col>` elements in sync with the resolved widths above, since the window is computed from those.
+     *   `getColumnWidthFromContentWidth` turns a content width into the matching column width.
+     * - The table has to render a `DataTable.HeaderRow`, which is what the columns are counted from.
+     *
+     * `aria-colcount` on the table and `aria-colindex` on each cell are set for you, so that assistive
+     * technology is told the real column count rather than the number of mounted cells. Both stay
+     * overridable by the values you pass yourself.
+     *
+     * **Not supported together with merged cells.** A `colSpan` / `rowSpan` shifts the source-order
+     * index the window is resolved by, so the wrong cells are mounted.
+     *
+     * @default false
+     *
+     * @example
+     * ```tsx
+     * <div style={{ height: 500 }}>
+     *   <DataTable enableColumnVirtualization leftFixedColumnIndex={0}>
+     *     <DataTable.Header>
+     *       <DataTable.HeaderRow>
+     *         {columns.map((column) => (
+     *           <DataTable.HeaderCell key={column.id} style={{ width: column.width }}>
+     *             {column.label}
+     *           </DataTable.HeaderCell>
+     *         ))}
+     *       </DataTable.HeaderRow>
+     *     </DataTable.Header>
+     *     <DataTable.Body>
+     *       {rows.map((row) => (
+     *         <DataTable.Row key={row.id}>
+     *           {columns.map((column) => (
+     *             <DataTable.Cell key={column.id}>{row[column.id]}</DataTable.Cell>
+     *           ))}
+     *         </DataTable.Row>
+     *       ))}
+     *     </DataTable.Body>
+     *   </DataTable>
+     * </div>
+     * ```
+     */
+    enableColumnVirtualization?: boolean;
+    /**
+     * The configuration of the column virtualization.
+     * Only applies when `enableColumnVirtualization` is `true`.
+     *
+     * @property getColumnWidth - Returns the width of a column in pixels. It receives the column index counted
+     * as `leftFixedColumnIndex` is, without the selection column. It takes precedence over the `style.width`
+     * of the header cell; return `undefined` to fall back to it, and then to 160px.
+     * @property overscan - The number of columns rendered outside the visible area, on each side. Defaults to `2`.
+     *
+     * @example
+     * ```tsx
+     * <DataTable
+     *   enableColumnVirtualization
+     *   columnVirtualizationOptions={{ getColumnWidth: (index) => columns[index]?.width, overscan: 4 }}
+     * >
+     * ```
+     */
+    columnVirtualizationOptions?: DataTableColumnVirtualizationOptions;
 } & ComponentPropsWithRef<'table'>;

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

@@ -1 +1,2 @@
-export declare const DataTableBody: import("react").ForwardRefExoticComponent<Omit<import("react").DetailedHTMLProps<import("react").HTMLAttributes<HTMLTableSectionElement>, HTMLTableSectionElement>, "ref"> & import("react").RefAttributes<HTMLTableSectionElement>>;
+import { type DataTableBodyProps } from './DataTableBody.types';
+export declare const DataTableBody: import("react").ForwardRefExoticComponent<Omit<DataTableBodyProps, "ref"> & import("react").RefAttributes<HTMLTableSectionElement>>;

package/dist/src/DataTable/DataTableBody/DataTableBody.js

@@ -1,19 +1,83 @@
-import { jsx as _jsx } from "react/jsx-runtime";
-import { forwardRef } from 'react';
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Children, cloneElement, forwardRef, Fragment, isValidElement, useCallback, useEffect, useMemo, useState, } from 'react';
+import { useVirtualizedRows, VIRTUAL_ROW_INDEX_ATTRIBUTE } from './hooks/useVirtualizedRows';
 import { dataTableBodySlotRecipe } from '../../../styled-system/recipes';
 import { cx } from '../../../styled-system/css';
 import { useDataTableContext } from '../DataTableProvider';
 import { DataTableRow } from '../DataTableRow';
 import { DataTableCell } from '../DataTableCell';
+import { mergeRefs } from '../../utilities/dom/mergeRefs';
 const NUMBER_OF_LOADING_ROWS = 4;
-export const DataTableBody = forwardRef(({ className, ...props }, ref) => {
-    const { numberColumns, loading } = useDataTableContext();
+/**
+ * React 19 exposes the ref of an element through its props, while React 18 keeps it on the element
+ * itself. Both are supported peers, so both have to be read to merge rather than clobber a
+ * consumer-supplied ref on a row.
+ *
+ * @param element - The row element to read the ref from.
+ *
+ * @returns The ref the consumer put on the row, if any.
+ */
+function getRowRef(element) {
+    return element.props.ref ?? element.ref;
+}
+export const DataTableBody = forwardRef(({ className, children, enableVirtualization = false, virtualizationOptions, ...props }, ref) => {
+    const { numberColumns, loading, scrollElement, setVirtualizedRowCount, headerRowCount } = useDataTableContext();
     const classes = dataTableBodySlotRecipe();
+    // The body is held in state so that its offset below the `<thead>` can be read while rendering.
+    const [bodyElement, setBodyElement] = useState(null);
+    const bodyRef = useMemo(() => mergeRefs(ref, setBodyElement), [ref]);
+    const rows = useMemo(() => (enableVirtualization ? Children.toArray(children) : []), [children, enableVirtualization]);
+    const isVirtualized = enableVirtualization && !loading;
+    // `Children.toArray` gives every element a key, so measured heights stay with their row on reorder.
+    const getRowKey = useCallback((index) => {
+        const row = rows[index];
+        return isValidElement(row) && row.key != null ? row.key : index;
+    }, [rows]);
+    // Called before the `loading` branch below returns, so that the hook order stays stable.
+    const { virtualRows, paddingTop, paddingBottom, measureElement } = useVirtualizedRows({
+        enabled: isVirtualized,
+        scrollElement,
+        rowCount: rows.length,
+        getItemKey: getRowKey,
+        scrollMargin: bodyElement?.offsetTop ?? 0,
+        ...virtualizationOptions,
+    });
+    // Only a window of the rows is mounted, so the table cannot count them. Publishing the real
+    // count is what lets the table report `aria-rowcount` instead of the mounted count.
+    useEffect(() => {
+        if (!isVirtualized)
+            return;
+        setVirtualizedRowCount(rows.length);
+        return () => {
+            setVirtualizedRowCount(null);
+        };
+    }, [isVirtualized, rows.length, setVirtualizedRowCount]);
+    const bodyClassName = cx(classes.root, 'mfui-DataTableBody__root', 
+    /* TODO: Remove in v5.0.0 */ 'mfui-DataGridBody__root', className);
     if (loading) {
-        return (_jsx("tbody", { className: cx(classes.root, 'mfui-DataTableBody__root', 
-            /* TODO: Remove in v5.0.0 */ 'mfui-DataGridBody__root', className), ...props, ref: ref, children: Array.from({ length: NUMBER_OF_LOADING_ROWS }).map((_, rowIndex) => (_jsx(DataTableRow, { children: Array.from({ length: numberColumns }).map((_, colIndex) => (_jsx(DataTableCell, {}, colIndex))) }, rowIndex))) }));
+        return (_jsx("tbody", { className: bodyClassName, ...props, ref: ref, children: Array.from({ length: NUMBER_OF_LOADING_ROWS }).map((_, rowIndex) => (_jsx(DataTableRow, { children: Array.from({ length: numberColumns }).map((_, colIndex) => (_jsx(DataTableCell, {}, colIndex))) }, rowIndex))) }));
     }
-    return (_jsx("tbody", { className: cx(classes.root, 'mfui-DataTableBody__root', 
-        /* TODO: Remove in v5.0.0 */ 'mfui-DataGridBody__root', className), ...props, ref: ref }));
+    if (!isVirtualized) {
+        return (_jsx("tbody", { className: bodyClassName, ...props, ref: ref, children: children }));
+    }
+    // `numberColumns` already counts the selection checkbox column, and falls back to a single
+    // column when the table renders no header row for it to count.
+    const spacerColSpan = Math.max(numberColumns, 1);
+    // The spacer stands in for the rows that are not mounted, so it reserves their height without
+    // being announced as a row of the table.
+    const renderSpacer = (position, height) => (_jsx("tr", { role: "presentation", "data-mfui-virtual-spacer": position, children: _jsx("td", { colSpan: spacerColSpan, className: classes.spacer, style: { height } }) }));
+    return (_jsxs("tbody", { className: bodyClassName, ...props, ref: bodyRef, children: [paddingTop > 0 ? renderSpacer('start', paddingTop) : null, virtualRows.map((virtualRow) => {
+                const child = rows[virtualRow.index];
+                // A `Fragment` cannot take the measuring ref or the ARIA attributes, so it is left as it is.
+                if (!isValidElement(child) || child.type === Fragment) {
+                    return child;
+                }
+                return cloneElement(child, {
+                    [VIRTUAL_ROW_INDEX_ATTRIBUTE]: virtualRow.index,
+                    // The header rows come first in the table, so the first data row is the row after them.
+                    'aria-rowindex': child.props['aria-rowindex'] ?? virtualRow.index + headerRowCount + 1,
+                    ref: mergeRefs(getRowRef(child), measureElement),
+                });
+            }), paddingBottom > 0 ? renderSpacer('end', paddingBottom) : null] }));
 });
 DataTableBody.displayName = 'DataTableBody';

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

@@ -1,4 +1,9 @@
 import { type ComponentPropsWithRef } from 'react';
+import { type VirtualizerOptions } from '@tanstack/react-virtual';
+/**
+ * The options for the row virtualization of the `DataTableBody` component.
+ */
+export type DataTableBodyVirtualizationOptions = Pick<VirtualizerOptions<HTMLElement, Element>, 'estimateSize' | 'overscan'>;
 /**
  * The props for the `DataTableBody` component.
  *
@@ -6,4 +11,79 @@ import { type ComponentPropsWithRef } from 'react';
  *
  * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/tbody
  */
-export type DataTableBodyProps = ComponentPropsWithRef<'tbody'>;
+export type DataTableBodyProps = {
+    /**
+     * Whether to render only the rows near the viewport (row virtualization).
+     *
+     * When enabled, the body mounts a window of its `DataTable.Row` children instead of all of them,
+     * and reserves the height of the rows it leaves out with spacer rows. This removes the DOM and
+     * mount cost of a large table, which is what dominates at thousands of rows.
+     * Note that the rows are still *created* by the consumer's own `map`, so creating the row elements
+     * stays O(number of rows).
+     *
+     * Row heights are measured as the rows mount, so rows whose content wraps to different heights
+     * are supported.
+     *
+     * Requirements:
+     *
+     * - An ancestor has to constrain the height of the `DataTable`, because the wrapper of the
+     *   `DataTable` is the element that scrolls and it is `height: 100%`.
+     * - The table has to use `table-layout: fixed` with explicit column widths. Column widths are
+     *   otherwise derived from the mounted rows only, so they shift while scrolling.
+     *   `getColumnWidthFromContentWidth` turns a content width into the matching column width.
+     *
+     * `aria-rowcount` on the table and `aria-rowindex` on each row are set for you, so that assistive
+     * technology is told the real row count rather than the number of mounted rows. Both stay
+     * overridable by the values you pass yourself.
+     *
+     * **Not supported together with merged cells.** A `rowSpan` reaches across rows that virtualization
+     * unmounts, so the merged cell is lost as soon as the row that owns it scrolls out of the window.
+     *
+     * **Each child has to be a single `DataTable.Row`.** A `Fragment` that groups several rows is
+     * windowed as one row and its rows are not measured, so pass the rows as a flat list instead.
+     *
+     * @default false
+     *
+     * @example
+     * ```tsx
+     * <div style={{ height: 500 }}>
+     *   <DataTable fixedHeader style={{ tableLayout: 'fixed' }}>
+     *     <colgroup>
+     *       <col style={{ width: getColumnWidthFromContentWidth(96, { position: 'first' }) }} />
+     *       <col />
+     *     </colgroup>
+     *     <DataTable.Header>
+     *       <DataTable.HeaderRow>
+     *         <DataTable.HeaderCell>行</DataTable.HeaderCell>
+     *         <DataTable.HeaderCell>エラー内容</DataTable.HeaderCell>
+     *       </DataTable.HeaderRow>
+     *     </DataTable.Header>
+     *     <DataTable.Body enableVirtualization>
+     *       {rows.map((row) => (
+     *         <DataTable.Row key={row.id}>
+     *           <DataTable.Cell>{row.line}</DataTable.Cell>
+     *           <DataTable.Cell>{row.message}</DataTable.Cell>
+     *         </DataTable.Row>
+     *       ))}
+     *     </DataTable.Body>
+     *   </DataTable>
+     * </div>
+     * ```
+     */
+    enableVirtualization?: boolean;
+    /**
+     * The configuration of the row virtualization.
+     * Only applies when `enableVirtualization` is `true`.
+     *
+     * @property estimateSize - The estimated height of a row in pixels, used until the row is measured. Defaults to `() => 44`.
+     * @property overscan - The number of rows rendered outside the visible area, on each side. Defaults to `8`.   *
+     * @example
+     * ```tsx
+     * <DataTable.Body
+     *   enableVirtualization
+     *   virtualizationOptions={{ estimateSize: () => 36, overscan: 12 }}
+     * >
+     * ```
+     */
+    virtualizationOptions?: DataTableBodyVirtualizationOptions;
+} & ComponentPropsWithRef<'tbody'>;

package/dist/src/DataTable/DataTableBody/hooks/useVirtualizedRows.d.ts

@@ -0,0 +1,64 @@
+import { type Key } from 'react';
+import { type VirtualItem } from '@tanstack/react-virtual';
+import { type DataTableBodyVirtualizationOptions } from '../DataTableBody.types';
+/**
+ * The attribute the virtualizer reads the row index from while measuring a mounted row.
+ * TanStack's default is `data-index`, which the repository's `data-mfui-` prefix rule forbids.
+ */
+export declare const VIRTUAL_ROW_INDEX_ATTRIBUTE = "data-mfui-index";
+export type UseVirtualizedRowsParams = {
+    /**
+     * Whether the rows are windowed.
+     */
+    enabled: boolean;
+    /**
+     * The element that scrolls the rows. It is `null` until it is mounted.
+     */
+    scrollElement: HTMLElement | null;
+    /**
+     * The total number of rows the body holds, not the number of mounted rows.
+     */
+    rowCount: number;
+    /**
+     * The distance in pixels from the top of the scroll element's content to the first row,
+     * which is the height of the `<thead>` above the body.
+     */
+    scrollMargin: number;
+    /**
+     * Returns a stable key for the row at the index, so that measured heights follow the row
+     * rather than its position when rows are reordered.
+     */
+    getItemKey?: (index: number) => Key;
+} & Partial<DataTableBodyVirtualizationOptions>;
+export type UseVirtualizedRowsReturn = {
+    /**
+     * The rows to mount, which is the visible rows plus the overscan.
+     * It is empty when virtualization is disabled.
+     */
+    virtualRows: VirtualItem[];
+    /**
+     * The height in pixels the spacer row before the window has to reserve.
+     */
+    paddingTop: number;
+    /**
+     * The height in pixels the spacer row after the window has to reserve.
+     */
+    paddingBottom: number;
+    /**
+     * The ref callback that measures a mounted row.
+     * The row must carry the index in {@link VIRTUAL_ROW_INDEX_ATTRIBUTE}.
+     */
+    measureElement: (node: Element | null) => void;
+};
+/**
+ * Windows the rows of a `DataTable.Body` with `@tanstack/react-virtual`, so that only the rows near
+ * the viewport are mounted.
+ *
+ * Rows are measured as they mount rather than trusted to `estimateSize`, so rows whose content wraps
+ * to different heights are supported.
+ *
+ * @param params - The virtualization configuration.
+ *
+ * @returns The rows to mount and the spacer heights that stand in for the rows that are not mounted.
+ */
+export declare function useVirtualizedRows({ enabled, scrollElement, rowCount, scrollMargin, estimateSize, overscan, getItemKey, }: UseVirtualizedRowsParams): UseVirtualizedRowsReturn;

package/dist/src/DataTable/DataTableBody/hooks/useVirtualizedRows.js

@@ -0,0 +1,53 @@
+import { useVirtualizer } from '@tanstack/react-virtual';
+/**
+ * The attribute the virtualizer reads the row index from while measuring a mounted row.
+ * TanStack's default is `data-index`, which the repository's `data-mfui-` prefix rule forbids.
+ */
+export const VIRTUAL_ROW_INDEX_ATTRIBUTE = 'data-mfui-index';
+/**
+ * The estimated height of a row in pixels, used before a row has been measured.
+ * It only affects the scroll range of the not-yet-mounted rows, because every mounted row is
+ * measured for real.
+ */
+const DEFAULT_ESTIMATED_ROW_HEIGHT = 44;
+/**
+ * The number of rows rendered outside the visible area, on each side.
+ */
+const DEFAULT_OVERSCAN = 8;
+/**
+ * Windows the rows of a `DataTable.Body` with `@tanstack/react-virtual`, so that only the rows near
+ * the viewport are mounted.
+ *
+ * Rows are measured as they mount rather than trusted to `estimateSize`, so rows whose content wraps
+ * to different heights are supported.
+ *
+ * @param params - The virtualization configuration.
+ *
+ * @returns The rows to mount and the spacer heights that stand in for the rows that are not mounted.
+ */
+export function useVirtualizedRows({ enabled, scrollElement, rowCount, scrollMargin, estimateSize = () => DEFAULT_ESTIMATED_ROW_HEIGHT, overscan = DEFAULT_OVERSCAN, getItemKey, }) {
+    // Always call useVirtualizer to keep the hook order stable, but with 0 count when disabled.
+    const virtualizer = useVirtualizer({
+        count: enabled ? rowCount : 0,
+        getScrollElement: () => scrollElement,
+        estimateSize,
+        overscan,
+        enabled,
+        getItemKey,
+        indexAttribute: VIRTUAL_ROW_INDEX_ATTRIBUTE,
+        // The rows start below the `<thead>`, not at the top of the scroll element, so without the margin
+        // the window would be shifted down by the header height.
+        scrollMargin,
+    });
+    const virtualRows = enabled ? virtualizer.getVirtualItems() : [];
+    const [firstVirtualRow] = virtualRows;
+    const lastVirtualRow = virtualRows.at(-1);
+    // `start` / `end` include the scroll margin while `getTotalSize()` does not, so the margin is
+    // removed to get distances within the body.
+    return {
+        virtualRows,
+        paddingTop: firstVirtualRow ? firstVirtualRow.start - scrollMargin : 0,
+        paddingBottom: lastVirtualRow ? virtualizer.getTotalSize() - (lastVirtualRow.end - scrollMargin) : 0,
+        measureElement: virtualizer.measureElement,
+    };
+}

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

@@ -1,2 +1,2 @@
 export { DataTableBody } from './DataTableBody';
-export type { DataTableBodyProps } from './DataTableBody.types';
+export type { DataTableBodyProps, DataTableBodyVirtualizationOptions } from './DataTableBody.types';

package/dist/src/DataTable/DataTableHeader/DataTableHeader.js

@@ -1,12 +1,23 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { forwardRef } from 'react';
+import { Children, cloneElement, forwardRef, isValidElement } from 'react';
 import { dataTableHeaderSlotRecipe } from '../../../styled-system/recipes';
 import { useDataTableContext } from '../DataTableProvider';
+import { DataTableHeaderRow } from '../DataTableHeaderRow';
 import { cx } from '../../../styled-system/css';
+import { isComponentOrWrapped } from '../../utilities/react/isComponentOrWrapped';
 export const DataTableHeader = forwardRef(({ children, className, ...props }, ref) => {
     const { fixedHeader } = useDataTableContext();
     const classes = dataTableHeaderSlotRecipe({ fixedHeader });
+    // Each header row needs its own position for `aria-rowindex`, which only the header can tell.
+    const items = Children.toArray(children);
+    const headerRows = items.filter((child) => isValidElement(child) && isComponentOrWrapped(child, DataTableHeaderRow));
     return (_jsx("thead", { className: cx(classes.root, 'mfui-DataTableHeader__root', 
-        /* TODO: Remove in v5.0.0 */ 'mfui-DataGridHeader__root', className), ...props, ref: ref, children: children }));
+        /* TODO: Remove in v5.0.0 */ 'mfui-DataGridHeader__root', className), ...props, ref: ref, children: items.map((child) => {
+            const headerRowIndex = headerRows.indexOf(child) + 1;
+            if (headerRowIndex === 0 || !isValidElement(child)) {
+                return child;
+            }
+            return cloneElement(child, { headerRowIndex });
+        }) }));
 });
 DataTableHeader.displayName = 'DataTableHeader';

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

@@ -9,7 +9,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 DataTableHeaderCell = forwardRef(({ children, type = 'text', sortButtonProps, sortOrder, actions, ascendingIconProps, descendingIconProps, unsortedIconProps, className, columnIndex, disabled = false, ...props }, ref) => {
+export const DataTableHeaderCell = forwardRef(({ children, type = 'text', sortButtonProps, sortOrder, actions, ascendingIconProps, descendingIconProps, unsortedIconProps, className, columnIndex, disabled = false, style, ...props }, ref) => {
     const { size, leftFixedColumnIndex, rightFixedColumnIndex, enableRowSelection, showVerticalBorder } = useDataTableContext();
     const { cellRef, isFixedColumn, isEdgeFixedColumn, fixedPositionStyles } = useFixedColumns({
         enableRowSelection,
@@ -62,6 +62,9 @@ export const DataTableHeaderCell = forwardRef(({ children, type = 'text', sortBu
         // 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 }));
+        /* TODO: Remove in v5.0.0 */ 'mfui-DataGridHeaderCell__root', className), "aria-sort": sortOrder, ...props, 
+        // Merged rather than replaced, so that a consumer `style` (e.g. the column `width`) keeps the
+        // sticky offsets of a fixed column, as `DataTableCell` does.
+        style: { ...style, ...fixedPositionStyles }, children: cellContentWithActions }));
 });
 DataTableHeaderCell.displayName = 'DataTableHeaderCell';