Ensure playground stories have working controls

tay1orjones commented 2 years ago

Every component in the storybook sidebar should have a Playground story, those stories should have operable controls.

High level checklist for each component:

Move .stories.js file out of next folder, or create .stories.js file and copy contents of *-story.js file over.
Remove deprecated knobs package and usage.
Ensure there is a playground story
Add argtypes to playground story
Pass ...args to playground story, spread them on the applicable component(s)
Make sure values are defined to enable controls view by default
https://github.com/carbon-design-system/carbon/issues/11249

FAQ:

What if there's no playground story but other stories have controls enabled on them?
- Ignore these components for now, we need to prioritize getting controls working for components that have nothing right now.

Checklist

[x] #11467
[x] #12351
[x] #11468
[x] #11463
[x] #11469
[x] #11471
[x] #11472
[x] https://github.com/carbon-design-system/carbon/issues/11894
[x] #11564
[x] #11719
[x] #11565
[x] #11716
[x] https://github.com/carbon-design-system/carbon/issues/11954
[x] #11717
- [x] components/Dropdown/next/Dropdown.stories.js
[x] #12161
[x] #12224
[x] components/FluidForm/FluidForm-story.js
[x] components/Form/next/Form.stories.js
- [x] #12339
[x] #12250
[x] #12248
[x] #12249
[x] ~components/Heading/Heading-story.js~
[x] #12584
[x] #12352
[x] #12255
[x] components/Layer/next/Layer.stories.js
[x] #11464
[x] #12162
[x] components/Modal/next/Modal.stories.js
[x] #11718
[x] #11562
[x] #11823
- [x] components/NumberInput/next/NumberInput.stories.js
[x] #12145
- [x] #12146
[x] #12226
[x] #12271
[x] #12272
[x] #12273
[x] components/Popover/next/Popover.stories.js
[x] components/ProgressBar/ProgressBar-story.js
- [x] components/ProgressBar/next/ProgressBar.stories.js
[x] #12227
[x] components/RadioButton/RadioButton-story.js
- [x] components/RadioButton/next/RadioButton.stories.js
[x] #12353
[x] components/Select/Select-story.js
- [x] #11466
[x] #12448
- [x] components/SkeletonPlaceholder/SkeletonPlaceholder-story.js
- [x] components/SkeletonText/SkeletonText-story.js
[x] components/Slider/Slider-story.js
- [x] components/Slider/next/Slider.stories.js
[x] components/Stack/next/Stack.stories.js
[x] components/StructuredList/StructuredList-story.js
- [x] components/StructuredList/next/StructuredList.stories.js
[x] #12251
[x] components/Tag/Tag-story.js
- [x] #11465
[x] #12583
[x] #12228
[x] components/TextInput/next/TextInput.stories.js
[x] components/Theme/next/Theme.stories.js
[x] components/Tile/next/Tile.stories.js
[x] #12356
[x] components/Toggle/Toggle-story.js
- [x] #11470
[x] components/ToggleSmall/ToggleSmall-story.js
[x] components/Toggletip/next/Toggletip.stories.js
[x] components/Toolbar/Toolbar-story.js
[x] components/Tooltip/Tooltip-story.js
- [x] components/Tooltip/next/Tooltip.stories.js
[x] components/TooltipDefinition/TooltipDefinition-story.js
[x] components/TooltipIcon/TooltipIcon-story.js
[x] components/TreeView/TreeView-story.js
- [x] components/TreeView/next/Treeview.stories.js
[x] #11606
[x] #12447
[x] #12486
[x] #12487
[x] #12488
[x] #12489
[x] #12490
[x] #12491
[x] #12510
[x] Storybook controls: Revisit Pagination nav
[x] #12588
[x] #12589
[x] #12664

joshblack commented 2 years ago

Process

Update stories to CSFv3
Remove withKnobs decorator, if it exists
Add the following snippet to the default export

export default {
  // ...
  parameters: {
    // ...
    controls: {
      hideNoControlsWarning: true,
    },
  },
  argTypes: {
    children: {
      table: {
        disable: true,
      },
    },
  },
};

[ ] Convert knobs to controls
[ ] Remove action from components
[ ] Add args to render, restructure, and pass to component
[ ] Rename Preview to Canvas
[ ] Rename Props to ArgsTable

How-to's

You can switch from action('onClick') to a control by giving it the type action

Questions

How should controls relate to compound components?
- For example, a control is for a prop inside of a component
Should props like children and className be visible under Controls?

Observations

Our stories are grouped around a component, like Accordion, but may include related components (like a skeleton) for which the controls do not apply
Controls can be confusing in compound component situations (how do we make it clear that controls are for an accordion item versus the accordion)

Approaches

Convert knobs directly to controls

joshblack commented 2 years ago

Goals

Easy to play around with a component to see what props may do in the component
Easy to reference/copy-paste an example into your project
It documents the component well (covers a variety of use-cases)
Easy to change
- Theme
- Language (RTL)
- Viewport

Options

Keep knobs as-is
Controls only for top-most component
Controls are a mix that emulates knobs
Add stories for sub-components

Questions

All stories have controls that are configurable or one playground story?
If we use controls, do we want to implement changes for all or only for playground stories?
What's the difference between a story and the content in a docs page?
Should we default to docs by default, instead of stories?

What's done in the industry?

It does not seem common to have controls implemented
https://govuk-react.github.io/govuk-react/

Preferences

Have explicit stories for common or documented use-cases

Options

Decision 1: controls are not prop tables
- Controls are meant to interact with the story to mess around with the component and see what props do interactively
- What this means:
- Controls will likely not have descriptions shown
- Controls will be grouped by component name
Decision 2: we should land on docs by default in production
Decision 3:

TannerS commented 1 year ago

Just an fyi @tay1orjones and @tw15egan I am handling

Ensure there is a playground story
Add argtypes to playground story

For TextInput in this pr => https://github.com/carbon-design-system/carbon/pull/12139

I also plan to open a pr to help out with more of these soon

tw15egan commented 1 year ago

Thanks @TannerS!

TannerS commented 1 year ago

I had a question for the team. here is a screenshot with numbers relating to my quesitons

1) When i see something like this (a task and a subtask of that task with two type of story files)

 components/Pagination/Pagination-story.js
    components/Pagination/next/Pagination.stories.js

does that mean too do both files? they both need playgrounds?

2) A lot of these components have a Default set up that basically has all the args and argtypes set up, i find myself basically duplicating these for a "playground". I am curious if this is ok or are the defauts suppose to be replaced. One example is pagination. once i understand intent i can improve my ongoing PR

3) do I need to only do storys in the next folder?

4) Some components like the Form and others, have no props for a playground, like this one has onlye classname and children. Technically for a playground class and children dont make much sense since u cant see anything or pass in a control with jsx but they are on the list. How should these be handled?

thanks in advance

cc: @tay1orjones @tw15egan @abbeyhrt

aledavila commented 1 year ago

@TannerS

We are removing -story.js and replacing it with whats in the next folder. All files in next must move into the root component folder and the next folder deleted.
Default is the main story that shows all of the component props with no controls. Controls only go in playground stories.
see 1
If there are no props that a user can play around with like form then you can omit the playground and do not enable controls.

carbon-design-system / carbon

Ensure playground stories have working controls #10751