Documenting Components with Storybook in Angular

Storybook is one of the successful libraries for documenting UI components in most of the frameworks, Though it started as a React library, Storybook supports most of the frameworks which follows the Component Driven Architecture.

Component Driven Architecture or Component Driven Development is nothing but building your application screens from ground up. Building components that can be plugged into any containers just by sending the required data to it. This helps in developing the components in isolation and maximum re-usability. Component Driven Development also helps in identifying the bugs faster, As the component will be pure and will respond the same way when the same data is passed, it makes a clear cut that the data passed to the component has to be wrong when the component breaks in one part of the screen.

Why do we have to document the component we develop?

Of course, you know how the component behaves, what are the input arguments it accepts, and what are the events it emits.
If the project has more screens and multiple developers are working on it, then identifying out which component to use in which case would be a challenge.
Documenting the components will avoid unnecessary interactions and conversations. If the person developed the components is not available, then it makes even worse to look into the code and know the reasons behind individual arguments.

Why Storybook?

Many libraries do component documentation, in the Angular community, they are less and most of them don’t support the basic concept of interacting with the component. Meaning, we cannot change the arguments and check how it behaves in the documentation. That’s where the Storybook stands tall. Storybook has many add-ons developed and maintained by the open-source community which allows users to not only document it, also test and make sure the components are bulletproof.

Let’s proceed with integrating Storybook into the application and see how to solve some of the challenges which official documents have missed out.

You can add Storybook via two different ways, I strongly recommend running one command and letting storybook do the setup for us,

npx -p @storybook/cli sb init --type angular

For more info on the above command, visit Storybook for Angular

Once the setup is done, we can start the development server by running
yarn storybook

Let us create a simple button component and illustrate the features of Storybook

button.component.html

<button 
    class="btn btn-primary btn-circle"
    (click)="onclick.emit($event)"
>
    <span>{{title}}</span>
</button>

<button

class="btn btn-primary btn-circle"

(click)="onclick.emit($event)"

<span>{{title}}</span>

</button>

button.component.ts

import { Component, Input, Output, EventEmitter } from '@angular/core';

@Component({
  selector: 'btn-primary',
  templateUrl: './btn-primary.component.html',
  styleUrls: ['./btn-primary.component.scss']
})
export class BtnPrimaryComponent {

  @Input() title: string = ''

  @Output() onclick = new EventEmitter<any>()

  constructor() { }

}

import { Component, Input, Output, EventEmitter } from '@angular/core';

@Component({

selector: 'btn-primary',

templateUrl: './btn-primary.component.html',

styleUrls: ['./btn-primary.component.scss']

})

export class BtnPrimaryComponent {

@Input() title: string = ''

@Output() onclick = new EventEmitter<any>()

constructor() { }

}

Simple, Isn’t it. Well, this is enough to understand most of the features. The way I write Stories could look a little different than you see in Angular documents and StackOverflow, but this is a way we can achieve most out of the storybook, and going forward you will see the same syntax as an official way to write stories.

btn-primary.stories.ts

import { moduleMetadata } from '@storybook/angular';

import { action } from '@storybook/addon-actions';
import { centered } from '@storybook/addon-centered/angular';
import { withKnobs, text } from '@storybook/addon-knobs';

import { BtnPrimaryComponent } from '../app/pComponents/btn-primary/btn-primary.component';
import { NgTranscribeModule } from 'ng-transcribe';

import * as markdown from './notes/primary-button.md'


export default {
  title: 'Buttons',
  decorators: [
    moduleMetadata({
      declarations: [BtnPrimaryComponent],
      imports: [NgTranscribeModule]
    }),
    withKnobs,
    centered
  ]
};

const actions = {
  btnClick : action('Button clicked')
}

export const primaryButton = () =>
  {
    const title = text('text', 'log in')
    return {
      component: BtnPrimaryComponent,
      template: `<btn-primary
                  (onclick)="onclick()"
                  [title]="title"
                  >
                </btn-primary>`,
      props: {
        title,
        onclick: actions.btnClick,
      }
    }
  };
primaryButton.story = {
    name : 'Primary Button',
    parameters: { notes:  markdown },
};

import { moduleMetadata } from '@storybook/angular';

import { action } from '@storybook/addon-actions';

import { centered } from '@storybook/addon-centered/angular';

import { withKnobs, text } from '@storybook/addon-knobs';

import { BtnPrimaryComponent } from '../app/pComponents/btn-primary/btn-primary.component';

import { NgTranscribeModule } from 'ng-transcribe';

import * as markdown from './notes/primary-button.md'

export default {

title: 'Buttons',

decorators: [

moduleMetadata({

declarations: [BtnPrimaryComponent],

imports: [NgTranscribeModule]

}),

withKnobs,

centered

]

};

const actions = {

btnClick : action('Button clicked')

}

export const primaryButton = () =>

