React - Storybook (Component workbench)

About

Storybook is a component workbench where you write story.

A story is a single state of your component. Technically, it is a function that returns something that can be rendered to screen.

UI component dev & test

Model

There are two basic levels of organization in Storybook:

  • the component (ie the javascript file in the stories directory)
  • and its child stories. (ie the exported function in the file)

Each story is a different instance of a component. You can have as many stories per component

Component

the default export defines metadata about your component:

  • including the component itself,
  • its title (where it will show up in the navigation UI story hierarchy),
  • decorators,
  • and parameters.
export default {
    component: Task,
    title: 'Task',
    id: 'Foo/Bar', // or 'foo-bar' if you prefer
    // Our exports that end in "Data" are not stories.
    excludeStories: /.*Data$/,
    decorators: [ ... ],
    parameters: { ... }
};

where:

  • id [Optional] is the id of the component/group (Doc)
  • title is the path/name of the component - title should be unique, i.e. not re-used across files.

id chosen is:'

  • id if present
  • otherwise title ?

Ref doc: Default export doc

Story

export const Baz = () => <MyComponent />;
Baz.story = {
   name: 'Moo',
   parameters: { 
       notes: 'popover tooltip' 
   },
};

where:

  • name is the name of the story
  • notes are tag for the search engine

id of a story is:

  • the name if present
  • otherwise, the export key

Url Path of a story is:

?path=/story/groupId--storyId
# example
?path=/story/foo-bar--baz

Hierarchy

Stories can be organized in a nested structure using / as a separator in the group title. Doc

export default {
  title: 'Design System/Atoms/Checkbox',
};

Configuration ShowRoots

import { addParameters } from '@storybook/react';

addParameters({
  options: {
    /**
     * display the top-level grouping as a "root" in the sidebar
     * @type {Boolean}
     */
    showRoots: false,
  },
});

Installation/Configuration/Getting Started

Install

  • Init
npx -p @storybook/cli sb init



Old way was ….

yarn add @storybook/react --dev
#or 
npm install @storybook/react --save-dev

Start

  • Config the start
"scripts": {
    "storybook": "start-storybook -p 9009 -s public"
  }
  • and Start
yarn storybook

Configure

Create the configuration file Doc

Where to find stories

Minimal: stories is a list of glob patterns that tells where the stories are located, relative to the configuration file.

module.exports = {
  stories: ['../src/components/**/*.stories.js'],
};

Addon Preset

module.exports = {
  stories: ['../src/components/**/*.stories.js'],
    addons: ['@storybook/preset-create-react-app','@storybook/addon-actions', '@storybook/addon-links'],
};

Story

  • Develop your stories
import React from 'react';
import { storiesOf } from '@storybook/react';
import { Button } from '@storybook/react/demo';

// There is two stories (.add)
storiesOf('Button', module)
  .add('with text', () => (
    <Button>Hello Button</Button>
  ))
  .add('with emoji', () => (
    <Button><span role="img" aria-label="so cool">😀 😎 👍 💯</span></Button>
  ));  

You may also locate them closer to components.

•
└── src
    └── components
        └── button
            ├── button.js
            └── button.stories.js

Run the Storybook

  • Run the Storybook
npm run storybook

Add-on

Action

Action is storybook native addons that permits to capture interaction via mocked callbacks called Actions

The callback appears in the actions panel of the Storybook UI when clicked.

So for instance when we build a pin button, we’ll seen it in the action panel.

Centered

Storyshot

With a snaphost test for each of our Task stories, if we change the implementation of Task, we’ll be prompted to verify the changes.

yarn add -D @storybook/addon-storyshots react-test-renderer
  • config
import initStoryshots from '@storybook/addon-storyshots';
initStoryshots();
  • Test
yarn test
# ie react-scripts test
PASS  src/storybook.test.js (7.372s)
  Storyshots
    Task
      √ Default (14ms)
      √ Pinned (1ms)
      √ Archived (2ms)

 › 3 snapshots written.
Snapshot Summary
 › 3 snapshots written from 1 test suite.

Test Suites: 1 passed, 1 total
Tests:       3 passed, 3 total
Snapshots:   3 written, 3 total
Time:        8.015s
Ran all test suites related to changed files.
  • if the snapshot change, the test will output:
› 3 snapshots failed from 1 test suite. Inspect your code changes or press `u` to update them.

Decorators

Decorators are a way to provide arbitrary wrappers to stories.

They can be used to:

  • add some `padding` around the rendered component.
  • wrap stories in “providers” –i.e. library components that set React context.

Searching

Doc search results will show up based on:

  • the file name / id
  • notes Doc

Example of story with notes.

export const callout = () => <Callout>Some children</Callout>;
callout.story = {
parameters: { notes: 'popover tooltip' },
};

Documentation / Reference


Powered by ComboStrap