embed-creator

埋め込みコンポーネント作成

ブランチ上で Datex Studio の埋め込みコンポーネント（configurationTypeId=20）を作成または変更します。これは、表示領域全体が単一の <iframe> である薄い UI コンポーネントです。埋め込みコンポーネントは、外部 URL（ホストされたマップ、ダッシュボード、ドキュメントビューアー）またはメモリ内の HTML 文字列（生成されたメールやレポートのプレビュー）を表示し、ほとんどの場合、$shell.open<referenceName>Dialog(...) でダイアログとして開きます（モジュールに登録されている場合は、埋め込みコンポーネントのパッケージ名が前に付きます）。

参照資料

• ../datex-studio-shared/branch-setup.md — ブランチ／接続の選択（各スキルで共通）
• references/embeds.md — 埋め込みコンポーネント作成の正式なリファレンス：ファイル形式、最小有効スケルトン、iframe のみというルール、data: URI を使った HTML 文字列のパターン、ダイアログの接続方法、印刷パターン、CSP に関する注意事項、事前確認チェックリスト
• ../datex-studio-conventions/file-format.md — configurationTypeId の一覧と TypeScript 式のエンコード規則（iframeConfig.href に適用）
• ../datex-studio-conventions/naming-conventions.md — _embed／-embed のサフィックス、ファイル名の拡張子を除いた部分の一致、表示名の規則
• ../datex-studio-runtime/runtime-globals.md — 埋め込みコンポーネントのコードで使用できる、プラットフォームから注入されるグローバル変数（$embed、$shell、$datasources、$utils など）
• ../form-creator/references/forms.md — 関連コンポーネント。コンテンツの横にフィールドコントロールやボタンが必要な場合はフォームを選択してください（フォームと埋め込みコンポーネントの選択）
• ../component-wiring-check/references/component-wiring.md — ホスト側の参照契約、変数を宣言する必要があるというルール、埋め込みコンポーネントを開くコンポーネントの moduleId ルール

依存関係

• requirements-gathering スキル — 会話のコンテキストに要件概要がない場合、その作成のために呼び出されます
• form-creator スキル — 要件にコンテンツの横のフィールドコントロールやツールバーが実際に必要な場合に呼び出されます（埋め込みコンポーネントは iframe のみで、ボタン用の表示領域はありません）
• component-wiring-check スキル — プッシュする前に、埋め込みコンポーネントを開くコンポーネントの configParameters と inParams の契約を監査するために呼び出されます

CLI のライフサイクル

埋め込みコンポーネントの作成には dxs configuration を使用します。これは、プラットフォームのすべての設定タイプに対応する汎用 CRUD プリミティブです。dxs embed サブコマンドやフィールド単位のパッチ機能はありません。JSON 本文全体を作成（または取得して抽出）し、編集してから、全体を再度プッシュします。CLI のタイプ識別子は embed（小文字）で、configurationTypeId: 20 に対応します。

新しい埋め込みコンポーネントを作成する場合：

# 1. Build body.json from scratch (see references/embeds.md → Minimal Valid Skeleton)
# 2. Validate — gates the push; exit 1 = errors found, not a broken CLI. Catches the "HREF is required" failure before push
dxs configuration validate embed -b <branchId> -D body.json
# 3. Create (upsert creates or updates by referenceName)
dxs configuration upsert embed -b <branchId> -D body.json

既存の埋め込みコンポーネントを編集する場合：

# 1. Fetch — note the envelope wrapper
dxs configuration get embed <configId> -b <branchId> -O envelope.json
# 2. EXTRACT THE INNER BODY (round-trip footgun guard)
jq .json envelope.json > body.json
# 3. Edit body.json
# 4. Validate — gates the push. Exit 1 = errors found (read validation_errors, fix, re-run), not a broken CLI
dxs configuration validate embed -b <branchId> -D body.json
# 5. Push
dxs configuration upsert embed -b <branchId> -D body.json

ラウンドトリップのルール（重要）

既存の設定を編集する際、envelope.json を直接 dxs configuration upsert にパイプで渡してはいけません。設定内容がひそかに破損します。編集前に、必ず jq .json envelope.json > body.json を実行してください。正式なラウンドトリップの方法と根本的なバグについては、../datex-studio-shared/configuration-roundtrip.md を参照してください。

ワークフロー

[Phase 1: Setup + Requirements]
Follow branch-setup.md for branch/connection selection
        |
[requirements brief in context?]  ── NO ─> invoke `requirements-gathering`
        |
