@mui/x-data-grid-premium 8.24.0 → 8.26.0

package/esm/hooks/features/history/defaultHistoryHandlers.js

@@ -0,0 +1,365 @@
+import _extends from "@babel/runtime/helpers/esm/extends";
+import { isDeepEqual } from '@mui/x-internals/isDeepEqual';
+import { gridVisibleRowsSelector, gridVisibleColumnFieldsSelector, gridColumnFieldsSelector } from '@mui/x-data-grid-pro';
+/**
+ * Create the default handler for cellEditStop events.
+ */
+export const createCellEditHistoryHandler = apiRef => {
+  return {
+    store: params => {
+      const {
+        id,
+        field
+      } = params;
+      const oldValue = apiRef.current.getRow(id)[field];
+      const newValue = apiRef.current.getRowWithUpdatedValues(id, field)[field];
+      if (isDeepEqual(oldValue, newValue)) {
+        return null;
+      }
+      return {
+        id,
+        field,
+        oldValue,
+        newValue
+      };
+    },
+    validate: (data, direction) => {
+      const {
+        id,
+        field,
+        oldValue,
+        newValue
+      } = data;
+
+      // Check if column is visible
+      if (!gridVisibleColumnFieldsSelector(apiRef).includes(field)) {
+        return false;
+      }
+      const {
+        rowIdToIndexMap,
+        range
+      } = gridVisibleRowsSelector(apiRef);
+
+      // Check if row is in the current page
+      const rowIndex = rowIdToIndexMap.get(id);
+      if (rowIndex === undefined || rowIndex < (range?.firstRowIndex || 0) || rowIndex > (range?.lastRowIndex || rowIndex)) {
+        return false;
+      }
+      const row = apiRef.current.getRow(id);
+
+      // Check if the value hasn't changed externally
+      const currentValue = row[field];
+      const expectedValue = direction === 'undo' ? newValue : oldValue;
+      if (!isDeepEqual(currentValue, expectedValue)) {
+        return false;
+      }
+      return true;
+    },
+    undo: async data => {
+      const {
+        id,
+        field,
+        oldValue
+      } = data;
+      if (apiRef.current.state.props.dataSource?.updateRow) {
+        const row = apiRef.current.getRow(id);
+        await apiRef.current.dataSource.editRow({
+          rowId: id,
+          updatedRow: _extends({}, row, {
+            [field]: oldValue
+          }),
+          previousRow: row
+        });
+      } else {
+        apiRef.current.updateRows([{
+          id,
+          [field]: oldValue
+        }]);
+      }
+
+      // Use `requestAnimationFrame` to ensure all undo updates are applied
+      requestAnimationFrame(() => {
+        apiRef.current.setCellFocus(id, field);
+        apiRef.current.scrollToIndexes({
+          rowIndex: apiRef.current.getRowIndexRelativeToVisibleRows(id),
+          colIndex: apiRef.current.getColumnIndex(field)
+        });
+      });
+    },
+    redo: async data => {
+      const {
+        id,
+        field,
+        newValue
+      } = data;
+      if (apiRef.current.state.props.dataSource?.updateRow) {
+        const row = apiRef.current.getRow(id);
+        await apiRef.current.dataSource.editRow({
+          rowId: id,
+          updatedRow: _extends({}, row, {
+            [field]: newValue
+          }),
+          previousRow: row
+        });
+      } else {
+        apiRef.current.updateRows([{
+          id,
+          [field]: newValue
+        }]);
+      }
+
+      // Use `requestAnimationFrame` to ensure all redo updates are applied
+      requestAnimationFrame(() => {
+        apiRef.current.setCellFocus(id, field);
+        apiRef.current.scrollToIndexes({
+          rowIndex: apiRef.current.getRowIndexRelativeToVisibleRows(id),
+          colIndex: apiRef.current.getColumnIndex(field)
+        });
+      });
+    }
+  };
+};
+
+/**
+ * Create the default handler for rowEditStop events.
+ */
+export const createRowEditHistoryHandler = apiRef => {
+  return {
+    store: params => {
+      const {
+        id
+      } = params;
+      const oldRow = apiRef.current.getRow(id) || {};
+      const newRow = apiRef.current.getRowWithUpdatedValues(id, '');
+      if (isDeepEqual(oldRow, newRow)) {
+        return null;
+      }
+      return {
+        id,
+        oldRow,
+        newRow
+      };
+    },
+    validate: (data, direction) => {
+      const {
+        id,
+        oldRow,
+        newRow
+      } = data;
+      const {
+        rowIdToIndexMap,
+        range
+      } = gridVisibleRowsSelector(apiRef);
+
+      // Check if row is in the current page
+      const rowIndex = rowIdToIndexMap.get(id);
+      if (rowIndex === undefined || rowIndex < (range?.firstRowIndex || 0) || rowIndex > (range?.lastRowIndex || rowIndex)) {
+        return false;
+      }
+      const row = apiRef.current.getRow(id);
+
+      // Check if modified fields haven't changed externally
+      const expectedRow = direction === 'undo' ? newRow : oldRow;
+      for (const field of Object.keys(expectedRow)) {
+        if (!isDeepEqual(row[field], expectedRow[field])) {
+          return false;
+        }
+      }
+      return true;
+    },
+    undo: async data => {
+      const {
+        id,
+        oldRow,
+        newRow
+      } = data;
+      if (apiRef.current.state.props.dataSource?.updateRow) {
+        await apiRef.current.dataSource.editRow({
+          rowId: id,
+          updatedRow: oldRow,
+          previousRow: newRow
+        });
+      } else {
+        apiRef.current.updateRows([_extends({
+          id
+        }, oldRow)]);
+      }
+
+      // Use `requestAnimationFrame` to ensure all undo updates are applied
+      requestAnimationFrame(() => {
+        apiRef.current.setCellFocus(id, Object.keys(oldRow)[0]);
+        apiRef.current.scrollToIndexes({
+          rowIndex: apiRef.current.getRowIndexRelativeToVisibleRows(id),
+          colIndex: 0
+        });
+      });
+    },
+    redo: async data => {
+      const {
+        id,
+        oldRow,
+        newRow
+      } = data;
+      if (apiRef.current.state.props.dataSource?.updateRow) {
+        await apiRef.current.dataSource.editRow({
+          rowId: id,
+          updatedRow: newRow,
+          previousRow: oldRow
+        });
+      } else {
+        apiRef.current.updateRows([_extends({
+          id
+        }, newRow)]);
+      }
+
+      // Use `requestAnimationFrame` to ensure all redo updates are applied
+      requestAnimationFrame(() => {
+        apiRef.current.setCellFocus(id, Object.keys(newRow)[0]);
+        apiRef.current.scrollToIndexes({
+          rowIndex: apiRef.current.getRowIndexRelativeToVisibleRows(id),
+          colIndex: 0
+        });
+      });
+    }
+  };
+};
+
+/**
+ * Create the default handler for clipboardPasteEnd events.
+ */
+export const createClipboardPasteHistoryHandler = apiRef => {
+  return {
+    store: params => params,
+    validate: (data, direction) => {
+      const {
+        oldRows,
+        newRows
+      } = data;
+      const updatedRowIds = Array.from(newRows.keys());
+
+      // Check if any rows were updated
+      if (updatedRowIds.length === 0) {
+        return false;
+      }
+
+      // Check if all affected rows are still visible and have expected values
+      const {
+        rowIdToIndexMap,
+        range
+      } = gridVisibleRowsSelector(apiRef);
+      for (let i = 0; i < updatedRowIds.length; i += 1) {
+        const rowId = updatedRowIds[i];
+        const rowIndex = rowIdToIndexMap.get(rowId);
+        if (rowIndex === undefined || rowIndex < (range?.firstRowIndex || 0) || rowIndex > (range?.lastRowIndex || rowIndex)) {
+          return false;
+        }
+        const row = apiRef.current.getRow(rowId);
+        if (!row) {
+          return false;
+        }
+        const expectedRow = direction === 'undo' ? newRows.get(rowId) : oldRows.get(rowId);
+
+        // Check if the row values match what we expect
+        for (const field of Object.keys(expectedRow)) {
+          if (!isDeepEqual(row[field], expectedRow[field])) {
+            return false;
+          }
+        }
+      }
+      return true;
+    },
+    undo: async data => {
+      const {
+        oldRows,
+        newRows
+      } = data;
+      const oldRowsValues = Array.from(oldRows.values());
+      const visibleColumns = apiRef.current.getVisibleColumns();
+
+      // Focus the first affected cell
+      if (oldRowsValues.length > 0 && visibleColumns.length > 0) {
+        const columnOrder = gridColumnFieldsSelector(apiRef);
+
+        // Since we undo, oldRowData is the new data that will be set and newRowData is the current row
+        const firstOldRow = Array.from(newRows.values())[0];
+        const [firstNewRowId, firstNewRow] = Array.from(oldRows.entries())[0];
+        let differentFieldIndex = columnOrder.length - 1;
+        // Find the first field that is different to set the focus on
+        for (let i = 0; i < columnOrder.length; i += 1) {
+          const field = columnOrder[i];
+          if (!isDeepEqual(firstOldRow[field], firstNewRow[field])) {
+            differentFieldIndex = i;
+            break;
+          }
+        }
+
+        // Restore all rows to their original state
+        apiRef.current.updateRows(oldRowsValues);
+        if (differentFieldIndex >= 0) {
+          requestAnimationFrame(() => {
+            apiRef.current.setCellFocus(firstNewRowId, columnOrder[differentFieldIndex]);
+            apiRef.current.scrollToIndexes({
+              rowIndex: apiRef.current.getRowIndexRelativeToVisibleRows(firstNewRowId),
+              colIndex: differentFieldIndex
+            });
+          });
+        }
+      }
+    },
+    redo: async data => {
+      const {
+        oldRows,
+        newRows
+      } = data;
+      const newRowsValues = Array.from(newRows.values());
+      const visibleColumns = apiRef.current.getVisibleColumns();
+
+      // Focus the first affected cell
+      if (newRowsValues.length > 0 && visibleColumns.length > 0) {
+        const columnOrder = gridColumnFieldsSelector(apiRef);
+        const firstOldRow = Array.from(oldRows.values())[0];
+        const [firstNewRowId, firstNewRow] = Array.from(newRows.entries())[0];
+        let differentFieldIndex = columnOrder.length - 1;
+        // Find the first field that is different to set the focus on
+        for (let i = 0; i < columnOrder.length; i += 1) {
+          const field = columnOrder[i];
+          if (!isDeepEqual(firstOldRow[field], firstNewRow[field])) {
+            differentFieldIndex = i;
+            break;
+          }
+        }
+
+        // Restore all rows to the pasted state
+        apiRef.current.updateRows(newRowsValues);
+        if (differentFieldIndex >= 0) {
+          requestAnimationFrame(() => {
+            apiRef.current.setCellFocus(firstNewRowId, columnOrder[differentFieldIndex]);
+            apiRef.current.scrollToIndexes({
+              rowIndex: apiRef.current.getRowIndexRelativeToVisibleRows(firstNewRowId),
+              colIndex: differentFieldIndex
+            });
+          });
+        }
+      }
+    }
+  };
+};
+
+/**
+ * Create the default history events map.
+ */
+export const createDefaultHistoryHandlers = (apiRef, props) => {
+  const handlers = {};
+  const canHaveEditing = props.isCellEditable || props.columns.some(col => col.editable);
+  if (!canHaveEditing) {
+    return handlers;
+  }
+  if (!props.dataSource || props.dataSource.updateRow) {
+    handlers.cellEditStop = createCellEditHistoryHandler(apiRef);
+    handlers.rowEditStop = createRowEditHistoryHandler(apiRef);
+  }
+  if (!props.dataSource) {
+    handlers.clipboardPasteEnd = createClipboardPasteHistoryHandler(apiRef);
+  }
+  return handlers;
+};

