@supersoniks/concorde 5.1.1 → 5.1.3

package/docs/src/docs/decorators/handle.md

@@ -0,0 +1,119 @@
+# @handle
+
+`@handle(...keys)` calls the decorated method each time a publisher assigns one of up to three store paths, with one typed argument per key. Nothing is stored on the component: use it for derived values and side effects, and [@subscribe](/docs/decorators/subscribe) when you only need the value. See [Data flow](/docs/getting-started/dataFlow) for the overall model.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { handle, Skip } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+
+const cockpitKey = new DataProviderKey&lt;{ altitude: number }&gt;("cockpit");
+
+@handle(cockpitKey.altitude)
+onAltitude(feet: number) {
+  this.meters = Math.round(feet * 0.3048);
+}
+  </template>
+</sonic-code>
+
+## Basic usage
+
+The method runs once with the current value when the component connects, then on **every** assignment, including `null` and `undefined`. Below, each climb assigns a new altitude and the method derives meters and flight level.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-handle"></docs-demo-sources>
+    <demo-handle></demo-handle>
+  </template>
+</sonic-code>
+
+## Dynamic path
+
+`${prop}` placeholders resolve from properties of the same component; when one changes, the method is called with the value at the new path. Rules: [Dynamic paths](/docs/misc/dynamic-path).
+
+<sonic-code language="typescript">
+  <template>
+const personKey = new DataProviderKey&lt;OnBoard, { seatIndex: number }&gt;(
+  "demoOnBoard.${seatIndex}",
+);
+
+@property({ type: Number }) seatIndex = 0;
+
+@handle(personKey)
+onPerson(person: OnBoard | null) {
+  this.announcement = person ? `${person.name}, please proceed to gate B12.` : "";
+}
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-handle-dynamic"></docs-demo-sources>
+    <demo-handle-dynamic></demo-handle-dynamic>
+  </template>
+</sonic-code>
+
+## Multiple keys
+
+Pass up to three [DataProviderKey](/docs/misc/dataProviderKey) values; the method receives one argument per key, in the same order. Any assignment to any key calls it, so other arguments may still be `null`.
+
+<sonic-code language="typescript">
+  <template>
+const flightKey = new DataProviderKey&lt;{ status: string; gate: string }&gt;("flight");
+const weatherKey = new DataProviderKey&lt;{ turbulence: boolean }&gt;("weather");
+
+@handle(flightKey.status, weatherKey.turbulence)
+onConditions(status: string, turbulence: boolean) {
+  this.seatbeltSign = status === "boarding" || turbulence === true;
+}
+  </template>
+</sonic-code>
+
+## Wait for all values
+
+With `waitForAllDefined: true`, the method runs only once every key holds a value other than `null` or `undefined`.
+
+<sonic-code language="typescript">
+  <template>
+@handle(flightKey.gate, passengerKey.name, { waitForAllDefined: true })
+announce(gate: string, name: string) {
+  this.message = `${name}, please proceed to gate ${gate}.`;
+}
+  </template>
+</sonic-code>
+
+## Skip values
+
+`skip` lists categories of values that must not call the method. A category is a named test, not a value to compare.
+
+| Category | Matches |
+|----------|---------|
+| `Skip.Nullish` | `null` or `undefined` |
+| `Skip.EmptyString` | `""` |
+| `Skip.EmptyObject` | `{}` (arrays excluded) |
+| `Skip.EmptyArray` | `[]` |
+
+<sonic-code language="typescript">
+  <template>
+@handle(passengerKey, { skip: [Skip.Nullish, Skip.EmptyObject] })
+onPassenger(passenger: Passenger) {
+  // not called while the publisher still holds {} (not loaded yet)
+  this.displayName = passenger.name;
+}
+  </template>
+</sonic-code>
+
+To reject a specific value, return early inside the method.
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `key` (1 to 3) | `DataProviderKey<T, U>` | Paths to watch; the method receives one value per key, in order |
+| `options.waitForAllDefined` | `boolean` (default `false`) | Call the method only when no value is `null` or `undefined` |
+| `options.skip` | `Skip[]` (default none) | Do not call the method when any value matches one of these categories |
+| `options.skipEmptyPlaceholder` | `boolean` (default `false`) | Treat a placeholder resolved to `""` as not ready |
+
+`options`, if present, is the last argument. `@handle` replaces the deprecated [@onAssign](/docs/decorators/on-assign): `@onAssign("a", "b")` is `@handle(keyA, keyB, { waitForAllDefined: true })`.

