Controls Need Functional Component, PropTypes, and DefaultProps?

[KenACollins]

The documentation for controls is inaccurate and incomplete.

Inaccurate: The docs include this statement "Controls does not require any modification to your components." but I found this not to be true. I had to change a class-based component to a functional component in order to see all my properties show up with their comments.

Incomplete: The docs don't explain at all how to get a comment to appear above each control on the Controls and Docs tabs. By reverse engineering the examples that come with a vanilla install I was able to figure out that I need MyComponent.propTypes and MyComponent.defaultProps in MyComponent.js, and each property requires a preceding comment.

[jonniebigodes]

Hi, @KenACollins I've picked up on this discussion and I wanted to give some insights into what was mentioned.
Regarding this:

Inaccurate: The docs include this statement "Controls does not require any modification to your components." but I found this not to be true. I had to change a class-based component to a functional component to see all my properties show up with their comments.

This is accurate and you can use class-based components at will. See here for an example component and story. Also you can check a deployed version of said component here.

Incomplete: The docs don't explain at all how to get a comment to appear above each control on the Controls and Docs tabs. By reverse engineering the examples that come with a vanilla install I was able to figure out that I need MyComponent.propTypes and MyComponent.defaultProps in MyComponent.js, and each property requires a preceding comment.

That's true and you need to include type checking with propTypes, but in this case, this is a standard industry practice that Storybook adheres to. Including type checking allows you to build robust components that will be automatically documented with Storybook, so that not only the developers have a clear sense of the component's requirements but also other stakeholders involved that might not be tech-savvy. Throughout the docs, we indirectly instruct our readers to adhere to this practice as well. Including a whole section in our Intro to Storybook tutorial. And also in our more advanced tutorial, Design Systems for Developers.

Let me know if you have further questions and we'll go from there.

Stay safe

[KenACollins]

Thanks for your response, @jonniebigodes. I will review your suggestions next week when I am back working on my Storybook design system. FYI, I did complete the Learn Storybook tutorial.

[KenACollins]

Okay, @jonniebigodes,

I reviewed your response. Using your code samples as reference, I was able to create a story for a class-based component and see controls as long as I pulled out the propTypes and defaultProps from the class and defined them below the class. But when it comes to the controls, I get different results depending on whether the component is a class or a function.

My component has 11 properties defined in propTypes, each with a preceding comment. I only defined two of them in the args property of each story. I have two versions of my component, one as a class and one as a function. I create two nearly identical stories files based on your example, the only difference being that one references the class component and the other references the function component. I added the following to .storybook/preview.js to ensure that comments would be displayed:

controls: { expanded: true },

The result I got on the Controls panel was:

• Class component: I only see the two properties I defined in args. The Description and Default columns are blank. Control column shows my hardcoded value from the story and is editable.
• Function component: I see all 11 properties. The Description column contains the comment pulled from propType, the Default column contains the value specified in defaultProps. The Control column shows my hardcoded value from the story and is editable.

Now, I don't really want to see all 11 properties on the Controls tab, they are not all passed by the developer, so I will have to hunt through the Storybook online documentation to find out how to hide some of them.

[shilman]

@KenACollins #13898

[KenACollins]

Hi Mike @shilman, Thanks for referring me to pull request# 13898. The technique described for selectively including or excluding properties from the Controls panel from within a story does not work for me after updating three of my Storybook packages and following the directions. I have added a comment in the pull request# 13898.

[KenACollins]

Okay, getting back to the issues I cited above, Storybook treats functional components differently from class components when it comes to the Controls panel. This is true of Storybook essentials package at 6.1.21 as well as 6.2.0-BETA. I currently have 6.2.0-BETA as that is the only way to get PR# 13898 and be able to exclude properties I don't want.

I started with our Button class component. I pulled out the static propTypes and defaultProps blocks and placed them outside the component definition at the bottom of the file. I then made a copy of this revised class component and rewrote it as a function.

For functional components, it works great. See screen shot below.

But the experience is different for class-based components. The Controls panel is sparse, devoid of properties, except those I explicitly code in the args property of the story and it leaves out the helpful comments and default values that the class component contains. Result is below.

Now, if I had to explicitly code every property I wanted to see via the args property, that would be okay, but the issue I can't solve is the missing comments. I need them to explain the meaning behind each property. We have a lot of reusable class-based components. Am I forced to rewrite them all as functions with React Hooks?

[shilman]

we are using react-docgen under the hood for JS, react-docgen-typescript for TS components. i would run the two different components (class-based and functional) through the respective tool and take a look at the output. if the output is the same for two equivalent components, then it's a bug in storybook. if it's wildly different, then that probably explains what you're seeing above.

[KenACollins]

Hi Mike (@shilman),

Interesting tool, react-docgen. I had never heard of it before.

Okay, I ran the two versions of my Button component by the react-docgen tool and the output was nearly identical. The only difference was that the class component has four methods (onMouseEnter, onMouseLeave, onClick, and getIcon) which appear in the methods property as shown below.

  "methods": [
    {
      "name": "onMouseEnter",
      "docblock": null,
      "modifiers": [],
      "params": [
        {
          "name": "event",
          "type": null
        }
      ],
      "returns": null
    },
    {
      "name": "onMouseLeave",
      "docblock": null,
      "modifiers": [],
      "params": [
        {
          "name": "event",
          "type": null
        }
      ],
      "returns": null
    },
    {
      "name": "onClick",
      "docblock": null,
      "modifiers": [],
      "params": [
        {
          "name": "event",
          "type": null
        }
      ],
      "returns": null
    },
    {
      "name": "getIcon",
      "docblock": null,
      "modifiers": [],
      "params": [],
      "returns": null
    }
  ],

The functional version of the Button component has the same four 'methods' as inner functions. Surprisingly, the react-docgen output for the functional component has a blank methods array...

"methods": [],

These results point to the problem residing in Storybook.

[KenACollins]

@shilman, @jonniebigodes - While my focus in this discussion topic is on the table that appears on the Controls panel, I found the ArgsTable of a Storybook Docs MDX file is just as prone to not appearing at all for a class component. I have opened a new issue for it here. My workaround until this is fixed is to rewrite all my class components as functions. It stinks and it is time-consuming so I hope I don't have to do this for long.

[shilman]

Would you be interested in contributing a fix to Storybook instead?

[KenACollins]

Uh, sure, Mike (@shilman)! How Storybook works is all magical to me but I guess I could take a look under the covers. I see that the ArgsTable component is located at node_modules\@storybook\addon-docs\dist\esm\blocks\ArgsTable.js but that it imports another ArgsTable component from @storybook/components and that one I could not find. I could try and figure out how it works and where it is falling short on class components. If you want to send me any additional details about the code base to point me in the right direction, you can find my contact details in my GitHub profile or let me know how else to discuss this offline.

But I won't be able to even consider looking into it until May. I have a date on the calendar - Thu April 29 - to introduce the design system to our core leadership team so I have to get cranking populating the system with reusable components and working on the slides for the presentation.