[material-ui][mui-system] Stabilize Grid v2 and deprecate Grid v1 #43054

DiegoAndai · 2024-07-24T14:09:35Z

Closes: #42761

Stabilize Grid v2 in the material-ui and mui-system packages. This means:

Remove the Unstable_ prefix from the imports
Add Grid v2 API page, which didn't exist before
Add callouts in the v6 migration guide and Grid v2 migration guide about the removal of the prefix
Adjust the codemod to consider the updated imports.

Finally, deprecate the Grid v1 component.

Notes

Initially, I planned to change the Grid v1 name to DeprecatedGrid, but this defeats the purpose of deprecation as it introduces a breaking change (changing the import) instead of offering a deprecation period for users to adjust. We can remove the Grid v2 in v7 and finally rename the Grid v2 to Grid
I also planned to reroute the docs as such:
- Grid v1: material-ui/deprecated-react-grid
- Grid v2: material-ui/react-grid
But this is a pain to do without changing the component's names. I don't think it's critical to make this change so I didn't do it.

DiegoAndai · 2024-07-24T14:11:28Z

Sorry for the large amount of files changed 😅 most of them are

-Unstable_Grid2
+Grid2

mui-bot · 2024-07-24T14:12:52Z

Netlify deploy preview

Grid2: parsed: +Infinity% , gzip: +Infinity%
Unstable_Grid2: parsed: -100.00% 😍, gzip: -100.00% 😍

Bundle size report

Details of bundle changes (Toolpad)
Details of bundle changes

Generated by 🚫 dangerJS against c3ef7a8

aarongarciah

Just some very small comments. Looks great.

docs/data/system/components/grid/AutoGrid.tsx

packages/mui-codemod/README.md

packages/mui-material/src/Grid/Grid.d.ts

packages/mui-material/src/Grid/Grid.js

docs/data/system/migration/migrating-to-v6/migrating-to-v6.md

Co-authored-by: Aarón García Hervás <[email protected]> Signed-off-by: Diego Andai <[email protected]>

siriwatknp · 2024-07-26T14:36:29Z

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';


Not related to this PR but I still see deprecated system props used in this demo. I found that there is no Unstable_Grid2 in the list of removeSystemProps codemod, it should be added along with Grid2 to the list.

I'll open a separate PR for this after we merge this one 👌🏼

docs/data/material/pages.ts

siriwatknp · 2024-07-26T14:45:19Z

docs/data/system/migration/migrating-to-v6/migrating-to-v6.md

 - The spacing mechanism was reworked to use the `gap` CSS property.

 This brings some breaking changes described in the following sections.

+#### Stabilized API


Suggested change

#### Stabilized API

I think this heading is not necessary.

I added sections because they're different breaking changes so providing structure makes it easier to follow, IMO. The other sections are for the size and offset props, and for the removal of disableEqualOverflow.

siriwatknp · 2024-07-26T14:48:14Z

docs/data/system/migration/migrating-to-v6/migrating-to-v6.md


- 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.


Can you add diff snippet to quickly show the migration?

DiegoAndai · 2024-07-26T15:14:25Z

@siriwatknp about this comment:

Can you add diff snippet to quickly show the migration?

The diff snippets and details on how to migrate are on the "Size and offset props" section below, this is a summary of the changes. Do you think we shouldn't have the summary?

siriwatknp · 2024-07-30T13:30:20Z

@siriwatknp about this comment:

Can you add diff snippet to quickly show the migration?

The diff snippets and details on how to migrate are on the "Size and offset props" section below, this is a summary of the changes. Do you think we shouldn't have the summary?

My bad, the diff is already in the section below that.

siriwatknp

🛳️ it.

Issue from #43054

oliviertassinari

Great that we are consolidating on one approach. I imagine that Pigment CSS Grid is identical to Grid2, developers don't even need to know about it.

Thoughts:

https://deploy-preview-43054--material-ui.netlify.app/material-ui/react-grid/ How about adding (deprecated) in the H1 to replicate the side nav? This would ensure Google and Algolia searches are clear.
Do we have an issue to migrate the codebase away from the deprecated Grid? I think we will need one, e.g. for the community to help. Otherwise, it's an issue about removing the old API that we need, but same, to coordinate the work toward it.
Continuing on 2. It feels like we should only add a runtime deprecation once we have migrated all our codebase. At that point, we would have a high confidence level that Grid v2 superset Grid v1.
I'm confused about the names. Are @mui/material/Grid2 and @mui/system/Grid both Grid v2? If yes, then, please, please, let's make the name match. First because the different should only be about either the default theme is preset or not. And second because we are moving to a place where @mui/material/Grid2 and @mui/material/Grid don't exist as exports from this npm package.

Initially, I planned to change the Grid v1 name to DeprecatedGrid, but this defeats the purpose of deprecation as it introduces a breaking change (changing the import) instead of offering a deprecation period for users to adjust. We can remove the Grid v2 in v7 and finally rename the Grid v2 to Grid

