[DataGridPremium] Automatic parents and children selection

docs/data/data-grid/row-grouping/RowGroupingPropagateSelection.js

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import {
+  DataGridPremium,
+  useGridApiRef,
+  useKeepGroupedColumnsHidden,
+} from '@mui/x-data-grid-premium';
+import { useMovieData } from '@mui/x-data-grid-generator';
+
+export default function RowGroupingPropagateSelection() {
+  const data = useMovieData();
+  const apiRef = useGridApiRef();
+
+  const initialState = useKeepGroupedColumnsHidden({
+    apiRef,
+    initialState: {
+      rowGrouping: {
+        model: ['company', 'director'],
+      },
+    },
+  });
+
+  return (
+    <div style={{ height: 400, width: '100%' }}>
+      <DataGridPremium
+        {...data}
+        apiRef={apiRef}
+        initialState={initialState}
+        checkboxSelection
+        propagateRowSelection
+      />
+    </div>
+  );
+}

docs/data/data-grid/row-grouping/RowGroupingPropagateSelection.tsx

@@ -0,0 +1,33 @@
+import * as React from 'react';
+import {
+  DataGridPremium,
+  useGridApiRef,
+  useKeepGroupedColumnsHidden,
+} from '@mui/x-data-grid-premium';
+import { useMovieData } from '@mui/x-data-grid-generator';
+
+export default function RowGroupingPropagateSelection() {
+  const data = useMovieData();
+  const apiRef = useGridApiRef();
+
+  const initialState = useKeepGroupedColumnsHidden({
+    apiRef,
+    initialState: {
+      rowGrouping: {
+        model: ['company', 'director'],
+      },
+    },
+  });
+
+  return (
+    <div style={{ height: 400, width: '100%' }}>
+      <DataGridPremium
+        {...data}
+        apiRef={apiRef}
+        initialState={initialState}
+        checkboxSelection
+        propagateRowSelection
+      />
+    </div>
+  );
+}

docs/data/data-grid/row-grouping/RowGroupingPropagateSelection.tsx.preview

@@ -0,0 +1,7 @@
+<DataGridPremium
+  {...data}
+  apiRef={apiRef}
+  initialState={initialState}
+  checkboxSelection
+  propagateRowSelection
+/>

docs/data/data-grid/row-grouping/row-grouping.md

@@ -305,6 +305,28 @@ In the example below:
 If you are dynamically switching the `leafField` or `mainGroupingCriteria`, the sorting and filtering models will not be cleaned up automatically, and the sorting/filtering will not be re-applied.
 :::
 
+## Automatic parents and children selection
+
+By default, selecting a parent row will not select its children.
+Set the `propagateRowSelection` prop to `true` to achieve the following behavior.
+
+1. Selecting/deselecting a parent row would select/deselect all the children rows.
+2. When all the child rows are selected, the parent row will be auto selected.
+3. When a child row is deselected, if one or more parent rows are already selected, they will be moved to an indeterminate state.
+4. "Select All" checkbox in the header row would select/deselect all the rows including child rows.
+5. After applying the filtering, the previously selected rows which are not in the newly filtered rows will be auto deselected.
+
+{{"demo": "RowGroupingPropagateSelection.js", "bg": "inline", "defaultCodeOpen": false}}
+
+:::info
+When the row selection propagation feature is enabled, only the filtered rows will be kept selected.
+If some rows were selected before filtering, they will be auto deselected if they are not among the newly filtered rows.
+:::
+
+:::warning
+The row selection propagation is a client-side feature and not recommended to be used with the [server-side data source](/x/react-data-grid/server-side-data/), since it will only work on the partially loaded data.
+:::
+
 ## Get the rows in a group
 
 You can use the `apiRef.current.getRowGroupChildren` method to get the id of all rows contained in a group.

docs/data/data-grid/tree-data/tree-data.md

@@ -87,6 +87,10 @@ If you want to access the grouping column field, for instance, to use it with co
 
 Same behavior as for the [Row grouping](/x/react-data-grid/row-grouping/#group-expansion).
 
+## Automatic parents and children selection
+
+Same behavior as for the [Row grouping](/x/react-data-grid/row-grouping/#propagate-row-selection).
+
 ## Gaps in the tree
 
 If some entries are missing to build the full tree, the `DataGridPro` will automatically create rows to fill those gaps.

docs/pages/x/api/data-grid/data-grid-premium.json

@@ -558,6 +558,7 @@
         "returned": "Promise<R> | R"
       }
     },
+    "propagateRowSelection": { "type": { "name": "bool" }, "default": "false" },
     "resizeThrottleMs": { "type": { "name": "number" }, "default": "60" },
     "rowBufferPx": { "type": { "name": "number" }, "default": "150" },
     "rowCount": { "type": { "name": "number" } },

docs/pages/x/api/data-grid/data-grid-pro.json

@@ -501,6 +501,7 @@
         "returned": "Promise<R> | R"
       }
     },
+    "propagateRowSelection": { "type": { "name": "bool" }, "default": "false" },
     "resizeThrottleMs": { "type": { "name": "number" }, "default": "60" },
     "rowBufferPx": { "type": { "name": "number" }, "default": "150" },
     "rowCount": { "type": { "name": "number" } },

