README

Storybook for DNA

Storybook for DNA is a UI development environment for your plain HTML snippets and DNA components. With it, you can visualize different states of your UI components and develop them interactively.

Storybook Screenshot

Storybook runs outside of your app. So you can develop UI components in isolation without worrying about app specific dependencies and requirements.

Getting Started

$ cd my-app

Add dependencies

Init npm if necessary

If you don't have package.json in your project, you'll need to init it first:

$ npm init

Add @chialab/storybook-dna

Add @chialab/storybook-dna to your project. To do that, run:

$ npm i @chialab/dna @chialab/storybook-dna -D

Add a npm script

Then add the following NPM script to your package.json in order to start the storybook later in this guide:

{
  "scripts": {
    "storybook": "start-storybook",
    "build-storybook": "build-storybook"
  }
}

Create the main file

For a basic Storybook configuration, the only thing you need to do is tell Storybook where to find stories.

To do that, create a file at .storybook/main.js with the following content:

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

For more information visit: storybook.js.org

Addons

The Storybook preset for DNA uses the Web Components Analyzer in order to extract properties, attributes, events and more from the component definition. This information can be very useful when used with the docs and knobs addons.

Configuring docs

Storybook Docs transforms your Storybook stories into world-class component documentation.

First, install the addon:

$ npm i @storybook/addon-docs -D

Then add the Storybook DNA preset for docs addon in your .storybook/main.js:

module.exports = {
  stories: [
    '../src/**/*.stories.[tj]s',
+   '../src/**/*.stories.mdx',
  ],
+ addons: [
+   '@chialab/storybook-dna/dist/docs/preset',
+ ],
};

This enable the support for mdx files compilation. You can now use the Meta, Preview and Story components to write your stories and the Props component to render the API documentation of the element.

import { Meta, Story, Preview, Props } from '@storybook/addon-docs/blocks';
import './Checkbox';

<Meta title="MDX/Checkbox" />

# Checkbox

With `MDX` we can define a story for `x-checkbox` right in the middle of our markdown documentation.

<Preview>
  <Story name="all checkboxes">
    <form>
      <x-checkbox id="Unchecked" label="Unchecked"></x-checkbox>
      <x-checkbox id="Checked" label="Checked" checked></x-checkbox>
      <x-checkbox appearance="secondary" id="second" label="Secondary" checked></x-checkbox>
    </form>
  </Story>
</Preview>

<Props of="x-checkbox" />

Configuring knobs

Storybook Addon Knobs allow you to edit props dynamically using the Storybook UI. You can also use Knobs as a dynamic variable inside stories in Storybook.

Install the addon:

$ npm i @storybook/addon-knobs -D

and update the .storybook/main.js file:

module.exports = {
  stories: [
    '../src/**/*.stories.[tj]s',
    '../src/**/*.stories.mdx',
  ],
  addons: [
    '@chialab/storybook-dna/dist/docs/preset',
+   '@storybook/addon-knobs/register',
  ],
};

Now we need to add two decorators to our stories: the withKnobs official decorator enables knobs, while the Storybook DNA withWebComponentsKnobs decorator automatically enables knobs for Web Components using the Web Component Analyzer.

In the .storybook/preview.js file add the following lines:

import { addDecorator } from '@chialab/storybook-dna';
import { withWebComponentsKnobs } from '@chialab/storybook-dna/dist/knobs';
import { withKnobs } from '@storybook/addon-knobs';

addDecorator(withWebComponentsKnobs);
addDecorator(withKnobs);

Storybook also comes with a lot of addons and a great API to customize as you wish.

Usage no npm install needed!