package/docs/src/docs/decorators/on-assign.md

@@ -0,0 +1,63 @@
+# @onAssign
+
+Legacy decorator that calls a method with the values at one or more string paths of the store, once all of them are defined. For new code, use [@handle](/docs/decorators/handle) with `{ waitForAllDefined: true }`: same behaviour, with typed `DataProviderKey` paths.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { onAssign } from "@supersoniks/concorde/decorators";
+
+@onAssign("passenger", "passengerSettings")
+onReady(passenger: Passenger, settings: Settings) {}
+  </template>
+</sonic-code>
+
+## Wait for every path
+
+The method is called only when every path holds a value other than `null` or `undefined`, with the values in the order of the paths. After that, each assignment calls it again with the latest values. Subscriptions start after `connectedCallback` and stop in `disconnectedCallback`.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-on-assign"></docs-demo-sources>
+    <demo-on-assign></demo-on-assign>
+  </template>
+</sonic-code>
+
+## Dynamic path
+
+Paths accept `${prop}` placeholders resolved on the host. While a placeholder is `null` or `undefined`, that path is unsubscribed. Write the paths as plain strings, not template literals. Rules: [Dynamic path placeholders](/docs/misc/dynamic-path).
+
+<sonic-code language="typescript">
+  <template>
+@property({ type: Number }) seat = 0;
+
+@onAssign("passengers.${seat}", "passengerSettings.${seat}")
+onSeat(passenger: Passenger, settings: Settings) {}
+  </template>
+</sonic-code>
+
+## Migrate to @handle
+
+<sonic-code language="typescript">
+  <template>
+// Before
+@onAssign("passenger", "passengerSettings")
+onReady(passenger: any, settings: any) {}
+
+// After
+const passengerKey = new DataProviderKey&lt;Passenger&gt;("passenger");
+const settingsKey = new DataProviderKey&lt;Settings&gt;("passengerSettings");
+
+@handle(passengerKey, settingsKey, { waitForAllDefined: true })
+onReady(passenger: Passenger, settings: Settings) {}
+  </template>
+</sonic-code>
+
+`@handle` accepts up to three keys. For more paths, keep `@onAssign` or split the logic into several `@handle` methods.
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `...paths` | `string[]` | Dot paths in the store (`"flights.0.status"`), optionally with `${prop}` placeholders; the method receives one argument per path, in order |

package/docs/src/docs/decorators/patch.md

@@ -0,0 +1,44 @@
+# @patch
+
+Sends the value of a publisher as the body of a `PATCH` request, to update part of a resource, and stores the response in an `ApiResult<T>` property. It takes the same arguments, options and `send(component)` handle as [@post](/docs/decorators/post); only the HTTP method differs.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { patch, type ApiResult } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
+  </template>
+</sonic-code>
+
+## Basic usage
+
+The body holds only the fields to change, here a gate change for flight CN 001.
+
+<sonic-code language="typescript">
+  <template>
+type Flight = { flight: string; route: string; gate: string };
+
+const gateChangeKey = new DataProviderKey&lt;Partial&lt;Flight&gt;&gt;("gateChange");
+
+@patch(new Endpoint&lt;Flight&gt;("flights/CN001"), gateChangeKey)
+@state()
+payload?: ApiResult&lt;Flight&gt;;
+
+moveToB12() {
+  set(gateChangeKey, { gate: "B12" }); // sends the PATCH
+}
+  </template>
+</sonic-code>
+
+Triggers, the `send` method decorator and every option are described on [@post](/docs/decorators/post).
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `endpoint` | `Endpoint<T>` | Resource path and response type |
+| `bodyKey` | `DataProviderKey<B>` | Publisher read as the partial body |
+| `configurationKey` | `DataProviderKey<APIConfiguration>` (optional) | API configuration publisher. Default: HTML scope |
+| `options` | `PatchOptions` | Same as [@post options](/docs/decorators/post) |

