@opencorestack/opengridx 2.0.4 → 3.0.0

package/lib/components/DataGrid/DataGrid.tsx

@@ -1,51 +1,90 @@
-import React, { useRef, useEffect, useCallback, useMemo, useState } from 'react';
+import React, { useRef, useMemo } from 'react';
 import { useLayout } from '../../hooks/core/useLayout';
 import { useGridKeyboardNavigation } from '../../hooks/core/useGridKeyboardNavigation';
 import { useGridControlledState } from '../../hooks/core/useGridControlledState';
-import { useGridRowPipeline } from '../../hooks/core/useGridRowPipeline';
+import { useGridThemeDimensions } from '../../hooks/core/useGridThemeDimensions';
+import { useGridRowPipeline, type GridRowPipelineResult } from '../../hooks/core/useGridRowPipeline';
 import { useGridVirtualization } from '../../hooks/core/useGridVirtualization';
 import { useGridColumns } from '../../hooks/core/useGridColumns';
 import { useGridVisibleRows } from '../../hooks/core/useGridVisibleRows';
-import { useGridScrollSync } from '../../hooks/core/useGridScrollSync';
+import { useGridViewport } from '../../hooks/core/useGridViewport';
+import { useGridDetailPanel } from '../../hooks/core/useGridDetailPanel';
 import { useGridStateSnapshot } from '../../hooks/core/useGridStateSnapshot';
+import { useGridDevWarnings, useGridStylesheetWarning } from '../../hooks/core/useGridDevWarnings';
+import { useGridRowInteractions } from '../../hooks/core/useGridRowInteractions';
+import { useGridLiveRowSelection } from '../../hooks/core/useGridLiveRowSelection';
+import { useGridApiMethods } from '../../hooks/core/useGridApiMethods';
+import { useGridColumnLookup } from '../../hooks/core/useGridColumnLookup';
+import { useGridPageCorrection } from '../../hooks/core/useGridPageCorrection';
+import { useGridColumnsPanel } from '../../hooks/core/useGridColumnsPanel';
+import { GridToolbarHostContext } from '../../hooks/core/gridToolbarHostContext';
+import { GridToolbarSlot } from './GridToolbarSlot';
 import { GridAggregationFooter } from './GridAggregationFooter';
 import { GridEmptyState } from './GridEmptyState';
 import { GridErrorOverlay } from './GridErrorOverlay';
 import { Header } from '../Header/Header';
-import { Pagination } from '../Pagination/Pagination';
 import { useDataGrid } from '../../hooks/core/useDataGrid';
 import { useRowReorder } from '../../hooks/useRowReorder';
-import { useTreeData } from '../../hooks/useTreeData';
-import { useRowGrouping } from '../../hooks/useRowGrouping';
+import { useGridHierarchy } from '../../hooks/core/useGridHierarchy';
 import { useGridEditing } from '../../hooks/features/useGridEditing';
 import { useGridSpanning } from '../../hooks/features/useGridSpanning';
+import { useGridSpanRowWindow, useGridSpanColumnWindow } from '../../hooks/features/useGridSpanRenderWindow';
+import { useColumnGroupReorderGuard } from '../../hooks/features/useColumnGroupReorderGuard';
 import { useGridDataSource } from '../../hooks/features/useGridDataSource';
-import { useAggregation } from '../../hooks/features/useAggregation';
-import { usePivot } from '../../hooks/features/usePivot';
-import { useGridClipboard } from '../../hooks/features/useGridClipboard';
+import { useServerTreeChildren } from '../../hooks/features/useServerTreeChildren';
+import { useAggregation, useServerAggregationResults } from '../../hooks/features/useAggregation';
+import { useGridPivot } from '../../hooks/features/useGridPivot';
+import { isServerDrivenDataSource } from '../../utils/dataSource';
 import { GridListView } from './GridListView';
+import { GridLoadingOverlay } from './GridLoadingOverlay';
 import { GridPinnedRows } from './GridPinnedRows';
 import { GridVirtualRows } from './GridVirtualRows';
 import { GridStandaloneColumnPanel } from './GridStandaloneColumnPanel';
