[GSoC] Playground / Toggle System for Live Documentation

[thompsongl]

A better playground / toggle system for EUI live documentation. Right now we have flat, read-only code displayed next to static examples. It would be nice if people could change the code examples in-browser on our docs site and see the changes live in the examples.

Outcome
An edit mechanism that would allow users to change, add, or otherwise modify props and content in rendered examples.

Related Discussion

• Discuss comment; Please note that the ideas mentioned are not requirements but concept suggestions that would need to be thoroughly vetted.

• Discuss comment; "having the interactive playground inline in our documentation is something we'd really like to see"

---

Interested in working on EUI for Google Summer of Code? See more details here: https://github.com/elastic/gsoc

[thompsongl]

@anishagg17 We'll use this issue to discuss and track modifications to your proposal.

Comment in this thread and then I can assign the issue to you.

[anishagg17]

@thompsongl Sorry for the late reply , I think my mention notifications are turned off.

@anishagg17 We'll use this issue to discuss and track modifications to your proposal.

Sure this would be great!

[thompsongl]

@cchaos We'll use this issue to track discussion for the EUI docs project. Post anything you've been thinking about for design, etc.

I'll be updating the main summary area soon

[cchaos]

My current thoughts are that I'd like to avoid creating a new tab to each documentation section. Instead, I'm thinking that it's basically a separate page(application) with all the components listed in it's own side nav on the left and toggles/code editor on the right. Then each component in our normal docs would just have a button/link that goes to it's playground section in this new page/app. I'll probably think through the design/layout of this over the next month, but that's the basic idea.

[thompsongl]

I'd like to avoid creating a new tab to each documentation section. Instead, I'm thinking that it's basically a separate page(application) with all the components listed in it's own side nav on the left and toggles/code editor on the right. Then each component in our normal docs would just have a button/link that goes to it's playground section in this new page/app.

@anishagg17 You can start exploring this idea. I'll do some research, as well.
Some things to consider:

• How would this concept change the scope of your original proposal?
• How would this concept change the technology choices (i.e., react-live) in your original proposal?

[anishagg17]

Before coding , let's discuss several alternatives that can be used for this purpose

• react-live
• react-view
• react-cosmos-playground
• react-source-render (DEPRECATED)

Also ,

just have a button/link that goes to it's playground section in this new page/app

Inculcates creating a new section within the docs-site this would be the first step later we can use the library of our choice and utilise it

[anishagg17]

react-live

Pros

1. Same code can be used for both readOnly code and Playground
2. Some modifications would be required to codeExamples.
3. CodeEditor, ErrorDisplay, ComponentPreview all can be designed, customised.

Cons

1. Import Statements are not supported inside the code example. (We can pass code through a function to comment out import statements)
2. TypeScript code can't be used

[anishagg17]

react-view

Pros

• Import Statements are supported.
• Supports TypeScript code.
• Provides more flexibility, adding toggles, ranges

Cons

• We would have to write out separate codeExamples for the playground, but about 40% would be copy pasted. Same code can also be used for both readOnly code and Playground but we would have to write out some complex function to remove all import statements and use them for import prop that might require special care for some examples as in case of EuiSideNav one import statement is multiline.

 const params = useView({
    initialCode: `() => {
      const text: string = "Hey";
      return <h2>{text}</h2>;
    }`,
   scope: {
      /* Component Name */,
    },
    imports: {
      '@elastic/eui': {
        named: ['/* Component Name*/'],
      },
    },
  });

[thompsongl]

react-view looks interesting. Have you seen any usages where the prop configuration is less manual? Like, is it possible to consume prop types from PropTypes or TypeScript output?

[anishagg17]

Like, is it possible to consume prop types from PropTypes or TypeScript output?

Yes, that might be made possible with some modifications, checks.

@cchaos Can you add more clarity to the app do we need separate playground for Buttons can also be links and Button with icon or a single playground for Button would work?

[cchaos]

No there would be a single playground for each component, not docs example. So a single playground for EuiButton with toggles based on all the possible props.

[anishagg17]

@thompsongl these are the props definition rendered by doc-gen (only some props are mentioned for simplicity)

const docsProps = {
  color: {
    defaultValue: {
      computed: false,
      value: "primary",
    },
    description: "`text` color is set for deprecation",
    required: false,
    type: {
      name: "enum",
      value: [
        { value: "ghost", computed: false },
        { value: "text", computed: false },
      ],
    },
  },
  fullWidth: {
    description: "",
    required: false,
    type: { name: "bool" },
  },
};

And these are the prop definition required by the react-view component.

const modifiedProps = {
  children: {
    value: "Hello",
    type: PropTypes.ReactNode,
    description: "Visible label.",
  },
  color: {
    defaultValue: "primary",
    description: "`text` color is set for deprecation",
    required: false,
    options: { ghost: "ghost", text: "text" },
    type: PropTypes.Enum,
  },
  fullWidth: {
    description: "",
    value: false,
    type: PropTypes.Boolean,
  },
};

[thompsongl]

The similarities look promising.
Even if react-view isn't the answer, I would imagine that the output from the TypeScript props parsing project will be helpful. @ashikmeerankutty what kind of props output are you expecting from your project?
//cc @chandlerprall