package/docs/src/docs/decorators/post.md

@@ -0,0 +1,134 @@
+# @post
+
+Sends the value of a publisher as the body of a `POST` request and stores the response in an `ApiResult<T>` property. Pass an [Endpoint](/docs/misc/endpoint) and a [DataProviderKey](/docs/misc/dataProviderKey) for the body; the request runs on connect and again whenever the body changes. [@put](/docs/decorators/put) and [@patch](/docs/decorators/patch) work the same way.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { post, type ApiResult } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
+
+type SignUp = { email: string; password: string };
+type CrewMember = { id: number; email: string };
+
+const signUpKey = new DataProviderKey&lt;SignUp&gt;("crewSignUp");
+
+@post(new Endpoint&lt;CrewMember&gt;("api/register"), signUpKey)
+@state()
+payload?: ApiResult&lt;CrewMember&gt;;
+  </template>
+</sonic-code>
+
+## Basic usage
+
+The property is `undefined` until a response arrives, then holds `request` · `response` · the typed `result`. Each body mutation sends a new request; mutations in the same frame are coalesced into one. The demo posts to the local mock `POST /docs-mock-api/api/register`.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-api-post"></docs-demo-sources>
+    <demo-api-post></demo-api-post>
+  </template>
+</sonic-code>
+
+## Method form
+
+On a method, the decorator calls it with the full `ApiResult<T>` after each request instead of assigning a property.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-api-post-method"></docs-demo-sources>
+    <demo-api-post-method></demo-api-post-method>
+  </template>
+</sonic-code>
+
+## Sending again
+
+Keep the decorator in a constant to call `send(component)`. It reads the current body and returns a `Promise<ApiResult<T> | undefined>` resolved once the request completes. Use it for "Save" or "Retry" buttons.
+
+<sonic-code language="typescript">
+  <template>
+const signUp = post(new Endpoint&lt;CrewMember&gt;("api/register"), signUpKey);
+
+@signUp
+@state()
+payload?: ApiResult&lt;CrewMember&gt;;
+
+async retry() {
+  const payload = await signUp.send(this);
+  console.log(payload?.result?.id);
+}
+  </template>
+</sonic-code>
+
+The `send` method decorator does the same around a method. It runs after the method by default (waiting for a returned Promise); `{ when: "before" }` sends first.
+
+<sonic-code language="typescript">
+  <template>
+import { send } from "@supersoniks/concorde/decorators";
+
+@send(signUp)
+async confirmCheckIn() {
+  // Validate the check-in form, then the POST is sent.
+}
+  </template>
+</sonic-code>
+
+## Manual trigger
+
+Set `autoPostOnBodyMutation: false` when the body is edited field by field (a check-in form) and the request must only go out on `send()` or `triggerKey`. A `triggerKey` publisher lets another component resend: calling `invalidate()` on it sends the current body.
+
+<sonic-code language="typescript">
+  <template>
+const submitKey = new DataProviderKey&lt;number&gt;("checkInSubmit");
+
+@post(checkInEndpoint, checkInKey, {
+  autoPostOnBodyMutation: false,
+  triggerKey: submitKey,
+})
+@state()
+payload?: ApiResult&lt;CheckIn&gt;;
+
+// Anywhere: dp(submitKey).invalidate();
+  </template>
+</sonic-code>
+
+By default (`skipIfBodyMissing: true`) nothing is sent while the body is `null` or `undefined`. `refetchEveryMs` repeats the request at a fixed interval after each response; use it only when repeating the operation is safe.
+
+## API configuration
+
+Without a configuration key, `serviceURL` and credentials come from the HTML scope, as with [@get](/docs/decorators/get). Pass a `DataProviderKey<APIConfiguration>` as third argument to read them from a publisher; options then move to the fourth argument. See [API configuration](/docs/misc/api-configuration).
+
+<sonic-code language="typescript">
+  <template>
+@post(signUpEndpoint, signUpKey, apiConfigurationKey, { skipIfBodyMissing: false })
+  </template>
+</sonic-code>
+
+## Dynamic path
+
+Placeholders in the endpoint (`${flight}`) are read from the host component; changing the property sends the same body to the new URL. See [Dynamic paths](/docs/misc/dynamic-path).
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-api-post-dynamic"></docs-demo-sources>
+    <demo-api-post-dynamic></demo-api-post-dynamic>
+  </template>
+</sonic-code>
+
+## API reference
+
+`post(endpoint, bodyKey, configurationKey?, options?)` returns a decorator for a property or a method, with a `send(component)` method.
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `endpoint` | `Endpoint<T>` | Path and response type. Supports `${prop}` placeholders |
+| `bodyKey` | `DataProviderKey<B>` | Publisher read as request body |
+| `configurationKey` | `DataProviderKey<APIConfiguration>` (optional) | API configuration publisher. Default: HTML scope |
+| `options.autoPostOnBodyMutation` | `boolean` (default `true`) | Send on connect and after each body mutation |
+| `options.skipIfBodyMissing` | `boolean` (default `true`) | Skip while the body is `null` or `undefined` |
+| `options.triggerKey` | `DataProviderKey<unknown>` | Publisher whose `invalidate()` resends |
+| `options.refetchEveryMs` | `number` (default `0`, off) | Resend interval in ms after each response |
+| `options.skipEmptyPlaceholder` | `boolean` (default `false`) | Treat a placeholder resolved to `""` as not ready |
+| `send(handle, { when })` | `"after"` (default) or `"before"` | Method decorator sending after or before the method |

