@opencorestack/opengridx 3.2.2 → 3.3.0

package/CHANGELOG.md

@@ -5,6 +5,28 @@
 
 ---
 
+## [3.3.0] — 2026-10-07
+
+### Added
+
+- **Wrapped header text** — new grid prop `wrapHeaderText` and per-column `GridColDef.wrapHeaderText` (the column wins). Long header titles wrap instead of being cut with an ellipsis, within the existing `headerHeight`: 2 lines at 56px, 3 at 72px, 4 at 88px, with an ellipsis on the last line if the title is still longer. The header never grows on its own; raise `headerHeight` for more lines. Wrapped header cells get the new class `ogx__header-cell--wrap` and show their full title as the `title` tooltip unless the column has a `description`. Sort icon, column menu button and resize handle are unchanged, and column auto-size still fits the title on one line. Demo: *Wrapped Header Text* (`/header-wrap`).
+- **Cell range selection** (`cellSelection`) — select a rectangle of cells as in Excel or Google Sheets: press and drag (the grid auto-scrolls over virtualized rows and columns when the pointer nears or leaves an edge), Shift+click, Shift+Arrow (no row wrap), Shift+Home/End, Ctrl+Shift+Home/End, Shift+PageUp/PageDown, Ctrl/Cmd+A (every data cell of the page) and Escape (collapse to the anchor). Ctrl/Cmd+C copies the range (the focused cell at minimum) as TSV, formatted as shown, without a header line; `apiRef.current.copySelectedRows()` still copies rows. Ranges never change the row selection; the checkbox, detail-panel, reorder and `__group__` columns never join a range. Group rows, subtotals, tree auto-parents and the pivot Grand Total are highlighted but not copied. A range touching part of a `colSpan` / `rowSpan` grows to cover it. Off by default: grids without the prop are unchanged.
+- **`cellSelectionModel` / `onCellSelectionModelChange(model, { reason })`** — controlled or uncontrolled model of `{ anchor, head }` corners addressed by row id and field, so a range follows its rows through sorting; it is cleared (`reason: 'dataChange'`) when a corner is no longer displayed. New types `GridCellCoordinates`, `GridCellRange`, `GridCellSelectionModel`, `GridCellSelectionReason`, `GridCellSelectionChangeDetails`, `GridSelectedCell`.
+- **`GridApi`**: `getCellSelectionModel`, `setCellSelectionModel`, `selectCellRange`, `clearCellSelection`, `getSelectedCells`, `copySelectedCells`.
+- **`showCellSelectionStats`** — a status bar with the Count, Sum and Average of the range (shared aggregation functions), replaceable through `slots.cellSelectionStats` (`GridCellSelectionStatsSlotProps`); the default component is exported as `CellSelectionStats`.
+- **Accessibility** — range cells carry `aria-selected="true"`, focus stays on the anchor, and the live region announces the size ("12 cells selected, 3 rows by 4 columns", debounced 300 ms); translate it with `localeText.cellSelectionAnnouncement`.
+- **Styling** — public classes `ogx__cell--range`, `ogx__cell--range-top|bottom|left|right` (inset outline, no layout shift) and `ogx--range-dragging`; CSS variables `--ogx-range-background` and `--ogx-range-border`, defined in every built-in theme and settable with the theme keys `grid.rangeBackground` / `grid.rangeBorder`.
+- Demo page *Cell Range Selection* and guide `docs/features/cell-selection.md`.
+
+### Changed
+
+- `Row` is now memoised (its `cellRange` prop compared by value), and the row click / checkbox handlers keep their identity across renders, so rows whose props did not change no longer re-render.
+
+### Internal
+
+- **React Compiler compatibility checked** — the library works in apps that use React Compiler, and when `lib/` itself is compiled (unit and browser suites pass with `REACT_COMPILER=1`). Fixed what the compiler rejected: a prop mutated in `Checkbox`, a self-referencing callback in `useGridEditing`, memoization the compiler could not keep in `FilterPanel` / `GridToolbar`, value expressions inside `try` in `Cell` / `useAggregation` / `useGridEditing`, and `GridToolbar`'s `forceColumnsOpen` effect. `InlineToolbar` (`slots.toolbar`) and `CellRenderTarget` (`renderCell`) are marked `'use no memo'`: compiled, they skipped the consumer's toolbar / cell function on re-render and broke its hooks. ESLint uses `react-hooks` `recommended-latest` (7.1.1) with `immutability` and `preserve-manual-memoization` on; new `npm run check:compiler`. Findings, remaining issues and how to re-run: `docs/contributing/react-compiler.md`.
+- **GitHub wiki** generated from `docs/` — `scripts/build-wiki.mjs` (`npm run wiki:build`) turns the docs, CHANGELOG and CONTRIBUTING into wiki pages with a sidebar, rewrites relative links to wiki pages (or GitHub URLs for source files and images), and adds hand-written Home, Getting Started and FAQ pages from `wiki/`. `.github/workflows/wiki.yml` publishes it on every push to `main` that touches them.
+
 ## [3.2.2] — 2026-10-01
 
 ### Security

