[core] Improve styling solution

[oliviertassinari]

We should be pretty close to beta once this PR is merged.

Work In Progress

• Fix multiple theme handling in withStyles
• theme.md Show MuiThemeProvider nesting
• usage.md without MuiThemeProvider
• theme.md Show MuiThemeProvider in the introduction
• insertionPoint as material-ui
• css-in-js.md Update API
• css-in-js.md Show how to use JSS provider of react-jss
• server-side.md Update examples
• testing.md Update API
• createStyleSheet optional name
• write new tests

Issues

Closes #7238 as a merge issue
Closes #6106 as using a broadcast approach
Closes #6129 as supporting theme nesting
Closes #6130 as I don't think it's needed in the core, we can write HOC for that
Closes #6821 as having interoperability with react-jss and
JssProvider
Closes #7310 as making the name optional and use the displayName when the name is not provided.

Wins

Some features this upgrade is unlocking:

• Better perfs
• Shorter class names in production
• Better readable class names in development
• Optional MuiThemeProvider, hence, less onboarding friction
• Simpler createStyleSheet API with an optional name
• Theme nesting
• Slower theme update but reliable
• Interoperability with react-jss

[oliviertassinari]

It should be almost good. I need to write new tests and we should be able to merge it ☯️ .
That's such a massive PR! That's definitely my biggest PR in terms of complexity and effort in the repository.

[oliviertassinari]

@kof This is the only limitation I have seen so far with the index trick over the previous global zIndex.

[oliviertassinari]

The regression was catch by Argos-CI 😍 .

[oliviertassinari]

@kof @iamstarkov feel free to have a look at the new styling solution here. Hopefully, at some point, we will be able to rely on theming and react-jss. At least, we know have a great e2e test: the documentation of Material-UI.

@nathanmarks RIP of jss-theme-reactor.

I wouldn't have been able to finish this PR without you guys, thanks a lot for pushing css-in-jss forward!

[stunaz]

That's a really great job @oliviertassinari , now we just have to wait for the release to enjoy it!

[oliviertassinari]

Will soon release it as the first beta version. Thanks. Hopefully, we won't have any issue. I believe those changes are game changer.

[kof]

One problem I am looking at right now with the latest mui is that now we can't have different Jss instances used for mui and for react-jss. The reason one may need them is plugins setup which might be different for mui than for the user code.

[oliviertassinari]

@kof We can always implement our own JssProvider to allow such pattern, I'm not sure we should allow it, why not just asking for a minimum set of plugins that Material-UI relies on?

[kof]

My use case is to have a plugin which is applied to my user code but NOT to mui code, because mui will break in this case.

[kof]

It is safer in general for mui to use an own jss instance I think.

[oliviertassinari]

because mui will break in this case.

We could do the comparaison with Babel, I have never seen a babel plugin breaking existing code, as far as I know. Maybe that's where the issue is?

It is safer in general for mui to use an own jss instance I think.

That's opening the door for inconsistency issues, can we still share the same sheetRegistry for SSR?
We can go into that direction too.

[kof]

That's opening the door for inconsistency issues,

you are right, if our road is towards using react-jss originally from both of them it would be expected both of them behave the same.

I am thinking right now that we should be able to disable/enable specific plugins where needed on specific sheets.

So for e.g. if I don't want mui to use jss-isolate plugin, I pass option createStyleSheet(styles, {isolate: false}) just for mui sheets. That option is already supported btw.

[oliviertassinari]

@kof Yes, we can add this extra isolate: false change, that should be a one line change fix :).

[kof]

Its just about passing any options user defines down to the style sheet I think.