[core] Implement useTheme processor and runtime theme

[brijeshb42]

Here's how the replacement works

Before transformation:

import { useTheme } from '../zero-styled';

function Component() {
  const theme = useTheme();
  // ...rest
}

After transformation:

import _theme from '@pigment-css/react/theme';

function Component() {
  const theme = _theme;
  // ...rest
}

Fixes: mui/material-ui#42260

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

[siriwatknp]

I think this should come from Material UI. Pigment should just call theme.toRuntime() and let Material UI decide what to add to the runtime.

In Material UI, we can export an adapter function that inserts .toRuntime() to the theme.

// next.config.js
import { createPigmentConfig, extendTheme } from '@mui/material/styles';

const config = createPigmentConfig(extendTheme());

module.exports = withPigment(config);

[siriwatknp]

If you agree with my proposal, I can create a PR to add the createPigmentCssConfig().

[mnajdova]

Agree with having this in Material UI side, and by default Pigment CSS can only add the CSS vars. What do you think?

[siriwatknp]

Yes, I think Pigment should call specific methods rather than owning the logic inside.

To let Pigment generate CSS variables from the theme:

create a method generateStyleSheets to theme. At build time, Pigment will create CSS file from the result of the method.

To create a runtime theme:

create a method toRuntime to theme. At build time, Pigment will use that result and export as JS (the result has to be a string)

To use the runtime theme:

import theme from '@pigment-css/react/theme';

[siriwatknp]

Here is my proposal, Material UI export a stringifyTheme function mui/material-ui#42476 for zero-runtime libraries.

From Pigment side, I see 2 choices:

1. Pigment calls a method from the theme, e.g. theme.toRuntime():

 // next.config.js
const { extendTheme, stringifyTheme } = require('@mui/material/styles');

const theme = extendTheme();

theme.toRuntime = () => stringifyTheme(theme);

module.exports = withPigment({
  theme,
})

2. Pigment read from the config

 // next.config.js
const { extendTheme, stringifyTheme } = require('@mui/material/styles');

const theme = extendTheme();

module.exports = withPigment({
  theme,
  runtimeTheme: stringifyTheme(theme),
})

I like this approach because regardless of the choice, it's not related to Material UI. In the future, stringifyTheme could be moved to Material UI plugin for Pigment.

[brijeshb42]

I like the first approach better, ie, theme.toRuntime. This way, users won't have to care about anything extra. We can make toRuntime method part of the createTheme/extendTheme from material-ui source code.
In future, this will anyways won't be part of the Pigment v1 release since the whole thing is very specific to Material UI. So we can move this over to the Material specific package.

I am naming the method to toRuntimeSource to be more explicit.

[siriwatknp]

Preapproved, please check my suggestions before merging.