package/README.md

@@ -76,6 +76,7 @@ Without a `height` prop the grid fills its container (`height: 100%`, or the fre
 - **Fully Customizable**: Slots system for replacing any component (pagination, overlays, toolbar).
 - **Export Functionality**: Built-in CSV, Excel (HTML `.xls`, or real `.xlsx` with the optional ExcelJS peer), JSON, PDF (optional jsPDF peer) and Print export.
 - **Clipboard**: `Ctrl+C` / `Cmd+C` copies the selected rows' visible columns as TSV for Excel/Sheets.
+- **Cell Range Selection** (v3.3): drag, Shift+click or Shift+arrows select a rectangle of cells; copy it as TSV and see its count, sum and average in a status bar (`cellSelection`, `showCellSelectionStats`).
 - **Accessibility**: WCAG 2.1 AA — full ARIA roles and keyboard navigation.
 - **Theming**: CSS variable API, `DataGridThemeProvider` with 5 built-in themes (`darkTheme`, `roseTheme`, `emeraldTheme`, `amberTheme`, `compactTheme`) and custom themes.
 - **Column & Row Reordering**: Drag-and-drop column reordering and row reordering.
@@ -174,6 +175,9 @@ This means that **Cursor**, **GitHub Copilot**, **Windsurf**, and other AI agent
 | `disableMultipleRowSelection` | `boolean` | Restrict to single-row selection. |
 | `pinCheckboxColumn` | `boolean` | Keeps the checkbox column visible during horizontal scroll. Default `true`. |
 | `disableClipboardCopy` | `boolean` | Turns off the grid's Ctrl/Cmd+C copy (`apiRef.current.copySelectedRows()` still works). |
+| `cellSelection` | `boolean` | Spreadsheet-style cell range selection; Ctrl/Cmd+C then copies the range (v3.3). |
+| `cellSelectionModel` / `onCellSelectionModelChange` | `GridCellSelectionModel` / `(model, { reason }) => void` | Controlled cell range. |
+| `showCellSelectionStats` | `boolean` | Status bar with count, sum and average of the range. |
 
 ### Sorting & Filtering
 
@@ -316,6 +320,12 @@ apiRef.current.autosizeColumn('name')   // fit to content (v3.1.0+)
 // Clipboard
 apiRef.current.copySelectedRows()      // → Promise<void>, rejects if the clipboard write fails
 
+// Cell range selection (cellSelection, v3.3.0+)
+apiRef.current.selectCellRange({ id: 1, field: 'q1' }, { id: 12, field: 'q4' })
+apiRef.current.getSelectedCells()      // → { id, field, value }[]
+apiRef.current.copySelectedCells()     // → Promise<void>
+apiRef.current.clearCellSelection()
+
 // Aggregation
 apiRef.current.getAggregationResult()  // → Record<string, unknown> | null
 apiRef.current.getAggregationModel()   // → GridAggregationModel | null
@@ -490,7 +500,7 @@ Built-in themes: `darkTheme`, `roseTheme`, `emeraldTheme`, `amberTheme`, `compac
 
 ## 📚 Documentation
 
-Full documentation at 👉 **[opencorestack.github.io/OpenGridX](https://opencorestack.github.io/OpenGridX/)**
+Full documentation at 👉 **[opencorestack.github.io/OpenGridX](https://opencorestack.github.io/OpenGridX/)** · 📖 **[Wiki](https://github.com/OpenCoreStack/OpenGridX/wiki)**
 
 ### 🏛️ Components
 - **[DataGrid](docs/components/datagrid.md)** — Main component props and slots
@@ -510,6 +520,7 @@ Full documentation at 👉 **[opencorestack.github.io/OpenGridX](https://opencor
 - **[Export Guide](docs/features/export-guide.md)** — Excel, CSV, JSON, and Print
 - **[PDF Export](docs/features/pdf-export.md)** — Branded PDF reports
 - **[Clipboard](docs/features/clipboard.md)** — Copy rows as TSV
+- **[Cell Range Selection](docs/features/cell-selection.md)** — Select, total and copy cell ranges
 - **[Keyboard & Accessibility](docs/features/keyboard-navigation.md)** — Keys, focus and ARIA
 - **[Data Source](docs/features/data-source.md)** — Server-side integration
 - **[Loading States](docs/features/loading-states.md)** — Skeleton and shimmer overlays

package/dist/index.d.ts

@@ -79,8 +79,22 @@ export declare interface CellProps<R extends GridRowModel = GridRowModel> {
     rowMeta?: GridRowMeta;
     /** The error the column's valueGetter threw for this cell (computed by Row); shown as a cell error. */
     valueError?: unknown;
+    /**
+     * Place of the cell in the selected cell range (`cellSelection`), as bit flags: in range 1, top
+     * edge 2, bottom 4, left 8, right 16. 0 or absent: not in a range. @since v3.3
+     */
+    rangeFlags?: number;
 }
 
+/**
+ * The status bar of `showCellSelectionStats`: count of non-empty cells, and the sum and average of
+ * the numeric cells of the selected range. Replace it with `slots.cellSelectionStats`, or wrap it.
+ * @since v3.3
+ */
+export declare function CellSelectionStats({ count, sum, average }: CellSelectionStatsProps): JSX.Element;
+
+export declare type CellSelectionStatsProps = GridCellSelectionStatsSlotProps & Record<string, unknown>;
+
 export declare const Checkbox: default_2.FC<CheckboxProps>;
 
 export declare interface CheckboxProps extends Omit<default_2.InputHTMLAttributes<HTMLInputElement>, 'type'> {
@@ -164,6 +178,13 @@ export declare interface DataGridProps<R extends GridValidRowModel = GridRowMode
     rowHeight?: number;
     /** Height of the header row in pixels. Defaults to 56. */
     headerHeight?: number;
+    /**
+     * Wraps header titles onto several lines instead of cutting them with an ellipsis. The header
+     * keeps `headerHeight` (2 lines at the default 56px, 3 at 72px, 4 at 88px); a title that still
+     * does not fit ends in an ellipsis. `GridColDef.wrapHeaderText` overrides it per column.
+     * Defaults to `false`.
+     */
+    wrapHeaderText?: boolean;
     /** If true, the grid height will adjust to match the total height of its rows. */
     autoHeight?: boolean;
     /**
@@ -233,6 +254,23 @@ export declare interface DataGridProps<R extends GridValidRowModel = GridRowMode
      * the shortcut. `apiRef.current.copySelectedRows()` still works. Default: false.
      */
     disableClipboardCopy?: boolean;
+    /**
+     * Lets users select a rectangle of cells (drag, Shift+click, Shift+arrows, Ctrl/Cmd+A) and copy it
+     * with Ctrl/Cmd+C as tab-separated text. While on, Ctrl/Cmd+C copies the cell range (the focused
+     * cell at minimum) instead of the selected rows; `apiRef.copySelectedRows()` still copies rows.
+     * Default: false. @since v3.3
+     */
+    cellSelection?: boolean;
+    /** Controlled cell selection (zero or one range). Needs `cellSelection`. @since v3.3 */
+    cellSelectionModel?: GridCellSelectionModel;
+    /** Fired when the cell selection changes, with what changed it. @since v3.3 */
+    onCellSelectionModelChange?: (model: GridCellSelectionModel, details: GridCellSelectionChangeDetails) => void;
+    /**
+     * Shows a status bar under the grid with the count of non-empty cells and the sum and average of the
+     * numeric cells in the range, while more than one cell is selected. Replaceable through
+     * `slots.cellSelectionStats`. Needs `cellSelection`. Default: false. @since v3.3
+     */
+    showCellSelectionStats?: 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. */
@@ -371,6 +409,11 @@ export declare interface DataGridProps<R extends GridValidRowModel = GridRowMode
          * Receives `GridFooterSlotProps` (plus `slotProps.footer`).
          */
         footer?: React.ComponentType<GridFooterSlotProps & Record<string, unknown>>;
+        /**
+         * Replaces the status bar of `showCellSelectionStats`. Receives `GridCellSelectionStatsSlotProps`
+         * (plus `slotProps.cellSelectionStats`). @since v3.3
+         */
+        cellSelectionStats?: React.ComponentType<GridCellSelectionStatsSlotProps & Record<string, unknown>>;
     };
     /** Properties passed directly to custom slots. */
     slotProps?: {
@@ -386,6 +429,8 @@ export declare interface DataGridProps<R extends GridValidRowModel = GridRowMode
         loadingOverlay?: GridOverlaySlotProps;
         /** Merged over the `GridFooterSlotProps` the grid passes to the footer slot. */
         footer?: Partial<GridFooterSlotProps> & Record<string, unknown>;
+        /** Merged over the `GridCellSelectionStatsSlotProps` the grid passes to the status bar. */
+        cellSelectionStats?: Partial<GridCellSelectionStatsSlotProps> & Record<string, unknown>;
     };
     /** When true, renders the grid as a single-column list of cards. Perfect for mobile/responsive views. */
     listView?: boolean;
@@ -688,6 +733,35 @@ export declare interface GridApi<R extends GridValidRowModel = GridRowModel> {
      * in which case nothing is written) and rejects when the clipboard write fails.
      */
     copySelectedRows: () => Promise<void>;
+    /** The cell selection (`[]` when `cellSelection` is off or nothing is selected). @since v3.3 */
+    getCellSelectionModel: () => GridCellSelectionModel;
+    /**
+     * Replaces the cell selection (only the first range is kept) and moves focus to its anchor.
+     * Does nothing while `cellSelection` is off. @since v3.3
+     */
+    setCellSelectionModel: (model: GridCellSelectionModel) => void;
+    /** Selects the rectangle between two cells; `anchor` becomes the active cell. @since v3.3 */
+    selectCellRange: (anchor: GridCellCoordinates, head: GridCellCoordinates) => void;
+    /** Empties the cell selection. Focus stays where it is. @since v3.3 */
+    clearCellSelection: () => void;
+    /**
+     * Cells of the current range in display order (row by row, columns in screen order), values read
+     * through the column's `valueGetter`. Synthetic rows (group headers, subtotals, tree auto-parents, the
+     * pivot Grand Total) and positions covered by a span are left out. @since v3.3
+     */
+    getSelectedCells: () => GridSelectedCell[];
+    /**
+     * Copies the cell range (the focused cell when nothing is selected) as tab-separated text, formatted
+     * the way the cells show it, with no header line. Resolves without writing when there is nothing to
+     * copy; rejects when the clipboard write fails. @since v3.3
+     */
+    copySelectedCells: () => Promise<void>;
+}
+
+/** One cell, addressed by its row id and column field. @since v3.3 */
+export declare interface GridCellCoordinates {
+    id: GridRowId;
+    field: string;
 }
 
 export declare interface GridCellParams<R extends GridValidRowModel = GridRowModel> {
@@ -699,6 +773,54 @@ export declare interface GridCellParams<R extends GridValidRowModel = GridRowMod
     colIndex: number;
 }
 
+/**
+ * A rectangle of cells between two corners. `anchor` is the active cell: it keeps focus, is the cell
+ * an edit starts in, and stays put while the range is extended. `head` is the corner that moves with
+ * Shift+arrows or the pointer, and the one scrolled into view. A single cell has `anchor` equal to `head`.
+ * @since v3.3
+ */
+export declare interface GridCellRange {
+    anchor: GridCellCoordinates;
+    head: GridCellCoordinates;
+}
+
+/** Second argument of `onCellSelectionModelChange`. @since v3.3 */
+export declare interface GridCellSelectionChangeDetails {
+    reason: GridCellSelectionReason;
+}
+
+/**
+ * The cell selection: zero or one range in 3.3 (the array form leaves room for several ranges later).
+ * Corners are ids and fields, so the rectangle follows its corner rows through sorting and filtering.
+ * @since v3.3
+ */
+export declare type GridCellSelectionModel = readonly GridCellRange[];
+
+/** What changed the cell selection. @since v3.3 */
+export declare type GridCellSelectionReason = 'pointer' | 'keyboard' | 'selectAll' | 'api' | 'clear' | 'dataChange';
+
+/**
+ * Props the grid passes to `slots.cellSelectionStats` (the status bar of `showCellSelectionStats`),
+ * before `slotProps.cellSelectionStats` is merged over them. Rendered only while more than one cell
+ * is selected.
+ * @since v3.3
+ */
+export declare interface GridCellSelectionStatsSlotProps {
+    apiRef: React.MutableRefObject<GridApi>;
+    /** Cells in the rectangle (rows × columns), synthetic rows and span-covered positions included. */
+    cellCount: number;
+    rowCount: number;
+    columnCount: number;
+    /** Non-empty cells of data rows. */
+    count: number;
+    /** Cells holding a number. */
+    numericCount: number;
+    /** Sum of the numeric cells, or `null` when there are none. */
+    sum: number | null;
+    /** Average of the numeric cells, or `null` when there are none. */
+    average: number | null;
+}
+
 /**
  * Metadata for a single column.
  * Governs rendering, sorting, filtering, and data transformation.
@@ -737,6 +859,12 @@ export declare interface GridColDef<R extends GridValidRowModel = GridRowModel>
     align?: GridAlignment;
     /** Content alignment within the header cell. */
     headerAlign?: GridAlignment;
+    /**
+     * Wraps this column's header title onto several lines instead of cutting it with an ellipsis.
+     * Overrides the grid's `wrapHeaderText`. The header keeps `headerHeight`: the title shows as many
+     * lines as fit and ends in an ellipsis if it is still longer. Raise `headerHeight` for more lines.
+     */
+    wrapHeaderText?: boolean;
     /** If false, sorting is disabled for this column. */
     sortable?: boolean;
     /** If false, filtering is disabled for this column. */
@@ -1046,6 +1174,12 @@ export declare interface GridLocaleText {
     paginationPage?: (page: number, pageCount: number) => string;
     /** Empty-state label. When set, overrides the `noRowsLabel` prop on DataGrid. Default: `"No Data"` */
     noRowsLabel?: string;
+    /**
+     * Screen-reader announcement after the cell range changes (`cellSelection`). Receives (cells, rows,
+     * columns). Default: `` (c, r, col) => `${c} cells selected, ${r} rows by ${col} columns` `` (singular for 1).
+     * @since v3.3
+     */
+    cellSelectionAnnouncement?: (cellCount: number, rowCount: number, columnCount: number) => string;
 }
 
 /**
@@ -1132,6 +1266,20 @@ export declare interface GridRenderHeaderParams {
     colIndex: number;
 }
 
+/**
+ * The range flags one row passes to its cells, or `null` for a row outside the range. Rows outside
+ * keep `null`, so a drag only re-renders the rows it enters or leaves. `left` / `right` are data
+ * column indices (`columnIndexMap`).
+ */
+declare interface GridRowCellRange {
+    left: number;
+    right: number;
+    isTop: boolean;
+    isBottom: boolean;
+    /** Rows from this one to the bottom of the range; only set (else 0) when the grid has row spans. */
+    bottomOffset: number;
+}
+
 export declare type GridRowGroupingModel = string[];
 
 /** Unique identifier for a row (string or number). */
@@ -1213,6 +1361,14 @@ export declare interface GridRowScrollEndParams {
 
 export declare type GridRowSelectionModel = GridRowId[];
 
+/** One cell of the selected range, as returned by `apiRef.getSelectedCells()`. @since v3.3 */
+export declare interface GridSelectedCell {
+    id: GridRowId;
+    field: string;
+    /** The cell's value, read through the column's `valueGetter`. */
+    value: unknown;
+}
+
 /** The `slotProps` prop of `DataGrid`: props for each slot, keyed like `GridSlots`. */
 export declare type GridSlotProps = NonNullable<DataGridProps['slotProps']>;
 
@@ -1354,6 +1510,10 @@ export declare interface GridThemeGrid {
     rowSelectedBackground?: string;
     rowSelectedHoverBackground?: string;
     cellFocusBorder?: string;
+    /** Tint over a selected cell range (`--ogx-range-background`). Default: the primary colour at 12%. @since v3.3 */
+    rangeBackground?: string;
+    /** Outline of a selected cell range (`--ogx-range-border`). Default: the primary colour. @since v3.3 */
+    rangeBorder?: string;
     pinnedLeftShadow?: string;
     pinnedRightShadow?: string;
     checkboxBg?: string;
@@ -1635,6 +1795,10 @@ export declare interface HeaderProps<R extends GridRowModel = GridRowModel> {
     onManageColumns?: () => void;
     /** Position of each visible data column in render order, for `colIndex` and `aria-colindex`. */
     columnIndexMap?: Map<string, number>;
+    /** Wraps header titles onto several lines; `GridColDef.wrapHeaderText` overrides it per column. */
+    wrapHeaderText?: boolean;
+    /** Header row height in pixels; sets how many lines a wrapped title may take. Defaults to 56. */
+    headerHeight?: number;
 }
 
 export declare const Input: default_2.FC<InputProps>;
@@ -1835,7 +1999,10 @@ export declare interface PrintOptions<R extends GridValidRowModel = GridRowModel
 
 export declare const roseTheme: GridTheme;
 
-export declare function Row<R extends GridRowModel = GridRowModel>(props: RowProps<R>): JSX.Element;
+/** One grid row. Memoised: rows whose props did not change (for example outside a dragged cell range) do not re-render. */
+export declare const Row: typeof RowImpl;
+
+declare function RowImpl<R extends GridRowModel = GridRowModel>(props: RowProps<R>): JSX.Element;
 
 export declare interface RowProps<R extends GridRowModel = GridRowModel> {
     row: R;
@@ -1901,6 +2068,11 @@ export declare interface RowProps<R extends GridRowModel = GridRowModel> {
     columnIndexMap?: Map<string, number>;
     /** 1-based `aria-rowindex` of this row in the whole grid (header rows included). Defaults to `rowIndex + 2`. */
     ariaRowIndex?: number;
+    /**
+     * The part of the selected cell range (`cellSelection`) in this row, or `null` / absent when the
+     * row is outside it. @since v3.3
+     */
+    cellRange?: GridRowCellRange | null;
 }
 
 declare interface RowSpanningCaches {