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

package/hooks/features/history/useGridHistory.js

@@ -0,0 +1,303 @@
+"use strict";
+'use client';
+
+var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
+var _interopRequireDefault = require("@babel/runtime/helpers/interopRequireDefault").default;
+Object.defineProperty(exports, "__esModule", {
+  value: true
+});
+exports.useGridHistory = exports.historyStateInitializer = void 0;
+var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
+var React = _interopRequireWildcard(require("react"));
+var _isObjectEmpty = require("@mui/x-internals/isObjectEmpty");
+var _debounce = _interopRequireDefault(require("@mui/utils/debounce"));
+var _internals = require("@mui/x-data-grid-pro/internals");
+var _gridHistorySelectors = require("./gridHistorySelectors");
+var _defaultHistoryHandlers = require("./defaultHistoryHandlers");
+const historyStateInitializer = state => {
+  return (0, _extends2.default)({}, state, {
+    history: {
+      stack: [],
+      currentPosition: -1,
+      enabled: false
+    }
+  });
+};
+exports.historyStateInitializer = historyStateInitializer;
+const useGridHistory = (apiRef, props) => {
+  const {
+    historyStackSize,
+    onUndo,
+    onRedo,
+    historyValidationEvents
+  } = props;
+
+  // Use default history events if none provided
+  const historyEventHandlers = React.useMemo(() => {
+    if (props.historyEventHandlers && !(0, _isObjectEmpty.isObjectEmpty)(props.historyEventHandlers)) {
+      return props.historyEventHandlers;
+    }
+    return (0, _defaultHistoryHandlers.createDefaultHistoryHandlers)(apiRef, {
+      dataSource: props.dataSource,
+      columns: props.columns,
+      isCellEditable: props.isCellEditable
+    });
+  }, [apiRef, props.columns, props.isCellEditable, props.dataSource, props.historyEventHandlers]);
+  const isEnabled = React.useMemo(() => historyStackSize > 0 && !(0, _isObjectEmpty.isObjectEmpty)(historyEventHandlers), [historyStackSize, historyEventHandlers]);
+  const isValidationNeeded = React.useMemo(() => isEnabled && historyValidationEvents.length > 0 && Object.values(historyEventHandlers).some(handler => handler.validate), [isEnabled, historyEventHandlers, historyValidationEvents]);
+
+  // Internal ref to track undo/redo operation state
+  // - 'idle': everything is done
+  // - 'in-progress': during async undo/redo handler execution (skip validation and prevent the state change by other events)
+  // - 'waiting-replay': after undo/redo handler is done, the validation event is triggered again (as undo/redo is changing the state).
+  //   In this hook we want to skip the replayed event.
+  const operationStateRef = React.useRef('idle');
+
+  // History event unsubscribers
+  const eventUnsubscribersRef = React.useRef([]);
+  // Validation event unsubscribers
+  const validationEventUnsubscribersRef = React.useRef([]);
+  const updateHistoryState = React.useCallback(newState => {
+    apiRef.current.setState(state => (0, _extends2.default)({}, state, {
+      history: (0, _extends2.default)({}, state.history, newState)
+    }));
+  }, [apiRef]);
+  const addToStack = React.useCallback(item => {
+    const currentPosition = (0, _gridHistorySelectors.gridHistoryCurrentPositionSelector)(apiRef);
+    let newStack = [...(0, _gridHistorySelectors.gridHistoryStackSelector)(apiRef)];
+
+    // If we're not at the end of the stack, truncate forward history
+    if (currentPosition < newStack.length - 1) {
+      newStack = newStack.slice(0, currentPosition + 1);
+    }
+
+    // Add the new item
+    newStack.push(item);
+
+    // If stack exceeds size, remove oldest items
+    if (newStack.length > historyStackSize) {
+      newStack = newStack.slice(newStack.length - historyStackSize);
+    }
+    updateHistoryState({
+      stack: newStack,
+      currentPosition: newStack.length - 1
+    });
+  }, [apiRef, updateHistoryState, historyStackSize]);
+  const clear = React.useCallback(() => {
+    updateHistoryState({
+      stack: [],
+      currentPosition: -1
+    });
+  }, [updateHistoryState]);
+  const clearUndoItems = React.useCallback(() => {
+    const stack = (0, _gridHistorySelectors.gridHistoryStackSelector)(apiRef);
+    const currentPosition = (0, _gridHistorySelectors.gridHistoryCurrentPositionSelector)(apiRef);
+
+    // If we're at the end of the stack (no redo items), clear everything
+    if (currentPosition >= stack.length - 1) {
+      clear();
+    } else {
+      updateHistoryState({
+        stack: stack.slice(currentPosition + 1),
+        currentPosition: -1
+      });
+    }
+  }, [apiRef, clear, updateHistoryState]);
+  const clearRedoItems = React.useCallback(() => {
+    const stack = (0, _gridHistorySelectors.gridHistoryStackSelector)(apiRef);
+    const currentPosition = (0, _gridHistorySelectors.gridHistoryCurrentPositionSelector)(apiRef);
+    updateHistoryState({
+      stack: stack.slice(0, currentPosition + 1)
+    });
+  }, [apiRef, updateHistoryState]);
+  const canUndo = React.useCallback(() => (0, _gridHistorySelectors.gridHistoryCanUndoSelector)(apiRef), [apiRef]);
+  const canRedo = React.useCallback(() => (0, _gridHistorySelectors.gridHistoryCanRedoSelector)(apiRef), [apiRef]);
+  const validateStackItems = React.useCallback(() => {
+    /**
+     * When:
+     * - idle: continue with the validation
+     * - in-progress: skip the validation and don't change the state
+     * - waiting-replay: skip the validation this time and reset the state to idle
+     */
+    if (operationStateRef.current !== 'idle') {
+      if (operationStateRef.current === 'waiting-replay') {
+        operationStateRef.current = 'idle';
+      }
+      return;
+    }
+    const stack = (0, _gridHistorySelectors.gridHistoryStackSelector)(apiRef);
+    const currentPosition = (0, _gridHistorySelectors.gridHistoryCurrentPositionSelector)(apiRef);
+    if (historyStackSize === 0) {
+      if (stack.length > 0) {
+        clear();
+      }
+      return;
+    }
+    if (stack.length === 0) {
+      return;
+    }
+    const newStack = [...stack];
+
+    // Redo check
+    if (currentPosition + 1 < newStack.length) {
+      const item = newStack[currentPosition + 1];
+      const handler = historyEventHandlers[item.eventName];
+      if (!handler) {
+        clearRedoItems();
+      } else {
+        const isValid = handler.validate ? handler.validate(item.data, 'redo') : true;
+        if (!isValid) {
+          clearRedoItems();
+        }
+      }
+    }
+
+    // Undo check
+    if (currentPosition >= 0) {
+      const item = newStack[currentPosition];
+      const handler = historyEventHandlers[item.eventName];
+      if (!handler) {
+        clearUndoItems();
+      } else {
+        const isValid = handler.validate ? handler.validate(item.data, 'undo') : true;
+        if (!isValid) {
+          clearUndoItems();
+        }
+      }
+    }
+  }, [apiRef, historyEventHandlers, historyStackSize, clear, clearUndoItems, clearRedoItems]);
+  const debouncedValidateStackItems = React.useMemo(() => (0, _debounce.default)(validateStackItems, 0), [validateStackItems]);
+  const apply = React.useCallback(async (item, operation) => {
+    const currentPosition = (0, _gridHistorySelectors.gridHistoryCurrentPositionSelector)(apiRef);
+    const clearMethod = operation === 'undo' ? clearUndoItems : clearRedoItems;
+    const {
+      eventName,
+      data
+    } = item;
+    const handler = historyEventHandlers[eventName];
+    if (!handler) {
+      // If the handler is not found, it means tha we are updating the handlers map, so we can igore this request
+      return false;
+    }
+    const isValid = handler.validate ? handler.validate(data, operation) : true;
+
+    // The data is validated every time state change event happens.
+    // We can get into a situation where the operation is not valid at this point only with the direct state updates.
+    if (!isValid) {
+      // Clear history and return false
+      clearMethod();
+      return false;
+    }
+
+    // Execute the operation
+    operationStateRef.current = 'in-progress';
+    await handler[operation](data);
+    operationStateRef.current = 'waiting-replay';
+    updateHistoryState({
+      currentPosition: operation === 'undo' ? currentPosition - 1 : currentPosition + 1
+    });
+    apiRef.current.publishEvent(operation, {
+      eventName,
+      data
+    });
+    // If there are no validations in the current setup, skip calling it and change the operation state to idle
+    if (isValidationNeeded) {
+      validateStackItems();
+    } else {
+      operationStateRef.current = 'idle';
+    }
+    return true;
+  }, [apiRef, isValidationNeeded, historyEventHandlers, clearUndoItems, clearRedoItems, updateHistoryState, validateStackItems]);
+  const undo = React.useCallback(async () => {
+    if (!canUndo()) {
+      return false;
+    }
+    const stack = (0, _gridHistorySelectors.gridHistoryStackSelector)(apiRef);
+    const currentPosition = (0, _gridHistorySelectors.gridHistoryCurrentPositionSelector)(apiRef);
+    return apply(stack[currentPosition], 'undo');
+  }, [apiRef, apply, canUndo]);
+  const redo = React.useCallback(async () => {
+    if (!canRedo()) {
+      return false;
+    }
+    const stack = (0, _gridHistorySelectors.gridHistoryStackSelector)(apiRef);
+    const currentPosition = (0, _gridHistorySelectors.gridHistoryCurrentPositionSelector)(apiRef);
+    return apply(stack[currentPosition + 1], 'redo');
+  }, [apiRef, apply, canRedo]);
+  const historyApi = {
+    undo,
+    redo,
+    clear,
+    canUndo,
+    canRedo
+  };
+  (0, _internals.useGridApiMethod)(apiRef, {
+    history: historyApi
+  }, 'public');
+  const handleKeyDown = React.useCallback(async event => {
+    if (!(0, _internals.isUndoShortcut)(event) && !(0, _internals.isRedoShortcut)(event)) {
+      return;
+    }
+    const action = (0, _internals.isUndoShortcut)(event) ? apiRef.current.history.undo : apiRef.current.history.redo;
+    event.preventDefault();
+    event.stopPropagation();
+    await action();
+  }, [apiRef]);
+  (0, _internals.useGridNativeEventListener)(apiRef, () => apiRef.current.rootElementRef.current, 'keydown', (0, _internals.runIf)(isEnabled, handleKeyDown));
+  (0, _internals.useGridEvent)(apiRef, 'undo', onUndo);
+  (0, _internals.useGridEvent)(apiRef, 'redo', onRedo);
+  React.useEffect(() => {
+    updateHistoryState({
+      enabled: isEnabled
+    });
+  }, [isEnabled, updateHistoryState]);
+  React.useEffect(() => {
+    if (!isValidationNeeded) {
+      return () => {};
+    }
+    historyValidationEvents.forEach(eventName => {
+      validationEventUnsubscribersRef.current.push(apiRef.current.subscribeEvent(eventName, debouncedValidateStackItems));
+    });
+    return () => {
+      validationEventUnsubscribersRef.current.forEach(unsubscribe => unsubscribe());
+      validationEventUnsubscribersRef.current = [];
+    };
+  }, [apiRef, isValidationNeeded, historyValidationEvents, debouncedValidateStackItems]);
+  React.useEffect(() => {
+    if (historyStackSize === 0) {
+      return () => {};
+    }
+    const events = Object.keys(historyEventHandlers);
+    // Subscribe to all events in the map
+    events.forEach(eventName => {
+      const handler = historyEventHandlers[eventName];
+      const unsubscribe = apiRef.current.subscribeEvent(eventName, (...params) => {
+        // Don't store if the event was triggered by undo/redo
+        if (operationStateRef.current !== 'idle') {
+          return;
+        }
+        const data = handler.store(...params);
+        if (data !== null) {
+          addToStack({
+            eventName,
+            data
+          });
+        }
+      });
+      eventUnsubscribersRef.current.push(unsubscribe);
+    });
+    return () => {
+      eventUnsubscribersRef.current.forEach(unsubscribe => unsubscribe());
+      eventUnsubscribersRef.current = [];
+    };
+  }, [apiRef, historyEventHandlers, historyStackSize, addToStack]);
+
+  // If the stack size is changed and it is smaller than the current stack size, clear the stack
+  React.useEffect(() => {
+    const currentStackSize = (0, _gridHistorySelectors.gridHistoryStackSelector)(apiRef).length;
+    if (currentStackSize > historyStackSize) {
+      clear();
+    }
+  }, [apiRef, historyStackSize, clear]);
+};
+exports.useGridHistory = useGridHistory;

