@opencorestack/opengridx 2.1.0 → 3.0.1

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import { default as default_2 } from 'react';
 import { JSX } from 'react/jsx-runtime';
-import { RefObject } from 'react';
+import { MutableRefObject } from 'react';
 
 export declare const amberTheme: GridTheme;
 
@@ -8,7 +8,7 @@ export declare type BuiltInAggFn = 'sum' | 'avg' | 'count' | 'min' | 'max' | 'un
 
 export declare const Button: default_2.FC<ButtonProps>;
 
-declare interface ButtonProps extends default_2.ButtonHTMLAttributes<HTMLButtonElement> {
+export declare interface ButtonProps extends default_2.ButtonHTMLAttributes<HTMLButtonElement> {
     variant?: 'text' | 'outlined' | 'contained';
     size?: 'small' | 'medium' | 'large';
     color?: 'primary' | 'secondary' | 'default';
@@ -18,6 +18,16 @@ declare interface ButtonProps extends default_2.ButtonHTMLAttributes<HTMLButtonE
 
 export declare const Cell: typeof CellImpl;
 
+/**
+ * Column-span information for one cell.
+ *
+ * Only span origins (colSpan > 1) and the cells they cover have an entry; every other cell has none
+ * and renders at its own resolved width. `leftVisibleCellIndex` / `rightVisibleCellIndex` are indices
+ * into the rendered data columns (left-pinned, then unpinned, then right-pinned).
+ *
+ * The hook stores only `colSpan` for an origin. `Row` adds the merged `width` and `flexGrow` from the
+ * columns it renders, so resizing a column never recomputes the spans.
+ */
 declare type CellColSpanInfo = {
     spannedByColSpan: true;
     rightVisibleCellIndex: number;
@@ -26,13 +36,14 @@ declare type CellColSpanInfo = {
     spannedByColSpan: false;
     cellProps: {
         colSpan: number;
-        width: number;
+        width?: number;
+        flexGrow?: number;
     };
 };
 
 declare function CellImpl<R extends GridRowModel = GridRowModel>(props: CellProps<R>): JSX.Element | null;
 
-declare interface CellProps<R extends GridRowModel = GridRowModel> {
+export declare interface CellProps<R extends GridRowModel = GridRowModel> {
     onCellClick?: (params: GridCellParams<R>) => void;
     onCellEditStart?: (field: string, value: unknown) => void;
     onCellValueChange?: (field: string, newValue: unknown) => void;
@@ -41,27 +52,38 @@ declare interface CellProps<R extends GridRowModel = GridRowModel> {
     colDef: GridColDef<R>;
     rowIndex: number;
     colIndex: number;
+    /** 1-based `aria-colindex` (system columns included). Defaults to `colIndex + 1`. */
+    ariaColIndex?: number;
     isSelected?: boolean;
     onClick?: (event: default_2.MouseEvent) => void;
     width?: number;
     pinnedPosition?: GridPinnedPosition | null;
     pinnedOffset?: number;
+    /**
+     * The cell is the last left-pinned or first right-pinned cell of its row: it gets
+     * `ogx__cell--pinned-left-last` / `ogx__cell--pinned-right-first` (the section edge shadow).
+     */
+    isPinnedEdge?: boolean;
     isFocused?: boolean;
     isFocusVisible?: boolean;
+    /** Whether this cell may enter edit mode (column, row and `isCellEditable` already resolved). */
     isEditable?: boolean;
     isEditing?: boolean;
     onEditStart?: () => void;
-    onEditStop?: (cancel?: boolean) => void;
+    /** Ends this cell's edit. `field` identifies the cell, so a late call cannot end another cell's edit. */
+    onEditStop?: (cancel?: boolean, field?: string) => void;
     onValueChange?: (newValue: unknown) => void;
     colSpanInfo?: CellColSpanInfo;
     rowSpan?: number;
     isHiddenByRowSpan?: boolean;
     rowMeta?: GridRowMeta;
+    /** The error the column's valueGetter threw for this cell (computed by Row); shown as a cell error. */
+    valueError?: unknown;
 }
 
 export declare const Checkbox: default_2.FC<CheckboxProps>;
 
-declare interface CheckboxProps extends Omit<default_2.InputHTMLAttributes<HTMLInputElement>, 'type'> {
+export declare interface CheckboxProps extends Omit<default_2.InputHTMLAttributes<HTMLInputElement>, 'type'> {
     indeterminate?: boolean;
     label?: string;
     inputRef?: default_2.Ref<HTMLInputElement>;
@@ -69,9 +91,9 @@ declare interface CheckboxProps extends Omit<default_2.InputHTMLAttributes<HTMLI
 
 declare type ColumnKey = string;
 
-export declare function ColumnVisibilityPanel<R extends GridRowModel = GridRowModel>(props: ColumnVisibilityPanelProps<R>): JSX.Element;
+export declare function ColumnVisibilityPanel<R extends GridValidRowModel = GridRowModel>(props: ColumnVisibilityPanelProps<R>): JSX.Element;
 
-export declare interface ColumnVisibilityPanelProps<R extends GridRowModel = GridRowModel> {
+export declare interface ColumnVisibilityPanelProps<R extends GridValidRowModel = GridRowModel> {
     columns: GridColDef<R>[];
     visibleColumns: Set<string>;
     onVisibilityChange: (field: string, isVisible: boolean) => void;
@@ -85,25 +107,53 @@ export declare interface ColumnVisibilityPanelProps<R extends GridRowModel = Gri
 
 export declare const compactTheme: GridTheme;
 
-export declare interface CsvExportOptions {
+export declare interface CsvExportOptions<R extends GridValidRowModel = GridRowModel> {
     fileName?: string;
     includeHeaders?: boolean;
     delimiter?: string;
+    /**
+     * Export only these row IDs. A non-empty selection takes precedence over `groupedRows` (the
+     * selected rows are exported flat), and the totals row is 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;
     aggregationResult?: Record<string, unknown> | null;
     aggregationModel?: GridAggregationModel | null;
     /** When provided, emits group headers, leaf rows, subtotals, and a grand total instead of a flat row list. */
     groupedRows?: GridGroupedExportRow[];
+    /**
+     * Prefix text cells that start with `=`, `+`, `-`, `@`, tab or carriage return with `'`, so
+     * spreadsheet apps show them as text instead of running them as formulas (CSV injection).
+     * Plain signed numbers are left alone. Default: `true`
+     * @since v3.0
+     */
+    escapeFormulas?: boolean;
+    /**
+     * Start the file with a UTF-8 byte-order mark, so Excel reads non-ASCII text (é, ü, ₹, 中文)
+     * correctly. Default: `true`
+     * @since v3.0
+     */
+    bom?: boolean;
 }
 
 export declare const darkTheme: GridTheme;
 
-export declare function DataGrid<R extends GridRowModel = GridRowModel>(props: DataGridProps<R>): JSX.Element;
+/**
+ * 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 declare function DataGrid<R extends GridValidRowModel = GridRowModel>(props: DataGridProps<R>): default_2.JSX.Element;
+
+export declare function DataGrid<R extends GridValidRowModel = GridRowModel>(props: DataGridUntypedColumnsProps<R>): default_2.JSX.Element;
 
 /**
  * Main properties for the DataGrid component.
  */
-export declare interface DataGridProps<R extends GridRowModel = GridRowModel> {
+export declare 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. */
@@ -178,7 +228,12 @@ export declare 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, a loading shimmer/skeleton is displayed. */
+    /**
+     * 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;
+    /** 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';
@@ -196,9 +251,16 @@ export declare interface DataGridProps<R extends GridRowModel = GridRowModel> {
     localeText?: GridLocaleText;
     /** Advanced: The starting internal state of the grid. */
     initialState?: 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: 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
@@ -209,9 +271,12 @@ export declare interface DataGridProps<R extends GridRowModel = GridRowModel> {
     onRowDoubleClick?: (params: GridRowParams<R>) => void;
     /** 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>;
@@ -221,18 +286,34 @@ export declare interface DataGridProps<R extends GridRowModel = GridRowModel> {
     disableColumnReorder?: boolean;
     /** Controlled horizontal order of column fields. */
     columnOrder?: GridColumnOrder;
-    /** Callback fired when column order changes. */
+    /**
+     * 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;
     /** Callback fired when rows are reordered. */
     onRowOrderChange?: (params: GridRowOrderChangeParams<R>) => void;
     /** 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;
     /** Controlled state for row grouping. */
@@ -241,7 +322,12 @@ export declare 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. */
     pivotMode?: boolean;
@@ -259,28 +345,47 @@ export declare interface DataGridProps<R extends GridRowModel = GridRowModel> {
     dataSource?: GridDataSource<R>;
     /** 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. */
     listView?: boolean;
@@ -302,9 +407,20 @@ export declare interface DataGridThemeProviderProps {
     style?: default_2.CSSProperties;
 }
 
+/**
+ * `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 declare type DataGridUntypedColumnsProps<R extends GridValidRowModel = GridRowModel> = Omit<DataGridProps<R>, 'columns'> & {
+    columns: GridColDef[];
+};
+
 export declare const emeraldTheme: GridTheme;
 
-export declare interface ExcelAdvancedExportOptions {
+export declare interface ExcelAdvancedExportOptions<R extends GridValidRowModel = GridRowModel> {
     /** Output filename (default: 'export.xlsx') */
     fileName?: string;
     /**
@@ -332,8 +448,13 @@ export declare interface ExcelAdvancedExportOptions {
     aggregationResult?: Record<string, unknown> | null;
     /** Current aggregation model */
     aggregationModel?: GridAggregationModel | null;
-    /** Currently selected row IDs */
+    /** Currently selected row IDs, written by `rows: 'selected'` sheets */
     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;
     /**
      * Grouped row structure, typically from `apiRef.current.getGroupedExportRows()`.
      * When provided, sheets with `rows: 'all'` are written in grouped order: group-header,
@@ -357,10 +478,10 @@ export declare interface ExcelColumnStyle {
     /** Horizontal alignment override */
     alignment?: 'left' | 'center' | 'right';
     /**
-     * If true, the cell value (expected to be an image URL string) will be
-     * fetched and embedded as an inline image in the cell.
-     * Requires the image server to serve CORS headers. Falls back to the
-     * raw URL string if the fetch fails (a warning is logged to the console).
+     * If true, the cell value (an image URL string, after `valueGetter`) is fetched and embedded
+     * as an inline image in the cell. PNG, JPEG and GIF are supported (detected from the bytes).
+     * Requires the image server to serve CORS headers. Falls back to the raw URL string if the
+     * fetch fails or the image is in another format (a warning is logged to the console).
      */
     embedImage?: boolean;
     /** Width of the embedded image in pixels (default: 40) */
@@ -369,21 +490,45 @@ export declare interface ExcelColumnStyle {
     imageHeight?: number;
 }
 
-export declare interface ExcelExportOptions {
+export declare interface ExcelExportOptions<R extends GridValidRowModel = GridRowModel> {
+    /**
+     * Output filename. The file is an HTML table that Excel opens as a legacy `.xls` workbook, so a
+     * `.xlsx` extension is replaced with `.xls` (Excel refuses HTML content named `.xlsx`). Use
+     * `exportToExcelAdvanced` for a real `.xlsx`. Default: `'export.xls'`
+     */
     fileName?: string;
+    /** Sheet tab name. Characters Excel rejects are replaced and the name is cut to 31 characters. Default: `'Sheet1'` */
     sheetName?: string;
     includeHeaders?: boolean;
+    /**
+     * Export only these row IDs. A non-empty selection takes precedence over `groupedRows` (the
+     * selected rows are exported flat), and the totals rows 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;
     aggregationResult?: Record<string, unknown> | null;
     aggregationModel?: GridAggregationModel | null;
     /** When provided, emits group headers, leaf rows, subtotals, and a grand total instead of a flat row list. */
     groupedRows?: GridGroupedExportRow[];
+    /**
+     * Prefix text cells that start with `=`, `+`, `-`, `@`, tab or carriage return with `'`, so
+     * Excel does not run them as formulas. Default: `true`
+     * @since v3.0
+     */
+    escapeFormulas?: boolean;
 }
 
 export declare interface ExcelSheetDefinition {
-    /** Sheet tab name (max 31 chars) */
+    /**
+     * Sheet tab name. Characters Excel rejects (`\ / ? * : [ ]`) become `-`, the name is cut to
+     * 31 characters, and a duplicate name gets a " (2)" suffix.
+     */
     name: string;
-    /** Which rows to include. Default: 'all' */
+    /** Which rows to include. `'selected'` writes only `selectedRows` (none when nothing is selected). Default: 'all' */
     rows?: 'all' | 'selected';
     /** Include header row. Default: true */
     includeHeaders?: boolean;
@@ -397,9 +542,13 @@ export declare interface ExcelSheetDefinition {
     alternateRowColor?: string | false;
 }
 
-export declare function exportToCsv<R extends GridRowModel>(rows: R[], columns: GridColDef<R>[], options?: CsvExportOptions): void;
+export declare function exportToCsv<R extends GridValidRowModel = GridRowModel>(rows: R[], columns: GridColDef<R>[], options?: CsvExportOptions<R>): void;
 
-export declare function exportToExcel<R extends GridRowModel>(rows: R[], columns: GridColDef<R>[], options?: ExcelExportOptions): void;
+export declare function exportToCsv<R extends GridValidRowModel = GridRowModel>(rows: R[], columns: GridColDef[], options?: CsvExportOptions<R>): void;
+
+export declare function exportToExcel<R extends GridValidRowModel = GridRowModel>(rows: R[], columns: GridColDef<R>[], options?: ExcelExportOptions<R>): void;
+
+export declare function exportToExcel<R extends GridValidRowModel = GridRowModel>(rows: R[], columns: GridColDef[], options?: ExcelExportOptions<R>): void;
 
 /**
  * Export the grid data to a real XLSX file using ExcelJS.
@@ -409,29 +558,43 @@ export declare function exportToExcel<R extends GridRowModel>(rows: R[], columns
  * ExcelJS is loaded lazily so it does not affect bundle size for apps
  * that only use CSV/JSON export.
  */
-export declare function exportToExcelAdvanced<R extends GridRowModel>(rows: R[], columns: GridColDef<R>[], options?: ExcelAdvancedExportOptions): Promise<void>;
+export declare function exportToExcelAdvanced<R extends GridValidRowModel = GridRowModel>(rows: R[], columns: GridColDef<R>[], options?: ExcelAdvancedExportOptions<R>): Promise<void>;
+
+export declare function exportToExcelAdvanced<R extends GridValidRowModel = GridRowModel>(rows: R[], columns: GridColDef[], options?: ExcelAdvancedExportOptions<R>): Promise<void>;
 
 /**
- * Export data to JSON format
+ * Export data to JSON format. Values are written raw (after `valueGetter`, without
+ * `valueFormatter`), including aggregation values, so the output can be parsed as data.
  */
-export declare function exportToJson<R extends GridRowModel>(rows: R[], columns: GridColDef<R>[], options?: JsonExportOptions): void;
+export declare function exportToJson<R extends GridValidRowModel = GridRowModel>(rows: R[], columns: GridColDef<R>[], options?: JsonExportOptions<R>): void;
 
-export declare function exportToPdf<R extends GridRowModel>(rows: R[], columns: GridColDef<R>[], options?: PdfExportOptions): Promise<void>;
+export declare function exportToJson<R extends GridValidRowModel = GridRowModel>(rows: R[], columns: GridColDef[], options?: JsonExportOptions<R>): void;
+
+export declare function exportToPdf<R extends GridValidRowModel = GridRowModel>(rows: R[], columns: GridColDef<R>[], options?: PdfExportOptions<R>): Promise<void>;
+
+export declare function exportToPdf<R extends GridValidRowModel = GridRowModel>(rows: R[], columns: GridColDef[], options?: PdfExportOptions<R>): Promise<void>;
 
 export declare const FilterPanel: default_2.FC<FilterPanelProps>;
 
-declare interface FilterPanelProps {
+export declare interface FilterPanelProps {
     filterModel: GridFilterModel;
     columns: GridColDef[];
     onFilterModelChange: (model: GridFilterModel) => void;
 }
 
+/** Default display string for an aggregate: `—` when missing, locale-grouped numbers, avg to 2 decimals. */
 export declare function formatAggregationValue(value: unknown, fnName: string): string;
 
 export declare interface GridAggregationModel {
     [field: string]: string;
 }
 
+/**
+ * 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 declare type GridAggregationPosition = 'inline' | 'footer' | null;
+
 export declare type GridAggregationResult = Record<string, unknown>;
 
 export declare type GridAlignment = 'left' | 'center' | 'right';
@@ -440,18 +603,22 @@ export declare type GridAlignment = 'left' | 'center' | 'right';
  * The Imperative API for interacting with the DataGrid.
  * Access this via the `apiRef` prop or a ref passed to the component.
  */
-export declare 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 declare 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
@@ -505,14 +672,16 @@ export declare interface GridApi {
         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>;
 }
 
-export declare interface GridCellParams<R extends GridRowModel = GridRowModel> {
+export declare interface GridCellParams<R extends GridValidRowModel = GridRowModel> {
     row: R;
     field: string;
     value: unknown;
@@ -525,7 +694,7 @@ export declare interface GridCellParams<R extends GridRowModel = GridRowModel> {
  * Metadata for a single column.
  * Governs rendering, sorting, filtering, and data transformation.
  */
-export declare interface GridColDef<R extends GridRowModel = GridRowModel> {
+export declare 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. */
@@ -579,25 +748,41 @@ export declare interface GridColDef<R extends GridRowModel = GridRowModel> {
         label: string;
     }>;
     /** 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). */
     zIndex?: number;
     /** 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.
      * Can be a static string or a function that receives the cell params and returns a string.
@@ -606,7 +791,7 @@ export declare 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.
      * @example
@@ -621,6 +806,15 @@ export declare interface GridColDef<R extends GridRowModel = GridRowModel> {
     exportable?: boolean;
 }
 
+/**
+ * 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.
+ */
+declare type GridColDefCallback<P, T> = {
+    bivarianceHack(params: P): T;
+}['bivarianceHack'];
+
 /**
  * Describes one level of column grouping.
  * Groups can be nested by placing child GridColumnGroup objects in `children`.
@@ -639,7 +833,7 @@ export declare 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)
@@ -650,7 +844,7 @@ export declare interface GridColumnGroup {
 
 export declare type GridColumnGroupingModel = GridColumnGroup[];
 
-declare type GridColumnOrder = string[];
+export declare type GridColumnOrder = string[];
 
 export declare interface GridColumnOrderChangeParams {
     column: GridColDef;
@@ -679,7 +873,7 @@ export declare type GridColumnVisibilityModel = Record<string, boolean>;
  * Interface for providing data to the grid from a remote source.
  * Enables server-side sorting, filtering, and pagination.
  */
-export declare interface GridDataSource<R extends GridRowModel = GridRowModel> {
+export declare interface GridDataSource<R extends GridValidRowModel = GridRowModel> {
     /**
      * Fetches a chunk of rows based on current grid state.
      * @param params Sorting, filtering, and range parameters.
@@ -691,7 +885,7 @@ export declare interface GridDataSource<R extends GridRowModel = GridRowModel> {
     getAggregations?: (params: Omit<GridGetRowsParams, 'startRow' | 'endRow'>) => Promise<Record<string, unknown>>;
 }
 
-declare interface GridDataSourceState {
+export declare interface GridDataSourceState {
     loading: boolean;
     error?: unknown;
 }
@@ -700,9 +894,9 @@ export declare interface GridDensityState {
     density: 'compact' | 'standard' | 'comfortable';
 }
 
-declare type GridDetailPanelHeight = number | 'auto';
+export declare type GridDetailPanelHeight = number | 'auto';
 
-export declare interface GridDetailPanelParams<R extends GridRowModel = GridRowModel> {
+export declare interface GridDetailPanelParams<R extends GridValidRowModel = GridRowModel> {
     row: R;
     id: GridRowId;
     rowIndex: number;
@@ -740,12 +934,34 @@ export declare interface GridFilterModel {
     quickFilterValues?: string[];
 }
 
-export declare type GridFilterOperator = 'contains' | 'equals' | 'startsWith' | 'endsWith' | 'isEmpty' | 'isNotEmpty' | 'isAnyOf' | '>' | '>=' | '<' | '<=' | '!=' | 'is' | 'not';
+export declare type GridFilterOperator = 'contains' | 'equals' | 'startsWith' | 'endsWith' | 'isEmpty' | 'isNotEmpty' | 'isAnyOf' | '=' | '>' | '>=' | '<' | '<=' | '!=' | 'is' | 'not' | 'after' | 'onOrAfter' | 'before' | 'onOrBefore';
 
 export declare interface GridFilterState {
     filterModel: GridFilterModel;
 }
 
+/**
+ * Props the grid passes to `slots.footer`, before `slotProps.footer` is merged over them.
+ * @since v3.0
+ */
+export declare 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 declare interface GridGetRowsParams {
     startRow: number;
     endRow: number;
@@ -755,7 +971,7 @@ export declare interface GridGetRowsParams {
     aggregationModel?: GridAggregationModel;
 }
 
-export declare interface GridGetRowsResponse<R extends GridRowModel = GridRowModel> {
+export declare interface GridGetRowsResponse<R extends GridValidRowModel = GridRowModel> {
     rows: R[];
     rowCount?: number;
     aggregationResults?: Record<string, unknown>;
@@ -765,7 +981,7 @@ export declare interface GridGetRowsResponse<R extends GridRowModel = GridRowMod
  * A single entry in the ordered list returned by `GridApi.getGroupedExportRows()`.
  * Traverse in array order to reproduce the on-screen grouping structure.
  */
-declare interface GridGroupedExportRow {
+export declare interface GridGroupedExportRow {
     /** Discriminator: the kind of row this entry represents. */
     type: 'group-header' | 'leaf' | 'group-subtotal' | 'grand-total';
     /** Nesting depth (0 = top-level group, 1 = nested group, etc.). */
@@ -774,18 +990,31 @@ declare 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'`). */
     row?: GridRowModel;
 }
 
-export declare type GridInitialState = GridState;
+/**
+ * The state the grid starts from. Every part is optional, including each column field, so a
+ * partial state such as `{ columns: { columnVisibilityModel: { age: false } } }` is valid.
+ */
+export declare interface GridInitialState extends Omit<GridState, 'columns'> {
+    columns?: Partial<GridColumnsState>;
+}
 
 /** Column definition used exclusively in List View mode. */
-export declare interface GridListViewColDef<R extends GridRowModel = GridRowModel> {
+export declare interface GridListViewColDef<R extends GridValidRowModel = GridRowModel> {
     field: string;
-    renderCell: (params: GridRenderCellParams<R>) => React.ReactNode;
+    renderCell(params: GridRenderCellParams<R>): React.ReactNode;
 }
 
 /** Overrideable user-visible strings for internationalisation. All fields are optional; defaults match the built-in English strings. */
@@ -800,11 +1029,24 @@ export declare interface GridLocaleText {
     noRowsLabel?: string;
 }
 
+/**
+ * Props of `slots.noRowsOverlay` and `slots.loadingOverlay`: the grid passes none of its own, only
+ * `slotProps.noRowsOverlay` / `slotProps.loadingOverlay`.
+ * @since v3.0
+ */
+export declare type GridOverlaySlotProps = Record<string, unknown>;
+
 export declare interface GridPaginationModel {
     page: number;
     pageSize: number;
 }
 
+/**
+ * Props the grid passes to `slots.pagination`, before `slotProps.pagination` is merged over them.
+ * @since v3.0
+ */
+export declare type GridPaginationSlotProps = PaginationProps;
+
 export declare interface GridPaginationState {
     paginationModel: GridPaginationModel;
     rowCount?: number;
@@ -827,7 +1069,7 @@ export declare interface GridPivotValueField {
 }
 
 /** Parameters passed to the `renderCell` function. */
-export declare interface GridRenderCellParams<R extends GridRowModel = GridRowModel> {
+export declare interface GridRenderCellParams<R extends GridValidRowModel = GridRowModel> {
     /** The current cell value. */
     value: unknown;
     /**
@@ -852,6 +1094,19 @@ export declare interface GridRenderCellParams<R extends GridRowModel = GridRowMo
     rowMeta?: GridRowMeta;
 }
 
+/**
+ * Parameters passed to `renderEditCell`. `value` is the pending (uncommitted) value.
+ * @since v3.0
+ */
+export declare 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 declare interface GridRenderHeaderParams {
     field: string;
     colDef: GridColDef;
@@ -864,24 +1119,39 @@ export declare type GridRowGroupingModel = string[];
 export declare type GridRowId = string | number;
 
 /**
- * Internal hierarchy metadata for a row. Exposed via `params.rowMeta` in `renderCell`.
+ * 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 declare 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;
 }
 
 /** Base interface for a grid row data object. */
@@ -896,13 +1166,13 @@ export declare interface GridRowModel {
     [key: string]: unknown;
 }
 
-export declare interface GridRowOrderChangeParams<R extends GridRowModel = GridRowModel> {
+export declare interface GridRowOrderChangeParams<R extends GridValidRowModel = GridRowModel> {
     row: R;
     oldIndex: number;
     targetIndex: number;
 }
 
-export declare interface GridRowParams<R extends GridRowModel = GridRowModel> {
+export declare interface GridRowParams<R extends GridValidRowModel = GridRowModel> {
     row: R;
     id: GridRowId;
     rowIndex: number;
@@ -916,7 +1186,7 @@ export declare interface GridRowPinning {
     bottom?: GridRowId[];
 }
 
-declare interface GridRowScrollEndParams {
+export declare interface GridRowScrollEndParams {
     visibleTop: number;
     visibleBottom: number;
     viewportHeight: number;
@@ -924,6 +1194,12 @@ declare interface GridRowScrollEndParams {
 
 export declare type GridRowSelectionModel = GridRowId[];
 
+/** The `slotProps` prop of `DataGrid`: props for each slot, keyed like `GridSlots`. */
+export declare type GridSlotProps = NonNullable<DataGridProps['slotProps']>;
+
+/** The `slots` prop of `DataGrid`: components that replace built-in parts of the grid. */
+export declare type GridSlots = NonNullable<DataGridProps['slots']>;
+
 export declare type GridSortDirection = 'asc' | 'desc' | null;
 
 export declare interface GridSortingState {
@@ -950,6 +1226,12 @@ export declare interface GridState {
 }
 
 export declare interface GridTheme {
+    /**
+     * The complete base palette the theme starts from (default `'light'`). The provider pins every
+     * colour token, so the grid follows the theme whatever the operating-system colour scheme is.
+     * Use `'dark'` for a dark theme; the other keys override single tokens on top of it.
+     */
+    mode?: 'light' | 'dark';
     colors?: GridThemeColors;
     typography?: GridThemeTypography;
     spacing?: GridThemeSpacing;
@@ -987,13 +1269,46 @@ export declare interface GridThemeColors {
     warning?: string;
     error?: string;
     info?: string;
+    /** Page-level surface colour (`--ogx-color-white`): inputs, buttons, checkbox fallbacks. */
+    white?: string;
+    /** Strongest text colour (`--ogx-color-black`). */
+    black?: string;
+    /**
+     * The neutral scale (`--ogx-color-gray-50` … `--ogx-color-gray-900`) used by group rows, detail
+     * panels, inputs, buttons and panels. The theme's `mode` supplies a complete scale; override
+     * single steps here.
+     */
+    gray?: GridThemeGrayScale;
 }
 
+/** Steps of the neutral scale; 50 is the lightest surface in light mode, the darkest in dark mode. */
+export declare interface GridThemeGrayScale {
+    50?: string;
+    100?: string;
+    200?: string;
+    300?: string;
+    400?: string;
+    500?: string;
+    600?: string;
+    700?: string;
+    800?: string;
+    900?: string;
+}
+
+/**
+ * Row and header heights are read by the grid itself (they drive virtualization), so they must be
+ * pixel values such as `'36px'` or `'36'`. The `rowHeight` / `headerHeight` props win over them;
+ * `rowHeightCompact` / `rowHeightComfortable` apply with `density="compact"` / `"comfortable"`.
+ */
 export declare interface GridThemeGrid {
     rowHeightCompact?: string;
     rowHeightStandard?: string;
     rowHeightComfortable?: string;
     headerHeight?: string;
+    /** Font size of body cells (`--ogx-grid-cell-font-size`, default 13px). */
+    cellFontSize?: string;
+    /** Font size of header cells (`--ogx-grid-header-font-size`, default 13px). */
+    headerFontSize?: string;
     cellPaddingX?: string;
     cellPaddingY?: string;
     background?: string;
@@ -1014,7 +1329,7 @@ export declare interface GridThemeGrid {
     checkboxBorder?: string;
 }
 
-declare interface GridThemeOverlays {
+export declare interface GridThemeOverlays {
     background?: string;
     text?: string;
     border?: string;
@@ -1027,7 +1342,7 @@ declare interface GridThemeOverlays {
     itemDangerText?: string;
 }
 
-declare interface GridThemeScrollbar {
+export declare interface GridThemeScrollbar {
     thumbColor?: string;
     trackColor?: string;
     size?: string;
@@ -1040,11 +1355,9 @@ export declare interface GridThemeShadows {
     xl?: string;
 }
 
-declare interface GridThemeSkeleton {
+export declare interface GridThemeSkeleton {
     baseColor?: string;
     highlightColor?: string;
-    darkBaseColor?: string;
-    darkHighlightColor?: string;
 }
 
 export declare interface GridThemeSpacing {
@@ -1056,7 +1369,7 @@ export declare interface GridThemeSpacing {
     xxl?: string;
 }
 
-declare interface GridThemeToolbar {
+export declare interface GridThemeToolbar {
     background?: string;
     text?: string;
     border?: string;
@@ -1152,11 +1465,20 @@ export declare interface GridToolbarProps {
     showNonHideableColumns?: boolean;
 }
 
+/**
+ * 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 declare interface GridToolbarSlotProps extends GridToolbarProps {
+    apiRef: React.MutableRefObject<GridApi>;
+}
+
 export declare function GridTooltip({ title, children, placement, enterDelay, leaveDelay }: GridTooltipProps): JSX.Element;
 
-declare interface GridTooltipProps {
-    title: React.ReactNode;
-    children: React.ReactElement;
+export declare interface GridTooltipProps {
+    title: default_2.ReactNode;
+    children: default_2.ReactElement;
     placement?: 'top' | 'bottom' | 'left' | 'right';
     enterDelay?: number;
     leaveDelay?: number;
@@ -1186,14 +1508,23 @@ export declare interface GridTreeNode {
     children?: GridRowId[];
     /** 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). */
     serverChildrenCount?: number;
 }
 
+/**
+ * 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 declare type GridValidRowModel = object;
+
 /** Parameters passed to the `valueFormatter` function. */
-export declare interface GridValueFormatterParams<R extends GridRowModel = GridRowModel> {
+export declare interface GridValueFormatterParams<R extends GridValidRowModel = GridRowModel> {
     /** The raw value to format. */
     value: unknown;
     /** The row object. */
@@ -1203,7 +1534,7 @@ export declare interface GridValueFormatterParams<R extends GridRowModel = GridR
 }
 
 /** Parameters passed to the `valueGetter` function. */
-export declare interface GridValueGetterParams<R extends GridRowModel = GridRowModel> {
+export declare interface GridValueGetterParams<R extends GridValidRowModel = GridRowModel> {
     /** The row object. */
     row: R;
     /** The field name. */
@@ -1212,10 +1543,27 @@ export declare interface GridValueGetterParams<R extends GridRowModel = GridRowM
     value: unknown;
 }
 
+/**
+ * Parameters passed to the `valueSetter` function.
+ * @since v3.0
+ */
+export declare 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;
+}
+
 export declare function Header<R extends GridRowModel = GridRowModel>(props: HeaderProps<R>): JSX.Element;
 
-declare interface HeaderProps<R extends GridRowModel = GridRowModel> {
+export declare interface HeaderProps<R extends GridRowModel = GridRowModel> {
     columns: GridColDef<R>[];
+    /**
+     * Every rendered data column in render order (left-pinned, unpinned, right-pinned) with its
+     * resolved width. Column group header rows are laid out over these; defaults to `columns`.
+     */
     allColumns?: GridColDef<R>[];
     columnGroupingModel?: GridColumnGroupingModel;
     checkboxSelection?: boolean;
@@ -1241,8 +1589,9 @@ declare interface HeaderProps<R extends GridRowModel = GridRowModel> {
     onDragOver?: (field: string) => (event: default_2.DragEvent) => void;
     onDragEnd?: () => void;
     onDrop?: (targetField: string) => (event: default_2.DragEvent) => void;
+    /** The grid's focus position; `id: null` means a header cell is focused. */
     focusedCell?: {
-        id: string | number;
+        id: string | number | null;
         field: string;
     } | null;
     onHeaderClick?: (field: string) => void;
@@ -1251,32 +1600,57 @@ declare interface HeaderProps<R extends GridRowModel = GridRowModel> {
     onHideColumn?: (field: string) => void;
     onPinColumn?: (field: string, side: 'left' | 'right' | null) => void;
     onManageColumns?: () => void;
+    /** Position of each visible data column in render order, for `colIndex` and `aria-colindex`. */
+    columnIndexMap?: Map<string, number>;
 }
 
 export declare const Input: default_2.FC<InputProps>;
 
-declare interface InputProps extends default_2.InputHTMLAttributes<HTMLInputElement> {
+export declare interface InputProps extends default_2.InputHTMLAttributes<HTMLInputElement> {
     fullWidth?: boolean;
     error?: boolean;
     startAdornment?: default_2.ReactNode;
     endAdornment?: default_2.ReactNode;
 }
 
-export declare interface JsonExportOptions {
+export declare interface JsonExportOptions<R extends GridValidRowModel = GridRowModel> {
     fileName?: string;
     pretty?: boolean;
+    /**
+     * Export only these row IDs. A non-empty selection takes precedence over `groupedRows` (the
+     * selected rows are exported flat), and the aggregation values are recomputed over them.
+     */
     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;
     aggregationResult?: Record<string, unknown> | null;
     aggregationModel?: GridAggregationModel | null;
     /** When provided, emits a nested grouping tree instead of a flat array. */
     groupedRows?: GridGroupedExportRow[];
 }
 
+export declare function Pagination(props: PaginationProps): JSX.Element;
+
+export declare interface PaginationProps {
+    page: number;
+    pageSize: number;
+    rowCount: number;
+    onPageChange: (page: number) => void;
+    onPageSizeChange: (pageSize: number) => void;
+    pageSizeOptions?: number[];
+    showFirstButton?: boolean;
+    showLastButton?: boolean;
+    localeText?: Pick<GridLocaleText, 'paginationRowsPerPage' | 'paginationOf' | 'paginationPage'>;
+}
+
 /**
  * Configuration options for exporting the DataGrid to PDF format.
  * Requires jspdf and jspdf-autotable peer dependencies.
  */
-export declare interface PdfExportOptions {
+export declare interface PdfExportOptions<R extends GridValidRowModel = GridRowModel> {
     /**
      * Output filename without extension. Default: 'export'
      */
@@ -1296,9 +1670,16 @@ export declare 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.
@@ -1328,23 +1709,63 @@ export declare interface PdfExportOptions {
      * Base font size in points for table body. Default: 9
      */
     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[];
 }
 
+declare interface PivotResult {
+    /** Pivot data rows followed by the Grand Total row (omitted when there are no data rows). */
+    pivotRows: GridRowModel[];
+    /** Row-label columns (one per row field) followed by one value column per column key and value field. */
+    pivotColumns: GridColDef[];
+    /** The distinct column-field value combinations, in display order. */
+    colKeys: string[];
+    /** `false` when the model has no usable row field or value field. */
+    isValid: boolean;
+}
+
 /**
  * Open print dialog with formatted table
  */
-export declare function printGrid<R extends GridRowModel>(rows: R[], columns: GridColDef<R>[], titleOrOptions?: string | PrintOptions): Promise<void>;
+export declare function printGrid<R extends GridValidRowModel = GridRowModel>(rows: R[], columns: GridColDef<R>[], titleOrOptions?: string | PrintOptions<R>): Promise<void>;
+
+export declare function printGrid<R extends GridValidRowModel = GridRowModel>(rows: R[], columns: GridColDef[], titleOrOptions?: string | PrintOptions<R>): Promise<void>;
 
-export declare interface PrintOptions {
+export declare interface PrintOptions<R extends GridValidRowModel = GridRowModel> {
     title?: string;
+    /**
+     * Print only these row IDs. A non-empty selection takes precedence over `groupedRows` (the
+     * selected rows are printed flat), and the 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;
     aggregationResult?: Record<string, unknown> | null;
     aggregationModel?: GridAggregationModel | null;
     /** When provided, emits group headers, leaf rows, subtotals, and a grand total instead of a flat row list. */
@@ -1355,8 +1776,10 @@ export declare const roseTheme: GridTheme;
 
 export declare function Row<R extends GridRowModel = GridRowModel>(props: RowProps<R>): JSX.Element;
 
-declare interface RowProps<R extends GridRowModel = GridRowModel> {
+export declare interface RowProps<R extends GridRowModel = GridRowModel> {
     row: R;
+    /** The row's id (from getRowId). Defaults to `row.id`; the grid always passes it. */
+    rowId?: GridRowId;
     columns: GridColDef<R>[];
     rowIndex: number;
     isSelected?: boolean;
@@ -1373,6 +1796,8 @@ declare interface RowProps<R extends GridRowModel = GridRowModel> {
     onDetailPanelToggle?: (rowId: GridRowId) => void;
     detailPanelContent?: default_2.ReactNode;
     detailPanelHeight?: GridDetailPanelHeight;
+    /** Called with the rendered height of an `'auto'` detail panel whenever it changes. */
+    onDetailPanelHeightChange?: (rowId: GridRowId, height: number) => void;
     pinCheckboxColumn?: boolean;
     pinExpandColumn?: boolean;
     rowReordering?: boolean;
@@ -1392,31 +1817,43 @@ declare interface RowProps<R extends GridRowModel = GridRowModel> {
         field: string;
         value: unknown;
     }) => void;
+    /** `id` / `field` name the cell whose editor asked to stop. */
     onEditStop?: (params?: {
         cancel?: boolean;
+        id?: GridRowId;
+        field?: string;
     }) => void;
     onEditCellValueChange?: (params: {
         id: GridRowId;
         field: string;
         value: unknown;
     }) => void;
+    /** Per-cell editability predicate (`DataGrid.isCellEditable`). */
+    isCellEditable?: (params: GridCellParams<R>) => boolean;
     focusedCellField?: string | null;
     isFocusVisible?: boolean;
     colspanMap?: Map<GridRowId, Record<string, CellColSpanInfo>>;
     rowSpanningCaches?: RowSpanningCaches;
     rowHeight?: number;
     rowMeta?: GridRowMeta;
+    /** Position of each visible data column in render order, for `colIndex` and `aria-colindex`. */
+    columnIndexMap?: Map<string, number>;
+    /** 1-based `aria-rowindex` of this row in the whole grid (header rows included). Defaults to `rowIndex + 2`. */
+    ariaRowIndex?: number;
 }
 
 declare interface RowSpanningCaches {
+    /** Row id → field → number of rows the origin cell spans (only entries > 1). */
     spannedCells: Record<GridRowId, Record<ColumnKey, number>>;
+    /** Row id → field → `true` for cells covered by a row span that starts in a row above. */
     hiddenCells: Record<GridRowId, Record<ColumnKey, boolean>>;
-    hiddenCellOriginMap: Record<number, Record<ColumnKey, number>>;
+    /** Row id → field → id of the row whose span covers the hidden cell. */
+    hiddenCellOriginMap: Record<GridRowId, Record<ColumnKey, GridRowId>>;
 }
 
 export declare function Skeleton({ rows, columns }: SkeletonProps): JSX.Element;
 
-declare interface SkeletonProps {
+export declare interface SkeletonProps {
     rows?: number;
     columns?: number;
 }
@@ -1439,11 +1876,15 @@ export declare interface ToolbarQuickFilterRenderProps {
     onChange: (value: string) => void;
 }
 
-export declare function useAggregation<R extends GridRowModel>(params: UseAggregationParams<R>): UseAggregationReturn;
+export declare function useAggregation<R extends GridValidRowModel = GridRowModel>(params: UseAggregationParams<R>): UseAggregationReturn;
 
-export declare interface UseAggregationParams<R extends GridRowModel> {
-    rows: R[];
+export declare function useAggregation<R extends GridValidRowModel = GridRowModel>(params: Omit<UseAggregationParams<R>, 'columns'> & {
     columns?: GridColDef[];
+}): UseAggregationReturn;
+
+export declare interface UseAggregationParams<R extends GridValidRowModel = GridRowModel> {
+    rows: R[];
+    columns?: GridColDef<R>[];
     aggregationModel: GridAggregationModel;
     isServerSide: boolean;
     dataSource?: GridDataSource<R>;
@@ -1461,12 +1902,28 @@ export declare interface UseAggregationReturn {
 /**
  * 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 declare function useGridApiRef(): RefObject<GridApi>;
+export declare function useGridApiRef<R extends GridValidRowModel = GridRowModel>(): MutableRefObject<GridApi<R>>;
 
 export declare function useGridStateStorage(options: UseGridStateStorageOptions | string): UseGridStateStorageReturn;
 
 export declare interface UseGridStateStorageOptions {
+    /**
+     * Storage key. The grid reads `initialState` only when it mounts, so when the key can
+     * change (per user, per view) remount the grid with it: `<DataGrid key={key} … />`.
+     */
     key: string;
     debounceMs?: number;
     include?: (keyof GridState)[];
@@ -1483,13 +1940,15 @@ export declare interface UseGridStateStorageReturn {
     clearState: () => void;
 }
 
-export declare function usePivot(rawRows: GridRowModel[], rawCols: GridColDef[], model: GridPivotModel, enabled: boolean): UsePivotReturn;
+/**
+ * Headless pivot: turns flat rows into pivot rows (one per row-field combination, then a Grand Total
+ * row) and generated columns (row-label columns, then one value column per column key and value field).
+ * `DataGrid`'s `pivotMode` uses the same engine.
+ */
+export declare function usePivot<R extends GridValidRowModel = GridRowModel>(rawRows: R[], rawCols: GridColDef<R>[], model: GridPivotModel, enabled: boolean): UsePivotReturn;
 
-export declare interface UsePivotReturn {
-    pivotRows: GridRowModel[];
-    pivotColumns: GridColDef[];
-    colKeys: string[];
-    isValid: boolean;
-}
+export declare function usePivot<R extends GridValidRowModel = GridRowModel>(rawRows: R[], rawCols: GridColDef[], model: GridPivotModel, enabled: boolean): UsePivotReturn;
+
+export declare type UsePivotReturn = PivotResult;
 
 export { }