@mui/x-data-grid 9.12.0 → 9.14.0

package/hooks/features/rowSelection/useGridRowSelection.d.mts

@@ -9,4 +9,4 @@ export declare const rowSelectionStateInitializer: GridStateInitializer<Pick<Dat
  * @requires useGridFocus (state) - can be after
  * @requires useGridKeyboardNavigation (`cellKeyDown` event must first be consumed by it)
  */
-export declare const useGridRowSelection: (apiRef: RefObject<GridPrivateApiCommunity>, props: Pick<DataGridProcessedProps, 'checkboxSelection' | 'rowSelectionModel' | 'onRowSelectionModelChange' | 'disableMultipleRowSelection' | 'disableRowSelectionOnClick' | 'disableRowSelectionExcludeModel' | 'isRowSelectable' | 'checkboxSelectionVisibleOnly' | 'pagination' | 'paginationMode' | 'filterMode' | 'classes' | 'keepNonExistentRowsSelected' | 'rowSelection' | 'rowSelectionPropagation' | 'signature'>) => void;
+export declare const useGridRowSelection: (apiRef: RefObject<GridPrivateApiCommunity>, props: Pick<DataGridProcessedProps, 'checkboxSelection' | 'rowSelectionModel' | 'onRowSelectionModelChange' | 'disableMultipleRowSelection' | 'disableRowSelectionOnClick' | 'disableRowSelectionExcludeModel' | 'isRowSelectable' | 'checkboxSelectionVisibleOnly' | 'pagination' | 'paginationMode' | 'filterMode' | 'classes' | 'keepNonExistentRowsSelected' | 'rowSelection' | 'rowSelectionPropagation' | 'dataSource' | 'signature'>) => void;

package/hooks/features/rowSelection/useGridRowSelection.d.ts

@@ -9,4 +9,4 @@ export declare const rowSelectionStateInitializer: GridStateInitializer<Pick<Dat
  * @requires useGridFocus (state) - can be after
  * @requires useGridKeyboardNavigation (`cellKeyDown` event must first be consumed by it)
  */
-export declare const useGridRowSelection: (apiRef: RefObject<GridPrivateApiCommunity>, props: Pick<DataGridProcessedProps, 'checkboxSelection' | 'rowSelectionModel' | 'onRowSelectionModelChange' | 'disableMultipleRowSelection' | 'disableRowSelectionOnClick' | 'disableRowSelectionExcludeModel' | 'isRowSelectable' | 'checkboxSelectionVisibleOnly' | 'pagination' | 'paginationMode' | 'filterMode' | 'classes' | 'keepNonExistentRowsSelected' | 'rowSelection' | 'rowSelectionPropagation' | 'signature'>) => void;
+export declare const useGridRowSelection: (apiRef: RefObject<GridPrivateApiCommunity>, props: Pick<DataGridProcessedProps, 'checkboxSelection' | 'rowSelectionModel' | 'onRowSelectionModelChange' | 'disableMultipleRowSelection' | 'disableRowSelectionOnClick' | 'disableRowSelectionExcludeModel' | 'isRowSelectable' | 'checkboxSelectionVisibleOnly' | 'pagination' | 'paginationMode' | 'filterMode' | 'classes' | 'keepNonExistentRowsSelected' | 'rowSelection' | 'rowSelectionPropagation' | 'dataSource' | 'signature'>) => void;

package/hooks/features/rowSelection/useGridRowSelection.js

@@ -17,6 +17,7 @@ var _useGridApiMethod = require("../../utils/useGridApiMethod");
 var _useGridLogger = require("../../utils/useGridLogger");
 var _useGridSelector = require("../../utils/useGridSelector");
 var _gridRowsSelector = require("../rows/gridRowsSelector");
+var _gridRowsUtils = require("../rows/gridRowsUtils");
 var _gridRowSelectionSelector = require("./gridRowSelectionSelector");
 var _gridFocusStateSelector = require("../focus/gridFocusStateSelector");
 var _gridFilterSelector = require("../filter/gridFilterSelector");
@@ -127,6 +128,10 @@ You need to upgrade to DataGridPro or DataGridPremium component to unlock multip
     if (props.rowSelection === false) {
       return false;
     }
+    const rowNode = (0, _gridRowsSelector.gridRowNodeSelector)(apiRef, id);
+    if (rowNode?.type === 'footer' || rowNode?.type === 'pinnedRow' || rowNode?.type === 'skeletonRow') {
+      return false;
+    }
 
     // If `keepNonExistentRowsSelected` is true, we might run in a case where row selectability is checked for a row that does not exist.
     // Since that row was previously selected (otherwise it would not be checked at this point), we return true.
@@ -136,10 +141,6 @@ You need to upgrade to DataGridPro or DataGridPremium component to unlock multip
     if (propIsRowSelectable && !propIsRowSelectable(apiRef.current.getRowParams(id))) {
       return false;
     }
-    const rowNode = (0, _gridRowsSelector.gridRowNodeSelector)(apiRef, id);
-    if (rowNode?.type === 'footer' || rowNode?.type === 'pinnedRow') {
-      return false;
-    }
     return true;
   }, [apiRef, props.rowSelection, props.keepNonExistentRowsSelected, propIsRowSelectable]);
   const getSelectedRows = React.useCallback(() => (0, _gridRowSelectionSelector.gridRowSelectionIdsSelector)(apiRef), [apiRef]);
@@ -315,6 +316,7 @@ You need to upgrade to DataGridPro or DataGridPremium component to unlock multip
    * EVENTS
    */
   const isFirstRender = React.useRef(true);
