documenting enum values | Storybook | Page 1

snow coral Aug 11, 2023, 7:06 PM

#

Hello,
trying to tap into the general wisdom of the community and see if anybody had to come up with a solution on documenting a component property's type that happens to be a set of distinct values (enum values). For instance a component can have its type specified as a union member of values:

/**
   * Specifies the background of the component. The default value of this property is theme driven.
   */
  background?:
    | 'neutral'
    | 'orange'
    | 'green'
    | 'teal';

In Storybook, lets presume you have an mdx page rendering the properties of the component using an ArgTypes docs block. Does SB has a solution to document the individual property values?

ashen radish Aug 14, 2023, 12:48 PM

#

Does SB has a solution to document the individual property values?
what does this mean?

snow coral Aug 14, 2023, 1:06 PM

#

If a property has an enum type (resolved from a union type for instance), sometimes these values as not self explanatory and the need documentation. I was just wondering if this use-case came up at all for anybody and if there is a solution to this. The other use-case that I wanted to bring up is how to document if a property is deprecated? Marking with the jsdoc standard @deprecated tag. I could imaging the ArgsTable having an additional column for deprecation information

ashen radish Aug 14, 2023, 2:18 PM

#

If you have a comment above a prop, SB will add that to the API table. eg:

interface MyComponentProps {
  // Specifies the background of the component. The default value of this property is theme driven.
  background?:
    | 'neutral'
    | 'orange'
    | 'green'
    | 'teal';
}

#

If you want to add more context, then you can always add custom content using MDX

snow coral Aug 14, 2023, 6:45 PM

#

ashen radish If you have a comment above a prop, SB will add that to the API table. eg: ``` ...

Thanks for your answer, there is no problem with the description part of an API, react-docgen-typescript takes care of it, I was wondering how would someone document complex property values. Surely, there is no need to document the values of a size or color property, they are sort of self-explanatory. However we have several instances, where these property values might need a more detailed description. Right now the only way I know how to achieve this is to embed into the jsdoc comment block of the property, maybe using some HTML tags there to format properly.
Something like this:

type MyCompProps = {
/**
   * Specifies the size of the avatar. The default value of this property is theme driven.
   * <table>
   *  <thead>
   *    <tr>
   *      <th>Value</th>
   *      <th>Description</th>
   *     </tr>
   *   </thead>
   *   <tbody>
   *    <tr>
   *      <td>2xs</td>
   *      <td>Extra-extra small value</td>
   *    </tr>
   *    <tr>
   *      <td>xs</td>
   *      <td>Extra small value</td>
   *    </tr> 
   *    <tr>
   *      <td>sm</td>
   *      <td>Small value</td>
   *    </tr>
   *.......................
   *   </tbody>
   * </table>
   */
  size?: '2xs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';

You mentioned adding content using MDX...can you elaborate on that? Thanks!

ashen radish Aug 14, 2023, 6:52 PM

#

With MDX, you have full control over the contents of the page: https://storybook.js.org/docs/react/writing-docs/mdx

You can add more descriptions on the docs page. Including that html snippet.

snow coral Aug 14, 2023, 8:23 PM

#

ashen radish With MDX, you have full control over the contents of the page: https://storybook...

That's true however you can't really do much with the ArgsTable considering the use-case I described. No worries though, I imagine ArgsTable is not extendable, it only shows the argsType info that was discovered either through ract-docgen-typescript (description, defaultValue, type and name) or via the story metadata.
Whereas the particular use-case (documenting in a framework-supported way property values for instance) might sound like an edge case, I can't think of the same for documenting deprecated API in a more standard fashion. What I'm thinking here is that you can annotate your API with the standard jsdoc tag @deprecated and VSCode would actually recognize that so you can act upon that...what is Storybook's answer/approach to deprecation strategies? I think in the same way the ArgsTable shows today the default value of a property or the description, if the API was deprecated in a standard way (I just described above), that should also make its way somehow into the ArgsTable. Wdyt?

ashen radish Aug 14, 2023, 8:33 PM

#

You do have some control over how things appear in the table: https://storybook.js.org/docs/react/api/arg-types#table

One option would be to manually tag props as deprecated using table.category

const meta: Meta<typeof Button> = {
  title: 'Example/Button',
  component: Button,
  tags: ['autodocs'],
  argTypes: {
    backgroundColor: {
      table: {
        category: 'deprecated',
      },
    },
  },
};

It looks like this in Storybook

#

Using @deprecated to automatically group args sounds like a cool idea. You should consider submitting an RFC: https://storybook.js.org/docs/react/contribute/RFC#page-top

#documenting enum values