@opencorestack/opengridx 2.1.0 → 3.0.1

package/lib/hooks/features/useGridEditing.ts

@@ -1,5 +1,5 @@
-import React, { useState, useCallback, useRef } from 'react';
-import type { GridRowId, GridRowModel } from '../../types';
+import { useState, useCallback, useRef, useEffect, useLayoutEffect, useMemo } from 'react';
+import type { GridColDef, GridRowId, GridRowModel } from '../../types';
 
 export interface GridEditingState {
     editingCell: {
@@ -13,87 +13,247 @@ export interface GridEditingState {
 export interface UseGridEditingParams<R extends GridRowModel> {
     rows: R[];
     getRowId: (row: R) => GridRowId;
+    /** Column definitions; used to find the edited column's `valueSetter`. */
+    columns?: GridColDef<R>[];
     processRowUpdate?: (newRow: R, oldRow: R) => R | Promise<R>;
     onProcessRowUpdateError?: (error: unknown) => void;
-    onRowChange?: (newRow: R) => void;
+    /**
+     * Receives the committed row and the id of the row that was edited. Match on `id` (the key the
+     * grid resolved with getRowId), not on a field of the returned row.
+     */
+    onRowChange?: (newRow: R, id: GridRowId) => void;
+}
+
+export interface StopCellEditParams {
+    /** Discard the pending value instead of committing it. */
+    cancel?: boolean;
+    /**
+     * Only act if this cell is the one being edited. Editors pass their own cell so that a late
+     * blur or unmount cannot end another cell's edit.
+     */
+    id?: GridRowId;
+    field?: string;
 }
 
 type EditingCellState = GridEditingState['editingCell'];
+type EditingCell = NonNullable<EditingCellState>;
 
-export function useGridEditing<R extends GridRowModel>(params: UseGridEditingParams<R>) {
-    const {
-        rows,
-        getRowId,
-        processRowUpdate,
-        onProcessRowUpdateError,
-        onRowChange
-    } = params;
+interface PendingCommit {
+    value: unknown;
+    promise: Promise<void>;
+}
+
+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.
+ *
+ * - One commit per edit: a stop while a commit is in flight (Enter then blur, Tab then the blur that
+ *   moving focus causes) shares that commit instead of calling `processRowUpdate` again. A stop that
+ *   arrives after the value changed again commits the newer value once the first commit settles.
+ * - A commit that settles late only closes the editor if that same session is still open with the
+ *   committed value; it never closes another cell's edit or drops text typed in the meantime. Its
+ *   row is always applied: `processRowUpdate` has already run, and may already have persisted it.
+ * - Starting an edit on another cell commits the current one first, so an edit whose editor is gone
+ *   (for example scrolled out of the render window) is never silently dropped.
+ * - The returned functions keep their identity for the lifetime of the grid.
+ */
+export function useGridEditing<R extends GridRowModel>(params: UseGridEditingParams<R>) {
     const [editingCell, setEditingCellState] = useState<EditingCellState>(null);
     const editingCellRef = useRef<EditingCellState>(null);
+    // Id of the current edit session; bumped whenever a cell enters edit mode.
+    const sessionRef = useRef(0);
+    const pendingRef = useRef(new Map<number, PendingCommit>());
+    const warnedFieldsRef = useRef(new Set<string>());
+    const mountedRef = useRef(false);
 
-    const setEditingCell = useCallback((val: React.SetStateAction<EditingCellState>) => {
-        setEditingCellState(val);
-        editingCellRef.current = typeof val === 'function' ? val(editingCellRef.current) : val;
-    }, []);
+    // Latest props, read when an edit is committed so the callbacks below can stay stable.
+    const latestRef = useRef(params);
+    useLayoutEffect(() => {
+        latestRef.current = params;
+    });
 
-    const startCellEdit = useCallback((editParams: { id: GridRowId; field: string; value: unknown }) => {
-        setEditingCell({
-            id: editParams.id,
-            field: editParams.field,
-            value: editParams.value,
-            originalValue: editParams.value
-        });
-    }, [setEditingCell]);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => { mountedRef.current = false; };
+    }, []);
 
-    const stopCellEdit = useCallback(async (stopParams?: { cancel?: boolean }) => {
-        const currentCell = editingCellRef.current;
-        if (!currentCell) return;
+    const setEditingCell = useCallback((next: EditingCellState) => {
+        editingCellRef.current = next;
+        setEditingCellState(next);
+    }, []);
 
-        if (stopParams?.cancel) {
-            setEditingCell(null);
-            return;
+    const commit = useCallback((token: number, cell: EditingCell): Promise<void> => {
+        const inFlight = pendingRef.current.get(token);
+        if (inFlight) {
+            if (isSameValue(inFlight.value, cell.value)) return inFlight.promise;
+            // The value changed while a commit was in flight: commit the newer value once it settles.
+            return inFlight.promise.then(() => {
+                const now = editingCellRef.current;
+                if (sessionRef.current !== token || !now || isSameValue(now.value, inFlight.value)) return;
+                return commit(token, now);
+            });
         }
 
-        const { id, field, value, originalValue } = currentCell;
+        const isCurrent = () => sessionRef.current === token && editingCellRef.current !== null;
 
-        if (value === originalValue) {
-            setEditingCell(null);
-            return;
+        if (isSameValue(cell.value, cell.originalValue)) {
+            if (isCurrent()) setEditingCell(null);
+            return RESOLVED;
         }
 
-        const existingRow = rows.find(r => getRowId(r) === id);
+        const { rows, getRowId, columns, processRowUpdate } = latestRef.current;
+        const existingRow = rows.find(r => getRowId(r) === cell.id);
         if (!existingRow) {
-            setEditingCell(null);
-            return;
+            if (isCurrent()) setEditingCell(null);
+            return RESOLVED;
         }
 
-        const newRow = { ...existingRow, [field]: value };
+        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);
+            }
+        };
 
-        try {
-            if (processRowUpdate) {
-                const processedRow = await processRowUpdate(newRow, existingRow);
-                onRowChange?.(processedRow);
+        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.`
+                ));
+                return;
+            }
+            latestRef.current.onRowChange?.(processed as R, cell.id);
+            const now = editingCellRef.current;
+            if (sessionRef.current !== token || !now) return;
+            if (isSameValue(now.value, cell.value)) {
+                setEditingCell(null);
             } else {
-                onRowChange?.(newRow);
+                // Newer text was typed while this commit was in flight: keep editing it.
+                setEditingCell({ ...now, originalValue: cell.value });
             }
-            setEditingCell(null);
+        };
+
+        // Register the commit before calling out, so a re-entrant stop joins it.
+        let settle!: () => void;
+        let fail!: (error: unknown) => void;
+        const promise = new Promise<void>((resolve, reject) => { settle = resolve; fail = reject; });
+        const entry: PendingCommit = { value: cell.value, promise };
+        pendingRef.current.set(token, entry);
+        const finish = () => {
+            if (pendingRef.current.get(token) === entry) pendingRef.current.delete(token);
+        };
+
+        let result: unknown;
+        try {
+            const colDef = columns?.find(c => c.field === cell.field);
+            const newRow = buildEditedRow(existingRow, cell, colDef, warnedFieldsRef.current);
+            result = processRowUpdate ? processRowUpdate(newRow, existingRow) : newRow;
         } catch (error) {
-            onProcessRowUpdateError?.(error);
+            // Consumer code (valueSetter / processRowUpdate) threw: report it, keep the editor open.
+            finish();
+            report(error);
+            settle();
+            return promise;
         }
 
-    }, [setEditingCell, rows, getRowId, processRowUpdate, onRowChange, onProcessRowUpdateError]);
+        const complete = (processed: unknown) => {
+            finish();
+            try {
+                apply(processed);
+                settle();
+            } catch (error) {
+                // A failure while the grid stores the row is a grid error, not a processRowUpdate one.
+                fail(error);
+            }
+        };
 
-    const setEditCellValue = useCallback((editParams: { id: GridRowId; field: string; value: unknown }) => {
-        if (editingCell && editingCell.id === editParams.id && editingCell.field === editParams.field) {
-            setEditingCell(prev => prev ? { ...prev, value: editParams.value } : null);
+        if (isPromiseLike(result)) {
+            Promise.resolve(result).then(complete, (error: unknown) => {
+                finish();
+                report(error);
+                settle();
+            });
+        } else {
+            complete(result);
         }
-    }, [editingCell, setEditingCell]);
+        return promise;
+    }, [setEditingCell]);
 
-    return {
+    const startCellEdit = useCallback((editParams: { id: GridRowId; field: string; value: unknown }) => {
+        const current = editingCellRef.current;
+        if (current) {
+            if (current.id === editParams.id && current.field === editParams.field) return;
+            // Commit the edit in progress before switching cells.
+            void commit(sessionRef.current, current);
+        }
+        sessionRef.current += 1;
+        setEditingCell({
+            id: editParams.id,
+            field: editParams.field,
+            value: editParams.value,
+            originalValue: editParams.value
+        });
+    }, [commit, setEditingCell]);
+
+    const stopCellEdit = useCallback((stopParams?: StopCellEditParams): Promise<void> => {
+        const cell = editingCellRef.current;
+        if (!cell || !mountedRef.current) return RESOLVED;
+        if (stopParams?.id !== undefined && stopParams.id !== cell.id) return RESOLVED;
+        if (stopParams?.field !== undefined && stopParams.field !== cell.field) return RESOLVED;
+
+        if (stopParams?.cancel) {
+            setEditingCell(null);
+            return RESOLVED;
+        }
+        return commit(sessionRef.current, cell);
+    }, [commit, setEditingCell]);
+
+    const setEditCellValue = useCallback((editParams: { id: GridRowId; field: string; value: unknown }) => {
+        const current = editingCellRef.current;
+        if (!current || current.id !== editParams.id || current.field !== editParams.field) return;
+        setEditingCell({ ...current, value: editParams.value });
+    }, [setEditingCell]);
+
+    return useMemo(() => ({
         editingCell,
         startCellEdit,
         stopCellEdit,
         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/hooks/features/useGridPivot.ts

@@ -0,0 +1,92 @@
+import { useEffect, useMemo, useRef } from 'react';
+import type { GridColDef, GridFilterModel, GridPivotModel, GridRowModel, GridSortItem } from '../../types';
+import { filterRows } from '../../utils/filtering';
+import { buildColumnLookup } from '../../utils/columnLookup';
+import { computePivot, splitPivotFilterModel, EMPTY_PIVOT_RESULT } from '../../utils/pivot';
+
+const EMPTY_FILTER_MODEL: GridFilterModel = { items: [] };
+const EMPTY_SORT_MODEL: GridSortItem[] = [];
+
+export interface UseGridPivotParams {
+    rows: GridRowModel[];
+    columns: GridColDef[];
+    pivotMode: boolean;
+    pivotModel: GridPivotModel;
+    filterModel: GridFilterModel;
+    sortModel: GridSortItem[];
+    /** Pivoting is client-side: with a dataSource the grid only holds one page, so pivot mode is not applied. */
+    hasDataSource: boolean;
+    /** treeData or a rowGroupingModel was requested; both are turned off while pivoting. */
+    hierarchyRequested: boolean;
+}
+
+export interface UseGridPivotResult {
+    /** Pivot mode is on, the model is usable and the grid is client-side. */
+    isActive: boolean;
+    /** Sorted pivot data rows followed by the Grand Total row. */
+    rows: GridRowModel[];
+    columns: GridColDef[];
+    /**
+     * Filter and sort models for the row pipeline. While pivoting they are empty: the pivot already
+     * applied them (filters to the source rows or the pivot rows, sorting with the Grand Total kept last).
+     */
+    pipelineFilterModel: GridFilterModel;
+    pipelineSortModel: GridSortItem[];
+}
+
+/**
+ * DataGrid's pivot stage. Source-field filters and the quick filter run on the source rows before
+ * pivoting, so pivot values and the Grand Total reflect them; conditions on generated value columns run
+ * on the pivot rows. Sorting orders the pivot data rows and never moves the Grand Total.
+ */
+export function useGridPivot(params: UseGridPivotParams): UseGridPivotResult {
+    const { rows, columns, pivotMode, pivotModel, filterModel, sortModel, hasDataSource, hierarchyRequested } = params;
+    const enabled = pivotMode && !hasDataSource;
+
+    const sourceFields = useMemo(() => new Set(columns.map((c) => c.field)), [columns]);
+    // No source column is on screen while pivoting (the row-label columns show the row fields
+    // whatever the visibility model says), so the quick filter searches every filterable source column.
+    const sourceLookup = useMemo(() => buildColumnLookup(columns), [columns]);
+    const splitFilter = useMemo(
+        () => splitPivotFilterModel(filterModel, sourceFields),
+        [filterModel, sourceFields],
+    );
+    const sourceRows = useMemo(
+        () => (enabled ? filterRows(rows, splitFilter.source, sourceLookup) : rows),
+        [enabled, rows, splitFilter.source, sourceLookup],
+    );
+    const pivot = useMemo(
+        () => (enabled
+            ? computePivot(sourceRows, columns, pivotModel, { outputFilterModel: splitFilter.output, sortModel })
+            : EMPTY_PIVOT_RESULT),
+        [enabled, sourceRows, columns, pivotModel, splitFilter.output, sortModel],
+    );
+    const isActive = enabled && pivot.isValid;
+
+    const warnedRef = useRef({ dataSource: false, hierarchy: false });
+    useEffect(() => {
+        if (process.env.NODE_ENV === 'production') return;
+        if (pivotMode && hasDataSource && !warnedRef.current.dataSource) {
+            warnedRef.current.dataSource = true;
+            console.warn(
+                '[OpenGridX] `pivotMode` is ignored when a `dataSource` is set: pivoting is client-side and the grid ' +
+                'only holds the rows of one server page. Pivot on the server, or pass the full dataset as `rows`.'
+            );
+        }
+        if (isActive && hierarchyRequested && !warnedRef.current.hierarchy) {
+            warnedRef.current.hierarchy = true;
+            console.warn(
+                '[OpenGridX] `treeData` and `rowGroupingModel` are turned off while `pivotMode` is active: the pivot ' +
+                'rows are already grouped by the pivot row fields.'
+            );
+        }
+    }, [pivotMode, hasDataSource, isActive, hierarchyRequested]);
+
+    return {
+        isActive,
+        rows: isActive ? pivot.pivotRows : rows,
+        columns: isActive ? pivot.pivotColumns : columns,
+        pipelineFilterModel: isActive ? EMPTY_FILTER_MODEL : filterModel,
+        pipelineSortModel: isActive ? EMPTY_SORT_MODEL : sortModel,
+    };
+}

package/lib/hooks/features/useGridSpanRenderWindow.ts

@@ -0,0 +1,104 @@
+import { useMemo } from 'react';
+import type { GridColDef, GridRowId, GridRowModel } from '../../types';
+import type { GridSpanningResult } from './useGridSpanning';
+
+interface RowRenderContext {
+    firstRowIndex: number;
+    lastRowIndex: number;
+    firstColumnIndex: number;
+    lastColumnIndex: number;
+}
+
+export interface UseGridSpanRowWindowParams {
+    spanning: GridSpanningResult;
+    renderContext: RowRenderContext;
+    offsetTop: number;
+    /** Cumulative heights of the center rows (layout output). */
+    cumulativeHeights: number[];
+}
+
+/**
+ * Extends the vertical render window back to the origin row of any row span that reaches the first
+ * rendered row. Only the origin renders the merged content, so without this the visible part of a
+ * span whose origin has scrolled above the overscan window would be blank.
+ */
+export function useGridSpanRowWindow(params: UseGridSpanRowWindowParams): { renderContext: RowRenderContext; offsetTop: number } {
+    const { spanning, renderContext, offsetTop, cumulativeHeights } = params;
+
+    return useMemo(() => {
+        if (!spanning.hasRowSpan) return { renderContext, offsetTop };
+        let first = Math.max(0, renderContext.firstRowIndex);
+        for (let start = spanning.getCenterRowSpanStart(first); start < first; start = spanning.getCenterRowSpanStart(first)) {
+            first = start;
+        }
+        if (first >= renderContext.firstRowIndex) return { renderContext, offsetTop };
+        return {
+            renderContext: { ...renderContext, firstRowIndex: first },
+            offsetTop: first > 0 ? cumulativeHeights[first - 1] ?? 0 : 0,
+        };
+    }, [spanning, renderContext, offsetTop, cumulativeHeights]);
+}
+
+interface ColumnLayout<R extends GridRowModel> {
+    leftPinnedCols: GridColDef<R>[];
+    unpinnedColsWithWidth: (GridColDef<R> & { width: number })[];
+    rightPinnedCols: GridColDef<R>[];
+    unpinnedAccWidths: number[];
+    unpinnedTotalWidth: number;
+}
+
+export interface UseGridSpanColumnWindowParams<R extends GridRowModel> {
+    spanning: GridSpanningResult;
+    /** Unpinned column window chosen by the virtualization. */
+    firstColumnIndex: number;
+    lastColumnIndex: number;
+    virtualColumns: GridColDef<R>[];
+    layout: ColumnLayout<R>;
+    /** Rows that will be rendered, with their resolved id (rows do not have to carry it in `row.id`). */
+    rows: { row: R; id?: GridRowId }[];
+}
+
+/**
+ * Widens the horizontal render window so every colSpan in the rendered rows is either fully inside
+ * it or fully outside it. A span origin left of the window would otherwise render nothing while its
+ * covered columns render nothing either, shifting the rest of the row left; a span that runs past
+ * the right edge would overflow the right spacer.
+ */
+export function useGridSpanColumnWindow<R extends GridRowModel>(params: UseGridSpanColumnWindowParams<R>): GridColDef<R>[] {
+    const { spanning, firstColumnIndex, lastColumnIndex, virtualColumns, layout, rows } = params;
+
+    return useMemo(() => {
+        if (!spanning.hasColSpan || layout.unpinnedColsWithWidth.length === 0) return virtualColumns;
+
+        let first = firstColumnIndex;
+        let last = lastColumnIndex;
+        let changed = true;
+        while (changed) {
+            changed = false;
+            for (const { row, id } of rows) {
+                const ranges = spanning.getUnpinnedColSpanRanges(id ?? row.id);
+                if (!ranges) continue;
+                for (let k = 0; k < ranges.length; k += 2) {
+                    const start = ranges[k];
+                    const end = ranges[k + 1];
+                    if (end < first || start > last) continue;
+                    if (start < first) { first = start; changed = true; }
+                    if (end > last) { last = end; changed = true; }
+                }
+            }
+        }
+
+        if (first === firstColumnIndex && last === lastColumnIndex) return virtualColumns;
+
+        const { leftPinnedCols, unpinnedColsWithWidth, rightPinnedCols, unpinnedAccWidths, unpinnedTotalWidth } = layout;
+        const leftSpacerWidth = first > 0 ? unpinnedAccWidths[first - 1] : 0;
+        const rightSpacerWidth = unpinnedTotalWidth - unpinnedAccWidths[last];
+        return [
+            ...leftPinnedCols,
+            ...(leftSpacerWidth > 0 ? [{ field: '__spacer_left__', width: leftSpacerWidth, isSpacer: true } as GridColDef<R>] : []),
+            ...unpinnedColsWithWidth.slice(first, last + 1),
+            ...(rightSpacerWidth > 0 ? [{ field: '__spacer_right__', width: rightSpacerWidth, isSpacer: true } as GridColDef<R>] : []),
+            ...rightPinnedCols,
+        ];
+    }, [spanning, firstColumnIndex, lastColumnIndex, virtualColumns, layout, rows]);
+}