bklit-ship

Bklit Ship Skill

このスキルは、bklit-ui モノレポのコントリビューターが、Studioで検証済みのチャートまたはコンポーネントを本番環境に移行するためのものです。UI パッケージで公開し、ドキュメントを整備して、ユーザーが利用できる状態にします。

このスキルを使うタイミング

• bklit/bklit-ui をクローンし、Studio（/studio）で検証済みの動作するプロトタイプがあり、それをリリースしたい場合。
• 「スキャフォールディング」から「正式な実装」に移る準備ができている場合。API と主要なプロパティ／バリアントは、プロトタイピングの段階で決定済みです。

---

計画：プロトタイプ → 本番環境

以下の手順を順に進めてください。各手順にはリポジトリ内の具体的な場所が記載されているので、チェックリストとして活用してください。

1. UI パッケージに移動してエクスポートする

• チャート／コンポーネントのソースを packages/ui/ に移動するか、そこで仕上げます（例：チャートの場合は packages/ui/src/charts/）。bklit-studioの手順に従っていれば、プロトタイプはすでにここにあるはずです。apps/web/components/playground/ に残っているコピーがあれば削除してください。
• 新しいチャート／コンポーネントをパッケージの公開 API からエクスポートします。
  • チャートの場合：packages/ui/src/charts/index.ts にエクスポートを追加します。
  • パッケージで特定のエントリーポイントに package.json の exports を使用している場合は、新しいコンポーネントを @bklitui/ui/charts（または適切なパス）としてインポートできるよう、該当するエントリーを追加または更新します。
• apps/web/components/playground/ にアプリ専用のチャートのコピーを追加しないでください（非推奨）。Studio のプレビューは packages/studio に配置します。

2. ドキュメントと使用例（apps/web）

ドキュメントは apps/web/ 以下にあります。次のすべてを行ってください。

• 既存のチャートを拡張してリリースする場合（新しいプロパティ、サブコンポーネント、動作など）、既存のコンポーネントドキュメントを更新します。

  • 該当する親ドキュメントのテーブルに新しいプロパティを追加します（例：line-chart.mdx の Grid highlightRowValues、ChartTooltip indicatorColor）。
  • 必要に応じて、関連するユーティリティのドキュメントも更新します（例：content/docs/utility/grid.mdx、tooltip.mdx）。
  • 主要なドキュメントプレビューは変更しないでください。既存ページの標準プレビューを新しいバリアントに差し替えないでください。
  • 機能の内容に応じて、専用のドキュメントページへのリンクを含む短いセクションを追加します（例：損益 → profit-loss-line.mdx）。

• チャートの使用例（/charts/[slug] のライブデモ）

  • 使用例を対応するギャラリールートに追加します（例：損益のバリアントは、新しいドキュメントプレビューだけでなく、/charts/line-chart に追加します）。
  • 新しい種類のチャートの場合は、apps/web/components/charts/chart-slugs.ts にそのスラッグを追加し、apps/web/components/charts/chart-examples.tsx に使用例を登録します（必要に応じて CHART_NAV_ITEMS／ファクトリーレジストリを使用します）。
  • スキャフォールディングの段階で検証したプロパティのバリアントを再利用するか、同等のものを用意します。

• 専用のドキュメントページ（新しいコンポーザブルまたはチャートの種類をリリースする場合）

  • 既存のコンポーネントドキュメントに合わせて、フロントマター、<ComponentPreview>、インストール方法、使用方法、プロパティを含む apps/web/content/docs/components/<name>.mdx を追加します。
  • apps/web/content/docs/components/meta.json にスラッグを追加します。これにより、デスクトップのサイドバーとモバイルメニューが生成されます。apps/web/components/docs/site-header.tsx はドキュメントページツリー（docsTree）からモバイルナビゲーションを生成するため、そこで手動管理のリストを編集する必要はありません。
  • 「New」バッジは任意です。ドキュメントとギャラリーの URL を apps/web/lib/nav-badges.ts に追加します（サイドバー、モバイルメニュー、サイトナビゲーションはいずれもここを参照します）。
  • サイト上部のリンク（Docs、Components、Recipes など）は apps/web/lib/site-nav-links.ts にあります。チャートページはここには追加しません。

3. Studio

• 機能が既存の種類のバリエーションであれば既存の Studio チャートを更新し、独立した種類であれば新しい Studio チャートを追加します。
• 調整可能なすべての props を Studio に接続します（プロトタイプ作成時に対応済みの場合を除く）。
  • packages/studio/src/lib/studio-parsers.ts — URL の状態キーとデフォルト値
  • packages/studio/src/lib/registry-control-groups.ts — コントロールグループ
  • packages/studio/src/lib/registry.tsx — プレビューのレンダリングと generateCode
  • packages/studio/src/lib/studio-components.ts — レイヤーツリー
  • チャートの種類を切り替えるときのチャート種類ごとのデフォルト値（packages/studio/src/components/studio-state-provider.tsx）
