メインコンテンツまでスキップ

シェルコントラクト

シェルコントラクトはアプリケーションの名前付き領域を定義します。テーマはこれらの領域をスタイリングし、プラグインは安定したスロットを通じてコンテンツを追加します。

名前付きシェル領域​

ホストは各メイン領域を安定したスロット属性で公開します:

スロット領域
app.shellアプリケーションシェルのルート
navigation.primaryナビゲーションレール
chat.headerチャットヘッダー
chat.viewportチャットのスクロールビューポート
chat.composerメッセージコンポーザー
character.browserキャラクターブラウザーのルート
panel.left左コンテキストパネル
status.area接続ステータス領域
modal.layerモーダルレイヤー（システムサーフェスの下のプラグイン）
notification.layer通知レイヤー

2 つのスロットが予約されていますが、v1 の一部ではありません: navigation.secondary と panel.right。

コントラクトが許可するもの​

テーマは次のことができます:

  • 任意の名前付き領域をスタイリング します。data-slot 属性とその中のコンポーネントフックを通じて。
  • メイン領域を配置 します。マニフェストの宣言型 shellLayout を通じて — 現在はナビゲーションレールの順序（main と bottom グループ）と管理タブの配置（pinned）。
  • チャットキャンバスの背景を置き換え ます。chat-wallpaper-* トークンを通じて。

領域の自由形式の再配置 — たとえばレールを右側に移動する — は v1 の一部ではありません。スロットはスタイリングされ埋められるもので、再配置されるものではありません。

プラグインがコンテンツを追加する方法​

プラグインは SDK の登録 API を受け取り、ホストはそのコンテンツを安定したスロットに配置します。たとえば、slot: 'left' で登録されたサイドバーパネルは panel.left 内にレンダリングされ、プラグインダイアログはシステムサーフェスの下の modal.layer 内にスタックします。

この分割から導かれるコントラクト:

  • テーマはプラグインの内部 DOM に依存しません。
  • プラグインは内部 React 階層や特定の生成クラス名に依存しません。
  • 両者は名前付きスロットとフック属性でのみ出会います。

領域内の安定したフック​

領域内で、コンポーネントは標準のフック属性を公開します。注目すべき例:

  • コンポーザールートは data-slot="chat.composer" を公開し、ツールバー部分、フィールド部分、data-component="textarea" の入力があります。
  • ボタンは data-component="button" を公開し、data-part="icon" と data-part="label" があり、関連アクションはアクションバー（data-component="action-bar"）にプライマリとセカンダリのグループで存在します。
  • タブは data-component="tabs" を公開し、list、trigger、content の部分があります。管理パネルはセグメントバリアントを使用します。
  • メッセージは data-component="chat-message" を公開し、data-role="user|assistant|system|tool" と streaming などの状態があります。
  • ナビゲーションレールは data-component="navigation-rail" を公開し、data-part="main-items"、data-part="bottom-items"、エントリごとの data-item="<id>"、そして data-state="expanded|collapsed" があります。
  • すべてのレールパネルは 1 つのヘッダークローム（data-component="sidebar-panel-header"）を共有するため、テーマは一度スタイリングすれば済みます。

レイアウトの責任​

ホストは動作に重要なレイアウトを所有します: フォーカストラップ、論理 RTL 方向、セーフエリアのインセット、最小インタラクティブターゲットサイズです。シェルテーマは領域の見た目と配置を変更できますが、文書化された DOM 順序、アクションリストの水平スクロール、キーボード動作を保持しなければなりません。ブレークポイントは SDK に登録され（ビューポート幅は VIEWPORT_BREAKPOINTS、コンテナサイズは CONTAINER_BREAKPOINTS）、prefers-reduced-motion などの機能クエリはレイアウトブレークポイントではありません。

これらの領域をスキンするスタイリングレイヤーはコンポーネントスキン を、シェルが壊れたときの復旧はセーフモード を参照してください。