feat(docs): add component explorer

[levithomason]

We've had a number of silent experiments for improving the docs. These are targeted at the ability to quickly understand and use component APIs. We've also had a number of requests and suggestions in this area. Due to this, I'm opening this PR as an RFC to put some of my current doc site ideas into the open and get feedback.

Be warned, the code is ugly as these are only experiments for now.

These efforts so far consist of two ideas. A component explorer and a code editor. Some mashup of these capabilities will result in the new doc site.

Component Explorer

What Does

• Generated forms based on component propTypes and _meta
• Rendered example
• Automatic callback logging
• Predefined initial props

What it Could Do

Work on all props

Right now, this only works on propTypes that use React.PropTypes and prop with enums defined in the component _meta. That leaves out all propTypes that use customPropTypes.

Ideally, I think we'd somehow move all prop definition into _meta so all props could give complete explorer capabilities. Also, the _meta itself can move out of the code and into the component doc block since we are parsing that as well. This would pull the doc code out of the runtime code.

Exist on every doc page

We currently do not display documentation for sub components though it exists. Once we do, the props table will likely have tabs at the top. One for the component and each of its sub components.

I'm thinking the "Examples" should also be tabbed. In those tabs, we could add "Explorer" which would load the explorer for that one component.

Multiple Named Example Sets

Currently, it defines a single "initial props" object for each component. It would be helpful in many cases to define a render function also. This is similar to how react-storybook defines stories, except in this case we would expose the props on the component to the user as well. So each example would have a render function, "initial props" applied to the component, and then allow the user to edit those props using the explorer form.

Sandbox DONE (all doc examples are editable)

What Does

• Define example files next to code, used as default editor text for the example
• Exposes React, Lodash, faker, and Stardust in the editor
• Autocomplete for React, Lodash, and Stardust components and props
• Live Rendered example
• List all props below editor

What it could do

• Become the editor for every component example
• Live as top level link in the docs sidebar, similar to the Babel "Try it out" repl
• Have the ability to load other examples

Try it

You can try each of these out on the playground branch by using the links in the sidebar:

[codecov-io]

Current coverage is 99.49% (diff: 100%)

Merging #427 into master will not change coverage

@@             master       #427   diff @@
==========================================
  Files           112        112          
  Lines          1767       1767          
  Methods           0          0          
  Messages          0          0          
  Branches          0          0          
==========================================
  Hits           1758       1758          
  Misses            9          9          
  Partials          0          0          

Powered by Codecov. Last update a89545d...31f8144

[Moeface]

This is really cool, nice work!

[brsanthu]

This is really nice. I think it would be even cool, if Explorer outputs into Sandbox, which outputs into output.

[levithomason]

That is a neat idea. It is sort of what I'm thinking for the combination of these as well. We could inject the explorerProps into the sandbox. Then allow the sandbox to have some syntax something like:

<Label {...explorerProps} />

Which would of course render the output.

[levithomason]

This combined with the ability to define multiple explorer prop sets would be really nice.

src/elements/Label/*-example.js

These define the editor content.

// DefaultLabel-example.js
const Example = () => (
  <Label {...explorerProps}>Inbox</Label>
)

// ImageLabel-example.js
const Example = () => (
  <Label {...explorerProps} image={faker.internet.avatar()}>
    Someone
  </Label>
)

// ColorLabel-example.js, defined with explorer props instead of inline
const Example = () => (
  <Label {...explorerProps}>Colored</Label>
)

src/elements/Label/explorer.js

This defines all the examples for this component.

import faker from 'faker'

const examples = [
  {
    title: 'A default label',
    code: 'DefaultLabel-example.js', // loaded as !raw text
  },
  {
    title: 'An image label',
    code: 'ImageLabel-example.js',
    props: {
      image: faker.internet.avatar(),
    },
  },
  {
    title: 'An colored label',
    code: 'ColoredLabel-example.js',
    props: {
      color: 'red', // this would set color to red in the explorer form
    },
  }
]

export default examples

I'm not sure about how to fit the list of examples, the explorer bar, the editor, and the rendered output on a single page though. Especially given wider components like Grid/Container/etc.

[levithomason]

Update

The editor is now incorporated with many features. I'll update this PR to only include the explorer work since every example is now a component sandbox.

/cc
@layershifter @jcarbo You'll need to npm i when updating your branches to get the new deps.

Editable Examples

Rendered HTML

Reset Changes

Imports & Exports Work

Errors

[jeffcarbs]

This is awesome!

[levithomason]

The current docs seem like they are covering this very well for now. Closing this for housekeeping and we'll consider it for future doc updates.

[agustif]

This has been discarded until notice? I was considering using storybook and storybook-knobs to do this but kinda hacking it in storybook, I did read your opinion on other issue about the lackings for your docs (which seems reasonable, maintaing code in-house is always better if manageable.

Anyways, my questions regards this feature, is in order to decide if it makes sense to open a community repo which can do this either your way or storybooks way (My goal is to have a GUI to edit props of Button for example, and being able to add props on the gui so I don't have views of all the variations, only the base + the docs + kobs for editing props. also while applying my own theming via less to semantic-ui's defaults and having Phoenix file_watch and do HMR with webpack

[levithomason]

I think it'd be great to improve our docs with this. If anyone has the time to invest to do so, I'd gladly review PRs and help out as I am able.