@opencorestack/opengridx 2.1.0 → 3.0.1

package/lib/hooks/core/useDataGrid.ts

@@ -1,38 +1,72 @@
 
-import { useReducer, useCallback, useState, useRef, useEffect, useLayoutEffect } from 'react';
+import { useReducer, useCallback, useState, useRef, useLayoutEffect } from 'react';
 import type {
   GridInternalState as GridState,
   GridRowModel,
   GridColDef,
   GridRowId,
-  GridSortItem,
-  GridFilterModel,
-  GridPaginationModel,
   GridColumnVisibilityModel,
   GridApi
 } from '../../types';
+import { createGridApiPlaceholder } from './gridApiPlaceholder';
+
+// Sort, filter, pagination and selection deliberately have no slice here: they live in
+// useGridControlledState, which is what the grid renders from. (Copies of them in this
+// reducer used to drift from it, which made the imperative API a no-op.)
+type GetRowId = (row: GridRowModel) => GridRowId;
 
 type GridAction =
-  | { type: 'SET_ROWS'; payload: GridRowModel[] | ((prev: GridRowModel[]) => GridRowModel[]); preserveRowCount?: boolean }
+  | { type: 'SET_ROWS'; payload: GridRowModel[] | ((prev: GridRowModel[]) => GridRowModel[]); getRowId: GetRowId }
+  | { type: 'REPLACE_ROW'; id: GridRowId; row: GridRowModel }
   | { type: 'SET_COLUMNS'; payload: GridColDef[] }
-  | { type: 'SET_SORT_MODEL'; payload: GridSortItem[] }
-  | { type: 'SET_FILTER_MODEL'; payload: GridFilterModel }
-  | { type: 'SET_PAGINATION_MODEL'; payload: GridPaginationModel }
-  | { type: 'SET_SELECTION'; payload: Set<GridRowId> }
   | { type: 'SET_DIMENSIONS'; payload: { viewportWidth: number; viewportHeight: number } }
   | { type: 'SET_DATASOURCE_LOADING'; payload: boolean }
   | { type: 'SET_DATASOURCE_ERROR'; payload: unknown }
   | { type: 'SET_ROW_COUNT'; payload: number };
 
