@opencorestack/opengridx 2.1.0 → 3.0.1

package/lib/types/index.ts

@@ -1,4 +1,5 @@
-
+import type { GridToolbarProps } from '../components/Toolbar/GridToolbar';
+import type { PaginationProps } from '../components/Pagination/Pagination';
 
 /** Unique identifier for a row (string or number). */
 export type GridRowId = string | number;
@@ -16,24 +17,55 @@ export interface GridRowModel {
 }
 
 /**
- * Internal hierarchy metadata for a row. Exposed via `params.rowMeta` in `renderCell`.
+ * The constraint on the row type `R` of the generic grid types (`DataGridProps<R>`, `GridColDef<R>`,
+ * `GridRenderCellParams<R>` …): any object type. Your own interfaces and type aliases can be used as `R`
+ * directly; they do not need an index signature or to extend `GridRowModel`. Rows without an `id`
+ * field need `getRowId`. `GridRowModel` stays the default `R` (rows with any keys, read as `unknown`).
+ * @since v3.0
+ */
+export type GridValidRowModel = object;
+
+/**
+ * A callback that is checked bivariantly in its parameter, like a method. Used for `GridColDef`
+ * options that are either a value or a function, so a column typed for your rows (`GridColDef<Row>`)
+ * can still be used where an untyped `GridColDef` is expected.
+ */
+type GridColDefCallback<P, T> = { bivarianceHack(params: P): T }['bivarianceHack'];
+
+/**
+ * Hierarchy metadata for a row. Exposed via `params.rowMeta` in `renderCell`.
  * Not present (`undefined`) for flat rows with no active tree-data or row-grouping.
  *
  * @since v1.1 — replaces the `_hasChildren` / `_treeDepth` / `_groupingField` etc.
- * properties that were previously (and incorrectly) typed on `GridRowModel`.
- * Those underscore fields remain on the row object at runtime for backward
- * compatibility; removal was deferred past v2.0 (still present as of v2.1.0)
- * to a future major version. Do not rely on them being absent yet.
+ * fields that were injected onto row objects. Since v3.0 those fields are no longer
+ * added at runtime: row objects reach `renderCell` exactly as you passed them.
  */
 export interface GridRowMeta {
+    /** The row has children to show: the expand toggle is rendered for it. */
     hasChildren?: boolean;
     treeDepth?: number;
     groupingField?: string;
     groupingValue?: unknown;
+    /** The label the grid shows for a synthetic row: the group label, or the path segment of an auto-created tree parent. */
     groupLabel?: string;
+    /**
+     * Data rows below this row at any depth that pass the active filter (row-grouping leaves, or
+     * tree-data rows; auto-created tree parents are not counted). The "(n)" shown next to group labels.
+     */
     descendantCount?: number;
     isExpanded?: boolean;
+    /**
+     * The row is synthetic: a row-grouping group row, a group subtotal row, or a tree-data parent the
+     * grid created for a path segment with no row of its own. Synthetic rows are never selected,
+     * edited or given a detail panel, and `valueGetter` is not called for them.
+     */
     isGroupRow?: boolean;
+    /**
+     * The row is the subtotal row of the group described by `groupingField` / `groupingValue`, shown
+     * after the group's children when `getAggregationPosition` returns `'footer'` for it.
+     * @since v3.0
+     */
+    isGroupFooter?: boolean;
 }
 
 export type GridAlignment = 'left' | 'center' | 'right';