-import type { DataGridProps, GridRowModel, GridRowId, GridSortDirection, GridColDef, GridRowParams, GridCellParams, GridDataSource, GridAggregationResult, GridFilterModel, GridTreeNode, GridSortItem, GridRowMeta, GridGroupedExportRow } from '../../types';
-
-const EMPTY_ROW_META_MAP: Map<GridRowId, GridRowMeta> = new Map();
-
-export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridProps<R>) {
+import { resolveGridModes, EMPTY_ROW_GROUPING_MODEL } from '../../utils/gridModes';
+import { useGridGroupingColumn } from '../../hooks/core/useGridGroupingColumn';
+import { useGridRowIdOf, getDefaultRowId } from '../../hooks/core/useGridRowIdOf';
+import { useGridApiRefBinding } from '../../hooks/core/useGridApiRefBinding';
+import { collectAllFilteredRows } from '../../utils/gridApiRows';
+import { NO_AGGREGATION_MODEL } from '../../utils/aggregation';
+import { isSyntheticRowId } from '../../utils/syntheticRows';
+import { useStableColumns } from '../../hooks/core/useStableColumns';
+import { useGridAggregationApi } from '../../hooks/core/useGridAggregationApi';
+import { useGridClipboardApi } from '../../hooks/core/useGridClipboardApi';
+import { useGridScrollToIndexesApi } from '../../hooks/core/useGridScrollToIndexesApi';
+import { useGridSortHandlers, useGridColumnMenuHandlers } from '../../hooks/core/useGridHeaderHandlers';
+import { useGridKeyboardMode, useGridPointerFocusHandlers } from '../../hooks/core/useGridFocusHandlers';
+import { getPaginationRowCount, pickPaginationLocaleText } from '../../utils/pagination';
+import { GridPaginationArea } from './GridPaginationArea';
+import { GridLiveRegion } from './GridLiveRegion';
+import { useGridAriaRows } from '../../hooks/core/useGridAriaRows';
+import { useGridToolbarProps } from '../../hooks/core/useGridToolbarProps';
+import type { DataGridProps, DataGridUntypedColumnsProps, GridValidRowModel, GridRowModel, GridRowId, GridColDef } from '../../types';
+
+/**
+ * The grid. `R` is your row type: any object type (an interface works), inferred from `rows`. `columns`
+ * can be typed for it (`GridColDef<R>[]`, so callbacks see `params.row` as `R`) or untyped (`GridColDef[]`).
+ */
+export function DataGrid<R extends GridValidRowModel = GridRowModel>(props: DataGridProps<R>): React.JSX.Element;
+export function DataGrid<R extends GridValidRowModel = GridRowModel>(props: DataGridUntypedColumnsProps<R>): React.JSX.Element;
+// Internally every row is read as a GridRowModel (a record keyed by field): the overloads above are the
+// public signatures, and a consumer's row objects are passed through untouched.
+export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridProps<R>): React.JSX.Element {
     const {
         rows,
-        columns,
+        columns: columnsProp,
         getRowId,
-        rowHeight = 52,
-        headerHeight = 56,
+        rowHeight: rowHeightProp,
+        headerHeight: headerHeightProp,
         autoHeight = false,
         density,
         checkboxSelection = false,
         disableRowSelectionOnClick = false,
         disableMultipleRowSelection = false,
+        disableClipboardCopy = false,
         rowSelectionModel: propRowSelectionModel,
         onRowSelectionModelChange: propOnRowSelectionModelChange,
         onRowClick,
+        onRowDoubleClick,
         onCellClick,
 
         filterModel: propFilterModel,
@@ -69,8 +108,9 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         disableColumnReorder = false,
         columnOrder,
         onColumnOrderChange,
+        onColumnOrderModelChange,
         height,
-        rowReordering = false,
+        rowReordering: rowReorderingProp = false,
         onRowOrderChange,
         loading = false,
 
@@ -112,7 +152,7 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         // Column Visibility
         columnVisibilityModel: propColumnVisibilityModel,
         onColumnVisibilityModelChange,
-        listView = false,
+        listView: listViewRequested = false,
         listViewColumn,
         columnGroupingModel,
         noRowsLabel = 'No Data',
@@ -120,46 +160,18 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         apiRef: propApiRef,
         overscanRowCount = 3,
     } = props;
+    // Equal inline column definitions keep one identity, so the row passes memoised on it do not re-run.
+    const columns = useStableColumns(columnsProp);
 
     const effectiveNoRowsLabel = localeText?.noRowsLabel ?? noRowsLabel;
-
-    // Stable defaults
-    const defaultFilterModel: GridFilterModel = useMemo(() => ({ items: [] }), []);
-    const filterModel = (propFilterModel || defaultFilterModel) as GridFilterModel;
-
-    const defaultRowGroupingModel = useMemo(() => [], []);
-    const rowGroupingModel = propRowGroupingModel || defaultRowGroupingModel;
-
-    // ─── Stabilize toolbar component identity ────────────────────────────────
-    // Problem: demos/users often define their toolbar as an inline function
-    // INSIDE their component body, e.g.:
-    //   const MyToolbar = (props) => <GridToolbar {...props} />  // inside render!
-    // This creates a NEW function reference on every parent re-render. React
-    // reconciles by component *identity*, so a new reference = unmount old
-    // toolbar + mount fresh one = all toolbar state (search expansion, filter
-    // open, typed text) is destroyed on every keystroke.
-    //
-    // Fix: a stable wrapper component created ONCE via useRef. Its identity
-    // never changes, so React keeps it mounted. It reads the latest toolbar
-    // from a separate ref that is updated on every render, so the rendered
-    // output is always current — zero stale closures.
-    const latestToolbarRef = useRef(slots?.toolbar);
-    latestToolbarRef.current = slots?.toolbar;
-    // The wrapper itself has a stable identity (created once via useRef).
-    // We call latestToolbarRef.current(props) as a PLAIN FUNCTION — not via
-    // React.createElement — so React never sees a changing component type.
-    // The elements the toolbar function returns are reconciled normally, so
-    // GridToolbar's internal state (filterOpen, search expansion) is preserved
-    // even when the toolbar is defined as an inline function inside the parent.
-    const StableToolbar = useRef((props: Record<string, unknown>) => {
-        const Toolbar = latestToolbarRef.current;
-        return Toolbar ? (Toolbar as (p: typeof props) => React.ReactElement | null)(props) : null;
-    }).current;
+    const rowGroupingModel = propRowGroupingModel || EMPTY_ROW_GROUPING_MODEL;
 
     const controlledState = useGridControlledState({
         initialState,
         sortModel: propSortModel,
         onSortModelChange,
+        filterModel: propFilterModel,
+        onFilterModelChange,
         aggregationModel: propAggregationModel,
         onAggregationModelChange,
         columnVisibilityModel: propColumnVisibilityModel,
@@ -167,161 +179,93 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         pinnedColumns: propPinnedColumns,
         onPinnedColumnsChange,
         pivotModel: propPivotModel,
-        onPivotModelChange,
-        paginationModel,
-        onPaginationModelChange,
+        onPivotModelChange, paginationModel, onPaginationModelChange, pageSizeOptions,
         rowSelectionModel: propRowSelectionModel,
         onRowSelectionModelChange: propOnRowSelectionModelChange,
+        density,
     });
 
     const {
-        sortModel,
-        isSortControlled,
-        setInternalSortModel,
-        aggregationModel,
-        handleAggregationModelChange,
-        columnVisibilityModel,
-        handleColumnVisibilityModelChange,
-        pinnedColumns,
-        handlePinnedColumnsChange,
-        currentPivotModel,
-        handlePivotModelChange,
-        effectivePaginationModel,
-        handlePaginationModelChange,
-        selectedRowIds,
-        isSelectionControlled,
-        setInternalRowSelectionModel,
+        sortModel, handleSortModelChange, filterModel,
+        handleFilterModelChange, aggregationModel, handleAggregationModelChange, columnVisibilityModel,
+        handleColumnVisibilityModelChange, pinnedColumns, handlePinnedColumnsChange, currentPivotModel,
+        handlePivotModelChange, effectivePaginationModel, handlePaginationModelChange,
+        selectedRowIds: selectionModelRowIds,
+        handleRowSelectionModelChange,
+        density: effectiveDensity,
     } = controlledState;
 
-    const onRowSelectionModelChange = propOnRowSelectionModelChange;
-
-    const pivot = usePivot(rows as GridRowModel[], columns as unknown as GridColDef[], currentPivotModel, pivotMode);
-
-    const effectiveRowHeight = density === 'compact' ? 32 : density === 'comfortable' ? 72 : rowHeight;
-
-    const activeRows = (pivotMode && pivot.isValid ? pivot.pivotRows : rows) as unknown as R[];
-    const baseColumns = (pivotMode && pivot.isValid ? pivot.pivotColumns : columns) as unknown as GridColDef<R>[];
-
-    // When groupingColDef is provided and row grouping is active, prepend a
-    // dedicated synthetic __group__ column at position 0 (pinned-left).
-    const isRowGroupingActive = Boolean(propRowGroupingModel && propRowGroupingModel.length > 0);
-
-    // Auto-pin __group__ column to the left when groupingColDef is active.
-    // Both values MUST be memoized: without useMemo they produce a new array/object
-    // reference every render, which cascades through useRowGrouping's memos and
-    // effects into an infinite setState loop (Maximum update depth exceeded).
-    const effectivePinnedColumns = useMemo(() => (
-        (groupingColDef && isRowGroupingActive && !pivotMode)
-            ? { ...pinnedColumns, left: ['__group__', ...((pinnedColumns?.left ?? []).filter(f => f !== '__group__'))] }
-            : pinnedColumns
-    ), [groupingColDef, isRowGroupingActive, pivotMode, pinnedColumns]);
-
-    const activeColumns = useMemo(() => (
-        (groupingColDef && isRowGroupingActive && !pivotMode)
-            ? [
-                {
-                    headerName: 'Group',
-                    width: 220,
-                    ...groupingColDef,
-                    field: '__group__',
-                    hideable: false,
-                    sortable: false,
-                    pinnable: false,
-                    exportable: false,
-                } as unknown as GridColDef<R>,
-                ...baseColumns,
-              ]
-            : baseColumns
-    ), [groupingColDef, isRowGroupingActive, pivotMode, baseColumns]);
-
-    const [serverAggregationResults, setServerAggregationResults] = useState<GridAggregationResult | null>(null);
-
-    useEffect(() => {
-        setServerAggregationResults(null);
-    }, [aggregationModel]);
+    const pivot = useGridPivot({
+        rows: rows as GridRowModel[],
+        columns: columns as unknown as GridColDef[],
+        pivotMode,
+        pivotModel: currentPivotModel,
+        filterModel,
+        sortModel,
+        hasDataSource: Boolean(dataSource),
+        hierarchyRequested: treeData || rowGroupingModel.length > 0,
+    });
+    const isPivotActive = pivot.isActive;
+    const {
+        rowReordering, hierarchyRowGroupingModel, isTreeDataRequested, isTreeData,
+        isRowGrouping, isHierarchyEnabled, hasGroupingColumn, pagination, listView,
+    } = resolveGridModes({
+        rowGroupingModel,
+        treeData,
+        hasTreeDataPath: Boolean(getTreeDataPath),
+        isPivotActive,
+        rowReordering: rowReorderingProp,
+        hasGroupingColDef: Boolean(groupingColDef),
+        pagination: propPagination,
+        paginationMode,
+        listView: listViewRequested,
+        hasListViewColumn: Boolean(listViewColumn),
+    });
 
-    const viewportRef = useRef<HTMLDivElement>(null);
-    const contentRef = useRef<HTMLDivElement>(null);
-    const gridRef = useRef<HTMLDivElement>(null);
-
-    const defaultGetRowId = useCallback((row: R) => row.id, []);
-    const effectiveGetRowId = getRowId || defaultGetRowId;
-
-    // Normalize rows so every row has `id === getRowId(row)`.
-    // createInitialState and SET_ROWS both key the internal store by row.id,
-    // so rows without a native id field collide on undefined without this.
-    // When getRowId is the default (row) => row.id this is a no-op per row.
-    const normalizedRows = useMemo(
-        () => activeRows.map(row => {
-            const id = effectiveGetRowId(row);
-            return id === row.id ? row : ({ ...row, id } as R);
-        }),
-        [activeRows, effectiveGetRowId]
-    );
+    // Props, then the enclosing DataGridThemeProvider's heights, then the defaults (52 / 56).
+    const { rowHeight: effectiveRowHeight, headerHeight } = useGridThemeDimensions({
+        rowHeight: rowHeightProp, headerHeight: headerHeightProp, density: effectiveDensity,
+    });
 
-    // Keyboard-mode flag: toggled via DOM classname — no React state needed
-    // so the ring appears instantly without a re-render cycle.
-    const setKeyboardMode = useCallback((on: boolean) => {
-        containerRef.current?.classList.toggle('ogx--kb', on);
-    }, []);
+    const activeRows = pivot.rows as unknown as R[];
+    const baseColumns = pivot.columns as unknown as GridColDef<R>[];
 
-    const dataSourceRef = useRef<GridDataSource<R> | undefined>(dataSource);
-    dataSourceRef.current = dataSource;
+    const { activeColumns, effectivePinnedColumns } = useGridGroupingColumn<R>({
+        baseColumns, pinnedColumns, hasGroupingColumn, groupingColDef, isTreeData, getTreeDataPath,
+    });
 
-    const fetchChildrenRef = useRef<((parentId: GridRowId, groupKeys: string[]) => Promise<void>) | null>(null);
-    const treeDataRef = useRef<ReturnType<typeof useTreeData> | null>(null);
+    const columnLookup = useGridColumnLookup(activeColumns, columnVisibilityModel);
 
-    const handleNodeExpansion = useCallback((node: GridTreeNode) => {
-        if (dataSourceRef.current && treeData) {
+    // getRows-provided totals, dropped as soon as the aggregation model they were computed for changes.
+    const [serverAggregationResults, setServerAggregationResults] = useServerAggregationResults(aggregationModel);
 
-            if ((node.serverChildrenCount ?? 0) > 0 && (node.children ?? []).length === 0) {
+    const containerRef = useRef<HTMLDivElement>(null);
+    const viewportRef = useRef<HTMLDivElement>(null);
+
+    // Rows are stored and handed to consumers untouched: getRowId only decides the internal
+    // key. Pivot rows are the grid's own and carry their own ids, so a getRowId written for
+    // the source rows does not apply to them.
+    const effectiveGetRowId = (!isPivotActive && getRowId) || getDefaultRowId;
 
-                const groupKeys = treeDataRef.current?.getNodePath(node.id) || [node.groupingKey];
-                fetchChildrenRef.current?.(node.id, groupKeys);
-            }
-        }
-    }, [treeData]);
+    const setKeyboardMode = useGridKeyboardMode(containerRef);
 
     const gridData = useDataGrid({
-        rows: normalizedRows,
+        rows: activeRows,
+        getRowId: effectiveGetRowId,
         columns: activeColumns,
         rowHeight: effectiveRowHeight,
         headerHeight,
-        rowCount: propRowCount,
         columnVisibilityModel,
-        initialState: props.initialState
+        initialState: props.initialState,
+        syncRows: !dataSource,
     });
     const {
-        state,
-        apiRef,
-        setRows,
-        setColumns,
-        setDimensions,
-        setDataSourceLoading,
-        setDataSourceError,
+        state, apiRef, setRows, replaceRow, setColumns, setDimensions, setDataSourceLoading, setDataSourceError,
         setRowCount
     } = gridData;
 
-    const { scrollTop, scrollLeft, overscanRows, handleScroll } = useGridScrollSync({ onRowsScrollEnd, overscanRowCount });
-
-    useEffect(() => {
-        if (propApiRef) {
-            propApiRef.current = apiRef.current;
-        }
-    }, [propApiRef, apiRef]);
-
-    const { copySelectedRows } = useGridClipboard({
-        selectedRowIds,
-        columns: activeColumns as unknown as GridColDef[],
-        getVisibleRows: () => apiRef.current.getVisibleRows(),
-        getRowId: effectiveGetRowId as unknown as (row: GridRowModel) => GridRowId,
-    });
-
-    // Expose on apiRef for programmatic use
-    useEffect(() => {
-        apiRef.current.copySelectedRows = copySelectedRows;
-        apiRef.current.getSelectedRows = () => Array.from(selectedRowIds);
-    }, [copySelectedRows, selectedRowIds, apiRef]);
+    const { getRowIdOf, getRowIdOfInEvents } = useGridRowIdOf(state.rows.idByRow);
+    useGridApiRefBinding(propApiRef, apiRef);
 
     const isInternalLoading = state.dataSource.loading;
     const effectiveLoading = loading || isInternalLoading;
@@ -330,552 +274,388 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
         return state.rows.allRows.map(id => state.rows.idRowsLookup.get(id)!) as R[];
     }, [state.rows]);
 
