component-canvas

コンポーネントキャンバス

プロジェクトに既存のコンポーネントが実際にどのように動作するかを表示するキャンバスを構築します。キャンバスはコンポーネントをラップしますが、コンポーネント自体は変更しません。

基本ルール

• キャンバスを動作させるために、コンポーネントのソース、エクスポート、スタイル、フック、動作を変更しないでください。コンポーネントからキャンバスのコードをインポートしたり、それに依存させたりしてはいけません。
• ライブラリ、ブラウザー API、レンダリングされたコンポーネントの DOM、ポータルのルートを変更しないでください。
• ユーザーが指定したコンポーネントだけを表示してください。コンポーネントの追加、依存関係のインストール、コンポーネントのデザイン変更、キャンバスの公開には、事前に許可が必要です。
• 既存のアクセス制御を維持してください。
• 無関係な作業には手を加えないでください。以前のキャンバス統合を削除する場合は、コンポーネントに対する変更のみを元に戻してください。
• コマンド、ブラウザーアクセス、依存関係、編集に関する制限に従ってください。

構築前に

リポジトリの規約、ルート、コンポーネントの公開 API、デザイントークン、テスト設定を確認してください。既存のフレームワークとライブラリを使用してください。

回答によって構築内容が変わる場合、または共有コードに影響する場合に限り、ユーザーに質問してください。たとえば、対象とするコンポーネント、新しい依存関係を許容するか、稼働中のサービスをプレビューしてよいかなどです。それ以外は妥当なデフォルトを選び、レポートでその内容を明示して作業を進めてください。

構築の順序

1. 1つのグループと1つのコンポーネントを含む最小限のキャンバス用ルートまたはエントリーポイントを追加します。動作を確認してください。
2. サンプルデータを使って、残りのグループを追加します。
3. バリエーションの比較を追加し、その後、高度なジェスチャーと永続化を機能ごとに追加します。

キャンバスのコードは1か所にまとめてください。ファイルを移動する際は、インポートとパッケージのエクスポートを確認してください。プロジェクトの言語、検証、テストの規約に従ってください。プロジェクトに存在しないアーキテクチャ層やディレクトリ名を追加しないでください。

レイアウトとカメラのロジックは、サンプルデータやコンポーネントのソースから分離してください。

レイアウト

• ビューポート全体を無地の背景で塗りつぶします。
• プロジェクトがすでにライトテーマとダークテーマに対応している場合は、既存のテーマ API を使って、アクセシブルな切り替え機能を追加してください。選択したテーマはキャンバスとネイティブのポータルに適用します。テーマに対応していない場合は、切り替え機能を追加しないでください。テーマを独自に作成したり、コンポーネントのスタイルを変更したりしてはいけません。
• 各グループに同じパディング、角丸、細い破線の境界線を設定します。どちらのテーマでも控えめながら見やすいようにしてください。境界線には、既存のミュートカラーを約25％の不透明度で使用します。飾りのないタイトルを境界線の8px上に配置し、不透明度を下げずにミュートカラーのテキスト色を使います。
• 横幅の広いグループを用意し、各行を幅が均等なサンプル枠で埋めます。必要に応じて折り返し、グループ内およびグループ間に十分な横方向と縦方向の間隔を確保します。コンポーネントを拡大せずにレイアウト全体に広げて配置します。
• グループはドラッグできないようにします。位置をハードコードする必要はありません。タイトル、境界線、パディングを含む実際の境界を測定してください。レンダリング前にスペースを確保するためのプレースホルダー（空のボックス）は、実際のコンテンツサイズを反映しないため無視してください。
• 背景のドット、装飾用カード、ページメニュー、説明バナー、選択ツール、ブロック編集は省略します。コンポーネントカードやメニューはサンプルとして表示してもかまいません。

バリエーション

• 要求された範囲内で、サポートされている名前付きバリエーションと有用な状態をすべて表示します。スタイル、テキストとアイコンのサイズ、向き、配置、整列、モダリティ、折りたたみモードについて、公開 API を確認します。
• 有用なコンテンツと構成の例を含めます。
• バリエーションを創作したり、すべてのプロパティの組み合わせを生成したりしないでください。省略した項目とその理由を記載します。
• 一度に比較するプロパティまたは機能は一つだけにします。それ以外はすべて同じに保ちます。同じラッパー、サンプルデータ、テキスト、アイコン、テーマ、間隔を使用します。
• スタイルの比較では、スタイルバリエーションだけを変更します。サイズ、状態、配置、その他の比較には、通常はデフォルトの単一スタイルを使用します。

例：サイズの比較では、すべてのボタンのテキストを「続行」とし、variant="default" を使用します。変更するのは size だけです。スタイルの比較では variant を変更し、サイズとテキストは同じに保ちます。

• コンポーネント本来の状態スタイル（無効時の不透明度、チェック時の色）を維持します。無効状態または読み取り専用状態を示す例を除き、例は入力に応答するようにします。
• クラスを追加するのではなく、実際のポインター入力とキーボード入力でホバー、フォーカス、押下状態をテストします。
• ポータルの例では、毎回同じトリガーを使用します。複数のモーダルを同時に開かないでください。
• バリエーション一覧と網羅性テストを用意します。プロジェクトが型をサポートしている場合は、型を使用します。
• コンポーネントでレスポンシブなケースまたは視覚的なケースを表示できない場合は、その制限を説明します。見せかけのためにコンポーネントを変更しないでください。

インタラクション