package/esm/hooks/features/history/gridHistoryInterfaces.d.ts

@@ -0,0 +1,95 @@
+import type { GridRowId, GridEvents, GridValidRowModel } from '@mui/x-data-grid-pro';
+/**
+ * Handler for a specific grid event
+ */
+export interface GridHistoryEventHandler<T = any> {
+  /**
+   * Store the data to be used for undo/redo operations.
+   * @param {any} params The parameters from the original event.
+   * @returns {T | null} The data to store in the history stack.
+   * Return `null` if the event should not be stored.
+   * This can be used to descrease the granularity of the undo steps.
+   */
+  store: (...params: any[]) => T | null;
+  /**
+   * Undo the changes made by this event.
+   * @param {T} data The stored data.
+   * @returns {boolean | Promise<boolean>} True if the operation was successful, false otherwise.
+   */
+  undo: (data: T) => void | Promise<void>;
+  /**
+   * Redo the changes made by this event.
+   * @param {T} data The stored data.
+   * @returns {boolean | Promise<boolean>} True if the operation was successful, false otherwise.
+   */
+  redo: (data: T) => void | Promise<void>;
+  /**
+   * Validate if the undo/redo operation can be performed.
+   * If validation is not needed, do not provide this method to avoid impacting performance.
+   * @param {T} data The stored data.
+   * @param {'undo' | 'redo'} operation - The operation to validate.
+   * @returns {boolean} True if the operation is valid, false otherwise.
+   */
+  validate?: (data: T, operation: 'undo' | 'redo') => boolean;
+}
+export interface GridHistoryItem<T = any> {
+  eventName: GridEvents;
+  data: T;
+}
+export interface GridHistoryState {
+  stack: GridHistoryItem[];
+  /**
+   * The current position in the stack.
+   * Points to the last executed action.
+   * -1 means no actions have been executed.
+   */
+  currentPosition: number;
+  /**
+   * True if the stack size is greater than 0 and there is at least one event handler.
+   */
+  enabled: boolean;
+}
+export interface GridHistoryApi {
+  /**
+   * The history API.
+   */
+  history: {
+    /**
+     * Undo the last action.
+     * @returns {Promise<boolean>} True if the operation was successful, false otherwise.
+     */
+    undo: () => Promise<boolean>;
+    /**
+     * Redo the last undone action.
+     * @returns {Promise<boolean>} True if the operation was successful, false otherwise.
+     */
+    redo: () => Promise<boolean>;
+    /**
+     * Clear the entire history.
+     */
+    clear: () => void;
+    /**
+     * @returns {boolean} True if there are undo steps available, false otherwise.
+     */
+    canUndo: () => boolean;
+    /**
+     * @returns {boolean} True if there are redo steps available, false otherwise.
+     */
+    canRedo: () => boolean;
+  };
+}
+export interface GridCellEditHistoryData {
+  id: GridRowId;
+  field: string;
+  oldValue: any;
+  newValue: any;
+}
+export interface GridRowEditHistoryData {
+  id: GridRowId;
+  oldRow: GridValidRowModel;
+  newRow: GridValidRowModel;
+}
+export interface GridClipboardPasteHistoryData {
+  oldRows: Map<GridRowId, GridValidRowModel>;
+  newRows: Map<GridRowId, GridValidRowModel>;
+}

