@ergosign/storybook-addon-pseudo-states-react

Storybook Addon Pseudo States

Storybook Addon Pseudo States allows you to automatically display pseudo states (and attribute states) of a component in Storybook's preview area.

Framework Support

Framework	Display States	Tool-Button to show/hide
Angular	+	+*
React	+	+*
Lit	+	+*
HTML	+	+*
Vue	+	+*

* Could lead to sync problems with other addons, like knobs

Getting started

First of all, you need to install Pseudo States into your project as a dev dependency.

npm install @ergosign/storybook-addon-pseudo-states-react --save-dev

Then, configure it as an addon by adding it to your addons.js file (located in the Storybook config directory).

To display the pseudo states, you have to add specific css classes to your styling, see Styling

Then, you can set the decorator locally, see Usage.

Styling

With Preset

Preset-Postcss adds postcss-loader to Storybook's custom webpack config.

You must also install postcss-pseudo-classes. Unfortunately, latest version is only tagged and not released. Please use at least tagged version 0.3.0

npm install postcss-pseudo-classes@0.3.0 --save-dev

Then add the preset preset-postcss to your configuration in main.js (located in the Storybook config directory):

main.js;

module.exports = {
  presets: ['@ergosign/storybook-addon-pseudo-states-angular/preset-postcss'],
};

Own Webpack config (but automatically generated with PostCss)

Add postcss-loader to a Storybook custom webpack config

module.exports = {
  module: {
    rules: [
      {
        test: /\.(scss|css)$/,
        use: [
          {
            loader: 'style-loader',
          },
          {
            loader: 'css-loader',
            options: {
              // ATTENTION when using css modules
              modules: {
                // !!! must not use [hash]'
                localIdentName: '[path][name]__[local]',
              },
            },
          },
          // Add loader here
          {
            loader: 'postcss-loader',
          },
          {
            loader: 'sass-loader',
          },
        ],
      },
    ],
  },
};

Add postcss-pseudo-classes.

npm install postcss-pseudo-classes --save-dev

And enable it in postcss.config.js

module.exports = {
  plugins: {
    'postcss-pseudo-classes': {
      // prefix: 'pseudoclass--',
    },
  },
};

When using a custom `prefix` parameter, use the same for postcss-pseudo-classes

module.exports = {
  plugins: {
    'postcss-pseudo-classes': {
      prefix: 'pseudoclass-example-prefix',
    },
  },
};

Manually

In addition to the standard pseudo state styling, you have to add fake classes consisting of prefix + pseudostate (\:hover, \:focus, \:active, \:yourOwnState) by yourself. Be aware that default prefix is \:. When using your own prefix, update your styling accordingly.

.element {
  //element styling

  &:hover,
  &\:hover {
    // hover styling
  }
}

With a custom prefix

custom prefix: .pseudoclass--

// in your story
parameters: {
    withPseudo: {
        selector: "element",
        prefix: "pseudoclass--"
    }
}

.element {
  //element styling

  &:hover,
  &.pseudoclass--hover {
    // hover styling
  }
}

Show/Hide Toolbar-Button

You can enable a toolbar button that toggles the Pseudo States in the Preview area.

