@supersoniks/concorde 5.1.0 → 5.1.2

package/docs/hubs/decorators.html

@@ -0,0 +1,443 @@
+<!DOCTYPE html>
+<html lang="en" data-doc-url="https://concorde.supersoniks.org/hubs/decorators.html" data-doc-id="hubs/decorators">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Concorde decorators reference — Concorde by Supersoniks</title>
+  <meta name="description" content="Hub for all Concorde Lit decorators: @get @post @put @patch @subscribe @publish @bind @handle and related. Use this page when asking about any decorator.">
+  <meta name="keywords" content="decorator, @get, @post, @put, @patch, @subscribe, @publish, @bind, @handle, ApiResult, Endpoint, DataProviderKey">
+  <meta name="concorde-doc-id" content="hubs/decorators">
+  <link rel="canonical" href="https://concorde.supersoniks.org/hubs/decorators.html">
+</head>
+<body>
+  <header>
+    <p><a href="/docs/index.html">Concorde documentation</a></p>
+  </header>
+  <main>
+    <article>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde documentation — Concorde decorators reference</strong>. Hub for all Concorde Lit decorators: @get @post @put @patch @subscribe @publish @bind @handle and related. Use this page when asking about any decorator. <span>Doc ID: <code>hubs/decorators</code>. Keywords: decorator, @get, @post, @put, @patch, @subscribe, @publish, @bind, @handle, ApiResult, Endpoint, DataProviderKey. URL: <a href="https://concorde.supersoniks.org/hubs/decorators.html">https://concorde.supersoniks.org/hubs/decorators.html</a>.</span></p>
+      <section id="docs-decorators-ancestor-attribute" data-doc-id="docs/decorators/ancestor-attribute">
+  <h2><a href="/docs/decorators/ancestor-attribute">@ancestorAttribute</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/decorators/ancestor-attribute</code> · <a href="/docs/decorators/ancestor-attribute">full page</a></p>
+  <p>Copies the value of an attribute from the nearest element that carries it (the host itself, then its ancestors, across shadow roots) into a class property. Use it to pick up a scope such as dataProvid</p>
+  <pre class="doc-excerpt">@ancestorAttribute
+
+Copies the value of an attribute from the nearest element that carries it (the host itself, then its ancestors, across shadow roots) into a class property. Use it to pick up a scope such as dataProvider without passing it down by hand, typically to feed a dynamic key of @subscribe.
+
+Import
+
+import { ancestorAttribute } from &quot;@supersoniks/concorde/decorators&quot;;
+
+@ancestorAttribute(&quot;dataProvider&quot;)
+dataProvider: string | null = null;
+
+Read once at connect
+
+By default the value is read once, just before the component's connectedCallback, and never updated. The closest element with the attribute wins. If no ancestor has it, the property keeps its initial value.
+
+An attribute present without a value ( ) resolves to &quot;&quot;. A camelCase name also matches its lowercase form (dataProvider and dataprovider).
+
+Follow DOM changes
+
+With { dynamic: true }, the property stays in sync while the component is connected: when an ancestor changes the attribute, when a closer ancestor gains or loses it, and when the component is moved. When no ancestor has the attribute, the property becomes null. Add @state() so Lit re-renders on each assignment.
+
+@ancestorAttribute(&quot;dataProvider&quot;, { dyn</pre>
+</section>
+<section id="docs-decorators-auto-subscribe" data-doc-id="docs/decorators/auto-subscribe">
+  <h2><a href="/docs/decorators/auto-subscribe">@autoSubscribe</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/decorators/auto-subscribe</code> · <a href="/docs/decorators/auto-subscribe">full page</a></p>
+  <p>Legacy decorator that re-runs a method whenever one of the store values it reads is assigned. For new code, prefer @subscribe with a DataProviderKey: dependencies are explicit and typed.</p>
+  <pre class="doc-excerpt">@autoSubscribe
+
+Legacy decorator that re-runs a method whenever one of the store values it reads is assigned. For new code, prefer @subscribe with a DataProviderKey: dependencies are explicit and typed.
+
+Import
+
+import { autoSubscribe } from &quot;@supersoniks/concorde/decorators&quot;;
+import { get } from &quot;@supersoniks/concorde/utils&quot;;
+
+@autoSubscribe()
+updateDisplay() {
+  this.total = get(passengersKey) + get(crewKey);
+}
+
+Tracked reads
+
+The method runs once after connectedCallback. Every store value read during that run becomes a dependency; assigning any of them runs the method again. Write the result to a @state() property (or call requestUpdate()) so the component re-renders.
+
+Notes
+
+- Several assignments in the same task trigger a single re-run (batched with queueMicrotask).
+- Keep reads unconditional: a value read only behind a condition becomes a dependency the first time that branch runs.
+- Subscriptions are removed in disconnectedCallback.
+
+API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| none | | @autoSubscribe() takes no argument; apply it to a method of a custom element |</pre>
+</section>
+<section id="docs-decorators-bind" data-doc-id="docs/decorators/bind">
+  <h2><a href="/docs/decorators/bind">@bind</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/decorators/bind</code> · <a href="/docs/decorators/bind">full page</a></p>
+  <p>Keeps a class property in sync with a path of the DataProvider store, in both directions when needed. Pass a dot-notation string or a DataProviderKey; add { reflect: true } to push local writes back t</p>
+  <pre class="doc-excerpt">@bind
+
+Keeps a class property in sync with a path of the DataProvider store, in both directions when needed. Pass a dot-notation string or a DataProviderKey; add { reflect: true } to push local writes back to the store. For read-only sync prefer @subscribe, and see Data flow for the overall model.
+
+Import
+
+import { bind } from &quot;@supersoniks/concorde/decorators&quot;;
+
+@bind(&quot;flight.gate&quot;)
+@state()
+gate = &quot;&quot;;
+
+Basic usage
+
+The first path segment is the data provider id, the rest is dot notation (array items use a numeric index: passengers.0). The property updates each time the store value changes. Add @state() so Lit re-renders.
+
+Typed key
+
+With a DataProviderKey , TypeScript checks that the property type matches T at that path.
+
+import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+
+type Flight = { flight: string; gate: string; boarded: number };
+const flightKey = new DataProviderKey&amp;lt;Flight&amp;gt;(&quot;flight&quot;);
+
+@bind(flightKey.boarded, { reflect: true })
+@state()
+boarded = 0;
+
+Reflect
+
+By default (reflect: false) the binding is one-way: assigning the property does not touch the store. With reflect: true, each assignment calls set() on the publisher, so every other subsc</pre>
+</section>
+<section id="docs-decorators-get" data-doc-id="docs/decorators/get">
+  <h2><a href="/docs/decorators/get">@get</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/decorators/get</code> · <a href="/docs/decorators/get">full page</a></p>
+  <p>@get(endpoint) runs an HTTP GET on an Endpoint and stores the full ApiResult&lt;T&gt; in a property, or passes it to a method. It runs again when the endpoint's placeholders or the API configuration change,</p>
+  <pre class="doc-excerpt">@get
+
+@get(endpoint) runs an HTTP GET on an Endpoint and stores the full ApiResult  in a property, or passes it to a method. It runs again when the endpoint's placeholders or the API configuration change, and on demand through refetch. For writes, see @post, @put and @patch.
+
+Import
+
+import { get, Endpoint, type ApiResult } from &quot;@supersoniks/concorde/decorators&quot;;
+
+type FlightBoard = { flights: Flight[] };
+const departuresEndpoint = new Endpoint&amp;lt;FlightBoard&amp;gt;(&quot;flights?direction=departures&quot;);
+
+@get(departuresEndpoint)
+@state()
+departures?: ApiResult&amp;lt;FlightBoard&amp;gt;;
+
+Property
+
+The property is undefined until the first response, then holds result (typed T), response (the HTTP response) and request. It is reset to undefined when the component disconnects.
+
+Without a configuration key, serviceURL and the token are read from the HTML scope: place the component under an element that sets them (see API configuration). The GET waits until serviceURL is available.
+
+Method
+
+Decorate a method to receive the ApiResult  after each GET instead of storing it.
+
+@get(departuresEndpoint)
+onDepartures(payload?: ApiResult&amp;lt;FlightBoard&amp;gt;) {
+  this.boarding = payload?.result?.flights.filter(</pre>
+</section>
+<section id="docs-decorators-handle" data-doc-id="docs/decorators/handle">
+  <h2><a href="/docs/decorators/handle">@handle</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/decorators/handle</code> · <a href="/docs/decorators/handle">full page</a></p>
+  <p>@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</p>
+  <pre class="doc-excerpt">@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 when you only need the value. See Data flow for the overall model.
+
+Import
+
+import { handle, Skip } from &quot;@supersoniks/concorde/decorators&quot;;
+import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+
+const cockpitKey = new DataProviderKey&amp;lt;{ altitude: number }&amp;gt;(&quot;cockpit&quot;);
+
+@handle(cockpitKey.altitude)
+onAltitude(feet: number) {
+  this.meters = Math.round(feet  0.3048);
+}
+
+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.
+
+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.
+
+const personKey = new DataProviderKey&amp;lt;OnBoard, { seatIndex: number }&amp;gt;(
+  &quot;demoOnBoard.${seatIndex}&quot;,
+);
+
+@property({ type: Number }) seatIndex = 0;</pre>
+</section>
+<section id="docs-decorators-on-assign" data-doc-id="docs/decorators/on-assign">
+  <h2><a href="/docs/decorators/on-assign">@onAssign</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/decorators/on-assign</code> · <a href="/docs/decorators/on-assign">full page</a></p>
+  <p>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 with { waitForAllDefined: true }: same behaviour,</p>
+  <pre class="doc-excerpt">@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 with { waitForAllDefined: true }: same behaviour, with typed DataProviderKey paths.
+
+Import
+
+import { onAssign } from &quot;@supersoniks/concorde/decorators&quot;;
+
+@onAssign(&quot;passenger&quot;, &quot;passengerSettings&quot;)
+onReady(passenger: Passenger, settings: Settings) {}
+
+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.
+
+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.
+
+@property({ type: Number }) seat = 0;
+
+@onAssign(&quot;passengers.${seat}&quot;, &quot;passengerSettings.${seat}&quot;)
+onSeat(passenger: Passenger, settings: Settings) {}
+
+Migrate to @handle
+
+// Before
+@onAssign(&quot;passenger&quot;, &quot;passengerSettings&quot;)
+onReady(passenger: any, setting</pre>
+</section>
+<section id="docs-decorators-patch" data-doc-id="docs/decorators/patch">
+  <h2><a href="/docs/decorators/patch">@patch</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/decorators/patch</code> · <a href="/docs/decorators/patch">full page</a></p>
+  <p>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&lt;T&gt; property. It takes the same arguments, options and send(componen</p>
+  <pre class="doc-excerpt">@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  property. It takes the same arguments, options and send(component) handle as @post; only the HTTP method differs.
+
+Import
+
+import { patch, type ApiResult } from &quot;@supersoniks/concorde/decorators&quot;;
+import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+import { Endpoint } from &quot;@supersoniks/concorde/utils/endpoint&quot;;
+
+Basic usage
+
+The body holds only the fields to change, here a gate change for flight CN 001.
+
+type Flight = { flight: string; route: string; gate: string };
+
+const gateChangeKey = new DataProviderKey&amp;lt;Partial&amp;lt;Flight&amp;gt;&amp;gt;(&quot;gateChange&quot;);
+
+@patch(new Endpoint&amp;lt;Flight&amp;gt;(&quot;flights/CN001&quot;), gateChangeKey)
+@state()
+payload?: ApiResult&amp;lt;Flight&amp;gt;;
+
+moveToB12() {
+  set(gateChangeKey, { gate: &quot;B12&quot; }); // sends the PATCH
+}
+
+Triggers, the send method decorator and every option are described on @post.
+
+API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| endpoint | Endpoint  | Resource path and response type |
+| bodyKey | DataProviderKey  | Publisher read as the partial body |
+| </pre>
+</section>
+<section id="docs-decorators-post" data-doc-id="docs/decorators/post">
+  <h2><a href="/docs/decorators/post">@post</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/decorators/post</code> · <a href="/docs/decorators/post">full page</a></p>
+  <p>Sends the value of a publisher as the body of a POST request and stores the response in an ApiResult&lt;T&gt; property. Pass an Endpoint and a DataProviderKey for the body; the request runs on connect and a</p>
+  <pre class="doc-excerpt">@post
+
+Sends the value of a publisher as the body of a POST request and stores the response in an ApiResult  property. Pass an Endpoint and a DataProviderKey for the body; the request runs on connect and again whenever the body changes. @put and @patch work the same way.
+
+Import
+
+import { post, type ApiResult } from &quot;@supersoniks/concorde/decorators&quot;;
+import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+import { Endpoint } from &quot;@supersoniks/concorde/utils/endpoint&quot;;
+
+type SignUp = { email: string; password: string };
+type CrewMember = { id: number; email: string };
+
+const signUpKey = new DataProviderKey&amp;lt;SignUp&amp;gt;(&quot;crewSignUp&quot;);
+
+@post(new Endpoint&amp;lt;CrewMember&amp;gt;(&quot;api/register&quot;), signUpKey)
+@state()
+payload?: ApiResult&amp;lt;CrewMember&amp;gt;;
+
+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.
+
+Method form
+
+On a method, the decorator calls it with the full ApiResult  after each request instead of assigning a property.
+
+Sending again
+
+Keep th</pre>
+</section>
+<section id="docs-decorators-publish" data-doc-id="docs/decorators/publish">
+  <h2><a href="/docs/decorators/publish">@publish</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/decorators/publish</code> · <a href="/docs/decorators/publish">full page</a></p>
+  <p>@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. See Data f</p>
+  <pre class="doc-excerpt">@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. See Data flow for the overall model.
+
+Import
+
+import { publish } from &quot;@supersoniks/concorde/decorators&quot;;
+import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+
+type CheckIn = { passenger: string; seat: string };
+const checkInKey = new DataProviderKey&amp;lt;CheckIn&amp;gt;(&quot;checkIn&quot;);
+
+@publish(checkInKey.passenger)
+@state()
+passenger = &quot;Ada Lindqvist&quot;;
+
+Basic usage
+
+Each assignment calls set() on the publisher at the 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 with reflect: true.
+
+The check-in form below publishes passenger and seat; the boarding pass reads them back with sub().
+
+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</pre>
+</section>
+<section id="docs-decorators-put" data-doc-id="docs/decorators/put">
+  <h2><a href="/docs/decorators/put">@put</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/decorators/put</code> · <a href="/docs/decorators/put">full page</a></p>
+  <p>Sends the value of a publisher as the body of a PUT request, to replace a resource, and stores the response in an ApiResult&lt;T&gt; property. It takes the same arguments, options and send(component) handle</p>
+  <pre class="doc-excerpt">@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  property. It takes the same arguments, options and send(component) handle as @post; only the HTTP method differs.
+
+Import
+
+import { put, type ApiResult } from &quot;@supersoniks/concorde/decorators&quot;;
+import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+import { Endpoint } from &quot;@supersoniks/concorde/utils/endpoint&quot;;
+
+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.
+
+type Passenger = { name: string; flight: string; seat: string };
+
+const passengerKey = new DataProviderKey&amp;lt;Passenger&amp;gt;(&quot;passengerForm&quot;);
+const savePassenger = put(
+  new Endpoint&amp;lt;Passenger, { passengerId: string }&amp;gt;(&quot;passengers/${passengerId}&quot;),
+  passengerKey,
+  { autoPostOnBodyMutation: false },
+);
+
+@property() passengerId = &quot;ada-lindqvist&quot;;
+
+@savePassenger
+@state()
+payload?: ApiResult&amp;lt;Passenger&amp;gt;;
+
+async save() {
+  await savePassenger.send(this);
+}
+
+Triggers, the send method decorator and every option are described on @post.
+
+API reference
+
+| Argumen</pre>
+</section>
+<section id="docs-decorators-subscribe" data-doc-id="docs/decorators/subscribe">
+  <h2><a href="/docs/decorators/subscribe">@subscribe</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/decorators/subscribe</code> · <a href="/docs/decorators/subscribe">full page</a></p>
+  <p>@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 to w</p>
+  <pre class="doc-excerpt">@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 to write and sub() to read inside a template. See Data flow for the overall model.
+
+Import
+
+import { subscribe } from &quot;@supersoniks/concorde/decorators&quot;;
+import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+
+type Cockpit = { altitude: number };
+const cockpitKey = new DataProviderKey&amp;lt;Cockpit&amp;gt;(&quot;cockpit&quot;);
+
+@subscribe(cockpitKey.altitude)
+@state()
+altitude = 0;
+
+Static path
+
+The key is a 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.
+
+type Flight = { code: string; gate: string; status: string };
+const flightKey = new DataProviderKey&amp;lt;Flight&amp;gt;(&quot;flight&quot;);
+
+@subscribe(flightKey)
+@state()
+flight: Flight | null = null;
+
+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 perso</pre>
+</section>
+<section id="docs-decorators-wait-for-ancestors" data-doc-id="docs/decorators/wait-for-ancestors">
+  <h2><a href="/docs/decorators/wait-for-ancestors">@awaitConnectedAncestors</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/decorators/wait-for-ancestors</code> · <a href="/docs/decorators/wait-for-ancestors">full page</a></p>
+  <p>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. P</p>
+  <pre class="doc-excerpt">@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
+
+import {
+  awaitConnectedAncestors,
+  dispatchConnectedEvent,
+} from &quot;@supersoniks/concorde/decorators&quot;;
+
+@customElement(&quot;flight-scope&quot;)
+@dispatchConnectedEvent()
+export class FlightScope extends LitElement {}
+
+@customElement(&quot;gate-panel&quot;)
+@awaitConnectedAncestors(&quot;flight-scope&quot;)
+export class GatePanel extends LitElement {}
+
+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.
+
+Several ancestors
+
+With several selectors, the child waits for every matching ancestor. Register both to initialize it, in any order.
+
+Ancestor already connected
+
+When the ancestor is already connected, or no ancestor matches, the child initializes immediately.
+
+Signal readiness
+
+@dispatchConnectedEvent() dispatches a bubbling sonic-connect</pre>
+</section>
+    </article>
+  </main>
+</body>
+</html>