[ashikmeerankutty]

{
  "description": "",
  "displayName": "EuiToast",
  "methods": [],
  "props": {
    "title": {
      "defaultValue": null,
      "description": "",
      "name": "title",
      "parent": {
        "fileName": "react-docgen-typescript/src/components/toast/toast.tsx",
        "name": "EuiToastProps"
      },
      "required": false,
      "type": {
        "name": "ReactNode"
      }
    },
    "iconType": {
      "defaultValue": null,
      "description": "",
      "name": "iconType",
      "parent": {
        "fileName": "react-docgen-typescript/src/components/toast/toast.tsx",
        "name": "EuiToastProps"
      },
      "required": false,
      "type": {
        "name": "string | ReactElement<any, string | ((props: any) => ReactElement<any, string | ... | (new (props: any) => Component<any, any, any>)> | null) | (new (props: any) => Component<any, any, any>)> | undefined"
      }
    },
    "onClose": {
      "defaultValue": null,
      "description": "",
      "name": "onClose",
      "parent": {
        "fileName": "react-docgen-typescript/src/components/toast/toast.tsx",
        "name": "EuiToastProps"
      },
      "required": false,
      "type": {
        "name": "(() => void) | undefined"
      }
    },
    "color": {
      "defaultValue": null,
      "description": "",
      "name": "color",
      "parent": {
        "fileName": "react-docgen-typescript/src/components/toast/toast.tsx",
        "name": "EuiToastProps"
      },
      "required": true,
      "type": {
        "name": "enum",
        "raw": "ToastColor",
        "value": [
          {
            "value": "\"primary\""
          },
          {
            "value": "\"success\""
          },
          {
            "value": "\"warning\""
          },
          {
            "value": "\"danger\""
          }
        ]
      }
    },
    "className": {
      "defaultValue": null,
      "description": "",
      "name": "className",
      "parent": {
        "fileName": "react-docgen-typescript/src/components/common.ts",
        "name": "CommonProps"
      },
      "required": false,
      "type": {
        "name": "string | undefined"
      }
    },
    "aria-label": {
      "defaultValue": null,
      "description": "",
      "name": "aria-label",
      "parent": {
        "fileName": "react-docgen-typescript/src/components/common.ts",
        "name": "CommonProps"
      },
      "required": false,
      "type": {
        "name": "string | undefined"
      }
    },
    "data-test-subj": {
      "defaultValue": null,
      "description": "",
      "name": "data-test-subj",
      "parent": {
        "fileName": "react-docgen-typescript/src/components/common.ts",
        "name": "CommonProps"
      },
      "required": false,
      "type": {
        "name": "string | undefined"
      }
    }
  },
  "hasHtml": true
}

@thompsongl This will be the output from the parser. It seems like it is similar to what required by react-view

[thompsongl]

That's great; thank you.

@anishagg17 what about using EUI components inside react-view? I think we would want to be able to use EuiCheckbox, EuiFieldText, etc. instead of the default form fields.

[anishagg17]

I have made a sample playground for EuiButton
those editor props can consumed by Eui-components also it provides a setter function as a prop to update the value of prop, so it was quiet easy setting up the playground.

code
demo

[anishagg17]

Can we have the roadmap for the first month?

[thompsongl]

This is awesome, @anishagg17
Nice job setting up that now.sh environment, also.

@cchaos What do you think about this concept?

[cchaos]

This is definitely very similar to the UI explorations I'm currently working on. The only concern I have is looking at the code, it seems very manual to create the "toggle" parts. I was hoping we could utilize more of the __docgenInfo or something similar to automatically pull in the props and it's supported values from the component itself.

[anishagg17]

it seems very manual to create the "toggle" parts

I don't think we would create many toggles as the working would proceed with initialCode prop , code for which would be extracted from any example demo thus toggles won't be utillized , and would make work much less manual.

EuiButton, EuiLink, EuiIcon, etc are some components for which live coding doesn't make much sense so ,I think toggles should be provided for them only, instead of initialCode as shown in the demo.

[thompsongl]

If body and actions are set to String, and title is faked then it works

Let's try this for EuiEmptyPrompt

let me know which section should I work next

Start with Layout components, then Utilities

[anishagg17]

@cchaos does EuiPortal(Utilities) requires a playground?

[thompsongl]

does EuiPortal(Utilities) requires a playground?

No, we can skip that one

[anishagg17]

@thompsongl #3959 marks the completion of all playgrounds 🎉 . Anything more that I need to do?

[cchaos]

@anishagg17 Thank you so much for all the work you did on this project!!! 🎉 🎉 It's amazing what's been accomplished over this past summer. The playground toggles really step up our documentation game and gives us such an easier way to test all the permutations of each component. Best of luck to you in future endeavors!

[thompsongl]

@anishagg17 Nothing more as far as EUI is concerned 😄 Just make sure you submit all your GSoC evaluations, etc. before the deadline later this week (if you haven't already).

You've done great work and should be proud of the last few months! I know all of us here were glad to have you and are thrilled with the outcome 🚀

[thompsongl]

Closing this because @anishagg17 did all the things

We'll track anything related to component playground in the future in separate issues.