@opencorestack/opengridx 2.1.0 → 3.0.1

package/docs/features/cell-spanning.md

@@ -10,70 +10,42 @@ Cell spanning allows cells in the DataGrid to span across multiple columns (colu
 - **Row Spanning**: Cells can span vertically across multiple rows
 - **Dynamic Spanning**: Span values can be calculated dynamically based on cell data
 - **Static Spanning**: Span values can be set as fixed numbers
-- **Accessibility**: Automatic ARIA attributes (`aria-colspan`, `aria-rowspan`)
-- **CSS Grid Integration**: Uses CSS Grid for proper layout
+- **Accessibility**: Automatic ARIA attributes (`aria-colspan`, `aria-rowspan`) and keyboard navigation that treats a merged area as one cell
+- **Virtualization-aware**: A span stays rendered while any part of it is in view, horizontally and vertically
+- **Zero cost when unused**: Nothing is computed unless a column declares `colSpan` or `rowSpan`
 
 ---
 
-## ⚠️ Important: Feature Conflicts
+## How spans interact with other features
 
-When using `colSpan` or `rowSpan`, some other DataGrid features may not work as expected or may create a confusing grid layout. **To avoid layout issues and unexpected behavior, consider disabling the following features for any columns that use cell spanning:**
+Spans are computed from the grid **as it is rendered**, so they follow the current column order, visibility, pinning, sorting, filtering and page:
 
-### Features to Disable
+| Feature | Behaviour |
+| :--- | :--- |
+| **Column visibility** | Hidden columns are skipped. `colSpan: 2` merges the origin with the next *visible* column, and the merged width and `aria-colspan` count visible columns only. |
+| **Column order / reordering** | A span covers the columns that follow the origin in the current (rendered) order. |
+| **Column pinning** | A span never crosses a pinned-section boundary: it is clamped to the end of the left-pinned, unpinned or right-pinned section its origin is in. |
+| **Row pinning** | Spans are computed separately for the top-pinned rows, the scrolling rows and the bottom-pinned rows, and never reach from one into another. |
+| **Sorting / filtering / pagination** | Spans are recomputed against the new row order, the filtered rows and the current page. `rowIndex` in the callback is the row's position in the rendered rows (top-pinned rows first). |
+| **Master-detail** | A row span ends at a row whose detail panel is expanded, so the merged cell never covers the panel. |
+| **Virtualization** | The render window is widened so a span is never cut: the row whose cell starts a visible row span, and the column that starts a visible column span, are always rendered. |
+| **Column resizing, flex and percentage widths** | A merged cell is exactly as wide as the columns it covers, using their resolved widths. The origin column's own `minWidth` / `maxWidth` do not apply to the merged cell. Resizing never recomputes the spans. |
+| **Keyboard navigation** | Arrow keys move over a merged area in one step and land on its origin cell; covered cells are never focused. While editing, Tab skips covered cells (outside edit mode Tab leaves the grid). |
+| **Infinite scrolling** | The loading placeholder rows are never passed to `colSpan` / `rowSpan`. |
+| **Row grouping, tree data, pivot** | Rows the grid made (group headers, subtotals, auto-created tree parents, the pivot Grand Total) are never a span origin, and a `rowSpan` ends before the next such row, so a span never merges data across a group boundary (v3.0+). |
 
-1. **Sorting** (`sortable: false`)
-   - When rows are reordered by sorting, spanned cells may break visual continuity
-   - Subtotal/summary rows with spanning should remain in fixed positions
+Spans on columns whose values change with sorting still work, but the merged areas move with the rows. For summary rows that must stay in place, disable sorting on the spanning column (`sortable: false`) or use [Row Pinning](./pinning.md).
 
-2. **Filtering** (when implemented)
-   - Hidden rows can cause spanned cells to appear disconnected or incomplete
-   - Filtering may hide parts of a spanned cell group
+### Span values
 
-3. **Column Reordering** (`disableReorder: true`)
-   - Moving columns can break the spanning logic
-   - Spanned cells depend on specific column order
+The value returned (or set) for `colSpan` / `rowSpan` is normalised before it is used:
 
-4. **Column Hiding** (`hideable: false`)
-   - Hiding columns within a span creates layout gaps and visual artifacts
-   - The grid cannot properly render partial spans
+- Values larger than what is left are clamped: `colSpan` to the end of the origin's pinned section, `rowSpan` to the end of the row section (or to the first row with an expanded detail panel). `aria-colspan` / `aria-rowspan` show the clamped value.
+- Fractions are rounded down (`1.7` → `1`).
+- `Infinity` means "to the end" and is clamped like any other large value.
+- `NaN`, `0`, negative numbers and non-numbers mean no span (`1`).
 
-5. **Column Pinning** (avoid pinning spanned columns)
-   - Pinned columns with spanning can cause rendering conflicts
-   - Spanning across pinned and non-pinned columns is not supported
-
-### Recommended Configuration
-
-```tsx
-const columns: GridColDef<Row>[] = [
-    {
-        field: 'summary',
-        headerName: 'Summary',
-        width: 200,
-        colSpan: (params) => params.row.isTotal ? 3 : 1,
-        // Disable conflicting features
-        sortable: false,        // ✅ Disable sorting
-        hideable: false,        // ✅ Disable column hiding
-        // Column reorder is disabled grid-wide via disableColumnReorder on <DataGrid>
-        // Note: Avoid pinning this column
-        renderCell: (params) => {
-            if (params.row.isTotal) {
-                return <strong>Total: {params.value}</strong>;
-            }
-            return params.value;
-        }
-    },
-    // Other columns...
-];
-```
-
-### Why These Limitations Exist
-
-Cell spanning fundamentally changes the grid's layout model:
-- **Sorting/Filtering** change row order/visibility, breaking span relationships
-- **Column operations** (reorder/hide/pin) modify the column structure that spans depend on
-- **CSS Grid** requires stable column positions for proper spanning
-
-**Best Practice**: Use cell spanning primarily for static summary rows, headers, or fixed layout sections where these features are not needed.
+A `colSpan` or `rowSpan` function (or the `valueGetter` whose value it receives) that **throws** is treated as `1` for that cell, and a warning is logged in development. The rest of the grid keeps rendering.
 
 ---
 
@@ -127,7 +99,7 @@ const columns: GridColDef<Row>[] = [
             if (params.row.isTotal) {
                 return <strong>Total: {params.row.name}</strong>;
             }
-            return params.value;
+            return params.formattedValue;
         }
     },
     {
@@ -145,7 +117,13 @@ const columns: GridColDef<Row>[] = [
 ### Basic Usage
 
 ```tsx
-const columns: GridColDef<Row>[] = [
+interface ItemRow {
+    id: number;
+    category: string;
+    item: string;
+}
+
+const columns: GridColDef<ItemRow>[] = [
     {
         field: 'category',
         headerName: 'Category',
@@ -164,18 +142,18 @@ const columns: GridColDef<Row>[] = [
 ### Dynamic Row Spanning
 
 ```tsx
-const columns: GridColDef<Row>[] = [
+// `rows: ItemRow[]` is the array passed to the grid, sorted by category.
+const columns: GridColDef<ItemRow>[] = [
     {
         field: 'category',
         headerName: 'Category',
         width: 150,
         // Dynamic row span based on data
         rowSpan: (params) => {
-            // Calculate how many rows this category spans
-            const categoryRows = rows.filter(
-                r => r.category === params.row.category
-            );
-            return categoryRows.length;
+            // Start a span at the first row of each category; the rest are covered by it
+            const index = rows.findIndex(r => r.category === params.row.category);
+            if (rows[index].id !== params.row.id) return 1;
+            return rows.filter(r => r.category === params.row.category).length;
         }
     },
     {
@@ -190,10 +168,20 @@ const columns: GridColDef<Row>[] = [
 
 ## Combined Column and Row Spanning
 
-You can use both `colSpan` and `rowSpan` together:
+You can use both `colSpan` and `rowSpan` together. The origin cell then covers the whole rectangle: with `colSpan: 3` and `rowSpan: 2`, the three cells in the next row are covered too.
+
+- A cell covered by another cell's `colSpan` is not evaluated as a `rowSpan` origin in that row.
+- A cell covered by a `rowSpan` from above is not evaluated as a `colSpan` origin.
+- A `colSpan` stops before a cell that a `rowSpan` from a row above already covers.
 
 ```tsx
-const columns: GridColDef<Row>[] = [
+interface SectionRow {
+    id: number;
+    header: string;
+    isHeader?: boolean;
+}
+
+const columns: GridColDef<SectionRow>[] = [
     {
         field: 'header',
         headerName: 'Header',
@@ -209,11 +197,11 @@ const columns: GridColDef<Row>[] = [
                         textAlign: 'center',
                         padding: '20px'
                     }}>
-                        {params.value}
+                        {params.formattedValue}
                     </div>
                 );
             }
-            return params.value;
+            return params.formattedValue;
         }
     }
 ];
@@ -292,7 +280,7 @@ export default function SalesReport() {
                 if (params.row.isSubtotal) {
                     return <em>{params.row.region} Subtotal</em>;
                 }
-                return params.value;
+                return params.formattedValue;
             }
         },
         {
@@ -305,35 +293,35 @@ export default function SalesReport() {
             headerName: 'Q1',
             width: 120,
             type: 'number',
-            valueFormatter: ({ value }) => `$${value.toLocaleString()}`
+            valueFormatter: ({ value }) => `$${(value as number).toLocaleString()}`
         },
         {
             field: 'q2',
             headerName: 'Q2',
             width: 120,
             type: 'number',
-            valueFormatter: ({ value }) => `$${value.toLocaleString()}`
+            valueFormatter: ({ value }) => `$${(value as number).toLocaleString()}`
         },
         {
             field: 'q3',
             headerName: 'Q3',
             width: 120,
             type: 'number',
-            valueFormatter: ({ value }) => `$${value.toLocaleString()}`
+            valueFormatter: ({ value }) => `$${(value as number).toLocaleString()}`
         },
         {
             field: 'q4',
             headerName: 'Q4',
             width: 120,
             type: 'number',
-            valueFormatter: ({ value }) => `$${value.toLocaleString()}`
+            valueFormatter: ({ value }) => `$${(value as number).toLocaleString()}`
         },
         {
             field: 'total',
             headerName: 'Total',
             width: 140,
             type: 'number',
-            valueFormatter: ({ value }) => value ? `$${value.toLocaleString()}` : ''
+            valueFormatter: ({ value }) => (value == null ? '' : `$${(value as number).toLocaleString()}`)
         }
     ];
 
@@ -387,7 +375,7 @@ Defines how many rows a cell should span.
 rowSpan: 2
 
 // Dynamic spanning
-rowSpan: (params) => params.row.categorySize || 1
+rowSpan: (params) => (params.row.categorySize as number | undefined) ?? 1
 ```
 
 ### GridRenderCellParams
@@ -396,12 +384,14 @@ Parameters passed to the `colSpan` and `rowSpan` functions:
 
 ```tsx
 interface GridRenderCellParams<R> {
-    value: any;           // Cell value
-    row: R;               // Complete row data
-    field: string;        // Column field name
+    value: unknown;        // Cell value: the valueGetter result when the column has one
+    formattedValue?: string; // The valueFormatter result (or String(value)); render this, not `value`
+    row: R;                // Complete row data
+    field: string;         // Column field name
     colDef: GridColDef<R>; // Column definition
-    rowIndex: number;     // Row index
-    colIndex: number;     // Column index
+    rowIndex: number;      // Position among the rendered rows (top-pinned rows, then the current page, then bottom-pinned rows)
+    colIndex: number;      // Position among the rendered data columns (left-pinned first); checkbox, detail-panel and reorder columns are not counted
+    rowMeta?: GridRowMeta; // Hierarchy metadata under tree data / row grouping
 }
 ```
 
@@ -430,11 +420,11 @@ Spanned cells can be styled using custom `renderCell`:
                     fontSize: '1.2em',
                     borderBottom: '2px solid #1976d2'
                 }}>
-                    {params.value}
+                    {params.formattedValue}
                 </div>
             );
         }
-        return params.value;
+        return params.formattedValue;
     }
 }
 ```
@@ -445,10 +435,10 @@ Spanned cells can be styled using custom `renderCell`:
 
 The DataGrid automatically adds ARIA attributes for spanned cells:
 
-- `aria-colspan`: Added when `colSpan > 1`
-- `aria-rowspan`: Added when `rowSpan > 1`
+- `aria-colspan`: Added when the (clamped) `colSpan > 1`
+- `aria-rowspan`: Added when the (clamped) `rowSpan > 1`
 
-This ensures screen readers properly announce the spanning behavior.
+Cells covered by a column span are not rendered. Cells covered by a row span render as empty `role="presentation"` placeholders that keep the column's slot. Keyboard focus always lands on the origin cell of a merged area.
 
 ---
 
@@ -456,43 +446,18 @@ This ensures screen readers properly announce the spanning behavior.
 
 1. **Use Dynamic Spanning**: Prefer dynamic spanning functions over static values for flexibility
 2. **Combine with renderCell**: Always provide custom rendering for spanned cells to improve visual clarity
-3. **Consider Performance**: Spanning calculations run on every render, so keep them lightweight
-4. **Test with Virtualization**: Ensure spanning works correctly with virtual scrolling
+3. **Consider Performance**: Span functions run once per cell of a spanning column whenever the rows or the column structure change (not on scroll or resize), so keep them lightweight
+4. **Keep Row Spans Short**: While a long row span is on screen, every row from its origin down is rendered, so a 1,000-row span renders up to 1,000 rows
 5. **Accessibility**: Provide meaningful content in spanned cells for screen readers
 
 ---
 
 ## Limitations
 
-### Feature Conflicts
-
-**⚠️ See the [Feature Conflicts](#️-important-feature-conflicts) section above for important information about which features should be disabled when using cell spanning.**
-
-### Technical Limitations
-
-1. **Virtualization**: 
-   - Row spanning may have visual artifacts with virtualization if spans cross virtual boundaries
-   - Large row spans (>10 rows) may cause performance issues with virtual scrolling
-   - Consider using row pinning for summary rows instead of row spanning
-
-2. **Pinned Columns**: 
-   - Column spanning with pinned columns requires careful consideration
-   - Spanning across pinned and non-pinned columns is not supported
-   - Use spanning only within pinned or non-pinned column groups
-
-3. **Sorting/Filtering**: 
-   - Spanned cells may break visual continuity when rows are reordered
-   - Always disable sorting on columns with dynamic spanning
-   - Filtering can hide parts of spanned cell groups
-
-4. **Column Operations**:
-   - Column reordering can break spanning logic
-   - Hiding columns within a span creates layout gaps
-   - Column resizing may not work optimally with spanned cells
-
-5. **Editing**:
-   - Cell editing on spanned cells may have unexpected behavior
-   - Consider disabling editing for columns with spanning
+1. **Pinned columns**: A span cannot cover columns in two pinned sections. Put the columns a span should merge in the same section.
+2. **Pinned rows**: A span cannot reach from a pinned row into the scrolling rows (or the other way).
+3. **Long row spans**: The rows between a visible row span's origin and the viewport are rendered, so very long row spans cost DOM nodes. Consider [Row Grouping](./tree-data-grouping.md) for large vertical groups.
+4. **Editing**: Double-click editing on a merged cell edits the origin cell's field.
 
 ### Workarounds
 
@@ -502,19 +467,9 @@ This ensures screen readers properly announce the spanning behavior.
 
 ---
 
-## Browser Support
-
-Cell spanning uses CSS Grid, which is supported in:
-- Chrome 57+
-- Firefox 52+
-- Safari 10.1+
-- Edge 16+
-
----
-
 ## See Also
 
 - [Row Pinning](./pinning.md)
 - [Column Pinning](./pinning.md)
-- [Custom Cell Rendering](./cell.md)
+- [Custom Cell Rendering](../components/cell.md)
 - [Aggregation](./aggregation-pivot.md)

package/docs/features/clipboard.md

@@ -4,9 +4,10 @@ OpenGridX supports copying grid data directly to the clipboard. This feature all
 
 ## 📑 Overview
 - **Zero Configuration**: Enabled by default with the standard `DataGrid`.
-- **Selected Rows**: Only selected rows are copied when selection is active.
-- **TSV Format**: Data is copied in Tab-Separated Values (TSV) format for maximum compatibility.
-- **Value Formatters**: Respects `valueFormatter` for accurate data representation.
+- **Selected Rows**: Every selected row that passes the filter is copied — rows on other pages, rows inside collapsed groups or tree nodes, and pinned rows included — in the order the grid shows them. Rows the filter removes are not copied.
+- **What you see**: Only the visible columns are copied, in screen order (column order, drag reorder and pinning are followed). Columns marked `exportable: false` (action/button columns) are left out, as in every export.
+- **TSV Format**: Data is copied in Tab-Separated Values (TSV) format, quoted the way Excel and Google Sheets read it.
+- **Cell values**: `valueGetter` and then `valueFormatter` are applied, as in the cells.
 
 ---
 
@@ -16,7 +17,17 @@ Selection and copying follow standard spreadsheet metaphors:
 | :--- | :--- |
 | `Ctrl + C` / `Cmd + C` | Copy currently selected rows to the clipboard. |
 
-> **Note**: The copy action is ignored if an input, textarea, or another editable element currently has focus.
+> **Note**: The shortcut only copies while focus is inside the grid (a cell, a header, the toolbar), so with several grids on a page only the one in use copies, and Ctrl+C elsewhere on the page is never taken over (v3.0). It is also ignored while an input, textarea, or another editable element has focus, and while the page has a text selection, which the browser copies as usual. `apiRef.current.copySelectedRows()` is not affected by focus.
+>
+> The shortcut works with Caps Lock on and on non-Latin keyboard layouts (the key in the "C" position). Ctrl+Shift+C and Ctrl+Alt+C are not copy shortcuts and are left alone. Focus stays where it was after the copy.
+
+### Taking over the shortcut
+- Call `event.preventDefault()` in your own `keydown` handler (on the element, `document`, or in the capture phase) and the grid leaves that Ctrl+C alone.
+- Or pass `disableClipboardCopy` to turn the grid's shortcut off entirely. `apiRef.current.copySelectedRows()` still works.
+
+```tsx
+<DataGrid rows={rows} columns={columns} disableClipboardCopy />
+```
 
 ---
 
@@ -34,32 +45,46 @@ If `checkboxSelection` is enabled and rows are selected, pressing `Ctrl + C` wil
 ```
 
 ### Programmatic Copy
