Basic storybook implementation #1636

haszari · 2020-01-23T01:29:24Z

This PR is an experiment. Goals:

Install and configure storybook for our repo.
Add a meaningful story for at least one component.

What is Storybook? It's developer tooling to document and develop components in isolation, outside of the context of your app. For us this means we can develop and test things like PriceSlider or QuantitySelector outside of WordPress + Woo (+ Woo Blocks Plugin) environment.

Why? Documenting our components allows us as developers to be explicit about the intended use and interface (props) of a component. Designers and product people can easily test and experience components in isolation, so that as a broader product team we can build up a library of consistent components for building new features or iterating on the UI. It also provides a nice way to review our components alongside those from other projects (e.g. Gutenberg, wc-admin).

Check out storybook docs here: https://storybook.js.org

Check out Gutenberg project storybook here: https://wordpress.github.io/gutenberg/

Screenshot

What's working

Some stories to get us started:
- Button, ReadMore and PriceSlider from js/base/components
- ErrorPlaceholder and Icons from js/components
Component styles are used in storybook, with some base styles applied from @wordpress/components; we may need more base styles / resets to simulate a "typical" theme front end or wp-admin environment
We're using chunks of our webpack config directly, mixed-in with Storybook defaults; hopefully this is reasonably stable
npm run storybook to launch storybook server - open browser to http://localhost:6006/
npm run build-storybook to build a static storybook site to storybook-static folder (we could publish this somewhere, e.g. GitHub Pages)

What's not working

Woo runtime dependencies (i.e. globals) aren't available, and some components depend on them, in particular wcSettings (see ProductPreview for an example broken story). I'm thinking we handle this as a follow-up; we can still write useful stories for many components.

How to test the changes in this Pull Request:

Clone this branch, npm install (a few new things).
npm run storybook to run storybook dev server.
Browse to http://localhost:6006 and browse component stories. Stories are alongside each component in a stories folder (similar to Gutenberg project).
Write a story for a component :)

Changelog

Dev: Added Storybook for documenting internal components.

haszari · 2020-01-27T03:30:58Z

This PR has been rebased (package.json conflicts)

nerrad

Great work @haszari ! This was working for me. I've left some feedback inline that can be addressed. Also, I'd like if we could add the same storybook addons as what gutenberg is using. All of them have great utility and it should be trivial to setup in this pull. That way going forward as we build and expand on stories we can utilize these add-ons. Having it configured from the get-go saves having to figure things out later.

@storybook/addon-docs: allows us to add extra docs for stories to help explain things further if needed.
@storybook/addon-knobs: allows for configuring variations of props fed to components in a story by the user (which can be useful for demonstrating and seeing various behaviour controlled via props).
@storybook/addon-storysource: displays the source of the story in the storybook which I think is super useful for seeing the code used for the story (which is another way for developers to learn how things are implemented).
@storybook/addon-viewport: This allows us to display stories in different sizes and layouts. Super useful for seeing responsive behaviour (does it behave as expected with breakpoints etc).
@storybook/addon-a11y: This adds some accessibility checks to stories. I think this can help us keep on top of any potential accessibility issues in our components.

Along with the potential followups already identified, I also think it'd be neat if (in a followup at some point) we could wire things up so that pulls trigger the creation of an accessible storybook that can be viewed along with the pull. This could potentially help with visual reviews of components as well (Gutenberg is doing something similar). But that's definitely not needed right away.

assets/js/base/components/button/index.js

assets/js/base/components/price-slider/stories/index.js

assets/js/components/error-placeholder/stories/index.js

assets/js/components/icons/stories/index.js

assets/js/components/product-preview/sad-stories/index.js

storybook/webpack.config.js

haszari · 2020-01-30T01:59:11Z

@nerrad Thanks for the feedback – now ready for a final review.

Note regarding addons – these are installed and configured (based on Gutenberg config) now. I've confirmed that they don't break the build and show up in the Storybook UI. I figure we'll need to revisit these in subsequent pulls as we add more stories - I haven't tested and configured all addons.

I did some brief testing and some aren't fully working out of the box:

a11y - the audit seems to never finish
storysource - never seems to find the story source

Rather than hold up merging this initial PR on investigating these addons, I suggest we merge and handle as follow up on the first few stories.

viewport works great out of the box. knobs and and docs need opt-in per story to do useful stuff, we should use when writing the next few stories :)

haszari · 2020-01-30T18:48:30Z

Looks like I need to rebase again. Keen to merge this ASAP!

- fixes scss imports breaking storybook build - note scss / styling doesn't work yet + organise our component stories into folder

- see also storybookjs/storybook#6201

…ussion)

append our webpack aliases to storybook webpack config

- PriceSlider expects client to handle onChange and pass in new min/max

- icons components are changing in #1644 - we need to refactor/do more work to get ProductPreview working (settings globals)

nerrad

I pushed a couple of commits that fixed the inoperative addons. I've added some comments for things that should be addressed. Once that's done, go ahead and merge (so pre-approving).

.eslintignore

nerrad · 2020-01-30T20:19:55Z

assets/js/base/components/button/stories/index.js

+/**
+ * External dependencies
+ */
+import React from 'react';
+


This is not needed.

nerrad · 2020-01-30T20:21:37Z

assets/js/base/components/price-slider/stories/index.js

