🌓 Chapter 83: Shadow DOM

Event Retargeting & Composed Events

`event.composed`, `composedPath()`, event target re-mapping across shadow boundaries, and custom event propagation mechanics.

LEARNING OBJECTIVES ⌵

Understand the mechanism and rationale behind Event Retargeting across Shadow DOM boundaries.
Differentiate between event.target, event.currentTarget, and event.composedPath().
Master the composed: boolean property and know which standard DOM events cross shadow boundaries.
Construct and dispatch encapsulated CustomEvent instances from within shadow trees.
Trace full event propagation trees through nested custom components using composedPath().

🎬 INTERACTIVE VISUAL PIPELINE Core Architecture Simulation

🌐

1. Input

Directives & Tags

⚙️

2. Parse

Tokenizer & AST

🌳

3. Layout

Box Model & Flow

🎨

4. Render

GPU Paint & Composite

PHASE 1: INPUT & DIRECTIVES

Browser receives declarative markup stream, parsing tag tokens and initializing component state.

📖 The Mental Model & Story (Intuitive Foundation)

Imagine a customer calling the corporate headquarters of an international logistics company to report a delivered package.

Internal Event (Inside the Fulfillment Center): Inside warehouse #42, forklift driver #892 places a cardboard box onto conveyor belt #4 (event.target = ForkliftDriver892).
External View (Event Retargeting at the Company Boundary): When the delivery notification reaches the customer's phone, the customer does not see the names of the internal forklift drivers, warehouse managers, or conveyor belt serial numbers. The notification says: "Your package was shipped by FedEx / Acme Corp" (event.target = <logistics-service>).
Security & Encapsulation Integrity: Internal personnel and machinery remain encapsulated. The outside world knows which organization handled the event without exposing internal operational blueprints.

SHADOW DOM (Private Warehouse)
┌─────────────────────────────────────────────────────────────┐
│  #shadow-root (open)                                        │
│    └── <div class="btn-wrap">                               │
│          └── <button id="internal-btn">Click Me</button>    │
│                 │                                           │
│                 │ Click Event Occurs                        │
│                 │ (Inside Shadow: event.target = <button>)  │
│                 ▼                                           │
════════════════════════ [ SHADOW BOUNDARY ] ════════════════════
                          │
                          │ Event Crosses Boundary
                          │ (Retargeted: event.target = <custom-widget>)
                          ▼
LIGHT DOM (Corporate Headquarters)
┌─────────────────────────────────────────────────────────────┐
│  <custom-widget>                                            │
│    └── document.addEventListener('click', (e) => {          │
│          console.log(e.target); // <custom-widget>          │
│        });                                                  │
└─────────────────────────────────────────────────────────────┘

Technical Deep Dive & Specifications

1. The Event Retargeting Algorithm

According to the WHATWG DOM Specification (Section 2.9: Dispatching Events): When an event bubbles up through a shadow boundary into an ancestor tree, the browser retargets the event:

Inside the shadow root: event.target points to the actual element clicked (e.g. <button id="internal-btn">).
Outside the shadow root (in the light DOM): event.target is adjusted to point to the Shadow Host element (<custom-widget>).

This prevents outer scripts from taking hard dependencies on the internal DOM structure of third-party or library components.

2. `event.target` vs `event.composedPath()`

While event.target is retargeted, developers who legitimately need to inspect the original trajectory can use event.composedPath():

document.addEventListener('click', (event) => {
  console.log('Retargeted Target:', event.target); 
  // <custom-widget>

  console.log('Composed Event Path:', event.composedPath());
  // [<button#internal-btn>, <div.btn-wrap>, #shadow-root, <custom-widget>, <body>, <html>, document, Window]
});

[!NOTE] If a shadow root was created in mode: 'closed', composedPath() will truncate the path at the shadow host, withholding internal nodes from outer listeners!

3. The `composed` Flag

