Storybook: [addon-docs] How to customize order of props table and previews?

[necolas]

Is your feature request related to a problem? Please describe.

I would like the docs page for a component not to render the first "story" above the prop types table. Also for the preset to load <name>.mdx files and not just <name>.stories.mdx.

Describe the solution you'd like

How to customize the page so I can control the order of the blocks and rename titles like "Stories" to "Examples". Or, how to rely entirely on a custom MDX page and insert a props table.

Describe alternatives you've considered

I looked through the available docs for addon-docs but didn't find anything that could help me do this myself.

Are you able to assist bring the feature to reality?

No

[necolas]

Looking through the source code it seems like there's meant to be a way to do this, but I get an empty props table that says "no component found"

import { Meta, Props } from '@storybook/addon-docs/blocks';
import { ActivityIndicator } from 'react-native-web';

<Meta title="Components|ActivityIndicator" component={ActivityIndicator} />

# ActivityIndicator

Displays a customizable activity indicator.

## Props

<Props />

I also think it could be easier to use MDX with examples if the ID wiring were explicit rather than using strings you discover by running the app. For example:

import { Meta, Props, Story, Preview } from '@storybook/addon-docs/blocks';
import { ActivityIndicator } from 'react-native-web';
import examples from './ActivityIndicator.examples.js';

<Meta title="Components|ActivityIndicator" component={ActivityIndicator} />

# ActivityIndicator

Displays a customizable activity indicator.

## Props

<Props />

## Examples

<Story item={examples.large} />

[shilman]

Hi @necolas! Let me try to answer with what's already there, and then maybe we can figure out what changes would be useful.

For the props table, try:

<Props of={ActivityIndicator} />

For customizing/overriding the DocsPage, there are a few options:

• Slots. You can override any section on DocsPage via slots. Documentation might need some work, but it's there: https://github.com/storybookjs/storybook/blob/next/addons/docs/docs/docspage.md#docspage-slots
• MDX. You can override story docs with MDX using this recipe, which is similar to what you've written above: https://github.com/storybookjs/storybook/blob/next/addons/docs/docs/recipes.md#csf-stories-with-mdx-docs
• Templates. You can override docs.page to be any react component, so technically you can render whatever you want there. DocsPage is a template that gets rendered to every story by default. In the future, I'll be stylizing how to do DIY templates, but for now it's DocsPage, MDX or you're on your own. https://github.com/storybookjs/storybook/blob/next/addons/docs/docs/docspage.md#replacing-docspage

Let me know what you think!

[necolas]

Hi Michael,

of={ActivityIndicator}

Thanks this did the trick!

At the moment I manually document types as follows (to avoid cluttering the docs with the shared types):

  ...ViewProps
  color: string
  size: number

The automatic storybook props table will inline all the View props. That's understandable and I'm not really sure how it could be any different. But thought I'd share.

You can override story docs with MDX using this recipe, which is similar to what you've written above

Thanks, sorry I missed that, I'll give it a try!

[shilman]

@necolas Just fixed a bug in that recipe, sorry! https://github.com/storybookjs/storybook/blob/next/addons/docs/docs/recipes.md#csf-stories-with-mdx-docs

[necolas]

When I do:

<Preview>
  <Story name="basic">{stories.basic}</Story>
</Preview>

The code shown is stories.basic rather than the component itself.

I'd also like to avoid having the sidebar show the individual stories, and have it behave more like a "doc" type, e.g., the "introduction" MDX example. Is that possible?

[shilman]

@necolas The story source is a limitation right now. Hard to do it in a cross-framework way. Suggestions welcome!

As for collapsing the docs, it's WIP. Need to revive the PR now that 5.2 is shipped: https://github.com/storybookjs/storybook/pull/7700

[necolas]

I noticed that Preview has a withSource prop but at the moment nothing is done with the 'none' value https://github.com/storybookjs/storybook/blob/next/lib/components/src/blocks/Preview.tsx#L72

[shilman]

😭 https://github.com/storybookjs/storybook/pull/8024