package/docs/src/docs/decorators/publish.md

@@ -0,0 +1,56 @@
+# @publish
+
+`@publish(key)` writes a component property to one path of the store: every assignment to the property is published there. It never reads back from the store; it is the inverse of [@subscribe](/docs/decorators/subscribe). See [Data flow](/docs/getting-started/dataFlow) for the overall model.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { publish } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+
+type CheckIn = { passenger: string; seat: string };
+const checkInKey = new DataProviderKey&lt;CheckIn&gt;("checkIn");
+
+@publish(checkInKey.passenger)
+@state()
+passenger = "Ada Lindqvist";
+  </template>
+</sonic-code>
+
+## Basic usage
+
+Each assignment calls `set()` on the publisher at the [DataProviderKey](/docs/misc/dataProviderKey) path. **On connect, a defined property value is published immediately**, so the initializer overwrites what the store held. Leave the property `undefined` to keep the store value. To read and write the same path, use [@bind](/docs/decorators/bind) with `reflect: true`.
+
+The check-in form below publishes `passenger` and `seat`; the boarding pass reads them back with [sub()](/docs/directives/sub).
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-publish"></docs-demo-sources>
+    <demo-publish></demo-publish>
+  </template>
+</sonic-code>
+
+## Dynamic path
+
+`${prop}` placeholders resolve from properties of the same component. When a placeholder changes, the property is published to the new path. While it is `null` or `undefined`, nothing is published. Rules and `skipEmptyPlaceholder`: [Dynamic paths](/docs/misc/dynamic-path).
+
+<sonic-code language="typescript">
+  <template>
+@property({ type: Number }) seatIndex = 0;
+
+@publish(
+  new DataProviderKey&lt;string, { seatIndex: number }&gt;("onBoard.${seatIndex}.seat"),
+  { skipEmptyPlaceholder: true },
+)
+@state()
+seat = "1A";
+  </template>
+</sonic-code>
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `key` | `DataProviderKey<T, U>` | Path to write. `U` lists the host properties used by `${…}` placeholders |
+| `options.skipEmptyPlaceholder` | `boolean` (default `false`) | Treat a placeholder resolved to `""` as not ready |

package/docs/src/docs/decorators/put.md

