[system] Add unstable_createCssVarsProvider api

[siriwatknp]

Codesandbox preview

the idea behind this PR is that Joy & Material will use unstable_createCssVarsProvider (similar to createStyled) to provide CSS variables that developers can extend and/or override the default theme.

CssVarsProvider at its core is a ThemeProvider + a function that compute theme input to create CSS variables.

The picture below describes the high-level flow that this API is responsible for.

How to use this API
First, the design system has to create the Provider with the default theme and then exports it. The theme structure needs to follow the palette structure (the keys will be the mode name and the value can be any palette structure). To see how type is defined, check out spec file

// in `packages/mui-joy`,

const ThemeContext = React.createContext();

const { CssVarsProvider, getInitModeScript } = createCssVarsProvider(
  ThemeContext,
  {
    defaultColorScheme: 'light',
    theme: {
      colorSchemes: {
        light: {
          palette: {
            brand: '',
            appBg: '',
          }
        },
        dark: {
          palette: {
            brand: '',
            appBg: '',
          }
        }
      },
      fontSize: {
        md: '1rem',
        // ...
      },
      // ...the rest theme structure
    },
  }
);

export { CssVarsProvider, getInitModeScript };

Then, developers can import the Provider from the package. (If they don't want to use CSS variables, they can import the ThemeProvider as usual)

import { CssVarsProvider, useTheme } from '@mui/joy';

function App() {
  return (
    <CssVarsProvider
       // theme={{ }} // they can override the default theme
       // theme={{ colorSchemes: { comfort: { ... } } }} // or they can extends the color schemes
    />
  )
}

const CustomComponent = () => {
  const theme = useTheme(); // the theme is the same as in `styled` API
  return (
    <button
      style={{
        // `vars` is the computed object that reference to CSS variables
        color: theme.vars.palette.brand, // the result is `var(--palette-brand)`
      }}>Foo</button>
  )
}

---

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

[mui-pr-bot]

Details of bundle changes

@material-ui/system: parsed: +5.81% , gzip: +5.80%

Generated by 🚫 dangerJS against bead5a9

[eps1lon]

What is being parsed into what and why do we need it?

[siriwatknp]

I have changed it a bit to make it easier. The cssVarsParser is responsible for creating { css, vars } from theme.

the css will be applied to <GlobalStyles styles={css} /> and vars will be attached to theme in react context so that the components can read and reference to css variable.

const Button = styled('button')(({ theme }) => ({
  color: theme.vars.palette.primary.main, // 'var(--palette-primary-main)'
}))

[mnajdova]

I will need to spend more time testing this locally, but this is my first round of review :) Really happy to see this 🤩

[hbjORbj]

I love it! I played with it a bit. Just to confirm my understanding, it is expected that theme.vars is undefined yet as useTheme for joy isn't in the scope of this PR, right? Code sandbox

[siriwatknp]

I love it! I played with it a bit. Just to confirm my understanding, it is expected that theme.vars is undefined yet as useTheme for joy isn't in the scope of this PR, right? Code sandbox

Yes, correct. This PR is from them system perspective only.

[mnajdova]

Some small details :)

[mnajdova]

Awesome 🔥 I don't have anything else to add