[Storybook] Add story code snippets

[mgadewoll]

Summary

🚧 This PR is still being updated and annotated 🚧

📢 This PR adds code snippets to our stories. 🦄 👩‍💻

The goal of this is to improve devX by providing dynamically updated code snippets for the stories. The code snippet is generated on story load as well as when any args change (e.g. when controls in the controls table are being updated)

This new functionality for code snippets is provided in an additional story panel next to the available panels for "Controls", "Actions" and "Interactions".

The basis for the code snippet generation is heavily inspired (copied and enhanced) on Storybooks Source block. The internal jsxDecorator file was copied and then adjusted to our specific needs. The main functionality to generate a string from react elements comes from the react-element-to-jsx-string package that is used.

The overall setup

We run our custom jsxDecorator on every story as a decorator via preview.tsx. This decorator generates the code snippet as string and sends it via Storybooks Channel events to our newly added custom addon panel which outputs the code string using Storybooks SyntaxHighlighter copmponent.

The main updates to the jsxDecorator on our side are to ensure the code outputs clean and relevant code snippets.
What was considered:

• rename Emotion wrappers to the actual component name (whenever we use css on a component in a story it will be an Emotion component)
• rename stateful wrappers that start with the wording Stateful (requires us to follow an agreed convention)
• remove obsolete fragment wrappers (but keeps needed ones)
• remove story specific wrappers (e.g. layout or styling)
• keep related wrappers (parent & subcomponent or related by name)
• resolve any other unexpected wrapper we might add to structure complex stories
• rename internal component names (starting with _ underscore, <_Component> is changed to <Component>)
• resolve css object to style attribute
• ensure boolean props are output in a meaningful way (generally as shorthand but keep specifically defined false values where false has meaning)
• ensure a nice formatting

The updates happen in different stages in jsxDecorator:

1. pre-conversion: determine what react element should be passed to react-element-to-jsx-string and with which options
2. conversion: pass react elements to react-element-to-jsx-string
3. post-conversion: do additional replacements on the returned string
4. formatting: format the result using prettier

Options

Currently there are two addon specific parameter options added with this PR that can be used under the key codeSnippet in the parameters config key.

// meta or story config
const meta = {
  title: 'Navigation/EuiButton',
  component: EuiButton,
  parameters: {
    codeSnippet: {
       // will skip code snippet generation for the component or story
      disable: true,
      // useful for complex story composition wrappers (using the story component as nested child)
      // it will resolve the outer wrapper and return the code snippet for it's children
      // see the story for `EuiHeader/Multiple Fixed Headers`. `EuiHeaderAlert/Flyout Example` or `EuiHeaderAlert/Popover Example` as examples
      resolveChildren: true,
    }
  }
}

ℹ️ Stories will also be skipped whenever an anonymous function is returned as story function, e.g. from render().

Screenshots

skipped code snippet generation

Disclaimer

⚠️ This PR currently does not add tests for the jsxDecorator functionality yet.

QA

• review all stories and their generated code snippets
  • Are there unexpected outputs?
  • Are there opportunities to improve what we output?
  • Does everything run as expected?

[kibanamachine]

Preview staging links for this PR:

• Docs site: https://eui.elastic.co/pr_7716/
• Storybook: https://eui.elastic.co/pr_7716/storybook

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: e144ec5

History

• 💚 Build #1836 succeeded 6c1c416
• 💚 Build #1835 succeeded 03f6eb9
• 💚 Build #1833 succeeded 4f0ff78