# @awaitConnectedAncestors

Delays a component's `connectedCallback` until its matching ancestors are defined and connected, so context they set up (a `dataProvider`, a publisher, a fetched payload) is ready when the child starts. Pair it with `@dispatchConnectedEvent` on the ancestors, which signals readiness.

## Import

<sonic-code language="typescript">
  <template>
import {
  awaitConnectedAncestors,
  dispatchConnectedEvent,
} from "@supersoniks/concorde/decorators";

@customElement("flight-scope")
@dispatchConnectedEvent()
export class FlightScope extends LitElement {}

@customElement("gate-panel")
@awaitConnectedAncestors("flight-scope")
export class GatePanel extends LitElement {}
  </template>
</sonic-code>

## Wait for an ancestor

Arguments are CSS selectors tested with `element.matches()` on each ancestor, across shadow roots. Here the parent element is not defined yet: the child stays uninitialized until you register it.

<sonic-code>
  <template>
    <docs-demo-sources for="demo-wait-ancestors-section"></docs-demo-sources>
    <demo-wait-ancestors-section></demo-wait-ancestors-section>
  </template>
</sonic-code>

## Several ancestors

With several selectors, the child waits for every matching ancestor. Register both to initialize it, in any order.

<sonic-code>
  <template>
    <docs-demo-sources for="demo-wait-ancestors-multi-section"></docs-demo-sources>
    <demo-wait-ancestors-multi-section></demo-wait-ancestors-multi-section>
  </template>
</sonic-code>

## Ancestor already connected

When the ancestor is already connected, or no ancestor matches, the child initializes immediately.

<sonic-code>
  <template>
    <docs-demo-sources for="demo-wait-ancestors-ready-section"></docs-demo-sources>
    <demo-wait-ancestors-ready-section></demo-wait-ancestors-ready-section>
  </template>
</sonic-code>

## Signal readiness

`@dispatchConnectedEvent()` dispatches a bubbling `sonic-connected` event (exported as `CONNECTED`) at the end of the ancestor's `connectedCallback`. You can listen to it anywhere:

<sonic-code language="typescript">
  <template>
import { CONNECTED } from "@supersoniks/concorde/decorators";

document.addEventListener(CONNECTED, (e) => console.log("ready:", e.target));
  </template>
</sonic-code>

Elements without a hyphen in their tag name count as connected. A custom element ancestor that never dispatches the event releases the child after a **5 second** timeout, so decorate the ancestors you wait for.

## API reference

| Decorator | Argument | Description |
|-----------|----------|-------------|
| `@awaitConnectedAncestors` | `...selectors: string[]` | Class decorator. CSS selectors of the ancestors to wait for; with no selector, the class is left unchanged |
| `@dispatchConnectedEvent` | none | Class decorator. Dispatches `CONNECTED` (`"sonic-connected"`, bubbles) after `connectedCallback` |