• 新しい Studio スラッグ を追加する場合は、次の対応も必要です（TypeScript が検出するのは Record<ChartSlug, …> の項目で、それ以外は検出されません）。
  • packages/studio/src/chart-slugs.ts — スラッグを追加
  • packages/studio/src/lib/types.ts — chartLabels の項目（表示名。satisfies Record<ChartSlug, string>）
  • packages/studio/src/components/chart-type-icons.tsx — CHART_TYPE_ICONS の項目（Record<ChartSlug, IconName>）
  • packages/studio/src/components/catalog/catalog-chart-preview-grid.tsx — カタログのタイルにカスタムサイズや状態のオーバーライドが必要な場合は、CATALOG_CHART_LAYOUT の項目を追加します（y 軸がある場合は STUDIO_Y_AXIS_CHART_PREFIX も追加します）。
  • packages/studio/src/lib/studio-url-key-orders.ts — 新しい URL 状態キーをすべて STUDIO_STATE_KEY_ORDER の末尾に追加します（固定されており、末尾への追加のみ可能です。挿入や並べ替えはしないでください。共有 URL が壊れます。studio-url-codec.test.ts でチェックされます）。
  • packages/studio/src/lib/studio-visibility-sync.ts — チャートに凡例またはブラシレイヤーがある場合は、legendComponentIdForChart / brushComponentIdForChart にケースを追加します（ない場合のデフォルトは null です）。

4. shadcn レジストリを再構築する

• リポジトリのルートから pnpm registry:build を実行します。
• これにより、packages/ui の内容で apps/web/public/r/ が更新されます。shadcn 経由でインストール可能にするコンポーネントは、packages/ui/registry.json に登録されていることを確認してください。

5. リント、フォーマット、テスト、ビルドを実行する

すべて問題がなくなるまで、リポジトリのルートから実行します。

pnpm lint
pnpm format
pnpm --filter @bklitui/ui test   # when package logic changed
pnpm build
pnpm registry:build              # if not already run in step 4

すべてのエラーを修正し、コミット時にフックが通るまで繰り返します。

6. コミット、プッシュして、PR を作成する

• 短く明確なメッセージでコミットします（例：feat(charts): add ProfitLossLine component）。
• ブランチをプッシュします。
• 出荷チェックリストに記入してPR を作成します（以下を参照）。

---

PR チェックリスト

• チャート／コンポーネントを packages/ui に移動し、エクスポート済み
• 既存のドキュメントを更新し、新しい props／機能を記載（標準プレビューに変更なし）
• ギャラリーの例を適切な /charts/** ルートに追加
• 専用のドキュメントページ＋サイドバー＋モバイルナビ（新しいコンポーザブル／チャートの種類の場合）
• Studio のチャートを更新または追加し、すべての props をコントロールグループに追加（新しいスラッグの場合：ラベル、アイコン、カタログレイアウト、URL キーの順序を末尾に追加）
• レジストリを再構築済み（pnpm registry:build）
• pnpm lint、テスト（該当する場合）、pnpm build がすべて成功

ファイル参照（クイック検索）

手順	場所
チャートのエクスポート	packages/ui/src/charts/index.ts
チャートのスラッグ	apps/web/components/charts/chart-slugs.ts
チャートの例（ナビゲーション＋レジストリ）	apps/web/components/charts/chart-examples.tsx
コンポーネントのドキュメント	apps/web/content/docs/components/<name>.mdx
ユーティリティのドキュメント（Grid、Tooltip、…）	apps/web/content/docs/utility/*.mdx
サイドバー＋モバイルナビゲーション	apps/web/content/docs/components/meta.json → pages（site-header.tsx のモバイルメニューは、ドキュメントのページツリーから生成されます）
「新規」バッジ	apps/web/lib/nav-badges.ts
Studio レジストリ	packages/studio/src/lib/registry.tsx
Studio コンポーネントツリー	packages/studio/src/lib/studio-components.ts
Studio コントロール	packages/studio/src/lib/registry-control-groups.ts
Studio URL の状態	packages/studio/src/lib/studio-parsers.ts ＋ packages/studio/src/lib/studio-url-key-orders.ts にキーを追加
Studio のスラッグ一覧／ラベル／アイコン	packages/studio/src/chart-slugs.ts、packages/studio/src/lib/types.ts（chartLabels）、packages/studio/src/components/chart-type-icons.tsx
Studio カタログタイル	packages/studio/src/components/catalog/catalog-chart-preview-grid.tsx
Studio レイヤーの表示状態の同期	packages/studio/src/lib/studio-visibility-sync.ts
レジストリ（ソース）	packages/ui/registry.json、ビルド出力：apps/web/public/r/
レジストリのビルド	ルートから実行：pnpm registry:build