[material-ui][mui-system] Stabilize Grid v2 and deprecate Grid v1 (#4…

…3054)
mui · Jul 30, 2024 · 08dce48 · 08dce48
1 parent f160039
commit 08dce48
Show file tree

Hide file tree

Showing 153 changed files with 608 additions and 295 deletions.
diff --git a/benchmark/browser/scenarios/grid-system/index.js b/benchmark/browser/scenarios/grid-system/index.js
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import Grid from '@mui/system/Unstable_Grid';
+import Grid from '@mui/system/Grid';
 
 export default function GridSystem() {
   return (

diff --git a/docs/data/material/components/grid/grid.md b/docs/data/material/components/grid/grid.md
@@ -19,6 +19,10 @@ Material Design's responsive UI is based on a 12-column grid layout.
 The `Grid` component shouldn't be confused with a data grid; it is closer to a layout grid. For a data grid head to [the `DataGrid` component](/x/react-data-grid/).
 :::
 
+:::warning
+The `Grid` component has been deprecated. Please use the [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 migration guide](/material-ui/migration/migrating-to-v6/).
+:::
+
 ## How it works
 
 The grid system is implemented with the `Grid` component:

diff --git a/docs/data/material/components/grid2/AutoGrid.js b/docs/data/material/components/grid2/AutoGrid.js
@@ -2,7 +2,7 @@ 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/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 const Item = styled(Paper)(({ theme }) => ({
   backgroundColor: '#fff',

diff --git a/docs/data/material/components/grid2/AutoGrid.tsx b/docs/data/material/components/grid2/AutoGrid.tsx
@@ -2,7 +2,7 @@ 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/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 const Item = styled(Paper)(({ theme }) => ({
   backgroundColor: '#fff',

diff --git a/docs/data/material/components/grid2/BasicGrid.js b/docs/data/material/components/grid2/BasicGrid.js
@@ -2,7 +2,7 @@ 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/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 const Item = styled(Paper)(({ theme }) => ({
   backgroundColor: '#fff',

diff --git a/docs/data/material/components/grid2/BasicGrid.tsx b/docs/data/material/components/grid2/BasicGrid.tsx
@@ -2,7 +2,7 @@ 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/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 const Item = styled(Paper)(({ theme }) => ({
   backgroundColor: '#fff',

diff --git a/docs/data/material/components/grid2/CenteredElementGrid.js b/docs/data/material/components/grid2/CenteredElementGrid.js
@@ -1,7 +1,7 @@
 import * as React from 'react';
 import Avatar from '@mui/material/Avatar';
 import Box from '@mui/material/Box';
-import Grid from '@mui/material/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 export default function CenteredElementGrid() {
   return (

diff --git a/docs/data/material/components/grid2/CenteredElementGrid.tsx b/docs/data/material/components/grid2/CenteredElementGrid.tsx
@@ -1,7 +1,7 @@
 import * as React from 'react';
 import Avatar from '@mui/material/Avatar';
 import Box from '@mui/material/Box';
-import Grid from '@mui/material/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 export default function CenteredElementGrid() {
   return (

diff --git a/docs/data/material/components/grid2/ColumnsGrid.js b/docs/data/material/components/grid2/ColumnsGrid.js
@@ -2,7 +2,7 @@ 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/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 const Item = styled(Paper)(({ theme }) => ({
   backgroundColor: '#fff',

diff --git a/docs/data/material/components/grid2/ColumnsGrid.tsx b/docs/data/material/components/grid2/ColumnsGrid.tsx
@@ -2,7 +2,7 @@ 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/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 const Item = styled(Paper)(({ theme }) => ({
   backgroundColor: '#fff',

diff --git a/docs/data/material/components/grid2/FullBorderedGrid.js b/docs/data/material/components/grid2/FullBorderedGrid.js
@@ -1,6 +1,6 @@
 import * as React from 'react';
 import Box from '@mui/material/Box';
-import Grid from '@mui/material/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 export default function FullBorderedGrid() {
   return (

diff --git a/docs/data/material/components/grid2/FullBorderedGrid.tsx b/docs/data/material/components/grid2/FullBorderedGrid.tsx
@@ -1,6 +1,6 @@
 import * as React from 'react';
 import Box from '@mui/material/Box';
-import Grid from '@mui/material/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 export default function FullBorderedGrid() {
   return (

diff --git a/docs/data/material/components/grid2/FullWidthGrid.js b/docs/data/material/components/grid2/FullWidthGrid.js
@@ -2,7 +2,7 @@ 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/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 const Item = styled(Paper)(({ theme }) => ({
   backgroundColor: '#fff',

diff --git a/docs/data/material/components/grid2/FullWidthGrid.tsx b/docs/data/material/components/grid2/FullWidthGrid.tsx
@@ -2,7 +2,7 @@ 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/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 const Item = styled(Paper)(({ theme }) => ({
   backgroundColor: '#fff',

diff --git a/docs/data/material/components/grid2/HalfBorderedGrid.js b/docs/data/material/components/grid2/HalfBorderedGrid.js
@@ -1,6 +1,6 @@
 import * as React from 'react';
 import Box from '@mui/material/Box';
-import Grid from '@mui/material/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 export default function HalfBorderedGrid() {
   const colWidth = { xs: 12, sm: 6, md: 4, lg: 3 };

diff --git a/docs/data/material/components/grid2/HalfBorderedGrid.tsx b/docs/data/material/components/grid2/HalfBorderedGrid.tsx
@@ -1,6 +1,6 @@
 import * as React from 'react';
 import Box from '@mui/material/Box';
-import Grid from '@mui/material/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 export default function HalfBorderedGrid() {
   const colWidth = { xs: 12, sm: 6, md: 4, lg: 3 } as const;

diff --git a/docs/data/material/components/grid2/NestedGrid.js b/docs/data/material/components/grid2/NestedGrid.js
@@ -2,7 +2,7 @@ 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/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 const Item = styled(Paper)(({ theme }) => ({
   backgroundColor: '#fff',

diff --git a/docs/data/material/components/grid2/NestedGrid.tsx b/docs/data/material/components/grid2/NestedGrid.tsx
@@ -2,7 +2,7 @@ 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/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 const Item = styled(Paper)(({ theme }) => ({
   backgroundColor: '#fff',

diff --git a/docs/data/material/components/grid2/NestedGridColumns.js b/docs/data/material/components/grid2/NestedGridColumns.js
@@ -2,7 +2,7 @@ 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/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 const Item = styled(Paper)(({ theme }) => ({
   backgroundColor: '#fff',

diff --git a/docs/data/material/components/grid2/NestedGridColumns.tsx b/docs/data/material/components/grid2/NestedGridColumns.tsx
@@ -2,7 +2,7 @@ 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/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 const Item = styled(Paper)(({ theme }) => ({
   backgroundColor: '#fff',

diff --git a/docs/data/material/components/grid2/OffsetGrid.js b/docs/data/material/components/grid2/OffsetGrid.js
@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { styled } from '@mui/material/styles';
 import Paper from '@mui/material/Paper';
-import Grid from '@mui/material/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 const Item = styled(Paper)(({ theme }) => ({
   backgroundColor: '#fff',

diff --git a/docs/data/material/components/grid2/OffsetGrid.tsx b/docs/data/material/components/grid2/OffsetGrid.tsx
@@ -1,7 +1,7 @@
 import * as React from 'react';
 import { styled } from '@mui/material/styles';
 import Paper from '@mui/material/Paper';
-import Grid from '@mui/material/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 const Item = styled(Paper)(({ theme }) => ({
   backgroundColor: '#fff',

diff --git a/docs/data/material/components/grid2/ResponsiveGrid.js b/docs/data/material/components/grid2/ResponsiveGrid.js
@@ -2,7 +2,7 @@ import * as React from 'react';
 import { experimentalStyled as styled } from '@mui/material/styles';
 import Box from '@mui/material/Box';
 import Paper from '@mui/material/Paper';
-import Grid from '@mui/material/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 const Item = styled(Paper)(({ theme }) => ({
   backgroundColor: '#fff',

diff --git a/docs/data/material/components/grid2/ResponsiveGrid.tsx b/docs/data/material/components/grid2/ResponsiveGrid.tsx
@@ -2,7 +2,7 @@ import * as React from 'react';
 import { experimentalStyled as styled } from '@mui/material/styles';
 import Box from '@mui/material/Box';
 import Paper from '@mui/material/Paper';
-import Grid from '@mui/material/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 const Item = styled(Paper)(({ theme }) => ({
   backgroundColor: '#fff',

diff --git a/docs/data/material/components/grid2/RowAndColumnSpacing.js b/docs/data/material/components/grid2/RowAndColumnSpacing.js
@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { styled } from '@mui/material/styles';
-import Grid from '@mui/material/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 import Paper from '@mui/material/Paper';
 import Box from '@mui/material/Box';
 

diff --git a/docs/data/material/components/grid2/RowAndColumnSpacing.tsx b/docs/data/material/components/grid2/RowAndColumnSpacing.tsx
@@ -1,6 +1,6 @@
 import * as React from 'react';
 import { styled } from '@mui/material/styles';
-import Grid from '@mui/material/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 import Paper from '@mui/material/Paper';
 import Box from '@mui/material/Box';
 

diff --git a/docs/data/material/components/grid2/SpacingGrid.js b/docs/data/material/components/grid2/SpacingGrid.js
@@ -1,6 +1,6 @@
 import * as React from 'react';
 import Box from '@mui/material/Box';
-import Grid from '@mui/material/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 import FormLabel from '@mui/material/FormLabel';
 import FormControl from '@mui/material/FormControl';
 import FormControlLabel from '@mui/material/FormControlLabel';

diff --git a/docs/data/material/components/grid2/SpacingGrid.tsx b/docs/data/material/components/grid2/SpacingGrid.tsx
@@ -1,6 +1,6 @@
 import * as React from 'react';
 import Box from '@mui/material/Box';
-import Grid from '@mui/material/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 import FormLabel from '@mui/material/FormLabel';
 import FormControl from '@mui/material/FormControl';
 import FormControlLabel from '@mui/material/FormControlLabel';

diff --git a/docs/data/material/components/grid2/VariableWidthGrid.js b/docs/data/material/components/grid2/VariableWidthGrid.js
@@ -2,7 +2,7 @@ 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/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 const Item = styled(Paper)(({ theme }) => ({
   backgroundColor: '#fff',

diff --git a/docs/data/material/components/grid2/VariableWidthGrid.tsx b/docs/data/material/components/grid2/VariableWidthGrid.tsx
@@ -2,7 +2,7 @@ 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/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 
 const Item = styled(Paper)(({ theme }) => ({
   backgroundColor: '#fff',

diff --git a/docs/data/material/components/grid2/grid2.md b/docs/data/material/components/grid2/grid2.md
@@ -1,7 +1,7 @@
 ---
 productId: material-ui
 title: React Grid component
-components: PigmentGrid
+components: PigmentGrid, Grid2
 githubLabel: 'component: Grid'
 materialDesign: https://m2.material.io/design/layout/understanding-layout.html
 ---
@@ -15,29 +15,6 @@ The columns can be configured with multiple breakpoints to specify the column sp
 
 {{"component": "@mui/docs/ComponentLinkHeader", "design": false}}
 
-## What's changed
-
-We built the `Grid` component from scratch in order to:
-
-- Fix [known issues](https://github.com/mui/material-ui/pull/32746) introduced in Material UI v5.
-- Simplify the logic with CSS variables, removing the unnecessary `item` prop and reducing CSS specificity.
-- Introduce a proper fix for [preventing a scrollbar](#prevent-scrollbar) by switching between negative margin approaches.
-- Set negative margins of equal size on all sides of the grid container by default.
-
-Since the new implementation is considered a breaking change, we introduced it as `Unstable_Grid2` to gather feedbacks from the community before making it stable in the next major release of Material UI.
-
-We encourage everyone to try the new version of the `Grid` by visiting the [Grid v2 migration guide](/material-ui/migration/migration-grid-v2/).
-
-:::info
-From now on, the `Grid` v1 and `Grid` v2 refer to the import as:
-
-```js
-import Grid from '@mui/material/Grid'; // Grid version 1
-import Grid from '@mui/material/Unstable_Grid2'; // Grid version 2
-```
-
-:::
-
 ## How it works
 
 The grid system is implemented with the `Grid` component:

diff --git a/docs/data/material/getting-started/templates/dashboard/components/MainGrid.js b/docs/data/material/getting-started/templates/dashboard/components/MainGrid.js
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import Grid from '@mui/material/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 import Box from '@mui/material/Box';
 import Stack from '@mui/material/Stack';
 import Typography from '@mui/material/Typography';

diff --git a/docs/data/material/getting-started/templates/dashboard/components/MainGrid.tsx b/docs/data/material/getting-started/templates/dashboard/components/MainGrid.tsx
@@ -1,5 +1,5 @@
 import * as React from 'react';
-import Grid from '@mui/material/Unstable_Grid2';
+import Grid from '@mui/material/Grid2';
 import Box from '@mui/material/Box';
 import Stack from '@mui/material/Stack';
 import Typography from '@mui/material/Typography';

diff --git a/docs/data/material/migration/migrating-to-v6/migrating-to-v6.md b/docs/data/material/migration/migrating-to-v6/migrating-to-v6.md
@@ -191,13 +191,27 @@ The `children` passed to the Loading Button component is now wrapped in a `<span
 
 ### Grid v2 (Unstable_Grid)
 
-The `Grid` v2 component was updated to match the API of the new `PigmentGrid` component, to allow interoperability between the two:
+The `Grid2` was updated and stabilized:
 
-- The previous size and offset props were replaced with the `size` and `offset` props
+- The previous size (`xs`, `sm`, `md`, ...) and offset (`xsOffset`, `smOffset`, `mdOffset`, ...) props, which were named after the theme's breakpoints, were replaced with the `size` and `offset` props.
 - The spacing mechanism was reworked to use the `gap` CSS property.
 
 This brings some breaking changes described in the following sections.
 
+#### Stabilized API
+
+The `Grid2` component API was stabilized, so its import no longer contains the `Unstable_` prefix:
+
+```diff
+- import { Unstable_Grid2 as Grid2 } from '@mui/material';
++ import { Grid2 } from '@mui/material';
+```
+
+```diff
+- import Grid from '@mui/material/Unstable_Grid2';
++ import Grid from '@mui/material/Grid2';
+```
+
 #### Size and offset props
 
 Previously, the size and offset props were named corresponding to the theme's breakpoints.
@@ -239,6 +253,10 @@ Use this codemod to migrate your project to the new size and offset props:
 npx @mui/codemod@next v6.0.0/grid-v2-props <path/to/folder>
 ```
 
+:::warning
+You need to modify the import from `@mui/material/Unstable_Grid2` to `@mui/material/Grid2` before running the codemod.
+:::
+
 If you have custom breakpoints, the change is the same:
 
 ```diff

diff --git a/docs/data/material/migration/migration-grid-v2/GridDisableEqualOverflow.js b/docs/data/material/migration/migration-grid-v2/GridDisableEqualOverflow.js