-You can trigger a copy action programmatically using the exported hook if building a custom toolbar.
+Call `apiRef.current.copySelectedRows()`, for example from a custom toolbar button. The promise resolves once the text is written (or straight away, writing nothing, when no selected row is found) and **rejects when the browser refuses the write**, so you can tell the user.
 
 ```tsx
-import { useGridClipboard } from '@opencorestack/opengridx';
+import { DataGrid, useGridApiRef } from '@opencorestack/opengridx';
 
-function MyCustomToolbar({ state, columns, getVisibleRows }) {
-  const { copySelectedRows } = useGridClipboard({ state, columns, getVisibleRows });
+function MyGrid({ rows, columns }) {
+  const apiRef = useGridApiRef();
+
+  const copy = async () => {
+    try {
+      await apiRef.current.copySelectedRows();
+      showToast('Copied');
+    } catch {
+      showToast('The browser blocked the clipboard');
+    }
+  };
 
   return (
-    <button onClick={copySelectedRows}>
-      Copy to Clipboard
-    </button>
+    <>
+      <button onClick={copy}>Copy to Clipboard</button>
+      <DataGrid rows={rows} columns={columns} apiRef={apiRef} checkboxSelection />
+    </>
   );
 }
 ```
 
+`copySelectedRows()` reads the latest selection, so it can be called right after `apiRef.current.selectRows(ids)` or from `onRowSelectionModelChange`.
+
 ---
 
 ## ⚙️ How it Works
 