-function createInitialState<R extends GridRowModel>(rows: R[], columns: GridColDef<R>[], columnVisibilityModel: GridColumnVisibilityModel = {}): GridState {
+const defaultGetRowId: GetRowId = (row) => row.id;
+
+// Rows are re-keyed on every rows change, so warn once rather than on every update.
+let warnedDuplicateIds = false;
+
+/**
+ * Keys rows by getRowId(row). The row objects are stored as given (never copied or given an
+ * `id` field), so `idByRow` maps each one back to its key. A row object the store already
+ * holds keeps its key (`knownIds`), so a committed edit stored under the edited row's id stays
+ * there even when the stored object does not resolve to that id itself. A duplicate id keeps
+ * the first row, so a later row never silently replaces it (or renders twice), and warns once
+ * in development.
+ */
+function buildRowsState(rows: GridRowModel[], getRowId: GetRowId, knownIds?: Map<GridRowModel, GridRowId>): GridState['rows'] {
   const idRowsLookup = new Map<GridRowId, GridRowModel>();
+  const idByRow = new Map<GridRowModel, GridRowId>();
   const allRows: GridRowId[] = [];
+  const duplicates: GridRowId[] = [];
 
   rows.forEach(row => {
-    idRowsLookup.set(row.id, row);
-    allRows.push(row.id);
+    const id = knownIds?.get(row) ?? getRowId(row);
+    if (idRowsLookup.has(id)) {
+      duplicates.push(id);
+      return;
+    }
+    idRowsLookup.set(id, row);
+    idByRow.set(row, id);
+    allRows.push(id);
   });
 
+  if (duplicates.length > 0 && !warnedDuplicateIds && process.env.NODE_ENV !== 'production') {
+    warnedDuplicateIds = true;
+    console.warn(
+      `[OpenGridX] ${duplicates.length} row(s) reuse the id of an earlier row and were ignored ` +
+      `(ids: ${duplicates.slice(0, 5).map(String).join(', ')}${duplicates.length > 5 ? ', …' : ''}). ` +
+      'Every row needs a unique id; pass getRowId if the unique key lives in another field.'
+    );
+  }
+
+  return { idRowsLookup, allRows, idByRow };
+}
+
+function createInitialState<R extends GridRowModel>(rows: R[], getRowId: GetRowId, columns: GridColDef<R>[], columnVisibilityModel: GridColumnVisibilityModel = {}): GridState {
   const columnLookup = new Map<string, GridColDef>();
   const orderedFields: string[] = [];
 
@@ -42,41 +76,20 @@ function createInitialState<R extends GridRowModel>(rows: R[], columns: GridColD
   });
 
   return {
-    rows: {
-      idRowsLookup,
-      allRows
-    },
+    rows: buildRowsState(rows, getRowId),
     columns: {
       all: columns as unknown as GridColDef[],
       lookup: columnLookup,
       orderedFields,
       columnVisibilityModel
     },
-    sorting: {
-      sortModel: []
-    },
-    filter: {
-      filterModel: { items: [] }
-    },
     pagination: {
-      paginationModel: { page: 0, pageSize: 100 },
-      rowCount: rows.length
-    },
-    selection: {
-      selectedRows: new Set()
+      rowCount: undefined
     },
     pinning: {
       pinnedColumns: {},
       pinnedRows: {}
     },
-    virtualization: {
-      renderContext: {
-        firstRowIndex: 0,
-        lastRowIndex: 0,
-        firstColumnIndex: 0,
-        lastColumnIndex: 0
-      },
-    },
     dimensions: {
       rowHeight: 52,
       headerHeight: 56,
@@ -93,28 +106,31 @@ function createInitialState<R extends GridRowModel>(rows: R[], columns: GridColD
 function gridReducer(state: GridState, action: GridAction): GridState {
   switch (action.type) {
     case 'SET_ROWS': {
-      const currentRows = Array.from(state.rows.idRowsLookup.values());
-      const newRows = typeof action.payload === 'function' 
+      const currentRows = state.rows.allRows.map(id => state.rows.idRowsLookup.get(id)!);
+      const newRows = typeof action.payload === 'function'
         ? action.payload(currentRows)
         : action.payload;
 
-      const idRowsLookup = new Map<GridRowId, GridRowModel>();
-      const allRows: GridRowId[] = [];
-
-      newRows.forEach(row => {
-        idRowsLookup.set(row.id, row);
-        allRows.push(row.id);
-      });
+      // pagination.rowCount is the server-reported total only (SET_ROW_COUNT). Client row
+      // counts are derived from the rows the grid shows, so replacing rows never touches it.
+      return {
+        ...state,
+        rows: buildRowsState(newRows, action.getRowId, state.rows.idByRow),
+      };
+    }
 
+    case 'REPLACE_ROW': {
+      // Stores a committed edit under the id of the row that was edited, in the current store.
+      const previous = state.rows.idRowsLookup.get(action.id);
+      if (previous === undefined) return state;
+      const idRowsLookup = new Map(state.rows.idRowsLookup);
+      idRowsLookup.set(action.id, action.row);
+      const idByRow = new Map(state.rows.idByRow);
+      idByRow.delete(previous);
+      idByRow.set(action.row, action.id);
       return {
         ...state,
-        rows: { idRowsLookup, allRows },
-        pagination: {
-          ...state.pagination,
-          // Only override rowCount when we're NOT in server mode (i.e. no preserveRowCount flag)
-          // Server-side fetches set rowCount separately via SET_ROW_COUNT.
-          rowCount: action.preserveRowCount ? state.pagination.rowCount : newRows.length
-        }
+        rows: { ...state.rows, idRowsLookup, idByRow },
       };
     }
 
@@ -138,33 +154,6 @@ function gridReducer(state: GridState, action: GridAction): GridState {
       };
     }
 
-    case 'SET_SORT_MODEL':
-      return {
-        ...state,
-        sorting: { sortModel: action.payload }
-      };
-
-    case 'SET_FILTER_MODEL':
-      return {
-        ...state,
-        filter: { filterModel: action.payload }
-      };
-
-    case 'SET_PAGINATION_MODEL':
-      return {
-        ...state,
-        pagination: {
-          ...state.pagination,
-          paginationModel: action.payload
-        }
-      };
-
-    case 'SET_SELECTION':
-      return {
-        ...state,
-        selection: { selectedRows: action.payload }
-      };
-
     case 'SET_DIMENSIONS':
       return {
         ...state,
@@ -209,32 +198,47 @@ function gridReducer(state: GridState, action: GridAction): GridState {
 
 export interface UseDataGridParams<R extends GridRowModel = GridRowModel> {
   rows: R[];
+  /** Keys the store. Read when rows are set; defaults to `row.id`. */
+  getRowId?: (row: R) => GridRowId;
   columns: GridColDef<R>[];
   rowHeight?: number;
   headerHeight?: number;
-  rowCount?: number;
   columnVisibilityModel?: GridColumnVisibilityModel;
   initialState?: import('../../state/types').GridInitialState;
+  /**
+   * When true (no dataSource owns the rows), the store follows the `rows` param: a new rows
+   * array replaces the stored rows in the same render, so rows and the columns rendered
+   * against them always change together.
+   */
+  syncRows?: boolean;
 }
 
+/**
+ * The row store, plus dimensions and dataSource status. With `syncRows`, a new `rows` array
+ * replaces the stored rows during render (never one commit later, which let new columns run
+ * against the previous rows). Without it, `rows` only seeds the store and a dataSource fills
+ * it through setRows.
+ */
 export function useDataGrid<R extends GridRowModel = GridRowModel>(params: UseDataGridParams<R>) {
-  const { rows, columns, rowHeight = 52, headerHeight = 56, columnVisibilityModel, initialState: propInitialState } = params;
+  const { rows, columns, rowHeight = 52, headerHeight = 56, columnVisibilityModel, initialState: propInitialState, syncRows = false } = params;
+  const getRowId = (params.getRowId ?? defaultGetRowId) as GetRowId;
+
+  // Latest getRowId for dispatches from effects and event handlers. An inline getRowId
+  // therefore never re-keys (or resets) the store by itself; new rows are keyed with it.
+  const getRowIdRef = useRef(getRowId);
+  useLayoutEffect(() => { getRowIdRef.current = getRowId; });
 
   const [internalInitialState] = useState(() =>
-    createInitialState(rows, columns, columnVisibilityModel)
+    createInitialState(rows, getRowId, columns, columnVisibilityModel)
   );
 
   const [state, dispatch] = useReducer(gridReducer, {
     ...internalInitialState,
-    sorting: propInitialState?.sorting || internalInitialState.sorting,
-    filter: propInitialState?.filter || internalInitialState.filter,
     dataSource: propInitialState?.dataSource
       ? { ...internalInitialState.dataSource, ...propInitialState.dataSource }
       : internalInitialState.dataSource,
     pagination: {
-      ...internalInitialState.pagination,
-      ...(propInitialState?.pagination || {}),
-      rowCount: params.rowCount ?? propInitialState?.pagination?.rowCount ?? internalInitialState.pagination.rowCount
+      rowCount: propInitialState?.pagination?.rowCount,
     },
     dimensions: {
       ...internalInitialState.dimensions,
@@ -243,42 +247,33 @@ export function useDataGrid<R extends GridRowModel = GridRowModel>(params: UseDa
     }
   });
 
+  // The rows (and sync mode) the store was last filled from. Updating the store while
+  // rendering makes React re-render before committing, so no commit pairs the columns of
+  // this render with the rows of the previous one.
+  const [syncedFrom, setSyncedFrom] = useState({ rows, syncRows });
+  if (syncedFrom.rows !== rows || syncedFrom.syncRows !== syncRows) {
+    setSyncedFrom({ rows, syncRows });
+    if (syncRows) dispatch({ type: 'SET_ROWS', payload: rows, getRowId });
+  }
+
   const stateRef = useRef(state);
   useLayoutEffect(() => { stateRef.current = state; });
 
-  // Sync internal state when the external `rows` prop changes
-  const prevRowsRef = useRef(rows);
-  useEffect(() => {
-    if (rows !== prevRowsRef.current) {
-      prevRowsRef.current = rows;
-      dispatch({ type: 'SET_ROWS', payload: rows as GridRowModel[] });
-    }
-  }, [rows]);
+  // `_preserveRowCount` is still accepted from callers written against the old signature;
+  // replacing rows never changes the server row count any more.
+  const setRows = useCallback((rowsOrUpdater: GridRowModel[] | ((prev: GridRowModel[]) => GridRowModel[]), _preserveRowCount?: boolean) => {
+    dispatch({ type: 'SET_ROWS', payload: rowsOrUpdater, getRowId: getRowIdRef.current });
+  }, []);
 
-  const setRows = useCallback((rowsOrUpdater: GridRowModel[] | ((prev: GridRowModel[]) => GridRowModel[]), preserveRowCount?: boolean) => {
-    dispatch({ type: 'SET_ROWS', payload: rowsOrUpdater, preserveRowCount });
+  /** Replaces the row stored under `id` (a committed edit); does nothing if that row is gone. */
+  const replaceRow = useCallback((id: GridRowId, row: GridRowModel) => {
+    dispatch({ type: 'REPLACE_ROW', id, row });
   }, []);
 
   const setColumns = useCallback((newColumns: GridColDef[]) => {
     dispatch({ type: 'SET_COLUMNS', payload: newColumns });
   }, []);
 
-  const setSortModel = useCallback((sortModel: GridSortItem[]) => {
-    dispatch({ type: 'SET_SORT_MODEL', payload: sortModel });
-  }, []);
-
-  const setFilterModel = useCallback((filterModel: GridFilterModel) => {
-    dispatch({ type: 'SET_FILTER_MODEL', payload: filterModel });
-  }, []);
-
-  const setPaginationModel = useCallback((paginationModel: GridPaginationModel) => {
-    dispatch({ type: 'SET_PAGINATION_MODEL', payload: paginationModel });
-  }, []);
-
-  const setSelection = useCallback((selectedRows: Set<GridRowId>) => {
-    dispatch({ type: 'SET_SELECTION', payload: selectedRows });
-  }, []);
-
   const setDimensions = useCallback((viewportWidth: number, viewportHeight: number) => {
     dispatch({ type: 'SET_DIMENSIONS', payload: { viewportWidth, viewportHeight } });
   }, []);
@@ -295,77 +290,24 @@ export function useDataGrid<R extends GridRowModel = GridRowModel>(params: UseDa
     dispatch({ type: 'SET_ROW_COUNT', payload: count });
   }, []);
 
-  const apiRef = useRef<GridApi>({
+  // Store-backed getters live here. DataGrid installs the rest of the API (sort, filter,
+  // pagination, selection, visible rows and columns) from the state it actually renders.
+  const [initialApi] = useState<GridApi>(() => ({
+    ...createGridApiPlaceholder(),
     getRow: (id: GridRowId) => stateRef.current.rows.idRowsLookup.get(id) || null,
-    getAllRows: () => Array.from(stateRef.current.rows.idRowsLookup.values()),
-    getVisibleRows: () => Array.from(stateRef.current.rows.idRowsLookup.values()),
-    getAllFilteredRows: () => Array.from(stateRef.current.rows.idRowsLookup.values()),
-    getGroupedExportRows: () => null,
-    getAggregationResult: () => null,
-    getAggregationModel: () => null,
+    getAllRows: () => stateRef.current.rows.allRows.map(id => stateRef.current.rows.idRowsLookup.get(id)!),
     getColumn: (field: string) => stateRef.current.columns.lookup.get(field) || null,
     getAllColumns: () => stateRef.current.columns.all,
-    getVisibleColumns: () => stateRef.current.columns.all,
-    selectRow: (id: GridRowId, isSelected = true) => {
-      const newSelection = new Set(stateRef.current.selection.selectedRows);
-      if (isSelected) {
-        newSelection.add(id);
-      } else {
-        newSelection.delete(id);
-      }
-      setSelection(newSelection);
-    },
-    selectRows: (ids: GridRowId[], isSelected = true) => {
-      const newSelection = new Set(stateRef.current.selection.selectedRows);
-      ids.forEach(id => {
-        if (isSelected) {
-          newSelection.add(id);
-        } else {
-          newSelection.delete(id);
-        }
-      });
-      setSelection(newSelection);
-    },
-    getSelectedRows: () => Array.from(stateRef.current.selection.selectedRows),
-    sortColumn: (field: string, direction) => {
-      if (direction === null) {
-        setSortModel(stateRef.current.sorting.sortModel.filter(item => item.field !== field));
-      } else {
-        const existingIndex = stateRef.current.sorting.sortModel.findIndex(item => item.field === field);
-        if (existingIndex >= 0) {
-          const newModel = [...stateRef.current.sorting.sortModel];
-          newModel[existingIndex] = { field, sort: direction };
-          setSortModel(newModel);
-        } else {
-          setSortModel([...stateRef.current.sorting.sortModel, { field, sort: direction }]);
-        }
-      }
-    },
-    getSortModel: () => stateRef.current.sorting.sortModel,
-    setFilterModel,
-    getFilterModel: () => stateRef.current.filter.filterModel,
-    setPage: (page: number) => {
-      setPaginationModel({ ...stateRef.current.pagination.paginationModel, page });
-    },
-    setPageSize: (pageSize: number) => {
-      setPaginationModel({ ...stateRef.current.pagination.paginationModel, pageSize, page: 0 });
-    },
-    scrollToIndexes: () => {
-
-    },
-    copySelectedRows: () => Promise.resolve()
-  });
+  }));
+  const apiRef = useRef<GridApi>(initialApi);
 
   return {
     state,
     dispatch,
     apiRef,
     setRows,
+    replaceRow,
     setColumns,
-    setSortModel,
-    setFilterModel,
-    setPaginationModel,
-    setSelection,
     setDimensions,
     setDataSourceLoading,
     setDataSourceError,

package/lib/hooks/core/useGridAggregationApi.ts

@@ -0,0 +1,72 @@
+import { useLayoutEffect, useRef } from 'react';
+import type { MutableRefObject } from 'react';
+import { buildGroupedExportRows } from '../../utils/grouping/groupedExportRows';
+import type { GridHierarchyVisibleRowsOptions, GridGroupAggregationPosition } from '../useRowGrouping';
+import type {
+    GridAggregationModel,
+    GridAggregationResult,
+    GridApi,
+    GridColDef,
+    GridGroupedExportRow,
+    GridRowId,
+    GridRowMeta,
+    GridRowModel,
+} from '../../types';
+
+export interface UseGridAggregationApiParams<R extends GridRowModel> {
+    apiRef: MutableRefObject<GridApi>;
+    /** An aggregation model is set and the pivot is off. */
+    hasAggregation: boolean;
+    aggregationResult: GridAggregationResult;
+    aggregationModel: GridAggregationModel;
+    isRowGrouping: boolean;
+    rowGroupingHandlers: {
+        getVisibleRows: (options?: GridHierarchyVisibleRowsOptions) => R[] | null;
+        rootAggregationPosition: GridGroupAggregationPosition;
+        aggregationPositions: Map<GridRowId, GridGroupAggregationPosition>;
+    };
+    rowMetaMap: Map<GridRowId, GridRowMeta>;
+    columns: GridColDef<R>[];
+    getRowId: (row: GridRowModel) => GridRowId;
+    /** The column that shows the group labels, so export order matches the screen when sorting by it. */
+    hierarchyField?: string;
+}
+
+/**
+ * Installs `getAggregationResult`, `getAggregationModel` and `getGroupedExportRows` on the API.
+ * Like useGridApiMethods, the methods are installed in a layout effect and read the latest values
+ * from a ref, so they are live in a parent's layout effect on mount and never answer from a
+ * previous render.
+ */
+export function useGridAggregationApi<R extends GridRowModel>(params: UseGridAggregationApiParams<R>): void {
+    const { apiRef } = params;
+    const latestRef = useRef(params);
+    useLayoutEffect(() => {
+        latestRef.current = params;
+    });
+
+    useLayoutEffect(() => {
+        const latest = () => latestRef.current;
+        apiRef.current.getAggregationResult = () => (latest().hasAggregation ? latest().aggregationResult : null);
+        apiRef.current.getAggregationModel = () => (latest().hasAggregation ? latest().aggregationModel : null);
+        apiRef.current.getGroupedExportRows = (): GridGroupedExportRow[] | null => {
+            const {
+                hasAggregation, aggregationResult, aggregationModel, isRowGrouping, rowGroupingHandlers,
+                rowMetaMap, columns, getRowId, hierarchyField,
+            } = latest();
+            if (!isRowGrouping) return null;
+            // Every group expanded, filtered and sorted like the screen: collapsed groups still
+            // export their rows. Subtotals and the grand total hidden by getAggregationPosition
+            // (null) are left out, as they are on screen.
+            return buildGroupedExportRows<R>({
+                rows: rowGroupingHandlers.getVisibleRows({ expandAll: true, labelField: hierarchyField }) ?? [],
+                getRowId,
+                rowMetaMap,
+                columns,
+                aggregationModel,
+                aggregationResult: hasAggregation && rowGroupingHandlers.rootAggregationPosition !== null ? aggregationResult : null,
+                isSubtotalHidden: (groupId) => rowGroupingHandlers.aggregationPositions.get(groupId) === null,
+            });
+        };
+    }, [apiRef]);
+}

package/lib/hooks/core/useGridApiMethods.ts

@@ -0,0 +1,115 @@
+import { useLayoutEffect, useRef } from 'react';
+import type {
+    GridApi,
+    GridColDef,
+    GridFilterModel,
+    GridPaginationModel,
+    GridRowId,
+    GridRowModel,
+    GridSortItem,
+} from '../../types';
+import { isSameSelection, nextSelectionForRows } from './useGridRowSelection';
+import { nextSortModelForColumn } from './useGridHeaderHandlers';
+
+export interface UseGridApiMethodsParams {
+    apiRef: React.MutableRefObject<GridApi>;
+
+    sortModel: GridSortItem[];
+    /** Mirrors a header click: multiSort merges into the model, otherwise the model is replaced. */
+    multiSort: boolean;
+    onSortModelChange: (model: GridSortItem[]) => void;
+
+    filterModel: GridFilterModel;
+    onFilterModelChange: (model: GridFilterModel) => void;
+
+    paginationModel: GridPaginationModel;
+    onPaginationModelChange: (model: GridPaginationModel) => void;
+
+    selectedRowIds: Set<GridRowId>;
+    /**
+     * A selection change made since the last commit (see useGridControlledState), or null. It
+     * wins over `selectedRowIds`, so the API is current inside onRowSelectionModelChange.
+     */
+    getPendingRowSelectionModel?: () => GridRowId[] | null;
+    onRowSelectionModelChange: (model: GridRowId[]) => void;
+    disableMultipleRowSelection: boolean;
+    /**
+     * Rows the grid made (group headers, subtotals, auto-created parents, the pivot Grand Total):
+     * `selectRow` / `selectRows` ignore their ids, as the checkbox, click and keyboard paths do.
+     */
+    isSyntheticRowId?: (id: GridRowId) => boolean;
+
+    /** Rows on screen: pinned top, the current page (or all rows), pinned bottom. */
+    getVisibleRows: () => GridRowModel[];
+    /** Every row that passes the filter, ignoring pagination and hierarchy expansion. */
+    getAllFilteredRows: () => GridRowModel[];
+    /** Columns on screen, in display order. */
+    visibleColumns: GridColDef[];
+}
+
+/**
+ * Installs the parts of the imperative API that read or change the state the grid renders
+ * from (sort, filter, pagination, selection, visible rows and columns). Setters go through
+ * the same handlers as the UI, so controlled props and change callbacks behave the same way.
+ *
+ * The methods read the latest values from a ref refreshed in a layout effect. A setter also
+ * writes its result into that ref, so consecutive calls in one tick (selectRow(1);
+ * selectRow(2)) build on each other instead of on the last render.
+ */
+export function useGridApiMethods(params: UseGridApiMethodsParams): void {
+    const { apiRef } = params;
+    const latestRef = useRef(params);
+
+    useLayoutEffect(() => {
+        latestRef.current = params;
+    });
+
+    useLayoutEffect(() => {
+        const api = apiRef.current;
+        const latest = () => latestRef.current;
+
+        api.getSortModel = () => latest().sortModel;
+        api.sortColumn = (field, direction) => {
+            const { sortModel, multiSort, onSortModelChange } = latest();
+            const next = nextSortModelForColumn(sortModel, field, direction, multiSort);
+            latestRef.current = { ...latest(), sortModel: next };
+            onSortModelChange(next);
+        };
+
+        api.getFilterModel = () => latest().filterModel;
+        api.setFilterModel = (model) => {
+            latestRef.current = { ...latest(), filterModel: model };
+            latest().onFilterModelChange(model);
+        };
+
+        const setPaginationModel = (model: GridPaginationModel) => {
+            latestRef.current = { ...latest(), paginationModel: model };
+            latest().onPaginationModelChange(model);
+        };
+        api.setPage = (page) => setPaginationModel({ ...latest().paginationModel, page });
+        api.setPageSize = (pageSize) => setPaginationModel({ ...latest().paginationModel, pageSize, page: 0 });
+
+        const currentSelection = (): Set<GridRowId> => {
+            const pending = latest().getPendingRowSelectionModel?.();
+            return pending ? new Set(pending) : latest().selectedRowIds;
+        };
+        const setSelection = (ids: GridRowId[], isSelected: boolean) => {
+            const { disableMultipleRowSelection, onRowSelectionModelChange, isSyntheticRowId } = latest();
+            const dataIds = isSyntheticRowId ? ids.filter(id => !isSyntheticRowId(id)) : ids;
+            if (dataIds.length === 0) return;
+            const current = currentSelection();
+            const next = nextSelectionForRows(current, dataIds, isSelected, disableMultipleRowSelection);
+            // Like the UI paths, a call that changes nothing (selecting a selected row) reports nothing.
+            if (isSameSelection(current, next)) return;
+            latestRef.current = { ...latest(), selectedRowIds: new Set(next) };
+            onRowSelectionModelChange(next);
+        };
+        api.getSelectedRows = () => Array.from(currentSelection());
+        api.selectRow = (id, isSelected = true) => setSelection([id], isSelected);
+        api.selectRows = (ids, isSelected = true) => setSelection(ids, isSelected);
+
+        api.getVisibleRows = () => latest().getVisibleRows();
+        api.getAllFilteredRows = () => latest().getAllFilteredRows();
+        api.getVisibleColumns = () => latest().visibleColumns;
+    }, [apiRef]);
+}

package/lib/hooks/core/useGridApiRef.ts

@@ -1,10 +1,25 @@
-import { useRef } from 'react';
-import type { GridApi } from '../../types';
+import { useRef, useState } from 'react';
+import type { MutableRefObject } from 'react';
+import type { GridApi, GridRowModel, GridValidRowModel } from '../../types';
+import { createGridApiPlaceholder } from './gridApiPlaceholder';
 
 /**
  * Hook to create a ref for the DataGrid API.
  * This ref can be passed to the `apiRef` prop of the `DataGrid` component.
+ *
+ * `apiRef.current` is never null: until the grid mounts it holds an API whose methods are
+ * no-ops (getters return empty values), and the grid swaps in the live API in a layout
+ * effect, so it is available to the parent's layout effects and effects.
+ *
+ * The return type is spelled out so the published declaration is `MutableRefObject<GridApi>`,
+ * which matches `DataGridProps.apiRef` under both @types/react 18 and 19. Left to inference,
+ * React 19's types emit `RefObject<GridApi>`, which React 18's types treat as read-only and
+ * nullable, so `apiRef={useGridApiRef()}` failed to type-check on React 18.
+ *
+ * Pass your row type to have the row getters typed: `useGridApiRef<Invoice>().current.getRow(id)`
+ * returns `Invoice | null`.
  */
-export function useGridApiRef() {
-    return useRef<GridApi>(null!);
+export function useGridApiRef<R extends GridValidRowModel = GridRowModel>(): MutableRefObject<GridApi<R>> {
+    const [placeholder] = useState(createGridApiPlaceholder<R>);
+    return useRef<GridApi<R>>(placeholder);
 }

package/lib/hooks/core/useGridApiRefBinding.ts

@@ -0,0 +1,18 @@
+import { useLayoutEffect } from 'react';
+import type { MutableRefObject } from 'react';
+import type { GridApi } from '../../types';
+
+/**
+ * Points the consumer's `apiRef` prop at the grid's live API. A layout effect, so the live API
+ * is in place before the parent's layout effects run.
+ */
+export function useGridApiRefBinding(
+    propApiRef: MutableRefObject<GridApi> | undefined,
+    apiRef: MutableRefObject<GridApi>
+): void {
+    useLayoutEffect(() => {
+        if (propApiRef) {
+            propApiRef.current = apiRef.current;
+        }
+    }, [propApiRef, apiRef]);
+}