canvas-component-definition

プロジェクトの種類

このスキルを適用する前に、package.json に @drupal-canvas/headless または @drupal-canvas/headless- で始まる依存関係があるか確認してください。該当する依存関係がある場合、このコードベースは Canvas Headless です。まず canvas-headless を読んでください。以下の React 固有のガイダンスよりも、そちらが優先されます。該当する依存関係がない場合、このコードベースは Canvas でレンダリングされる React です。コンポーネントは React（index.jsx／.tsx）であり、このスキルの内容がすべてそのまま適用されます。プロジェクトの種類はこの2つだけです。

正式な定義

Canvas コンポーネントは、次の要素で構成されるパッケージです。

1. 実装エントリーファイル（React プロジェクトでは index.jsx、headless プロジェクトでは index.vue、index.astro など。詳しくは canvas-headless を参照）
2. Canvas のメタデータ／スキーマ（component.yml）
3. 命名規則および構造との互換性（machineName、フォルダーパス、Workbench のモックパス）
4. Canvas 互換の props／slots モデリング
5. 作成したプレビュー状態をカバーする Workbench モック

最初の4つは、Drupal Canvas でコンポーネントを使用するために必須です。Workbench の組み込み Default タブ以外の名前付きプレビュー状態を作成するには、Workbench モックを使用してください。

最低限の要件（必須）

すべての Canvas コンポーネントは、以下のチェック項目をすべて満たす必要があります。

• コンポーネントフォルダーが <components-root>/<machine-name>/ に存在する（リポジトリで設定されたコンポーネントルートを使用します。.env で定義されている場合があります）
• 実装エントリーファイルが <components-root>/<machine-name>/index.jsx に存在する（headless プロジェクトでは、フレームワークに適した拡張子を使用）
• メタデータが <components-root>/<machine-name>/component.yml に存在する
• component.yml に必須のトップレベルキー（name、machineName、status、required、props、slots）が含まれている
• フォルダー名が component.yml の machineName と完全に一致している（ケバブケース）
• props／slots が Canvas のルールに従っている（たとえば、サポートされていないオブジェクト配列の prop 形状は避け、繰り返し使う複雑なコンテンツには slots を使用する）
• 繰り返し表示するカード／項目を、card1Title、card2Title、car3Image のような番号付きの prop グループに分割しない。代わりに、親の slot コンテンツと子の項目コンポーネントとしてモデル化する
• 画像を表す prop には、$ref: json-schema-definitions://canvas.module/image を指定した単一のオブジェクト prop を使用する。1つの画像を imageUrl、imageAlt、imageWidth などの文字列／数値 props に分割しない
• 選択された Drupal エンティティを表す prop には、$ref: json-schema-definitions://canvas.module/content-entity-reference を指定し、component.yml に対応する dataDependencies.entityFields.<propName> エントリーを設定する

いずれかの項目が欠けている場合、そのコンポーネントは Canvas での使用に不完全です。

ローカルでの作成とレビューのため、コンポーネントのソースおよびメタデータと同じ場所に、対応する Workbench モックファイルを追加してください。

• コンポーネントのエントリーファイルおよび component.yml と同じ場所に mocks.json を配置する
• component.yml の各 prop の最初のサンプル値を使用してコンポーネントをレンダリングする自動生成の Default タブ以外にプレビューが必要な場合は、名前付きモックを少なくとも1つ作成する

コンポーネントに十分な Workbench プレビューのカバレッジがない場合、レンダリング出力の変更は不完全です。

命名ガイダンス

このコードベースはすでに特定のプロジェクトまたは製品向けなので、コンポーネント名にプロジェクト名や製品名のプレフィックスを付ける必要はなく、付けてはいけません。machineName、フォルダー名、表示名は、acme-hero や nebula-contact-form ではなく、hero や contact-form のように汎用的で再利用しやすい名前にしてください。

再利用可能な基本名のうち、最も短いものをデフォルトで使用してください。「simple hero」「solid hero」「cream hero」「two cards」のような依頼でも、通常は Hero または Card にします。違いはコンポーネント名ではなく、props、バリアント、コンポジション、またはモック名で表現してください。コンポーネントが本当に一度限りのものである場合に限り、特化した名前を使用します。

命名規則と例については references/naming.md を参照してください。

作成前の再利用チェック

新しいコンポーネントを作成する前に、特にユーザーが再利用、組み合わせ、ラップするコンポーネントを指定している場合は、既存のワークスペースコンポーネントで要件を満たせるか確認してください。

これが、再利用を優先するための標準ポリシーです。他のスキルでは同じ判断基準を繰り返さず、ここにリンクしてください。

• 既存のコンポーネントがすでに適合する場合、または妥当な拡張、バリアント、薄いラッパーで適合させられる場合は、それを再利用してください。
• 既存のコンポーネントを迂回する代替コンポーネントを、明示せずに作成しないでください。
• 名前が指定された既存のコンポーネントを、新しい実装で明示せずに置き換えないでください。
• 既存のコンポーネントが適合しない場合は、その不一致を説明し、拡張、ラップ、新しい目的特化型コンポーネントの作成のいずれかを意図的に選択してください。
• 不一致やトレードオフによって、依頼に沿えているかどうかが変わる場合は、それを明示してください。

ワークベンチのモック

モックの命名、配置、形式の選択、検証には references/component-mocks.md を使用してください。

スキルの連携

以下の順序で、関連スキルの使用を検討してください。

0. canvas-design-decomposition
   • 作業を構成する前に、デザイン（Figma フレーム、スクリーンショット、スクレイピングしたページ、または口頭での仕様）を領域、コンポーネントツリー、意図的な props と slots に分解する必要がある場合に使用します。このスキルで計画を作成し、このスキル（canvas-component-definition）でその後のフォルダー構成の要件と実装を担います。境界がすでに明らかな既存コンポーネントのみを編集する場合は、ステップ 0 を省略してください。
1. canvas-component-metadata
   • component.yml、props／slots、列挙型の作成や変更、または prop の検証エラーの修正時に使用します。
2. canvas-component-composability
   • prop／slot 構成の設計、大規模なコンポーネントの分解、props と slots のどちらを使うかの判断、既存コンポーネントの再利用／組み合わせ／ラップ、繰り返し表示するリスト／グリッドのコンテンツのモデル化に使用します。
3. canvas-styling-conventions
   • 新しいコンポーネント、スタイル用 props、Tailwind トークンの使用、CVA バリアント、クラスの変更、スタイルに影響する prop の変更など、すべてのスタイリング作業に使用します。
4. canvas-component-utils
   • FormattedText と Image を使って、書式付き HTML テキストやメディアをレンダリングする場合に使用します。
5. canvas-data-fetching
   • JSON:API、SWR、includes、フィルターパターンを使って Drupal コンテンツを取得／レンダリングする場合や、パンくずリスト、ブランディング、エンティティメタデータ、言語切り替えのためにページ／サイトのコンテキストを読み取る場合に使用します。
6. プレビューの網羅性の確認
   • Default の例と、作成した mocks.json の各状態が、依頼された変更のレビューに十分であることを確認してください。
7. canvas-component-push（任意）
   • ユーザーが Canvas へのコンポーネントのプッシュ／公開／同期を明示的に依頼した場合にのみ使用してください。
   • 実装や静的検証の後に、自動でプッシュを実行しないでください。