+  const previousRowsLookupRef = React.useRef(null);
   const removeOutdatedSelection = React.useCallback(() => {
     if (isFirstRender.current) {
       return;
@@ -323,6 +325,11 @@ You need to upgrade to DataGridPro or DataGridPremium component to unlock multip
     const rowsLookup = (0, _gridRowsSelector.gridRowsLookupSelector)(apiRef);
     const rowTree = (0, _gridRowsSelector.gridRowTreeSelector)(apiRef);
     const filteredRowsLookup = (0, _gridFilterSelector.gridFilteredRowsLookupSelector)(apiRef);
+    const previousRowsLookup = previousRowsLookupRef.current;
+    previousRowsLookupRef.current = rowsLookup;
+    // Read the depth at call time. The event that runs this callback can fire in the same
+    // tick as the state update that changes the depth, before the render-scope value updates.
+    const isNested = (0, _gridRowsSelector.gridRowMaximumTreeDepthSelector)(apiRef) > 1;
     const isNonExistent = id => {
       if (props.filterMode === 'server') {
         return !rowsLookup[id];
@@ -350,6 +357,32 @@ You need to upgrade to DataGridPro or DataGridPremium component to unlock multip
       return node.children.some(childId => isOrHasSelectableDescendant(childId));
     };
     let hasChanged = false;
+
+    // Rows can load after their parent was selected (server-side lazy loading).
+    // They arrive unselected, so the parent re-derivation below would drop the parent.
+    // With `rowSelectionPropagation.descendants`, the rows that appeared since the last run
+    // inherit the selection state of their closest previously known ancestor instead.
+    if (isNested && props.rowSelectionPropagation?.descendants && currentSelection.type === 'include' && currentSelection.ids.size > 0 && previousRowsLookup !== null && previousRowsLookup !== rowsLookup) {
+      const isNewRow = id => rowsLookup[id] !== undefined && previousRowsLookup[id] === undefined;
+      const inheritsSelection = id => {
+        const parentId = rowTree[id]?.parent;
+        if (parentId == null || parentId === _gridRowsUtils.GRID_ROOT_GROUP_ID) {
+          return false;
+        }
+        if (selectionManager.has(parentId)) {
+          return true;
+        }
+        // A row that appeared together with its parent reads the state further up the chain.
+        return isNewRow(parentId) ? inheritsSelection(parentId) : false;
+      };
+      const dataRowIds = (0, _gridRowsSelector.gridDataRowIdsSelector)(apiRef);
+      for (const id of dataRowIds) {
+        if (isNewRow(id) && filteredRowsLookup[id] !== false && inheritsSelection(id) && apiRef.current.isRowSelectable(id)) {
+          selectionManager.select(id);
+          hasChanged = true;
+        }
+      }
+    }
     for (const id of currentSelection.ids) {
       if (isNonExistent(id)) {
         if (props.keepNonExistentRowsSelected) {
@@ -382,9 +415,10 @@ You need to upgrade to DataGridPro or DataGridPremium component to unlock multip
     // For nested data, on row tree updation (filtering, adding rows, etc.) when the selection is
     // not empty, we need to re-run scanning of the tree to propagate the selection changes
     // Example: A parent whose de-selected children are filtered out should now be selected
-    const shouldReapplyPropagation = isNestedData && props.rowSelectionPropagation?.parents && (newSelectionModel.ids.size > 0 ||
-    // In case of exclude selection, newSelectionModel.ids.size === 0 means all rows are selected
-    newSelectionModel.type === 'exclude');
+    // With a data source, an `exclude` model is left alone: the grid only knows the loaded
+    // subset of the rows, so rewriting the model into an `include` of the known rows would
+    // drop the "rows that load later are selected too" semantics of the select-all state.
+    const shouldReapplyPropagation = isNested && props.rowSelectionPropagation?.parents && (newSelectionModel.type === 'exclude' ? props.dataSource === undefined : newSelectionModel.ids.size > 0);
     if (hasChanged || shouldReapplyPropagation) {
       if (shouldReapplyPropagation) {
         if (newSelectionModel.type === 'exclude') {
@@ -398,13 +432,20 @@ You need to upgrade to DataGridPro or DataGridPremium component to unlock multip
           }
           apiRef.current.selectRows(selectedRowIds, true, true);
         } else {
-          apiRef.current.selectRows(Array.from(newSelectionModel.ids), true, true);
+          // `getPropagatedRowSelectionModel` reads the sibling selection state from the model
+          // built above, so the rows selected during this run count for the parent derivation.
+          // `selectRows` would read the state from before this run instead.
+          const propagatedModel = apiRef.current.getPropagatedRowSelectionModel(newSelectionModel);
+          const isSelectionValid = propagatedModel.ids.size < 2 || canHaveMultipleSelection;
+          if (isSelectionValid && (propagatedModel.type !== currentSelection.type || propagatedModel.ids.size !== currentSelection.ids.size || !Array.from(propagatedModel.ids).every(id => currentSelection.ids.has(id)))) {
+            apiRef.current.setRowSelectionModel(propagatedModel, 'multipleRowsSelection');
+          }
         }
       } else {
         apiRef.current.setRowSelectionModel(newSelectionModel, 'multipleRowsSelection');
       }
     }
-  }, [apiRef, isNestedData, props.rowSelectionPropagation?.parents, props.keepNonExistentRowsSelected, props.filterMode, getRowsToBeSelected]);
+  }, [apiRef, props.rowSelectionPropagation?.parents, props.rowSelectionPropagation?.descendants, props.keepNonExistentRowsSelected, props.filterMode, props.dataSource, canHaveMultipleSelection, getRowsToBeSelected]);
   const handleSingleRowSelection = React.useCallback((id, event) => {
     const hasCtrlKey = event.metaKey || event.ctrlKey;
 
@@ -542,7 +583,7 @@ You need to upgrade to DataGridPro or DataGridPremium component to unlock multip
       handleSingleRowSelection(params.id, event);
       return;
     }
-    if (String.fromCharCode(event.keyCode) === 'A' && (event.ctrlKey || event.metaKey)) {
+    if ((0, _keyboardUtils.isSelectAllShortcut)(event)) {
       event.preventDefault();
       if (canHaveMultipleSelection) {
         toggleAllRows(true);

package/hooks/features/rowSelection/useGridRowSelection.mjs

@@ -9,13 +9,14 @@ import { useGridEvent } from "../../utils/useGridEvent.mjs";
 import { useGridApiMethod } from "../../utils/useGridApiMethod.mjs";
 import { useGridLogger } from "../../utils/useGridLogger.mjs";
 import { useGridSelector } from "../../utils/useGridSelector.mjs";
-import { gridRowsLookupSelector, gridRowMaximumTreeDepthSelector, gridRowNodeSelector, gridRowTreeSelector } from "../rows/gridRowsSelector.mjs";
+import { gridDataRowIdsSelector, gridRowsLookupSelector, gridRowMaximumTreeDepthSelector, gridRowNodeSelector, gridRowTreeSelector } from "../rows/gridRowsSelector.mjs";
+import { GRID_ROOT_GROUP_ID } from "../rows/gridRowsUtils.mjs";
 import { gridRowSelectionManagerSelector, gridRowSelectionStateSelector, gridRowSelectionCountSelector, gridRowSelectionIdsSelector } from "./gridRowSelectionSelector.mjs";
 import { gridFocusCellSelector } from "../focus/gridFocusStateSelector.mjs";
 import { gridExpandedSortedRowIdsSelector, gridFilteredRowsLookupSelector, gridFilterModelSelector, gridQuickFilterValuesSelector } from "../filter/gridFilterSelector.mjs";
 import { GRID_CHECKBOX_SELECTION_COL_DEF, GRID_ACTIONS_COLUMN_TYPE } from "../../../colDef/index.mjs";
 import { GridCellModes } from "../../../models/gridEditRowModel.mjs";
-import { isKeyboardEvent, isNavigationKey } from "../../../utils/keyboardUtils.mjs";
+import { isKeyboardEvent, isNavigationKey, isSelectAllShortcut } from "../../../utils/keyboardUtils.mjs";
 import { getVisibleRows } from "../../utils/useGridVisibleRows.mjs";
 import { GRID_DETAIL_PANEL_TOGGLE_FIELD } from "../../../internals/constants.mjs";
 import { gridClasses } from "../../../constants/gridClasses.mjs";
@@ -119,6 +120,10 @@ You need to upgrade to DataGridPro or DataGridPremium component to unlock multip
     if (props.rowSelection === false) {
       return false;
     }
+    const rowNode = gridRowNodeSelector(apiRef, id);
+    if (rowNode?.type === 'footer' || rowNode?.type === 'pinnedRow' || rowNode?.type === 'skeletonRow') {
+      return false;
+    }
 
     // If `keepNonExistentRowsSelected` is true, we might run in a case where row selectability is checked for a row that does not exist.
     // Since that row was previously selected (otherwise it would not be checked at this point), we return true.
@@ -128,10 +133,6 @@ You need to upgrade to DataGridPro or DataGridPremium component to unlock multip
     if (propIsRowSelectable && !propIsRowSelectable(apiRef.current.getRowParams(id))) {
       return false;
     }
-    const rowNode = gridRowNodeSelector(apiRef, id);
-    if (rowNode?.type === 'footer' || rowNode?.type === 'pinnedRow') {
-      return false;
-    }
     return true;
   }, [apiRef, props.rowSelection, props.keepNonExistentRowsSelected, propIsRowSelectable]);
   const getSelectedRows = React.useCallback(() => gridRowSelectionIdsSelector(apiRef), [apiRef]);
@@ -307,6 +308,7 @@ You need to upgrade to DataGridPro or DataGridPremium component to unlock multip
    * EVENTS
    */
   const isFirstRender = React.useRef(true);
+  const previousRowsLookupRef = React.useRef(null);
   const removeOutdatedSelection = React.useCallback(() => {
     if (isFirstRender.current) {
       return;
@@ -315,6 +317,11 @@ You need to upgrade to DataGridPro or DataGridPremium component to unlock multip
     const rowsLookup = gridRowsLookupSelector(apiRef);
     const rowTree = gridRowTreeSelector(apiRef);
     const filteredRowsLookup = gridFilteredRowsLookupSelector(apiRef);
+    const previousRowsLookup = previousRowsLookupRef.current;
+    previousRowsLookupRef.current = rowsLookup;
+    // Read the depth at call time. The event that runs this callback can fire in the same
+    // tick as the state update that changes the depth, before the render-scope value updates.
+    const isNested = gridRowMaximumTreeDepthSelector(apiRef) > 1;
     const isNonExistent = id => {
       if (props.filterMode === 'server') {
         return !rowsLookup[id];
@@ -342,6 +349,32 @@ You need to upgrade to DataGridPro or DataGridPremium component to unlock multip
       return node.children.some(childId => isOrHasSelectableDescendant(childId));
     };
     let hasChanged = false;
+
+    // Rows can load after their parent was selected (server-side lazy loading).
+    // They arrive unselected, so the parent re-derivation below would drop the parent.
+    // With `rowSelectionPropagation.descendants`, the rows that appeared since the last run
+    // inherit the selection state of their closest previously known ancestor instead.
+    if (isNested && props.rowSelectionPropagation?.descendants && currentSelection.type === 'include' && currentSelection.ids.size > 0 && previousRowsLookup !== null && previousRowsLookup !== rowsLookup) {
+      const isNewRow = id => rowsLookup[id] !== undefined && previousRowsLookup[id] === undefined;
+      const inheritsSelection = id => {
+        const parentId = rowTree[id]?.parent;
+        if (parentId == null || parentId === GRID_ROOT_GROUP_ID) {
+          return false;
+        }
+        if (selectionManager.has(parentId)) {
+          return true;
+        }
+        // A row that appeared together with its parent reads the state further up the chain.
+        return isNewRow(parentId) ? inheritsSelection(parentId) : false;
+      };
+      const dataRowIds = gridDataRowIdsSelector(apiRef);
+      for (const id of dataRowIds) {
+        if (isNewRow(id) && filteredRowsLookup[id] !== false && inheritsSelection(id) && apiRef.current.isRowSelectable(id)) {
+          selectionManager.select(id);
+          hasChanged = true;
+        }
+      }
+    }
     for (const id of currentSelection.ids) {
       if (isNonExistent(id)) {
         if (props.keepNonExistentRowsSelected) {
@@ -374,9 +407,10 @@ You need to upgrade to DataGridPro or DataGridPremium component to unlock multip
     // For nested data, on row tree updation (filtering, adding rows, etc.) when the selection is
     // not empty, we need to re-run scanning of the tree to propagate the selection changes
     // Example: A parent whose de-selected children are filtered out should now be selected
-    const shouldReapplyPropagation = isNestedData && props.rowSelectionPropagation?.parents && (newSelectionModel.ids.size > 0 ||
-    // In case of exclude selection, newSelectionModel.ids.size === 0 means all rows are selected
-    newSelectionModel.type === 'exclude');
+    // With a data source, an `exclude` model is left alone: the grid only knows the loaded
+    // subset of the rows, so rewriting the model into an `include` of the known rows would
+    // drop the "rows that load later are selected too" semantics of the select-all state.
+    const shouldReapplyPropagation = isNested && props.rowSelectionPropagation?.parents && (newSelectionModel.type === 'exclude' ? props.dataSource === undefined : newSelectionModel.ids.size > 0);
     if (hasChanged || shouldReapplyPropagation) {
       if (shouldReapplyPropagation) {
         if (newSelectionModel.type === 'exclude') {
@@ -390,13 +424,20 @@ You need to upgrade to DataGridPro or DataGridPremium component to unlock multip
           }
           apiRef.current.selectRows(selectedRowIds, true, true);
         } else {
-          apiRef.current.selectRows(Array.from(newSelectionModel.ids), true, true);
+          // `getPropagatedRowSelectionModel` reads the sibling selection state from the model
+          // built above, so the rows selected during this run count for the parent derivation.
+          // `selectRows` would read the state from before this run instead.
+          const propagatedModel = apiRef.current.getPropagatedRowSelectionModel(newSelectionModel);
+          const isSelectionValid = propagatedModel.ids.size < 2 || canHaveMultipleSelection;
+          if (isSelectionValid && (propagatedModel.type !== currentSelection.type || propagatedModel.ids.size !== currentSelection.ids.size || !Array.from(propagatedModel.ids).every(id => currentSelection.ids.has(id)))) {
+            apiRef.current.setRowSelectionModel(propagatedModel, 'multipleRowsSelection');
+          }
         }
       } else {
         apiRef.current.setRowSelectionModel(newSelectionModel, 'multipleRowsSelection');
       }
     }
-  }, [apiRef, isNestedData, props.rowSelectionPropagation?.parents, props.keepNonExistentRowsSelected, props.filterMode, getRowsToBeSelected]);
+  }, [apiRef, props.rowSelectionPropagation?.parents, props.rowSelectionPropagation?.descendants, props.keepNonExistentRowsSelected, props.filterMode, props.dataSource, canHaveMultipleSelection, getRowsToBeSelected]);
   const handleSingleRowSelection = React.useCallback((id, event) => {
     const hasCtrlKey = event.metaKey || event.ctrlKey;
 
@@ -534,7 +575,7 @@ You need to upgrade to DataGridPro or DataGridPremium component to unlock multip
       handleSingleRowSelection(params.id, event);
       return;
     }
-    if (String.fromCharCode(event.keyCode) === 'A' && (event.ctrlKey || event.metaKey)) {
+    if (isSelectAllShortcut(event)) {
       event.preventDefault();
       if (canHaveMultipleSelection) {
         toggleAllRows(true);

package/hooks/features/rowSelection/utils.js

@@ -67,6 +67,11 @@ const checkboxPropsSelector = exports.checkboxPropsSelector = (0, _createSelecto
       return;
     }
     const node = rowTree[itemToTraverseId];
+    // Skeleton rows are placeholders for rows that are not loaded yet.
+    // They have no selection state, so they do not affect the parent checkbox state.
+    if (node?.type === 'skeletonRow') {
+      return;
+    }
     if (node?.type === 'group') {
       node.children.forEach(traverseDescendants);
     }

package/hooks/features/rowSelection/utils.mjs

@@ -60,6 +60,11 @@ export const checkboxPropsSelector = createSelector(gridColumnDefinitionsSelecto
       return;
     }
     const node = rowTree[itemToTraverseId];
+    // Skeleton rows are placeholders for rows that are not loaded yet.
+    // They have no selection state, so they do not affect the parent checkbox state.
+    if (node?.type === 'skeletonRow') {
+      return;
+    }
     if (node?.type === 'group') {
       node.children.forEach(traverseDescendants);
     }

package/hooks/features/rows/gridRowsUtils.d.mts

@@ -1,5 +1,5 @@
 import type { RefObject } from '@mui/x-internals/types';
-import type { GridAutoGeneratedGroupNode, GridAutoGeneratedPinnedRowNode, GridColDef, GridFooterNode, GridGroupNode, GridRowId, GridRowIdGetter, GridRowModel, GridRowModelUpdate, GridRowTreeConfig, GridSkeletonRowNode, GridTreeNode, GridValidRowModel } from "../../../models/index.mjs";
+import type { GridAutoGeneratedGroupNode, GridAutoGeneratedPinnedRowNode, GridColDef, GridFooterNode, GridGroupNode, GridRowId, GridRowIdGetter, GridRowModel, GridRowModelUpdate, GridRowModelReplace, GridRowTreeConfig, GridSkeletonRowNode, GridTreeNode, GridValidRowModel } from "../../../models/index.mjs";
 import type { DataGridProcessedProps } from "../../../models/props/DataGridProps.mjs";
 import type { GridApiCommunity, GridPrivateApiCommunity } from "../../../models/api/gridApiCommunity.mjs";
 import type { GridRowsInternalCache, GridRowsState, GridRowTreeCreationParams } from "./gridRowsInterfaces.mjs";
@@ -43,6 +43,40 @@ export declare const getRowsStateFromCache: ({
 export declare const isAutogeneratedRow: (row: GridRowModel) => boolean;
 export declare const isAutogeneratedRowNode: (rowNode: GridTreeNode) => rowNode is GridFooterNode | GridSkeletonRowNode | GridAutoGeneratedGroupNode | GridAutoGeneratedPinnedRowNode;
 export declare const getTreeNodeDescendants: (tree: GridRowTreeConfig, parentId: GridRowId, skipAutoGeneratedRows: boolean, directChildrenOnly?: boolean) => GridRowId[];
+export declare const isReplaceUpdate: (update: GridRowModelUpdate | GridRowModelReplace) => update is GridRowModelReplace;
+/**
+ * Extracts the replacement row from a `{ _action: 'replace', row }` update.
+ * The marker lives on the throwaway envelope, so the row object itself is never touched.
+ * @param {GridRowModelReplace} update The update provided to `updateRows()`.
+ * @returns {GridRowModel} The object to store as the row, verbatim.
+ */
+export declare const getReplaceRow: (update: GridRowModelReplace) => GridRowModel;
+/**
+ * Merges a partial update into the existing row.
+ * Prototype-preservation rules:
+ *   1. If partialRow is a class instance (non-plain object), use its prototype — the
+ *      caller is passing in a fully-constructed instance and owns the prototype chain.
+ *   2. If partialRow is a plain object (Object.prototype), prefer oldRow's prototype so
+ *      that a partial-update object does not silently discard the existing row's class.
+ *   3. If both are plain objects the result is also a plain object (no-op).
+ *
+ * Note: private class fields (#field syntax) cannot be preserved through a spread-style
+ * merge because the brand check is tied to the original instance. Rows that rely on
+ * private fields must either supply a fully-constructed instance as partialRow (rule 1
+ * above) or use `_action: 'replace'` rather than a plain-object partial update.
+ * @param {GridRowModel} oldRow The row currently stored in the lookup.
+ * @param {GridRowModelUpdate} partialRow The update to merge into it.
+ * @returns {GridRowModel} The merged row.
+ */
+export declare const mergeRowUpdate: (oldRow: GridRowModel, partialRow: GridRowModelUpdate) => GridRowModel;
+/**
+ * Warns when a replace demotes a class instance to a plain object, which happens when the
+ * replacement was built with a spread instead of being passed as-is.
+ * Dev-only, does nothing in production.
+ * @param {GridRowModel | undefined} oldRow The row being replaced, if any.
+ * @param {GridRowModel} replacement The row provided in a `{ _action: 'replace', row }` update.
+ */
+export declare const warnIfReplaceLosesPrototype: (oldRow: GridRowModel | undefined, replacement: GridRowModel) => void;
 export declare const updateCacheWithNewRows: ({
   previousCache,
   getRowId,
@@ -51,10 +85,10 @@ export declare const updateCacheWithNewRows: ({
 }: {
   previousCache: GridRowsInternalCache;
   getRowId: DataGridProcessedProps['getRowId'];
-  updates: GridRowModelUpdate[];
+  updates: Array<GridRowModelUpdate | GridRowModelReplace>;
   groupKeys?: string[];
 }) => GridRowsInternalCache;
 export declare const minimalContentHeight = "var(--DataGrid-overlayHeight, calc(var(--height) * 2))";
-export declare function computeRowsUpdates(apiRef: RefObject<GridApiCommunity>, updates: GridRowModelUpdate[], getRowId: DataGridProcessedProps['getRowId']): GridRowModelUpdate[];
+export declare function computeRowsUpdates(apiRef: RefObject<GridApiCommunity>, updates: Array<GridRowModelUpdate | GridRowModelReplace>, getRowId: DataGridProcessedProps['getRowId']): (GridRowModelReplace<GridValidRowModel> | GridRowModelUpdate)[];
 export declare const getValidRowHeight: (rowHeightProp: any, defaultRowHeight: number, warningMessage: string) => number;
 export declare const rowHeightWarning: string;

package/hooks/features/rows/gridRowsUtils.d.ts

@@ -1,5 +1,5 @@
 import type { RefObject } from '@mui/x-internals/types';
-import type { GridAutoGeneratedGroupNode, GridAutoGeneratedPinnedRowNode, GridColDef, GridFooterNode, GridGroupNode, GridRowId, GridRowIdGetter, GridRowModel, GridRowModelUpdate, GridRowTreeConfig, GridSkeletonRowNode, GridTreeNode, GridValidRowModel } from "../../../models/index.js";
+import type { GridAutoGeneratedGroupNode, GridAutoGeneratedPinnedRowNode, GridColDef, GridFooterNode, GridGroupNode, GridRowId, GridRowIdGetter, GridRowModel, GridRowModelUpdate, GridRowModelReplace, GridRowTreeConfig, GridSkeletonRowNode, GridTreeNode, GridValidRowModel } from "../../../models/index.js";
 import type { DataGridProcessedProps } from "../../../models/props/DataGridProps.js";
 import type { GridApiCommunity, GridPrivateApiCommunity } from "../../../models/api/gridApiCommunity.js";
 import type { GridRowsInternalCache, GridRowsState, GridRowTreeCreationParams } from "./gridRowsInterfaces.js";
@@ -43,6 +43,40 @@ export declare const getRowsStateFromCache: ({
 export declare const isAutogeneratedRow: (row: GridRowModel) => boolean;
 export declare const isAutogeneratedRowNode: (rowNode: GridTreeNode) => rowNode is GridFooterNode | GridSkeletonRowNode | GridAutoGeneratedGroupNode | GridAutoGeneratedPinnedRowNode;
 export declare const getTreeNodeDescendants: (tree: GridRowTreeConfig, parentId: GridRowId, skipAutoGeneratedRows: boolean, directChildrenOnly?: boolean) => GridRowId[];
+export declare const isReplaceUpdate: (update: GridRowModelUpdate | GridRowModelReplace) => update is GridRowModelReplace;
+/**
+ * Extracts the replacement row from a `{ _action: 'replace', row }` update.
+ * The marker lives on the throwaway envelope, so the row object itself is never touched.
+ * @param {GridRowModelReplace} update The update provided to `updateRows()`.
+ * @returns {GridRowModel} The object to store as the row, verbatim.
+ */
+export declare const getReplaceRow: (update: GridRowModelReplace) => GridRowModel;
+/**
+ * Merges a partial update into the existing row.
+ * Prototype-preservation rules:
+ *   1. If partialRow is a class instance (non-plain object), use its prototype — the
+ *      caller is passing in a fully-constructed instance and owns the prototype chain.
+ *   2. If partialRow is a plain object (Object.prototype), prefer oldRow's prototype so
+ *      that a partial-update object does not silently discard the existing row's class.
+ *   3. If both are plain objects the result is also a plain object (no-op).
+ *
+ * Note: private class fields (#field syntax) cannot be preserved through a spread-style
+ * merge because the brand check is tied to the original instance. Rows that rely on
+ * private fields must either supply a fully-constructed instance as partialRow (rule 1
+ * above) or use `_action: 'replace'` rather than a plain-object partial update.
+ * @param {GridRowModel} oldRow The row currently stored in the lookup.
+ * @param {GridRowModelUpdate} partialRow The update to merge into it.
+ * @returns {GridRowModel} The merged row.
+ */
+export declare const mergeRowUpdate: (oldRow: GridRowModel, partialRow: GridRowModelUpdate) => GridRowModel;
+/**
+ * Warns when a replace demotes a class instance to a plain object, which happens when the
+ * replacement was built with a spread instead of being passed as-is.
+ * Dev-only, does nothing in production.
+ * @param {GridRowModel | undefined} oldRow The row being replaced, if any.
+ * @param {GridRowModel} replacement The row provided in a `{ _action: 'replace', row }` update.
+ */
+export declare const warnIfReplaceLosesPrototype: (oldRow: GridRowModel | undefined, replacement: GridRowModel) => void;
 export declare const updateCacheWithNewRows: ({
   previousCache,
   getRowId,
@@ -51,10 +85,10 @@ export declare const updateCacheWithNewRows: ({
 }: {
   previousCache: GridRowsInternalCache;
   getRowId: DataGridProcessedProps['getRowId'];
-  updates: GridRowModelUpdate[];
+  updates: Array<GridRowModelUpdate | GridRowModelReplace>;
   groupKeys?: string[];
 }) => GridRowsInternalCache;
 export declare const minimalContentHeight = "var(--DataGrid-overlayHeight, calc(var(--height) * 2))";
-export declare function computeRowsUpdates(apiRef: RefObject<GridApiCommunity>, updates: GridRowModelUpdate[], getRowId: DataGridProcessedProps['getRowId']): GridRowModelUpdate[];
+export declare function computeRowsUpdates(apiRef: RefObject<GridApiCommunity>, updates: Array<GridRowModelUpdate | GridRowModelReplace>, getRowId: DataGridProcessedProps['getRowId']): (GridRowModelReplace<GridValidRowModel> | GridRowModelUpdate)[];
 export declare const getValidRowHeight: (rowHeightProp: any, defaultRowHeight: number, warningMessage: string) => number;
 export declare const rowHeightWarning: string;

package/hooks/features/rows/gridRowsUtils.js

@@ -7,9 +7,10 @@ Object.defineProperty(exports, "__esModule", {
 exports.buildRootGroup = exports.GRID_ROOT_GROUP_ID = exports.GRID_ID_AUTOGENERATED = void 0;
 exports.checkGridRowIdIsValid = checkGridRowIdIsValid;
 exports.computeRowsUpdates = computeRowsUpdates;
-exports.updateCacheWithNewRows = exports.rowHeightWarning = exports.minimalContentHeight = exports.isAutogeneratedRowNode = exports.isAutogeneratedRow = exports.getValidRowHeight = exports.getTreeNodeDescendants = exports.getTopLevelRowCount = exports.getRowsStateFromCache = exports.getRowValue = exports.getRowIdFromRowModel = exports.createRowsInternalCache = void 0;
+exports.warnIfReplaceLosesPrototype = exports.updateCacheWithNewRows = exports.rowHeightWarning = exports.minimalContentHeight = exports.mergeRowUpdate = exports.isReplaceUpdate = exports.isAutogeneratedRowNode = exports.isAutogeneratedRow = exports.getValidRowHeight = exports.getTreeNodeDescendants = exports.getTopLevelRowCount = exports.getRowsStateFromCache = exports.getRowValue = exports.getRowIdFromRowModel = exports.getReplaceRow = exports.createRowsInternalCache = void 0;
 var _extends2 = _interopRequireDefault(require("@babel/runtime/helpers/extends"));
 var _formatErrorMessage2 = _interopRequireDefault(require("@mui/x-internals/formatErrorMessage"));
+var _warning = require("@mui/x-internals/warning");
 var _gridRowsSelector = require("./gridRowsSelector");
 const GRID_ROOT_GROUP_ID = exports.GRID_ROOT_GROUP_ID = `auto-generated-group-node-root`;
 const GRID_ID_AUTOGENERATED = exports.GRID_ID_AUTOGENERATED = Symbol('mui.id_autogenerated');
@@ -178,6 +179,83 @@ const getTreeNodeDescendants = (tree, parentId, skipAutoGeneratedRows, directChi
   return validDescendants;
 };
 exports.getTreeNodeDescendants = getTreeNodeDescendants;
+const isReplaceUpdate = update =>
+// eslint-disable-next-line no-underscore-dangle
+update._action === 'replace';
+
+/**
+ * Extracts the replacement row from a `{ _action: 'replace', row }` update.
+ * The marker lives on the throwaway envelope, so the row object itself is never touched.
+ * @param {GridRowModelReplace} update The update provided to `updateRows()`.
+ * @returns {GridRowModel} The object to store as the row, verbatim.
+ */
+exports.isReplaceUpdate = isReplaceUpdate;
+const getReplaceRow = update => {
+  const {
+    row
+  } = update;
+  if (row == null) {
+    throw new Error(process.env.NODE_ENV !== "production" ? `MUI X Data Grid: A row update with \`_action: 'replace'\` was provided without a \`row\` property.
+Without it, the Data Grid does not know which object to store for that row.
+Provide the replacement object in the \`row\` property, for example \`updateRows([{ _action: 'replace', row }])\`.
+For more detail, see https://mui.com/x/react-data-grid/row-updates/.` : (0, _formatErrorMessage2.default)(304));
+  }
+  return row;
+};
+
+/**
+ * Merges a partial update into the existing row.
+ * Prototype-preservation rules:
+ *   1. If partialRow is a class instance (non-plain object), use its prototype — the
+ *      caller is passing in a fully-constructed instance and owns the prototype chain.
+ *   2. If partialRow is a plain object (Object.prototype), prefer oldRow's prototype so
+ *      that a partial-update object does not silently discard the existing row's class.
+ *   3. If both are plain objects the result is also a plain object (no-op).
+ *
+ * Note: private class fields (#field syntax) cannot be preserved through a spread-style
+ * merge because the brand check is tied to the original instance. Rows that rely on
+ * private fields must either supply a fully-constructed instance as partialRow (rule 1
+ * above) or use `_action: 'replace'` rather than a plain-object partial update.
+ * @param {GridRowModel} oldRow The row currently stored in the lookup.
+ * @param {GridRowModelUpdate} partialRow The update to merge into it.
+ * @returns {GridRowModel} The merged row.
+ */
+exports.getReplaceRow = getReplaceRow;
+const mergeRowUpdate = (oldRow, partialRow) => {
+  const partialRowProto = Object.getPrototypeOf(partialRow);
+  const isPartialRowPlain = partialRowProto === Object.prototype || partialRowProto === null;
+  const proto = isPartialRowPlain ? Object.getPrototypeOf(oldRow) : partialRowProto;
+  const merged = Object.create(proto);
+  Object.assign(merged, oldRow, partialRow);
+  return merged;
+};
+
+/**
+ * Warns when a replace demotes a class instance to a plain object, which happens when the
+ * replacement was built with a spread instead of being passed as-is.
+ * Dev-only, does nothing in production.
+ * @param {GridRowModel | undefined} oldRow The row being replaced, if any.
+ * @param {GridRowModel} replacement The row provided in a `{ _action: 'replace', row }` update.
+ */
+exports.mergeRowUpdate = mergeRowUpdate;
+const warnIfReplaceLosesPrototype = (oldRow, replacement) => {
+  if (process.env.NODE_ENV === 'production' || !oldRow) {
+    return;
+  }
+  const replacementProto = Object.getPrototypeOf(replacement);
+  if (replacementProto !== Object.prototype && replacementProto !== null) {
+    return;
+  }
+  const oldRowProto = Object.getPrototypeOf(oldRow);
+  if (oldRowProto === Object.prototype || oldRowProto === null) {
+    return;
+  }
+
+  // The message must stay free of row-specific details: `warnOnce()` caches by message, so
+  // interpolating the id would log once per row and grow the cache with every update.
+  (0, _warning.warnOnce)(["MUI X Data Grid: A plain object was provided as the `row` of a `_action: 'replace'` update, but the row it replaces is a class instance.", "Building the replacement with a spread (`{ _action: 'replace', row: { ...row } }`) creates a plain object, dropping the prototype chain and the private fields that `_action: 'replace'` exists to preserve.", "Pass the instance itself instead, for example `{ _action: 'replace', row }`.", 'For more detail, see https://mui.com/x/react-data-grid/row-updates/.']);
+};
+exports.warnIfReplaceLosesPrototype = warnIfReplaceLosesPrototype;
 const updateCacheWithNewRows = ({
   previousCache,
   getRowId,
@@ -191,10 +269,28 @@ const updateCacheWithNewRows = ({
   // Remove duplicate updates.
   // A server can batch updates, and send several updates for the same row in one fn call.
   const uniqueUpdates = new Map();
+  // Ids whose accumulated update is stored as the row instead of being merged into the
+  // existing one. The flag lives outside the row object so that it is never mutated.
+  const replaceIds = new Set();
   updates.forEach(update => {
-    const id = getRowIdFromRowModel(update, getRowId, 'A row was provided without id when calling updateRows():');
-    if (uniqueUpdates.has(id)) {
-      uniqueUpdates.set(id, (0, _extends2.default)({}, uniqueUpdates.get(id), update));
+    // A replace is provided as a `{ _action: 'replace', row }` envelope: the marker stays
+    // on the throwaway envelope and the inner row is used verbatim, so that the object
+    // provided by the caller is the one that ends up in the lookup.
+    const isReplace = isReplaceUpdate(update);
+    const row = isReplace ? getReplaceRow(update) : update;
+    const id = getRowIdFromRowModel(row, getRowId, 'A row was provided without id when calling updateRows():');
+    if (isReplace) {
+      // A replace resets whatever has been accumulated for that id.
+      uniqueUpdates.set(id, row);
+      replaceIds.add(id);
+    } else if (uniqueUpdates.has(id)) {
+      const accumulatedUpdate = uniqueUpdates.get(id);
+      if (process.env.NODE_ENV !== 'production' && replaceIds.has(id)) {
+        (0, _warning.warnOnce)(["MUI X Data Grid: A row was provided with `_action: 'replace'` but it is not the last update for that row in this batch.", 'The remaining updates are merged onto the replacement, so the row keeps its prototype but is neither the same object nor carries its `#private` fields, which a merge cannot copy.', 'Make the replace the last update for that row if `apiRef.current.getRow(id)` must return the object you passed in.', 'For more detail, see https://mui.com/x/react-data-grid/row-updates/.']);
+      }
+      // The merge keeps the accumulated entry's prototype and the id stays in `replaceIds`,
+      // so the result is still applied as a replace.
+      uniqueUpdates.set(id, mergeRowUpdate(accumulatedUpdate, update));
     } else {
       uniqueUpdates.set(id, update);
     }
@@ -246,6 +342,15 @@ const updateCacheWithNewRows = ({
     }
     const oldRow = dataRowIdToModelLookup[id];
 
+    // Action === "replace"
+    // The bookkeeping is the same as for "modify" / "insert" below, only the way the row
+    // is stored differs: the object is stored as-is so that its prototype chain, private
+    // fields (#field) and reference identity are all preserved.
+    const isReplace = replaceIds.has(id);
+    if (isReplace) {
+      warnIfReplaceLosesPrototype(oldRow, partialRow);
+    }
+
     // Action === "modify"
     if (oldRow) {
       // If the data row has been removed since the last state update,
@@ -261,23 +366,7 @@ const updateCacheWithNewRows = ({
       }
 
       // Update the data row lookups.
-      // Prototype-preservation rules:
-      //   1. If partialRow is a class instance (non-plain object), use its prototype — the
-      //      caller is passing in a fully-constructed instance and owns the prototype chain.
-      //   2. If partialRow is a plain object (Object.prototype), prefer oldRow's prototype so
-      //      that a partial-update object does not silently discard the existing row's class.
-      //   3. If both are plain objects the result is also a plain object (no-op).
-      //
-      // Note: private class fields (#field syntax) cannot be preserved through a spread-style
-      // merge because the brand check is tied to the original instance. Rows that rely on
-      // private fields must supply a fully-constructed instance as partialRow (rule 1 above)
-      // rather than a plain-object partial update.
-      const partialRowProto = Object.getPrototypeOf(partialRow);
-      const isPartialRowPlain = partialRowProto === Object.prototype || partialRowProto === null;
-      const proto = isPartialRowPlain ? Object.getPrototypeOf(oldRow) : partialRowProto;
-      const merged = Object.create(proto);
-      Object.assign(merged, oldRow, partialRow);
-      dataRowIdToModelLookup[id] = merged;
+      dataRowIdToModelLookup[id] = isReplace ? partialRow : mergeRowUpdate(oldRow, partialRow);
       return;
     }
 
@@ -319,16 +408,24 @@ const minimalContentHeight = exports.minimalContentHeight = 'var(--DataGrid-over
 function computeRowsUpdates(apiRef, updates, getRowId) {
   const nonPinnedRowsUpdates = [];
   updates.forEach(update => {
-    const id = getRowIdFromRowModel(update, getRowId, 'A row was provided without id when calling updateRows():');
+    const isReplace = isReplaceUpdate(update);
+    const row = isReplace ? getReplaceRow(update) : update;
+    const id = getRowIdFromRowModel(row, getRowId, 'A row was provided without id when calling updateRows():');
     const rowNode = (0, _gridRowsSelector.gridRowNodeSelector)(apiRef, id);
     if (rowNode?.type === 'pinnedRow') {
       // @ts-ignore because otherwise `release:build` doesn't work
       const pinnedRowsCache = apiRef.current.caches.pinnedRows;
       const prevModel = pinnedRowsCache.idLookup[id];
       if (prevModel) {
-        pinnedRowsCache.idLookup[id] = (0, _extends2.default)({}, prevModel, update);
+        if (isReplace) {
+          warnIfReplaceLosesPrototype(prevModel, row);
+          pinnedRowsCache.idLookup[id] = row;
+        } else {
+          pinnedRowsCache.idLookup[id] = mergeRowUpdate(prevModel, update);
+        }
       }
     } else {
+      // The envelope is passed through untouched, `updateCacheWithNewRows` unwraps it.
       nonPinnedRowsUpdates.push(update);
     }
   });