Revise "Playground" story approach in the `@carbon/react` storybook

[tay1orjones]

Context

As a developer using @carbon/react, I need a way to copy and paste valid/working component code snippets from storybook, So that I can get a jumpstart using a component in my project, experiment in a sandbox/stackblitz, etc.

The @carbon/react storybook has supported this use case so far via the storysource plugin. It displays the code source of the current story being shown in the canvas. It meets this need fairly well if the story uses explicit values within the story.

Click to expand example


Although when controls/args are used, the source code doesn't work well for copy/paste because it contains storybook-specific code (...args) that would cause an error in any environment outside of our storybook:

Click to expand example


As-is experience

To combat this we have so far tried to follow a strategy where we only use controls/args on a single specific story named "Playground". Each component typically has one - controls are fully enabled, and other stories have explicit prop usage instead of controls. This way the story source is copy/paste-able for every story except the Playground story.

In some cases Playground stories can't be used because the component has variants that require different stories and aren't able to be contained in one Playground story. Button and StructuredList are an example of this currently. In these cases controls are enabled on every story and there is no Playground story.

This strategy and it's inconsistency is confusing for both maintainers and users of the storybook.

Proposal

Stories are intended to be authored using args. Every story should be updated to use args where possible. We could then delete the playground stories.

Another way to think about this is that we're renaming Playground stories to be Default. The goal isn't to encourage adding a new story for every variant of a component - instead this change encourages further reduction of stories towards greater reliance on args.

There are a few ways we can continue supporting the copy/paste use case:

• Enhance our docs pages to include Source or Canvas blocks, which appear to support dynamic code snippet generation when using args via the type option:

  • dynamic: Renders the story source with dynamically updated arg values

• Provide an "Open in Stackblitz" link on every story via the stackblitz addon, where the current story source can be opened in a sandbox for experimentation

Additional benefits of this approach include:

• Having one less story in every component folder
• A simplified story authoring experience that would match the storybook documentation
• Every story would support args, so we could use args for configuration in AVT and VRT tests, which would simplify the "arrange" portion of these tests

[sstrubberg]

I freaking love quality of life improvements like this. Let's figure out a way to slide this in. Might be a fun EOY project.

[tay1orjones]

Agree! It's kind of related to https://github.com/carbon-design-system/carbon/issues/12947, probably something to do alongside it actually.