Interesting challenge, I didn't look close, I could have seen us go for a straight rename because 1. it's easy to handle for people 2. the API is almost the same, and we can have prop deprecation + props mapping when using the wrong imports to still get most of the behavior right + a clear migration message.

oliviertassinari · 2024-08-02T13:09:00Z

docs/data/material/migration/migration-grid-v2/migration-grid-v2.md

+```
+
+Alongside the stabilization, the API has been improved.
+You can see the changes and further details of how to migrate in the [Material UI v6 migration guide](/material-ui/migrating-to-v6/).


This link doesn't work.

Suggested change

You can see the changes and further details of how to migrate in the [Material UI v6 migration guide](/material-ui/migrating-to-v6/).

You can see the changes and further details on how to migrate in the [Material UI v6 migration guide](/material-ui/migration/migrating-to-v6/).

Fixed in e36c897

oliviertassinari · 2024-08-02T13:20:29Z

docs/data/material/migration/migrating-to-v6/migrating-to-v6.md

+- import { Unstable_Grid2 as Grid2 } from '@mui/material';
+ import { Grid2 } from '@mui/material';


Extra line break

Suggested change

- import { Unstable_Grid2 as Grid2 } from '@mui/material';

+ import { Grid2 } from '@mui/material';

-import { Unstable_Grid2 as Grid2 } from '@mui/material';

+import { Grid2 } from '@mui/material';

Handled in: #43021

DiegoAndai · 2024-08-15T01:33:34Z

I'm confused about the names. Are @mui/material/Grid2 and @mui/system/Grid both Grid v2? If yes, then, please, please, let's make the name match. First because the different should only be about either the default theme is preset or not. And second because we are moving to a place where @mui/material/Grid2 and @mui/material/Grid don't exist as exports from this npm package.

Interesting challenge, I didn't look close, I could have seen us go for a straight rename because 1. it's easy to handle for people 2. the API is almost the same, and we can have prop deprecation + props mapping when using the wrong imports to still get most of the behavior right + a clear migration message.

@oliviertassinari, thanks for the feedback. This is the exact debate I went through in my head when deciding not to rename them as it "defeats the purpose of deprecation as it introduces a breaking change (changing the import) instead of offering a deprecation period for users to adjust.". I still think the actual implementation is the correct one, and we're very close to stable, so I don't want to introduce a new change.

As the original Grid is deprecated now, we can plan for it to be removed in v7 and solve this naming confusion once and for all. This is an intermediate step, we'll get there eventually 😊

oliviertassinari · 2024-08-25T20:53:19Z

@DiegoAndai Fair points, I guess the main thing I'm trying to get is make progress with #40594 and go to the point where Grid is never exported from @mui/material but only from @mui/system. I could see us supporting @mui/system/Grid2 to ease this transition.

In any cases, issue created: #43437, we need to keep track of this for the future.

DiegoAndai added 7 commits July 18, 2024 16:55

Stabilize Grid in the system package

f078cf4

Stabilize material's Grid2

6d2bd32

Adapt to changes in Joy package

3f00fe7

Merge branch 'next' into stabilize-grid-v2

cb48ba4

Fix missing broken imports

bae2e7d

Update documentation

8ea62ab

Update codemod

e9891aa

DiegoAndai added breaking change component: Grid The React component. package: system Specific to @mui/system package: material-ui Specific to @mui/material labels Jul 24, 2024

DiegoAndai requested review from aarongarciah and siriwatknp July 24, 2024 14:09

DiegoAndai self-assigned this Jul 24, 2024

DiegoAndai changed the title ~~[material-ui][mui-system] Stabilize Grid v2 and deprecate Grid v1.~~ [material-ui][mui-system] Stabilize Grid v2 and deprecate Grid v1 Jul 24, 2024

Non-breaking spaces

9e5f8b7

github-actions bot added the PR: out-of-date The pull request has merge conflicts and can't be merged label Jul 25, 2024

aarongarciah reviewed Jul 25, 2024

View reviewed changes

DiegoAndai and others added 4 commits July 25, 2024 16:17

Remove unnecessary empty lines

ddb320b

Update packages/mui-material/src/Grid/Grid.d.ts

fa3df2b

Co-authored-by: Aarón García Hervás <[email protected]> Signed-off-by: Diego Andai <[email protected]>

Update packages/mui-material/src/Grid/Grid.js

3d05ced

Co-authored-by: Aarón García Hervás <[email protected]> Signed-off-by: Diego Andai <[email protected]>

Merge branch 'next' into stabilize-grid-v2

db05825

github-actions bot removed the PR: out-of-date The pull request has merge conflicts and can't be merged label Jul 25, 2024

DiegoAndai added 2 commits July 25, 2024 16:37

Improve documentation phrasing

24ff2bb

Remove mention to PigmentGrid

65cfd00

siriwatknp reviewed Jul 26, 2024

View reviewed changes

docs/data/material/pages.ts Outdated Show resolved Hide resolved

siriwatknp reviewed Jul 26, 2024

View reviewed changes

Add deprecated nav flag and use it for Grid

3d0ed8f

DiegoAndai requested a review from siriwatknp July 29, 2024 14:57

siriwatknp approved these changes Jul 30, 2024

View reviewed changes

Final copy edits and remove stale demo

c3ef7a8

DiegoAndai merged commit 08dce48 into mui:next Jul 30, 2024
22 checks passed

DiegoAndai deleted the stabilize-grid-v2 branch July 30, 2024 15:10

oliviertassinari added a commit that referenced this pull request Aug 2, 2024

[docs] Fix 404 link to migration pages

e36c897

Issue from #43054

oliviertassinari reviewed Aug 2, 2024

View reviewed changes

DiegoAndai mentioned this pull request Aug 14, 2024

[codemod] Add Grid2 to removeSystemProps codemod #43302

Merged

oliviertassinari mentioned this pull request Aug 25, 2024

[Grid2] Rollout plan #43437

Open

6 tasks

DiegoAndai mentioned this pull request Sep 11, 2024

[material-ui] Bring back GridProps and GridTypeMap #43717

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[material-ui][mui-system] Stabilize Grid v2 and deprecate Grid v1 #43054

[material-ui][mui-system] Stabilize Grid v2 and deprecate Grid v1 #43054

DiegoAndai commented Jul 24, 2024 •

edited

Loading

DiegoAndai commented Jul 24, 2024 •

edited

Loading

mui-bot commented Jul 24, 2024 •

edited

Loading

aarongarciah left a comment

siriwatknp Jul 26, 2024 •

edited

Loading

DiegoAndai Jul 26, 2024

DiegoAndai Aug 14, 2024

siriwatknp Jul 26, 2024 •

edited

Loading

DiegoAndai Jul 26, 2024

siriwatknp Jul 26, 2024

DiegoAndai commented Jul 26, 2024

siriwatknp commented Jul 30, 2024

siriwatknp left a comment

oliviertassinari left a comment •

edited

Loading

oliviertassinari Aug 2, 2024

oliviertassinari Aug 2, 2024 •

edited

Loading

DiegoAndai commented Aug 15, 2024

oliviertassinari commented Aug 25, 2024 •

edited

Loading


		- 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.

	You can see the changes and further details of how to migrate in the [Material UI v6 migration guide](/material-ui/migrating-to-v6/).
	You can see the changes and further details on how to migrate in the [Material UI v6 migration guide](/material-ui/migration/migrating-to-v6/).

		- import { Unstable_Grid2 as Grid2 } from '@mui/material';
		+ import { Grid2 } from '@mui/material';

[material-ui][mui-system] Stabilize Grid v2 and deprecate Grid v1 #43054

[material-ui][mui-system] Stabilize Grid v2 and deprecate Grid v1 #43054

Conversation

DiegoAndai commented Jul 24, 2024 • edited Loading

Notes

DiegoAndai commented Jul 24, 2024 • edited Loading

mui-bot commented Jul 24, 2024 • edited Loading

Netlify deploy preview

Bundle size report

aarongarciah left a comment

Choose a reason for hiding this comment

siriwatknp Jul 26, 2024 • edited Loading

Choose a reason for hiding this comment

DiegoAndai Jul 26, 2024

Choose a reason for hiding this comment

DiegoAndai Aug 14, 2024

Choose a reason for hiding this comment

siriwatknp Jul 26, 2024 • edited Loading

Choose a reason for hiding this comment

DiegoAndai Jul 26, 2024

Choose a reason for hiding this comment

siriwatknp Jul 26, 2024

Choose a reason for hiding this comment

DiegoAndai commented Jul 26, 2024

siriwatknp commented Jul 30, 2024

siriwatknp left a comment

Choose a reason for hiding this comment

oliviertassinari left a comment • edited Loading

Choose a reason for hiding this comment

oliviertassinari Aug 2, 2024

Choose a reason for hiding this comment

oliviertassinari Aug 2, 2024 • edited Loading

Choose a reason for hiding this comment

DiegoAndai commented Aug 15, 2024

oliviertassinari commented Aug 25, 2024 • edited Loading

DiegoAndai commented Jul 24, 2024 •

edited

Loading

DiegoAndai commented Jul 24, 2024 •

edited

Loading

mui-bot commented Jul 24, 2024 •

edited

Loading

siriwatknp Jul 26, 2024 •

edited

Loading

siriwatknp Jul 26, 2024 •

edited

Loading

oliviertassinari left a comment •

edited

Loading

oliviertassinari Aug 2, 2024 •

edited

Loading

oliviertassinari commented Aug 25, 2024 •

edited

Loading