See [Framework Support](##Framework Support) which Frameworks support this feature.

Enable the button by adding it to your main.js file (located in the Storybook config directory):

// main.js

module.exports = {
  addons: ['@ergosign/storybook-addon-pseudo-states-angular/register'],
};

Usage

WARNING: withPseudo should always the first element in your decorators array because it alters the template of the story.

General

Component Story Format (CSF, recommended)

import { withPseudo } from '@ergosign/storybook-addon-pseudo-states-react';

const section = {
  title: 'Button',
  decorators: [withPseudo],
  parameters: {
    withPseudo: { selector: 'button' },
  },
};
export default section;

export const Story = () => {
  return {
    component: ButtonComponent,
  };
};

storyOf Format

import { withPseudo } from '@ergosign/storybook-addon-pseudo-states-<framework>';

storiesOf('Button', module)
  .addDecorator(withPseudo)
  .addParameters({
    withPseudo: {
      selector: 'button', // css selector of pseudo state's host element
      pseudo: ['focus', 'hover', 'hover & focus', 'active'],
      attributes: ['disabled', 'readonly', 'error'],
    },
  })
  .add('Icon Button', () => <Button />);

There is a default configuration for StateComposition.

With React

When using CSS Modules, you must use automatically styling generation via postcss-loader (see Styling section).

StateComposition.attributes enable component's props.

import { withPseudo } from '@ergosign/storybook-addon-pseudo-states-react';

storiesOf('Button', module)
  .addDecorator(withPseudo)
  .addParameters({
    withPseudo: {
      attribtues: [], // no attributes to show --> overwrite default [DISABLE]
    },
  })
  .add('Button', () => <Button label="I'm a normal button" />)

  .addParameters({
    withPseudo: {
      stateComposition: {
        pseudo: [...PseudoStatesDefault, 'hover & focus'],
        attributes: [
          ...AttributesStatesDefault,
          'selected',
          'error',
          'isLoading',
          'isReady',
        ],
      },
    },
  })
  .add('Button', () => <Button label="I'm a normal button" />);

With Angular

At the moment, only Component Story Format is supported (tested).

import { withPseudo } from '@ergosign/storybook-addon-pseudo-states-angular';

const section = {
  component: ButtonComponent,
  title: 'Button',
  moduleMetadata: {
    declarations: [ButtonComponent],
    imports: [CommonModule],
  },
  decorators: [
    // ButtonComponent's styling has prefixed pseudo-states styling
    withPseudo({ prefix: 'pseudoclass--' }),
  ],
  parameters: {
    // <button> exists inside of angular component ButtonComponent
    withPseudo: { selector: 'button' },
  },
};
export default section;

export const Story = () => {
  return {
    component: ButtonComponent,
    moduleMetadata: {
      declarations: [ButtonComponent],
      imports: [CommonModule],
    },
    // ButtonComponent has same properties as props' keys
    props: {
      label: 'Test Label',
      anotherProperty: true,
    },
  };
};

export const StoryWithTemplate = () => {
  return {
    // always provide component!
    component: ButtonComponent,
    moduleMetadata: {
      entryComponents: [ButtonComponent], // required to support other addons, like knobs addon
      declarations: [ButtonComponent],
      imports: [CommonModule],
    },
    template: `<test-button [label]="label" [anotherProperty]="anotherProperty"></test-button>`,
    props: {
      label: 'Test Label',
      anotherProperty: true,
    },
  };
};

With HTML

storiesOf('Demo', module)
  .addDecorator(withPseudo)
  .addParameters({ withPseudo: { selector: null } })
  .add('story1', () => {
    const button = document.createElement('button');
    button.type = 'button';
    button.innerText = 'Hello World!';
    button.addEventListener('click', e => console.log(e));
    return button;
  })
  // story with selecotr on inner element
  .addParameters({ withPseudo: { selector: 'span' } })
  .add('story2', () => {
    const headline = document.createElement('h1');
    const span = document.createElement('span');
    span.innerHTML = 'Hello World';

    headline.appendChild(span);

    return headline;
  });

Parameters

export interface PseudoStatesParameters {
  disabled?: boolean;
  // query for selector to host element[s] that have to be modified
  selector?: Selector;
  // prefix for state classes that will be added to host element
  prefix?: string;
  pseudos?: PseudoStates;
  attributes?: AttributeStates;
}

export type PseudoState = PseudoStateEnum | string;
export type AttributeState = AttributeStatesEnum | string;

export type PseudoStates = Array<PseudoState>;
export type AttributeStates = Array<AttributeState>;

export const PseudoStatesDefault: PseudoStates = [FOCUS, HOVER, ACTIVE];
export const AttributesStatesDefault: AttributeStates = [DISABLED];
export const AttributesStatesInputDefault: AttributeStates = [
  DISABLED,
  READONLY,
];

Changelog

0.0.1-alpha.23 (2020-03-24)

Bug Fixes

• angular: allow moduleMetadata in story without declarations (9d95d69)