-1. **Header Row**: The first line of the copied content includes the column header names.
+1. **Header Row**: The first line of the copied content includes the column header names (`headerName`, else `field`).
 2. **Data Transformation**: The grid iterates through the selected rows and columns:
-   - **Exclusions**: Special internal columns (checkboxes, expanders, etc.) are excluded.
-   - **Formatting**: If a column has a `valueFormatter`, it is applied to the raw value before copying.
-3. **TSV Generation**: Fields are joined by tabs (`\t`), and rows are joined by newlines (`\n`).
-4. **Clipboard API**: Uses the modern `navigator.clipboard.writeText` API.
+   - **Exclusions**: Hidden columns, grid system columns (checkbox, expand, reorder, the `groupingColDef` column) and `exportable: false` columns are excluded. Synthetic group rows are never copied.
+   - **Values**: `valueGetter` runs first, then `valueFormatter` (also for empty values, as in the cells). Empty values are written as empty cells.
+3. **TSV Generation**: Fields are joined by tabs (`\t`), and rows are joined by newlines (`\n`). A field that holds a tab, a line break or a double quote is wrapped in double quotes, with inner quotes doubled (`say "hi"` → `"say ""hi"""`), so the pasted table keeps its rows and columns.
+4. **Clipboard API**: Uses `navigator.clipboard.writeText`. When it is missing (plain `http:` pages) or rejects, a hidden-textarea `document.execCommand('copy')` fallback runs; focus and the page selection are restored afterwards.
+
+> **Formulas**: copy reproduces what the grid shows and does **not** neutralise formulas. A copied value that starts with `=`, `+`, `-` or `@` may be evaluated as a formula when pasted into Excel, Google Sheets or LibreOffice. The file exports (CSV, Excel, and the others) do neutralise such text by prefixing `'`; use an export when the data comes from untrusted input.
 
 ---
 

