[DataGridPro] Row reorder (mui#4034)

docs/data/data-grid/events/events.json

@@ -239,6 +239,12 @@
     "params": "GridRowParams",
     "event": "MuiEvent<React.MouseEvent<HTMLElement>>"
   },
+  {
+    "name": "rowOrderChange",
+    "description": "Fired when the user ends reordering a row.",
+    "params": "GridRowOrderChangeParams",
+    "event": "MuiEvent<{}>"
+  },
   {
     "name": "rowSelectionCheckboxChange",
     "description": "Fired when the value of the selection checkbox of a row is changed",

docs/data/data-grid/getting-started/getting-started.md

@@ -168,7 +168,7 @@ The enterprise components come in two plans: Pro and Premium.
 | **Row**                                                                                |           |                                    |                                            |
 | [Row height](/x/react-data-grid/rows/#row-height)                                      |    ✅     |                 ✅                 |                     ✅                     |
 | [Row spanning](/x/react-data-grid/rows/#row-spanning)                                  |    🚧     |                 🚧                 |                     🚧                     |
-| [Row reordering](/x/react-data-grid/rows/#row-reorder)                                 |    ❌     |                 🚧                 |                     🚧                     |
+| [Row reordering](/x/react-data-grid/rows/#row-reorder)                                 |    ❌     |                 ✅                 |                     ✅                     |
 | [Row pinning](/x/react-data-grid/rows/#row-pinning)                                    |    ❌     |                 🚧                 |                     🚧                     |
 | **Selection**                                                                          |           |                                    |                                            |
 | [Single row selection](/x/react-data-grid/selection/#single-row-selection)             |    ✅     |                 ✅                 |                     ✅                     |

docs/data/data-grid/rows/RowOrderingGrid.js

@@ -0,0 +1,57 @@
+import * as React from 'react';
+import { DataGridPro } from '@mui/x-data-grid-pro';
+import { useDemoData } from '@mui/x-data-grid-generator';
+
+function updateRowPosition(initialIndex, newIndex, rows) {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      const rowsClone = [...rows];
+      const row = rowsClone.splice(initialIndex, 1)[0];
+      rowsClone.splice(newIndex, 0, row);
+      resolve(rowsClone);
+    }, Math.random() * 500 + 100); // simulate network latency
+  });
+}
+
+export default function RowOrderingGrid() {
+  const { data, loading: initialLoadingState } = useDemoData({
+    dataSet: 'Commodity',
+    rowLength: 20,
+    maxColumns: 20,
+  });
+
+  const [rows, setRows] = React.useState(data.rows);
+  const [loading, setLoading] = React.useState(initialLoadingState);
+
+  React.useEffect(() => {
+    setRows(data.rows);
+  }, [data]);
+
+  React.useEffect(() => {
+    setLoading(initialLoadingState);
+  }, [initialLoadingState]);
+
+  const handleRowOrderChange = async (params) => {
+    setLoading(true);
+    const newRows = await updateRowPosition(
+      params.oldIndex,
+      params.targetIndex,
+      rows,
+    );
+
+    setRows(newRows);
+    setLoading(false);
+  };
+
+  return (
+    <div style={{ height: 400, width: '100%' }}>
+      <DataGridPro
+        loading={loading}
+        rows={rows}
+        columns={data.columns}
+        rowReordering
+        onRowOrderChange={handleRowOrderChange}
+      />
+    </div>
+  );
+}

docs/data/data-grid/rows/RowOrderingGrid.tsx

@@ -0,0 +1,65 @@
+import * as React from 'react';
+import {
+  DataGridPro,
+  GridRowModel,
+  GridRowOrderChangeParams,
+} from '@mui/x-data-grid-pro';
+import { useDemoData } from '@mui/x-data-grid-generator';
+
+function updateRowPosition(
+  initialIndex: number,
+  newIndex: number,
+  rows: Array<GridRowModel>,
+): Promise<any> {
+  return new Promise((resolve) => {
+    setTimeout(() => {
+      const rowsClone = [...rows];
+      const row = rowsClone.splice(initialIndex, 1)[0];
+      rowsClone.splice(newIndex, 0, row);
+      resolve(rowsClone);
+    }, Math.random() * 500 + 100); // simulate network latency
+  });
+}
+
+export default function RowOrderingGrid() {
+  const { data, loading: initialLoadingState } = useDemoData({
+    dataSet: 'Commodity',
+    rowLength: 20,
+    maxColumns: 20,
+  });
+
+  const [rows, setRows] = React.useState(data.rows);
+  const [loading, setLoading] = React.useState(initialLoadingState);
+
+  React.useEffect(() => {
+    setRows(data.rows);
+  }, [data]);
+
+  React.useEffect(() => {
+    setLoading(initialLoadingState);
+  }, [initialLoadingState]);
+
+  const handleRowOrderChange = async (params: GridRowOrderChangeParams) => {
+    setLoading(true);
+    const newRows = await updateRowPosition(
+      params.oldIndex,
+      params.targetIndex,
+      rows,
+    );
+
+    setRows(newRows);
+    setLoading(false);
+  };
+
+  return (
+    <div style={{ height: 400, width: '100%' }}>
+      <DataGridPro
+        loading={loading}
+        rows={rows}
+        columns={data.columns}
+        rowReordering
+        onRowOrderChange={handleRowOrderChange}
+      />
+    </div>
+  );
+}

docs/data/data-grid/rows/RowOrderingGrid.tsx.preview

@@ -0,0 +1,7 @@
+<DataGridPro
+  loading={loading}
+  rows={rows}
+  columns={data.columns}
+  rowReordering
+  onRowOrderChange={handleRowOrderChange}
+/>

docs/data/data-grid/rows/rows.md

@@ -135,6 +135,79 @@ To add a border instead, set `rowSpacingType` to `"border"` and customize the co
 
 You can check the [styling rows](/x/react-data-grid/style/#styling-rows) section for more information.
 
+## Row reorder [<span class="plan-pro"></span>](https://mui.com/store/items/material-ui-pro/)
+
+Row reordering allows to rearrange rows by dragging the special reordering cell.
+
+By default, row reordering is disabled.
+To enable it, you need to add the `rowReordering` prop.
+
+```tsx
+<DataGridPro rowReordering />
+```
+
+{{"demo": "RowOrderingGrid.js", "disableAd": true, "bg": "inline"}}
+
+To capture changes in the order of the dragged row, you can pass a callback to the `onRowOrderChange` prop. This callback is called with a `GridRowOrderChangeParams` object.
+
+In addition, you can import the following events to customize the row reordering experience:
+
+- `rowDragStart`: emitted when dragging of a row starts.
+- `rowDragOver`: emitted when dragging a row over another row.
+- `rowDragEnd`: emitted when dragging of a row stops.
+
+### Customizing the reorder value
+
+By default, when you start dragging a row, the `id` is displayed in the draggable box.
+To change this, you can give a value to the `__reorder__` field for each row.
+
+```tsx
+const columns: GridColumns = [{ field: 'brand' }];
+
+const rows: GridRowsProp = [
+  { id: 0, brand: 'Nike', __reorder__: 'Nike' },
+  { id: 1, brand: 'Adidas', __reorder__: 'Adidas' },
+  { id: 2, brand: 'Puma', __reorder__: 'Puma' },
+];
+
+<DataGridPro rows={rows} columns={columns} rowReordering />;
+```
+
+### Customizing the row reordering icon
+
+To change the icon used for the row reordering, you can provide a different component for the [icon slot](/x/react-data-grid/components/#icons) as follow:
+
+```tsx
+<DataGridPro
+  components={{
+    RowReorderIcon: CustomMoveIcon,
+  }}
+/>
+```
+
+Another way to customize is to add a column with `field: __reorder__` to your set of columns.
+That way, you can overwrite any of the properties from the `GRID_REORDER_COL_DEF` column.
+The grid will detect that there is already a reorder column defined and it will not add another one in the default position.
+By only setting the `field`, is up to you to configure the remaining options (e.g. disable the column menu, filtering, sorting).
+To already start with a few suggested options configured, spread `GRID_REORDER_COL_DEF` when defining the column.
+
+```tsx
+<DataGridPro
+  columns={[
+    {
+      ...GRID_REORDER_COL_DEF, // Already contains the right field
+      width: 40,
+    },
+  ]}
+/>
+```
+
+This approach can also be used to change the location of the toggle column.
+
+> ⚠️ For now, row reordering is disabled if sorting is applied to the grid.
+>
+> In addition, if row grouping or tree data is being used, the row reordering is also disabled.
+
 ## 🚧 Row spanning
 
 > ⚠️ This feature isn't implemented yet. It's coming.
@@ -146,14 +219,6 @@ Row spanning allows to change this default behavior.
 It allows cells to span multiple rows.
 This is very close to the "row spanning" in an HTML `<table>`.
 
-## 🚧 Row reorder [<span class="plan-pro"></span>](https://mui.com/store/items/material-ui-pro/)
-
-> ⚠️ This feature isn't implemented yet. It's coming.
->
-> 👍 Upvote [issue #206](https://github.com/mui/mui-x/issues/206) if you want to see it land faster.
-
-Row reorder is used to rearrange rows by dragging the row with the mouse.
-
 ## 🚧 Row pinning [<span class="plan-pro"></span>](https://mui.com/store/items/material-ui-pro/)
 
 > ⚠️ This feature isn't implemented yet. It's coming.