docs/translations/api-docs/data-grid/data-grid-premium/data-grid-premium.json

@@ -184,7 +184,7 @@
     "groupingColDef": { "description": "The grouping column used by the tree data." },
     "headerFilterHeight": { "description": "Override the height of the header filters." },
     "headerFilters": {
-      "description": "If <code>true</code>, enables the data grid filtering on header feature."
+      "description": "If <code>true</code>, the header filters feature is enabled."
     },
     "hideFooter": { "description": "If <code>true</code>, the footer component is hidden." },
     "hideFooterPagination": {
@@ -586,6 +586,9 @@
         "Promise<R> | R": "The final values to update the row."
       }
     },
+    "propagateRowSelection": {
+      "description": "If <code>true</code>, following behavior happens with nested data: 1. Selecting/deselecting a parent row would select/deselect all the children rows. 2. When all the child rows are selected, the parent row will be auto selected. 3. When a child row is deselected, if one or more parent rows are already selected, they will be moved to an indeterminate state. 4. Select All checkbox in the header row would select/deselect all the rows including child rows. Works with tree data and row grouping on the client-side only."
+    },
     "resizeThrottleMs": { "description": "The milliseconds throttle delay for resizing the grid." },
     "rowBufferPx": { "description": "Row region in pixels to render before/after the viewport" },
     "rowCount": {

docs/translations/api-docs/data-grid/data-grid-pro/data-grid-pro.json

@@ -165,7 +165,7 @@
     "groupingColDef": { "description": "The grouping column used by the tree data." },
     "headerFilterHeight": { "description": "Override the height of the header filters." },
     "headerFilters": {
-      "description": "If <code>true</code>, enables the data grid filtering on header feature."
+      "description": "If <code>true</code>, the header filters feature is enabled."
     },
     "hideFooter": { "description": "If <code>true</code>, the footer component is hidden." },
     "hideFooterPagination": {
@@ -532,6 +532,9 @@
         "Promise<R> | R": "The final values to update the row."
       }
     },
