React-styleguidist: Suggestion: a configuration option to render props below examples

[n1313]

Today, prop definitions are rendered above usage examples, and I think this arrangement makes it slightly more difficult for a new reader to understand how the component is supposed to be used, because it is difficult to put props and their values into proper context without seeing the final result (the live example) and seeing what it does. If you don't know a component well and it uses some special terminology to describe itself (like "top bar", "bottom bar") then it won't make much sense to you until you see the live component. Therefore, I think that reversing this order (optionally?) so that the examples are put above props would be a UX improvement.

I'd like to use this repo's own README file as a demonstration of my point: the gif is placed above documentation links because a picture is worth a thousand words, and it conveys the concept of what react-styleguidist is and what it does is in a very compact and efficient way. I think the same idea could be applied to components as well.

Another demonstration would be a typical MDN page: an example of what Array.slice() does is put above its syntax.

Before:

1. Component title
2. Description
3. Props and methods
4. Examples

After:

1. Component title
2. Description
3. Examples
4. Props and methods

[sapegin]

I’d rather change the default view than add one more option. But I’d like to hear other opinions.

/cc @okonet @SaraVieira

[bluetidepro]

@sapegin I think the issue here is you will always have people that want them in specific order. Like, for example, I prefer the way you have it today than this. I would not like this change as the default personally. Maybe you could just make it a config array so you could put them in any order in a custom array and it would output in that order you specify. Something like ['title', 'description', 'props', 'examples'] maybe?

[sapegin]

You can already do this by overriding a component. Maybe it would be better to make this simpler.

[okonet]

This makes sense but I think what makes even more sense is to make those props interactive somehow. Probably this is something that should be evaluated after the plugin API is done?

[sapegin]

@okonet It depends on what do you mean by interactive. But this tab bar with props is already extensible, but don’t have an external API for that (which is #505).

[WaldoJeffers]

It's an interesting feature, but putting the props table after the examples can have a downside: if there are many examples, it makes it easier to completely miss it. In my usage of RSG, I often show a very simple use case of the component, add a bit of text, and then add several examples displaying roughly all possible combinations of props. If the props table was at the end, some people might not see it.

But I do hear your point on showing what it looks like before giving the full spec. Having a way to simply configure the order in which these sections appear is interesting.

Slightly unrelated question, is there a way to show the props table by default (currently hidden by default)?

[n1313]

@WaldoJeffers https://react-styleguidist.js.org/docs/configuration.html#showusage

[sapegin]

Looks like we shouldn’t change default order. So I’d suggest to make ReactComponentRenderer easier to modify. I’d remove all styles and replace them with react-spaceman.

https://github.com/styleguidist/react-styleguidist/blob/master/src/rsg-components/ReactComponent/ReactComponentRenderer.js

[siddharthkp]

Came here to start exactly this discussion 😄

1. Props after example

   It does make sense for new users to look at the examples first and then look at the props table, but for repeat users, it's exactly the other way round. Now, it's difficult to comment which is more common, it depends on the context of your library. Open source libraries and internal libraries will have opposite use cases.

   a) Which makes me wonder if this is a user config, not an author config?
   b) can be improved slightly by adding a tiny navigation on top?

1. The other approach is to merge the 2 and make the props easier to consume for both new and old users

   This makes sense but I think what makes even more sense is to make those props interactive somehow. - Andrey

   I have a simplistic proof of concept here from a project I'm working on: https://fabric.now.sh

2. Custom prop table

   I've realised that in some cases, the propTypes are not always a perfect mapping of how props can be used.

   Here's a use case where it works. type is the prop which accepts a few values.

   <Button type="primary"/>
   
   <Button type="transparent"/>
   

   Another way to make this is with directly the values. I like the API/developer experience of this approach more.

   <Button primary/>
   
   <Button transparent/>
   

   But, it's not possible to infer from propTypes that primary and transparent are conflicting props and only one of them can be used. This is something I've tried to tackle in the proof of concept (https://fabric.now.sh)

[sapegin]

I'm going to close this for now, but may revisit in the future.