@moneyforward/mfui-components 4.6.0 → 4.8.0

package/dist/src/DataTable/DataTableHeaderRow/DataTableHeaderRow.js

@@ -1,35 +1,54 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cloneElement, forwardRef, isValidElement, useEffect } from 'react';
-import { dataTableHeaderRowSlotRecipe } from '../../../styled-system/recipes';
+import { dataTableHeaderRowSlotRecipe, dataTableSlotRecipe } from '../../../styled-system/recipes';
 import { useDataTableContext } from '../DataTableProvider';
 import { DataTableHeaderCell } from '../DataTableHeaderCell';
 import { Checkbox } from '../../Checkbox';
 import { cx } from '../../../styled-system/css';
 import { isComponentOrWrapped } from '../../utilities/react/isComponentOrWrapped';
 import { flattenChildren } from '../../utilities/react/flattenChildren';
-export const DataTableHeaderRow = forwardRef(({ children, checkboxProps, className, ...props }, ref) => {
-    const { enableRowSelection, setNumberColumns } = useDataTableContext();
+import { useIsomorphicLayoutEffect } from '../../utilities/react/useIsomorphicLayoutEffect';
+import { renderVirtualizedColumns } from '../utils/renderVirtualizedColumns';
+export const DataTableHeaderRow = forwardRef(({ children, checkboxProps, className, headerRowIndex = 1, ...props }, ref) => {
+    const { enableRowSelection, setNumberColumns, registerHeaderRow, virtualizedRowCount, columnWindow, reportDeclaredColumnWidths, } = useDataTableContext();
     const classes = dataTableHeaderRowSlotRecipe();
+    const isColumnVirtualized = columnWindow !== null;
+    // A virtualized body offsets the `aria-rowindex` of its rows by the number of header rows, which
+    // only the header rows themselves can report.
+    useEffect(() => registerHeaderRow(), [registerHeaderRow]);
     // Building the element before wrapping keeps everything the header row owns on the Checkbox itself.
     const selectionCheckbox = (_jsx(Checkbox, { checked: checkboxProps?.checked, indeterminate: checkboxProps?.indeterminate, "aria-label": checkboxProps?.['aria-label'] ?? 'すべての行を選択', disabled: checkboxProps?.disabled, onChange: checkboxProps?.onChange, onClick: checkboxProps?.onClick }));
     // Count the number of header cells, plus the selection checkbox column rendered
     // below when `enableRowSelection` is on (it isn't part of `children`).
-    useEffect(() => {
+    // Every cell is counted rather than the mounted ones, so that the count stays the total number
+    // of columns while the columns are virtualized.
+    // While the columns are virtualized, the declared width of every header cell is reported as well,
+    // for the `<colgroup>` the table renders. This runs as a layout effect so that the table re-renders
+    // with its `<col>` elements before the first paint, rather than one frame later.
+    useIsomorphicLayoutEffect(() => {
         const headerCells = flattenChildren(children).filter((child) => isValidElement(child) && isComponentOrWrapped(child, DataTableHeaderCell));
         setNumberColumns(headerCells.length + (enableRowSelection ? 1 : 0));
-    }, [children, enableRowSelection, setNumberColumns]);
+        if (isColumnVirtualized) {
+            reportDeclaredColumnWidths(headerCells.map((cell) => cell.props.style?.width));
+        }
+    }, [children, enableRowSelection, isColumnVirtualized, setNumberColumns, reportDeclaredColumnWidths]);
     return (_jsxs("tr", { className: cx(classes.root, 'mfui-DataTableHeaderRow__root', 
-        /* TODO: Remove in v5.0.0 */ 'mfui-DataGridHeaderRow__root', className), ...props, ref: ref, children: [enableRowSelection ? (_jsx(DataTableHeaderCell, { columnIndex: 0, disabled: checkboxProps?.disabled, children: checkboxProps?.wrapper ? checkboxProps.wrapper(selectionCheckbox) : selectionCheckbox })) : null, flattenChildren(children).map((child, index) => {
-                if (!isValidElement(child)) {
-                    return child;
-                }
-                // Check if the component is DataTableHeaderCell or wraps DataTableHeaderCell
-                if (isComponentOrWrapped(child, DataTableHeaderCell)) {
-                    // Add selectable offset to columnIndex if selectable is true
-                    const columnIndex = enableRowSelection ? index + 1 : index;
-                    return cloneElement(child, { columnIndex });
-                }
-                return child;
+        /* TODO: Remove in v5.0.0 */ 'mfui-DataGridHeaderRow__root', className), ...(virtualizedRowCount !== null && { 'aria-rowindex': headerRowIndex }), ...props, ref: ref, children: [enableRowSelection ? (_jsx(DataTableHeaderCell, { columnIndex: 0, disabled: checkboxProps?.disabled, ...(isColumnVirtualized && { 'aria-colindex': 1 }), children: checkboxProps?.wrapper ? checkboxProps.wrapper(selectionCheckbox) : selectionCheckbox })) : null, renderVirtualizedColumns({
+                cells: flattenChildren(children),
+                // Add selectable offset to columnIndex if selectable is true
+                columnOffset: enableRowSelection ? 1 : 0,
+                columnWindow,
+                spacerClassName: cx(dataTableSlotRecipe().headerColumnSpacer, 'mfui-DataTable__headerColumnSpacer'),
+                renderCell: (child, columnIndex) => {
+                    // Check if the component is DataTableHeaderCell or wraps DataTableHeaderCell
+                    if (!isValidElement(child) || !isComponentOrWrapped(child, DataTableHeaderCell)) {
+                        return child;
+                    }
+                    return cloneElement(child, {
+                        columnIndex,
+                        ...(isColumnVirtualized && { 'aria-colindex': child.props['aria-colindex'] ?? columnIndex + 1 }),
+                    });
+                },
             })] }));
 });
 DataTableHeaderRow.displayName = 'DataTableHeaderRow';

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

@@ -44,4 +44,13 @@ export type DataTableHeaderRowProps = {
     checkboxProps?: Pick<CheckboxProps, 'aria-label' | 'checked' | 'indeterminate' | 'onChange' | 'disabled' | 'onClick'> & {
         wrapper?: DataTableSelectionCheckboxWrapper;
     };
+    /**
+     * **Do not pass this prop manually.**
+     *
+     * The 1-based position of this row among the header rows.
+     * Used for the `aria-rowindex` of the row while the body is virtualized.
+     *
+     * @default undefined
+     */
+    headerRowIndex?: number;
 } & ComponentPropsWithRef<'tr'>;

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

@@ -1,14 +1,56 @@
 import { type PropsWithChildren } from 'react';
 import { type DataTableProps } from './DataTable.types';
+import { type DataTableColumnWindow } from './hooks/useVirtualizedColumns';
+import { type DeclaredColumnWidth } from './utils/resolveColumnWidths';
 export type DataTableSize = 'small' | 'medium';
 /**
  * The props for the `DataTableContext` component.
  */
 export type DataTableContextProps = Pick<DataTableProps, 'size' | 'enableRowSelection' | 'enableRowClickSelection' | 'fixedHeader' | 'showVerticalBorder' | 'leftFixedColumnIndex' | 'rightFixedColumnIndex' | 'loading' | 'layout'>;
-export type DataTableProviderValues = {
+/**
+ * The values the `DataTable` owns and shares with its composition components.
+ *
+ * This should only be used in DataTable component.
+ */
+export type DataTableVirtualizationValues = {
+    /**
+     * The wrapper element of the table, which is the element that scrolls.
+     * It is `null` until the wrapper is mounted, and when the body is used outside a `DataTable`.
+     */
+    scrollElement: HTMLElement | null;
+    /**
+     * The number of rows the body holds while it is virtualized, or `null` when it is not.
+     * The body publishes it so that the table can report the real row count to assistive technology
+     * even though only a window of rows is mounted.
+     */
+    virtualizedRowCount: number | null;
+    setVirtualizedRowCount: (rowCount: number | null) => void;
+    /**
+     * The number of mounted header rows, which offsets the `aria-rowindex` of the body rows.
+     */
+    headerRowCount: number;
+    /**
+     * Registers a header row and returns the function to unregister it.
+     */
+    registerHeaderRow: () => () => void;
+    /**
+     * The columns each row mounts while the columns are virtualized, or `null` when they are not.
+     * The table computes it once so that the header row and every row window the same columns.
+     */
+    columnWindow: DataTableColumnWindow | null;
+    /**
+     * Reports the `style.width` of every header cell, mounted or not, which the table turns into the
+     * widths of its `<col>` elements while the columns are virtualized.
+     */
+    reportDeclaredColumnWidths: (widths: readonly DeclaredColumnWidth[]) => void;
+    /**
+     * The total number of columns, counted by the header row from all of its cells rather than the
+     * mounted ones, plus the selection checkbox column.
+     */
     numberColumns: number;
     setNumberColumns: (number: number) => void;
-} & DataTableContextProps;
+};
+export type DataTableProviderValues = DataTableContextProps & DataTableVirtualizationValues;
 /**
  * The context for the `DataTable` component.
  *
@@ -24,4 +66,4 @@ export declare const useDataTableContext: () => DataTableProviderValues;
  *
  * This should only be used in DataTable component.
  */
-export declare function DataTableProvider({ children, size, enableRowSelection, enableRowClickSelection, fixedHeader, showVerticalBorder, leftFixedColumnIndex, rightFixedColumnIndex, loading, layout, }: PropsWithChildren<DataTableContextProps>): import("react/jsx-runtime").JSX.Element;
+export declare function DataTableProvider({ children, size, enableRowSelection, enableRowClickSelection, fixedHeader, showVerticalBorder, leftFixedColumnIndex, rightFixedColumnIndex, loading, layout, scrollElement, virtualizedRowCount, setVirtualizedRowCount, headerRowCount, registerHeaderRow, columnWindow, reportDeclaredColumnWidths, numberColumns, setNumberColumns, }: PropsWithChildren<DataTableContextProps & DataTableVirtualizationValues>): import("react/jsx-runtime").JSX.Element;

package/dist/src/DataTable/DataTableProvider.js

@@ -1,6 +1,6 @@
 'use client';
 import { jsx as _jsx } from "react/jsx-runtime";
-import { createContext, useContext, useMemo, useState } from 'react';
+import { createContext, useContext, useMemo } from 'react';
 /**
  * The context for the `DataTable` component.
  *
@@ -19,6 +19,19 @@ export const DataTableContext = createContext({
     setNumberColumns: () => {
         // Do nothing
     },
+    scrollElement: null,
+    virtualizedRowCount: null,
+    setVirtualizedRowCount: () => {
+        // Do nothing
+    },
+    headerRowCount: 0,
+    registerHeaderRow: () => () => {
+        // Do nothing
+    },
+    columnWindow: null,
+    reportDeclaredColumnWidths: () => {
+        // Do nothing
+    },
 });
 /**
  * The hook to use the `DataTableContext`.
@@ -29,8 +42,7 @@ export const useDataTableContext = () => useContext(DataTableContext);
  *
  * This should only be used in DataTable component.
  */
-export function DataTableProvider({ children, size = 'medium', enableRowSelection = false, enableRowClickSelection = false, fixedHeader = false, showVerticalBorder = false, leftFixedColumnIndex, rightFixedColumnIndex, loading, layout = 'default', }) {
-    const [numberColumns, setNumberColumns] = useState(0);
+export function DataTableProvider({ children, size = 'medium', enableRowSelection = false, enableRowClickSelection = false, fixedHeader = false, showVerticalBorder = false, leftFixedColumnIndex, rightFixedColumnIndex, loading, layout = 'default', scrollElement, virtualizedRowCount, setVirtualizedRowCount, headerRowCount, registerHeaderRow, columnWindow, reportDeclaredColumnWidths, numberColumns, setNumberColumns, }) {
     const contextValue = useMemo(() => ({
         size,
         enableRowSelection,
@@ -43,6 +55,13 @@ export function DataTableProvider({ children, size = 'medium', enableRowSelectio
         layout,
         numberColumns,
         setNumberColumns,
+        scrollElement,
+        virtualizedRowCount,
+        setVirtualizedRowCount,
+        headerRowCount,
+        registerHeaderRow,
+        columnWindow,
+        reportDeclaredColumnWidths,
     }), [
         size,
         enableRowSelection,
@@ -54,6 +73,14 @@ export function DataTableProvider({ children, size = 'medium', enableRowSelectio
         loading,
         layout,
         numberColumns,
+        setNumberColumns,
+        scrollElement,
+        virtualizedRowCount,
+        setVirtualizedRowCount,
+        headerRowCount,
+        registerHeaderRow,
+        columnWindow,
+        reportDeclaredColumnWidths,
     ]);
     return _jsx(DataTableContext.Provider, { value: contextValue, children: children });
 }

package/dist/src/DataTable/DataTableRow/DataTableRow.js

@@ -1,7 +1,8 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cloneElement, forwardRef, isValidElement, useCallback, useMemo, useRef, useState } from 'react';
 import { DataTableRowActionContext, } from '../DataTableRowActionContext';
-import { dataTableRowSlotRecipe } from '../../../styled-system/recipes';
+import { dataTableRowSlotRecipe, dataTableSlotRecipe } from '../../../styled-system/recipes';
+import { renderVirtualizedColumns } from '../utils/renderVirtualizedColumns';
 import { DataTableCell } from '../DataTableCell';
 import { Checkbox } from '../../Checkbox';
 import { useDataTableContext } from '../DataTableProvider';
@@ -50,7 +51,8 @@ function isClickFromNestedInteractiveElement(event) {
     return !interactiveElement.matches(ROW_ACTION_BUTTON_SELECTOR);
 }
 export const DataTableRow = forwardRef(({ children, disabled = false, highlighted, checkboxProps, className, onClickRow, rowActionButtonProps, selectable, 'aria-expanded': ariaExpandedProp, ...props }, ref) => {
-    const { enableRowSelection: contextEnableRowSelection, enableRowClickSelection, layout } = useDataTableContext();
+    const { enableRowSelection: contextEnableRowSelection, enableRowClickSelection, layout, columnWindow, } = useDataTableContext();
+    const isColumnVirtualized = columnWindow !== null;
     const selectionCheckboxRef = useRef(null);
     const isSelectable = selectable ?? contextEnableRowSelection;
     // A selected row is always highlighted, and `highlighted` stays an independent signal on top of it,
@@ -159,16 +161,23 @@ export const DataTableRow = forwardRef(({ children, disabled = false, highlighte
         onClickRow?.(event);
     };
     return (_jsx(DataTableRowActionContext.Provider, { value: rowActionContextValue, children: _jsxs("tr", { ref: ref, className: cx(classes.root, 'mfui-DataTableRow__root', 
-            /* TODO: Remove in v5.0.0 */ 'mfui-DataGridRow__root', className), ...(!hasRowActionButton && ariaExpandedProp !== undefined && { 'aria-expanded': ariaExpandedProp }), ...props, ...(disabled && { 'aria-disabled': disabled }), onClick: handleClickRow, children: [isSelectable ? (_jsx(DataTableCell, { columnIndex: 0, isRowHighlighted: isRowHighlighted, disabled: disabled, children: checkboxProps?.wrapper ? checkboxProps.wrapper(selectionCheckbox) : selectionCheckbox })) : null, flatChildren.map((child, index) => {
-                    if (!isValidElement(child)) {
-                        return child;
-                    }
-                    if (isComponentOrWrapped(child, DataTableCell)) {
-                        // Add selectable offset to columnIndex if selectable is true
-                        const columnIndex = isSelectable ? index + 1 : index;
-                        return cloneElement(child, { isRowHighlighted, columnIndex, disabled });
-                    }
-                    return child;
+            /* TODO: Remove in v5.0.0 */ 'mfui-DataGridRow__root', className), ...(!hasRowActionButton && ariaExpandedProp !== undefined && { 'aria-expanded': ariaExpandedProp }), ...props, ...(disabled && { 'aria-disabled': disabled }), onClick: handleClickRow, children: [isSelectable ? (_jsx(DataTableCell, { columnIndex: 0, isRowHighlighted: isRowHighlighted, disabled: disabled, ...(isColumnVirtualized && { 'aria-colindex': 1 }), children: checkboxProps?.wrapper ? checkboxProps.wrapper(selectionCheckbox) : selectionCheckbox })) : null, renderVirtualizedColumns({
+                    cells: flatChildren,
+                    // Add selectable offset to columnIndex if selectable is true
+                    columnOffset: isSelectable ? 1 : 0,
+                    columnWindow,
+                    spacerClassName: cx(dataTableSlotRecipe().columnSpacer, 'mfui-DataTable__columnSpacer'),
+                    renderCell: (child, columnIndex) => {
+                        if (!isCellElement(child)) {
+                            return child;
+                        }
+                        return cloneElement(child, {
+                            isRowHighlighted,
+                            columnIndex,
+                            disabled,
+                            ...(isColumnVirtualized && { 'aria-colindex': child.props['aria-colindex'] ?? columnIndex + 1 }),
+                        });
+                    },
                 })] }) }));
 });
 DataTableRow.displayName = 'DataTableRow';

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

@@ -0,0 +1,73 @@
+import { type DataTableColumnVirtualizationOptions } from '../DataTable.types';
+/**
+ * The columns of a row that are mounted while the columns are virtualized.
+ *
+ * Every index is a grid column index, which counts the selection checkbox column as column 0
+ * when the rows are selectable, and every end is exclusive.
+ * A row mounts `[0, prefixEnd)`, `[windowStart, windowEnd)` and `[suffixStart, end of row)`,
+ * and fills each gap between them with a single spacer cell.
+ */
+export type DataTableColumnWindow = {
+    /**
+     * The end of the always-mounted columns on the left: the selection checkbox column, the first
+     * consumer column and the left fixed columns.
+     */
+    prefixEnd: number;
+    /**
+     * The first column of the window of scrollable columns that is mounted.
+     */
+    windowStart: number;
+    /**
+     * The end of the window of scrollable columns that is mounted.
+     */
+    windowEnd: number;
+    /**
+     * The first of the always-mounted right fixed columns, or `undefined` without right fixed columns.
+     */
+    suffixStart: number | undefined;
+};
+export type UseVirtualizedColumnsParams = {
+    /**
+     * Whether the columns are windowed.
+     */
+    enabled: boolean;
+    /**
+     * The element that scrolls the columns. It is `null` until it is mounted.
+     */
+    scrollElement: HTMLElement | null;
+    /**
+     * The table, whose first row is measured for the width of the always-mounted left columns.
+     */
+    tableRef: React.RefObject<HTMLTableElement | null>;
+    /**
+     * The total number of grid columns, including the selection checkbox column.
+     */
+    columnCount: number;
+    /**
+     * The number of columns that come before the consumer's columns, which is 1 when the rows are
+     * selectable and 0 otherwise.
+     */
+    selectionColumnCount: number;
+    /**
+     * The width of each consumer column in pixels, which is also the width of its `<col>`.
+     */
+    columnWidths: readonly number[];
+    leftFixedColumnIndex?: number;
+    rightFixedColumnIndex?: number;
+} & Pick<DataTableColumnVirtualizationOptions, 'overscan'>;
+/**
+ * Windows the columns of a `DataTable` with `@tanstack/react-virtual`, so that only the columns
+ * near the viewport are mounted.
+ *
+ * Only the columns between the left and the right fixed columns are windowed. The first column,
+ * after the selection checkbox column, is always mounted as well, because it hosts the row action
+ * button of a row that is not selectable and usually the row header.
+ *
+ * The columns are never measured: under `table-layout: fixed` each column is exactly as wide as its
+ * `<col>`, so the declared widths are the real ones.
+ *
+ * @param params - The virtualization configuration.
+ *
+ * @returns The columns to mount, or `null` when virtualization is disabled.
+ */
+export declare function useVirtualizedColumns({ enabled, scrollElement, tableRef, columnCount, selectionColumnCount, columnWidths, leftFixedColumnIndex, rightFixedColumnIndex, overscan, }: UseVirtualizedColumnsParams): DataTableColumnWindow | null;

package/dist/src/DataTable/hooks/useVirtualizedColumns.js

@@ -0,0 +1,109 @@
+import { useMemo, useRef, useState } from 'react';
+import { useVirtualizer } from '@tanstack/react-virtual';
+import { useIsomorphicLayoutEffect } from '../../utilities/react/useIsomorphicLayoutEffect';
+import { DEFAULT_COLUMN_WIDTH } from '../utils/resolveColumnWidths';
+/**
+ * The number of columns rendered outside the visible area, on each side.
+ */
+const DEFAULT_OVERSCAN = 2;
+/**
+ * Windows the columns of a `DataTable` with `@tanstack/react-virtual`, so that only the columns
+ * near the viewport are mounted.
+ *
+ * Only the columns between the left and the right fixed columns are windowed. The first column,
+ * after the selection checkbox column, is always mounted as well, because it hosts the row action
+ * button of a row that is not selectable and usually the row header.
+ *
+ * The columns are never measured: under `table-layout: fixed` each column is exactly as wide as its
+ * `<col>`, so the declared widths are the real ones.
+ *
+ * @param params - The virtualization configuration.
+ *
+ * @returns The columns to mount, or `null` when virtualization is disabled.
+ */
+export function useVirtualizedColumns({ enabled, scrollElement, tableRef, columnCount, selectionColumnCount, columnWidths, leftFixedColumnIndex, rightFixedColumnIndex, overscan = DEFAULT_OVERSCAN, }) {
+    // The first consumer column stays mounted even without left fixed columns: it hosts the row action
+    // button of a row that is not selectable, and the row header that names each row.
+    const prefixEnd = selectionColumnCount + Math.max(leftFixedColumnIndex ?? 0, 0) + 1;
+    const suffixStart = rightFixedColumnIndex === undefined ? undefined : selectionColumnCount + rightFixedColumnIndex;
+    const scrollableColumnCount = Math.max(0, Math.min(suffixStart ?? columnCount, columnCount) - prefixEnd);
+    // The scrollable columns start after the always-mounted left columns, not at the left edge of the
+    // scroll element, so without the margin the window would be shifted right by their width.
+    // It is measured rather than summed from the widths, because the width of the selection column is
+    // a CSS expression of design tokens.
+    const [scrollMargin, setScrollMargin] = useState(0);
+    const hasWarnedDuplicateColgroup = useRef(false);
+    useIsomorphicLayoutEffect(() => {
+        const table = tableRef.current;
+        if (!enabled || !table)
+            return;
+        const measureScrollMargin = () => {
+            const cells = table.rows[0]?.cells;
+            let width = 0;
+            for (let index = 0; index < prefixEnd; index++) {
+                width += cells?.[index]?.offsetWidth ?? 0;
+            }
+            setScrollMargin(width);
+        };
+        measureScrollMargin();
+        // The always-mounted columns resize with the table, e.g. when the wrapper is resized.
+        const resizeObserver = new ResizeObserver(measureScrollMargin);
+        resizeObserver.observe(table);
+        return () => {
+            resizeObserver.disconnect();
+        };
+    }, [enabled, tableRef, prefixEnd, columnCount]);
+    // The table skips its own `<colgroup>` only when it finds the consumer's among its direct children,
+    // so a `<colgroup>` rendered by a consumer component ends up next to the table's without any error.
+    useIsomorphicLayoutEffect(() => {
+        const table = tableRef.current;
+        if (process.env['NODE_ENV'] === 'production' || !enabled || !table || hasWarnedDuplicateColgroup.current)
+            return;
+        if (table.querySelectorAll(':scope > colgroup').length > 1) {
+            hasWarnedDuplicateColgroup.current = true;
+            console.warn('[MFUI] DataTable received enableColumnVirtualization and found more than one <colgroup>. ' +
+                'Pass your <colgroup> element directly as a child of DataTable so that DataTable skips its own, ' +
+                'or remove it and let DataTable declare the columns from columnVirtualizationOptions.getColumnWidth ' +
+                'and the style.width of each DataTable.HeaderCell.');
+        }
+    });
+    // Always call useVirtualizer to keep the hook order stable, but with 0 count when disabled.
+    const virtualizer = useVirtualizer({
+        count: enabled ? scrollableColumnCount : 0,
+        horizontal: true,
+        getScrollElement: () => scrollElement,
+        // The widths count the consumer columns, as `leftFixedColumnIndex` does, without the selection column.
+        estimateSize: (index) => columnWidths[prefixEnd + index - selectionColumnCount] ?? DEFAULT_COLUMN_WIDTH,
+        overscan,
+        enabled,
+        // Keyed by the grid column, so that a column keeps its key when the number of fixed columns changes.
+        getItemKey: (index) => prefixEnd + index,
+        scrollMargin,
+    });
+    // The virtualizer keeps its item sizes until it is told to recompute them, so a column whose
+    // width changes would otherwise keep its old offset. The widths are compared by value, because
+    // `getColumnWidth` is usually an inline function and they are resolved again on every render.
+    const columnWidthsKey = columnWidths.join(',');
+    const previousColumnWidthsKey = useRef(columnWidthsKey);
+    useIsomorphicLayoutEffect(() => {
+        if (previousColumnWidthsKey.current === columnWidthsKey)
+            return;
+        previousColumnWidthsKey.current = columnWidthsKey;
+        virtualizer.measure();
+    }, [columnWidthsKey, virtualizer]);
+    const virtualColumns = enabled ? virtualizer.getVirtualItems() : [];
+    const firstIndex = virtualColumns[0]?.index;
+    const lastIndex = virtualColumns.at(-1)?.index;
+    // Kept referentially stable while the mounted columns stay the same, so that the rows only
+    // re-render when the window actually moves.
+    return useMemo(() => {
+        if (!enabled)
+            return null;
+        return {
+            prefixEnd,
+            windowStart: firstIndex === undefined ? prefixEnd : prefixEnd + firstIndex,
+            windowEnd: lastIndex === undefined ? prefixEnd : prefixEnd + lastIndex + 1,
+            suffixStart,
+        };
+    }, [enabled, prefixEnd, firstIndex, lastIndex, suffixStart]);
+}

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

@@ -1,7 +1,7 @@
 export { DataTable } from './DataTable';
 export { getColumnWidthFromContentWidth } from './utils/getColumnWidthFromContentWidth';
-export type { DataTableProps } from './DataTable.types';
-export type { DataTableBodyProps } from './DataTableBody';
+export type { DataTableProps, DataTableColumnVirtualizationOptions } from './DataTable.types';
+export type { DataTableBodyProps, DataTableBodyVirtualizationOptions } from './DataTableBody';
 export type { DataTableCellProps } from './DataTableCell';
 export type { DataTableHeaderProps } from './DataTableHeader';
 export type { DataTableHeaderCellProps } from './DataTableHeaderCell';

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

@@ -0,0 +1,11 @@
+/**
+ * The width of the selection checkbox column.
+ *
+ * The checkbox cell is always the table's start-edge cell, so its border-box has to hold the
+ * start-edge padding from `_first` as well as the inner cell's padding around the checkbox.
+ * Otherwise the checkbox overflows into the next column under `table-layout: fixed`.
+ *
+ * The header cell, the body cell and the `<col>` that `DataTable` renders for column virtualization
+ * all take the width from here, so that they cannot disagree.
+ */
+export declare const SELECTION_COLUMN_WIDTH = "[calc({sizes.mfui.size.dimension.icon.square.comfort} + {spacing.mfui.size.padding.data-table-cell.horizontal.comfort} * 2 + {spacing.mfui.size.padding.container.horizontal.comfort})]";

package/dist/src/DataTable/shared/commonStyles.js

@@ -0,0 +1,11 @@
+/**
+ * The width of the selection checkbox column.
+ *
+ * The checkbox cell is always the table's start-edge cell, so its border-box has to hold the
+ * start-edge padding from `_first` as well as the inner cell's padding around the checkbox.
+ * Otherwise the checkbox overflows into the next column under `table-layout: fixed`.
+ *
+ * The header cell, the body cell and the `<col>` that `DataTable` renders for column virtualization
+ * all take the width from here, so that they cannot disagree.
+ */
+export const SELECTION_COLUMN_WIDTH = '[calc({sizes.mfui.size.dimension.icon.square.comfort} + {spacing.mfui.size.padding.data-table-cell.horizontal.comfort} * 2 + {spacing.mfui.size.padding.container.horizontal.comfort})]';

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

@@ -0,0 +1,42 @@
+import { type ReactNode } from 'react';
+import { type DataTableColumnWindow } from '../hooks/useVirtualizedColumns';
+type RenderVirtualizedColumnsParams = {
+    /**
+     * The cells of the row, flattened, without the selection checkbox cell the row renders itself.
+     */
+    cells: ReactNode[];
+    /**
+     * The grid column of the first cell, which is 1 when the row renders a selection checkbox cell.
+     */
+    columnOffset: number;
+    /**
+     * The columns to mount, or `null` to mount every cell.
+     */
+    columnWindow: DataTableColumnWindow | null;
+    /**
+     * The class name of the spacer cells.
+     */
+    spacerClassName: string;
+    /**
+     * Renders a mounted cell.
+     *
+     * @param cell - The cell to render.
+     * @param columnIndex - The grid column of the cell.
+     */
+    renderCell: (cell: ReactNode, columnIndex: number) => ReactNode;
+};
+/**
+ * Applies the column window to the cells of a row. The header row and the rows share it, so that
+ * they cannot disagree about which columns are mounted.
+ *
+ * Each gap left by the columns that are not mounted is filled with a single spacer cell spanning
+ * them. Under `table-layout: fixed` the spacer takes exactly the width of the `<col>` elements it
+ * spans, so the mounted cells stay in their columns and the sticky offsets of the fixed columns,
+ * which are summed over the cells of the row, stay what they are without virtualization.
+ *
+ * @param params - The cells of the row and the window to apply.
+ *
+ * @returns The cells to mount, with the spacer cells in place of the columns that are not mounted.
+ */
+export declare function renderVirtualizedColumns({ cells, columnOffset, columnWindow, spacerClassName, renderCell, }: RenderVirtualizedColumnsParams): ReactNode[];
+export {};

package/dist/src/DataTable/utils/renderVirtualizedColumns.js

@@ -0,0 +1,40 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Applies the column window to the cells of a row. The header row and the rows share it, so that
+ * they cannot disagree about which columns are mounted.
+ *
+ * Each gap left by the columns that are not mounted is filled with a single spacer cell spanning
+ * them. Under `table-layout: fixed` the spacer takes exactly the width of the `<col>` elements it
+ * spans, so the mounted cells stay in their columns and the sticky offsets of the fixed columns,
+ * which are summed over the cells of the row, stay what they are without virtualization.
+ *
+ * @param params - The cells of the row and the window to apply.
+ *
+ * @returns The cells to mount, with the spacer cells in place of the columns that are not mounted.
+ */
+export function renderVirtualizedColumns({ cells, columnOffset, columnWindow, spacerClassName, renderCell, }) {
+    if (columnWindow === null) {
+        return cells.map((cell, index) => renderCell(cell, index + columnOffset));
+    }
+    const rowColumnCount = cells.length + columnOffset;
+    // The bounds are clamped to the row, so a row with fewer cells than the header still lays out.
+    const suffixStart = Math.min(columnWindow.suffixStart ?? rowColumnCount, rowColumnCount);
+    const prefixEnd = Math.min(columnWindow.prefixEnd, suffixStart);
+    const windowStart = Math.min(Math.max(columnWindow.windowStart, prefixEnd), suffixStart);
+    const windowEnd = Math.min(Math.max(columnWindow.windowEnd, windowStart), suffixStart);
+    const renderRange = (start, end) => cells
+        .slice(Math.max(start - columnOffset, 0), Math.max(end - columnOffset, 0))
+        .map((cell, index) => renderCell(cell, Math.max(start, columnOffset) + index));
+    // The spacer stands in for the columns that are not mounted, so it reserves their width without
+    // being announced as a cell of the table.
+    const renderSpacer = (position, colSpan) => (_jsx("td", { 
+        // oxlint-disable-next-line jsx-a11y/no-interactive-element-to-noninteractive-role -- A `td` is not interactive; the role only keeps this empty layout cell from being announced as a cell.
+        role: "presentation", colSpan: colSpan, className: spacerClassName, "data-mfui-virtual-spacer": position }, `mfui-virtual-column-spacer-${position}`));
+    return [
+        ...renderRange(0, prefixEnd),
+        windowStart > prefixEnd ? renderSpacer('start', windowStart - prefixEnd) : null,
+        ...renderRange(windowStart, windowEnd),
+        suffixStart > windowEnd ? renderSpacer('end', suffixStart - windowEnd) : null,
+        ...renderRange(suffixStart, rowColumnCount),
+    ];
+}

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

@@ -0,0 +1,28 @@
+import { type CSSProperties } from 'react';
+import { type DataTableColumnVirtualizationOptions } from '../DataTable.types';
+/**
+ * The width of a column in pixels when neither `getColumnWidth` nor its header cell declares one.
+ */
+export declare const DEFAULT_COLUMN_WIDTH = 160;
+/**
+ * The `style.width` of a header cell, which the header row reports for each column.
+ */
+export type DeclaredColumnWidth = CSSProperties['width'];
+/**
+ * Resolves the width of every consumer column, in pixels, for column virtualization.
+ *
+ * Each column takes the first of:
+ *
+ * 1. `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.
+ * 3. {@link DEFAULT_COLUMN_WIDTH}.
+ *
+ * @param declaredColumnWidths - The `style.width` of each header cell, which also gives the number
+ * of consumer columns.
+ *
+ * @param getColumnWidth - The consumer's width callback, which receives the column index counted as
+ * `leftFixedColumnIndex` is, without the selection column.
+ *
+ * @returns The width of each consumer column in pixels.
+ */
+export declare function resolveColumnWidths(declaredColumnWidths: readonly DeclaredColumnWidth[], getColumnWidth: DataTableColumnVirtualizationOptions['getColumnWidth']): number[];