Documentation Demo JS - how to handle chrome vs components

[cee-chen]

@cchaos @miukimiu Please feel free to edit this initial discussion topic, I'm just getting the ball rolling here.

How do we want to standardize and DRY out demos that have certain overhead/controlling elements (such as buttons, radios/checkboxes/switches) etc. which directly control the demo to illustrate certain props?

1. https://elastic.github.io/eui/#/forms/super-date-picker#sizing for example includes all the JSX for the switches directly inside the Demo JS.

2. https://elastic.github.io/eui/#/forms/super-date-picker#update-button however abstracts out the chrome/controls to a separate imported component, and as such the Demo JS is much cleaner.

I believe Caroline also mentioned there were even more options or approaches, but I can't remember them offhand currently, so would appreciate a refresher.

[cchaos]

Yep, expanding on your examples above and adding some more:

1. The most basic setup allowed today in the big JSON config of _example.js files

{
  sections: [
    {
      demo: <Example />, // Contains all the toggles
      source: [
        {
          type: GuideSectionTypes.TSX,
          code: ExampleSource,  // Contains the code for all the toggles
        },
      ],
    {
  ]
}

The downside here is that the copy/paste source code contains a lot of cruft that was only meant for the example. Originally we tried to remedy this with the Snippet tab but it's a lot to maintain and our survey says people rarely use it especially compared to the source code tab.

---

2. Move the component render portion of the demo to another file and only import that in _example.js for the source code.

{
  sections: [
    {
      demo: <Example />, // Contains all the toggles and imports the component demo source
      source: [
        {
          type: GuideSectionTypes.TSX,
          code: ComponentDemoSource,  // Contains the code just for the component demo
        },
      ],
    {
  ]
}

The downsides to this approach is that it creates yet another file to have to be created and requires passing through the configurations which show up as required props in the source code component. Though some could say that this is a "pro" because it also gives them a full starting file if they're creating an EUI component abstraction.

---

3. Remove the demo and source keys from the configuration and import the <GuideSection> directly into the demo code and render it in the text key.

{
  sections: [
    {
      wrapText: false, // Required so that the demo isn't wrapped by EuiText
      text: (
        <>
          <EuiText>
            <p>...Intro</p>              
          </EuiText>
          <EuiSpacer />
          <Example /> // Contains all the toggles and manually renders GuideSection to pass all the demo and source code to
        </>
      )
    {
  ]
}

If the toggle are simply switching out example files, this is a really clean approach to the docs user. The source code is exactly what's rendering and the toggles sit outside of the example panel.

---

Once we're utilizing no. 3 more often, it makes the whole config style _example.js pages less necessary and more cumbersome. I think @miukimiu and I both prefer option 3 and to consider just making it easier to make a single file for each example section.