[Phase 2: Embed vs Form decision]
Consult references/embeds.md → "Purpose & When to Use":
  - render a URL or an HTML blob, no controls needed   -> embed
  - needs field inputs, a toolbar, or a Print button
    that lives outside the rendered content            -> form (or put the
                                                          control inside the HTML)
If field controls/toolbar are required -> invoke `form-creator` and stop here.
        |
[Phase 3: Pick the source — URL or HTML string]
  URL          -> iframeConfig.href points at the URL (directly or via a var
                  computed in on_init). Example: a hosted map.
  HTML string  -> on_init sets a var to a data:text/html URI built from the
                  HTML; iframeConfig.href points at that var.
        |
[Phase 4: Author embed body]
Build body.json from references/embeds.md → Minimal Valid Skeleton:
  - type: "iframe"  (the only supported designer type)
  - iframeConfig.href  (REQUIRED — a TS expression, usually $embed.vars.<url>)
  - inParams[]  (the URL / HTML / id the host passes in)
  - vars[]  (the computed href var)
  - onInitFlowConfig -> on_init flow that computes the href var
        |
[Phase 5: Validate + push]
dxs configuration validate embed -b <branchId> -D body.json
dxs configuration upsert  embed -b <branchId> -D body.json
        |
[Phase 6: Wire the opener + verify]
Caller opens it: $shell.open<referenceName>Dialog(inParamsObj, 'flyout', EModalSize.Xlarge)  (+ <Package>. segment if the embed is in a module)
Verify in Studio: iframe renders; if HTML preview, the in-document Print button works
        |
[invoke `post-edit-verification`; then `component-validator`]

フェーズの詳細

フェーズ 2：埋め込みコンポーネントとフォームの選択

埋め込みコンポーネントの画面表示領域全体が iframe です。フィールドコントロール、ツールバー、ボタン用の表示領域はありません。要件が「この URL／HTML をダイアログまたはパネルに表示する」だけの場合は、埋め込みコンポーネントを選択します。ダイアログに入力欄、検証後に確定するフロー、またはコンテンツを囲む UI（ヘッダーやツールバー）が必要な場合は、代わりにフォームを選択してください。ボタンと表示する HTML の両方が必要なら、フォームではなく、ボタンをHTML 内に置くのが実用的です（印刷パターンを参照）。フォームには iframe を配置できません（iframe 用のフィールドコントロールがありません）。

フェーズ 3：ソースを選択する — URL または HTML 文字列

iframeConfig.href が唯一のコンテンツチャネルです。srcdoc はなく、インライン HTML の埋め込みタイプもありません。このスキルでは type は常に iframe です（列挙型のもう一つのメンバーである powerBi はコード生成でサポートされておらず、Studio UI では制限されています。「よくある間違い」を参照してください）。したがって：

• 外部 URL — on_init で URL を計算するか、href 変数にハードコードします。$embed.inParams からクエリパラメーターを組み立てます。

• メモリ内の HTML 文字列 — on_init で文字列を data: URI に変換します。

  $embed.vars.ref_url = "data:text/html;charset=utf-8," + encodeURIComponent($embed.inParams.html);
  

  そして iframeConfig.href に "$embed.vars.ref_url" を指定します。ダイアログ内に生成した HTML（メールのプレビューやレポートの校正用表示など）を描画する標準的な方法です。references/embeds.md → HTML 文字列の描画を参照してください。

フェーズ 4：埋め込みの本文を作成する

references/embeds.md → 最小限の有効なスケルトンを基に body.json を作成します。重要なポイントは次のとおりです。

1. ファイルの基本事項。 configurationTypeId: 20、サフィックスは -embed.json、referenceName は _embed で終わり、ファイル名のステムと一致させます。さらに、共通チェック（../datex-studio-conventions/universal-checklist.md）として、description は null 以外で、100 文字以内である必要があります。
2. type: "iframe"。 コード生成でサポートされる唯一の EEmbedDesignerType です。列挙型には powerBi も定義されていますが、コード生成では完全にサポートされておらず、Studio UI でも制限されているため、絶対に作成しないでください。列挙型にない値（html、script、content、code）は検証で即座に失敗します。
3. iframeConfig.href は必須で、TypeScript の式です。 $embed.vars.ref_url だけを指定すると、生の式（ラップなし）として扱われます。リテラル URL は TypeScript の文字列リテラル（"'https://example.com'"）にする必要があります。ただし、URL はほぼ常に inParams に依存するため、on_init で計算して変数にバインドする方法を推奨します。../datex-studio-conventions/file-format.md → 宣言的な文字列値は TypeScript の式を参照してください。
4. 記述する $embed.vars.<id> はすべて宣言してください。 href 変数（およびその他の変数）はトップレベルの vars[] に含める必要があります。含まれていないと書き込みに失敗します。エディターやフォームと同じルールです。
5. on_init で href を計算します。 onInitFlowConfig フロー（configurationTypeId: 9 の埋め込みフロー）で $embed.inParams を読み取り、URL または data: URI を組み立てて、href 変数に割り当てます。

