[Grid] Improve Grid2 upgrade experience (@DiegoAndai) (mui#45372)

docs/data/material/components/grid/grid.md

@@ -21,7 +21,9 @@ The `Grid` component shouldn't be confused with a data grid; it is closer to a l
 :::
 
 :::warning
-The `Grid` component has been deprecated. Please use [Grid v2](/material-ui/react-grid2/) instead. See how to migrate in the [Grid v2 migration guide](/material-ui/migration/migration-grid-v2/) and [Material UI v6 upgrade guide](/material-ui/migration/upgrade-to-v6/).
+The Grid component has been deprecated.
+Please use [Grid2](/material-ui/react-grid2/) instead.
+See the [Grid2 upgrade guide](/material-ui/migration/upgrade-to-grid-v2/) for more details.
 :::
 
 ## How it works

docs/data/material/components/grid2/ColumnLayoutInsideGrid.js

@@ -0,0 +1,36 @@
+import * as React from 'react';
+import { styled } from '@mui/material/styles';
+import Box from '@mui/material/Box';
+import Paper from '@mui/material/Paper';
+import Grid from '@mui/material/Grid2';
+import Stack from '@mui/material/Stack';
+
+const Item = styled(Paper)(({ theme }) => ({
+  backgroundColor: '#fff',
+  ...theme.typography.body2,
+  padding: theme.spacing(1),
+  textAlign: 'center',
+  color: theme.palette.text.secondary,
+  ...theme.applyStyles('dark', {
+    backgroundColor: '#1A2027',
+  }),
+}));
+
+export default function ColumnLayoutInsideGrid() {
+  return (
+    <Box sx={{ flexGrow: 1 }}>
+      <Grid container spacing={2}>
+        <Grid size={4}>
+          <Stack spacing={2}>
+            <Item>Column 1 - Row 1</Item>
+            <Item>Column 1 - Row 2</Item>
+            <Item>Column 1 - Row 3</Item>
+          </Stack>
+        </Grid>
+        <Grid size={8}>
+          <Item sx={{ height: '100%', boxSizing: 'border-box' }}>Column 2</Item>
+        </Grid>
+      </Grid>
+    </Box>
+  );
+}

docs/data/material/components/grid2/ColumnLayoutInsideGrid.tsx

@@ -0,0 +1,36 @@
+import * as React from 'react';
+import { styled } from '@mui/material/styles';
+import Box from '@mui/material/Box';
+import Paper from '@mui/material/Paper';
+import Grid from '@mui/material/Grid2';
+import Stack from '@mui/material/Stack';
+
+const Item = styled(Paper)(({ theme }) => ({
+  backgroundColor: '#fff',
+  ...theme.typography.body2,
+  padding: theme.spacing(1),
+  textAlign: 'center',
+  color: theme.palette.text.secondary,
+  ...theme.applyStyles('dark', {
+    backgroundColor: '#1A2027',
+  }),
+}));
+
+export default function ColumnLayoutInsideGrid() {
+  return (
+    <Box sx={{ flexGrow: 1 }}>
+      <Grid container spacing={2}>
+        <Grid size={4}>
+          <Stack spacing={2}>
+            <Item>Column 1 - Row 1</Item>
+            <Item>Column 1 - Row 2</Item>
+            <Item>Column 1 - Row 3</Item>
+          </Stack>
+        </Grid>
+        <Grid size={8}>
+          <Item sx={{ height: '100%', boxSizing: 'border-box' }}>Column 2</Item>
+        </Grid>
+      </Grid>
+    </Box>
+  );
+}

docs/data/material/components/grid2/ColumnLayoutInsideGrid.tsx.preview

@@ -0,0 +1,12 @@
+<Grid container spacing={2}>
+  <Grid size={4}>
+    <Stack spacing={2}>
+      <Item>Column 1 - Row 1</Item>
+      <Item>Column 1 - Row 2</Item>
+      <Item>Column 1 - Row 3</Item>
+    </Stack>
+  </Grid>
+  <Grid size={8}>
+    <Item sx={{ height: '100%', boxSizing: 'border-box' }}>Column 2</Item>
+  </Grid>
+</Grid>

docs/data/material/components/grid2/grid2.md

@@ -243,10 +243,11 @@ It cannot wrap other elements.
 
 ## Limitations
 
-### Column direction and reversing
+### Column direction
 
-The `size` and `offset` props are _not_ supported within containers that use `direction="column"` or `direction="column-reverse"`.
+Using `direction="column"` or `direction="column-reverse"` is not supported.
+The Grid component is specifically designed to subdivide a layout into columns, not rows.
+You should not use the Grid component on its own to stack layout elements vertically.
+Instead, you should use the [Stack component](/material-ui/react-stack/) inside of a Grid to create vertical layouts as shown below:
 
-Size and offset props define the number of columns the component will use for a given breakpoint.
-They are intended to control the width using `flex-basis` in `row` containers, but they will impact the height in `column` containers.
-If used, these props may have undesirable effects on the height of the `Grid` item elements.
+{{"demo": "ColumnLayoutInsideGrid.js"}}

docs/data/material/migration/migration-v4/v5-component-changes.md

@@ -775,10 +775,10 @@ If you need negative margins on all sides, we recommend using the new Grid v2 in
 + import Grid from '@mui/material/Grid2';
 ```
 
-To learn more about the Grid v2, check out the [demos](/material-ui/react-grid2/) and the [Grid migration guide](/material-ui/migration/migration-grid-v2/).
+To learn more about Grid2, check out the [Grid2 component doc](/material-ui/react-grid2/) and the [upgrade guide](/material-ui/migration/upgrade-to-grid-v2/).
 
 :::info
-Grid v2 was introduced in Material UI v5.9.1 and features negative margins on all sides by default.
+Grid2 was introduced in Material UI v5.9.1 and features negative margins on all sides by default.
 :::
 
 ## GridList