@opencorestack/opengridx 3.2.1 → 3.3.0

package/lib/hooks/core/useGridCellSelectionApi.ts

@@ -0,0 +1,97 @@
+import { useLayoutEffect, useRef } from 'react';
+import type { MutableRefObject, RefObject } from 'react';
+import { isSameCell } from '../../utils/focus';
+import type { FocusedCell } from '../../utils/focus';
+import { isRangeColumnField, isSameCoordinates } from '../../utils/cellSelection';
+import { writeToClipboard } from '../features/useGridClipboard';
+import type { UseGridCellSelectionReturn } from './useGridCellSelection';
+import type { GridApi, GridCellCoordinates, GridCellSelectionModel } from '../../types';
+
+export interface UseGridCellSelectionApiParams {
+    apiRef: MutableRefObject<GridApi>;
+    selection: UseGridCellSelectionReturn;
+    /** The rendered model (controlled or internal). */
+    model: GridCellSelectionModel;
+    getPendingModel: () => GridCellSelectionModel | null;
+    focusedCell: FocusedCell | null;
+    setFocusedCell: React.Dispatch<React.SetStateAction<FocusedCell | null>>;
+    /** The grid root: its `ogx--kb` class tells a keyboard focus move from a pointer one. */
+    containerRef: RefObject<HTMLDivElement | null>;
+}
+
+/**
+ * Runs after useGridKeyboardNavigation. Keeps the range's anchor and the focused cell together:
+ * a new anchor (pointer, keyboard, API or a controlled model) moves focus there, and focus moved
+ * to another data cell (plain arrows, Tab back in) collapses the range to it. Clears a range whose
+ * corner is no longer displayed (`reason: 'dataChange'`). Installs the cell selection API methods.
+ */
+export function useGridCellSelectionApi(params: UseGridCellSelectionApiParams): void {
+    const { apiRef } = params;
+    const latestRef = useRef(params);
+    useLayoutEffect(() => {
+        latestRef.current = params;
+    });
+
+    const previousAnchorRef = useRef<GridCellCoordinates | null>(null);
+    const previousFocusRef = useRef<FocusedCell | null>(null);
+    const reportedDataChangeRef = useRef<GridCellSelectionModel | null>(null);
+
+    const { selection, model, focusedCell, setFocusedCell, containerRef } = params;
+    const anchor = selection.range?.anchor ?? null;
+    const anchorRow = selection.resolved?.anchorRow;
+
+    useLayoutEffect(() => {
+        selection.reportFocus(focusedCell);
+        const anchorChanged = !isSameCoordinates(previousAnchorRef.current, anchor);
+        const focusChanged = !isSameCell(previousFocusRef.current, focusedCell);
+        previousAnchorRef.current = anchor;
+        previousFocusRef.current = focusedCell;
+        if (!selection.enabled) return;
+
+        if (selection.range && !selection.resolved) {
+            // A corner's row or column is no longer displayed. Reported once per model.
+            if (reportedDataChangeRef.current !== model) {
+                reportedDataChangeRef.current = model;
+                selection.setModel([], 'dataChange');
+            }
+            return;
+        }
+        if (anchorChanged && anchor) {
+            if (!focusedCell || focusedCell.id !== anchor.id || focusedCell.field !== anchor.field) {
+                setFocusedCell({ id: anchor.id, field: anchor.field, rowIndex: anchorRow });
+            }
+            return;
+        }
+        if (focusChanged && focusedCell && focusedCell.id !== null && isRangeColumnField(focusedCell.field)
+            && !isSameCoordinates(anchor, { id: focusedCell.id, field: focusedCell.field })) {
+            const cell = { id: focusedCell.id, field: focusedCell.field };
+            const byKeyboard = containerRef.current?.classList.contains('ogx--kb') ?? false;
+            selection.setModel([{ anchor: cell, head: cell }], byKeyboard ? 'keyboard' : 'pointer');
+        }
+    }, [selection, model, anchor, anchorRow, focusedCell, setFocusedCell, containerRef]);
+
+    useLayoutEffect(() => {
+        const api = apiRef.current;
+        const current = () => latestRef.current;
+        api.getCellSelectionModel = () => {
+            const { selection: s, getPendingModel, model: rendered } = current();
+            return s.enabled ? (getPendingModel() ?? rendered) : [];
+        };
+        api.setCellSelectionModel = (next) => {
+            current().selection.setModel(next, 'api');
+        };
+        api.selectCellRange = (rangeAnchor, head) => {
+            current().selection.setModel([{ anchor: rangeAnchor, head }], 'api');
+        };
+        api.clearCellSelection = () => {
+            current().selection.setModel([], 'clear');
+        };
+        api.getSelectedCells = () => current().selection.getSelectedCells();
+        api.copySelectedCells = async () => {
+            const { selection: s } = current();
+            if (!s.enabled) return;
+            const text = s.getCopyText();
+            if (text !== null) await writeToClipboard(text);
+        };
+    }, [apiRef]);
+}

