@moneyforward/mfui-components 4.7.0 → 4.8.0

package/dist/src/DataTable/DataTable.js

@@ -15,8 +15,11 @@ 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
@@ -32,6 +35,34 @@ const Base = forwardRef(({ className, size = 'medium', enableRowSelection = fals
             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.
@@ -65,9 +96,11 @@ const Base = forwardRef(({ className, size = 'medium', enableRowSelection = fals
     // 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;
-    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, 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: [_jsx("table", { ref: mergeRefs(ref, tableRef), className: cx(classes.table, 'mfui-DataTable__table', 
-                    /* TODO: Remove in v5.0.0 */ 'mfui-DataGrid__table', className), ...ariaRowCountProps, ...props, children: children }), shouldShowEmptyState ? (_jsx("div", { className: cx(classes.emptyState, 'mfui-DataTable__emptyState', 
+    // 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/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';

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

@@ -1,15 +1,18 @@
 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';
+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 } = useDataTableContext();
+    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]);
@@ -17,22 +20,35 @@ export const DataTableHeaderRow = forwardRef(({ children, checkboxProps, classNa
     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), ...(virtualizedRowCount !== null && { 'aria-rowindex': headerRowIndex }), ...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/DataTableProvider.d.ts

@@ -1,5 +1,7 @@
 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.
@@ -31,11 +33,24 @@ export type DataTableVirtualizationValues = {
      * Registers a header row and returns the function to unregister it.
      */
     registerHeaderRow: () => () => void;
-};
-export type DataTableProviderValues = {
+    /**
+     * 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 & DataTableVirtualizationValues;
+};
+export type DataTableProviderValues = DataTableContextProps & DataTableVirtualizationValues;
 /**
  * The context for the `DataTable` component.
  *
@@ -51,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, scrollElement, virtualizedRowCount, setVirtualizedRowCount, headerRowCount, registerHeaderRow, }: PropsWithChildren<DataTableContextProps & DataTableVirtualizationValues>): 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.
  *
@@ -28,6 +28,10 @@ export const DataTableContext = createContext({
     registerHeaderRow: () => () => {
         // Do nothing
     },
+    columnWindow: null,
+    reportDeclaredColumnWidths: () => {
+        // Do nothing
+    },
 });
 /**
  * The hook to use the `DataTableContext`.
@@ -38,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', scrollElement, virtualizedRowCount, setVirtualizedRowCount, headerRowCount, registerHeaderRow, }) {
-    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,
@@ -57,6 +60,8 @@ export function DataTableProvider({ children, size = 'medium', enableRowSelectio
         setVirtualizedRowCount,
         headerRowCount,
         registerHeaderRow,
+        columnWindow,
+        reportDeclaredColumnWidths,
     }), [
         size,
         enableRowSelection,
@@ -68,11 +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,6 +1,6 @@
 export { DataTable } from './DataTable';
 export { getColumnWidthFromContentWidth } from './utils/getColumnWidthFromContentWidth';
-export type { DataTableProps } from './DataTable.types';
+export type { DataTableProps, DataTableColumnVirtualizationOptions } from './DataTable.types';
 export type { DataTableBodyProps, DataTableBodyVirtualizationOptions } from './DataTableBody';
 export type { DataTableCellProps } from './DataTableCell';
 export type { DataTableHeaderProps } from './DataTableHeader';

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})]";