@opencorestack/opengridx 3.3.0 → 3.5.0

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`, `clear` and `fill`; `undo` / `redo` replay it. */
+export type GridEditSource = 'edit' | 'paste' | 'clear' | 'fill' | '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/useGridEditing.ts

@@ -1,6 +1,15 @@
 import { useState, useCallback, useRef, useEffect, useLayoutEffect, useMemo } from 'react';
 import type { GridColDef, 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';
 
 export interface GridEditingState {
     editingCell: {
@@ -23,6 +32,12 @@ export interface UseGridEditingParams<R extends GridRowModel> {
      * grid resolved with getRowId), not on a field of the returned row.
      */
     onRowChange?: (newRow: R, id: GridRowId) => void;
+    /**
+     * Receives the cell change once `processRowUpdate` succeeded and the row was stored (undo/redo
+     * history): the value before and the stored value, both read through `getCellValue`. Not called
+     * when the stored value equals the previous one.
+     */
+    onCommitted?: (changes: GridCellChange[]) => void;
 }
 
 export interface StopCellEditParams {
@@ -46,18 +61,6 @@ interface PendingCommit {
 
 const RESOLVED: Promise<void> = Promise.resolve();
 
-/** A misuse of the editing contract (e.g. processRowUpdate returned nothing), as opposed to a consumer rejection. */
-class OpenGridXEditError extends Error {}
-
-function isSameValue(a: unknown, b: unknown): boolean {
-    if (a instanceof Date && b instanceof Date) return a.getTime() === b.getTime();
-    return Object.is(a, b);
-}
-
-function isPromiseLike(value: unknown): value is PromiseLike<unknown> {
-    return typeof value === 'object' && value !== null && typeof (value as { then?: unknown }).then === 'function';
-}
-
 /**
  * Cell edit sessions and their commits.
  *
@@ -126,24 +129,21 @@ export function useGridEditing<R extends GridRowModel>(params: UseGridEditingPar
             return RESOLVED;
         }
 
-        const report = (error: unknown) => {
-            const onError = latestRef.current.onProcessRowUpdateError;
-            if (onError) {
-                onError(error);
-            } else if (process.env.NODE_ENV !== 'production' && error instanceof OpenGridXEditError) {
-                console.error(error.message);
-            }
-        };
+        const report = (error: unknown) => reportEditError(error, latestRef.current.onProcessRowUpdateError);
+        const colDef = columns?.find(c => c.field === cell.field);
 
         const apply = (processed: unknown) => {
             if (typeof processed !== 'object' || processed === null) {
-                report(new OpenGridXEditError(
-                    `[OpenGridX] processRowUpdate must return the updated row object (or a Promise of it); ` +
-                    `it returned ${processed === null ? 'null' : typeof processed}. The edit was not saved and the editor stays open.`
-                ));
+                report(invalidProcessedRowError(processed, 'The edit was not saved and the editor stays open.'));
                 return;
             }
             latestRef.current.onRowChange?.(processed as R, cell.id);
+            const { onCommitted } = latestRef.current;
+            if (onCommitted) {
+                const before = getCellValue(existingRow, cell.field, colDef);
+                const after = getCellValue(processed as R, cell.field, colDef);
+                if (!isSameValue(before, after)) onCommitted([{ id: cell.id, field: cell.field, before, after }]);
+            }
             const now = editingCellRef.current;
             if (sessionRef.current !== token || !now) return;
             if (isSameValue(now.value, cell.value)) {
@@ -164,7 +164,6 @@ export function useGridEditing<R extends GridRowModel>(params: UseGridEditingPar
             if (pendingRef.current.get(token) === entry) pendingRef.current.delete(token);
         };
 
-        const colDef = columns?.find(c => c.field === cell.field);
         const outcome = attempt<unknown>(() => {
             const newRow = buildEditedRow(existingRow, cell, colDef, warnedFieldsRef.current);
             return processRowUpdate ? processRowUpdate(newRow, existingRow) : newRow;
@@ -246,23 +245,3 @@ export function useGridEditing<R extends GridRowModel>(params: UseGridEditingPar
         setEditCellValue
     }), [editingCell, startCellEdit, stopCellEdit, setEditCellValue]);
 }
-
-function buildEditedRow<R extends GridRowModel>(
-    row: R,
-    cell: EditingCell,
-    colDef: GridColDef<R> | undefined,
-    warnedFields: Set<string>
-): R {
-    if (colDef?.valueSetter) {
-        return colDef.valueSetter({ value: cell.value, row, field: cell.field });
-    }
-    if (colDef?.valueGetter && process.env.NODE_ENV !== 'production' && !warnedFields.has(cell.field)) {
-        warnedFields.add(cell.field);
-        console.warn(
-            `[OpenGridX] Column "${cell.field}" is editable and has a valueGetter but no valueSetter. ` +
-            `The edited value was written to row["${cell.field}"], which the valueGetter may ignore, so the cell ` +
-            'can keep showing the old value. Add a valueSetter that maps the value back onto the row.'
-        );
-    }
-    return { ...row, [cell.field]: cell.value };
-}

package/lib/index.ts

@@ -93,6 +93,7 @@ export type {
     GridValueGetterParams,
     GridSortCellParams,
     GridValueSetterParams,
+    GridValueParserParams,
     GridValueFormatterParams,
     GridRowParams,
     GridCellParams,
@@ -108,6 +109,15 @@ export type {
     GridCellSelectionChangeDetails,
     GridSelectedCell,
     GridCellSelectionStatsSlotProps,
+    GridEditSkipReason,
+    GridBatchEditResult,
+    GridClipboardPasteResult,
+    GridFillDirection,
+    GridFillResult,
+    GridFillValueParams,
+    GridBeforeClipboardPasteParams,
+    GridHistoryChangeParams,
+    GridUndoRedoOptions,
     GridColumnOrder,
     GridColumnOrderChangeParams,
     GridRowOrderChangeParams,

package/lib/styles/opengridx.css

@@ -1,7 +1,10 @@
 @import './base/variables.css';
 @import './base/reset.css';
+/* Shared primitives first, so component styles that restyle them win on equal specificity. */
+@import '../components/ui/Input.css';
 @import '../components/DataGrid/DataGrid.css';
 @import '../components/Header/Header.css';
+@import '../components/HeaderFilter/HeaderFilter.css';
 @import '../components/Row/Row.css';
 @import '../components/Cell/Cell.css';
 @import '../components/Cell/GridEditInputCell.css';
@@ -16,7 +19,6 @@
 @import '../components/ui/Checkbox.css';
 @import '../components/ui/DragHandleIcon.css';
 @import '../components/ui/ExpandIcon.css';
-@import '../components/ui/Input.css';
 @import '../components/Toolbar/GridToolbar.css';
 @import '../components/Toolbar/PivotPanel.css';
 @import '../components/FilterPanel/FilterPanel.css';
@@ -26,3 +28,4 @@
 @import '../components/ColumnGroupHeader/ColumnGroupHeader.css';
 @import '../components/Tooltip/Tooltip.css';
 @import '../components/CellSelectionStats/CellSelectionStats.css';
+@import '../components/AiAssistant/GridAiAssistantPanel.css';

package/lib/theme/DataGridThemeProvider.tsx

@@ -11,6 +11,7 @@ const primaryDerived: Record<string, string> = {
     '--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-fill-handle-color': 'var(--ogx-range-border)',
     '--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)',
@@ -285,6 +286,7 @@ function themeToCSS(theme: GridTheme): Record<string, string> {
         set('--ogx-grid-cell-focus-border', g.cellFocusBorder);
         set('--ogx-range-background', g.rangeBackground);
         set('--ogx-range-border', g.rangeBorder);
+        set('--ogx-fill-handle-color', g.fillHandleColor);
         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/types.ts

@@ -163,6 +163,8 @@ export interface GridThemeGrid {
     rangeBackground?: string;
     /** Outline of a selected cell range (`--ogx-range-border`). Default: the primary colour. @since v3.3 */
     rangeBorder?: string;
+    /** The fill handle on the range's corner (`--ogx-fill-handle-color`). Default: the range border colour. @since v3.5 */
+    fillHandleColor?: string;
     pinnedLeftShadow?: string;
   pinnedRightShadow?: string;
     checkboxBg?: string;