package/lib/hooks/core/useGridClipboardApi.ts

@@ -11,15 +11,20 @@ export interface UseGridClipboardApiParams {
     /** The grid root: Ctrl/Cmd+C only copies while focus is inside it. */
     containerRef: RefObject<HTMLDivElement | null>;
     disableKeyboardShortcut: boolean;
+    /**
+     * Cell range selection: the text Ctrl/Cmd+C copies instead of the selected rows (`null`: nothing).
+     * Absent while `cellSelection` is off, so the shortcut copies rows.
+     */
+    getCellRangeCopyText?: () => string | null;
 }
 
 /**
  * Copies the selected rows (every page, collapsed groups, pinned rows) with the on-screen columns
  * in screen order, on Ctrl/Cmd+C while focus is inside this grid, and installs `copySelectedRows`
- * on the API for programmatic use.
+ * on the API for programmatic use. With `cellSelection` on, the shortcut copies the cell range instead.
  */
 export function useGridClipboardApi(params: UseGridClipboardApiParams): void {
-    const { apiRef, columns, getRowId, containerRef, disableKeyboardShortcut } = params;
+    const { apiRef, columns, getRowId, containerRef, disableKeyboardShortcut, getCellRangeCopyText } = params;
 
     const getGridRootElement = useCallback(() => containerRef.current, [containerRef]);
     const { copySelectedRows } = useGridClipboard({
@@ -29,6 +34,7 @@ export function useGridClipboardApi(params: UseGridClipboardApiParams): void {
         getRowId,
         getRootElement: getGridRootElement,
         disableKeyboardShortcut,
+        getShortcutText: getCellRangeCopyText,
     });
 
     // Stable identity.

package/lib/hooks/core/useGridControlledState.ts

@@ -7,6 +7,9 @@ import type {
     GridPaginationModel,
     GridAggregationModel,
     GridPivotModel,
+    GridCellSelectionModel,
+    GridCellSelectionChangeDetails,
+    GridCellSelectionReason,
 } from '../../types';
 import type { GridInitialState, GridDensityState } from '../../state/types';
 
@@ -42,6 +45,9 @@ export interface UseGridControlledStateParams {
     onRowSelectionModelChange?: (model: GridRowId[]) => void;
 
     density?: GridDensity;
+
+    cellSelectionModel?: GridCellSelectionModel;
+    onCellSelectionModelChange?: (model: GridCellSelectionModel, details: GridCellSelectionChangeDetails) => void;
 }
 
 export interface UseGridControlledStateReturn {
@@ -94,8 +100,17 @@ export interface UseGridControlledStateReturn {
 
     // density (prop, else initialState.density, else 'standard')
     density: GridDensity;
+
+    // cell selection
+    cellSelectionModel: GridCellSelectionModel;
+    /** Sets the internal model when uncontrolled and fires onCellSelectionModelChange. */
+    handleCellSelectionModelChange: (model: GridCellSelectionModel, reason: GridCellSelectionReason) => void;
+    /** Like `getPendingRowSelectionModel`, for the cell selection. Stable identity. */
+    getPendingCellSelectionModel: () => GridCellSelectionModel | null;
 }
 
+const EMPTY_CELL_SELECTION_MODEL: GridCellSelectionModel = [];
+
 const EMPTY_PIVOT_MODEL: GridPivotModel = { rowFields: [], columnFields: [], valueFields: [] };
 const DEFAULT_PAGE_SIZE = 100;
 
@@ -128,6 +143,8 @@ export function useGridControlledState(params: UseGridControlledStateParams): Us
         rowSelectionModel: propRowSelectionModel,
         onRowSelectionModelChange,
         density: propDensity,
+        cellSelectionModel: propCellSelectionModel,
+        onCellSelectionModelChange,
     } = params;
 
     // ── Sort ─────────────────────────────────────────────────────────────────
@@ -248,6 +265,23 @@ export function useGridControlledState(params: UseGridControlledStateParams): Us
     const [initialDensity] = useState<GridDensity>(() => initialState?.density?.density ?? 'standard');
     const density = propDensity ?? initialDensity;
 
+    // ── Cell selection ───────────────────────────────────────────────────────
+    const isCellSelectionControlled = propCellSelectionModel !== undefined;
+    const [internalCellSelectionModel, setInternalCellSelectionModel] = useState<GridCellSelectionModel>(EMPTY_CELL_SELECTION_MODEL);
+    const cellSelectionModel = isCellSelectionControlled ? propCellSelectionModel : internalCellSelectionModel;
+
+    const pendingCellSelectionRef = useRef<GridCellSelectionModel | null>(null);
+    useLayoutEffect(() => {
+        pendingCellSelectionRef.current = null;
+    });
+    const getPendingCellSelectionModel = useCallback(() => pendingCellSelectionRef.current, []);
+
+    const handleCellSelectionModelChange = useCallback((model: GridCellSelectionModel, reason: GridCellSelectionReason) => {
+        pendingCellSelectionRef.current = model;
+        if (!isCellSelectionControlled) setInternalCellSelectionModel(model);
+        onCellSelectionModelChange?.(model, { reason });
+    }, [isCellSelectionControlled, onCellSelectionModelChange]);
+
     return {
         sortModel: sortModel as GridSortItem[],
         isSortControlled,
@@ -281,5 +315,9 @@ export function useGridControlledState(params: UseGridControlledStateParams): Us
         getPendingRowSelectionModel,
 
         density,
+
+        cellSelectionModel,
+        handleCellSelectionModelChange,
+        getPendingCellSelectionModel,
     };
 }

package/lib/hooks/core/useGridKeyboardNavigation.ts

@@ -14,6 +14,7 @@ import {
     isSystemField,
 } from '../../utils/focus';
 import type { FocusedCell } from '../../utils/focus';
+import { isRangeColumnField } from '../../utils/cellSelection';
 import type { GridRowModel, GridRowId, GridColDef, GridCellParams, GridSortItem, GridSortDirection, GridRowParams, GridRowMeta } from '../../types';
 import type { GridEditingState } from '../features/useGridEditing';
 
@@ -93,6 +94,21 @@ export interface UseGridKeyboardNavigationParams<R extends GridRowModel> {
      * Navigation skips the cells of the focused span and lands on span origins.
      */
     getSpanOrigin?: (rowId: GridRowId, field: string) => { rowId: GridRowId; field: string } | null;
+    /**
+     * Cell range selection (`cellSelection`), absent while it is off. Shift+navigation keys on a
+     * data cell move the range's head (focus stays on the anchor), Escape collapses the range and
+     * Ctrl/Cmd+A selects every data cell instead of every row.
+     */
+    cellSelection?: GridKeyboardCellSelection;
+}
+
+export interface GridKeyboardCellSelection {
+    /** Returns whether the key was used. */
+    extendSelection: (key: string, withModifier: boolean, pageSize: number, from: FocusedCell) => boolean;
+    /** Returns whether a multi-cell range was collapsed. */
+    collapseSelection: () => boolean;
+    /** Returns whether anything was selected. */
+    selectAllCells: () => boolean;
 }
 
 export interface UseGridKeyboardNavigationReturn {
@@ -170,6 +186,7 @@ export function useGridKeyboardNavigation<R extends GridRowModel>(
         pinExpandColumn = true,
         rowHeight,
         getSpanOrigin,
+        cellSelection,
     } = params;
 
     const [storedFocus, setFocusedCell] = useState<FocusedCell | null>(null);
@@ -419,11 +436,19 @@ export function useGridKeyboardNavigation<R extends GridRowModel>(
 
         // Tab is not captured outside edit mode: the grid is a single tab stop and Tab leaves it
         // (or reaches focusable content inside cells and detail panels).
+        if (key === 'Escape' && cellSelection?.collapseSelection()) {
+            event.preventDefault();
+            return;
+        }
         if (key === 'Tab' || key === 'Escape') return;
         // Enter and Space activate a control rendered inside a cell.
         if (targetKind === 'control' && (key === 'Enter' || isSpace)) return;
 
         if ((event.ctrlKey || event.metaKey) && (key === 'a' || key === 'A')) {
+            if (cellSelection) {
+                if (cellSelection.selectAllCells()) event.preventDefault();
+                return;
+            }
             if (!rowSelectionEnabled || !multipleRowSelectionEnabled || !handleSelectAll) return;
             event.preventDefault();
             handleSelectAll(true);
@@ -496,6 +521,12 @@ export function useGridKeyboardNavigation<R extends GridRowModel>(
         const withModifier = event.ctrlKey || event.metaKey;
         const page = pagination ? pageSize : 10;
 
+        // Shift+navigation on a data cell extends the cell range; focus stays on its anchor.
+        if (cellSelection && event.shiftKey && id !== null && isRangeColumnField(field)
+            && cellSelection.extendSelection(key, withModifier, page, focusedCell)) {
+            return;
+        }
+
         const step = (r: number, c: number): { r: number; c: number } => {
             switch (key) {
                 case 'ArrowRight': return c + 1 > lastCol ? { r: r + 1, c: 0 } : { r, c: c + 1 };
@@ -558,6 +589,7 @@ export function useGridKeyboardNavigation<R extends GridRowModel>(
         scrollCellIntoView,
         getSpanOrigin,
         getRowId,
+        cellSelection,
     ]);
 
     return {

package/lib/hooks/core/useGridRowInteractions.ts

@@ -51,6 +51,10 @@ export function useGridRowInteractions<R extends GridRowModel>(
         selectableRowIds,
     });
 
+    // Depend on the selection callbacks, not the object around them (a new one each render), so the
+    // handlers keep their identity and memoised rows do not re-render.
+    const { clickRow, toggleRow } = rowSelection;
+
     const handleRowClick = useCallback((rowParams: GridRowParams<R>) => {
         const { id } = rowParams;
 
@@ -66,16 +70,16 @@ export function useGridRowInteractions<R extends GridRowModel>(
 
         // The pivot Grand Total is clickable (onRowClick) but, like any synthetic row, not selectable.
         if (!disableRowSelectionOnClick && !isSyntheticRowId(id, rowMetaMap)) {
-            rowSelection.clickRow(id);
+            clickRow(id);
         }
-    }, [isHierarchyEnabled, activeHierarchyHandlers, onRowClick, rowMetaMap, disableRowSelectionOnClick, rowSelection]);
+    }, [isHierarchyEnabled, activeHierarchyHandlers, onRowClick, rowMetaMap, disableRowSelectionOnClick, clickRow]);
 
     // Honors disableMultipleRowSelection like a row click does. Synthetic group / subtotal rows
     // and the pivot Grand Total are not data: their ids never enter the selection model.
     const handleSelectionChange = useCallback((rowId: GridRowId, isSelected: boolean) => {
         if (isSyntheticRowId(rowId, rowMetaMap)) return;
-        rowSelection.toggleRow(rowId, isSelected);
-    }, [rowMetaMap, rowSelection]);
+        toggleRow(rowId, isSelected);
+    }, [rowMetaMap, toggleRow]);
 
     return { rowSelection, handleRowClick, handleSelectionChange };
 }

package/lib/hooks/core/useGridThemeDimensions.ts

@@ -10,7 +10,7 @@ const COMFORTABLE_ROW_HEIGHT = 72;
 /** A theme height in pixels (`'36px'` or `'36'`); anything else (rem, calc, …) is ignored. */
 export function parseThemePixels(value: string | undefined): number | undefined {
     if (value === undefined) return undefined;
-    const match = /^\s*(\d+(?:\.\d+)?)\s*(px)?\s*$/.exec(value);
+    const match = /^(\d+(?:\.\d+)?)(?:\s*px)?$/.exec(value.trim());
     if (!match) return undefined;
     const px = Number(match[1]);
     return px > 0 ? px : undefined;

package/lib/hooks/features/useAggregation.ts

@@ -108,14 +108,16 @@ export function useAggregation<R extends GridRowModel>(
 
         let cancelled = false;
         const request = latestRequestRef.current;
+        // Built outside the try: React Compiler cannot compile `??` inside a try statement yet.
+        const query = {
+            sortModel: request.sortModel ?? [],
+            filterModel: request.filterModel ?? { items: [] },
+            groupKeys: [],
+            aggregationModel: request.aggregationModel,
+        };
         let pending: Promise<GridAggregationResult>;
         try {
-            pending = Promise.resolve(getAggregations({
-                sortModel: request.sortModel ?? [],
-                filterModel: request.filterModel ?? { items: [] },
-                groupKeys: [],
-                aggregationModel: request.aggregationModel,
-            }));
+            pending = Promise.resolve(getAggregations(query));
         } catch (err) {
             pending = Promise.reject(err);
         }

package/lib/hooks/features/useGridClipboard.ts

@@ -27,6 +27,11 @@ export interface UseGridClipboardProps {
   getRootElement?: () => HTMLElement | null;
   /** Turns the Ctrl/Cmd+C shortcut off. `copySelectedRows` still works. */
   disableKeyboardShortcut?: boolean;
+  /**
+   * When given, Ctrl/Cmd+C writes the text it returns instead of copying the selected rows, and
+   * writes nothing when it returns `null` (cell range selection).
+   */
+  getShortcutText?: () => string | null;
 }
 
 /** Grid-made columns that never hold row data. */
@@ -58,6 +63,39 @@ export function buildClipboardTsv(rows: GridRowModel[], columns: GridColDef[]):
   return [header, ...lines].join('\n');
 }
 
+/** A cell value formatted the way the cell shows it; a valueFormatter that throws gives the raw text. */
+function formatCopyValue(row: GridRowModel, col: GridColDef): string {
+  const value = getCellValue(row, col.field, col);
+  try {
+    return formatExportValue(row, col, value);
+  } catch {
+    return value == null ? '' : String(value);
+  }
+}
+
+/**
+ * A cell range as Excel and Google Sheets copy it: tabs between columns, line breaks between rows and
+ * no header line. `rows` are the data rows of the range (synthetic rows already left out); a position
+ * for which `isCovered` returns true (covered by a span whose origin sits elsewhere) is left empty.
+ */
+export function buildRangeTsv(
+  rows: readonly GridRowModel[],
+  columns: readonly GridColDef[],
+  isCovered?: (row: GridRowModel, col: GridColDef) => boolean,
+): string {
+  const lines: string[] = new Array(rows.length);
+  for (let r = 0; r < rows.length; r++) {
+    const row = rows[r];
+    const cells: string[] = new Array(columns.length);
+    for (let c = 0; c < columns.length; c++) {
+      const col = columns[c];
+      cells[c] = isCovered?.(row, col) ? '' : escapeTsvField(formatCopyValue(row, col));
+    }
+    lines[r] = cells.join('\t');
+  }
+  return lines.join('\n');
+}
+
 /**
  * The textarea + execCommand fallback, for browsers without the async Clipboard API (plain http)
  * or when it rejects. It has to focus the textarea, so focus and the page selection are put back
@@ -98,7 +136,7 @@ function copyTextSynchronous(text: string): boolean {
  * Writes text to the clipboard: the async Clipboard API when there is one, the execCommand
  * fallback when it is missing or rejects. Rejects when neither worked.
  */
-async function writeToClipboard(text: string): Promise<void> {
+export async function writeToClipboard(text: string): Promise<void> {
   const clipboard = typeof navigator !== 'undefined' ? navigator.clipboard : undefined;
   if (clipboard && typeof clipboard.writeText === 'function') {
     try {
@@ -180,7 +218,14 @@ export function useGridClipboard(props: UseGridClipboardProps) {
       const selection = window.getSelection();
       if (selection && !selection.isCollapsed && selection.toString() !== '') return;
 
-      copySelectedRows().catch((err: unknown) => {
+      const { getShortcutText } = latestRef.current;
+      const copy = getShortcutText
+        ? () => {
+          const text = getShortcutText();
+          return text === null ? Promise.resolve() : writeToClipboard(text);
+        }
+        : copySelectedRows;
+      copy().catch((err: unknown) => {
         console.error('[OpenGridX] Failed to copy to clipboard:', err);
       });
     };

package/lib/hooks/features/useGridEditing.ts

@@ -1,5 +1,6 @@
 import { useState, useCallback, useRef, useEffect, useLayoutEffect, useMemo } from 'react';
 import type { GridColDef, GridRowId, GridRowModel } from '../../types';
+import { attempt } from '../../utils/attempt';
 
 export interface GridEditingState {
     editingCell: {
@@ -95,6 +96,10 @@ export function useGridEditing<R extends GridRowModel>(params: UseGridEditingPar
         setEditingCellState(next);
     }, []);
 
+    // The in-flight branch below re-runs the commit through this ref: a callback that refers to
+    // itself is read before its declaration, which React Compiler rejects.
+    const commitRef = useRef<((token: number, cell: EditingCell) => Promise<void>) | null>(null);
+
     const commit = useCallback((token: number, cell: EditingCell): Promise<void> => {
         const inFlight = pendingRef.current.get(token);
         if (inFlight) {
@@ -103,7 +108,7 @@ export function useGridEditing<R extends GridRowModel>(params: UseGridEditingPar
             return inFlight.promise.then(() => {
                 const now = editingCellRef.current;
                 if (sessionRef.current !== token || !now || isSameValue(now.value, inFlight.value)) return;
-                return commit(token, now);
+                return commitRef.current?.(token, now);
             });
         }
 
@@ -159,18 +164,19 @@ export function useGridEditing<R extends GridRowModel>(params: UseGridEditingPar
             if (pendingRef.current.get(token) === entry) pendingRef.current.delete(token);
         };
 
-        let result: unknown;
-        try {
-            const colDef = columns?.find(c => c.field === cell.field);
+        const colDef = columns?.find(c => c.field === cell.field);
+        const outcome = attempt<unknown>(() => {
             const newRow = buildEditedRow(existingRow, cell, colDef, warnedFieldsRef.current);
-            result = processRowUpdate ? processRowUpdate(newRow, existingRow) : newRow;
-        } catch (error) {
+            return processRowUpdate ? processRowUpdate(newRow, existingRow) : newRow;
+        });
+        if (!outcome.ok) {
             // Consumer code (valueSetter / processRowUpdate) threw: report it, keep the editor open.
             finish();
-            report(error);
+            report(outcome.error);
             settle();
             return promise;
         }
+        const result = outcome.value;
 
         const complete = (processed: unknown) => {
             finish();
@@ -194,6 +200,9 @@ export function useGridEditing<R extends GridRowModel>(params: UseGridEditingPar
         }
         return promise;
     }, [setEditingCell]);
+    useLayoutEffect(() => {
+        commitRef.current = commit;
+    }, [commit]);
 
     const startCellEdit = useCallback((editParams: { id: GridRowId; field: string; value: unknown }) => {
         const current = editingCellRef.current;

package/lib/index.ts

@@ -21,6 +21,8 @@ export type { GridToolbarProps, ToolbarButtonRenderProps, ToolbarQuickFilterRend
 export { GridTooltip } from './components/Tooltip/Tooltip';
 export type { GridTooltipProps } from './components/Tooltip/Tooltip';
 export { ColumnVisibilityPanel } from './components/ColumnVisibilityPanel/ColumnVisibilityPanel';
+export { CellSelectionStats } from './components/CellSelectionStats/CellSelectionStats';
+export type { CellSelectionStatsProps } from './components/CellSelectionStats/CellSelectionStats';
 export type { ColumnVisibilityPanelProps } from './components/ColumnVisibilityPanel/ColumnVisibilityPanel';
 
 export { useGridApiRef } from './hooks/core/useGridApiRef';
@@ -99,6 +101,13 @@ export type {
     GridPinnedPosition,
     GridColumnVisibilityModel,
     GridRowSelectionModel,
+    GridCellCoordinates,
+    GridCellRange,
+    GridCellSelectionModel,
+    GridCellSelectionReason,
+    GridCellSelectionChangeDetails,
+    GridSelectedCell,
+    GridCellSelectionStatsSlotProps,
     GridColumnOrder,
     GridColumnOrderChangeParams,
     GridRowOrderChangeParams,

package/lib/styles/base/variables.css

@@ -93,7 +93,10 @@
   --ogx-grid-row-selected-background: var(--ogx-color-primary-light);
   --ogx-grid-row-selected-hover-background: #dbeafe; 
   --ogx-grid-cell-focus-border: var(--ogx-color-primary);
-  --ogx-grid-pinned-left-shadow: 4px 0 24px -4px rgba(0, 0, 0, 0.05); 
+  /* Cell range selection (cellSelection, v3.3): tint over the range and its outline. */
+  --ogx-range-background: rgba(59, 130, 246, 0.12);
+  --ogx-range-border: var(--ogx-color-primary);
+  --ogx-grid-pinned-left-shadow: 4px 0 24px -4px rgba(0, 0, 0, 0.05);
   --ogx-grid-pinned-right-shadow: -4px 0 24px -4px rgba(0, 0, 0, 0.05);
   --ogx-skeleton-base: #f0f0f0;
   --ogx-skeleton-highlight: #f8f8f8;
@@ -142,6 +145,8 @@
     --ogx-grid-row-selected-background: #1e3a5f;
     --ogx-grid-row-selected-hover-background: #1d4ed8;
     --ogx-grid-cell-focus-border: #60a5fa;
+    --ogx-range-background: rgba(96, 165, 250, 0.18);
+    --ogx-range-border: #60a5fa;
     --ogx-checkbox-bg: #1e293b;
     --ogx-checkbox-border: #64748b;
     --ogx-grid-pinned-left-shadow: 4px 0 24px -4px rgba(0, 0, 0, 0.3);

package/lib/styles/opengridx.css

@@ -25,3 +25,4 @@
 @import '../components/ListView/ListView.css';
 @import '../components/ColumnGroupHeader/ColumnGroupHeader.css';
 @import '../components/Tooltip/Tooltip.css';
+@import '../components/CellSelectionStats/CellSelectionStats.css';

package/lib/theme/DataGridThemeProvider.tsx

@@ -9,6 +9,8 @@ const primaryDerived: Record<string, string> = {
     '--ogx-grid-row-selected-background': 'var(--ogx-color-primary-light)',
     '--ogx-grid-row-selected-hover-background': 'color-mix(in srgb, var(--ogx-color-primary) 14%, var(--ogx-color-primary-light))',
     '--ogx-grid-cell-focus-border': 'var(--ogx-color-primary)',
+    '--ogx-range-background': 'color-mix(in srgb, var(--ogx-color-primary) 12%, transparent)',
+    '--ogx-range-border': 'var(--ogx-color-primary)',
     '--ogx-toolbar-btn-primary-bg': 'var(--ogx-color-primary)',
     '--ogx-toolbar-btn-primary-hover': 'var(--ogx-color-primary-dark)',
     '--ogx-toolbar-input-focus-border': 'var(--ogx-color-primary)',
@@ -281,6 +283,8 @@ function themeToCSS(theme: GridTheme): Record<string, string> {
         set('--ogx-grid-row-selected-background', g.rowSelectedBackground);
         set('--ogx-grid-row-selected-hover-background', g.rowSelectedHoverBackground);
         set('--ogx-grid-cell-focus-border', g.cellFocusBorder);
+        set('--ogx-range-background', g.rangeBackground);
+        set('--ogx-range-border', g.rangeBorder);
         set('--ogx-grid-pinned-left-shadow', g.pinnedLeftShadow);
         set('--ogx-grid-pinned-right-shadow', g.pinnedRightShadow);
         set('--ogx-checkbox-bg', g.checkboxBg);

package/lib/theme/presets.ts

@@ -21,6 +21,8 @@ export const darkTheme: GridTheme = {
     rowSelectedBackground: '#1e3a5f',  
     rowSelectedHoverBackground: '#1d4ed8', 
     cellFocusBorder: '#60a5fa',
+    rangeBackground: 'rgba(96, 165, 250, 0.18)',
+    rangeBorder: '#60a5fa',
     checkboxBg: '#1e293b',            
     checkboxBorder: '#64748b',         
   },
@@ -92,6 +94,8 @@ export const roseTheme: GridTheme = {
     rowSelectedBackground: '#ffe4e6',
     rowSelectedHoverBackground: '#fecdd3',
     cellFocusBorder: '#e11d48',
+    rangeBackground: 'rgba(225, 29, 72, 0.10)',
+    rangeBorder: '#e11d48',
   },
 };
 
@@ -110,6 +114,8 @@ export const emeraldTheme: GridTheme = {
     rowSelectedBackground: '#d1fae5',
     rowSelectedHoverBackground: '#a7f3d0',
     cellFocusBorder: '#059669',
+    rangeBackground: 'rgba(5, 150, 105, 0.12)',
+    rangeBorder: '#059669',
   },
 };
 
@@ -128,6 +134,8 @@ export const amberTheme: GridTheme = {
     rowSelectedBackground: '#fef3c7',
     rowSelectedHoverBackground: '#fde68a',
     cellFocusBorder: '#d97706',
+    rangeBackground: 'rgba(217, 119, 6, 0.12)',
+    rangeBorder: '#d97706',
   },
 };
 

package/lib/theme/types.ts

@@ -159,6 +159,10 @@ export 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;