+    "propagateRowSelection": {
+      "description": "If <code>true</code>, following behavior happens with nested data: 1. Selecting/deselecting a parent row would select/deselect all the children rows. 2. When all the child rows are selected, the parent row will be auto selected. 3. When a child row is deselected, if one or more parent rows are already selected, they will be moved to an indeterminate state. 4. Select All checkbox in the header row would select/deselect all the rows including child rows. Works with tree data and row grouping on the client-side only."
+    },
     "resizeThrottleMs": { "description": "The milliseconds throttle delay for resizing the grid." },
     "rowBufferPx": { "description": "Row region in pixels to render before/after the viewport" },
     "rowCount": {

packages/x-data-grid-premium/src/DataGridPremium/DataGridPremium.tsx

@@ -421,7 +421,7 @@ DataGridPremiumRaw.propTypes = {
    */
   headerFilterHeight: PropTypes.number,
   /**
-   * If `true`, enables the data grid filtering on header feature.
+   * If `true`, the header filters feature is enabled.
    * @default false
    */
   headerFilters: PropTypes.bool,
@@ -894,6 +894,16 @@ DataGridPremiumRaw.propTypes = {
    * @returns {Promise<R> | R} The final values to update the row.
    */
   processRowUpdate: PropTypes.func,
+  /**
+   * If `true`, following behavior happens with nested data:
+   * 1. Selecting/deselecting a parent row would select/deselect all the children rows.
+   * 2. When all the child rows are selected, the parent row will be auto selected.
+   * 3. When a child row is deselected, if one or more parent rows are already selected, they will be moved to an indeterminate state.
+   * 4. Select All checkbox in the header row would select/deselect all the rows including child rows.
+   * Works with tree data and row grouping on the client-side only.
+   * @default false
+   */
+  propagateRowSelection: PropTypes.bool,
   /**
    * The milliseconds throttle delay for resizing the grid.
    * @default 60

packages/x-data-grid-premium/src/tests/rowSelection.DataGridPremium.test.tsx

@@ -0,0 +1,178 @@
+import * as React from 'react';
+import { createRenderer, fireEvent, act } from '@mui/internal-test-utils';
+import { getCell } from 'test/utils/helperFn';
+import { expect } from 'chai';
+import {
+  DataGridPremium,
+  DataGridPremiumProps,
+  GridApi,
+  GridRowsProp,
+  useGridApiRef,
+} from '@mui/x-data-grid-premium';
+
+const isJSDOM = /jsdom/.test(window.navigator.userAgent);
+
+interface BaselineProps extends DataGridPremiumProps {
+  rows: GridRowsProp;
+}
+
+const rows: GridRowsProp = [
+  { id: 0, category1: 'Cat A', category2: 'Cat 1' },
+  { id: 1, category1: 'Cat A', category2: 'Cat 2' },
+  { id: 2, category1: 'Cat A', category2: 'Cat 2' },
+  { id: 3, category1: 'Cat B', category2: 'Cat 2' },
+  { id: 4, category1: 'Cat B', category2: 'Cat 1' },
+];
+
+const baselineProps: BaselineProps = {
+  autoHeight: isJSDOM,
+  disableVirtualization: true,
+  rows,
+  columns: [
+    {
+      field: 'id',
+      type: 'number',
+    },
+    {
+      field: 'category1',
+    },
+    {
+      field: 'category2',
+    },
+  ],
+};
+
+describe('<DataGridPremium /> - Row selection', () => {
+  const { render } = createRenderer();
+
+  let apiRef: React.MutableRefObject<GridApi>;
+
+  function Test(props: Partial<DataGridPremiumProps>) {
+    apiRef = useGridApiRef();
+
+    return (
+      <div style={{ width: 300, height: 300 }}>
+        <DataGridPremium {...baselineProps} checkboxSelection apiRef={apiRef} {...props} />
+      </div>
+    );
+  }
+
+  describe('prop: propagateRowSelection', () => {
+    it('should select all the children when selecting a parent', () => {
+      render(
+        <Test propagateRowSelection initialState={{ rowGrouping: { model: ['category1'] } }} />,
+      );
+
+      fireEvent.click(getCell(1, 0).querySelector('input')!);
+      expect(apiRef.current.getSelectedRows()).to.have.keys([
+        'auto-generated-row-category1/Cat B',
+        3,
+        4,
+      ]);
+    });
+
+    it('should deselect all the children when deselecting a parent', () => {
+      render(
+        <Test propagateRowSelection initialState={{ rowGrouping: { model: ['category1'] } }} />,
+      );
+
+      fireEvent.click(getCell(1, 0).querySelector('input')!);
+      expect(apiRef.current.getSelectedRows()).to.have.keys([
+        'auto-generated-row-category1/Cat B',
+        3,
+        4,
+      ]);
+      fireEvent.click(getCell(1, 0).querySelector('input')!);
+      expect(apiRef.current.getSelectedRows().size).to.equal(0);
+    });
+
+    it('should put the parent into indeterminate if some but not all the children are selected', () => {
+      render(
+        <Test
+          propagateRowSelection
+          defaultGroupingExpansionDepth={-1}
+          initialState={{ rowGrouping: { model: ['category1'] } }}
+          density="compact"
+        />,
+      );
+
+      fireEvent.click(getCell(1, 0).querySelector('input')!);
+      expect(getCell(0, 0).querySelector('input')!).to.have.attr('data-indeterminate', 'true');
+    });
+
+    it('should auto select the parent if all the children are selected', () => {
+      render(
+        <Test
+          propagateRowSelection
+          defaultGroupingExpansionDepth={-1}
+          density="compact"
+          initialState={{ rowGrouping: { model: ['category1'] } }}
+        />,
+      );
+
+      fireEvent.click(getCell(1, 0).querySelector('input')!);
+      fireEvent.click(getCell(2, 0).querySelector('input')!);
+      fireEvent.click(getCell(3, 0).querySelector('input')!);
+      expect(apiRef.current.getSelectedRows()).to.have.keys([
+        0,
+        1,
+        2,
+        'auto-generated-row-category1/Cat A',
+      ]);
+    });
+
+    it('should deselect auto selected parent if one of the children is deselected', () => {
+      render(
+        <Test
+          propagateRowSelection
+          defaultGroupingExpansionDepth={-1}
+          density="compact"
+          initialState={{ rowGrouping: { model: ['category1'] } }}
+        />,
+      );
+
+      fireEvent.click(getCell(1, 0).querySelector('input')!);
+      fireEvent.click(getCell(2, 0).querySelector('input')!);
+      fireEvent.click(getCell(3, 0).querySelector('input')!);
+      expect(apiRef.current.getSelectedRows()).to.have.keys([
+        0,
+        1,
+        2,
+        'auto-generated-row-category1/Cat A',
+      ]);
+      fireEvent.click(getCell(2, 0).querySelector('input')!);
+      expect(apiRef.current.getSelectedRows()).to.have.keys([0, 2]);
+    });
+
+    it('should deselect unfiltered rows after filtering', () => {
+      render(
+        <Test
+          propagateRowSelection
+          defaultGroupingExpansionDepth={-1}
+          density="compact"
+          initialState={{ rowGrouping: { model: ['category1'] } }}
+        />,
+      );
+
+      fireEvent.click(getCell(1, 0).querySelector('input')!);
+      fireEvent.click(getCell(2, 0).querySelector('input')!);
+      fireEvent.click(getCell(3, 0).querySelector('input')!);
+      fireEvent.click(getCell(5, 0).querySelector('input')!);
+
+      expect(apiRef.current.getSelectedRows()).to.have.keys([
+        0,
+        1,
+        2,
+        'auto-generated-row-category1/Cat A',
+        3,
+      ]);
+      act(() => {
+        apiRef.current.setFilterModel({
+          items: [],
+          quickFilterValues: ['Cat B'],
+        });
+      });
+      expect(apiRef.current.getSelectedRows()).to.have.keys([3]);
+    });
+  });
+});