+/**
+ * External dependencies
+ */
+import { React, useState } from 'react';


React is a default export (so usage is wrong) and is not needed. useState should be imported from @wordpress/element.

nerrad · 2020-01-30T20:22:07Z

assets/js/base/components/read-more/stories/index.js

+/**
+ * External dependencies
+ */
+import React from 'react';


No need to import React. To save repeating this everywhere, this comment applies to everywhere. Importing is not needed because the JSX is handled via babel pragma.

haszari requested a review from a team January 23, 2020 01:29

haszari self-assigned this Jan 23, 2020

haszari added the status: in progress label Jan 23, 2020

nerrad added tools Used for work on build or release tools. and removed status: in progress labels Jan 24, 2020

haszari added the status: needs review label Jan 27, 2020

haszari requested review from senadir, nerrad and mikejolley and removed request for a team January 27, 2020 02:59

haszari changed the title ~~Try/storybook~~ Basic storybook implementation Jan 27, 2020

haszari force-pushed the try/storybook branch from 0ee1928 to 658127b Compare January 27, 2020 03:28

nerrad added this to the 2.6.0 milestone Jan 27, 2020

nerrad suggested changes Jan 28, 2020

View reviewed changes

haszari requested a review from a team as a code owner January 30, 2020 00:54

haszari force-pushed the try/storybook branch from 2a22d84 to 2a577d6 Compare January 30, 2020 01:49

haszari assigned nerrad Jan 30, 2020

haszari added the action: needs feedback label Jan 30, 2020

haszari added 9 commits January 31, 2020 07:55

install & configure storybook (via magic npx script)

8a96c2e

fix indentation in storybook generated files

0c27294

eslint ignore generated storybook files (for now at least)

f4387dc

unhide storybook folder, consistent with Gutenberg project

051b3de

demo story for one of our components (with no css/styles)

f263aed

hack in scss webpack config & add story for button:

9138151

- fixes scss imports breaking storybook build - note scss / styling doesn't work yet + organise our component stories into folder

git ignore storybook-static build folder

6d10ace

pin dependencies for storybook

687509b

piggy-back off main webpack config for storybook module.rules (for scss)

fe6d629

haszari added 21 commits January 31, 2020 07:55

add --ci flag to prevent storybook opening new browser tab…

141455a

- see also storybookjs/storybook#6201

rename default stories to Default (following Gutenberg pattern)

a50dfbd

add story for ErrorPlaceholder

d9f9eed

failing ProductPreview story (committing to PR as an example for disc…

5d05fa9

…ussion)

storybook for components/icons

896335f

fix aliased dependencies in components for storybook:

a6dbd97

append our webpack aliases to storybook webpack config

basic story for PriceSlider (looks right but interaction broken)

bf921fd

fix PriceSlider user interaction:

482fc99

- PriceSlider expects client to handle onChange and pass in new min/max

add comment about priceslider max/min (todoish)

728892a

remove default stories from storybook scaffolding

5fe188f

organise stories by module (aka folder in codebase)

52aead2

package-lock update after rebase

60fd111

remove unnecessary ignores (default stories are gone)

fd6b9f8

delete experimental/risky/broken stories:

b2c9bda

- icons components are changing in #1644 - we need to refactor/do more work to get ProductPreview working (settings globals)

remove unnecessary import

47ac863

clarify PriceSlider component intended usage comment in story

7483d9e

remove redundant wrapper divs from stories

3c0909f

add common storybook addons (used by Gutenberg storybook)

8d584da

rebuild package.lock after rebase

2eb1890

remove unnecessary wrapper div

6b9293a

package fixes after rebase

3574a99

haszari force-pushed the try/storybook branch from 0d3c01a to 3574a99 Compare January 30, 2020 19:04

nerrad added 2 commits January 30, 2020 15:07

add configuration for storybook source loader

0a353ac

add decorators for a11y and knobs plugins

d922bd5

nerrad approved these changes Jan 30, 2020

View reviewed changes

woocommercebot added status: ready to merge and removed status: needs review labels Jan 30, 2020

remove unnecessary react import & import useState from WP

20b9d79

haszari merged commit 1f30102 into master Jan 30, 2020

haszari deleted the try/storybook branch January 30, 2020 20:59

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Basic storybook implementation #1636

Basic storybook implementation #1636

haszari commented Jan 23, 2020 •

edited

Loading

haszari commented Jan 27, 2020

nerrad left a comment

haszari commented Jan 30, 2020

haszari commented Jan 30, 2020

nerrad left a comment

nerrad Jan 30, 2020

nerrad Jan 30, 2020

nerrad Jan 30, 2020

Basic storybook implementation #1636

Basic storybook implementation #1636

Conversation

haszari commented Jan 23, 2020 • edited Loading

Screenshot

What's working

What's not working

How to test the changes in this Pull Request:

Changelog

haszari commented Jan 27, 2020

nerrad left a comment

Choose a reason for hiding this comment

haszari commented Jan 30, 2020

haszari commented Jan 30, 2020

nerrad left a comment

Choose a reason for hiding this comment

nerrad Jan 30, 2020

Choose a reason for hiding this comment

nerrad Jan 30, 2020

Choose a reason for hiding this comment

nerrad Jan 30, 2020

Choose a reason for hiding this comment

haszari commented Jan 23, 2020 •

edited

Loading