• クリック、テキスト選択、入力、ボタンとスイッチの操作、フォーカス、入れ子になったスクロールが引き続き機能するようにします。
• キャンバスのショートカット（Space、矢印、Escape、ネイティブの取り消し）は、キャンバスのシェル内にだけ適用します。プレビューの操作からこれらのキーを奪わないでください。
• キャンバス内のプレビューのナビゲーションは、キャンバスホストで処理します。キャンバスグループへのリンクでは、ページをスクロールするのではなくカメラを移動させます。ポータル内のリンクも含め、キャンバス外へ移動するリンクの動作を定義します。コンポーネントのリンクやルーター内部は変更しないでください。
• ポータルは画面座標系のサイズでネイティブのルートに配置したままにします。位置決めとモーダルのフォーカスはライブラリに任せます。必要な場合にのみ公開コンテナオプションを使用します。キャンバスの変換下で位置とクリック可能な領域を確認します。問題が起きる場合は、その旨を報告するか、別のプレビュー用ドキュメントを提案します。コンポーネントにパッチを当てないでください。
• キャンバスには、取り消し／やり直し、編集用ショートカット、履歴はありません。

プレビューの安全性

プレビューをマウントする前に、安全性を確保します。

• テストデータを使うプロバイダー、モックサービス、または既存のコールバックプロパティを使って、実環境への呼び出しや実際の書き込みを防ぎます。
• 静的なデモ用アセットとローカルのフィクスチャは使用できます。
• 本番環境の認証情報やデータは使用しないでください。
• 安全に隔離できない場合は、実環境を使う例を省略し、その理由を説明します。ドキュメントを別にするだけでは、プレビューの安全性は確保されません。

カメラ

• マウスとトラックパッド：パンし、カーソル位置を中心にズームします。タッチ：パンとピンチ操作を行います。
• 空のキャンバス領域で通常のパンを開始します。プレビューとポータル内ではネイティブジェスチャーを維持します。
• イベントを広範囲にキャンセルせず、インタラクティブなコンテンツに touch-action: none を指定しないでください。
• ポインター数の変化、キャンセル、キャプチャの喪失、ウィンドウのフォーカス喪失、非表示タブに対応します。破棄時にはキャプチャを解放し、リスナー、オブザーバー、タイマー、アニメーションフレームをクリーンアップします。
• ジェスチャーによる変換は、アニメーションフレームごとに最大1回適用します。レイアウトの読み取りと書き込みを交互に行わないでください。
• コンテンツの拡大時やビューポートのサイズ変更時にグループが重ならないようにします。レイアウトループや不要な移動を避けます。レイアウトが安定してからフィットさせます。フィット操作でグループの配置を変えてはいけません。
• 表示範囲外のキーボードフォーカスが見えるようにカメラを移動します。ネイティブのページスクロールでキャンバスが動かないようにします。
• キーボードによるカメラ操作が機能し、キャンバスのコントロールに視認可能なフォーカスがあるようにします。
• アクセシブルな名前を持つ「すべてにフィット」と「リセット」のアイコンボタンを用意します。ビューが失われた場合でも操作できるようにします。
• カメラの値を検証し、範囲内に収まるようにします。

永続化

• カメラのみをバージョン管理された形式で保存し、プロジェクトまたはワークスペースごとにストレージキーを使用します。
• 不正な形式またはサイズ超過のデータ、利用できないストレージ、容量超過エラーに対処します。
• 既知の古い形式を移行します。不明な形式の場合は安全なデフォルトを使用し、古いグループ位置と履歴を破棄します。
• リセットではカメラのみを元に戻します。プレビュー状態や下書きは消去しません。

確認項目

許可されている場合は、リポジトリのチェックを実行します。その後、ブラウザーで次の項目を確認します。

• ルートがマウントされ、インポートとエクスポートが解決され、コンソールにエラーが表示されないこと。
• コンポーネントのソースに変更がないこと。
• 表示対象のバリエーションが表示され、省略したものについて説明され、グループに破線の枠線があり、スタイル以外の比較では単一のスタイルが使われていること。
• キーボードによるカメラ操作とフォーカスの可視化が機能すること。プレビューコントロールが本来のショートカットとジェスチャーを維持していること。
• 複数のズームレベルとビューポートサイズで、ネストされたスクロール、ポータルの配置、クリック可能な領域、モーダルのフォーカスが機能すること。
• パンとピンチがポインターの変更やキャンセル後も正常に動作すること。破棄時にリソースが解放されること。
• グループの展開後やサイズ変更後に、グループが重ならないこと。全体表示が機能し、画面外の要素にフォーカスすると正しく表示されること。
• カメラが再読み込み後も保持されること。ストレージのエラー時に安全にフォールバックすること。リセット後もプレビューの下書きが保持されること。要求がない限り、下書きが再読み込み後も残る必要はありません。
• グループをドラッグできないこと。キャンバスに取り消し／やり直し機能がないこと。
• プレビューで安全なテストデータが使用され、プロジェクトやアカウントへの実際の書き込みが発生しないこと。

チェックは、実行した場合にのみ合格とみなされます。チェックを省略した場合は、その旨を記載してください。

レポート

ビルドまたはレビューの最後には、必ず次の見出しを記載します。

• 変更点： 変更したファイルと各ファイルの変更内容。コンポーネントに変更があった場合は記載します（変更はないはずです）。
• 実行したチェック： 各チェックとその結果。
• 未動作または未テスト： 既知の不足、省略したバリエーションとその理由、未確認の項目。
• 決定事項： 質問せずに選択したデフォルト。

上記のチェックがすべて合格していない限り、実装を検証済み、またはテンプレートを利用可能と説明しないでください。