Storybook Typescript documentation autogen

[vladoyoung]

Is your feature request related to a problem? Please describe. It would be great if there was some kind of documentation within the Storybook app itself, so we don't rely on the Reshaped site all the time. This would be beneficial in scenarios where our own instance of the design system is an older version than an updated source code version, or if we want to stick to being offline during development.

Describe the solution you'd like As much information within the Storybook documentation as possible, or at least a Typescript props table as the story arguments. Maybe a "Docs"/"Introduction" MDX page for each component? The documentation on the Reshaped site is excellent, so anything close to that would be amazing!

Describe alternatives you've considered I've tried setting this up myself multiple times, with multiple approaches, but was not successful. I've used the following guides and numerous other issues across forums related to the issues I was experiencing: https://storybook.js.org/addons/storybook-addon-react-docgen https://storybook.js.org/docs/api/main-config-typescript https://storybook.js.org/docs/configure/typescript https://storybook.js.org/docs/api/arg-types

Additional context I've hit a wall with all the approaches with various errors, or no errors at all and no meaningful output. I can't remember all of the issues I've encountered and I don't have any screenshots I can provide, but I would be glad to assist if need be!

[its-monotype]

Today React Aria released the Tailwind Starter Kit with their Components, they have a Storybook preview with Docs, and it seems that's what you want. I hope it would be a great example for reference.

[vladoyoung]

Yes, it should look like that. Although the Reshaped team might not be able to get the controls working with the current stories architecture they have set up. I personally am fine with just a props table of some sort, but having fully functioning controls would be a great addition too!

[blvdmitry]

Trying a few options right now and I think the main tradeoff is happening around the structure of stories. Right now we're grouping multiple component examples so everyone can use fewer Chromatic screenshots and be able to faster test various components props combinations. Like you've mentioned before – that doesn't work really well with the addons out of the box so I'm trying to find the right balance to have both, ideally without having to manually maintain yet another component props definition

[blvdmitry]

Seems like I've made some progress. It displays a new primary story for the documentation preview, props table and a list of all stories with their code snippets. The main bottleneck is in some of the components where auto inferring in react-docgen-typescript doesn't work as expected so it asks to provide the argTypes manually. I'll check how many components have that issue and maybe the best approach is to provide it for them manually.

[vladoyoung]

That's great progress @blvdmitry ! One thing to keep in mind is that if the "Show code" functionality shows the arrow function before the actual component code, you can mess around with the parameters for the components and change the source attribute to remove the arrow function.

Here are some resources for that: https://storybook.js.org/docs/api/doc-block-source#type https://github.com/storybookjs/storybook/issues/23366

Also, I was wondering if the decorator for direction, mode and theme were really necessary on the parent "Docs" page?

[blvdmitry]

I guess it depends on how you plan to use the docs. I assume in terms of having a place to refer the props outside of the TS definitions, I could just render the generated prop table and all stories. Stories in that case will be used mostly for the code snippets (assuming there are no additional controls), which makes me thing that maybe it's a good idea to render the stories source code in each story with an addon instead and only keep the docs for the props table

[vladoyoung]

That sounds like a good starting point to me. I guess the ultimate goal would be to stay within the storybook app as much as possible, instead of referring to the Reshaped site for props all the time. Just being cautious of developer workflows here. Code snippets and base argsTable would be a great starting point.

[blvdmitry]

So after some exploration, this was the furthest I could push it without having to maintain another documentation source. Probably it's a good indication to move some of the documentation markdown to the library itself to render it in storybook and then use it on the website too.

Each component gets 3 new panels:

Code – displays the story source code. Unfortunately for the use case of displaying it in the panel it displays the arrow function. It's different from the docs fix you've suggested (it worked if you render a separate docs page) and there is an opened issue in the storybook repo about it.

Controls - tries to infer all the properties component supports. It doesn't work with forwardRef and that's a known storybook issue, for the components using it – I will add some manually written prop tables. It also doesn't support compound components unless you create separate stories for them.

Finally, I've also implemented a very simple addon to display an iframe of the latest docs, not to keep it opened in multiple tabs

Gonna take tomorrow to manually provide the missing prop tables and we'll ship it in the next release

[vladoyoung]

This is absolutely amazing @blvdmitry ! I'm excited to see it running on the next release!

Unfortunately for the use case of displaying it in the panel it displays the arrow function

I somehow got it working before on either component or whole docs level, but we can sort that as a bug fix later.

[blvdmitry]

Yeah, I had it working in the docs, but to show it in the panel - I had to use a different plugin (storysource), which has an issue with the source-loader changes that were made to storybook lately

[blvdmitry]

Done with all the changes for the release. With some forwardRef typings workarounds, I've also managed to generated props for components using forwardRef. The only two components that don't generate props are Dismissible and Autocomplete but they still have examples and link to the docs. Hopefully this will be fixed once I can migrate to react-docgen from react-docgen-typescript.

Going to be out in the upcoming release. Thanks for all your suggestions, really appreciate it 🙌

[blvdmitry]

Funny part, my forwardRef shenanigans turned into a micro-optimization 😅

[vladoyoung]

Thanks for sorting in such a quick manner! Really appreciate the support!