静的なHTMLのためのコンポーネント駆動開発―その導入を振り返って

バリエーションのテスト

Storybookを使ってコンポーネントを個別に開発することによって、同じコンポーネントの複数の状態やバリエーションをテストできるようになります。

次のようなPugとCSSによるMediaコンポーネントを考えてみましょう。

Media.pug:

mixin Media(params={})
  - const props = Object.assign({ image: '', reverse: false }, params)
  .Media(type=props.type, class={ '-reverse': props.reverse })&attributes(attributes)
    img.Media__image(src=props.image)
    .Media__body
      block

.Media {
  display: flex;
}

.Media__image {
  flex: 0 0 auto;
}

.Media.-invert {
  flex-direction: row-invert;
}

-invertバリアントがどのように描画されるかを検証するのに、2つの異なるストーリーを作ってもいいでしょう。

しかしより有力なソリューションは、Storybook Addon Knobsを使ってコンポーネントの属性を動的に書き換えることです。

この手法の優れた点は、複数のバリアントの組み合わせを同じストーリーでテストできることです。

以下の例ではbooleanノブを使ってreverse属性の値をトグルし、同時にselectノブでアスペクト比の異なる2つの画像を切り替えられるようにしています。

Media.stories.js:

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

import { renderer } from 'storypug'
import Media from './Media.pug'

const { html } = renderer()

const images = [
  'https://via.placeholder.com/150',
  'https://via.placeholder.com/350x150',
]

export default {
  title: 'Components/Media',
  decorators: [withKnobs],
}

export const Default = () =>
  html(
    Media,
    {
      image: select('Image', images, images[0]),
      reverse: boolean('Reverse Style', false),
    },
    '<p>Contents...</p>',
  )

このストーリーはブラウザでは以下のように見えます。

JavaScriptインタラクションの実装

Pugテンプレートに限らず、HTMLコンポーネント駆動のプロジェクトでJavaScriptを扱おうとすると、インタラクションをどこで、どのように登録するかという疑問が頭をもたげます。

「どこで」については、JavaScriptを機能コンポーネントに収めることをお勧めします。機能コンポーネントとは、Atomic Designの方法論にあるorganismの定義を真似て言うと、複数のコンポーネントの集まりで、比較的複雑な、インターフェース上で明確に区分できるセクション、と言えます。HTMLとCSSだけから成り立っているシンプルなボタンなどプリミティブな単機能のコンポーネントに対し、画像ギャラリーやフォーム、モーダルのような「複合体」コンポーネントは、JavaScriptのロジックを閉じ込めるにはうってつけです。

「どのように」については、プロジェクトの性質と要件によります。私たちは多くのプロジェクトでStimulusを使っています。ページを静的あるいは動的にサーバーサイドで生成するタイプのプロジェクトにおいて、フロントエンドのコードベースをシンプルに、整理された状態に保つように作られたフレームワークです。

Stimulusのコントローラーを機能コンポーネントにマップすれば、コンポーネントをStorybook内で個別に開発できます。

例として検索コンポーネントを作ってみましょう。

Search.pug:

//- load children components
include /components/Button/Button

mixin Search(props={})
  form.Search(
    action="/search"
    role="search"
    data-controller="search"
    data-action="search#send"
  )
    label.Search__field
      span.Search__label Keywords
      input.Search__input(type="search" name="keywords" data-target="search.keywords")
    +Button({ type: 'submit' }) Search

コントローラーは次のようになります。

Search.js:

import { Controller } from 'stimulus'

export default class SearchController extends Controller {
  static targets = ['keywords']

  send(e) {
    e.preventDefault()
    const query = this.keywordsTarget.value.trim()

    if (!query) {
      alert(`Type a keyword!`)
      return
    }
    alert(`Fetching results for: "${query}"...`)

    // fetch search results...
  }
}

コントローラーを初期化するにあたっては、Stimulusが自身の状態を管理するためのコンテナ（Applicationクラスのインスタンス）に登録しておく必要があります。通常StimulusのApplicationクラスはhtml要素に結びつけられますが、私たちのケースではコンポーネントごとに個別のコンテキストが必要です。これを解決するため、私たちはStorypugのrender関数を使っています。これによりPugコンポーネントをラッパー要素内のDOMツリーに描画することが可能になります。そしてこのラッパー要素を、検索コンポーネントだけを子コントローラーとして持つローカルの（個別の）アプリケーションを初期化するために利用するのです。

Search.stories.js:

