[system] Add new Grid implementation

[siriwatknp]

Preview: https://deploy-preview-32746--material-ui.netlify.app/system/react-grid/

Motivations

• MUI is about to have an alternative UI library called "Joy UI". It also needs Grid component so we decided to move layout components (container, grid, and stack) to the system package so that they can be reused on both Material UI and Joy UI.
• We would like to use this opportunity to fix the existing issues with the Grid implementation without breaking changes.
  • [Grid] Grid system spacing not creating proper gutters in v5 #31244
  • [Grid] spacing with full width Items / Layout shift #29266
  • sx property on Grid doesn't allow changing paddingTop #28855
  • [Grid] Add support for new breakpoints #26369
  • [Grid] Support offset #11251

What's new

• Offset feature (next PR)
• Full support nested grid
• Able to switch between negative margin implementations (works with nested grid) (next PR)
• Replace class selector with CSS variables (easier to customize via sx prop)
• item and zeroMinWidth props are not needed (they are removed).

Implementation approach

• Use the margin/padding strategy similar to v4 by default.

  The strategy changes in v5 (margin, padding on top,left sides) aims to fix [Grid] Extra width of container & scrollbar #7466, but it creates more issues (see [Grid] Grid system spacing not creating proper gutters in v5 #31244, [Grid] spacing with full width Items / Layout shift #29266).

• Introduce a new flag disableEqualOverflow to fix a specific issue about [Grid] Extra width of container & scrollbar #7466. When the flag is true, the negative margin is apply to top and left sides of the grid (similar to the current Grid v5)

• Simplify the logic by using CSS variables and reduce javascript calculation by using calc()

  • lines of code: Before ~600, After ~400 (with offset and disableEqualOverflow features)
  • there is no performance difference (benchmark by running the 1000 grid items inside a grid container).
  • get rid of CSS specificity via gridClasses.item
  • get rid of item prop (Grid is always an item that follows flexbox)
  • no limitation on the nested grid.

• zeroMinWidth prop is removed. It works by default.

Material UI migration strategy (in a separate PR)

Since the new grid is rewritten, an adoption strategy is required to make sure that it covers all the edge cases. We can mark this new implementation as v6.

Option 1: export a new grid (GridV6) from @mui/material. Developers can test it out per instance like this:

// some page
-import Grid from '@mui/material/Grid';
+import Grid from '@mui/material/GridV6';

<Grid container spacing={2}>
  <Grid
-   item
     md={6}
  > ... </Grid>
  ...
</Grid>

Option 2: expose a prop in the existing Grid, eg. enableGridV6. However, I think the option 1 is better because of less bundle size (if you don't use it) and better types inference.

We can expose the new grid for 4-6 months and collect feedback, bug fixes. Once we are working on the v6, we can remove the old grid, switch GridV6 to Grid and write a code mod to transform:

-import GridV6 from '@mui/material/GridV6';
+import Grid from '@mui/material/Grid';

Option 3: export the new Grid from @mui/lab. For theme components type, it will be MuiGridV6 (to not overlap with existing Grid):

export interface LabComponents {
  // ...
  MuiGridV6?: {
    defaultProps?: ComponentsProps['MuiGridV6'];
    styleOverrides?: ComponentsOverrides<Theme>['MuiGridV6'];
    variants?: ComponentsVariants['MuiGridV6'];
  };
}

The usage will be like this:

import Grid from '@mui/lab/Grid';

---

• I have followed (at least) the PR section of the contributing guide.

[mui-bot]

Details of bundle changes

@mui/joy: parsed: +2.67% , gzip: +2.84%

Generated by 🚫 dangerJS against 906db8e

[oliviertassinari]

We would like to use this opportunity to fix the existing issues with the Grid implementation without breaking changes

@siriwatknp This sounds like a great idea, but I think that each problem should be solved in its own PR, one step at a time. It will help with the review.

[siriwatknp]

We would like to use this opportunity to fix the existing issues with the Grid implementation without breaking changes

@siriwatknp This sounds like a great idea, but I think that each problem should be solved in its own PR, one step at a time. It will help with the review.

Sounds good. I can split offset feature and negative margin switching into separate PRs. cc @mnajdova What do you think?

[mnajdova]

Sounds good. I can split offset feature and negative margin switching into separate PRs. cc @mnajdova What do you think?

Sure 👍

[siriwatknp]

Remove this to be able to import @mui/system/Grid;

[siriwatknp]

Sounds good. I can split offset feature and negative margin switching into separate PRs. cc @mnajdova What do you think?

Sure 👍

Done! offset and disableEqualOverflow are removed.

[mnajdova]

Generally looks good. Should we prefix it with Unstable_ :)

[siriwatknp]

Generally looks good. Should we prefix it with Unstable_ :)

I think it makes sense when we reexport this new Grid from Material UI but maybe not for System.

I am merging this and we can discuss this in a separate PR before the next release.

[leonbloy]

The negative margins are still rather ... surprising, and a source of confusion for the unsuspecting user.

Is this how it's supposed to work ? https://codesandbox.io/s/laughing-bush-30o2dk?file=/demo.tsx

In this example, 5 containers are created (same spacing). Notice how the effect of the (top/bottom) negative margins results in a vertical asymetry in the spacings. Also, it's rather surprising/frustating that two containers with two items each (that fill 12 columns each) do not behave the same as a single container with for items that sum 24 columns.

[siriwatknp]

The negative margins are still rather ... surprising, and a source of confusion for the unsuspecting user.

Is this how it's supposed to work ? https://codesandbox.io/s/laughing-bush-30o2dk?file=/demo.tsx

In this example, 5 containers are created (same spacing). Notice how the effect of the (top/bottom) negative margins results in a vertical asymetry in the spacings. Also, it's rather surprising/frustating that two containers with two items each (that fill 12 columns each) do not behave the same as a single container with for items that sum 24 columns.

If you think this is a bug, please open a new issue. We can discuss further in the issue.

[mattste]

@siriwatknp one thing that's not clear from the docs: can you mix GridV1 and GridV2 within the same component tree?

For example:

<GridV2 container>
  <GridV1 item></GridV1>
 <GridV1 item></GridV1>
</GridV2>

[siriwatknp]

@siriwatknp one thing that's not clear from the docs: can you mix GridV1 and GridV2 within the same component tree?

For example:

<GridV2 container>
  <GridV1 item></GridV1>
 <GridV1 item></GridV1>
</GridV2>

You should not mix them.