フェーズ 6：呼び出し元を接続して検証する

埋め込みを開くコンポーネント（エディターフロー、ハブのツールバーのボタン、グリッドの行アクションなど）は、自動生成されたシェルメソッドを呼び出します。

// top-level embed (no package):
await $shell.opencustom_email_preview_embedDialog({ html: previewHtml }, 'flyout', EModalSize.Xlarge);
// embed registered under a package:
await $shell.<Package>.opencustom_email_preview_embedDialog({ html: previewHtml }, 'flyout', EModalSize.Xlarge);

メソッド名は open + 埋め込みの referenceName + Dialog です（スネークケースはそのまま保持されます）。埋め込みがパッケージ／モジュールに登録されている場合にのみ、パッケージセグメントが付きます。トップレベルのアプリケーション埋め込みは、セグメントなしで $shell.open<referenceName>Dialog(...) として開きます。パッケージがある場合、<Package> は呼び出し元ではなく、埋め込み自体のモジュールです。inParam オブジェクトは埋め込みの inParams から生成されます。ホストには、それらの inParams を満たす完全な configParameters 契約が必要です。また、パッケージ化された埋め込みの場合は moduleId を埋め込みのパッケージに設定します。component-wiring-check で監査してください。

Studio で検証します。iframe に URL／HTML が描画されることを確認します。HTML プレビューの場合は、ドキュメント内の 印刷 ボタンで埋め込みコンテンツだけが印刷されることを確認してください（印刷のパターンと注意事項を参照してください）。

事前チェックリスト

references/embeds.md → 事前チェックリストにあるチェックリスト全体を確認してください。簡易版は以下のとおりです。

1. ファイルの基本事項。 configurationTypeId: 20、サフィックスは -embed.json、referenceName は _embed で終わり、ファイル名のベース名と一致していること、title は他と区別できるセンテンスケースの表示名であること。さらに、共通チェックも確認してください（../datex-studio-conventions/universal-checklist.md）。
2. type: "iframe" — コード生成でサポートされる唯一のタイプです。定義されていますがサポートされていない powerBi は作成しないでください。
3. iframeConfig.href が存在すること — 省略すると HREF is required エラーになります。
4. Href 変数が宣言されていること — トップレベルの vars[] で宣言し、on_init で値を割り当ててください。
5. HTML 文字列を埋め込む場合は、data:text/html;charset=utf-8, と encodeURIComponent(...) を組み合わせて URI を作成してください。srcdoc には依存しないでください。
6. **印刷ボタン（プレビューの場合）**は HTML 内に配置し（onclick="window.print()"）、@media print で非表示にしてください。親から iframe 内を呼び出せるとは考えないでください。
7. 呼び出し元との契約 — ホストでは、各埋め込みの inParam に対応する configParameters エントリを宣言してください。component-wiring-check で監査できます。
8. description は null ではなく、空でなく、100 文字以下であること。

よくある間違い

症状 → 原因 → 対処法の正式な一覧は、references/embeds.md → よくある失敗パターンにあります。作成時によく起きる注意点は以下のとおりです。

• srcdoc や、インラインでマークアップを挿入するための iframe 以外の type（html／script／content） — いずれもサポートされていません。href の data:text/html URI を介して HTML を描画してください。
• iframeConfig.href を省略する — HREF is required エラーで検証に失敗します。これが唯一のコンテンツ受け渡し経路です。
• $embed.vars.<id> に書き込む際、vars[] で宣言しない — 書き込みに失敗します。
• href にリテラル URL をクォートせずにハードコードする — href は TS 式です。TS の文字列としてクォートする（"'https://...'"）か、on_init で計算してください。
• 内側の .json ではなくエンベロープをアップサートする — 設定内容が警告なしに破壊されます。まず jq .json envelope.json > body.json を実行してください。

編集後、post-edit-verification を実行して、description／JSON／スキーマの違反を検出してください。最終確認には component-validator を実行してください。