-    const treeDataHandlers = useTreeData({
+    const { treeDataHandlers, rowGroupingHandlers, activeHierarchyHandlers, rowMetaMap } = useGridHierarchy<R>({
         rows: effectiveRows,
-        getRowId: effectiveGetRowId,
-        getTreeDataPath,
-        treeData,
-        defaultGroupingExpansionDepth,
-        filterModel,
-
-        sortModel,
-        onRowExpansionChange: handleNodeExpansion
-    });
-
-    useEffect(() => {
-        treeDataRef.current = treeDataHandlers;
-    }, [treeDataHandlers]);
-
-    const rowGroupingHandlers = useRowGrouping({
-        rows: effectiveRows,
-        getRowId: effectiveGetRowId,
+        getRowId: getRowIdOf,
+        getTreeDataPath, isTreeDataRequested, isTreeData,
         columns: activeColumns,
-        rowGroupingModel,
-        aggregationModel,
-        defaultGroupingExpansionDepth,
-        filterModel,
-        sortModel,
-        getAggregationPosition
+        rowGroupingModel: hierarchyRowGroupingModel,
+        isRowGrouping, aggregationModel, defaultGroupingExpansionDepth, filterModel, sortModel,
+        getAggregationPosition, columnLookup, filterMode, sortingMode,
     });
 
     const editingHandlers = useGridEditing({
         rows: effectiveRows,
-        getRowId: effectiveGetRowId,
+        getRowId: getRowIdOf,
+        columns: activeColumns,
         processRowUpdate,
         onProcessRowUpdateError,
-        onRowChange: (updatedRow) => {
-            // Dispatch a proper state update so React re-renders with the new row value
-            const { dispatch } = gridData;
-            const currentRows = Array.from(gridData.state.rows.idRowsLookup.values());
-            const nextRows = currentRows.map(r =>
-                r.id === updatedRow.id ? updatedRow : r
-            );
-            dispatch({ type: 'SET_ROWS', payload: nextRows });
+        onRowChange: (updatedRow, rowId) => {
+            // Replaces the edited row in the *current* store, under the edited row's id: this runs
+            // after an awaited processRowUpdate, by which time the rows prop (or a dataSource
+            // fetch) may have replaced the rows this render saw. The returned row is stored as is
+            // (the grid never writes an id onto it), even if it does not carry its key itself.
+            replaceRow(rowId, updatedRow);
         },
     });
 
-    const isTreeData = treeData;
-    const isRowGrouping = !!(rowGroupingModel && rowGroupingModel.length > 0);
-    const isHierarchyEnabled = isTreeData || isRowGrouping;
-    const activeHierarchyHandlers = isTreeData ? treeDataHandlers : (isRowGrouping ? rowGroupingHandlers : null);
-
-    const rowMetaMap = useMemo<Map<GridRowId, GridRowMeta>>(() => {
-        if (isTreeData) return treeDataHandlers.rowMetaMap;
-        if (isRowGrouping) return rowGroupingHandlers.rowMetaMap;
-        return EMPTY_ROW_META_MAP;
-    }, [isTreeData, treeDataHandlers.rowMetaMap, isRowGrouping, rowGroupingHandlers.rowMetaMap]);
-
-    const pagination = propPagination && !isRowGrouping;
-
-    const handleRowClick = useCallback((params: GridRowParams<R>) => {
-        const { row, id } = params;
-
-        if (isHierarchyEnabled && rowMetaMap.get(row.id)?.hasChildren) {
-            activeHierarchyHandlers?.toggleExpansion(id);
-            return;
-        }
-
-        onRowClick?.(params);
-
-        if (!disableRowSelectionOnClick) {
-            let next: GridRowId[];
-            if (disableMultipleRowSelection) {
-                const alreadySelected = selectedRowIds.has(id as GridRowId);
-                next = alreadySelected ? [] : [id as GridRowId];
-            } else {
-                const newSelection = new Set(selectedRowIds);
-                if (newSelection.has(id as GridRowId)) {
-                    newSelection.delete(id as GridRowId);
-                } else {
-                    newSelection.add(id as GridRowId);
-                }
-                next = Array.from(newSelection);
-            }
-            if (!isSelectionControlled) {
-                setInternalRowSelectionModel(next);
-            }
-            onRowSelectionModelChange?.(next);
-        }
-    }, [isHierarchyEnabled, activeHierarchyHandlers, onRowClick, rowMetaMap, disableRowSelectionOnClick, disableMultipleRowSelection, selectedRowIds, isSelectionControlled, setInternalRowSelectionModel, onRowSelectionModelChange]);
+    // The selection without ids of removed rows. Only client-owned rows are pruned: a server page
+    // or a pivot of the rows does not hold every row a selection may name.
+    const selectedRowIds = useGridLiveRowSelection({
+        selectedRowIds: selectionModelRowIds,
+        rowsLookup: state.rows.idRowsLookup,
+        rowMetaMap,
+        enabled: !dataSource && !isPivotActive && paginationMode === 'client' && filterMode === 'client',
+        onSelectionModelChange: handleRowSelectionModelChange,
+    });
 
     const dataSourceHandlers = useGridDataSource({
-        dataSource,
-        sortModel,
-        filterModel,
+        dataSource, sortModel, filterModel,
         paginationModel: effectivePaginationModel,
-        paginationMode,
-        sortingMode,
-        filterMode,
-        aggregationModel,
-        setRows,
-        setRowCount,
-        setDataSourceLoading,
-        setDataSourceError,
+        paginationMode, sortingMode, filterMode, aggregationModel,
+        rowGroupingActive: isRowGrouping,
+        getRowId: effectiveGetRowId as unknown as (row: GridRowModel) => GridRowId,
+        setRows, setRowCount, setDataSourceLoading, setDataSourceError,
         onAggregationResults: setServerAggregationResults,
+        onPaginationModelChange: handlePaginationModelChange,
     });
 
-    useEffect(() => {
-        if (dataSourceHandlers.fetchChildren) {
-            fetchChildrenRef.current = dataSourceHandlers.fetchChildren;
-        }
-    }, [dataSourceHandlers.fetchChildren]);
-
-    useEffect(() => {
-        if (!dataSource) {
-            setRows(normalizedRows);
-        }
-    }, [normalizedRows, setRows, dataSource]);
+    useServerTreeChildren({
+        enabled: isTreeData && Boolean(dataSource),
+        treeNodes: treeDataHandlers.treeNodes,
+        isGroupExpanded: treeDataHandlers.isGroupExpanded,
+        getNodePath: treeDataHandlers.getNodePath,
+        toggleExpansion: treeDataHandlers.toggleExpansion,
+        fetchChildren: dataSourceHandlers.fetchChildren,
+    });
 
     // ── Detail panel (hoisted — hasDetailPanel feeds into useGridColumns) ──────
-    const hasDetailPanel = Boolean(getDetailPanelContent);
-    const [internalExpandedRowIds, setInternalExpandedRowIds] = useState<Set<GridRowId>>(new Set());
-    const expandedRowIds = controlledExpandedRowIds ?? internalExpandedRowIds;
-
-    const handleDetailPanelToggle = useCallback((rowId: GridRowId) => {
-        const newExpandedRowIds = new Set(expandedRowIds);
-        if (newExpandedRowIds.has(rowId)) {
-            newExpandedRowIds.delete(rowId);
-        } else {
-            newExpandedRowIds.add(rowId);
-        }
-        if (controlledExpandedRowIds === undefined) {
-            setInternalExpandedRowIds(newExpandedRowIds);
-        }
-        onDetailPanelExpandedRowIdsChange?.(newExpandedRowIds);
-    }, [expandedRowIds, controlledExpandedRowIds, onDetailPanelExpandedRowIdsChange]);
+    const {
+        hasDetailPanel, expandedRowIds, handleDetailPanelToggle, detailPanelHeights, reportDetailPanelHeight,
+    } = useGridDetailPanel({
+        hasDetailPanel: Boolean(getDetailPanelContent),
+        controlledExpandedRowIds, onDetailPanelExpandedRowIdsChange, rowMetaMap,
+    });
 
     // ── Column management ─────────────────────────────────────────────────────
     const {
-        effectiveColumns,
-        orderedColumns,
-        visibleOrderedColumns,
-        navigationColumns,
-        columnWidths,
-        effectiveColumnOrder,
-        setInternalColumnOrder,
-        columnReorderHandlers,
-        handleColumnResize,
+        effectiveColumns, hierarchyField, orderedColumns, visibleOrderedColumns, renderOrderedColumns, navigationColumns, columnIndexMap,
+        columnWidths, effectiveColumnOrder, columnReorderHandlers, moveColumn, resetColumnOrder, handleColumnResize,
     } = useGridColumns<R>({
-        activeColumns,
-        isHierarchyEnabled,
-        isRowGrouping,
-        isTreeData,
-        activeHierarchyHandlers,
-        columnVisibilityModel,
-        columnOrder,
-        onColumnOrderChange,
-        disableColumnReorder,
-        pivotMode,
-        checkboxSelection,
-        hasDetailPanel,
-        rowReordering,
-        initialState,
-        setColumns,
+        activeColumns, isHierarchyEnabled, isRowGrouping, isTreeData, activeHierarchyHandlers,
+        columnVisibilityModel, columnOrder, onColumnOrderChange, onColumnOrderModelChange, disableColumnReorder,
+        pivotMode: isPivotActive,
+        checkboxSelection, hasDetailPanel, rowReordering, initialState, setColumns,
+        pinnedColumns: effectivePinnedColumns,
+        getRowId: getRowIdOfInEvents,
+        aggregationModel,
+        groupingRows: isRowGrouping ? rowGroupingHandlers.groupingRows : undefined,
     });
 
     useGridStateSnapshot({
-        onStateChange,
-        sortModel,
-        filterModel,
-        effectivePaginationModel,
-        columnWidths,
-        effectiveColumnOrder,
-        columnVisibilityModel,
-        pinnedColumns: effectivePinnedColumns,
+        onStateChange, sortModel, filterModel, effectivePaginationModel, columnWidths, effectiveColumnOrder,
+        columnVisibilityModel, pinnedColumns,
+        density: effectiveDensity,
     });
 
     const rowPipeline = useGridRowPipeline<GridRowModel>({
         effectiveRows: effectiveRows as GridRowModel[],
-        activeHierarchyHandlers: activeHierarchyHandlers as { getVisibleRows: () => GridRowModel[] } | null,
+        activeHierarchyHandlers,
         filterMode,
-        filterModel,
-        dataSource: dataSource as GridDataSource<GridRowModel> | undefined,
-        sortModel,
-        sortingMode,
-        pagination,
+        filterModel: pivot.pipelineFilterModel,
+        sortModel: pivot.pipelineSortModel,
+        sortingMode, pagination, paginationMode, effectivePaginationModel, pinnedRows,
+        getRowId: getRowIdOf,
+        columnLookup,
+        hierarchyField,
+    });
+    const {
+        filteredRows, dataRows, pinnedTopRows, pinnedBottomRows, sortedUnpinnedRows, paginatedUnpinnedRows, allRenderableRows,
+    } = rowPipeline as unknown as GridRowPipelineResult<R>;
+    // The unpinned rows on screen: the current page, or every row without pagination.
+    const centerRows = pagination ? paginatedUnpinnedRows : sortedUnpinnedRows;
+
+    useGridPageCorrection({
+        paginationModel: effectivePaginationModel,
+        currentPage: rowPipeline.currentPage,
+        enabled: pagination && !effectiveLoading && sortedUnpinnedRows.length > 0,
+        onPaginationModelChange: handlePaginationModelChange,
+    });
+
+    const paginationRowCount = getPaginationRowCount({
         paginationMode,
-        effectivePaginationModel,
-        pinnedRows,
-        isLoading: state.dataSource.loading,
-        pageSize: effectivePaginationModel.pageSize,
+        hasDataSource: Boolean(dataSource),
+        dataSourceRowCount: state.pagination.rowCount,
+        rowCountProp: propRowCount,
+        clientRowCount: sortedUnpinnedRows.length,
+    });
+
+    const { rowSelection, handleRowClick, handleSelectionChange } = useGridRowInteractions<R>({
+        dataRows,
+        getRowId: getRowIdOf,
+        isPivotActive,
+        selectedRowIds,
+        onSelectionModelChange: handleRowSelectionModelChange,
+        disableMultipleRowSelection, disableRowSelectionOnClick, isHierarchyEnabled, rowMetaMap,
+        activeHierarchyHandlers, onRowClick,
+    });
+
+    useGridApiMethods({
+        apiRef: gridData.apiRef,
+        sortModel,
+        multiSort,
+        onSortModelChange: handleSortModelChange,
+        filterModel,
+        onFilterModelChange: handleFilterModelChange,
+        paginationModel: effectivePaginationModel,
+        onPaginationModelChange: handlePaginationModelChange,
+        selectedRowIds,
+        getPendingRowSelectionModel: controlledState.getPendingRowSelectionModel,
+        onRowSelectionModelChange: handleRowSelectionModelChange,
+        disableMultipleRowSelection,
+        isSyntheticRowId: (id) => isSyntheticRowId(id, rowMetaMap),
+        getVisibleRows: () => [...pinnedTopRows, ...centerRows, ...pinnedBottomRows],
+        getAllFilteredRows: () => collectAllFilteredRows<GridRowModel>({
+            hierarchyHandlers: activeHierarchyHandlers,
+            pinnedTopRows,
+            sortedUnpinnedRows,
+            pinnedBottomRows,
+            rowMetaMap,
+            getRowId: getRowIdOf,
+            hierarchyField,
+            dataRows,
+        }),
+        visibleColumns: renderOrderedColumns as unknown as GridColDef[],
     });
-    const filteredRows        = rowPipeline.filteredRows        as R[];
-    const pinnedTopRows       = rowPipeline.pinnedTopRows       as R[];
-    const pinnedBottomRows    = rowPipeline.pinnedBottomRows    as R[];
-    const sortedUnpinnedRows  = rowPipeline.sortedUnpinnedRows  as R[];
-    const paginatedUnpinnedRows = rowPipeline.paginatedUnpinnedRows as R[];
-    const allRenderableRows   = rowPipeline.allRenderableRows   as R[];
-
-    useEffect(() => {
-        gridData.apiRef.current.getVisibleRows = () => pagination ? paginatedUnpinnedRows : sortedUnpinnedRows;
-        gridData.apiRef.current.getAllFilteredRows = () => sortedUnpinnedRows;
-        gridData.apiRef.current.getVisibleColumns = () => effectiveColumns as unknown as GridColDef[];
-    }, [sortedUnpinnedRows, paginatedUnpinnedRows, pagination, effectiveColumns, gridData.apiRef]);
 
+    // Indices address the consumer's own rows, whatever the sort, filter, page or pinning.
     const rowReorderHandlers = useRowReorder({
-        rows: pagination ? paginatedUnpinnedRows : sortedUnpinnedRows,
-        getRowId: (row) => row.id,
+        rows: effectiveRows,
+        getRowId: getRowIdOf,
         onRowOrderChange,
         rowReordering
     });
 
-    const spanning = useGridSpanning(
-        allRenderableRows,
-        navigationColumns,
-        columnWidths
-    );
-
-    const { aggregationResult } = useAggregation({
-        rows: filteredRows,
+    const { aggregationResult, isLoading: isAggregationLoading } = useAggregation({
+        rows: dataRows,
         columns: activeColumns as unknown as GridColDef[],
-        aggregationModel,
-        isServerSide: !!(dataSource && (paginationMode === 'server' || sortingMode === 'server')),
-        dataSource,
-        filterModel,
-        sortModel,
-        serverAggregationResults,
+        // The pivot's Grand Total row is the aggregate in pivot mode: nothing to total here.
+        aggregationModel: isPivotActive ? NO_AGGREGATION_MODEL : aggregationModel,
+        // When the server drives the rows (paginates, sorts or filters them), the grid only holds
+        // the rows it returned, so client totals would be partial.
+        isServerSide: isServerDrivenDataSource({ dataSource, paginationMode, sortingMode, filterMode }),
+        dataSource, filterModel, sortModel, serverAggregationResults,
     });
 
-    const hasAggregation = Object.keys(aggregationModel).length > 0;
-
-    useEffect(() => {
-        gridData.apiRef.current.getAggregationResult = () => hasAggregation ? aggregationResult : null;
-        gridData.apiRef.current.getAggregationModel = () => hasAggregation ? aggregationModel : null;
-        gridData.apiRef.current.getGroupedExportRows = (): GridGroupedExportRow[] | null => {
-            if (!isRowGrouping) return null;
-            const { treeNodes, groupingRows } = rowGroupingHandlers;
-            const rowLookup = new Map<GridRowId, GridRowModel>();
-            sortedUnpinnedRows.forEach(r => rowLookup.set((r as GridRowModel).id as GridRowId, r as GridRowModel));
-
-            const result: GridGroupedExportRow[] = [];
-
-            const traverse = (ids: GridRowId[]) => {
-                ids.forEach(id => {
-                    const node = treeNodes.get(id);
-                    if (!node) return;
-                    const isGroup = Boolean(node.children && node.children.length > 0);
-                    if (isGroup) {
-                        result.push({
-                            type: 'group-header',
-                            depth: node.depth,
-                            groupField: node.groupingField,
-                            groupValue: node.groupingValue,
-                        });
-                        traverse(node.children!);
-                        if (hasAggregation && node.aggregatedValues) {
-                            result.push({
-                                type: 'group-subtotal',
-                                depth: node.depth,
-                                groupField: node.groupingField,
-                                groupValue: node.groupingValue,
-                                aggregatedValues: node.aggregatedValues,
-                            });
-                        }
-                    } else {
-                        const row = rowLookup.get(id) ?? groupingRows.get(id);
-                        if (row) {
-                            result.push({ type: 'leaf', depth: node.depth, row });
-                        }
-                    }
-                });
-            };
-
-            traverse(Array.from(treeNodes.keys()).filter(id => treeNodes.get(id)?.parentId === null));
-
-            if (hasAggregation && aggregationResult) {
-                result.push({ type: 'grand-total', depth: 0, aggregatedValues: aggregationResult });
-            }
-            return result;
-        };
-    }, [aggregationResult, aggregationModel, hasAggregation, gridData.apiRef, isRowGrouping, rowGroupingHandlers, sortedUnpinnedRows]);
+    // In pivot mode the pivot's own Grand Total row is the aggregate; aggregationModel keys name source
+    // fields that the pivot rows do not have.
+    const hasAggregation = Object.keys(aggregationModel).length > 0 && !isPivotActive;
+
+    useGridAggregationApi<R>({
+        apiRef, hasAggregation, aggregationResult, aggregationModel, isRowGrouping, rowGroupingHandlers, rowMetaMap,
+        columns: activeColumns,
+        getRowId: getRowIdOf,
+        hierarchyField,
+    });
 
     const layout = useLayout({
         rowHeight: effectiveRowHeight,
-        pagination,
-        paginatedUnpinnedRows,
-        sortedUnpinnedRows,
-        expandedRowIds,
-        getDetailPanelHeight,
+        pagination, paginatedUnpinnedRows, sortedUnpinnedRows, expandedRowIds, getDetailPanelHeight,
+        detailPanelHeights,
         pinnedTopRowsLength: pinnedTopRows.length,
         pinnedBottomRowsLength: pinnedBottomRows.length,
-        visibleOrderedColumns,
+        pinnedTopRows, pinnedBottomRows, visibleOrderedColumns,
         pinnedColumns: effectivePinnedColumns,
         columnWidths,
         viewportWidth: state.dimensions.viewportWidth || 1000,
-        checkboxSelection,
-        hasDetailPanel,
-        rowReordering,
-        pinCheckboxColumn,
-        pinExpandColumn,
-        autoHeight,
+        checkboxSelection, hasDetailPanel, rowReordering, pinCheckboxColumn, pinExpandColumn, autoHeight,
         paginationMode,
         isLoading: state.dataSource.loading,
         pageSize: effectivePaginationModel.pageSize,
+        getRowId: getRowIdOf,
+    });
+
+    const spanning = useGridSpanning<R>({
+        pinnedTopRows, centerRows, pinnedBottomRows,
+        columns: visibleOrderedColumns,
+        leftPinnedColumns: layout.leftPinnedCols,
+        unpinnedColumns: layout.unpinnedColsWithWidth,
+        rightPinnedColumns: layout.rightPinnedCols,
+        expandedRowIds: hasDetailPanel ? expandedRowIds : undefined,
+        rowMetaMap,
+        getRowId: getRowIdOf,
+    });
+
+    // Rendered data columns with their layout-resolved widths, in render order (column group header rows).
+    const renderedDataColumns = useMemo(
+        () => [...layout.leftPinnedCols, ...layout.unpinnedColsWithWidth, ...layout.rightPinnedCols],
+        [layout.leftPinnedCols, layout.unpinnedColsWithWidth, layout.rightPinnedCols]
+    );
+
+    useGridClipboardApi({
+        apiRef,
+        columns: renderedDataColumns as unknown as GridColDef[],
+        getRowId: getRowIdOf,
+        containerRef,
+        disableKeyboardShortcut: disableClipboardCopy,
     });
+    useGridScrollToIndexesApi<R>({ apiRef, viewportRef, layout, rowHeight: effectiveRowHeight });
 
-    // Merge layout-computed widths (which include flex resolution) with user-resize
-    // overrides. The footer and other consumers that receive `columnWidths` only get
-    // the resize-override map, which has no entry for flex columns that haven't been
-    // manually resized — causing them to fall back to the raw `col.width` prop instead
-    // of the actual rendered width.
-    const resolvedColumnWidths = useMemo(() => {
-        const result: Record<string, number> = {};
-        for (const col of [...layout.leftPinnedCols, ...layout.unpinnedColsWithWidth, ...layout.rightPinnedCols]) {
-            if (!col.isSpacer) result[col.field] = col.width;
-        }
-        return { ...result, ...columnWidths };
-    }, [layout.leftPinnedCols, layout.unpinnedColsWithWidth, layout.rightPinnedCols, columnWidths]);
-
-    useEffect(() => {
-        gridData.apiRef.current.scrollToIndexes = ({ rowIndex, colIndex }) => {
-            const el = viewportRef.current;
-            if (!el) return;
-
-            if (rowIndex !== undefined && rowIndex >= 0) {
-                const rowTop = rowIndex > 0 ? layout.cumulativeHeights[rowIndex - 1] : 0;
-                const rowBottom = layout.cumulativeHeights[rowIndex] ?? rowTop;
-                const { scrollTop, clientHeight } = el;
-                if (rowTop < scrollTop) {
-                    el.scrollTop = rowTop;
-                } else if (rowBottom > scrollTop + clientHeight) {
-                    el.scrollTop = rowBottom - clientHeight;
-                }
-            }
-
-            if (colIndex !== undefined && colIndex >= 0) {
-                // colIndex is an index into all data columns: leftPinned + unpinned + rightPinned
-                const allDataCols = [...layout.leftPinnedCols, ...layout.unpinnedColsWithWidth, ...layout.rightPinnedCols];
-                const targetCol = allDataCols[colIndex];
-                if (!targetCol) return;
-                const unpinnedIndex = layout.unpinnedColsWithWidth.findIndex(c => c.field === targetCol.field);
-                if (unpinnedIndex === -1) return; // pinned column — always visible, no scroll needed
-                const colLocalLeft = unpinnedIndex > 0 ? layout.unpinnedAccWidths[unpinnedIndex - 1] : 0;
-                const colLocalRight = layout.unpinnedAccWidths[unpinnedIndex] ?? colLocalLeft;
-                const colRight = layout.leftWidth + colLocalRight;
-                const { scrollLeft, clientWidth } = el;
-                if (colLocalLeft < scrollLeft) {
-                    el.scrollLeft = colLocalLeft;
-                } else if (colRight > scrollLeft + clientWidth) {
-                    el.scrollLeft = colRight - clientWidth;
-                }
-            }
-        };
-    }, [layout, viewportRef, gridData.apiRef]);
+    const { scrollTop, scrollLeft, overscanRows, handleScroll, setViewportElement } = useGridViewport({
+        onRowsScrollEnd, overscanRowCount, rowCount: layout.unpinnedRowsLength, autoHeight, setDimensions, viewportRef,
+    });
 
     const virtualization = useGridVirtualization({
-        layout,
-        scrollTop,
-        scrollLeft,
+        layout, scrollTop, scrollLeft,
         viewportWidth: state.dimensions.viewportWidth,
         viewportHeight: state.dimensions.viewportHeight,
-        autoHeight,
-        rowReordering,
-        hasDetailPanel,
-        checkboxSelection,
-        pinCheckboxColumn,
-        pinExpandColumn,
+        autoHeight, rowReordering, hasDetailPanel, checkboxSelection, pinCheckboxColumn, pinExpandColumn,
         overscanRows,
     });
 
 
-    useEffect(() => {
-        if (!viewportRef.current) return;
-
-        const resizeObserver = new ResizeObserver((entries) => {
-            for (const entry of entries) {
-                const { width, height } = entry.contentRect;
-                setDimensions(width, height);
-            }
-        });
-
-        resizeObserver.observe(viewportRef.current);
-
-        return () => {
-            resizeObserver.disconnect();
-        };
-    }, [setDimensions]);
-
-    const handleSelectionChange = useCallback((rowId: GridRowId, isSelected: boolean) => {
-        const newSelection = new Set(selectedRowIds);
-        if (isSelected) {
-            newSelection.add(rowId);
-        } else {
-            newSelection.delete(rowId);
-        }
-        const newSelectionArray = Array.from(newSelection);
-
-        if (!isSelectionControlled) {
-            setInternalRowSelectionModel(newSelectionArray);
-        }
-        onRowSelectionModelChange?.(newSelectionArray);
-    }, [selectedRowIds, isSelectionControlled, onRowSelectionModelChange, setInternalRowSelectionModel]);
-
-    const handleSelectAll = useCallback((isSelected: boolean) => {
-        let newSelection: GridRowId[] = [];
-        if (isSelected) {
-            newSelection = effectiveRows.map((row: GridRowModel) => row.id);
-        }
-
-        if (!isSelectionControlled) {
-            setInternalRowSelectionModel(newSelection);
-        }
-        onRowSelectionModelChange?.(newSelection);
-    }, [effectiveRows, isSelectionControlled, onRowSelectionModelChange, setInternalRowSelectionModel]);
-
-    const handleSort = useCallback((field: string, direction: GridSortDirection) => {
-        const newSortModel = direction ? [{ field, sort: direction }] : [];
-
-        if (!isSortControlled) {
-            setInternalSortModel(newSortModel as GridSortItem[]);
-        }
-        onSortModelChange?.(newSortModel as GridSortItem[]);
-    }, [isSortControlled, onSortModelChange, setInternalSortModel]);
-
-    const handleSortAdd = useCallback((field: string, direction: GridSortDirection) => {
-        const existing = sortModel.filter(item => item.field !== field);
-        const newSortModel: GridSortItem[] = direction
-            ? [...existing, { field, sort: direction }]
-            : existing;
-
-        if (!isSortControlled) {
-            setInternalSortModel(newSortModel);
-        }
-        onSortModelChange?.(newSortModel);
-    }, [sortModel, isSortControlled, onSortModelChange, setInternalSortModel]);
-
-    const { focusedCell, setFocusedCell, handleFocus, handleBlur, handleKeyDown } = useGridKeyboardNavigation({
-        allRenderableRows,
-        navigationColumns,
-        checkboxSelection,
-        selectedRowIds,
-        handleSelectionChange,
-        handleDetailPanelToggle,
-        editingHandlers,
-        setKeyboardMode,
-        sortModel,
-        handleSort,
-        isCellEditable,
-        pagination,
+    const { handleSort, handleSortAdd } = useGridSortHandlers({ sortModel, onSortModelChange: handleSortModelChange });
+
+    const rowSelectionEnabled = checkboxSelection || !disableRowSelectionOnClick;
+    const {
+        focusedCell, setFocusedCell, viewportTabIndex, ensureGridFocus, handleFocus, handleBlur, handleKeyDown,
+        handleMouseDownCapture,
+    } = useGridKeyboardNavigation({
+        allRenderableRows, navigationColumns, checkboxSelection, selectedRowIds, handleSelectionChange,
+        handleDetailPanelToggle, editingHandlers, setKeyboardMode, sortModel, handleSort, handleSortAdd, multiSort,
+        isCellEditable, pagination,
         pageSize: effectivePaginationModel.pageSize,
         virtualization,
         viewportRef,
+        pinnedTopRowCount: pinnedTopRows.length,
+        getRowId: getRowIdOf,
+        rowMetaMap,
+        getSpanOrigin: spanning.getSpanOrigin,
+        onRowActivate: handleRowClick,
+        toggleRowExpansion: activeHierarchyHandlers?.toggleExpansion,
+        handleSelectAll: rowSelection.selectAll,
+        rowSelectionEnabled,
+        multipleRowSelectionEnabled: !disableMultipleRowSelection,
+        pinCheckboxColumn,
+        pinExpandColumn,
+        rowHeight: effectiveRowHeight,
     });
 
-    const handleCellClick = useCallback((params: GridCellParams<R>) => {
-        setKeyboardMode(false);
-        setFocusedCell({ id: params.row.id, field: params.field });
-
-        gridRef.current?.focus({ preventScroll: true });
-        onCellClick?.(params);
-    }, [onCellClick, setKeyboardMode, setFocusedCell]);
+    const { handleCellClick, handleHeaderClick } = useGridPointerFocusHandlers<R>({
+        ensureGridFocus, setKeyboardMode, setFocusedCell, getRowId: getRowIdOf, onCellClick,
+    });
+    const { handleHideColumn, handlePinColumn } = useGridColumnMenuHandlers({
+        columnVisibilityModel,
+        onColumnVisibilityModelChange: handleColumnVisibilityModelChange,
+        pinnedColumns,
+        onPinnedColumnsChange: handlePinnedColumnsChange,
+    });
 
-    const prevEditingCellRef = useRef(editingHandlers.editingCell);
-    useEffect(() => {
-        const wasEditing = Boolean(prevEditingCellRef.current);
-        const isEditing = Boolean(editingHandlers.editingCell);
+    const ariaRows = useGridAriaRows({
+        columnGroupingModel,
+        pinnedTopCount: pinnedTopRows.length,
+        pinnedBottomCount: pinnedBottomRows.length,
+        pagination,
+        paginationMode,
+        paginationModel: effectivePaginationModel,
+        paginationRowCount,
+        paginatedUnpinnedRowCount: paginatedUnpinnedRows.length,
+        sortedUnpinnedRowCount: sortedUnpinnedRows.length,
+    });
 
-        if (wasEditing && !isEditing) {
+    const spanRowWindow = useGridSpanRowWindow({
+        spanning,
+        renderContext: virtualization.renderContext,
+        offsetTop: virtualization.offsetTop,
+        cumulativeHeights: layout.cumulativeHeights,
+    });
 
-            gridRef.current?.focus({ preventScroll: true });
-        }
+    const visibleRows = useGridVisibleRows<R>({
+        renderContext: spanRowWindow.renderContext,
+        pinnedTopRows, pinnedBottomRows, paginatedUnpinnedRows, sortedUnpinnedRows, pagination,
+        getRowId: getRowIdOf,
+    });
 
-        prevEditingCellRef.current = editingHandlers.editingCell;
-    }, [editingHandlers.editingCell]);
+    const renderColumns = useGridSpanColumnWindow<R>({
+        spanning,
+        firstColumnIndex: virtualization.renderContext.firstColumnIndex,
+        lastColumnIndex: virtualization.renderContext.lastColumnIndex,
+        virtualColumns: virtualization.virtualColumns,
+        layout,
+        rows: visibleRows,
+    });
 
-    const visibleRows = useGridVisibleRows<R>({
-        renderContext: virtualization.renderContext,
-        pinnedTopRows,
-        pinnedBottomRows,
-        paginatedUnpinnedRows,
-        sortedUnpinnedRows,
-        pagination,
+    useGridDevWarnings({
+        paginationRequested: propPagination,
+        isRowGrouping,
+        autoHeight,
+        viewportHeight: state.dimensions.viewportHeight,
+        renderedRowCount: visibleRows.length,
+        totalRowCount: pinnedTopRows.length + centerRows.length + pinnedBottomRows.length,
+        pinnedRowsIgnored: isHierarchyEnabled && Boolean(pinnedRows?.top?.length || pinnedRows?.bottom?.length),
+        scrollHeight: virtualization.totalHeight,
+        listViewWithoutColumn: listViewRequested && !listViewColumn,
     });
 
+    const { allSelected, someSelected } = rowSelection;
 
-    const allSelected = rows.length > 0 && selectedRowIds.size === rows.length;
-    const someSelected = selectedRowIds.size > 0 && selectedRowIds.size < rows.length;
+    // Header drag-reorder keeps a column inside its column group (and ungrouped columns outside groups).
+    const headerReorderHandlers = useColumnGroupReorderGuard(columnGroupingModel, columnReorderHandlers);
 
     const hasRowSpanning = React.useMemo(() => effectiveColumns.some(c => !!c.rowSpan), [effectiveColumns]);
-    const [columnsPanelOpen, setColumnsPanelOpen] = React.useState(false);
-    const containerRef = React.useRef<HTMLDivElement>(null);
-    const standalonePanelRef = React.useRef<HTMLDivElement>(null);
-
-    const toolbarProps = React.useMemo(() => {
-        if (!slots?.toolbar) return null;
-        const reorderHandler = disableColumnReorder
-            ? undefined
-            : (fromField: string, toField: string) => {
-                const currentOrder = [...effectiveColumnOrder];
-                const fromIdx = currentOrder.indexOf(fromField);
-                const toIdx = currentOrder.indexOf(toField);
-                if (fromIdx === -1 || toIdx === -1) return;
-                const newOrder = [...currentOrder];
-                newOrder.splice(fromIdx, 1);
-                newOrder.splice(toIdx, 0, fromField);
-                if (!columnOrder) setInternalColumnOrder(newOrder);
-                const col = effectiveColumns.find(c => c.field === fromField);
-                if (col) onColumnOrderChange?.({ oldIndex: fromIdx, targetIndex: toIdx, column: col as unknown as GridColDef });
-            };
-        return {
-            apiRef: gridData.apiRef,
-            columns: orderedColumns as unknown as GridColDef[],
-            baseColumns: columns as unknown as GridColDef[],
-            aggregationModel,
-            onAggregationModelChange: handleAggregationModelChange,
-            ...(pivotMode || propPivotModel || onPivotModelChange ? {
-                pivotModel: currentPivotModel,
-                onPivotModelChange: handlePivotModelChange,
-            } : {}),
-            filterModel,
-            onFilterModelChange,
-            columnVisibilityModel,
-            onColumnVisibilityModelChange: handleColumnVisibilityModelChange,
-            onColumnReorder: reorderHandler,
-            onColumnOrderReset: disableColumnReorder ? undefined : () => setInternalColumnOrder(columns.map(c => c.field)),
-            forceColumnsOpen: columnsPanelOpen,
-            onColumnsPanelClose: () => setColumnsPanelOpen(false),
-            ...slotProps?.toolbar,
-        };
-    }, [
-        slots?.toolbar, disableColumnReorder, effectiveColumnOrder, orderedColumns, effectiveColumns,
-        columnOrder, onColumnOrderChange, setInternalColumnOrder, gridData.apiRef,
-        columns, aggregationModel, handleAggregationModelChange, pivotMode,
-        propPivotModel, onPivotModelChange, currentPivotModel, handlePivotModelChange,
-        filterModel, onFilterModelChange, columnVisibilityModel,
-        handleColumnVisibilityModelChange, columnsPanelOpen, slotProps?.toolbar,
-    ]);
-
-    // Click-outside handler for standalone column panel
-    useEffect(() => {
-        if (!columnsPanelOpen || slots?.toolbar) return;
-        function handleClickOutside(e: MouseEvent) {
-            if (standalonePanelRef.current && !standalonePanelRef.current.contains(e.target as Node)) {
-                setColumnsPanelOpen(false);
-            }
-        }
-        document.addEventListener('mousedown', handleClickOutside);
-        return () => document.removeEventListener('mousedown', handleClickOutside);
-    }, [columnsPanelOpen, slots?.toolbar]);
+    const columnsPanel = useGridColumnsPanel();
+    useGridStylesheetWarning(containerRef);
+
+    const NoRowsOverlaySlot = slots?.noRowsOverlay;
+    const LoadingOverlaySlot = slots?.loadingOverlay;
+    const loadingOverlay = LoadingOverlaySlot ? <LoadingOverlaySlot {...slotProps?.loadingOverlay} /> : undefined;
+    const noRowsOverlay = NoRowsOverlaySlot ? <NoRowsOverlaySlot {...slotProps?.noRowsOverlay} /> : undefined;
+    const FooterSlot = slots?.footer;
+    // Loading with rows on screen: the rows stay and an indicator runs over them. With no rows the
+    // body shows skeletons or the loading overlay instead, and infinite scroll appends skeleton rows.
+    const showLoadingOverRows = effectiveLoading && allRenderableRows.length > 0 && paginationMode !== 'infinite';
+    const ToolbarSlot = slots?.toolbar;
+
+    const toolbarProps = useGridToolbarProps<R>({
+        toolbar: slots?.toolbar,
+        toolbarSlotProps: slotProps?.toolbar,
+        apiRef,
+        orderedColumns,
+        baseColumns: columns,
+        aggregationModel,
+        onAggregationModelChange: handleAggregationModelChange,
+        pivotMode,
+        pivotModelProp: propPivotModel,
+        onPivotModelChangeProp: onPivotModelChange,
+        pivotModel: currentPivotModel,
+        onPivotModelChange: handlePivotModelChange,
+        filterModel,
+        onFilterModelChange: handleFilterModelChange,
+        columnVisibilityModel,
+        onColumnVisibilityModelChange: handleColumnVisibilityModelChange,
+        disableColumnReorder, columnGroupingModel, moveColumn, resetColumnOrder,
+        forceColumnsOpen: columnsPanel.toolbarPanelRequested,
+        onColumnsPanelClose: columnsPanel.closeToolbarPanel,
+    });
+
+    // Props the row renderers (top-pinned, centre and bottom-pinned rows) all take.
+    const rowRenderProps = {
+        rowReordering, columnIndexMap, editingHandlers, isCellEditable, selectedRowIds, checkboxSelection,
+        onRowClick: handleRowClick,
+        onRowDoubleClick,
+        onCellClick: handleCellClick,
+        onSelectionChange: handleSelectionChange,
+        columnWidths,
+        pinnedColumns: effectivePinnedColumns,
+        hasDetailPanel, expandedRowIds, getDetailPanelContent, getDetailPanelHeight,
+        onDetailPanelToggle: handleDetailPanelToggle,
+        onDetailPanelHeightChange: reportDetailPanelHeight,
+        pinCheckboxColumn, pinExpandColumn, focusedCell,
+        colspanMap: spanning.colspanMap,
+        rowSpanningCaches: spanning.rowSpanningCaches,
+        rowHeight: effectiveRowHeight,
+        rowMetaMap,
+    };
 
     return (
         <div
@@ -889,51 +669,65 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
             } as unknown as React.CSSProperties}
             aria-busy={effectiveLoading}
         >
-            {toolbarProps && <StableToolbar {...toolbarProps} />}
-
-            {!slots?.toolbar && (
-                <GridStandaloneColumnPanel<R>
-                    isOpen={columnsPanelOpen}
-                    containerRef={containerRef}
-                    panelRef={standalonePanelRef}
-                    effectiveColumns={effectiveColumns}
-                    columnVisibilityModel={columnVisibilityModel}
-                    effectiveColumnOrder={effectiveColumnOrder}
-                    columnOrder={columnOrder}
-                    disableColumnReorder={disableColumnReorder}
-                    onClose={() => setColumnsPanelOpen(false)}
-                    onColumnVisibilityChange={handleColumnVisibilityModelChange}
-                    onColumnOrderChange={onColumnOrderChange}
-                    setInternalColumnOrder={setInternalColumnOrder}
-                />
+            {ToolbarSlot && toolbarProps && (
+                <GridToolbarHostContext.Provider value={columnsPanel.toolbarHost}>
+                    <GridToolbarSlot component={ToolbarSlot} toolbarProps={toolbarProps} />
+                </GridToolbarHostContext.Provider>
             )}
 
+            {/* Used by the column menu's Manage columns when no GridToolbar can show the panel */}
+            <GridStandaloneColumnPanel<R>
+                isOpen={columnsPanel.standalonePanelOpen}
+                containerRef={containerRef}
+                panelRef={columnsPanel.standalonePanelRef}
+                columns={orderedColumns}
+                columnVisibilityModel={columnVisibilityModel}
+                disableColumnReorder={disableColumnReorder}
+                onClose={columnsPanel.closeStandalonePanel}
+                onColumnVisibilityChange={handleColumnVisibilityModelChange}
+                onColumnMove={moveColumn}
+                onColumnOrderReset={resetColumnOrder}
+                columnGroupingModel={columnGroupingModel}
+            />
+
+
             {listView && listViewColumn && (
                 <GridListView<R>
                     ariaLabel={ariaLabel}
                     allRenderableRows={allRenderableRows}
-                    filteredRows={filteredRows}
+                    dataRowCount={dataRows.length}
+                    pinnedTopRowCount={pinnedTopRows.length}
+                    pinnedBottomRowCount={pinnedBottomRows.length}
+                    unpinnedRowCount={sortedUnpinnedRows.length}
                     pagination={pagination}
                     effectivePaginationModel={effectivePaginationModel}
+                    currentPage={rowPipeline.currentPage}
                     pageSizeOptions={pageSizeOptions}
                     selectedRowIds={selectedRowIds}
                     listViewColumn={listViewColumn}
+                    columnsByField={columnLookup.byField}
+                    rowMetaMap={rowMetaMap}
                     noRowsLabel={effectiveNoRowsLabel}
                     rowHeight={effectiveRowHeight}
                     checkboxSelection={checkboxSelection}
                     paginationMode={paginationMode}
-                    dataSource={dataSource}
-                    serverRowCount={state.pagination.rowCount || 0}
+                    serverRowCount={paginationRowCount}
                     paginationSlot={slots?.pagination}
                     paginationSlotProps={slotProps?.pagination}
-                    localeText={localeText ? {
-                        paginationRowsPerPage: localeText.paginationRowsPerPage,
-                        paginationOf: localeText.paginationOf,
-                        paginationPage: localeText.paginationPage,
-                    } : undefined}
+                    localeText={pickPaginationLocaleText(localeText)}
                     onRowClick={handleRowClick}
+                    onRowDoubleClick={onRowDoubleClick}
                     onSelectionChange={handleSelectionChange}
                     onPaginationModelChange={handlePaginationModelChange}
+                    onRowsScrollEnd={onRowsScrollEnd}
+                    getRowId={getRowIdOf}
+                    multiselectable={rowSelectionEnabled && !disableMultipleRowSelection}
+                    selectable={rowSelectionEnabled}
+                    onToggleExpansion={activeHierarchyHandlers?.toggleExpansion}
+                    loading={effectiveLoading}
+                    loadingOverlay={loadingOverlay}
+                    noRowsOverlay={noRowsOverlay}
+                    showPaginationControls={!FooterSlot}
                 />
             )}
 
@@ -942,245 +736,185 @@ export function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridP
             ══════════════════════════════════════════════════════════════ */}
             {!listView && (
                 <div
-                    ref={(el) => {
-                        viewportRef.current = el;
-                        gridRef.current = el;
-                    }}
+                    ref={setViewportElement}
                     className="ogx__viewport"
                     onScroll={handleScroll}
                     role="grid"
                     aria-label={ariaLabel || 'Data grid'}
-                    aria-rowcount={filteredRows.length + 1}
-                    aria-colcount={
-                        columns.length +
-                        (checkboxSelection ? 1 : 0) +
-                        (hasDetailPanel ? 1 : 0) +
-                        (rowReordering ? 1 : 0)
-                    }
+                    aria-rowcount={ariaRows.rowCount}
+                    aria-colcount={navigationColumns.length}
+                    aria-multiselectable={rowSelectionEnabled && !disableMultipleRowSelection}
                     aria-busy={effectiveLoading}
-                    tabIndex={0}
+                    tabIndex={viewportTabIndex}
                     onKeyDownCapture={() => { setKeyboardMode(true); }}
-                    onMouseDownCapture={() => { setKeyboardMode(false); }}
+                    onMouseDownCapture={handleMouseDownCapture}
                     onKeyDown={handleKeyDown}
                     onFocus={handleFocus}
                     onBlur={handleBlur}
                 >
                     <div
-                        ref={contentRef}
                         className="ogx__content"
                         style={{
                             width: virtualization.totalWidth
                         }}
                         role="presentation"
                     >
-                        { }
-                        <Header
-                            columns={virtualization.virtualColumns}
-                            allColumns={effectiveColumns}
-                            columnGroupingModel={columnGroupingModel}
-                            checkboxSelection={checkboxSelection}
-                            allSelected={allSelected}
-                            someSelected={someSelected}
-                            onSelectAll={handleSelectAll}
-                            sortModel={sortModel}
-                            onSort={handleSort}
-                            onSortAdd={handleSortAdd}
-                            multiSort={multiSort}
-
-                            onColumnResize={handleColumnResize}
-                            columnWidths={columnWidths}
-                            pinnedColumns={effectivePinnedColumns}
-
-                            focusedCell={focusedCell}
-                            onHeaderClick={(field) => {
-                                setFocusedCell({ id: 'HEADER', field });
-                                setKeyboardMode(false);
-                                gridRef.current?.focus({ preventScroll: true });
-                            }}
-                            onDragStart={columnGroupingModel ? undefined : columnReorderHandlers.onDragStart}
-                            onDragOver={columnGroupingModel ? undefined : columnReorderHandlers.onDragOver}
-                            onDragEnd={columnGroupingModel ? undefined : columnReorderHandlers.onDragEnd}
-                            onDrop={columnGroupingModel ? undefined : columnReorderHandlers.onDrop}
-                            draggedColumn={columnGroupingModel ? undefined : columnReorderHandlers.draggedColumn}
-                            dragOverColumn={columnGroupingModel ? undefined : columnReorderHandlers.dragOverColumn}
-                            rowReordering={rowReordering}
-                            hasDetailPanel={hasDetailPanel}
-                            pinCheckboxColumn={pinCheckboxColumn}
-                            pinExpandColumn={pinExpandColumn}
-                            aggregationModel={aggregationModel}
-                            onHideColumn={(field) => {
-                                handleColumnVisibilityModelChange({
-                                    ...columnVisibilityModel,
-                                    [field]: false,
-                                });
-                            }}
-                            onManageColumns={() => setColumnsPanelOpen(true)}
-                            onPinColumn={(field, side) => {
-                                const left = [...(pinnedColumns?.left ?? [])];
-                                const right = [...(pinnedColumns?.right ?? [])];
-
-                                const cleanLeft = left.filter(f => f !== field);
-                                const cleanRight = right.filter(f => f !== field);
-                                if (side === 'left') {
-                                    handlePinnedColumnsChange({ left: [...cleanLeft, field], right: cleanRight });
-                                } else if (side === 'right') {
-                                    handlePinnedColumnsChange({ left: cleanLeft, right: [...cleanRight, field] });
-                                } else {
-                                    handlePinnedColumnsChange({ left: cleanLeft, right: cleanRight });
-                                }
-                            }}
-                        />
+                        {/* Header and top-pinned rows stick together, so pinned rows sit below every header row. */}
+                        <div className="ogx__sticky-top" role="presentation">
+                            <Header
+                                columns={renderColumns}
+                                allColumns={renderedDataColumns}
+                                columnGroupingModel={columnGroupingModel}
+                                checkboxSelection={checkboxSelection}
+                                allSelected={allSelected}
+                                someSelected={someSelected}
+                                onSelectAll={rowSelection.selectAll}
+                                sortModel={sortModel}
+                                onSort={handleSort}
+                                onSortAdd={handleSortAdd}
+                                multiSort={multiSort}
+
+                                onColumnResize={handleColumnResize}
+                                columnWidths={columnWidths}
+                                pinnedColumns={effectivePinnedColumns}
+
+                                focusedCell={focusedCell}
+                                columnIndexMap={columnIndexMap}
+                                onHeaderClick={handleHeaderClick}
+                                onDragStart={headerReorderHandlers.onDragStart}
+                                onDragOver={headerReorderHandlers.onDragOver}
+                                onDragEnd={headerReorderHandlers.onDragEnd}
+                                onDrop={headerReorderHandlers.onDrop}
+                                draggedColumn={headerReorderHandlers.draggedColumn}
+                                dragOverColumn={headerReorderHandlers.dragOverColumn}
+                                rowReordering={rowReordering}
+                                hasDetailPanel={hasDetailPanel}
+                                pinCheckboxColumn={pinCheckboxColumn}
+                                pinExpandColumn={pinExpandColumn}
+                                aggregationModel={aggregationModel}
+                                onHideColumn={handleHideColumn}
+                                onManageColumns={columnsPanel.openColumnsPanel}
+                                onPinColumn={handlePinColumn}
+                            />
+
+                            <GridPinnedRows<R>
+                                {...rowRenderProps}
+                                rows={pinnedTopRows}
+                                position="top"
+                                ariaRowIndexBase={ariaRows.topBase}
+                                columns={renderColumns}
+                                pinnedRows={pinnedRows}
+                                getRowId={getRowIdOf}
+                            />
+                        </div>
 
                         {/* Empty State Overlay (Standard View) — showing after header */}
                         {!effectiveLoading && !state.dataSource.error && filteredRows.length === 0 && (
-                            <GridEmptyState noRowsLabel={effectiveNoRowsLabel} width={virtualization.totalWidth} />
+                            <GridEmptyState
+                                noRowsLabel={effectiveNoRowsLabel}
+                                width={virtualization.totalWidth}
+                                overlay={noRowsOverlay}
+                            />
                         )}
 
-                        <GridPinnedRows<R>
-                            rows={pinnedTopRows}
-                            position="top"
-                            columns={virtualization.virtualColumns}
-                            selectedRowIds={selectedRowIds}
-                            checkboxSelection={checkboxSelection}
-                            onRowClick={handleRowClick}
-                            onCellClick={handleCellClick}
-                            onSelectionChange={handleSelectionChange}
-                            columnWidths={columnWidths}
-                            pinnedColumns={effectivePinnedColumns}
-                            pinnedRows={pinnedRows}
-                            hasDetailPanel={hasDetailPanel}
-                            expandedRowIds={expandedRowIds}
-                            getDetailPanelContent={getDetailPanelContent}
-                            getDetailPanelHeight={getDetailPanelHeight}
-                            onDetailPanelToggle={handleDetailPanelToggle}
-                            pinCheckboxColumn={pinCheckboxColumn}
-                            pinExpandColumn={pinExpandColumn}
-                            focusedCell={focusedCell}
-                            colspanMap={spanning.colspanMap}
-                            rowSpanningCaches={spanning.rowSpanningState.caches}
-                            rowHeight={effectiveRowHeight}
-                            rowMetaMap={rowMetaMap}
-                        />
-
                         <GridVirtualRows<R>
+                            {...rowRenderProps}
                             virtualContainerHeight={virtualization.totalHeight - virtualization.pinnedTopHeight - virtualization.pinnedBottomHeight}
-                            offsetTop={virtualization.offsetTop}
+                            offsetTop={spanRowWindow.offsetTop}
                             effectiveLoading={effectiveLoading}
                             visibleRows={visibleRows}
                             baseColumns={columns as unknown as GridColDef<R>[]}
-                            virtualColumns={virtualization.virtualColumns}
+                            virtualColumns={renderColumns}
                             viewportWidth={state.dimensions.viewportWidth}
-                            checkboxSelection={checkboxSelection}
-                            hasDetailPanel={hasDetailPanel}
-                            rowReordering={rowReordering}
-                            rowHeight={effectiveRowHeight}
-                            pinnedRows={pinnedRows}
-                            selectedRowIds={selectedRowIds}
-                            onRowClick={handleRowClick}
-                            onCellClick={handleCellClick}
-                            onSelectionChange={handleSelectionChange}
-                            columnWidths={columnWidths}
-                            pinnedColumns={effectivePinnedColumns}
-                            expandedRowIds={expandedRowIds}
-                            getDetailPanelContent={getDetailPanelContent}
-                            getDetailPanelHeight={getDetailPanelHeight}
-                            onDetailPanelToggle={handleDetailPanelToggle}
-                            pinCheckboxColumn={pinCheckboxColumn}
-                            pinExpandColumn={pinExpandColumn}
                             rowReorderHandlers={rowReorderHandlers}
-                            editingHandlers={editingHandlers}
-                            focusedCell={focusedCell}
-                            colspanMap={spanning.colspanMap}
-                            rowSpanningCaches={spanning.rowSpanningState.caches}
                             paginationMode={paginationMode}
                             dataSourceLoading={state.dataSource.loading}
                             sortedUnpinnedRowCount={sortedUnpinnedRows.length}
                             infiniteScrollSkeletonCount={Math.min(effectivePaginationModel.pageSize, 20)}
                             unpinnedRowsLength={layout.unpinnedRowsLength}
-                            rowMetaMap={rowMetaMap}
+                            lastRenderedRowIndex={spanRowWindow.renderContext.lastRowIndex}
+                            ariaRowIndexOffset={ariaRows.centerOffset}
+                            loadingOverlay={loadingOverlay}
                         />
 
-                        <GridPinnedRows<R>
-                            rows={pinnedBottomRows}
-                            position="bottom"
-                            columns={virtualization.virtualColumns}
-                            selectedRowIds={selectedRowIds}
-                            checkboxSelection={checkboxSelection}
-                            onRowClick={handleRowClick}
-                            onCellClick={handleCellClick}
-                            onSelectionChange={handleSelectionChange}
-                            columnWidths={columnWidths}
-                            pinnedColumns={effectivePinnedColumns}
-                            pinnedRows={pinnedRows}
-                            hasDetailPanel={hasDetailPanel}
-                            expandedRowIds={expandedRowIds}
-                            getDetailPanelContent={getDetailPanelContent}
-                            getDetailPanelHeight={getDetailPanelHeight}
-                            onDetailPanelToggle={handleDetailPanelToggle}
-                            pinCheckboxColumn={pinCheckboxColumn}
-                            pinExpandColumn={pinExpandColumn}
-                            focusedCell={focusedCell}
-                            colspanMap={spanning.colspanMap}
-                            rowSpanningCaches={spanning.rowSpanningState.caches}
-                            rowHeight={effectiveRowHeight}
-                            rowMetaMap={rowMetaMap}
-                        />
-
-                        {/* Aggregation Footer Row — suppressed in pivot mode because pivot rows
-                             already contain pre-aggregated values with synthetic field keys
-                             (e.g. 'Q1\u001frevenue\u001fsum') that don't match aggregationModel keys. */}
-                        {hasAggregation && !pivotMode && (
-                            <GridAggregationFooter
-                                columns={orderedColumns as unknown as GridColDef[]}
-                                aggregationModel={aggregationModel}
-                                aggregationResult={aggregationResult}
-                                columnWidths={resolvedColumnWidths}
-                                rowHeight={effectiveRowHeight}
-                                checkboxSelection={checkboxSelection}
-                                hasDetailPanel={hasDetailPanel}
-                                rowReordering={rowReordering}
-                                pinnedColumns={effectivePinnedColumns}
+                        {/* Bottom-pinned rows and the aggregation footer stick together, footer last. */}
+                        <div className="ogx__sticky-bottom" role="presentation">
+                            <GridPinnedRows<R>
+                                {...rowRenderProps}
+                                rows={pinnedBottomRows}
+                                position="bottom"
+                                rowIndexOffset={ariaRows.bottomRowIndexOffset}
+                                ariaRowIndexBase={ariaRows.bottomBase}
+                                columns={renderColumns}
+                                pinnedRows={pinnedRows}
+                                getRowId={getRowIdOf}
                             />
-                        )}
+
+                            {/* Aggregation Footer Row — laid out from the same virtual columns as the rows, so
+                                 hidden, pinned and scrolled columns line up. Off in pivot mode (hasAggregation). */}
+                            {hasAggregation && rowGroupingHandlers.rootAggregationPosition !== null && (
+                                <GridAggregationFooter
+                                    columns={virtualization.virtualColumns as unknown as GridColDef[]}
+                                    aggregationModel={aggregationModel}
+                                    aggregationResult={aggregationResult}
+                                    columnWidths={columnWidths}
+                                    rowHeight={effectiveRowHeight}
+                                    checkboxSelection={checkboxSelection}
+                                    hasDetailPanel={hasDetailPanel}
+                                    rowReordering={rowReordering}
+                                    pinCheckboxColumn={pinCheckboxColumn}
+                                    pinExpandColumn={pinExpandColumn}
+                                    pinnedColumns={effectivePinnedColumns}
+                                    loading={isAggregationLoading}
+                                />
+                            )}
+                        </div>
 
                     </div>
                 </div>
             )}
 
-            {!listView && pagination && (() => {
-                const PaginationComponent = slots?.pagination || Pagination;
-                return (
-                    <PaginationComponent
-                        page={effectivePaginationModel.page}
-                        pageSize={effectivePaginationModel.pageSize}
-                        rowCount={state.pagination.rowCount}
-                        pageSizeOptions={pageSizeOptions}
-                        onPageChange={(newPage: number) => handlePaginationModelChange({ ...effectivePaginationModel, page: newPage })}
-                        onPageSizeChange={(newPageSize: number) => handlePaginationModelChange({ ...effectivePaginationModel, pageSize: newPageSize, page: 0 })}
-                        localeText={localeText ? {
-                            paginationRowsPerPage: localeText.paginationRowsPerPage,
-                            paginationOf: localeText.paginationOf,
-                            paginationPage: localeText.paginationPage,
-                        } : undefined}
-                        {...slotProps?.pagination}
-                    />
-                );
-            })()}
-
-            {/* Accessibility Live Region */}
-            <div className="ogx-aria-live-status" role="status" aria-live="polite">
-                {effectiveLoading ? 'Loading data...' : ''}
-                {state.dataSource.error ? `Error: ${state.dataSource.error instanceof Error ? state.dataSource.error.message : 'Unknown error'}` : ''}
-                {!loading && !state.dataSource.error && (
-                    filteredRows.length === 0
-                        ? effectiveNoRowsLabel
-                        : (filterModel && ((filterModel.quickFilterValues?.length || 0) > 0 || (filterModel.items?.length || 0) > 0))
-                            ? `${filteredRows.length} ${filteredRows.length === 1 ? 'row' : 'rows'} found`
-                            : ''
-                )}
-            </div>
-
-            <GridErrorOverlay error={state.dataSource.error} />
+            {FooterSlot && (
+                <FooterSlot
+                    apiRef={gridData.apiRef}
+                    aggregationModel={aggregationModel}
+                    aggregationResult={hasAggregation ? aggregationResult : null}
+                    rowCount={isHierarchyEnabled && paginationMode !== 'server' ? dataRows.length : paginationRowCount}
+                    pagination={pagination}
+                    paginationModel={effectivePaginationModel}
+                    pageSizeOptions={pageSizeOptions}
+                    onPaginationModelChange={handlePaginationModelChange}
+                    {...slotProps?.footer}
+                />
+            )}
+
+            {!listView && !FooterSlot && pagination && (
+                <GridPaginationArea
+                    paginationSlot={slots?.pagination}
+                    paginationSlotProps={slotProps?.pagination}
+                    page={rowPipeline.currentPage}
+                    paginationModel={effectivePaginationModel}
+                    rowCount={paginationRowCount}
+                    pageSizeOptions={pageSizeOptions}
+                    onPaginationModelChange={handlePaginationModelChange}
+                    localeText={localeText}
+                />
+            )}
+
+            <GridLiveRegion
+                loading={effectiveLoading}
+                error={state.dataSource.error}
+                noRowsLabel={effectiveNoRowsLabel}
+                filteredRowCount={filteredRows.length}
+                dataRowCount={dataRows.length}
+                filterModel={filterModel}
+            />
+
+            {showLoadingOverRows && (
+                <GridLoadingOverlay overlay={loadingOverlay} />
+            )}
+
+            <GridErrorOverlay error={state.dataSource.error} onRetry={dataSource ? dataSourceHandlers.fetchRows : undefined} />
         </div>
     );
 }