package/docs/features/custom-pagination.md

@@ -4,11 +4,22 @@ This guide shows how to use Ant Design (or any other UI library) components with
 
 ## Using Ant Design Select for Page Size
 
+Slots are typed `React.ComponentType<Record<string, unknown>>`, so the component takes `Record<string, unknown>` and narrows it to the props it reads (see [Slots API](../customization/slots-api.md#available-slots)).
+
 ```tsx
-import { Select } from 'antd';
+import { Pagination, Select } from 'antd';
 import { DataGrid } from '@opencorestack/opengridx';
 
-function AntdPaginationComponent(props) {
+type PaginationSlotProps = {
+    page: number;
+    pageSize: number;
+    rowCount: number;
+    pageSizeOptions: number[];
+    onPageChange: (page: number) => void;
+    onPageSizeChange: (pageSize: number) => void;
+};
+
+function AntdPaginationComponent(props: Record<string, unknown>) {
     const {
         page,
         pageSize,
@@ -16,12 +27,15 @@ function AntdPaginationComponent(props) {
         pageSizeOptions,
         onPageChange,
         onPageSizeChange
-    } = props;
+    } = props as PaginationSlotProps;
 
-    const pageCount = Math.max(1, Math.ceil(rowCount / pageSize));
-    const currentPage = Math.min(page, pageCount - 1);
-    const firstRowIndex = currentPage * pageSize;
+    // Client-side, `page` is already clamped to the last page.
+    const firstRowIndex = page * pageSize;
     const lastRowIndex = Math.min(firstRowIndex + pageSize, rowCount);
+    // Show the page size in use even when it is not one of pageSizeOptions, as the built-in pager does.
+    const sizes = pageSizeOptions.includes(pageSize)
+        ? pageSizeOptions
+        : [...pageSizeOptions, pageSize].sort((a, b) => a - b);
 
     return (
         <div style={{
@@ -38,7 +52,7 @@ function AntdPaginationComponent(props) {
                 <Select
                     value={pageSize}
                     onChange={onPageSizeChange}
-                    options={pageSizeOptions.map(size => ({
+                    options={sizes.map(size => ({
                         value: size,
                         label: size
                     }))}
@@ -47,11 +61,11 @@ function AntdPaginationComponent(props) {
             </div>
 
             {/* Row count */}
-            <span>{firstRowIndex + 1}–{lastRowIndex} of {rowCount}</span>
+            <span>{rowCount === 0 ? 0 : firstRowIndex + 1}–{lastRowIndex} of {rowCount}</span>
 
             {/* Ant Design Pagination */}
             <Pagination
-                current={currentPage + 1}
+                current={page + 1}
                 total={rowCount}
                 pageSize={pageSize}
                 onChange={(page) => onPageChange(page - 1)}
@@ -86,15 +100,16 @@ function MyApp() {
 
 ```tsx
 import { Select, MenuItem } from '@mui/material';
+// PaginationSlotProps: the type alias from the example above
 
-function MuiPaginationComponent(props) {
-    const { pageSize, pageSizeOptions, onPageSizeChange } = props;
+function MuiPaginationComponent(props: Record<string, unknown>) {
+    const { pageSize, pageSizeOptions, onPageSizeChange } = props as PaginationSlotProps;
 
     return (
         <div>
             <Select
                 value={pageSize}
-                onChange={(e) => onPageSizeChange(e.target.value)}
+                onChange={(e) => onPageSizeChange(Number(e.target.value))}
             >
                 {pageSizeOptions.map(size => (
                     <MenuItem key={size} value={size}>
@@ -111,18 +126,23 @@ function MuiPaginationComponent(props) {
 
 Your custom pagination component will receive these props:
 
-- `page`: Current page index (0-based)
-- `pageSize`: Current page size
-- `rowCount`: Total number of rows
-- `pageSizeOptions`: Array of available page sizes
+- `page`: Current page index (0-based). With client pagination it is clamped to the last page: when the rows shrink below the current page, the grid shows the last page and reports the corrected page once through `onPaginationModelChange`.
+- `pageSize`: Current page size. It may be a value missing from `pageSizeOptions` (the built-in pager then lists it as an extra option).
+- `rowCount`: Number of rows being paged: the filtered, unpinned rows (pinned rows show on every page), or the server total with `paginationMode="server"`.
+- `pageSizeOptions`: Array of available page sizes (default `[10, 25, 50, 100]`). The default page size is 100, or the first option when 100 is not offered.
 - `onPageChange(newPage: number)`: Callback to change page
-- `onPageSizeChange(newPageSize: number)`: Callback to change page size
+- `onPageSizeChange(newPageSize: number)`: Callback to change page size (also goes back to page 0)
+- `localeText`: `{ paginationRowsPerPage, paginationOf, paginationPage }`, passed only when the grid's `localeText` prop is set. The built-in pager uses `paginationRowsPerPage` as the select's label and accessible name.
 - Any additional props from `slotProps.pagination`
 
+The slot is rendered only while pagination is in effect: `pagination` is set, row grouping is off and `paginationMode` is not `"infinite"`. A `slots.footer` replaces it. List view uses it too.
+
 ## Other Customizable Slots
 
 ```tsx
 <DataGrid
+    rows={rows}
+    columns={columns}
     slots={{
         pagination: CustomPaginationComponent,
         noRowsOverlay: CustomNoRowsComponent,
@@ -140,4 +160,4 @@ Your custom pagination component will receive these props:
 
 ## Complete Example
 
-See `demo/examples/CustomPagination.tsx` for a complete working example.
+See `demo/examples/CustomPagination/CustomPagination.tsx` for a complete working example.