[DigTheDoug]

@necolas The story source is a limitation right now. Hard to do it in a cross-framework way. Suggestions welcome!

Is there an Issue created for this? I wasn't able to find a corresponding one in my search. I'd be happy to make one if there isn't. I _love_ the MDX docs for everything else it provides, but the code block not working is unfortunately a dealbreaker for using that format.

[shilman]

@DigTheDoug @necolas If you just define the stories in MDX, story source works perfectly. MDX files are loadable just like CSF and actually export an identical interface once loaded. But feel free to create an issue to track improving the source for the CSF/MDX mix case. Thanks! 🙇

[DigTheDoug]

@necolas Thanks, I was aware of that, but I feel that you give up the benefits of using CSF in that case, like having the portable components to use in testing, being able to define shared variables for stories, etc. But I will make an issue and at least see if others have any opinions or suggestions. Thanks!

[shilman]

@DigTheDoug True, there are advantages to using CSF. You can also document it with DocsPage, which doesn't have this issue. Let me see if I can hack in a solution to the MDX problem tomorrow. Might actually be an easy fix! 😄

[DigTheDoug]

Thanks @shilman, let me know if I can do anything to help! To be clear, DocsPage is _awesome_ and a huge addition to Storybook and I started testing it out as soon as it was announced to see if we could move our existing docs over to reduce the various things we have to manage. I'm trying to match the parity of our design system docs that currently exist in mdx, but in a separate gatsby context. They have descriptions for each story as well as usage guidelines, best practices, etc.

Anyways, thanks again for looking and let me know if I can help.

[necolas]

Another quirk I've encountered is that the Preview component doesn't always contain its content. This because this block of styles doesn't contain the content if its width exceeds the width of the preview (e.g., a horizontally scrollable element) if that itself uses flexbox to fill its parent container.

const ChildrenContainer = styled.div<PreviewProps>(({ isColumn, columns }) => ({
  display: 'flex',
  flexWrap: 'wrap',
  flexDirection: isColumn ? 'column' : 'row',
  marginTop: -20,

  '> *': {
    flex: columns ? `1 1 calc(100%/${columns} - 20px)` : `1 1 0%`,
    marginRight: 20,
    marginTop: 20,
  },
}));

https://github.com/storybookjs/storybook/blob/next/lib/components/src/blocks/Preview.tsx#L20-L31

Adding maxWidth:100% to the > * block fixes the issue; as does making the flexDirection:column and removing flexWrap:wrap. The right margin could perhaps also be removed; I'm not sure what it is for but it causes the right-edge of the preview to be intended.

[shilman]

@necolas would it be possible for you to issue a small PR if you think this a generalizable fix? I'm not sure I get it, but if it's in the PR and there's a repro in official-storybook, I'd love to get it fixed.

[necolas]

Do I put the patch up against 'next' branch? What's 'official-storybook'?

[necolas]

I don't understand how PRs work in this repo but here's a patch to illustrate what I meant https://github.com/storybookjs/storybook/pull/8628

[necolas]

For the props table, try: <Props of={ActivityIndicator} />

Did this change in one of the alphas? I updated to 5.3.0-alpha.43 and all the propTypes tables stopped rendering content

[shilman]

We're actively iterating the props table now, but I wouldn't have expected anything to break. Try upgrading to alpha.45? cc @patricklafrance

[necolas]

Hmm upgrading didn't fix the issue. Here's an example: https://necolas.github.io/react-native-web/docs/?path=/docs/components-activityindicator

This is how I have to populate the props table: https://github.com/necolas/react-native-web/blob/master/packages/docs/src/components/ActivityIndicator/ActivityIndicator.stories.js