{

const title = text('text', 'log in')

return {

component: BtnPrimaryComponent,

template: `<btn-primary

(onclick)="onclick()"

[title]="title"

</btn-primary>`,

props: {

title,

onclick: actions.btnClick,

}

};

primaryButton.story = {

name : 'Primary Button',

parameters: { notes: markdown },

};

Let us read line by line and understand the importance of them,
First-line imports ModuleMetadata from Storybook Angular library which is used to define the module for this component, If you see line 16 from the above example, you identify we are defining a module as part of decorations. This is one of the best ways to write stories that will solve most of our problems of importing external modules specific to one story so that we don’t run into errors.

Lines 3,4, and 5 are importing storybook add-ons which we want to use in this story. For more details on how to install add-ons visit Storybook add-ons

actions add-on is used to simulate user actions, this helps to check if the EventEmitters are working fine. using them is as simple as shown in the above code. This adds a new tab in your storybook UI in the add-ons section. if you’ve followed this document then you must get a log statement in the actions tab when you click on the button.

Storybook by default places all the components at the top-left position. This is suitable for container components, not for simple presentational components like button or input. We would want them to be placed in the middle so that we have a clear view of the component. Hence the reason why we have added ‘centered’ add-on in our story and mentioned it as part of the decorator.

Knobs are the best way to interact with the component’s inputs, they provide methods to all the possible ways to pass arguments into the component and we can change it in the Knobs tab in our add-ons section in Storybook UI. In our example we are specifying that our component uses knobs by ‘withKnobs’ in decorators. ‘text’ method is used to create an argument of type String. The first parameter to text method is the label which will be displayed and the second is the value.

‘NgTranscribeModule’ is an I18n module, I have added in this example to showcase how we can add external modules which are imported inside the module file in our component code.

Lastly, we can write documents that will be displayed in the notes section. It can be a simple string or a .md file(we need to install an add-on) like below.

notes/primary-button.md

#Primary Button

This is a variation of buttons used in the application

    
##Input
   __title__: string = ''

#### title is used for the button text

##Events
   __onclick__ 

#### This event gets triggered or called when the user clicks on the button

#Primary Button

This is a variation of buttons used in the application

##Input

__title__: string = ''

#### title is used for the button text

##Events

__onclick__

#### This event gets triggered or called when the user clicks on the button

Add-ons used in the above example are :- ‘@storybook/addon-actions’, ‘@storybook/addon-links’, ‘@storybook/addon-notes’, ‘@storybook/addon-knobs’

I additionally recommend using ‘@storybook/addon-viewport’, ‘@storybook/addon-docs’ which helps in a few ways.

I would like to cover one case which storybook document misses which made my life difficult for a few days,

Let us assume we have an input component which will be used inside Reactive form and requires a Group sent from the parent component, the below example code shows how we can solve such problems, I am skipping the explanation to keep the post short. comment below should you have any questions.

import { moduleMetadata } from '@storybook/angular';
import { centered } from '@storybook/addon-centered/angular';
import { withKnobs, text, boolean } from '@storybook/addon-knobs';

import { FormGroup, FormControl } from "@angular/forms";
import {FormsModule, ReactiveFormsModule} from "@angular/forms";
import { FloatingLabelComponent } from 'src/app/pComponents/floating-label/floating-label.component';
import { NgTranscribeModule } from 'ng-transcribe';

import * as markdown from './notes/floating-label.md'

export default {
  title: 'Inputs',
  decorators: [
    moduleMetadata({
      declarations: [FloatingLabelComponent],
      imports: [FormsModule, ReactiveFormsModule, NgTranscribeModule],
    }),
    centered,
    withKnobs
  ]
};


export const FloatingLabel = () => {
  let formGroup = new FormGroup({
    username : new FormControl()
  })
  const label = text('label', 'username')
  const type = text('type', 'text')
  const requiredMsg = text('requiredMsg', 'LOGIN.email_req')
  const isRequired = boolean('Required?', true)
  
  return {
      component: FloatingLabelComponent,
      template: `<floating-label
                  [group]="group"
                  [label]="label"
                  [type]="type"
                  [controlName]="controlName"
                  [hasErrors]="true"
                  [isRequired]="isRequired"
                  [requiredMsg]="requiredMsg"
                  ></floating-label>`,
      props: {
        group:formGroup,
        label,
        type,
        requiredMsg,
        isRequired,
        controlName: 'username'
      }
  }
}

FloatingLabel.story = {
  parameters: {
      notes: markdown
  }
}

import { moduleMetadata } from '@storybook/angular';

import { centered } from '@storybook/addon-centered/angular';

import { withKnobs, text, boolean } from '@storybook/addon-knobs';

import { FormGroup, FormControl } from "@angular/forms";

import {FormsModule, ReactiveFormsModule} from "@angular/forms";

import { FloatingLabelComponent } from 'src/app/pComponents/floating-label/floating-label.component';

import { NgTranscribeModule } from 'ng-transcribe';

import * as markdown from './notes/floating-label.md'

export default {

title: 'Inputs',

decorators: [

moduleMetadata({

declarations: [FloatingLabelComponent],

imports: [FormsModule, ReactiveFormsModule, NgTranscribeModule],

}),

centered,

withKnobs

]

};

export const FloatingLabel = () => {

let formGroup = new FormGroup({

username : new FormControl()

})

const label = text('label', 'username')

const type = text('type', 'text')

const requiredMsg = text('requiredMsg', 'LOGIN.email_req')

const isRequired = boolean('Required?', true)

return {

component: FloatingLabelComponent,

template: `<floating-label

[group]="group"

[label]="label"

[type]="type"

[controlName]="controlName"

[hasErrors]="true"

[isRequired]="isRequired"

[requiredMsg]="requiredMsg"

></floating-label>`,

props: {

group:formGroup,

label,

type,

requiredMsg,

isRequired,

controlName: 'username'

}

FloatingLabel.story = {

parameters: {

notes: markdown

}

Happy Coding……!

Tagged as: angular, JavaScript, storybook

Related Posts