@@ -65,7 +97,7 @@ export interface GridTreeNode {
     /** Display label for the group. */
     label?: string;
 
-    /** Total count of all descendants (recursive). */
+    /** Row grouping: the number of leaf rows in the group that pass the active filter (recursive). */
     descendantCount?: number;
 
     /** Count of children on the server (for lazy loading). */
@@ -78,7 +110,7 @@ export type GridSortDirection = 'asc' | 'desc' | null;
  * Metadata for a single column.
  * Governs rendering, sorting, filtering, and data transformation.
  */
-export interface GridColDef<R extends GridRowModel = GridRowModel> {
+export interface GridColDef<R extends GridValidRowModel = GridRowModel> {
   /** The unique identifier for the column, typically matching a row object key. */
   field: string;
   /** Text displayed in the column header. */
@@ -129,16 +161,25 @@ export interface GridColDef<R extends GridRowModel = GridRowModel> {
   /** Options used for 'singleSelect' type. */
   valueOptions?: Array<string | number | { value: unknown; label: string }>;
 
+  // The row callbacks below are declared as methods so that `GridColDef<Row>` stays assignable to an
+  // untyped `GridColDef` (method parameters are checked bivariantly).
   /** Function to compute a cell value from raw row data. */
-  valueGetter?: (params: GridValueGetterParams<R>) => unknown;
+  valueGetter?(params: GridValueGetterParams<R>): unknown;
+  /**
+   * Maps an edited value back onto the row when an edit is committed; return the updated row.
+   * Needed for editable columns with a `valueGetter`, whose value is not stored in `row[field]`.
+   * Without it the commit writes `row[field] = value`.
+   * @since v3.0
+   */
+  valueSetter?(params: GridValueSetterParams<R>): R;
   /** Function to format a value into a human-readable string. */
-  valueFormatter?: (params: GridValueFormatterParams<R>) => string;
+  valueFormatter?(params: GridValueFormatterParams<R>): string;
   /** Custom component or element to render in the cell. */
-  renderCell?: (params: GridRenderCellParams<R>) => React.ReactNode;
+  renderCell?(params: GridRenderCellParams<R>): React.ReactNode;
   /** Custom component or element to render in the header. */
-  renderHeader?: (params: GridRenderHeaderParams) => React.ReactNode;
-  /** Component to render when the cell is in edit mode. */
-  renderEditCell?: (params: GridRenderCellParams<R>) => React.ReactNode;
+  renderHeader?(params: GridRenderHeaderParams): React.ReactNode;
+  /** Component to render when the cell is in edit mode. Receives `onValueChange`, `onCommit` and `onCancel`. */
+  renderEditCell?(params: GridRenderEditCellParams<R>): React.ReactNode;
   /** If true, the cell's value can be modified by the user. */
   editable?: boolean;
   /** Optional stacking order (CSS z-index). */
@@ -146,10 +187,19 @@ export interface GridColDef<R extends GridRowModel = GridRowModel> {
   /** If true, the column kebab/hamburger menu is disabled. */
   disableColumnMenu?: boolean;
 
-  /** Number of columns this cell should occupy horizontally. */
-  colSpan?: number | ((params: GridRenderCellParams<R>) => number);
-  /** Number of rows this cell should occupy vertically. */
-  rowSpan?: number | ((params: GridRenderCellParams<R>) => number);
+  /**
+   * Number of columns this cell should occupy horizontally: the origin plus the next visible columns
+   * in render order, clamped to the end of the origin's pinned section. Fractions are floored,
+   * `Infinity` means "to the end", and NaN / values below 1 mean no span. `params.value` is the
+   * `valueGetter` result. A function that throws is treated as 1.
+   */
+  colSpan?: number | GridColDefCallback<GridRenderCellParams<R>, number>;
+  /**
+   * Number of rows this cell should occupy vertically, clamped to the end of its row section
+   * (top-pinned, scrolling or bottom-pinned rows) and to the first row with an expanded detail
+   * panel. Normalised like `colSpan`. With both set, the origin covers the whole rectangle.
+   */
+  rowSpan?: number | GridColDefCallback<GridRenderCellParams<R>, number>;
 
   /**
    * Custom CSS class applied to every cell in this column.
@@ -159,7 +209,7 @@ export interface GridColDef<R extends GridRowModel = GridRowModel> {
    *   cellClassName: 'my-class'
    *   cellClassName: ({ value }) => value > 100 ? 'cell--high' : 'cell--low'
    */
-  cellClassName?: string | ((params: GridRenderCellParams<R>) => string);
+  cellClassName?: string | GridColDefCallback<GridRenderCellParams<R>, string>;
 
   /**
    * Custom CSS class applied to the header cell of this column.
@@ -177,9 +227,9 @@ export interface GridColDef<R extends GridRowModel = GridRowModel> {
 }
 
 /** Column definition used exclusively in List View mode. */
-export interface GridListViewColDef<R extends GridRowModel = GridRowModel> {
+export interface GridListViewColDef<R extends GridValidRowModel = GridRowModel> {
   field: string;
-  renderCell: (params: GridRenderCellParams<R>) => React.ReactNode;
+  renderCell(params: GridRenderCellParams<R>): React.ReactNode;
 }
 
 /**
@@ -200,7 +250,7 @@ export interface GridColumnGroup {
   groupId: string;
   /** Text displayed in the group header cell. */
   headerName: string;
-  /** Optional override for the header cell background color. */
+  /** CSS class(es) added to this group's header cell(s). */
   headerClassName?: string;
   /**
    * Either an array of column field strings (leaf group)
@@ -213,7 +263,7 @@ export type GridColumnGroupingModel = GridColumnGroup[];
 
 
 /** Parameters passed to the `valueGetter` function. */
-export interface GridValueGetterParams<R extends GridRowModel = GridRowModel> {
+export interface GridValueGetterParams<R extends GridValidRowModel = GridRowModel> {
   /** The row object. */
   row: R;
   /** The field name. */
@@ -222,8 +272,21 @@ export interface GridValueGetterParams<R extends GridRowModel = GridRowModel> {
   value: unknown;
 }
 
+/**
+ * Parameters passed to the `valueSetter` function.
+ * @since v3.0
+ */
+export interface GridValueSetterParams<R extends GridValidRowModel = GridRowModel> {
+  /** The committed value from the editor. */
+  value: unknown;
+  /** The row as it was before the edit. */
+  row: R;
+  /** The field name. */
+  field: string;
+}
+
 /** Parameters passed to the `valueFormatter` function. */
-export interface GridValueFormatterParams<R extends GridRowModel = GridRowModel> {
+export interface GridValueFormatterParams<R extends GridValidRowModel = GridRowModel> {
   /** The raw value to format. */
   value: unknown;
   /** The row object. */
@@ -233,7 +296,7 @@ export interface GridValueFormatterParams<R extends GridRowModel = GridRowModel>
 }
 
 /** Parameters passed to the `renderCell` function. */
-export interface GridRenderCellParams<R extends GridRowModel = GridRowModel> {
+export interface GridRenderCellParams<R extends GridValidRowModel = GridRowModel> {
   /** The current cell value. */
   value: unknown;
   /**
@@ -258,6 +321,19 @@ export interface GridRenderCellParams<R extends GridRowModel = GridRowModel> {
   rowMeta?: GridRowMeta;
 }
 
+/**
+ * Parameters passed to `renderEditCell`. `value` is the pending (uncommitted) value.
+ * @since v3.0
+ */
+export interface GridRenderEditCellParams<R extends GridValidRowModel = GridRowModel> extends GridRenderCellParams<R> {
+  /** Updates the pending value. Call it on every change; nothing is saved until `onCommit`. */
+  onValueChange: (value: unknown) => void;
+  /** Commits the pending value (runs `processRowUpdate`) and leaves edit mode. */
+  onCommit: () => void;
+  /** Discards the pending value and leaves edit mode. */
+  onCancel: () => void;
+}
+
 export interface GridRenderHeaderParams {
   field: string;
   colDef: GridColDef;
@@ -282,13 +358,18 @@ export type GridFilterOperator =
   | 'isEmpty'
   | 'isNotEmpty'
   | 'isAnyOf'
+  | '='
   | '>'
   | '>='
   | '<'
   | '<='
   | '!='
   | 'is'
-  | 'not';
+  | 'not'
+  | 'after'
+  | 'onOrAfter'
+  | 'before'
+  | 'onOrBefore';
 
 /** Describes a filter condition for a specific column. */
 export interface GridFilterItem {
@@ -326,7 +407,7 @@ export interface GridFilterModel {
  * Configuration options for exporting the DataGrid to PDF format.
  * Requires jspdf and jspdf-autotable peer dependencies.
  */
-export interface PdfExportOptions {
+export interface PdfExportOptions<R extends GridValidRowModel = GridRowModel> {
   /**
    * Output filename without extension. Default: 'export'
    */
@@ -350,10 +431,18 @@ export interface PdfExportOptions {
   orientation?: 'portrait' | 'landscape';
 
   /**
-   * If provided, only rows whose id is in this array are exported.
+   * If provided, only rows whose id is in this array are exported. A non-empty selection takes
+   * precedence over `groupedRows` (the selected rows are exported flat), and the footer totals
+   * are recomputed over the selected rows.
    */
   selectedRows?: (string | number)[];
 
+  /**
+   * The grid's `getRowId`, when it has one: `selectedRows` holds those ids, and the grid does not
+   * copy them onto `row.id` (v3.0+). Defaults to `row.id`.
+   */
+  getRowId?: (row: R) => GridRowId;
+
   /**
    * Aggregation result from apiRef.current.getAggregationResult().
    * When provided alongside aggregationModel, appends a footer row.
@@ -390,11 +479,30 @@ export interface PdfExportOptions {
    */
   fontSize?: number;
 
+  /**
+   * A TrueType font for the whole document. The built-in Helvetica font only covers Latin-1 and
+   * WinAnsi punctuation (é, ü, €, “ ”, •). Without this option other characters (₹, Greek,
+   * Cyrillic, CJK, Devanagari, U+202F used by some locales as a thousands separator) are
+   * replaced with `?` (spaces and minus signs with their ASCII forms) and a warning is logged.
+   * `data` is the `.ttf` file as a base64 string; `boldData` is an optional bold face for the
+   * title, header and totals (the regular face is used when omitted). jsPDF does not shape
+   * complex scripts, so Devanagari or Arabic ligatures may not join.
+   * @since v3.0
+   */
+  font?: {
+    /** Font family name, e.g. 'NotoSans'. */
+    name: string;
+    /** Base64-encoded .ttf file. */
+    data: string;
+    /** Base64-encoded bold .ttf file. Default: `data`. */
+    boldData?: string;
+  };
+
   /**
    * Pre-built grouped export rows from `apiRef.current.getGroupedExportRows()`.
    * When provided, the PDF table reflects the grouping structure (group headers,
    * leaf rows, per-group subtotals, grand total) instead of a flat row list.
-   * Has no effect when the grid has no active `rowGroupingModel`.
+   * Has no effect when the grid has no active `rowGroupingModel`, or when `selectedRows` is non-empty.
    */
   groupedRows?: GridGroupedExportRow[];
 }
@@ -412,6 +520,13 @@ export interface GridGroupedExportRow {
   groupField?: string;
   /** The raw grouping value for this level (absent on 'leaf' and 'grand-total'). */
   groupValue?: unknown;
+  /**
+   * The group label exactly as the grid shows it (from `groupingValueFormatter`, else `"field: value"`),
+   * on 'group-header' and 'group-subtotal' entries from `getGroupedExportRows()`. Exporters use it for
+   * group-header rows; when absent they apply the column's `groupingValueFormatter` themselves.
+   * @since v3.0
+   */
+  groupLabel?: string;
   /** Per-group aggregation results (present on 'group-subtotal' and 'grand-total'). */
   aggregatedValues?: Record<string, unknown>;
   /** The original data row (only present when `type === 'leaf'`). */
@@ -446,7 +561,7 @@ export interface GridColumnOrderChangeParams {
 
 export type GridColumnOrder = string[]; 
 
-export interface GridRowOrderChangeParams<R extends GridRowModel = GridRowModel> {
+export interface GridRowOrderChangeParams<R extends GridValidRowModel = GridRowModel> {
   row: R;
   oldIndex: number; 
   targetIndex: number; 
@@ -461,7 +576,7 @@ export interface GridGetRowsParams {
     aggregationModel?: GridAggregationModel;
 }
 
-export interface GridGetRowsResponse<R extends GridRowModel = GridRowModel> {
+export interface GridGetRowsResponse<R extends GridValidRowModel = GridRowModel> {
   rows: R[];
   rowCount?: number;
     aggregationResults?: Record<string, unknown>;
@@ -471,7 +586,7 @@ export interface GridGetRowsResponse<R extends GridRowModel = GridRowModel> {
  * Interface for providing data to the grid from a remote source.
  * Enables server-side sorting, filtering, and pagination.
  */
-export interface GridDataSource<R extends GridRowModel = GridRowModel> {
+export interface GridDataSource<R extends GridValidRowModel = GridRowModel> {
   /**
    * Fetches a chunk of rows based on current grid state.
    * @param params Sorting, filtering, and range parameters.
@@ -495,26 +610,24 @@ export interface GridPinnedColumns {
   right?: string[];
 }
 
-export interface GridPinnedRows<R extends GridRowModel = GridRowModel> {
+export interface GridPinnedRows<R extends GridValidRowModel = GridRowModel> {
   top?: R[];
   bottom?: R[];
 }
 
-export interface GridVirtualizationState {
-  renderContext: GridRenderContext;
-}
-
 export type GridRowGroupingModel = string[]; 
 
-export type GridAggregationFunction = (values: unknown[]) => unknown;
-
 export interface GridAggregationModel {
   [field: string]: string;
 }
 
 export type GridAggregationResult = Record<string, unknown>;
 
-export type GridAggregationPosition = 'footer' | 'inline' | 'both';
+/**
+ * Where a group's aggregates are shown, as returned by `getAggregationPosition`: `'inline'` on the group row,
+ * `'footer'` on a subtotal row after the group's children, `null` hidden.
+ */
+export type GridAggregationPosition = 'inline' | 'footer' | null;
 
 export type GridPivotAggFn = 'sum' | 'avg' | 'count' | 'min' | 'max';
 
@@ -530,27 +643,16 @@ export interface GridPivotModel {
     valueFields:  GridPivotValueField[];
 }
 
-export interface GridRenderContext {
-  firstRowIndex: number;
-  lastRowIndex: number;
-  firstColumnIndex: number;
-  lastColumnIndex: number;
-}
-
 export interface GridInternalState {
   rows: {
     idRowsLookup: Map<GridRowId, GridRowModel>;
     allRows: GridRowId[];
-  };
-  sorting: {
-    sortModel: GridSortItem[];
-  };
-  filter: {
-    filterModel: GridFilterModel;
+    /** Row object → its getRowId() key. Rows are stored untouched, so this is how ids are resolved. */
+    idByRow: Map<GridRowModel, GridRowId>;
   };
   pagination: {
-    paginationModel: GridPaginationModel;
-    rowCount: number;
+    /** Server-reported total (dataSource responses); undefined until one arrives. */
+    rowCount?: number;
   };
   columns: {
     all: GridColDef[];
@@ -558,14 +660,10 @@ export interface GridInternalState {
     orderedFields: string[];
     columnVisibilityModel: GridColumnVisibilityModel;
   };
-  selection: {
-    selectedRows: Set<GridRowId>;
-  };
   pinning: {
     pinnedColumns: GridPinnedColumns;
     pinnedRows: GridPinnedRows;
   };
-  virtualization: GridVirtualizationState;
   dimensions: {
     rowHeight: number;
     headerHeight: number;
@@ -599,7 +697,7 @@ export interface GridLocaleText {
 /**
  * Main properties for the DataGrid component.
  */
-export interface DataGridProps<R extends GridRowModel = GridRowModel> {
+export interface DataGridProps<R extends GridValidRowModel = GridRowModel> {
   /** The dataset to display in the grid. */
   rows: R[];
   /** Column definitions governing how data is displayed and interacted with. */
@@ -683,8 +781,13 @@ export interface DataGridProps<R extends GridRowModel = GridRowModel> {
   disableRowSelectionOnClick?: boolean;
   /** If true, the user can only select a single row at a time. */
   disableMultipleRowSelection?: boolean;
+  /**
+   * If true, Ctrl/Cmd+C does not copy the selected rows, so the page (or your own handler) owns
+   * the shortcut. `apiRef.current.copySelectedRows()` still works. Default: false.
+   */
+  disableClipboardCopy?: boolean;
 
-  /** If true, a loading shimmer/skeleton is displayed. */
+  /** Loading state. With no rows the body shows skeleton rows (or `slots.loadingOverlay`); with rows, they stay and a progress bar (or `slots.loadingOverlay`) is shown over them. */
   loading?: boolean;
   /** Visual density of the grid. */
   density?: 'compact' | 'standard' | 'comfortable';
@@ -705,10 +808,17 @@ export interface DataGridProps<R extends GridRowModel = GridRowModel> {
 
   /** Advanced: The starting internal state of the grid. */
   initialState?: import('../state/types').GridInitialState;
-  /** Advanced: Callback fired for every internal state update. */
+  /**
+   * Called on mount and whenever the value of the sorting, filter, pagination, columns (widths, order,
+   * visibility, pinning) or density state changes. Selection, expansion and editing do not call it.
+   */
   onStateChange?: (state: import('../state/types').GridState) => void;
 
-  /** Callback fired when a row is clicked. */
+  /**
+   * Callback fired when a row is clicked. Tree-data parent rows are real rows: a click fires this and
+   * selects them like any row (the chevron expands them). Synthetic rows (row-grouping group rows,
+   * subtotal rows and auto-created tree parents) do not fire it: clicking a group row toggles it.
+   */
   onRowClick?: (params: GridRowParams<R>) => void;
   /**
    * Callback fired when a row is double-clicked. Also fires for group rows; check
@@ -720,9 +830,12 @@ export interface DataGridProps<R extends GridRowModel = GridRowModel> {
   /** Callback fired when a cell is clicked. */
   onCellClick?: (params: GridCellParams<R>) => void;
 
-  /** Renders the detail panel content for a row in Master-Detail mode. */
+  /**
+   * Renders the detail panel content for a row in Master-Detail mode. Called for data rows only:
+   * synthetic group, subtotal and auto-created tree-parent rows have no detail panel.
+   */
   getDetailPanelContent?: (params: GridDetailPanelParams<R>) => React.ReactNode;
-  /** Defines the height of the detail panel. */
+  /** Defines the height of the detail panel. Called for data rows only, like `getDetailPanelContent`. */
   getDetailPanelHeight?: (params: GridDetailPanelParams<R>) => GridDetailPanelHeight;
   /** Controlled state for expanded detail panels. */
   detailPanelExpandedRowIds?: Set<GridRowId>;
@@ -733,8 +846,17 @@ export interface DataGridProps<R extends GridRowModel = GridRowModel> {
   disableColumnReorder?: boolean; 
   /** Controlled horizontal order of column fields. */
   columnOrder?: GridColumnOrder; 
-  /** Callback fired when column order changes. */
-  onColumnOrderChange?: (params: GridColumnOrderChangeParams) => void; 
+  /**
+   * Fired when the user moves one column (header drag or Columns panel). `oldIndex` / `targetIndex`
+   * are positions in the grid's full column order: every current column, in order.
+   */
+  onColumnOrderChange?: (params: GridColumnOrderChangeParams) => void;
+  /**
+   * Fired with the whole new column order after every change: a header drag, a Columns panel drag
+   * and the panel's Reset. The easiest way to keep a controlled `columnOrder` in sync.
+   * Not fired for the generated columns of pivot mode.
+   */
+  onColumnOrderModelChange?: (columnOrder: GridColumnOrder) => void;
 
   /** If true, rows can be reordered via drag-and-drop. */
   rowReordering?: boolean; 
@@ -743,10 +865,17 @@ export interface DataGridProps<R extends GridRowModel = GridRowModel> {
 
   /** If true, enables hierarchical tree data display. */
   treeData?: boolean;
-  /** Function to get the path (array of strings) for a row in Tree Data mode. */
+  /**
+   * Function to get the path (array of strings) for a row in Tree Data mode. Required with `treeData`:
+   * without it the rows are shown flat. Segments may contain any character, including '/'. Keep the
+   * function identity stable (module scope or useCallback); a new function rebuilds the tree.
+   */
   getTreeDataPath?: (row: R) => string[];
-  /** Optional override for the grouping column. */
-  groupingColDef?: GridColDef<R>;
+  /**
+   * Adds a dedicated grouping column (pinned left) under row grouping or tree data, configured by these
+   * fields. Every key is optional: `field` is always `'__group__'` (a `field` you pass is ignored).
+   */
+  groupingColDef?: Partial<GridColDef<R>>;
   /** Initial expansion depth for Tree Data. */
   defaultGroupingExpansionDepth?: number;
 
@@ -756,7 +885,12 @@ export interface DataGridProps<R extends GridRowModel = GridRowModel> {
   aggregationModel?: GridAggregationModel;
   /** Callback fired when aggregation model changes. */
   onAggregationModelChange?: (model: GridAggregationModel) => void;
-  /** Advanced: Controls where aggregation results appear relative to groups. */
+  /**
+   * Advanced: where aggregation results appear. Called for every group node (with its current
+   * `isExpanded`) and once with `null` for the grand total. `'inline'` (default for groups) shows them
+   * on the group row; `'footer'` on a subtotal row after the group's children while it is expanded
+   * (inline while collapsed); `null` hides them. For the grand total, `null` hides the footer row.
+   */
   getAggregationPosition?: (groupNode: GridTreeNode | null) => 'inline' | 'footer' | null;
 
   /** If true, switches the grid to multidimensional Pivot Mode. */
@@ -778,29 +912,48 @@ export interface DataGridProps<R extends GridRowModel = GridRowModel> {
   /** Callback fired when scrolling reaches the bottom of the grid viewport. */
   onRowsScrollEnd?: (params: GridRowScrollEndParams) => void;
 
-  /** Advanced: Reactive reference to the internal API for imperative control. */
-  apiRef?: React.MutableRefObject<GridApi>;
+  /**
+   * Advanced: reactive reference to the internal API for imperative control. Pass
+   * `useGridApiRef<MyRow>()` to have the row getters typed as `MyRow`; a plain `useGridApiRef()` also works.
+   */
+  apiRef?: React.MutableRefObject<GridApi<R>> | React.MutableRefObject<GridApi>;
 
   /** Custom components to replace internal grid parts. */
   slots?: {
-    /** Component rendered as the grid toolbar. */
-    toolbar?: React.ComponentType<Record<string, unknown>>;
-    /** Component rendered as the pagination control. */
-    pagination?: React.ComponentType<Record<string, unknown>>;
-    /** Component rendered when the grid is empty. */
-    noRowsOverlay?: React.ComponentType<Record<string, unknown>>;
-    /** Component rendered during loading states. */
-    loadingOverlay?: React.ComponentType<Record<string, unknown>>;
-    /** Component rendered at the very bottom of the grid. */
-    footer?: React.ComponentType<Record<string, unknown>>;
+    /**
+     * Component rendered as the grid toolbar. Receives `GridToolbarSlotProps` (plus `slotProps.toolbar`),
+     * so it can be typed with `GridToolbarProps` or wrap the exported `GridToolbar`.
+     */
+    toolbar?: React.ComponentType<GridToolbarSlotProps & Record<string, unknown>>;
+    /**
+     * Component rendered as the pagination control. Receives `PaginationProps` (plus `slotProps.pagination`),
+     * so it can be typed with `PaginationProps` or wrap the exported `Pagination`.
+     */
+    pagination?: React.ComponentType<GridPaginationSlotProps & Record<string, unknown>>;
+    /** Component rendered when the grid is empty. Receives only `slotProps.noRowsOverlay`. */
+    noRowsOverlay?: React.ComponentType<GridOverlaySlotProps>;
+    /** Component rendered during loading states. Receives only `slotProps.loadingOverlay`. */
+    loadingOverlay?: React.ComponentType<GridOverlaySlotProps>;
+    /**
+     * Component rendered at the very bottom of the grid, in place of the pagination area.
+     * Receives `GridFooterSlotProps` (plus `slotProps.footer`).
+     */
+    footer?: React.ComponentType<GridFooterSlotProps & Record<string, unknown>>;
   };
   /** Properties passed directly to custom slots. */
   slotProps?: {
-    toolbar?: Record<string, unknown>;
-    pagination?: Record<string, unknown>;
-    noRowsOverlay?: Record<string, unknown>;
-    loadingOverlay?: Record<string, unknown>;
-    footer?: Record<string, unknown>;
+    /**
+     * Merged over the props the grid passes to the toolbar. Typed as `GridToolbarProps` (so render props
+     * such as `renderQuickFilter` are checked and their parameters inferred), plus any extra keys a custom
+     * toolbar reads. `columns` / `baseColumns` are not checked, so typed `GridColDef<R>[]` can be passed.
+     */
+    toolbar?: Omit<Partial<GridToolbarProps>, 'columns' | 'baseColumns'> & Record<string, unknown>;
+    /** Merged over the `PaginationProps` the grid passes to the pagination slot. */
+    pagination?: Partial<GridPaginationSlotProps> & Record<string, unknown>;
+    noRowsOverlay?: GridOverlaySlotProps;
+    loadingOverlay?: GridOverlaySlotProps;
+    /** Merged over the `GridFooterSlotProps` the grid passes to the footer slot. */
+    footer?: Partial<GridFooterSlotProps> & Record<string, unknown>;
   };
 
   /** When true, renders the grid as a single-column list of cards. Perfect for mobile/responsive views. */
@@ -815,26 +968,73 @@ export interface DataGridProps<R extends GridRowModel = GridRowModel> {
   columnGroupingModel?: GridColumnGroupingModel;
 }
 
-export interface GridEditCellProps<V = unknown> {
-  id: GridRowId;
-  field: string;
-  value?: V;
-  formattedValue?: string;
+/**
+ * `DataGridProps<R>` with untyped `columns` (`GridColDef[]`, i.e. `GridColDef<GridRowModel>[]`). `DataGrid`
+ * accepts these props as well as `DataGridProps<R>`, so columns written without a row type work with rows of
+ * any type `R`. Their callbacks then see `params.row` as `GridRowModel`; type the columns as
+ * `GridColDef<R>[]` to get your row type there.
+ * @since v3.0
+ */
+export type DataGridUntypedColumnsProps<R extends GridValidRowModel = GridRowModel> =
+  Omit<DataGridProps<R>, 'columns'> & { columns: GridColDef[] };
+
+/**
+ * Props the grid passes to `slots.toolbar`, before `slotProps.toolbar` is merged over them: the
+ * `GridToolbarProps` it controls (columns, models and their change handlers) plus `apiRef`.
+ * @since v3.0
+ */
+export interface GridToolbarSlotProps extends GridToolbarProps {
+  apiRef: React.MutableRefObject<GridApi>;
 }
 
-export type GridRowModes = 'view' | 'edit';
+/**
+ * Props the grid passes to `slots.pagination`, before `slotProps.pagination` is merged over them.
+ * @since v3.0
+ */
+export type GridPaginationSlotProps = PaginationProps;
+
+/**
+ * Props of `slots.noRowsOverlay` and `slots.loadingOverlay`: the grid passes none of its own, only
+ * `slotProps.noRowsOverlay` / `slotProps.loadingOverlay`.
+ * @since v3.0
+ */
+export type GridOverlaySlotProps = Record<string, unknown>;
 
-export interface GridRowModesModel {
-  [id: GridRowId]: { mode: GridRowModes; fieldToFocus?: string };
+/**
+ * Props the grid passes to `slots.footer`, before `slotProps.footer` is merged over them.
+ * @since v3.0
+ */
+export interface GridFooterSlotProps {
+  apiRef: React.MutableRefObject<GridApi>;
+  /** The active aggregation model (`{}` when none). */
+  aggregationModel: GridAggregationModel;
+  /** The grand-total aggregation result, or `null` when no aggregation is active. */
+  aggregationResult: GridAggregationResult | null;
+  /**
+   * The built-in pager's count: rows after filtering, pinned rows excluded (`rowCount` from the
+   * server in server pagination mode). Under tree data / row grouping: the filtered data rows.
+   */
+  rowCount: number;
+  /** Whether pagination is in effect (false under row grouping and infinite scroll). */
+  pagination: boolean;
+  paginationModel: GridPaginationModel;
+  pageSizeOptions: number[];
+  onPaginationModelChange: (model: GridPaginationModel) => void;
 }
 
-export interface GridRowParams<R extends GridRowModel = GridRowModel> {
+/** The `slots` prop of `DataGrid`: components that replace built-in parts of the grid. */
+export type GridSlots = NonNullable<DataGridProps['slots']>;
+
+/** The `slotProps` prop of `DataGrid`: props for each slot, keyed like `GridSlots`. */
+export type GridSlotProps = NonNullable<DataGridProps['slotProps']>;
+
+export interface GridRowParams<R extends GridValidRowModel = GridRowModel> {
   row: R;
   id: GridRowId;
   rowIndex: number;
 }
 
-export interface GridCellParams<R extends GridRowModel = GridRowModel> {
+export interface GridCellParams<R extends GridValidRowModel = GridRowModel> {
   row: R;
   field: string;
   value: unknown;
@@ -843,7 +1043,7 @@ export interface GridCellParams<R extends GridRowModel = GridRowModel> {
   colIndex: number;
 }
 
-export interface GridDetailPanelParams<R extends GridRowModel = GridRowModel> {
+export interface GridDetailPanelParams<R extends GridValidRowModel = GridRowModel> {
   row: R;
   id: GridRowId;
   rowIndex: number;
@@ -851,31 +1051,26 @@ export interface GridDetailPanelParams<R extends GridRowModel = GridRowModel> {
 
 export type GridDetailPanelHeight = number | 'auto';
 
-export type GridDetailPanelContent<R extends GridRowModel = GridRowModel> = 
-  | React.ReactNode 
-  | ((params: GridDetailPanelParams<R>) => React.ReactNode);
-
-export interface GridDetailPanelState {
-  expandedRowIds: Set<GridRowId>;
-  contentCache: Map<GridRowId, React.ReactNode>;
-}
-
 /**
  * The Imperative API for interacting with the DataGrid.
  * Access this via the `apiRef` prop or a ref passed to the component.
  */
-export interface GridApi {
+/**
+ * The imperative grid API. `R` types the row getters (`getRow`, `getAllRows`, `getVisibleRows`,
+ * `getAllFilteredRows`); it defaults to `GridRowModel`, so `GridApi` alone keeps working.
+ */
+export interface GridApi<R extends GridValidRowModel = GridRowModel> {
   /**
    * Returns the row model with the given ID.
    * @param id The row unique ID.
    */
-  getRow: (id: GridRowId) => GridRowModel | null;
+  getRow: (id: GridRowId) => R | null;
   /** Returns all rows currently loaded into the grid. */
-  getAllRows: () => GridRowModel[];
+  getAllRows: () => R[];
   /** Returns all rows currently visible after filtering and sorting. */
-  getVisibleRows: () => GridRowModel[];
+  getVisibleRows: () => R[];
   /** Returns all filtered and sorted rows, ignoring pagination. Use this for full-dataset exports. */
-  getAllFilteredRows: () => GridRowModel[];
+  getAllFilteredRows: () => R[];
   /**
    * Returns an ordered flat list of `GridGroupedExportRow` entries that mirrors the
    * on-screen grouping tree: group-headers, leaf rows, per-group subtotals, and a
@@ -933,9 +1128,11 @@ export interface GridApi {
   scrollToIndexes: (params: { rowIndex?: number; colIndex?: number }) => void;
 
   /**
-   * Programmatically copies all currently selected rows to the clipboard as TSV.
-   * Equivalent to the user pressing Ctrl+C / Cmd+C.
-   * @returns A Promise that resolves when the copy completes.
+   * Programmatically copies all currently selected rows to the clipboard as TSV: every selected
+   * row that passes the filter (other pages, collapsed groups and pinned rows included), with the
+   * visible columns in screen order. Equivalent to the user pressing Ctrl+C / Cmd+C.
+   * @returns A Promise that resolves when the text is written (or when no selected row was found,
+   * in which case nothing is written) and rejects when the clipboard write fails.
    */
   copySelectedRows: () => Promise<void>;
 }