(The RNW storybook should also give you an idea of why I'd like to remove the accordion dropdown on each docs page that contains stories, and prevent the page scrolling down past the description and props table)

[patricklafrance]

Hi @necolas

Thanks for the issue. The problem here is that ofProps doesn't have anything related to React.

Try to update:

const ofProps = () => {};

With

export const ofProps = () => <div>hey!</div>;

@shilman I dont see how this is related to the changes in 5.3. That might the bump to react-docgen 5.0 beta that cause the issue.

[shilman]

Thanks @patricklafrance -- you rock!!!

cc @danielduan on the react-docgen upgrade 😘

I think it's reasonable to expect the "props-having object" to be a React component. @necolas WDYT?

[necolas]

It was working in the 36 (ish) alpha. I only do this because the library itself doesn't use prop types or typescript, and the storybook doesn't use the library source files either. I'll try changing to return an empty div

[shilman]

w00t!! I just released https://github.com/storybookjs/storybook/releases/tag/v5.3.0-beta.1 containing PR #8628 that references this issue. Upgrade today to try it out!

You can find this prerelease on the @next NPM tag.

[necolas]

The problem here is that ofProps doesn't have anything related to React.

This doesn't seem to make a difference.

You can find this prerelease on the @next NPM tag.

The beta throws errors about @storybook/addon-docs/preset not existing, which the last alpha said to use in place of @storybook/addon-docs/react/preset, which also doesn't exist anymore.

[shilman]

The beta throws errors about @storybook/addon-docs/preset not existing, which the last alpha said to use in place of @storybook/addon-docs/react/preset, which also doesn't exist anymore.

Can you check your version and verify that all @storybook/* packages have upgraded to 5.3.0-beta.1? The new docs preset is working fine for me in a clean install (and it doesn't make sense that it's throwing errors unless you somehow have an old or maybe stable version). Thanks!

[shilman]

Hurrah!! I just released https://github.com/storybookjs/storybook/releases/tag/v5.2.8 containing PR #8628 that references this issue. Upgrade today to try it out!

[necolas]

Any suggestions on how to get the props table showing again?

[shilman]

Please upgrade all your @storybook/* packages to 5.3.0-rc.0. Here's a walkthrough for a clean setup: https://gist.github.com/shilman/bc9cbedb2a7efb5ec6710337cbd20c0c

[necolas]

Thanks. I'm using 5.3.0-rc.0. Does storybook need me to use CRA and TypeScript now?

[shilman]

@necolas Of course it doesn't require you to use CRA. Just providing that as an example setup that's working. Can you share what's not working and we can take a look at it?

[kungfuyou]

@necolas Im pretty new to docs and Im struggling to understand how I can override sections on DocsPage using slots. Could you post me a quick example of how to achieve this for eg. the propsSlot?

[shilman]

@kungfuyou Slots have been removed in 6.0. I recommend this instead. I think it should also work in 5.3: https://github.com/storybookjs/storybook/blob/next/addons/docs/docs/docspage.md#replacing-docspage

[coreybruyere]

I'm unable to display component props using the Props component with the of prop. I'm simply importing the component into an MDX component but props still aren't being displayed inside of Storybook. Is there something I'm missing from a Storybook API perspective?

https://github.com/coreybruyere/skeleton-ui/blob/master/packages/core/src/components/Box/Box.stories.mdx

[shilman]

@coreybruyere when i install your project on my machine it appears to be working for me:

There are some base props missing, which can be enabled by customizing the typescript handling:

https://storybook.js.org/docs/react/configure/typescript#overriding-the-configuration-to-infer-additional-props

[coreybruyere]

Thanks @shilman - missed that in the docs. Was focused on config docs and bypassed TS related docs. Need to learn to start reading the TS subsection in library docs more as a new TS convert!

[coreybruyere]

This is what I ended up using to filter unneeded props and display third party props I wanted -- In my case props from styled-system.

typescript: {
    reactDocgen: "react-docgen-typescript",
    reactDocgenTypescriptOptions: {
      compilerOptions: {
        allowSyntheticDefaultImports: false,
        esModuleInterop: false,
      },
      propFilter: (prop) => {
        if (prop.parent) {
          return (
            !prop.parent.fileName.includes("react") &&
            !prop.parent.fileName.includes("styled-components")
          );
        }

        return true;
      },
    },
  },