package/esm/hooks/features/history/gridHistoryInterfaces.js

@@ -0,0 +1 @@
+export {};

package/esm/hooks/features/history/gridHistorySelectors.d.ts

@@ -0,0 +1,16 @@
+import type { GridStatePremium } from "../../../models/gridStatePremium.js";
+export declare const gridHistoryEnabledSelector: (args_0: import("react").RefObject<{
+  state: GridStatePremium;
+} | null>) => boolean;
+export declare const gridHistoryStackSelector: (args_0: import("react").RefObject<{
+  state: GridStatePremium;
+} | null>) => import("./gridHistoryInterfaces.js").GridHistoryItem<any>[];
+export declare const gridHistoryCurrentPositionSelector: (args_0: import("react").RefObject<{
+  state: GridStatePremium;
+} | null>) => number;
+export declare const gridHistoryCanUndoSelector: (args_0: import("react").RefObject<{
+  state: GridStatePremium;
+} | null>) => boolean;
+export declare const gridHistoryCanRedoSelector: (args_0: import("react").RefObject<{
+  state: GridStatePremium;
+} | null>) => boolean;

package/esm/hooks/features/history/gridHistorySelectors.js

@@ -0,0 +1,7 @@
+import { createSelector, createRootSelector } from '@mui/x-data-grid-pro/internals';
+const gridHistoryStateSelector = createRootSelector(state => state.history);
+export const gridHistoryEnabledSelector = createSelector(gridHistoryStateSelector, history => history.enabled);
+export const gridHistoryStackSelector = createSelector(gridHistoryStateSelector, history => history.stack);
+export const gridHistoryCurrentPositionSelector = createSelector(gridHistoryStateSelector, history => history.currentPosition);
+export const gridHistoryCanUndoSelector = createSelector(gridHistoryCurrentPositionSelector, currentPosition => currentPosition >= 0);
+export const gridHistoryCanRedoSelector = createSelector(gridHistoryStackSelector, gridHistoryCurrentPositionSelector, (stack, currentPosition) => currentPosition < stack.length - 1);

