@opencorestack/opengridx 3.2.2 → 3.3.0

package/lib/types/index.ts

@@ -144,6 +144,12 @@ export 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. */
@@ -658,6 +664,68 @@ export interface GridPaginationModel {
 
 export type GridRowSelectionModel = GridRowId[];
 
+/** One cell, addressed by its row id and column field. @since v3.3 */
+export interface GridCellCoordinates {
+  id: GridRowId;
+  field: string;
+}
+
+/**
+ * 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 interface GridCellRange {
+  anchor: GridCellCoordinates;
+  head: GridCellCoordinates;
+}
+
+/**
+ * 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 type GridCellSelectionModel = readonly GridCellRange[];
+
+/** What changed the cell selection. @since v3.3 */
+export type GridCellSelectionReason = 'pointer' | 'keyboard' | 'selectAll' | 'api' | 'clear' | 'dataChange';
+
+/** Second argument of `onCellSelectionModelChange`. @since v3.3 */
+export interface GridCellSelectionChangeDetails {
+  reason: GridCellSelectionReason;
+}
+
+/** One cell of the selected range, as returned by `apiRef.getSelectedCells()`. @since v3.3 */
+export interface GridSelectedCell {
+  id: GridRowId;
+  field: string;
+  /** The cell's value, read through the column's `valueGetter`. */
+  value: unknown;
+}
+
+/**
+ * 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 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;
+}
+
 export interface GridPinnedColumns {
   left?: string[];
   right?: string[];
@@ -745,6 +813,12 @@ export 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;
 }
 
 /**
@@ -763,6 +837,13 @@ export interface DataGridProps<R extends GridValidRowModel = GridRowModel> {
   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;
   /**
@@ -840,6 +921,24 @@ export interface DataGridProps<R extends GridValidRowModel = GridRowModel> {
    */
   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. */
@@ -992,6 +1091,11 @@ export interface DataGridProps<R extends GridValidRowModel = GridRowModel> {
      * 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?: {
@@ -1007,6 +1111,8 @@ export interface DataGridProps<R extends GridValidRowModel = GridRowModel> {
     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. */
@@ -1198,4 +1304,28 @@ export 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>;
 }

package/lib/utils/attempt.ts

@@ -0,0 +1,14 @@
+export type AttemptResult<T> = { ok: true; value: T } | { ok: false; error: unknown };
+
+/**
+ * Calls `fn` and contains a throw. Components and hooks use it instead of an inline `try` / `catch`
+ * around expressions with `?.`, `??`, `||` or `? :`: React Compiler cannot compile a function that has
+ * those inside a `try` statement yet and skips the whole component or hook.
+ */
+export function attempt<T>(fn: () => T): AttemptResult<T> {
+    try {
+        return { ok: true, value: fn() };
+    } catch (error) {
+        return { ok: false, error };
+    }
+}

package/lib/utils/cellSelection.ts

@@ -0,0 +1,238 @@
+import type { GridCellCoordinates, GridCellRange, GridCellSelectionModel, GridRowId } from '../types';
+import { isSystemField } from './focus';
+
+/**
+ * Pure helpers of cell range selection (`cellSelection`). A range is stored as two corner cells
+ * (ids and fields); everything here works it out against the current display order.
+ */
+
+/** The synthetic row-grouping column. Like the system columns, it never joins a range. */
+export const GROUPING_COLUMN_FIELD = '__group__';
+
+/** Whether cells of this column can be part of a range: data columns only. */
+export function isRangeColumnField(field: string): boolean {
+    return !isSystemField(field) && field !== GROUPING_COLUMN_FIELD;
+}
+
+export const isSameCoordinates = (a: GridCellCoordinates | null | undefined, b: GridCellCoordinates | null | undefined): boolean =>
+    a === b || (!!a && !!b && a.id === b.id && a.field === b.field);
+
+export const isSingleCellRange = (range: GridCellRange): boolean => isSameCoordinates(range.anchor, range.head);
+
+/** A model holding the same range(s) as `b`. */
+export function isSameCellSelectionModel(a: GridCellSelectionModel, b: GridCellSelectionModel): boolean {
+    if (a === b) return true;
+    if (a.length !== b.length) return false;
+    return a.every((range, i) => isSameCoordinates(range.anchor, b[i].anchor) && isSameCoordinates(range.head, b[i].head));
+}
+
+/** A rectangle in display indices: rows of the renderable rows, columns of the range columns. Inclusive. */
+export interface CellRangeRect {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}
+
+/** The rectangle of a range, plus where its two corners are. */
+export interface ResolvedCellRange extends CellRangeRect {
+    anchorRow: number;
+    anchorCol: number;
+    headRow: number;
+    headCol: number;
+}
+
+/** Span information, from useGridSpanning. */
+export interface CellRangeSpanLookup {
+    /** For a cell covered by a span, the origin cell of that span; `null` for any other cell. */
+    getSpanOrigin: (rowId: GridRowId, field: string) => { rowId: GridRowId; field: string } | null;
+    /** The colSpan of a span origin (1 for other cells). */
+    getColSpan: (rowId: GridRowId, field: string) => number;
+    /** The rowSpan of a span origin (1 for other cells). */
+    getRowSpan: (rowId: GridRowId, field: string) => number;
+}
+
+export interface CellRangeContext {
+    /** Ids of the renderable rows (top-pinned, page rows, bottom-pinned), in display order. */
+    rowIds: readonly GridRowId[];
+    rowIndexById: ReadonlyMap<GridRowId, number>;
+    /** Range columns in screen order: left-pinned, centre, right-pinned. */
+    fields: readonly string[];
+    colIndexByField: ReadonlyMap<string, number>;
+    /** Present when the grid has column or row spans. */
+    spans?: CellRangeSpanLookup;
+}
+
+/** The merged area (span) that contains a cell, or the cell itself. */
+function mergedArea(r: number, c: number, ctx: CellRangeContext): CellRangeRect {
+    const { rowIds, fields, rowIndexById, colIndexByField, spans } = ctx;
+    const single = { top: r, bottom: r, left: c, right: c };
+    if (!spans) return single;
+    const rowId = rowIds[r];
+    const field = fields[c];
+    const origin = spans.getSpanOrigin(rowId, field) ?? { rowId, field };
+    const originRow = rowIndexById.get(origin.rowId);
+    const originCol = colIndexByField.get(origin.field);
+    if (originRow === undefined || originCol === undefined) return single;
+    const rowSpan = Math.max(1, spans.getRowSpan(origin.rowId, origin.field));
+    const colSpan = Math.max(1, spans.getColSpan(origin.rowId, origin.field));
+    return {
+        top: originRow,
+        bottom: Math.min(rowIds.length - 1, originRow + rowSpan - 1),
+        left: originCol,
+        right: Math.min(fields.length - 1, originCol + colSpan - 1),
+    };
+}
+
+/**
+ * Grows a rectangle until no span crosses its edge, as Excel does with merged cells. A span that
+ * crosses the edge holds a cell on the edge, so only the edge cells are looked at.
+ */
+export function growRectToSpans(rect: CellRangeRect, ctx: CellRangeContext): CellRangeRect {
+    if (!ctx.spans) return rect;
+    let { top, bottom, left, right } = rect;
+    let changed = true;
+    const take = (area: CellRangeRect) => {
+        if (area.top < top) { top = area.top; changed = true; }
+        if (area.bottom > bottom) { bottom = area.bottom; changed = true; }
+        if (area.left < left) { left = area.left; changed = true; }
+        if (area.right > right) { right = area.right; changed = true; }
+    };
+    while (changed) {
+        changed = false;
+        for (let r = top; r <= bottom; r++) {
+            take(mergedArea(r, left, ctx));
+            if (right !== left) take(mergedArea(r, right, ctx));
+        }
+        for (let c = left + 1; c < right; c++) {
+            take(mergedArea(top, c, ctx));
+            if (bottom !== top) take(mergedArea(bottom, c, ctx));
+        }
+    }
+    return { top, bottom, left, right };
+}
+
+/**
+ * Where a range lies in the current display order, or `null` when one of its corners is not
+ * displayed (its row was filtered, paged or removed, or its column hidden).
+ */
+export function resolveCellRange(range: GridCellRange, ctx: CellRangeContext): ResolvedCellRange | null {
+    const anchorRow = ctx.rowIndexById.get(range.anchor.id);
+    const headRow = ctx.rowIndexById.get(range.head.id);
+    const anchorCol = ctx.colIndexByField.get(range.anchor.field);
+    const headCol = ctx.colIndexByField.get(range.head.field);
+    if (anchorRow === undefined || headRow === undefined || anchorCol === undefined || headCol === undefined) return null;
+    const rect = growRectToSpans({
+        top: Math.min(anchorRow, headRow),
+        bottom: Math.max(anchorRow, headRow),
+        left: Math.min(anchorCol, headCol),
+        right: Math.max(anchorCol, headCol),
+    }, ctx);
+    return { ...rect, anchorRow, anchorCol, headRow, headCol };
+}
+
+export const rectCellCount = (rect: CellRangeRect): number => (rect.bottom - rect.top + 1) * (rect.right - rect.left + 1);
+
+/**
+ * The new head for a Shift+navigation key, as display indices, or `null` when it does not move.
+ * Shift+Arrow moves one cell and does not wrap to the next row. Extending moves from the far edge
+ * of the rectangle, so the head steps out of a span it grew over.
+ */
+export function nextRangeHead(
+    resolved: ResolvedCellRange,
+    key: string,
+    withModifier: boolean,
+    pageSize: number,
+    lastRow: number,
+    lastCol: number,
+): { row: number; col: number } | null {
+    const { headRow, headCol, anchorRow, anchorCol, top, bottom, left, right } = resolved;
+    let row = headRow;
+    let col = headCol;
+    switch (key) {
+        case 'ArrowRight': col = headCol >= anchorCol ? right + 1 : headCol + 1; break;
+        case 'ArrowLeft': col = headCol <= anchorCol ? left - 1 : headCol - 1; break;
+        case 'ArrowDown': row = headRow >= anchorRow ? bottom + 1 : headRow + 1; break;
+        case 'ArrowUp': row = headRow <= anchorRow ? top - 1 : headRow - 1; break;
+        case 'Home':
+            col = 0;
+            if (withModifier) row = 0;
+            break;
+        case 'End':
+            col = lastCol;
+            if (withModifier) row = lastRow;
+            break;
+        case 'PageUp': row = headRow - pageSize; break;
+        case 'PageDown': row = headRow + pageSize; break;
+        default: return null;
+    }
+    row = Math.min(Math.max(row, 0), lastRow);
+    col = Math.min(Math.max(col, 0), lastCol);
+    if (row === headRow && col === headCol) return null;
+    return { row, col };
+}
+
+/**
+ * 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`).
+ */
+export 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 function getRowCellRange(
+    range: { top: number; bottom: number; left: number; right: number } | null | undefined,
+    rowIndex: number,
+    hasRowSpan: boolean,
+): GridRowCellRange | null {
+    if (!range || rowIndex < range.top || rowIndex > range.bottom) return null;
+    return {
+        left: range.left,
+        right: range.right,
+        isTop: rowIndex === range.top,
+        isBottom: rowIndex === range.bottom,
+        bottomOffset: hasRowSpan ? range.bottom - rowIndex : 0,
+    };
+}
+
+export const isSameRowCellRange = (a: GridRowCellRange | null | undefined, b: GridRowCellRange | null | undefined): boolean =>
+    a === b || (!!a && !!b && a.left === b.left && a.right === b.right && a.isTop === b.isTop && a.isBottom === b.isBottom
+        && a.bottomOffset === b.bottomOffset);
+
+/** Bit flags a cell receives for its place in the range (a number keeps memoised cells stable). */
+export const RANGE_CELL = 1;
+export const RANGE_TOP = 2;
+export const RANGE_BOTTOM = 4;
+export const RANGE_LEFT = 8;
+export const RANGE_RIGHT = 16;
+
+/**
+ * The flags of the cell at data column `colIndex` (spanning `colSpan` columns and `rowSpan` rows from
+ * this row), or 0 when it is outside the range.
+ */
+export function getCellRangeFlags(rowRange: GridRowCellRange | null | undefined, colIndex: number, colSpan: number, rowSpan: number): number {
+    if (!rowRange) return 0;
+    const lastCol = colIndex + Math.max(1, colSpan) - 1;
+    if (colIndex < rowRange.left || lastCol > rowRange.right) return 0;
+    let flags = RANGE_CELL;
+    if (rowRange.isTop) flags |= RANGE_TOP;
+    if (rowRange.isBottom || (rowSpan > 1 && rowSpan - 1 >= rowRange.bottomOffset)) flags |= RANGE_BOTTOM;
+    if (colIndex === rowRange.left) flags |= RANGE_LEFT;
+    if (lastCol === rowRange.right) flags |= RANGE_RIGHT;
+    return flags;
+}
+
+/** The default screen-reader text after a range change. */
+export function defaultCellSelectionAnnouncement(cellCount: number, rowCount: number, columnCount: number): string {
+    const plural = (n: number, one: string, many: string) => `${n} ${n === 1 ? one : many}`;
+    return `${plural(cellCount, 'cell', 'cells')} selected, ${plural(rowCount, 'row', 'rows')} by ${plural(columnCount, 'column', 'columns')}`;
+}
+
+/** Above this many cells a copy warns (development only) that exportToCsv suits the job better. */
+export const LARGE_RANGE_COPY_CELLS = 100_000;

package/lib/utils/headerWrap.ts

@@ -0,0 +1,23 @@
+/**
+ * Line height of a wrapped header title in pixels. Must match `line-height` of
+ * `.ogx__header-cell--wrap .ogx__header-cell-title` in Header.css.
+ */
+export const HEADER_WRAP_LINE_HEIGHT = 16;
+
+/** Vertical padding of a header cell (`--ogx-grid-cell-padding-y`, 8px by default), top plus bottom. */
+const HEADER_VERTICAL_PADDING = 16;
+
+/**
+ * How many lines a wrapped header title may take inside a header of `headerHeight` pixels: 2 at 56px,
+ * 3 at 72px, 4 at 88px. One line less when the aggregation label sits under the title. Never below 1.
+ */
+export function getHeaderLineClamp(headerHeight: number, hasAggregationLabel = false): number {
+    const available = Number.isFinite(headerHeight) ? headerHeight - HEADER_VERTICAL_PADDING : 0;
+    const lines = Math.floor(available / HEADER_WRAP_LINE_HEIGHT) - (hasAggregationLabel ? 1 : 0);
+    return Math.max(1, lines);
+}
+
+/** Whether a column's header title wraps: the column's own `wrapHeaderText` wins over the grid's. */
+export function shouldWrapHeaderText(columnWrap: boolean | undefined, gridWrap: boolean | undefined): boolean {
+    return columnWrap ?? gridWrap ?? false;
+}

package/llms.txt

@@ -1,6 +1,6 @@
 # OpenGridX — AI Agent Context
 # Package: @opencorestack/opengridx
-# Version: 3.2.2
+# Version: 3.3.0
 # Docs: https://opencorestack.github.io/OpenGridX/
 # This file is machine-readable. AI developers: start here.
 
@@ -78,6 +78,7 @@ export default function App() {
 | localeText        | GridLocaleText | —  | Override pager / no-rows strings: paginationRowsPerPage, paginationOf(from,to,count), paginationPage(page,count), noRowsLabel |
 | rowHeight         | number    | 52      | Row height in pixels                   |
 | headerHeight      | number    | 56      | Header height in pixels                |
+| wrapHeaderText    | boolean   | false   | Wrap header titles within headerHeight (2 lines at 56px, 3 at 72, 4 at 88; ellipsis on the last line). Header never grows: raise headerHeight for more lines. Class ogx__header-cell--wrap. Per column: GridColDef.wrapHeaderText (3.3.0+) |
 | loading           | boolean   | false   | No rows: skeleton rows (or slots.loadingOverlay). Rows shown: they stay, a progress bar (.ogx__loading-bar) runs along the top, or slots.loadingOverlay is shown over them |
 | noRowsLabel       | string    | 'No Data' | Empty state message                  |
 | density           | 'compact'/'standard'/'comfortable' | 'standard' | 32px / rowHeight / 72px rows |
@@ -92,6 +93,10 @@ export default function App() {
 | onRowSelectionModelChange  | (model: GridRowId[]) => void  | Selection change callback. Also fires once with ids of removed rows pruned (client-owned rows) |
 | disableRowSelectionOnClick | boolean                       | Prevent click toggling selection    |
 | disableClipboardCopy       | boolean                       | Turn off the grid's Ctrl/Cmd+C copy (copySelectedRows still works) |
+| cellSelection              | boolean (3.3.0+)              | Spreadsheet-style cell ranges: drag (auto-scrolls), Shift+click, Shift+arrows/Home/End/PageUp/PageDown, Ctrl/Cmd+A = every data cell of the page, Escape collapses. Ctrl/Cmd+C then copies the range as TSV (no header line) instead of the selected rows. Ranges never change the row selection |
+| cellSelectionModel         | GridCellSelectionModel        | Controlled range: readonly { anchor: { id, field }, head: { id, field } }[] (0 or 1 range). Corners are ids/fields: the range follows sorting; cleared ('dataChange') when a corner is no longer displayed |
+| onCellSelectionModelChange | (model, { reason }) => void   | reason: 'pointer' | 'keyboard' | 'selectAll' | 'api' | 'clear' | 'dataChange' |
+| showCellSelectionStats     | boolean                       | Status bar: Count (non-empty), Sum and Average (numeric) of the range; slots.cellSelectionStats replaces it |
 
 ### Sorting
 | Prop              | Type                        | Description                     |
@@ -247,6 +252,7 @@ There are no getRowClassName / getCellClassName / theme props: use GridColDef.ce
 | rowSpan           | number / (params) => number                            | Cell row span (clamped to the row section) |
 | align             | 'left'/'center'/'right'                                | Cell content alignment                     |
 | headerAlign       | 'left'/'center'/'right'                                | Header content alignment                   |
+| wrapHeaderText    | boolean                                                | Wrap this header title; overrides the grid prop (3.3.0+) |
 | sortable          | boolean (default true)                                 | Enable sorting                             |
 | sortComparator    | (v1, v2, params1, params2) => number                   | Custom ascending comparator (3.1.0+). v1/v2 are valueGetter values incl. null/undefined; params { id, field, row, value }. Negated for desc; multi-sort tie-break chain; groups by grouping value; tree siblings; pivot row labels. Throw/NaN = 0. Ignored in server sortingMode |
 | filterable        | boolean (default true)                                 | Enable filtering and quick search          |
@@ -307,6 +313,14 @@ apiRef.current.autosizeColumns(fields?)
 apiRef.current.copySelectedRows()      // → Promise<void>; rejects if the write fails. Copies every selected row that passes
                                        //   the filter (all pages, collapsed groups, pinned rows), visible columns in screen order
 
+// Cell range selection (cellSelection, 3.3.0+); inert while cellSelection is off
+apiRef.current.selectCellRange({ id: 1, field: 'a' }, { id: 5, field: 'c' }) // anchor = active cell
+apiRef.current.setCellSelectionModel(model)
+apiRef.current.getCellSelectionModel()  // → GridCellSelectionModel
+apiRef.current.getSelectedCells()      // → { id, field, value }[]; synthetic rows and span-covered cells left out
+apiRef.current.copySelectedCells()     // → Promise<void>; TSV, no header line
+apiRef.current.clearCellSelection()
+
 // Aggregation
 apiRef.current.getAggregationResult()  // → Record<string, unknown> | null (null in pivot mode)
 apiRef.current.getAggregationModel()   // → GridAggregationModel | null
@@ -530,7 +544,8 @@ Derived tokens (e.g. `--ogx-grid-cell-focus-border`, which defaults to the prima
 Class names use the `ogx__` BEM prefix, e.g.:
 - `ogx__row`, `ogx__row--selected`, `ogx__row--even`, `ogx__row--odd`
 - `ogx__cell`, `ogx__cell--focused`, `ogx__cell--editing`
-- `ogx__header-cell`, `ogx__header-cell--sorted`
+- Cell ranges (3.3.0+): `ogx__cell--range`, `ogx__cell--range-top|bottom|left|right` (inset box-shadow outline), `ogx--range-dragging` on the root during a drag; variables `--ogx-range-background`, `--ogx-range-border` (theme keys `grid.rangeBackground`, `grid.rangeBorder`)
+- `ogx__header-cell`, `ogx__header-cell--sorted`, `ogx__header-cell--wrap` (wrapHeaderText, 3.3.0+)
 - Sticky wrappers: `ogx__sticky-top` (header + top-pinned rows), `ogx__sticky-bottom` (bottom-pinned rows + aggregation footer)
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@opencorestack/opengridx",
-  "version": "3.2.2",
+  "version": "3.3.0",
   "description": "OpenGridX: High-performance React data infrastructure. Unlock advanced Row Grouping, Excel Export, and Column Pinning without the usual \"Pro\" gatekeeping. Built for speed, scale, and complete architectural freedom. Fully open, virtualization-ready, and feature-complete.",
   "type": "module",
   "main": "./dist/opengridx.umd.js",
@@ -55,7 +55,9 @@
     "test:smoke": "node scripts/smoke.mjs",
     "test:watch": "vitest --project unit",
     "coverage": "vitest run --coverage",
-    "prepublishOnly": "npm run build:lib"
+    "prepublishOnly": "npm run build:lib",
+    "wiki:build": "node scripts/build-wiki.mjs",
+    "check:compiler": "node scripts/check-react-compiler.mjs"
   },
   "keywords": [
     "react",
@@ -106,6 +108,7 @@
     }
   },
   "devDependencies": {
+    "@babel/core": "^7.29.7",
     "@eslint/js": "^9.39.1",
     "@playwright/test": "^1.58.2",
     "@testing-library/jest-dom": "^7.0.0",
@@ -117,8 +120,9 @@
     "@vitejs/plugin-react": "^5.1.1",
     "@vitest/browser-playwright": "^4.1.11",
     "@vitest/coverage-v8": "^4.1.11",
+    "babel-plugin-react-compiler": "^1.0.0",
     "eslint": "^9.39.1",
-    "eslint-plugin-react-hooks": "^7.0.1",
+    "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-react-refresh": "^0.4.24",
     "exceljs": "^4.4.0",
     "globals": "^16.5.0",