An event can cross shadow boundaries only if its composed attribute is true.

                  ┌──────────────────────┐
                  │ Event Dispatched in  │
                  │     Shadow Tree      │
                  └──────────┬───────────┘
                             │
                  bubbles: true / false?
                             │
               ┌─────────────┴─────────────┐
               ▼                           ▼
        bubbles: false              bubbles: true
      (Does not bubble)          (Bubbles to #shadow-root)
                                           │
                             composed: true / false?
                                           │
                             ┌─────────────┴─────────────┐
                             ▼                           ▼
                      composed: false             composed: true
                 (Stops at Shadow Boundary)  (Crosses into Light DOM)

4. Standard DOM Event Composition Matrix

Event Category	Standard Event Types	`bubbles`	`composed`	Crosses Boundary?
Mouse / Pointer	`click`, `dblclick`, `mousedown`, `mouseup`, `pointerdown`	✅ Yes	✅ Yes	🟢 YES
Hover / Traversal	`mouseenter`, `mouseleave`	❌ No	❌ No	🛑 NO
Keyboard	`keydown`, `keyup`, `keypress`	✅ Yes	✅ Yes	🟢 YES
Focus	`focusin`, `focusout`	✅ Yes	✅ Yes	🟢 YES
Focus (Legacy)	`focus`, `blur`	❌ No	❌ No	🛑 NO
Form / Input	`input`, `change`, `submit`, `reset`	✅/❌	❌ No (mostly)	🛑 NO
Resource / Window	`load`, `unload`, `error`, `resize`, `scroll`	❌ No	❌ No	🛑 NO

5. Dispatching Custom Events Across Boundaries

To allow outer applications to listen to custom component events, you must explicitly set { bubbles: true, composed: true }:

// Inside a Custom Element class:
this.dispatchEvent(new CustomEvent('cart-updated', {
  detail: { itemCount: 3, total: 99.50 },
  bubbles: true,   // Allows event to bubble up the DOM tree
  composed: true   // Allows event to cross the Shadow Boundary into outer document
}));

💻 Interactive Code Playground

Starter Code

Save this file as event-retargeting.html and open it in your browser:

Line-by-Line Code Breakdown

Line 92–104: Inside the shadow tree, clicking #btn-increment fires a native click event and dispatches a custom 'count-change' event with { bubbles: true, composed: true }.
Line 117–120: In the global document click listener, e.target is evaluated. Even though the user physically clicked <button id="btn-increment">, e.target reports <counter-widget>.
Line 122–124: e.composedPath() provides the full unmasked array of traversed nodes from the button up to window.

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL playground.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Lesson 83.8 - Event Retargeting Inspector</title>
  <style>
    body {
      font-family: system-ui, sans-serif;
      padding: 2rem;
      background: #0f172a;
      color: #f8fafc;
    }
    .layout {
      display: grid;
      grid-template-columns: 1fr 1fr;
      gap: 2rem;
      max-width: 900px;
    }
    .console-panel {
      background: #020617;
      border: 1px solid #334155;
      padding: 1rem;
      border-radius: 8px;
      font-family: 'Courier New', monospace;
      font-size: 0.85rem;
      max-height: 400px;
      overflow-y: auto;
    }
    .entry {
      margin-bottom: 0.75rem;
      padding-bottom: 0.75rem;
      border-bottom: 1px dashed #1e293b;
    }
    .target-hl { color: #38bdf8; font-weight: bold; }
    .path-hl { color: #a78bfa; }
  </style>
</head>
<body>

<h1>Shadow DOM Event Retargeting</h1>
  <p>Click the buttons inside the component to audit how <code>event.target</code> is remapped.</p>

<div>
      <h3>Document-Level Event Log:</h3>
      <div class="console-panel" id="log">Click a button to inspect event...</div>
    </div>
  </div>

constructor() {
        super();
        this.attachShadow({ mode: 'open' });
      }

connectedCallback() {
        this.shadowRoot.innerHTML = `
          <style>
            :host {
              display: inline-block;
              background: #1e293b;
              padding: 1.5rem;
              border-radius: 10px;
              border: 1px solid #334155;
            }
            .val {
              font-size: 2rem;
              font-weight: bold;
              color: #f8fafc;
              margin-bottom: 1rem;
              text-align: center;
            }
            .controls {
              display: flex;
              gap: 8px;
            }
            button {
              padding: 8px 16px;
              font-weight: bold;
              border-radius: 6px;
              border: none;
              cursor: pointer;
            }
            .btn-dec { background: #ef4444; color: white; }
            .btn-inc { background: #10b981; color: white; }
          </style>

<div class="val" id="display">0</div>
          <div class="controls">
            <button class="btn-dec" id="btn-decrement">- Decrement</button>
            <button class="btn-inc" id="btn-increment">+ Increment</button>
          </div>
        `;

const disp = this.shadowRoot.querySelector('#display');
        
        this.shadowRoot.querySelector('#btn-decrement').addEventListener('click', () => {
          this.#count--;
          disp.textContent = this.#count;
          this.#dispatchCountChange();
        });

this.shadowRoot.querySelector('#btn-increment').addEventListener('click', () => {
          this.#count++;
          disp.textContent = this.#count;
          this.#dispatchCountChange();
        });
      }

#dispatchCountChange() {
        this.dispatchEvent(new CustomEvent('count-change', {
          detail: { count: this.#count },
          bubbles: true,
          composed: true // CRUCIAL: Crosses shadow boundary
        }));
      }
    }

customElements.define('counter-widget', CounterWidget);

// 2. Global Event Listener in Outer Document
    const log = document.getElementById('log');

document.addEventListener('click', (e) => {
      // Only log if click occurred on/inside counter-widget
      if (!e.composedPath().some(el => el.tagName === 'COUNTER-WIDGET')) return;

const pathTags = e.composedPath()
        .map(node => node.nodeName || (node instanceof Document ? '#document' : 'Window'))
        .join(' ➔ ');

log.innerHTML = `
        <div class="entry">
          <div><strong>Event Type:</strong> ${e.type}</div>
          <div><strong>Retargeted Target:</strong> <span class="target-hl">&lt;${e.target.tagName.toLowerCase()}&gt;</span></div>
          <div><strong>Actual Path:</strong> <span class="path-hl">${pathTags}</span></div>
          <div><strong>Composed:</strong> ${e.composed} | <strong>Bubbles:</strong> ${e.bubbles}</div>
        </div>
      ` + log.innerHTML;
    });

// Custom Event Listener
    document.addEventListener('count-change', (e) => {
      console.log('Custom count-change received from:', e.target, 'Payload:', e.detail);
    });
  </script>
</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Composed Telemetry Event Emitter

Scenario: Build an analytics-ready video player component <telemetry-player> that dispatches structured telemetry events (media-play, media-pause, media-seek) when users interact with shadow controls.

Instructions:

Create <telemetry-player> with an open shadow root containing Play, Pause, and Skip buttons.
When buttons are clicked, dispatch custom events with bubbles: true and composed: true.
Include structured metrics in event.detail (e.g. { action: 'play', timestamp: Date.now(), positionSec: 42 }).
In the main document, register a single global telemetry listener on document.body that logs all analytics payloads with the retargeted component identifier.

🏁 Starter Code Sandbox

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

STARTER CODE SANDBOX exercise.html

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <title>Solution 83.8 - Telemetry Event Emitter</title>
  <style>
    body { font-family: system-ui, sans-serif; padding: 2rem; background: #0b0f19; color: #fff; }
    .analytics-table { width: 100%; border-collapse: collapse; margin-top: 1.5rem; }
    .analytics-table th, .analytics-table td { padding: 8px 12px; border: 1px solid #334155; text-align: left; font-size: 0.85rem; }
    .analytics-table th { background: #1e293b; color: #38bdf8; }
  </style>
</head>
<body>

  <h2>Telemetry Video Player</h2>
  <telemetry-player player-id="onboarding-vid-01"></telemetry-player>

  <h3>Telemetry Ingestion Stream</h3>
  <table class="analytics-table">
    <thead>
      <tr>
        <th>Event Target</th>
        <th>Player ID</th>
        <th>Action</th>
        <th>Position</th>
        <th>Timestamp</th>
      </tr>
    </thead>
    <tbody id="telemetry-log"></tbody>
  </table>

  <script>
    class TelemetryPlayer extends HTMLElement {
      #currentTime = 0;

      constructor() {
        super();
        this.attachShadow({ mode: 'open' });
      }

      connectedCallback() {
        const playerId = this.getAttribute('player-id') || 'unnamed-player';

        this.shadowRoot.innerHTML = `
          <style>
            :host {
              display: inline-block;
              background: #1e293b;
              padding: 1.5rem;
              border-radius: 8px;
              border: 1px solid #334155;
            }
            .controls { display: flex; gap: 8px; }
            button {
              background: #3b82f6;
              color: white;
              border: none;
              padding: 8px 16px;
              border-radius: 6px;
              font-weight: bold;
              cursor: pointer;
            }
            button:hover { background: #2563eb; }
          </style>

          <div style="margin-bottom: 12px; font-weight: 600;">Player: ${playerId}</div>
          <div class="controls">
            <button id="btn-play">▶ Play</button>
            <button id="btn-pause">⏸ Pause</button>
            <button id="btn-skip">⏩ +10s</button>
          </div>
        `;

        this.shadowRoot.querySelector('#btn-play').addEventListener('click', () => {
          this.#emitTelemetry('play');
        });

        this.shadowRoot.querySelector('#btn-pause').addEventListener('click', () => {
          this.#emitTelemetry('pause');
        });

        this.shadowRoot.querySelector('#btn-skip').addEventListener('click', () => {
          this.#currentTime += 10;
          this.#emitTelemetry('seek');
        });
      }

      #emitTelemetry(action) {
        this.dispatchEvent(new CustomEvent('player-telemetry', {
          bubbles: true,
          composed: true,
          detail: {
            playerId: this.getAttribute('player-id'),
            action: action,
            position: `${this.#currentTime}s`,
            timestamp: new Date().toLocaleTimeString()
          }
        }));
      }
    }

    customElements.define('telemetry-player', TelemetryPlayer);

    // Global Telemetry Collector at Document Level
    const logTable = document.getElementById('telemetry-log');

    document.addEventListener('player-telemetry', (event) => {
      const { playerId, action, position, timestamp } = event.detail;
      const hostTagName = event.target.tagName.toLowerCase();

      const row = document.createElement('tr');
      row.innerHTML = `
        <td style="color: #a78bfa;">&lt;${hostTagName}&gt;</td>
        <td>${playerId}</td>
        <td><strong>${action}</strong></td>
        <td>${position}</td>
        <td style="color: #94a3b8;">${timestamp}</td>
      `;
      logTable.prepend(row);
    });
  </script>
</body>
</html>

Why this works:

Custom events dispatched with composed: true escape the component's shadow root.
event.target in the document listener points to <telemetry-player>, preserving the component abstraction.
Event details provide pure business data to the analytics layer without exposing internal DOM buttons.

⚠️ Common Pitfalls

Creating Custom Events without composed: true: By default, new CustomEvent('my-event', { bubbles: true }) has composed: false. If you dispatch this event inside a shadow root, it bubbles to the #shadow-root and silently dies, never reaching document listeners!
Relying on event.target for Internal Node Inspection in Light DOM: In the light DOM, e.target is always the host element. Do not write if (e.target.id === 'inner-btn') in parent document listeners; use e.composedPath() or custom event detail data instead.

💡 Pro Tips

Use focusin instead of focus: The legacy focus and blur events have composed: false and do not cross shadow boundaries. The standard focusin and focusout events have composed: true and bubble cleanly through all shadow roots.
Closed Shadow Roots and composedPath(): If any shadow root in the path is mode: 'closed', composedPath() stops at that boundary, safeguarding private internal hierarchies.

📌 Key Takeaways

Event Retargeting modifies event.target when events cross a shadow boundary so outer listeners see the Shadow Host element.
event.composedPath() returns an array of all DOM nodes the event traversed through, including shadow nodes (for open roots).
Standard user interaction events (click, keydown, focusin) are composed: true by default.
Custom events require { bubbles: true, composed: true } to escape a Shadow DOM boundary.
mouseenter, mouseleave, focus, and blur are composed: false and do not leave their shadow root.
--

⭐ LEARN: HTML 🌟 ⚔️ QUIZ BATTLE ARENA // ACTIVE

? Question 1 / 3

What is the value of `event.target` when a user clicks an internal `<button>` inside an open shadow root of `<user-card>`, and the event is captured by `document.body.addEventListener('click', ...)`?

Topic: HTML Fundamentals

? Question 2 / 3

Which configuration must be passed to `CustomEvent` to allow it to bubble up and cross a shadow root into the main document?

Topic: HTML Fundamentals

? Question 3 / 3

Why does a `focus` event listener on `document` fail to detect when an `<input>` inside a Shadow DOM component receives keyboard focus?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

1. The Event Retargeting Algorithm

2. event.target vs event.composedPath()

3. The composed Flag

4. Standard DOM Event Composition Matrix

5. Dispatching Custom Events Across Boundaries

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Composed Telemetry Event Emitter

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

What is the value of event.target when a user clicks an internal <button> inside an open shadow root of <user-card>, and the event is captured by document.body.addEventListener('click', ...)?

Which configuration must be passed to CustomEvent to allow it to bubble up and cross a shadow root into the main document?

Why does a focus event listener on document fail to detect when an <input> inside a Shadow DOM component receives keyboard focus?

2. `event.target` vs `event.composedPath()`

3. The `composed` Flag

What is the value of `event.target` when a user clicks an internal `<button>` inside an open shadow root of `<user-card>`, and the event is captured by `document.body.addEventListener('click', ...)`?

Which configuration must be passed to `CustomEvent` to allow it to bubble up and cross a shadow root into the main document?

Why does a `focus` event listener on `document` fail to detect when an `<input>` inside a Shadow DOM component receives keyboard focus?