shadow-dom-overlay-insertion

シャドウ DOM へのオーバーレイ挿入

問題

コンポーネント A（例：EFCanvas）が自身の隣にオーバーレイを DOM に挿入しようとすると、通常は this.parentElement.appendChild(overlay) を使用します。A がシャドウ DOM ホスト（例：EFWorkbench）内にスロットとして配置されている場合、これは正常に動作しません。

EFWorkbench (shadow host)
  shadow root
    <div class="canvas-slot-container">   ← the real DOM parent
      <slot name="canvas">                ← slot element
        [EFCanvas is assigned here]       ← light DOM, assigned via slot

• efCanvas.parentElement は内部コンテナーではなく、シャドウホストを返します
• shadowHost.appendChild(overlay) を呼び出すと、オーバーレイはホストの ライト DOM に配置されます。シャドウ DOM の CSS と z-index が適用されないため、オーバーレイが表示されません

修正パターン

private insertOverlay(overlay: HTMLElement): void {
  const slot = this.assignedSlot;

  if (slot) {
    // Correctly slotted: insert into the shadow-internal container
    slot.parentElement?.appendChild(overlay);
    return;
  }

  if (this.parentElement?.shadowRoot) {
    // Shadow DOM exists but slot assignment hasn't happened yet
    // (connectedCallback fires before Lit renders shadow DOM).
    // Return early; caller should retry via requestAnimationFrame.
    return;
  }

  // Not slotted — plain DOM, safe to use parentElement
  this.parentElement?.appendChild(overlay);
}

タイミングに関する注意点

HTML の解析中、Lit がシャドウ DOM をレンダリングする前に connectedCallback が実行されます。この時点では：

• this.assignedSlot は null です（スロットの割り当てがまだ行われていません）
• this.parentElement は null ではありません（シャドウホストです）
• this.parentElement.shadowRoot も null です（シャドウ DOM がまだアタッチされていません）

同じマイクロタスクの実行中に後から（Lit の performUpdate の後に）：

• this.assignedSlot は <slot> 要素になります
• slot.parentElement は内部コンテナーになります

ガードパターン：

connectedCallback() {
  super.connectedCallback();
  this.tryInsertOverlay();
}

private tryInsertOverlay(): void {
  if (!this.assignedSlot && this.parentElement?.shadowRoot) {
    // Too early — shadow host exists but slot not yet assigned.
    // Lit will assign the slot after performUpdate.
    requestAnimationFrame(() => this.tryInsertOverlay());
    return;
  }
  this.insertOverlay(this.overlay);
}

ルールのまとめ

状況	assignedSlot	parentElement.shadowRoot	対応
スロットに配置されていない	null	null/undefined	parentElement.appendChild を使用
正しくスロットに配置されている	non-null	（任意）	assignedSlot.parentElement.appendChild を使用
早すぎる場合（Lit が未レンダリング）	null	non-null	早期に return し、RAF 経由で再試行
スロットに配置され、親にシャドウがない	null	null	parentElement.appendChild を使用

親がシャドウ DOM ホストの場合、this.parentElement を直接使用しないでください。