import { renderer } from 'storypug'
import Search from './Search.pug'
import { Application } from 'stimulus'
import SearchController from './Search'

const { render } = renderer()

export default {
  title: 'Components/Search',
}

export const Default = () => {
  // render instead of returning the raw HTML
  const wrapper = render(Search)

  // initialize a local stimulus application
  const application = Application.start(wrapper.el)

  // register (initialize) the Search controller
  application.register('search', SearchController)

  // return the application wrapper element
  return wrapper.el
}

以下は実際に動いているコンポーネントのデモです。

テストプロセスの改善

コンポーネント駆動開発とStorybookによって得られるさらなる恩恵として、コードベースにユニットテストを導入しやすくなるという点があります。

一般にフロントエンドのプロジェクトではユニットテストよりもインテグレーションテストを重視するのがベストプラクティスとされています。しかし私たちの場合、スナップショットと呼ばれる手法によって、ユニットテストについても恩恵を受けられます。スナップショットはもともと、Jestフレームワークによって広められたものです。

スナップショットを使うと、Jestはまずコンポーネントによって描画されたHTMLを保存し、そしてテストを実行してコンポーネントのHTMLが保存されたものと一致するかを検出します。これにより、コンポーネントやその子孫に変更を加えたときに起こる非一貫性やエラーを追跡できます。そしてより重要なのは、コンポーネントが想定どおりに描画されているかどうかを検証できることです。

Storybookの最新バージョンでは、ストーリーをテストファイルにインポートすればそのままスナップショットテストに使えます。

Button.test.js:

import { Default, Submit } from './Button.stories'

describe('Button', () => {
  test('matches the Default snapshot', () => {
    expect(Default()).toMatchSnapshot()
  })
  test('matches the submit snapshot', () => {
    expect(Submit()).toMatchSnapshot()
  })
})

Storypugのドキュメンテーションでは、.pugテンプレートをテストファイルで使うときJestをどのように設定すればいいかを詳しく解説しています。

内部チームに向けて

実際、アジャイルの手法を開発に取り入れたとしても、様々な分野の専門性を持ったメンバー間で仕事の進捗を共有するのは難しいことがあります。

しかしもしデザイナーやプロジェクトマネジャーに対し、閲覧しやすく、いい感じにまとめられたプレビューを見せることができれば、早い段階でのフィードバックや検証がもらいやすくなります。

小さなプロジェクトなら、Storybookを静的にビルドしてウェブ上のプライベートな場所に上げ、チームメンバーとシェアしてもいいでしょう。

複数の開発者が関わるような大規模プロジェクトの場合、すべてのブランチでプッシュするごとにスタイルガイドを最新の状態にするような、継続的デプロイのシステムを構築するとよいでしょう（このようなタスクの有力候補はNetlifyです）。

バックエンド開発者もまた、これまで述べてきたコンポーネント駆動開発からの恩恵を受けられます。フロントエンドとバックエンドのテンプレート実装が異なる場所で進められているとき、バックエンド開発者にとってにとってのStorybookは、コンポーネントを閲覧できるディクショナリでもあり、最終版のリリース可能な実装を検証するためのベンチマークでもあります。

ステークホルダーに向けて

もうひとつ、コンポーネント駆動開発とStorybookを使って有用だと感じのは、クライアントやステークホルダーとのコミュニケーションをより良いものにしてくれるという点です。

ページテンプレートの開発というものは、とくにプロジェクトの初期段階では、開発者の努力や進捗がステークホルダーから見えない状態が長く続きがちです。

そこでStorybookのようなスタイルガイドをステークホルダーに公開すれば、チームがプロジェクトにしっかりコミットしていることを伝えられます。またコンポーネントの面で見ると、例えばオフキャンバスメニューのような、シンプルだと思われているUIを作るのにどのような努力が払われているかを示す成果物にもなります。

ドキュメンテーションツールとして

その上、バージョン5.2の最新機能であるDocsアドオンがあれば、Storybookを本格的なドキュメンテーションツールとして使うことができます。

StorybookはJavaScriptのストーリーのほか、MarkdownとMDXファイルをサポートしているので、開発者だけでなく非開発者も、コンポーネントのリッチなドキュメンテーションやデザインガイドライン、組み込みガイドを書くことが可能です。

ReactコンポーネントをサポートするMarkdown拡張であるMDXを使えば、プロジェクトのタイポグラフィやカラーパレットをグラフィカルで直観的な形式で展開するビルトインコンポーネントも利用できます（くわしくはこちらの記事をご覧ください）。