package/hooks/features/index.d.ts

@@ -4,4 +4,5 @@ export * from "./export/index.js";
 export * from "./cellSelection/index.js";
 export * from "./aiAssistant/index.js";
 export * from "./sidebar/index.js";
-export * from "./pivoting/index.js";
+export * from "./pivoting/index.js";
+export * from "./history/index.js";

package/hooks/features/index.js

@@ -79,4 +79,15 @@ Object.keys(_pivoting).forEach(function (key) {
       return _pivoting[key];
     }
   });
+});
+var _history = require("./history");
+Object.keys(_history).forEach(function (key) {
+  if (key === "default" || key === "__esModule") return;
+  if (key in exports && exports[key] === _history[key]) return;
+  Object.defineProperty(exports, key, {
+    enumerable: true,
+    get: function () {
+      return _history[key];
+    }
+  });
 });

package/hooks/utils/useGridChartIntegration.js

@@ -1,4 +1,5 @@
 "use strict";
+'use client';
 
 var _interopRequireWildcard = require("@babel/runtime/helpers/interopRequireWildcard").default;
 Object.defineProperty(exports, "__esModule", {

package/index.js

@@ -1,5 +1,5 @@
 /**
- * @mui/x-data-grid-premium v8.24.0
+ * @mui/x-data-grid-premium v8.26.0
  *
  * @license SEE LICENSE IN LICENSE
  * This source code is licensed under the SEE LICENSE IN LICENSE license found in the

package/models/dataGridPremiumProps.d.ts

@@ -1,5 +1,5 @@
 import { RefObject } from '@mui/x-internals/types';
-import { GridCallbackDetails, GridValidRowModel, GridGroupNode, GridEventListener, GridGetRowsError, GridUpdateRowError, type GridColDef, GridLocaleTextApi } from '@mui/x-data-grid-pro';
+import { GridCallbackDetails, GridValidRowModel, GridGroupNode, GridEventListener, GridGetRowsError, GridUpdateRowError, type GridColDef, GridLocaleTextApi, type GridEvents } from '@mui/x-data-grid-pro';
 import { GridExperimentalProFeatures, DataGridProPropsWithDefaultValue, DataGridProPropsWithoutDefaultValue, DataGridPropsWithComplexDefaultValueAfterProcessing, DataGridPropsWithComplexDefaultValueBeforeProcessing, DataGridPremiumSharedPropsWithDefaultValue } from '@mui/x-data-grid-pro/internals';
 import type { GridRowGroupingModel } from "../hooks/features/rowGrouping/index.js";
 import type { GridAggregationModel, GridAggregationFunction, GridAggregationFunctionDataSource, GridAggregationPosition } from "../hooks/features/aggregation/index.js";
@@ -11,6 +11,7 @@ import { GridCellSelectionModel } from "../hooks/features/cellSelection/index.js
 import type { GridPivotingColDefOverrides, PivotingColDefCallback, GridPivotModel } from "../hooks/features/pivoting/gridPivotingInterfaces.js";
 import { GridDataSourcePremium as GridDataSource, GridGetRowsParamsPremium as GridGetRowsParams } from "../hooks/features/dataSource/models.js";
 import { Conversation, PromptResponse, PromptSuggestion } from "../hooks/features/aiAssistant/gridAiAssistantInterfaces.js";
+import type { GridHistoryEventHandler } from "../hooks/features/history/gridHistoryInterfaces.js";
 export interface GridExperimentalPremiumFeatures extends GridExperimentalProFeatures {
   charts?: boolean;
 }
@@ -101,6 +102,22 @@ export interface DataGridPremiumPropsWithDefaultValue<R extends GridValidRowMode
    * @default false
    */
   chartsIntegration: boolean;
+  /**
+   * The maximum size of the history stack.
+   * Set to 0 to disable the undo/redo feature.
+   * @default 30
+   */
+  historyStackSize: number;
+  /**
+   * Map of grid events to their undo/redo handlers.
+   * @default Handlers for `rowEditStop`, `cellEditStop` and `clipboardPasteEnd` events
+   */
+  historyEventHandlers: Record<GridEvents, GridHistoryEventHandler<any>>;
+  /**
+   * List of grid events after which the history stack items should be re-validated.
+   * @default ['columnsChange', 'rowsSet', 'sortedRowsSet', 'filteredRowsSet', 'paginationModelChange']
+   */
+  historyValidationEvents: GridEvents[];
 }
 export interface DataGridPremiumPropsWithoutDefaultValue<R extends GridValidRowModel = any> extends Omit<DataGridProPropsWithoutDefaultValue<R>, 'initialState' | 'apiRef' | 'dataSource' | 'onDataSourceError'> {
   /**
@@ -292,4 +309,12 @@ export interface DataGridPremiumPropsWithoutDefaultValue<R extends GridValidRowM
    * @param {string} activeChartId The new active chart id.
    */
   onActiveChartIdChange?: (activeChartId: string) => void;
+  /**
+   * Callback fired when an undo operation is executed.
+   */
+  onUndo?: GridEventListener<'undo'>;
+  /**
+   * Callback fired when a redo operation is executed.
+   */
+  onRedo?: GridEventListener<'redo'>;
 }

package/models/gridApiPremium.d.ts

@@ -11,9 +11,10 @@ import type { GridPivotingApi, GridPivotingPrivateApi } from "../hooks/features/
 import { GridAiAssistantApi } from "../hooks/features/aiAssistant/gridAiAssistantInterfaces.js";
 import { GridSidebarApi } from "../hooks/features/sidebar/gridSidebarInterfaces.js";
 import { GridChartsIntegrationApi, GridChartsIntegrationPrivateApi } from "../hooks/features/chartsIntegration/gridChartsIntegrationInterfaces.js";
+import type { GridHistoryApi } from "../hooks/features/history/gridHistoryInterfaces.js";
 /**
  * The api of Data Grid Premium.
  * TODO: Do not redefine manually the pro features
  */
-export interface GridApiPremium extends GridApiCommon<GridStatePremium, GridInitialStatePremium>, GridRowProApi, GridColumnPinningApi, GridDetailPanelApi, GridRowGroupingApi, GridExcelExportApi, GridAggregationApi, GridRowPinningApi, GridDataSourceApiPremium, GridCellSelectionApi, GridPivotingApi, GridAiAssistantApi, GridSidebarApi, GridChartsIntegrationApi, GridRowMultiSelectionApi, GridColumnReorderApi {}
+export interface GridApiPremium extends GridApiCommon<GridStatePremium, GridInitialStatePremium>, GridRowProApi, GridColumnPinningApi, GridDetailPanelApi, GridRowGroupingApi, GridExcelExportApi, GridAggregationApi, GridRowPinningApi, GridDataSourceApiPremium, GridCellSelectionApi, GridPivotingApi, GridAiAssistantApi, GridSidebarApi, GridChartsIntegrationApi, GridHistoryApi, GridRowMultiSelectionApi, GridColumnReorderApi {}
 export interface GridPrivateApiPremium extends GridApiPremium, GridPrivateOnlyApiCommon<GridApiPremium, GridPrivateApiPremium, DataGridPremiumProcessedProps>, GridDataSourcePremiumPrivateApi, GridAggregationPrivateApi, GridDetailPanelPrivateApi, GridRowReorderPrivateApi, GridPivotingPrivateApi, GridChartsIntegrationPrivateApi {}

package/models/gridStatePremium.d.ts

@@ -4,6 +4,7 @@ import type { GridPivotingInitialState, GridPivotingState } from "../hooks/featu
 import type { GridAiAssistantInitialState, GridAiAssistantState } from "../hooks/features/aiAssistant/gridAiAssistantInterfaces.js";
 import type { GridSidebarInitialState, GridSidebarState } from "../hooks/features/sidebar/gridSidebarState.js";
 import type { GridChartsIntegrationState, GridChartsIntegrationInitialState } from "../hooks/features/chartsIntegration/gridChartsIntegrationInterfaces.js";
+import type { GridHistoryState } from "../hooks/features/history/gridHistoryInterfaces.js";
 /**
  * The state of Data Grid Premium.
  */
@@ -15,6 +16,7 @@ export interface GridStatePremium extends GridStatePro {
   aiAssistant: GridAiAssistantState;
   sidebar: GridSidebarState;
   chartsIntegration: GridChartsIntegrationState;
+  history: GridHistoryState;
 }
 /**
  * The initial state of Data Grid Premium.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/x-data-grid-premium",
-  "version": "8.24.0",
+  "version": "8.26.0",
   "author": "MUI Team",
   "description": "The Premium plan edition of the MUI X Data Grid Components.",
   "license": "SEE LICENSE IN LICENSE",
@@ -38,10 +38,10 @@
     "@mui/x-internal-exceljs-fork": "4.4.3",
     "clsx": "^2.1.1",
     "prop-types": "^15.8.1",
-    "@mui/x-data-grid": "8.24.0",
-    "@mui/x-data-grid-pro": "8.24.0",
-    "@mui/x-license": "8.24.0",
-    "@mui/x-internals": "8.24.0"
+    "@mui/x-data-grid": "8.26.0",
+    "@mui/x-internals": "8.26.0",
+    "@mui/x-data-grid-pro": "8.26.0",
+    "@mui/x-license": "8.26.0"
   },
   "peerDependencies": {
     "@emotion/react": "^11.9.0",

package/typeOverloads/modules.d.ts

@@ -1,4 +1,4 @@
-import type { GridExportDisplayOptions, GridValidRowModel } from '@mui/x-data-grid-pro';
+import { GridEventLookup, GridExportDisplayOptions, GridRowId, GridValidRowModel } from '@mui/x-data-grid-pro';
 import type { GridAggregationCellMeta } from '@mui/x-data-grid-pro/internals';
 import type { GridPipeProcessingLookupPro, GridControlledStateEventLookupPro, GridApiCachesPro, GridEventLookupPro } from '@mui/x-data-grid-pro/typeOverloads';
 import type { GridGroupingValueGetter, GridGroupingValueSetter, GridPastedValueParser } from "../models/index.js";
@@ -79,7 +79,12 @@ interface GridEventLookupPremium extends GridEventLookupPro {
   /**
    * Fired when the clipboard paste operation ends.
    */
-  clipboardPasteEnd: {};
+  clipboardPasteEnd: {
+    params: {
+      oldRows: Map<GridRowId, GridValidRowModel>;
+      newRows: Map<GridRowId, GridValidRowModel>;
+    };
+  };
   /**
    * Fired when the sidebar is opened.
    */
@@ -105,6 +110,24 @@ interface GridEventLookupPremium extends GridEventLookupPro {
       synced: boolean;
     };
   };
+  /**
+   * Fired when an undo operation is executed.
+   */
+  undo: {
+    params: {
+      eventName: keyof GridEventLookup;
+      data: any;
+    };
+  };
+  /**
+   * Fired when a redo operation is executed.
+   */
+  redo: {
+    params: {
+      eventName: keyof GridEventLookup;
+      data: any;
+    };
+  };
 }
 export interface GridColDefPremium<R extends GridValidRowModel = any, V = any, F = V> {
   /**

package/typeOverloads/modules.js

@@ -1,5 +1,3 @@
 "use strict";
 
-Object.defineProperty(exports, "__esModule", {
-  value: true
-});
+var _xDataGridPro = require("@mui/x-data-grid-pro");