@@ -0,0 +1,51 @@
+# @put
+
+Sends the value of a publisher as the body of a `PUT` request, to replace a resource, and stores the response in an `ApiResult<T>` property. It takes the same arguments, options and `send(component)` handle as [@post](/docs/decorators/post); only the HTTP method differs.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { put, type ApiResult } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
+  </template>
+</sonic-code>
+
+## Basic usage
+
+The full passenger record is sent on connect and after each body mutation. Placeholders such as `${passengerId}` are resolved on the host component.
+
+<sonic-code language="typescript">
+  <template>
+type Passenger = { name: string; flight: string; seat: string };
+
+const passengerKey = new DataProviderKey&lt;Passenger&gt;("passengerForm");
+const savePassenger = put(
+  new Endpoint&lt;Passenger, { passengerId: string }&gt;("passengers/${passengerId}"),
+  passengerKey,
+  { autoPostOnBodyMutation: false },
+);
+
+@property() passengerId = "ada-lindqvist";
+
+@savePassenger
+@state()
+payload?: ApiResult&lt;Passenger&gt;;
+
+async save() {
+  await savePassenger.send(this);
+}
+  </template>
+</sonic-code>
+
+Triggers, the `send` method decorator and every option are described on [@post](/docs/decorators/post).
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `endpoint` | `Endpoint<T>` | Resource path and response type |
+| `bodyKey` | `DataProviderKey<B>` | Publisher read as the full replacement body |
+| `configurationKey` | `DataProviderKey<APIConfiguration>` (optional) | API configuration publisher. Default: HTML scope |
+| `options` | `PutOptions` | Same as [@post options](/docs/decorators/post) |

package/docs/src/docs/decorators/subscribe.md

@@ -0,0 +1,87 @@
+# @subscribe
+
+`@subscribe(key)` keeps a component property in sync with one path of the store: when a publisher assigns that path, the property updates and the component re-renders. It is read-only; use [@publish](/docs/decorators/publish) to write and [sub()](/docs/directives/sub) to read inside a template. See [Data flow](/docs/getting-started/dataFlow) for the overall model.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { subscribe } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+
+type Cockpit = { altitude: number };
+const cockpitKey = new DataProviderKey&lt;Cockpit&gt;("cockpit");
+
+@subscribe(cockpitKey.altitude)
+@state()
+altitude = 0;
+  </template>
+</sonic-code>
+
+## Static path
+
+The key is a [DataProviderKey](/docs/misc/dataProviderKey): the property type must match `T` at that path. Add `@state()` so Lit re-renders. Until the publisher holds a value, the property keeps its initializer.
+
+<sonic-code language="typescript">
+  <template>
+type Flight = { code: string; gate: string; status: string };
+const flightKey = new DataProviderKey&lt;Flight&gt;("flight");
+
+@subscribe(flightKey)
+@state()
+flight: Flight | null = null;
+  </template>
+</sonic-code>
+
+## Dynamic path
+
+`${prop}` placeholders resolve from properties of the same component. Declare them in the key's second generic so TypeScript requires them on the host. When `seatIndex` changes, the path is resolved again and `person` refreshes; while the placeholder is `null` or `undefined`, the subscription is inactive. Resolution rules: [Dynamic paths](/docs/misc/dynamic-path).
+
+<sonic-code language="typescript">
+  <template>
+type OnBoard = { name: string; role: string; seat: string };
+const personKey = new DataProviderKey&lt;OnBoard, { seatIndex: number }&gt;(
+  "demoOnBoard.${seatIndex}",
+);
+
+@property({ type: Number }) seatIndex = 0;
+
+@subscribe(personKey)
+@state()
+person: OnBoard | null = null;
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-subscribe-dynamic"></docs-demo-sources>
+    <demo-subscribe-dynamic></demo-subscribe-dynamic>
+  </template>
+</sonic-code>
+
+## Ancestor scope
+
+Inside a list row or a `dataProvider` wrapper, read the path from the closest ancestor with [@ancestorAttribute](/docs/decorators/ancestor-attribute), then use it as the placeholder.
+
+<sonic-code language="typescript">
+  <template>
+const rowKey = new DataProviderKey&lt;OnBoard, { dataProvider: string | null }&gt;(
+  "${dataProvider}",
+);
+
+@ancestorAttribute("dataProvider")
+dataProvider: string | null = null;
+
+@subscribe(rowKey)
+@state()
+person: OnBoard | null = null;
+  </template>
+</sonic-code>
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `key` | `DataProviderKey<T, U>` | Path to read. `U` lists the host properties used by `${…}` placeholders |
+
+The decorated property is typed `T` (optionally `| null` or `| undefined`). The subscription starts when the component connects and stops when it disconnects.

package/docs/src/docs/decorators/wait-for-ancestors.md

@@ -0,0 +1,76 @@
+# @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` |