StorybookのDocsBlockを触ってみる

Storybookは、Canvasタブの以外には「Docs」というタブが設けられています

Docsには、以下のような文書を書くことができます

今回は、Docsの書き方について紹介しようと思います

Docsの種類

Storybookの公式ページに行き、左パネルの「Write docs」の下の「Docs Blocks」を注目します
「Docs Blocks」の下には8つのページがあります、その8つはDocsBlockの全部の種類です

さらに、Docsにの書き方は2種類存在しています

一つ目はMDX、ArgsTableを例えてみると
ドキュメントは「Working with MDX」のセクションです

もう一つ目はDocsPageです、ドキュメントは「Working with the DocsPage
」のセクションです

MDXは、DocsPageより豊富で、多様なDocsを書くことができます

今回はDocsPageで書きます

コンポーネントの作成

まずはstorybookにインストール、適当にコンポーネントを作成しようと思います
WebComponentで作成します

top-nav.js

class TopNav extends HTMLElement {
	constructor() {
		super();
		this.title = this.dataset.title || 'タイトル';

		this.outerHTML = `
		<header class="top-nav">
			<div class="top-nav-start"></div>
			<div class="top-nav-center">
				<h1>${this.title}</h1>
			</div>
			<div class="top-nav-end"></div>
		</header>
		`;
	}
}

customElements.define('top-nav', TopNav);

次は、storiesを作成します
Canvasだけ作成しておきます

top-nav.stories.js

import './top-nav';

export default {
	title: 'Layout/TopNav',
	args: {
		title: 'タイトル',
	},
};

export const Default = (arg) => {
	const template = document.createElement('template');
	template.innerHTML = `<top-nav data-title=${arg.title}></top-nav>`;
	return template.content.firstChild;
};

これでCanvasページは完成しましたが

Docsページはほぼ空の状態です

Docsを追加

ここからDocsBlockを追加しようと思います
まずはdescription

export defaultの部分に、parameters.docs.description.componentを追加しようと思います
フォーマットはMarkdownです

top-nav.stories.js

export default {
	title: 'Layout/TopNav',
	args: {
		title: 'タイトル',
	},
+	parameters: {
+		docs: {
+			description: {
+				component: 'ヘッダーのコンポーネント、タイトル名の指定ができます',
+			},
+		},
+	},
};

次はSample Codeを入れようと思います
parameters.docs.source.codeを入れます

top-nav.stories.js

export default {
	title: 'Layout/TopNav',
	args: {
		title: 'タイトル',
	},
	parameters: {
		docs: {
			description: {
				component: 'ヘッダーのコンポーネント、タイトル名の指定ができます',
			},
+			source: {
+				code: `<top-nav data-title="タイトル"></top-nav>`,
+			},
		},
	},
};

さらに、parameters.docs.source.stateを`openに指定して、常にコードが見れるように設定できます

次はArgsTableです
このコンポーネントは一つのArgs：titleのみ存在しているので
まずはargTypes.title.descriptionを指定します

top-nav.stories.js

export default {
	title: 'Layout/TopNav',
	args: {
		title: 'タイトル',
	},
+	argTypes: {
+		title: {
+			description: 'ページのタイトル',
+		},
+	},
	...略...
};

次はargTypes.title.table.defaultValue.summaryを指定します

top-nav.stories.js

export default {
	title: 'Layout/TopNav',
	args: {
		title: 'タイトル',
	},
	argTypes: {
		title: {
			description: 'ページのタイトル',
+			table: {
+				defaultValue: {
+					summary: 'タイトル',
+				},
+			},
		},
	},
	...略...
};

argTypes.title.table.type.summaryを指定します

top-nav.stories.js

export default {
	title: 'Layout/TopNav',
	args: {
		title: 'タイトル',
	},
	argTypes: {
		title: {
			description: 'ページのタイトル',
			table: {
				defaultValue: {
					summary: 'タイトル',
				},
+				type: {
+					summary: 'string',
+				},
			},
		},
	},
	...略...
};

これで全てのDocsBlockを紹介できました

MDXの記法ならもっと多いDocsが利用できますが
DocsBlockだけでこれが極限です