[styled-engine] Add enableCssLayer prop to StyledEngineProvider

[siriwatknp]

First step for #44700.

• Added a new enableCssLayer prop (same prop name as the AppRouter integration)
• It's independent of the existing injectFirst prop.

The next step is to create a Tailwind v4 guide in a separate PR.

Try it out

1. Create a vite project with tailwind css v4 and Material UI installed with:

  "@mui/material": "https://pkg.csb.dev/mui/material-ui/commit/cbeefad4/@mui/material",

2. Set enableCssLayer to StyleEngineProvider component

<StyledEngineProvider enableCssLayer>

3. Add CSS layer order using GlobalStyles under StyledEngineProvider.

// src/App.jsx
<StyledEngineProvider>
  <GlobalStyles styles="@layer base, theme, components, mui, utilities;" />
  …
</StyledEngineProvider>

The reason to do this from Material UI side is to ensure that CSS layer order is configured correctly before Material UI components render.

Review recommendation

toggle "Hide whitespace"

---

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

[mui-bot]

Netlify deploy preview

https://deploy-preview-45428--material-ui.netlify.app/

@mui/joy: parsed: +0.06% , gzip: +0.11%
@material-ui/core: parsed: +0.05% , gzip: +0.07%
@material-ui/system: parsed: +0.34% , gzip: +0.38%

Bundle size report

Details of bundle changes (Toolpad)
Details of bundle changes

Generated by 🚫 dangerJS against baf2ed3

[aarongarciah]

Should we add some tests? Looks like StyledEngineProvider doesn't have any, but still worth it IMO.

[siriwatknp]

Should we add some tests? Looks like StyledEngineProvider doesn't have any, but still worth it IMO.

Added the test. It's not that simple to test the generated CSS with @layer so I have to add private object to intercept the styles.

It won't leak to user because it's not exported through barrel files.

[aarongarciah]

@siriwatknp can you add instructions on how to properly test this change to get a sense of how the final DX looks like? I'm testing in a Vite app and when I enable enableCssLayer some styles are gone. I assume we need to disable Tailwind's preflight and include the mui layer somewhere?

[siriwatknp]

@siriwatknp can you add instructions on how to properly test this change to get a sense of how the final DX looks like? I'm testing in a Vite app and when I enable enableCssLayer some styles are gone. I assume we need to disable Tailwind's preflight and include the mui layer somewhere?

Added the instruction in the PR description.

[aarongarciah]

Tested and it works as expected 👍 I'd love more eyes on this before approving, also on the testing strategy.

[DiegoAndai]

@siriwatknp LGTM, only one change from my side: https://github.com/mui/material-ui/pull/45428/files#r1983527460

[DiegoAndai]

Nit: We should move the override and delete of TEST_INTERNALS_DO_NOT_USE.insert into beforeAll and afterAll calls

[siriwatknp]

Refactored.

[DiegoAndai]

@siriwatknp there's still some left over from the refactor:

• line 33 delete
• The last two tests still have the .insert definition and the delete at the end

[siriwatknp]

🤦‍♂️ Opps, removed.

[DiegoAndai]

LGTM ✅

@siriwatknp remember that if we need to cherry-pick to v6, the v6.x label should be added as well

[github-actions]

Cherry-pick PRs will be created targeting branches: v6.x