Merge pull request #426 from openameba/docs/improve-spindle-hooks-docs

docs(spindle-hooks): add some docs
openameba · Jun 28, 2022 · 7e8cee1 · 7e8cee1
2 parents 01efb30 + 52fbb16
commit 7e8cee1
Show file tree

Hide file tree

Showing 3 changed files with 142 additions and 10 deletions.
diff --git a/packages/spindle-hooks/CONTRIBUTING.md b/packages/spindle-hooks/CONTRIBUTING.md
@@ -0,0 +1,18 @@
+# Contributing to Spindle UI
+
+Spindle は、Ameba で利用するデザインシステムです。このリポジトリは、デザインシステムで定義された内容を実際に利用しやすいように実装に落とし込んだものです。
+
+Ameba として提供される成果物は、それらに則って開発されることを推奨しています。そのため、機能の要望や修正の Pull Request は Ameba に在籍するメンバーからのみとしています(ごめんなさい 🙇)。
+
+ただし、リンク先のミス、誤字・脱字などの Pull Request、Issue 提起は大歓迎です。わかりづらい点や疑問に思う箇所がありましたら、お気軽にお知らせください！
+
+## 新規 Hooks の作り方
+
+新規 Hooks を作る際には大まかに以下のフローを辿ります。
+
+1. Hooks の命名・利用方法などのドキュメント化。通常これは Slack や GitHub Discussions などをきっかけに作業が開始され、まず Figma にルールがまとまります。
+2. Design Doc の作成。Spindle では Hooks ごとに Design Doc を作成し、該当 Hooks に関わる事柄を整理します。Hooks 名・概要・使用するデザイントークン・アクセシビリティ対応項目などを記載します。Design Doc の雛形は Notion にありますので確認してみてください。
+3. Design Doc のレビュー。ある程度 Design Doc ができあがったら Spindle チームや Web チームでレビューをします。この段階での Design Doc はレビュー用途で使用するので完璧に仕上げる必要はありません！
+4. Hooks 作成。実際に Hooks を実装します。Storybook やテストの作成も忘れずお願いします！また、コンポーネント設計に困った場合には、すでに作成されているコンポーネントを見たり、[Spindle Hooks の Design Doc](/packages/spindle-hooks/docs/design-doc.md)を見てみてください。
+5. コンポーネント Stability の決定。Spindle Hooks ではコンポーネントごとに Stability を決め、どうゆう利用が想定されているか明記しています。[定められた Stability](/packages/spindle-hooks#Hooks%20%E4%B8%80%E8%A6%A7)の中から選択肢、Storybook の冒頭に記載します。
+6. Pull Request の作成。ここまでできたら後は GitHub 上でやりとりし、リリースまで進めます。Pull Request やリリースに関しては[Contributing to Spindle](/CONTRIBUTING.md)を参照してください。
diff --git a/packages/spindle-hooks/README.md b/packages/spindle-hooks/README.md
@@ -8,9 +8,9 @@ Spindle (Ameba Design System) Hooks
 
 > Spindle Hooks は試験開発中のため、大幅に変更される可能性があります。安定版リリースまでの間はバージョン番号は 0 となり、バージョンに関わらず breaking change が行われることがありますので、利用時には注意してください。変更内容は、[CHANGELOG](CHANGELOG.md)に記載されています。
 
-![MIT license](https://img.shields.io/npm/l/@openameba/spindle-ui) ![npm](https://img.shields.io/npm/v/@openameba/spindle-ui)
+![MIT licence](https://img.shields.io/npm/l/@openameba/spindle-hooks) ![npm](https://img.shields.io/npm/v/@openameba/spindle-hooks)
 
-Spindle Hooks は、Ameba のデザインシステム「Spindle」で定義されたコンポーネントを配布するライブラリです。様々なタイプのプロジェクトに導入できるように設計されています。
+Spindle Hooks は、Ameba のデザインシステム「Spindle」で定義されたコンポーネントの機能部分にフォーカスし、再利用可能な React Hooks を提供するライブラリです。様々なタイプのプロジェクトに導入できるように設計されています。
 
 ## インストール
 
@@ -24,29 +24,53 @@ yarn add @openameba/spindle-hooks
 
 ## 利用方法
 
-TODO
+Spindle Hooks は以下のように利用できます。
+
+```js
+import { render } from 'react-dom';
+import ReactDOM from 'react-dom';
+import { useTimeDistance } from '@openameba/spindle-hooks';
+
+function App() {
+  const publishedAt = '2022-03-11T01:15:51.237Z';
+  const [dateString] = useTimeDistance(publishedAt);
+  return <time datetime={publishedAt}>{dateString}</time>;
+}
+
+ReactDOM.render(<App />, document.querySelector('#app'));
+```
+
+Spindle Hooks は Spindle UI と同様に module 版の配信もしています。利用する際には、[導入ガイド](https://github.com/openameba/spindle/pull/175)を参考にしてください(リンク先は spindle-ui なので spindle-hooks に置き換えてください)。
 
 ## Hooks 一覧
 
-TODO
+利用可能な React Hooks は、[Storybook](https://ameba-spindle-hooks.web.app/)で公開されています。各コンポーネントの開発状況は[Stoybook Doc](https://ameba-spindle-hooks.web.app/?path=/docs/usecarousel--normal)の Stability Budge で以下のように表されています。
 
 - ![stability-stable](https://img.shields.io/badge/stability-stable-green.svg) 想定された機能が実装、テストされており本番環境で利用できます
 - ![stability-unstable](https://img.shields.io/badge/stability-unstable-yellow.svg) 足りていない機能や不安定な動作があり、まだ完全ではないですが、本番環境で利用できます
 - ![stability-wip](https://img.shields.io/badge/stability-work_in_progress-lightgrey.svg) 開発中のため、本番環境での利用はしない方がよいでしょう
 - ![stability-experimental](https://img.shields.io/badge/stability-experimental-orange.svg) 実験的な機能で大きな変更や削除される可能性があります
 - ![stability-deprecated](https://img.shields.io/badge/stability-deprecated-red.svg) 廃止される予定のため、できるだけはやく利用を停止してください
 
-## サンプルアプリケーション
-
-TODO
-
 ## ブラウザサポート
 
 Spindle Hooks は Firefox、Google Chrome、Microsoft Edge、Safari の最新版と Internet Explorer 11 で動作確認しています。
 
 ## 開発方法
 
-TODO
+```
+yarn install
+yarn dev # storybookが起動します
+```
+
+新規 Hooks を追加する際には利用方法がイメージしやすいように Storybook も追加します。
+必要に応じてユニットテストも追加します。
+
+ユニットテストは以下のように実行します。
+
+```sh
+yarn test:interaction
+```
 
 ## ライセンス
 

diff --git a/packages/spindle-hooks/docs/design-doc.md b/packages/spindle-hooks/docs/design-doc.md
@@ -1 +1,91 @@
-追記します。
+## 前提 / Context
+
+Spindle UI では UI コンポーネントのみを公開していますが、実際の機能は同じで見た目を変えたいというユースケースもあります。
+
+例えばカルーセルは spindle-ui で[HeroCarousel](https://ameba-spindle.web.app/?path=/story/herocarousel--normal)として提供されていますが、UI が固定されており要件によって自由に UI を変更することは難しいです。
+
+そのため、カルーセルであればスライドのアニメーションや再生・停止といった機能のみを提供し UI については使用側で自由に決められるようにしたいです。
+
+## 目指すこと / Goals
+
+汎用的で必要最低限の機能を実装し、サービス間で共通のロジックを使いまわせるようにします。
+
+## 目指さないこと / Non-goals
+
+一部のケースでしか使用できないような機能を追加すること。
+
+## 概要 / Overview
+
+Ameba の開発での利用実績を踏まえ、以下の点を考慮してライブラリを提供します。
+
+- **React Hooks の提供**: Ameba で最も利用されている UI ライブラリの React で作られたミニマムな Hooks を提供します
+- **UI コンポーネントカタログ中心の開発**: 作られたコンポーネントはすぐにテストされ、表示を確認します
+- **管理されたファイルサイズ**: 共通処理が集まるため、大きくなりがちなライブラリのファイルサイズが規定を超さないようにします
+
+## どのようにやっていくか / Approach, Detailed design
+
+### React Hooks の提供
+
+各アプリケーション間で共通で利用したいロジックを React Hooks として提供します。ただし、UI に依存したり命令的に DOM を処理することで副作用を含んだりしないように注意します。
+
+React Hooks は以下のように利用します。
+
+```js
+import { useTimeDistance } from '@openameba/spindle-hooks';
+
+function WakuWakuTime() {
+  const publishedAt = '2022-02-22T22:22:22.222Z';
+  const [dateString] = useTimeDistance(publishedAt);
+  return <time datetime={publishedAt}>{dateString}</time>;
+}
+```
+
+#### 他の手段
+
+より多くのプロジェクトで利用するために、Vue.js や Web Components で作成する必要があるかもしれませんが、2022 年 6 月現在では最も利用されている React で作成しています。
+
+React を使用せずに命令的に JavaScript で DOM を操作する方法もあります。この方法であればライブラリに依存せずにロジックを共通化できる一方、メンテナンスコストがかかったり、使いやすいインターフェイスを実現するのが難しかったりします。
+
+## UI コンポーネントカタログ中心の開発
+
+Spindle Hooks は、様々なプロジェクトで利用される可能性があるため、多くの人にとって簡単に確認できるドキュメントが必要です。また、Spindle が目指している「Ameba らしさ」が満たされているかチェックできる仕組みも求められます。
+
+Spindle Hooks は開発中、公開後どちらも Storybook で作られたカタログを中心に確認されます。そこでは、見た目、ソースコードの確認やアクセシビリティ、パフォーマンス、などがテストされます。
+
+また Spindle Hooks は多くのロジックを含むため React Testing Library を用いたユニットテストを書き、誰もがメンテナンスしやすく、使いやすい状態を目指します。
+
+## 管理されたファイルサイズ
+
+ライブラリは、共通処理が集約されたり、様々なバリエーションの実装が求められたりするため、ファイルサイズが増えがちです。それらを検知するために、ファイルサイズを機械的にチェックしています。
+
+各 Hooks が指定されたサイズ以上にならないように管理されています。
+
+```JSON
+// bundlesize.config.json
+{
+  "files": [
+    {
+      "path": "./dist/**/*.mjs",
+      "maxSize": "1.5 kB"
+    }
+  ]
+}
+```
+
+## 想定される問題 / Drawback, Risk
+
+UI ライブラリを運営していくうえで、以下の問題が想定されます。これらを回避するために、できるだけ短期間に小さく運営を始めるとよいでしょう。
+
+- 運用が大変で適切に更新されない
+- 要望が増えすぎて対応しきれない
+- 技術要素の利用条件が変化し、作り直さなければならない
+
+## 関連リンク / Related link
+
+- [React](https://reactjs.org/)
+- [Vue.js](https://vuejs.org/)
+- [Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components)
+- [postcss/postcss-import](https://github.com/postcss/postcss-import)
+- [Storybook](https://storybook.js.org/)
+- [React Testing Library](https://testing-library.com/docs/react-testing-library/intro/)
+- [siddharthkp/bundlesize](https://github.com/siddharthkp/bundlesize)