Migrate to storybook essentials, controls and evaluate docs / mdx format

[haszari]

Storybook has a brand new way of writing stories and making interactive component docs.

Most of this is available in a bundle of addons: essentials.

In particular I think we could benefit from:

• Migrating from knobs (no longer best practice) to controls (more automatic).
• Writing our stories as MDX with inline documentation.

Outcomes for this issue (or separate follow up if needed):

1. Add essentials as dependency and adjust configuration if necessary.
2. Update one story that uses knobs to using MDX.
3. Add docs to a story using MDX.

Alternatively could add docs for a new component (not in storybook) to demonstrate best practices (2 & 3).

[nerrad]

I think the path you outline for this issue sounds good (pick a component with an existing story to write the new Storybook flow with and demonstrate how to do).

[haszari]

Hit a snag getting this going. The new addons use our PropTypes to automatically generate controls (knobs) etc from args (i.e. component props).

The problem is that our propTypes are not getting passed through the build, so no controls are working.

Storybook uses react-docgen to capture info from proptypes declarations, and I think that it's not working for us because it's configured to look in .mjs or .jsx files – all our components and stories are in .jsx files.

Here's the relevant config in Storybook: (props @shilman for finding this!)

https://github.com/storybookjs/storybook/blob/master/app/react/src/server/framework-preset-react-docgen.ts

[nerrad]

I'm sorry I missed this earlier, are propTypes the only way to generate controls? I'd actually like to move away from using propTypes and embrace typescript flavored jsdocs moving forward because it has better static typing than propTypes (which are runtime typing). Then we'd also be able to get rid of another import.

[haszari]

I'm sorry I missed this earlier, are propTypes the only way to generate controls? I'd actually like to move away from using propTypes and embrace typescript flavored jsdocs moving forward because it has better static typing than propTypes (which are runtime typing).

Sounds like a good plan to me @nerrad 😄

I don't think propTypes are the only option. You can definitely hint these manually - that could be a temporary workaround.

Under the hood it's using react-docgen, so I'm guessing that it's possible to use typescript type info, or similar type comments in our case.

I'll switch my investigation to getting docs and controls (etc, via args) working based on typescript comments, instead of PropTypes.

While we're on the topic, perhaps we could look at using TypeScript extension for our components and/or stories? If we are using TypeScript types, that feels like the path of least resistance to me (compared with using JSDoc). TypeScript is a superset of JS, so we could gradually adopt types. I'm not an expert in TypeScript - just an idea.

[haszari]

Storybook uses react-docgen to capture info from proptypes declarations, and I think that it's not working for us because it's configured to look in .mjs or .jsx files – all our components and stories are in .jsx files.

This was a red herring, I was confused by the regex - it definitely includes .js 🤦

[haszari]

More info about TypeScript-powered args/props/docs:

https://github.com/storybookjs/storybook/blob/next/addons/docs/react/README.md#typescript-props-with-react-docgen

https://github.com/storybookjs/storybook/blob/next/MIGRATION.md#react-prop-tables-with-typescript

storybookjs/storybook#10311

storybookjs/storybook#8532

I'm not sure if we need to do extra stuff to get the typescript stuff firing for our "TypeScript" in JSDoc comments, but 🤞 I'm working on that.

[haszari]

Still having trouble getting args working. I've logged an issue with Storybook here: storybookjs/storybook#12292

On the PR I've made a few changes and confirmed that TypeScript components and stories are working, so that's one option (but pretty drastic!).

[haszari]

We do have a simple workaround we could go with - args and argTypes. However this will mirror our proptypes or typescript info, so ideally we'd only have one place to document props. I don't know if this allows us to add description (docs) to props.

https://github.com/storybookjs/storybook/tree/next/addons/controls#my-controls-arent-being-auto-generated-what-should-i-do

Example:

import QuantitySelector from '../';

export default {
	title: 'WooCommerce Blocks/@base-components/QuantitySelector',
	component: QuantitySelector,
};

const Template = ( args ) => <QuantitySelector { ...args } />;

export const Primary = Template.bind( {} );
Primary.args = {
	disabled: false,
	quantity: 1,
	itemName: 'widgets',
};
Primary.argTypes = {
	disabled: { control: { type: 'boolean' } },
};

[haszari]

Moved this to icebox for now - focusing on cart/checkout for cycle.

[haszari]

I'd love it if we could start using MDX for our stories and/or automatically power our controls (new improved knobs) from our component source. The goals are:

• use the latest / greatest tech from storybook - controls
• reduce the boilerplate / repetition needed to set up interactivity (i.e. no extra code to tell knobs/controls about component props)

@opr I'm keen for your thoughts / ideas on this. We got stuck last time I looked, maybe things have improved now.

[github-actions]

This issue has been marked as stale because it has not seen any activity within the past 60 days. Our team uses this tool to help surface issues for review. If you are the author of the issue there's no need to comment as it will be looked at.

Internal: After 10 days with no activity this issue will be automatically be closed.

[github-actions]

This issue has been marked as stale because it has not seen any activity within the past 60 days. Our team uses this tool to help surface issues for review. If you are the author of the issue there's no need to comment as it will be looked at.

Internal: After 10 days with no activity this issue will be automatically be closed.