[Storybook] Add story code snippets

[mgadewoll]

Summary

https://eui.elastic.co/pr_7716/storybook/

Important

Disclaimer: This PR is the result of a spacetime/hackathon-y week and therefore mainly focused on building functionality instead of optimizing it as much as possible.

📢 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>)
• reerse-resolve css attribute to ensure it is not transformed to Emotion
• 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 a few 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: {
      // Optional way to override selected story args with manual values.
      // This is useful when the story arg would render unreadable or not useful output.
      // You can use interpolation markers #{} to ensure the value is output as is, this
      // is useful for e.g. functions to prevent them from being called.
      args: {
        propA: 'new value for propA',
        propB: "#{someFunctionCall('inputValue')}" // returns: propB={someFunctionCall('inputValue')}
      },
      // will skip code snippet generation for the component or story
      // @default false
      skip: true,
      // Useful for complex story composition wrappers (using the story component as 
      // nested child and not as direct return for `render`).
      // It will skip the outer story wrapper and return the code snippet for its children
      // instead. See the story for `EuiHeader/Multiple Fixed Headers` as an example.
      // @default false
      resolveChildren: true,
      // Useful when the story outputs additional contnt that should not be included in the
      // snippet and instead only the actual story component should be output as snippet.
      // @default false
      resolveStoryElementOnly: true,
      // The jsx renderer removes the story components default props. In case that they should 
      // be added to a specific code snippet it can be enabled by setting this option to `false`.
      // @default true
      removeDefaultProps: false,
    }
  }
}

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

Limitations

⚠️ Currently it's not yet supported to resolve "render functions" (either used as children or any prop value)
Components that make use of render functions (specifically for children) are currently (manually) skipped until support is added.

ℹ️ Currently this implementation is using Storybooks SyntaxHighlighter component to output the code snippets. This works mainly well but seems to have trouble properly detecting the code parts for large snippets which results in some partially uncolored snippets. We could in the future check to replace this component with another to improve.

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?

[cee-chen]

Any thoughts about dogfooding EuiCodeBlock for this instead of using Storybook's component? 👀

[mgadewoll]

Yeah that's a good idea! I think I briefly had that thought while initially building this but went with the Storybook component just because it works out of the box (as they use it for their docs source code) and saved me some time 😅.
Let me have another look how it would work with our component 👍

[mgadewoll]

Yeah I realize now why I took the Storybook component. There are issues using the EUI components because emotion is not properly resolved somehow for the addon panel. 🫠

You have tried to stringify object returned from `css` function. It isn't supposed to be used directly (e.g. as value of the `className` prop), but rather handed to emotion so it can handle it (e.g. as value of `css` prop).

[cee-chen]

Haha whoops 🙈 Yeah, Storybook probably needs the Emotion babel preset which is a whole fun setup thing (https://emotion.sh/docs/css-prop). You could the JSX pragma to see if that works?

[cee-chen]

But no worries if it doesn't, I'm totally fine with the Storybook component as-is!

[mgadewoll]

Yeah I had a first brief look at it to set this up but it didn't work as expected and it will need some more digging. I think I'd opt for leaving it as is for now and doing the update as a standalone task because I do think it would be generally good to be able to use our component as the Storybook SyntaxHighlighter has some limitation that it does not always properly highlighting the code.

🗒️ What I tried/noticed:

• Emotion works fine in the preview but not the manager parts
• I tried adding the emotion preset and it did absolutely nothing (it also seemed like the root babel config is not used - adding a manual config for Storybook with the preset resulted in custom components with css prop working but the imported EUI files still were broken)
• adding the JSX pragma worked when it was set in the EUI component files that are imported, not when added in the Storybook files (which is not an option)

[cee-chen]

Thoughts on using EuiEmptyPrompt or EuiCallOut instead of this container? Am I being too extra here right now? 😅

[mgadewoll]

No, that's a good idea! Why not reuse what we already have!
Let's see first if we can hide the panel for not available code snippets because we would not need this, if we just hide it 😄

[mgadewoll]

Ah wait, for the loading state it would still be used, so yes! I'll check how that'll look like 🙂

[mgadewoll]

ℹ️ This is blocked due to the same issue around Emotion mentioned here.

[cee-chen]

Pulled this down to test and the EuiDatePicker story is working perfectly!! Seriously huge kudos for this fantastic work Lene, this is going to be an amazing tool for devs to use! 👏 🚀

[kibanamachine]

Preview staging links for this PR:

• Docs site: https://eui.elastic.co/pr_7716/
• Storybook: https://eui.elastic.co/pr_7716/storybook
• New docs: https://eui.elastic.co/pr_7716/new-docs

[elasticmachine]

💚 Build Succeeded

• Buildkite Build
• Commit: dbb9a20

History

• 💚 Build #2265 succeeded 58f724e
• 💚 Build #2261 succeeded 26f4abc
• 💚 Build #2258 succeeded 2411218
• 💚 Build #2207 succeeded b7ff818
• 💚 Build #2206 succeeded 8b8e875
• 💚 Build #2205 succeeded 4a979ff

cc @mgadewoll