Shadow Slots, Events, and Focus Contracts

Working case

A shared case-review panel accepts a heading, an action label, and a help link from the page. One host replaces the help link after a permission change; another reorders panels while the reviewer is using a keyboard. The component must not clone the supplied link and then forget updates. It emits a case-select event carrying a stable case ID, but no private note text. An analytics listener outside the shadow root receives the event; a local keydown inside does not become an application command unless the component deliberately emits one.

Implementation boundary

function caseSelectEvent(caseId) {
  return new CustomEvent('case-select', { bubbles: true, composed: true, detail: { caseId } });
}
const selection = caseSelectEvent(47);
console.log(selection.bubbles && selection.composed && selection.detail.caseId === 47);
// Output: true

Document named slots and fallback content. Observe slot changes only for work that depends on assigned nodes, and avoid rewriting the host-owned nodes. Emit a task event with bubbles and composed set when outside application code needs it; include a small immutable detail object and let the host perform authorization. Internal implementation events stay internal. Restore focus to a meaningful control after closing an internal overlay. Test the composed path rather than relying on an internal selector from host code. An open root aids integration tests, but it is not a security boundary; a closed root is not a data-protection mechanism either.

Cost and boundaries

Slot assignment and a small custom event are cheap. Work performed on every slotchange may not be: scanning all descendants across n mounted panels can become O(total projected nodes) per update. Cache only stable derived information and invalidate it when slot content changes. Retaining old assigned nodes in a component field can keep detached private content in memory. Focus restoration requires a stable owner reference, which should be cleared when the host removes the panel. Monitor event volume when pointer movement or progress updates cross the boundary.

Failure trace

Replace a slotted help link while the panel remains mounted. Its current destination must appear without rebuilding the panel. Fire a composed case-select event and prove the host receives the correct case ID, while a deliberately internal event does not escape. Move focus into an overlay, remove the panel, and ensure no detached node receives focus afterward. Try keyboard, touch, and a screen reader; visual slot placement alone cannot prove reading order. Change the selected account and reject an old case-select event from an inactive panel.

Verification

Host-owned slot nodes can change without a rebuild.
Only intentional events cross the shadow boundary.
Focus never returns to a removed panel.

Practice drill

Create a panel with title and actions slots. Supply a server-rendered title and a normal link as fallback content. Replace the action slot during a permission change, then emit a versioned selection event. Record the event detail seen by the host and keep private note text out of it. With JavaScript disabled, the title and link should still be useful; with JavaScript enabled, focus and event behavior should remain predictable after the panel moves.

Decision note

Slots share presentation space, while events and focus define the actual integration boundary.

Common Mistakes

Reading an internal button by selector from the host.
Sending private record text in event detail.
Treating a closed shadow root as access control.

Connected practice

Build Project: interoperable case-decision control and review Web Development: components and compatibility quiz.