feat(cli): static style extraction

[connor-baer]

Follow-up to #477. Closes #479.

Purpose

There are some web projects at SumUp that can't or don't use React. They need to implement all styles from scratch and need to be updated separately. We can solve this by extracting the styles from the React components as static CSS.

This was an experimental feature in v1. The migration to TypeScript as part of v2 broke the extraction script. This is a re-implementation with the goal of making the feature production-ready.

Approach and changes

• Install the babel-plugin-react-docgen-typescript to extract prop type information from the components. This information is used to render every variation of a component and capture the corresponding styles.
• Improve the static style extraction logic to account for changes in Emotion's internals and other edge cases. Migrate to TypeScript and integrate the script with the CLI.
• Document each component that supports static style extraction.

Technical implementation

1. Extract the docgen information at build time and save it to a file that is included in the dist bundle. This needs to happen at build time because we need access to the TypeScript source files to be able to extract this information.
2. Users install the package and call the yarn circuit-ui static-styles command which validates the provided options and then spawns a child process.
3. The child process runs a script using @babel/node to generate the static CSS. The indirect call through @babel/node is necessary since the Emotion Babel preset is required to properly extract the styles and their classnames.

How to use

After installing @sumup/circuit-ui into their project, users can use the Circuit UI CLI to generate a custom stylesheet. Below is an overview of the available options:

$ yarn circuit-ui static-styles --help

Usage:
  --theme             The name of the theme to use.
                                          [options: "light"] [default: "light"]
  --components        A comma separated list of the components to include.
                      Also supports "all" or "none".
                                                       [array] [default: "all"]
  --global            Whether to include global styles.
                                                     [boolean] [default: false]
  --customProperties  Whether to use CSS custom properties (variables).
                                                     [boolean] [default: false]
  --pretty            Whether the CSS should be formatted with prettier.
                                                     [boolean] [default: false]
  --filePath          Path to the file where the stylesheet should be saved,
                      relative to the current directory.               [string]
  --help              Show help                                       [boolean]

Future improvements

The CLI could be moved to a separate package (perhaps as part of #703?). This would have the following benefits:

• @babel/node, prettier, yargs, and cross-spawn could be removed from the component library's prod dependencies.
• react, react-dom, @emotion/core, @emotion/cache, @sumup/design-tokens could be added to prod dependencies (instead of peer), so we could run the CLI without installing it first: npx @sumup/circuit-cli static-styles --help.

There should be better documentation for the available classnames. We might be able to build a Storybook addon similar to Storybook's PropsTable to extract and display them.

Definition of done

• Development completed
• Reviewers assigned
• Unit and integration tests
• Meets minimum browser support
• Meets accessibility requirements

[vercel]

This pull request is being automatically deployed with Vercel (learn more).
To see the status of your deployment, click below or on the icon next to each commit.

🔍 Inspect: https://vercel.com/sumup-oss/circuit-ui/830ac4wv0
✅ Preview: https://circuit-ui-git-feature-static-style-extraction.sumup-oss.vercel.app

[codecov]

Codecov Report

Merging #714 (7fa7766) into canary (073fd43) will decrease coverage by 0.03%.
The diff coverage is 90.00%.

@@            Coverage Diff             @@
##           canary     #714      +/-   ##
==========================================
- Coverage   93.68%   93.64%   -0.04%     
==========================================
  Files         131      132       +1     
  Lines        2280     2283       +3     
  Branches      643      644       +1     
==========================================
+ Hits         2136     2138       +2     
- Misses        119      120       +1     
  Partials       25       25              

Impacted Files	Coverage Δ
src/components/Anchor/Anchor.tsx	100.00% <ø> (ø)
src/components/Button/Button.tsx	97.56% <50.00%> (-2.44%)	⬇️
src/util/deprecate.ts	100.00% <100.00%> (ø)
src/util/warning.ts	100.00% <100.00%> (ø)

[connor-baer]

@robinmetral and I decided that static style extraction isn't the right approach to support non-React projects. It's brittle, doesn't have a nice API, and we lose out on important accessibility features that are baked into the React components.

We haven't decided on a better alternative yet. One idea is to migrate Circuit UI to a framework agnostic stack (e.g. web components or Svelte).