@opencorestack/opengridx 3.2.2 → 3.4.0

package/lib/hooks/core/useGridUndoRedo.ts

@@ -0,0 +1,220 @@
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef } from 'react';
+import type { MutableRefObject, RefObject } from 'react';
+import type {
+    GridApi,
+    GridBatchEditResult,
+    GridColDef,
+    GridHistoryChangeParams,
+    GridRowId,
+    GridRowModel,
+} from '../../types';
+import { classifyKeyTarget } from '../../utils/focus';
+import type { FocusedCell } from '../../utils/focus';
+import { scrollColumnIntoView, scrollRowIntoView } from '../../utils/scroll';
+import { boundingTargetRect, buildEditTargetContext, rectCorners } from '../../utils/editing/targets';
+import type { GridCellChange } from '../../utils/editing/commit';
+import type { GridEditSource, UseGridBatchEditReturn } from '../features/useGridBatchEdit';
+import type { UseGridCellSelectionReturn } from './useGridCellSelection';
+import type { LayoutResult } from './useLayout';
+
+/** Default number of actions `undoRedo` keeps. */
+export const UNDO_HISTORY_LIMIT = 100;
+
+type CommitListener = (changes: GridCellChange[], source: GridEditSource) => void;
+
+export interface GridEditCommitChannel {
+    /** Passed to the commit paths (`useGridEditing`, `useGridBatchEdit`) as `onCommitted`. Stable. */
+    emit: CommitListener;
+    /** Set by `useGridUndoRedo`, which runs later in the hook order. Stable. */
+    setListener: (listener: CommitListener | null) => void;
+}
+
+/**
+ * Connects the commit paths, which run early in the hook order, to the history, which runs late
+ * (it needs the focus and selection hooks). Created before `useGridBatchEdit`.
+ */
+export function useGridEditCommitChannel(): GridEditCommitChannel {
+    const listenerRef = useRef<CommitListener | null>(null);
+    const emit = useCallback<CommitListener>((changes, source) => {
+        const listener = listenerRef.current;
+        if (listener) listener(changes, source);
+    }, []);
+    const setListener = useCallback((listener: CommitListener | null) => {
+        listenerRef.current = listener;
+    }, []);
+    return useMemo(() => ({ emit, setListener }), [emit, setListener]);
+}
+
+export interface UseGridUndoRedoParams<R extends GridRowModel> {
+    apiRef: MutableRefObject<GridApi>;
+    enabled: boolean;
+    limit: number;
+    onHistoryChange?: (params: GridHistoryChangeParams) => void;
+    channel: GridEditCommitChannel;
+    batchEdit: UseGridBatchEditReturn<R>;
+    isEditing: boolean;
+    containerRef: RefObject<HTMLDivElement | null>;
+    viewportRef: RefObject<HTMLDivElement | null>;
+    selection: UseGridCellSelectionReturn;
+    setFocusedCell: React.Dispatch<React.SetStateAction<FocusedCell | null>>;
+    allRenderableRows: R[];
+    getRowId: (row: R) => GridRowId;
+    navigationColumns: ReadonlyArray<GridColDef<R>>;
+    layout: LayoutResult<R>;
+    rowHeight: number;
+    pinnedTopRowCount: number;
+}
+
+const emptyResult = (): GridBatchEditResult => ({ updated: [], failed: [], skipped: [] });
+
+/** 'undo', 'redo' or null for a keydown. Ctrl/Cmd+Z, Ctrl/Cmd+Shift+Z, Ctrl+Y (also on non-Latin layouts). */
+function historyShortcut(event: KeyboardEvent): 'undo' | 'redo' | null {
+    if (event.altKey || !(event.ctrlKey || event.metaKey)) return null;
+    const key = (event.key ?? '').toLowerCase();
+    const latin = /^[a-z]$/.test(key);
+    const isZ = key === 'z' || (!latin && event.code === 'KeyZ');
+    const isY = key === 'y' || (!latin && event.code === 'KeyY');
+    if (isZ) return event.shiftKey ? 'redo' : 'undo';
+    if (isY && event.ctrlKey && !event.shiftKey) return 'redo';
+    return null;
+}
+
+/**
+ * Undo / redo of cell edits, pastes and range clears (`undoRedo`, v3.4). An action is recorded only
+ * after `processRowUpdate` succeeded, as the changed cells with their value before and the stored
+ * value after. Undo writes the `before` values as a batch edit (so `valueSetter` and
+ * `processRowUpdate` run); a cell that no longer holds its `after` value is skipped (`'changed'`), a
+ * row that is gone too (`'missing'`). Redo is the reverse. Runs after useGridClipboardPaste.
+ */
+export function useGridUndoRedo<R extends GridRowModel>(params: UseGridUndoRedoParams<R>): void {
+    const { apiRef, enabled, channel, containerRef } = params;
+    const latestRef = useRef(params);
+    useLayoutEffect(() => {
+        latestRef.current = params;
+    });
+
+    const undoStackRef = useRef<GridCellChange[][]>([]);
+    const redoStackRef = useRef<GridCellChange[][]>([]);
+    const lastEmittedRef = useRef<GridHistoryChangeParams>({ canUndo: false, canRedo: false, size: 0 });
+    // Undo and redo run one after the other, each on the rows the previous one stored.
+    const queueRef = useRef<Promise<unknown>>(Promise.resolve());
+
+    const notify = useCallback(() => {
+        const next = {
+            canUndo: undoStackRef.current.length > 0,
+            canRedo: redoStackRef.current.length > 0,
+            size: undoStackRef.current.length,
+        };
+        const last = lastEmittedRef.current;
+        if (last.canUndo === next.canUndo && last.canRedo === next.canRedo && last.size === next.size) return;
+        lastEmittedRef.current = next;
+        latestRef.current.onHistoryChange?.(next);
+    }, []);
+
+    const record = useCallback((changes: GridCellChange[]) => {
+        if (!latestRef.current.enabled || changes.length === 0) return;
+        const stack = undoStackRef.current;
+        stack.push(changes);
+        const limit = Math.max(1, latestRef.current.limit);
+        if (stack.length > limit) stack.splice(0, stack.length - limit);
+        redoStackRef.current = [];
+        notify();
+    }, [notify]);
+
+    useLayoutEffect(() => {
+        channel.setListener(enabled ? record : null);
+        return () => channel.setListener(null);
+    }, [channel, enabled, record]);
+
+    const clearHistory = useCallback(() => {
+        undoStackRef.current = [];
+        redoStackRef.current = [];
+        notify();
+    }, [notify]);
+
+    // Turning undoRedo off forgets the history.
+    useEffect(() => {
+        if (!enabled) clearHistory();
+    }, [enabled, clearHistory]);
+
+    /** Selects the affected cells (their bounding rectangle) and scrolls its first cell into view. */
+    const reveal = useCallback((cells: GridCellChange[]) => {
+        const p = latestRef.current;
+        const ctx = buildEditTargetContext(p.allRenderableRows, p.getRowId, p.navigationColumns);
+        const rect = boundingTargetRect(ctx, cells);
+        if (!rect) return;
+        const { anchor, head } = rectCorners(ctx, rect);
+        if (p.selection.enabled) p.selection.setModel([{ anchor, head }], 'keyboard');
+        else p.setFocusedCell({ id: anchor.id, field: anchor.field, rowIndex: rect.top });
+        const viewport = p.viewportRef.current;
+        if (!viewport) return;
+        scrollRowIntoView(viewport, rect.top - p.pinnedTopRowCount, p.layout.cumulativeHeights, p.layout.pinnedBottomHeight, p.rowHeight);
+        scrollColumnIntoView(viewport, p.layout.unpinnedColsWithWidth.findIndex(c => c.field === anchor.field), p.layout);
+    }, []);
+
+    /** Replays the top action of one stack onto the other. */
+    const replay = useCallback((direction: 'undo' | 'redo'): Promise<GridBatchEditResult> => {
+        const run = async (): Promise<GridBatchEditResult> => {
+            if (!latestRef.current.enabled) return emptyResult();
+            const from = direction === 'undo' ? undoStackRef : redoStackRef;
+            const to = direction === 'undo' ? redoStackRef : undoStackRef;
+            const action = from.current.pop();
+            if (!action) return emptyResult();
+            notify();
+            // Undo writes `before` where `after` still holds; redo writes `after` where `before` holds.
+            const edits = action.map(change => direction === 'undo'
+                ? { id: change.id, field: change.field, value: change.before, expect: { value: change.after } }
+                : { id: change.id, field: change.field, value: change.after, expect: { value: change.before } });
+            const outcome = await latestRef.current.batchEdit.applyEdits(edits, direction);
+            if (outcome.committed.length > 0) {
+                // The opposite action: for an undo, `before` is what it stored and `after` what it replaced.
+                to.current.push(direction === 'undo'
+                    ? outcome.committed.map(c => ({ id: c.id, field: c.field, before: c.after, after: c.before }))
+                    : outcome.committed);
+            }
+            // Rows whose processRowUpdate failed keep their part of the action, to try again.
+            const failedIds = new Set<GridRowId>(outcome.result.failed.map(f => f.id));
+            if (failedIds.size > 0) {
+                const remainder = action.filter(change => failedIds.has(change.id));
+                if (remainder.length > 0) from.current.push(remainder);
+            }
+            notify();
+            if (outcome.committed.length > 0) reveal(outcome.committed);
+            return outcome.result;
+        };
+        const next = queueRef.current.then(run, run);
+        queueRef.current = next;
+        return next;
+    }, [notify, reveal]);
+
+    const undo = useCallback(() => replay('undo'), [replay]);
+    const redo = useCallback(() => replay('redo'), [replay]);
+
+    useEffect(() => {
+        const root = containerRef.current;
+        if (!root || !enabled) return;
+        const onKeyDown = (event: KeyboardEvent) => {
+            if (event.defaultPrevented) return;
+            const shortcut = historyShortcut(event);
+            if (!shortcut) return;
+            const viewport = latestRef.current.viewportRef.current;
+            if (!viewport || latestRef.current.isEditing) return;
+            // Inside an editor or a text field the input's own undo wins.
+            const kind = classifyKeyTarget(event.target, viewport);
+            if (kind !== 'grid' && kind !== 'control') return;
+            event.preventDefault();
+            void (shortcut === 'undo' ? undo() : redo());
+        };
+        root.addEventListener('keydown', onKeyDown);
+        return () => root.removeEventListener('keydown', onKeyDown);
+    }, [containerRef, enabled, undo, redo]);
+
+    useLayoutEffect(() => {
+        const api = apiRef.current;
+        api.undo = undo;
+        api.redo = redo;
+        api.canUndo = () => latestRef.current.enabled && undoStackRef.current.length > 0;
+        api.canRedo = () => latestRef.current.enabled && redoStackRef.current.length > 0;
+        api.clearHistory = clearHistory;
+    }, [apiRef, undo, redo, clearHistory]);
+}

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/useGridBatchEdit.ts

