eui

eui copied to clipboard

Summary

🚧 This PR is still being edited to ensure the changes are explained and commented 🚧

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

The code snippets are provided in an additional story panel next to the available panels for "Controls", "Actions" and "Interactions". 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)

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. additional 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?

I skimmed the decorators/ addon directory but it's A Lot to review, I may have to return to it again later when my brain is working 😅 @tkajtoch, any chance you would want to take a look / help code review that section as well?

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

:green_heart: Build Succeeded

• Buildkite Build
• Commit: dbb9a2055f517c1cd78e3a806ade3600e8709ba7

History

• :green_heart: Build #2265 succeeded 58f724e1799c89e8aafbb4c91eb79f85ab1d4b25
• :green_heart: Build #2261 succeeded 26f4abc1eebb8713fa3ebc960724c20c1f99d41c
• :green_heart: Build #2258 succeeded 2411218af4834b2334725924a1496cac4545f430
• :green_heart: Build #2207 succeeded b7ff818a914f8dbb622d38b84f400797ffbf9a36
• :green_heart: Build #2206 succeeded 8b8e8752db0a3deae0f8ad4c8038b5bd780f24ca
• :green_heart: Build #2205 succeeded 4a979ff518514305b13487e30d1b5d4ec1c29d55

cc @mgadewoll