package/esm/hooks/features/history/index.d.ts

@@ -0,0 +1,3 @@
+export type { GridHistoryEventHandler } from "./gridHistoryInterfaces.js";
+export { createCellEditHistoryHandler, createRowEditHistoryHandler, createClipboardPasteHistoryHandler } from "./defaultHistoryHandlers.js";
+export { gridHistoryCanUndoSelector, gridHistoryCanRedoSelector, gridHistoryEnabledSelector } from "./gridHistorySelectors.js";

package/esm/hooks/features/history/index.js

@@ -0,0 +1,2 @@
+export { createCellEditHistoryHandler, createRowEditHistoryHandler, createClipboardPasteHistoryHandler } from "./defaultHistoryHandlers.js";
+export { gridHistoryCanUndoSelector, gridHistoryCanRedoSelector, gridHistoryEnabledSelector } from "./gridHistorySelectors.js";

package/esm/hooks/features/history/useGridHistory.d.ts

@@ -0,0 +1,6 @@
+import { RefObject } from '@mui/x-internals/types';
+import { GridStateInitializer } from '@mui/x-data-grid-pro/internals';
+import { GridPrivateApiPremium } from "../../../models/gridApiPremium.js";
+import { DataGridPremiumProcessedProps } from "../../../models/dataGridPremiumProps.js";
+export declare const historyStateInitializer: GridStateInitializer;
+export declare const useGridHistory: (apiRef: RefObject<GridPrivateApiPremium>, props: Pick<DataGridPremiumProcessedProps, "columns" | "isCellEditable" | "dataSource" | "historyStackSize" | "historyEventHandlers" | "historyValidationEvents" | "onUndo" | "onRedo">) => void;