DevDocs: Auto Proptype Documentation for Components and Blocks

[withinboredom]

Auto Proptype Documentation for Components and Blocks

Props are the way we configure child components. As a developer, it can be confusing sometimes as to what a simple change to a prop can do. It can change behavior and appearance. Wouldn't it be nice to tinker with the example in the Dev Docs?

Well, now you can.

Overview and Approach

In order to get prop types, the code has to be read, as there's no reliable way I could discover to read propTypes while the code is running. I used react-docgen to parse the component's source and figure out the propTypes. From there, I could have used a webpack loader or read it on the nodejs server. I chose to avoid the webpack loader for fear that I could have increased a production bundle size in some way. If my thinking is wrong in this, please let me know. ;)

Once having the propTypes in the client, it's fairly straightforward to render a table. There's some internal bookkeeping and two copies of the props being passed about. The flow goes something like:

One copy is used for rendering the table, and is the raw form the user is editing along with metadata, the other, is passed to the "component under props" -- for lack of a better term -- called computedProps. computedProps have been parsed and are sent to the child component.

Currently, the example component must be modified to pass props it receives onto its children, and is responsible for wiring up global state, if needed. The prop is called isShowingOff, which seems like an apt name for a prop which makes the component show off everything it is capable of.

The "editor" attempts to detect the presence of this prop, and will show a notification if it isn't present in the example component, alerting the user that their changes may not be propagated.

As a helpful tidbit, it also shows the import statement, in order to help developers save some time looking for where the shown component is located.

Feel free to check it out: on calypso.live

Currently, the only components able to be edited via the props-editor are:

• author-selector: which doesn't do much
• comment-button
• like-button

Still remaining

Alas, there's still a ways to go!

• Fix a bug where clicking the revert focuses the cursor instead of fully reverting
• Tests 🔴 -> 💚
• Redux, which should actually simplify things
• Add jsdoc to table components
• Documentation -- specifically around how an example component should be updated
• Documentation -- specifically around how to write a parser, in the event a new propType gets invented
• Documentation -- specifically propTypes
• Check for the possibility of a memory leak somewhere (may be unrelated to my code, but I'm going to check)
• Make the serverside code async (or switch to a module loader)
• General polishing
• Address any concerns that you may have

[mtias]

Adding a design concept from @adambbecker that could be useful to you:

[mtias]

Also, cc @MichaelArestad for some of the playground work that seems relevant to this as well.

[folletto]

I did a quick test, and I agree we need some more complete design input here. As a first test, my feedback would be:

1. It needs a clear indicator that the panel can be accessed. I'm imagining an icon on the right side of the title, but can be any kind of explicit actuator.
2. I think it should open a separate page, which would be the "component playground" page, with a directly addressable URL like: /devdocs/play/comment-button. This is very important because would allow easy discussions, testing and refactoring flows. It could also lose the sidebar.
3. The comment-button bit pre-fills a sort of search field, which indicates the component currently active for play.
4. Would be equally good if the URL could incorporate the changed parameters too, so I could just write anywhere "What about if we use $component like this $link" and it would be immediately accessible. The URL could be just: /devdocs/play/comment-button?tagName=div&commentCount=5.

With the above, I think we'd have laid the foundations of a great playground functionality. :D

[withinboredom]

Thanks! This is great feedback!

[withinboredom]

Closing as a proof of concept