@@ -0,0 +1,217 @@
+import { useCallback, useLayoutEffect, useMemo, useRef } from 'react';
+import type { GridBatchEditResult, GridColDef, GridEditSkipReason, GridRowId, GridRowModel } from '../../types';
+import { attempt } from '../../utils/attempt';
+import { getCellValue } from '../../utils/values';
+import {
+    buildEditedRow,
+    invalidProcessedRowError,
+    isPromiseLike,
+    isSameValue,
+    reportEditError,
+} from '../../utils/editing/commit';
+import type { GridCellChange } from '../../utils/editing/commit';
+
+/** What made a commit: history records `edit`, `paste` and `clear`; `undo` / `redo` replay it. */
+export type GridEditSource = 'edit' | 'paste' | 'clear' | 'undo' | 'redo';
+
+/** One cell to write in a batch edit. */
+export interface GridBatchCellEdit {
+    id: GridRowId;
+    field: string;
+    value: unknown;
+    /**
+     * Undo/redo: the value the cell must still hold. When it holds something else the cell is
+     * skipped with reason `'changed'` (values are compared, not row objects).
+     */
+    expect?: { value: unknown };
+}
+
+/** A batch edit's result, plus the cell changes that were stored (what history records). */
+export interface GridBatchEditOutcome {
+    result: GridBatchEditResult;
+    committed: GridCellChange[];
+}
+
+export interface UseGridBatchEditParams<R extends GridRowModel> {
+    /** The rendered row store (`state.rows.idRowsLookup`). */
+    rowsLookup: ReadonlyMap<GridRowId, R>;
+    columns: GridColDef<R>[];
+    processRowUpdate?: (newRow: R, oldRow: R) => R | Promise<R>;
+    onProcessRowUpdateError?: (error: unknown) => void;
+    /** Stores rows in one update (`replaceRows` of the row store). */
+    replaceRows: (rows: ReadonlyMap<GridRowId, R>) => void;
+    /** Receives the stored changes of every commit that is not an undo or redo (history). */
+    onCommitted?: (changes: GridCellChange[], source: GridEditSource) => void;
+}
+
+export interface UseGridBatchEditReturn<R extends GridRowModel> {
+    /**
+     * Writes cells through `valueSetter` → `processRowUpdate` (once per row, rows in parallel) →
+     * the store (one update for every row that succeeded). A row that throws or rejects is reported
+     * to `onProcessRowUpdateError` and does not stop the others. Cells whose value does not change
+     * are left alone. Resolves when every row has settled.
+     */
+    applyEdits: (edits: readonly GridBatchCellEdit[], source: GridEditSource) => Promise<GridBatchEditOutcome>;
+    /** The latest row under `id`, including rows stored but not rendered yet. */
+    getRow: (id: GridRowId) => R | undefined;
+    /** Stores one committed row (a single-cell edit), so `getRow` sees it before the next render. */
+    storeRow: (id: GridRowId, row: R) => void;
+}
+
+interface RowCell<R extends GridRowModel> {
+    field: string;
+    value: unknown;
+    colDef: GridColDef<R> | undefined;
+    order: number;
+}
+
+interface RowGroup<R extends GridRowModel> {
+    id: GridRowId;
+    row: R;
+    cells: RowCell<R>[];
+}
+
+type Settled = { id: GridRowId; ok: true; processed: unknown } | { id: GridRowId; ok: false; error: unknown };
+
+/**
+ * Batch edits: several cells committed together through the single-edit pipeline (paste, range clear,
+ * undo, redo). One `processRowUpdate` per row, one store update for the batch, failures isolated per
+ * row and reported through the same path as single edits. The returned functions are stable.
+ */
+export function useGridBatchEdit<R extends GridRowModel>(params: UseGridBatchEditParams<R>): UseGridBatchEditReturn<R> {
+    const latestRef = useRef(params);
+    // Rows stored since the last render. The rendered lookup catches up on the next render, when
+    // this is emptied; until then an undo right after a paste still reads the pasted rows.
+    const overlayRef = useRef(new Map<GridRowId, R>());
+    const warnedFieldsRef = useRef(new Set<string>());
+    useLayoutEffect(() => {
+        latestRef.current = params;
+        overlayRef.current.clear();
+    });
+
+    const getRow = useCallback((id: GridRowId): R | undefined => {
+        const pending = overlayRef.current.get(id);
+        return pending === undefined ? latestRef.current.rowsLookup.get(id) : pending;
+    }, []);
+
+    const store = useCallback((rows: Map<GridRowId, R>) => {
+        if (rows.size === 0) return;
+        rows.forEach((row, id) => { overlayRef.current.set(id, row); });
+        latestRef.current.replaceRows(rows);
+    }, []);
+
+    const storeRow = useCallback((id: GridRowId, row: R) => {
+        store(new Map([[id, row]]));
+    }, [store]);
+
+    const applyEdits = useCallback((edits: readonly GridBatchCellEdit[], source: GridEditSource): Promise<GridBatchEditOutcome> => {
+        const { columns, processRowUpdate } = latestRef.current;
+        const report = (error: unknown) => reportEditError(error, latestRef.current.onProcessRowUpdateError);
+        const columnOrder = new Map<string, number>();
+        const columnByField = new Map<string, GridColDef<R>>();
+        columns.forEach((col, index) => {
+            columnOrder.set(col.field, index);
+            columnByField.set(col.field, col);
+        });
+
+        const skipped: { id: GridRowId; field: string; reason: GridEditSkipReason }[] = [];
+        const groups = new Map<GridRowId, RowGroup<R>>();
+        for (const edit of edits) {
+            const row = getRow(edit.id);
+            if (row === undefined) {
+                skipped.push({ id: edit.id, field: edit.field, reason: 'missing' });
+                continue;
+            }
+            const colDef = columnByField.get(edit.field);
+            if (edit.expect && !isSameValue(getCellValue(row, edit.field, colDef), edit.expect.value)) {
+                skipped.push({ id: edit.id, field: edit.field, reason: 'changed' });
+                continue;
+            }
+            let group = groups.get(edit.id);
+            if (!group) {
+                group = { id: edit.id, row, cells: [] };
+                groups.set(edit.id, group);
+            }
+            const order = columnOrder.get(edit.field) ?? Number.MAX_SAFE_INTEGER;
+            const existing = group.cells.findIndex(cell => cell.field === edit.field);
+            const cell = { field: edit.field, value: edit.value, colDef, order };
+            // The same cell twice: the last value wins.
+            if (existing === -1) group.cells.push(cell);
+            else group.cells[existing] = cell;
+        }
+
+        const settled: Settled[] = [];
+        const pending: Promise<Settled>[] = [];
+        const warned = warnedFieldsRef.current;
+        groups.forEach(group => {
+            const { id, row } = group;
+            // Cells that already hold the value are not written; a row with none left is left alone.
+            const cells = group.cells
+                .filter(cell => !isSameValue(getCellValue(row, cell.field, cell.colDef), cell.value))
+                .sort((a, b) => a.order - b.order);
+            group.cells = cells;
+            if (cells.length === 0) return;
+            const outcome = attempt<unknown>(() => {
+                let newRow = row;
+                for (const cell of cells) newRow = buildEditedRow(newRow, cell, cell.colDef, warned);
+                return processRowUpdate ? processRowUpdate(newRow, row) : newRow;
+            });
+            if (!outcome.ok) {
+                settled.push({ id, ok: false, error: outcome.error });
+                return;
+            }
+            const value = outcome.value;
+            if (isPromiseLike(value)) {
+                pending.push(Promise.resolve(value).then(
+                    (processed): Settled => ({ id, ok: true, processed }),
+                    (error: unknown): Settled => ({ id, ok: false, error }),
+                ));
+            } else {
+                settled.push({ id, ok: true, processed: value });
+            }
+        });
+
+        const finish = (all: Settled[]): GridBatchEditOutcome => {
+            const byId = new Map<GridRowId, Settled>();
+            all.forEach(entry => { byId.set(entry.id, entry); });
+            const updated: GridRowId[] = [];
+            const failed: { id: GridRowId; error: unknown }[] = [];
+            const committed: GridCellChange[] = [];
+            const stored = new Map<GridRowId, R>();
+            groups.forEach(group => {
+                const entry = byId.get(group.id);
+                if (!entry) return;
+                if (!entry.ok) {
+                    failed.push({ id: group.id, error: entry.error });
+                    report(entry.error);
+                    return;
+                }
+                const processed = entry.processed;
+                if (typeof processed !== 'object' || processed === null) {
+                    const error = invalidProcessedRowError(processed, 'The row was not saved.');
+                    failed.push({ id: group.id, error });
+                    report(error);
+                    return;
+                }
+                const storedRow = processed as R;
+                stored.set(group.id, storedRow);
+                updated.push(group.id);
+                for (const cell of group.cells) {
+                    const before = getCellValue(group.row, cell.field, cell.colDef);
+                    const after = getCellValue(storedRow, cell.field, cell.colDef);
+                    if (!isSameValue(before, after)) committed.push({ id: group.id, field: cell.field, before, after });
+                }
+            });
+            store(stored);
+            if (committed.length > 0 && source !== 'undo' && source !== 'redo') {
+                latestRef.current.onCommitted?.(committed, source);
+            }
+            return { result: { updated, failed, skipped }, committed };
+        };
+
+        if (pending.length === 0) return Promise.resolve(finish(settled));
+        return Promise.all(pending).then(results => finish([...settled, ...results]));
+    }, [getRow, store]);
+
+    return useMemo(() => ({ applyEdits, getRow, storeRow }), [applyEdits, getRow, storeRow]);
+}

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);
       });
     };