[Joy] Improve variant customization experience

[siriwatknp]

Preview https://deploy-preview-30878--material-ui.netlify.app/experiments/joy/variant/
CodeSandbox https://codesandbox.io/s/joy-cra-typescript-forked-h9zus?file=/src/App.tsx

Improve variant customization experience

This PR moves the variant generation from the default theme to run time generation so that developers only need to configure the variables.

Before

Joy defines variant tokens (theme.palette.primary.*) and variants (theme.variants.*) separately. Consequently, if developers want to add/remove some tokens that Joy provides as a default, they will have to adjust the theme.variants as well.

Take Strapi clone as an example:

Joy	Strapi
Initially, Joy does not define the token outlinedBg (the background of the outlined variant).	https://www.figma.com/file/9jClRdtL7DgQcG4iYU6MzC/Strapi---UI-Kit-%F0%9F%A7%A9-(Community)?node-id=9974%3A117504

To make Joy looks like Strapi, here is what the developer have to do:

1. add outlinedBg to theme.palette.primary.outlinedBg

<CssVarsProvider theme={{
  colorSchemes: {
    light: {
      palette: {
        primary: {
          outlinedBg: 'var(--palette-primary-200)',
        }
      }
    }
  }
}}>

2. add backgroundColor to theme.variants.outlined

<CssVarsProvider theme={{
  variants: {
    outlined: {
      primary: {
        // the extra stylesheet that will be merged with the default variant
        backgroundColor: 'var(--palette-primary-outlinedBg),
      }
    }
  }
}}>

3. module augmentation for typescript

This is just only for primary color, I have to do this for 4 colors. This takes a lot of effort just to customize the background, so it made me think that the process should be easier.

New

I came to realize that the variant tokens in theme.palette.* are already explicit.

• If you want to customize the background of the outlined variant, you would specify theme.palette.$color.outlinedBg and you expect the style to work.
• if you want to customize the background (hover state) of the outlined variant, you would specify theme.palette.$color.outlinedHoverBg and that should be done.

The process of building variant styles should be done after Joy has combined the default theme + user-input tokens via <CssVarsProvider theme={{ colorSchemes: { light: { palette: { ... } }} }}>.

---

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

[mui-bot]

Details of bundle changes

@material-ui/system: parsed: +0.44% , gzip: +0.59%
@mui/joy: parsed: -0.33% 😍, gzip: +1.00%

Generated by 🚫 dangerJS against f90bacf

[siriwatknp]

rename to match the variant variables.

[siriwatknp]

This is the main change of this PR.

[siriwatknp]

JoyTheme should not be a generic.

[siriwatknp]

There is no change on these functions, just moved there to prevent dependency cycle.

[siriwatknp]

Split palette to make theme independent (for TS augmentation)

[siriwatknp]

I found that the below code caused an error, so I added a condition with a test.

sx={[
  theme => theme.typography.something, // undefined
]}

[mnajdova]

Just to make sure I understand correctly, under the variants key, we can basically specify styles for each variant + color + state(hover, disabled, active)?
It is not clear except for colors how other CSS properties are being added. Are there some docs, or can you point me to the code that does this?

[siriwatknp]

Just to make sure I understand correctly, under the variants key, we can basically specify styles for each variant + color + state(hover, disabled, active)?

Yes, those variants that you specify (higher priority) will be merged with the variants generated from the palette tokens.

---

It is not clear except for colors how other CSS properties are being added. Are there some docs, or can you point me to the code that does this?

It is in createCssVarsProvider.js. In line 109-113, we generate the CSS variables and the vars object from mergedTheme (palette is excluded):

const { css: rootCss, vars: rootVars } = cssVarsParser(mergedTheme, {
  prefix,
  basePrefix: designSystemPrefix,
  shouldSkipGeneratingVar,
});

then in line 216, the CSS variables is attach to global stylesheet:

<GlobalStyles styles={{ ':root': rootCss }} />

[mnajdova]

I couldn't spot anything suspicious. I plan to test the joy package, so I am approving assuming this improves the experience. I will report any bugs/problems I will find during the tests

[danilo-leal]

Same as Marija! I think I understood the concept, so it's good to go for now. But I'll try it out effectively when playing with building the example UIs :)