@supersoniks/concorde 5.1.0 → 5.1.2

package/docs/docs/decorators/get.md

@@ -0,0 +1,160 @@
+# @get
+
+`@get(endpoint)` runs an HTTP GET on an [Endpoint](/docs/misc/endpoint) and stores the full `ApiResult<T>` 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](/docs/decorators/post), [@put](/docs/decorators/put) and [@patch](/docs/decorators/patch).
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { get, Endpoint, type ApiResult } from "@supersoniks/concorde/decorators";
+
+type FlightBoard = { flights: Flight[] };
+const departuresEndpoint = new Endpoint&lt;FlightBoard&gt;("flights?direction=departures");
+
+@get(departuresEndpoint)
+@state()
+departures?: ApiResult&lt;FlightBoard&gt;;
+  </template>
+</sonic-code>
+
+## 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](/docs/misc/api-configuration)). The GET waits until `serviceURL` is available.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-api-get"></docs-demo-sources>
+    <demo-api-get></demo-api-get>
+  </template>
+</sonic-code>
+
+## Method
+
+Decorate a method to receive the `ApiResult<T>` after each GET instead of storing it.
+
+<sonic-code language="typescript">
+  <template>
+@get(departuresEndpoint)
+onDepartures(payload?: ApiResult&lt;FlightBoard&gt;) {
+  this.boarding = payload?.result?.flights.filter((f) =&gt; f.status === "boarding") ?? [];
+}
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-api-get-method"></docs-demo-sources>
+    <demo-api-get-method></demo-api-get-method>
+  </template>
+</sonic-code>
+
+## Configuration key
+
+Pass a `DataProviderKey<APIConfiguration>` as the second argument to read the configuration from the store instead of the HTML scope. Any change to that publisher runs the GET again.
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import type { APIConfiguration } from "@supersoniks/concorde/utils/api";
+
+const flightsApi = new DataProviderKey&lt;APIConfiguration&gt;("flightsApi");
+
+@get(departuresEndpoint, flightsApi)
+@state()
+departures?: ApiResult&lt;FlightBoard&gt;;
+  </template>
+</sonic-code>
+
+## Dynamic endpoint
+
+`${prop}` placeholders in the endpoint resolve from properties of the same component; each change runs a new GET. While a placeholder is `null` or `undefined`, no request is sent and the property is `undefined`. Rules: [Dynamic paths](/docs/misc/dynamic-path).
+
+<sonic-code language="typescript">
+  <template>
+const boardEndpoint = new Endpoint&lt;FlightBoard, { direction: string }&gt;(
+  "flights?direction=${direction}",
+);
+
+@property() direction = "departures";
+
+@get(boardEndpoint, flightsApi)
+@state()
+board?: ApiResult&lt;FlightBoard&gt;;
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-api-get-configuration-key"></docs-demo-sources>
+    <demo-api-get-configuration-key></demo-api-get-configuration-key>
+  </template>
+</sonic-code>
+
+## Refetch
+
+Keep the decorator in a constant to reuse it. `refetch(component)` runs the GET for that instance only and resolves with the new `ApiResult<T>` (or `undefined`).
+
+<sonic-code language="typescript">
+  <template>
+const departuresGet = get(departuresEndpoint);
+
+@departuresGet
+@state()
+departures?: ApiResult&lt;FlightBoard&gt;;
+
+async refresh() {
+  await departuresGet.refetch(this);
+}
+  </template>
+</sonic-code>
+
+`@refetch(handle)` does the same around a method. By default the GET runs **after** the method (and after its Promise, if it returns one); use `{ when: "before" }` to run it first. The method call resolves once the GET is done.
+
+<sonic-code language="typescript">
+  <template>
+import { refetch } from "@supersoniks/concorde/decorators";
+
+@refetch(departuresGet)
+async showArrivals() {
+  this.direction = "arrivals";
+}
+  </template>
+</sonic-code>
+
+## Polling and triggers
+
+`refetchEveryMs` runs the GET again that many milliseconds after each response (default `0`: off). `triggerKey` runs it whenever another component calls `invalidate()` on that publisher.
+
+<sonic-code language="typescript">
+  <template>
+import { dp } from "@supersoniks/concorde/utils";
+
+const boardRefresh = new DataProviderKey&lt;number&gt;("boardRefresh");
+
+@get(departuresEndpoint, { refetchEveryMs: 30000, triggerKey: boardRefresh })
+@state()
+departures?: ApiResult&lt;FlightBoard&gt;;
+
+// anywhere else
+dp(boardRefresh).invalidate();
+  </template>
+</sonic-code>
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `endpoint` | `Endpoint<T, U>` | Path relative to `serviceURL`. `U` lists the host properties used by `${…}` placeholders |
+| `configurationKey` | `DataProviderKey<APIConfiguration>` (optional) | Read the configuration from the store instead of the HTML scope |
+| `options.refetchEveryMs` | `number` (default `0`) | Polling interval after each response; `0` disables it |
+| `options.triggerKey` | `DataProviderKey<unknown>` | Publisher whose `invalidate()` runs the GET again |
+| `options.skipEmptyPlaceholder` | `boolean` (default `false`) | Treat a placeholder resolved to `""` as not ready |
+
+`options` is the second argument, or the third when a `configurationKey` is passed. The returned decorator exposes `refetch(component): Promise<ApiResult<T> | undefined>`.
+
+| `@refetch` argument | Type | Description |
+|---------------------|------|-------------|
+| `handle` | value returned by `get(…)` | GET to run |
+| `options.when` | `"before"` or `"after"` (default `"after"`) | Run the GET before or after the method |

package/docs/docs/decorators/handle.html

@@ -0,0 +1,139 @@
+<!DOCTYPE html>
+<html lang="en" data-doc-url="https://concorde.supersoniks.org/docs/decorators/handle" data-doc-id="docs/decorators/handle">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>@handle — Concorde by Supersoniks</title>
+  <meta name="description" content="@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">
+  <meta name="keywords" content="Concorde, supersoniks, docs/decorators/handle, handle, @handle, decorator, @handle(...keys), null, undefined, ${prop}, waitForAllDefined: true, ${name}, please proceed to gate ${gate}., skip">
+  <meta name="concorde-doc-id" content="docs/decorators/handle">
+  <link rel="canonical" href="https://concorde.supersoniks.org/docs/decorators/handle">
+  <link rel="alternate" type="text/markdown" href="https://concorde.supersoniks.org/docs/decorators/handle.md">
+</head>
+<body>
+  <header>
+    <p><a href="/docs/index.html">Concorde documentation</a> · <a href="https://concorde.supersoniks.org/docs/decorators/handle">same URL (interactive)</a> · <a href="/llms.txt">llms.txt</a></p>
+  </header>
+  <main>
+    <article>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde decorator — @handle</strong>. @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 <span>Doc ID: <code>docs/decorators/handle</code>. Keywords: Concorde, supersoniks, docs/decorators/handle, handle, @handle, decorator, @handle(...keys), null, undefined, ${prop}, waitForAllDefined: true, ${name}, please proceed to gate ${gate}., skip. URL: <a href="https://concorde.supersoniks.org/docs/decorators/handle">https://concorde.supersoniks.org/docs/decorators/handle</a>.</span></p>
+      <h1 id="handle">@handle</h1>
+<p><code>@handle(...keys)</code> 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 <a href="/docs/decorators/subscribe">@subscribe</a> when you only need the value. See <a href="/docs/getting-started/dataFlow">Data flow</a> for the overall model.</p>
+<h2 id="import">Import</h2>
+<pre><code class="language-typescript">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);
+}
+</code></pre>
+<h2 id="basic-usage">Basic usage</h2>
+<p>The method runs once with the current value when the component connects, then on <strong>every</strong> assignment, including <code>null</code> and <code>undefined</code>. Below, each climb assigns a new altitude and the method derives meters and flight level.</p>
+<pre><code>&lt;docs-demo-sources for=&quot;demo-handle&quot;&gt;&lt;/docs-demo-sources&gt;
+    &lt;demo-handle&gt;&lt;/demo-handle&gt;
+</code></pre>
+<h2 id="dynamic-path">Dynamic path</h2>
+<p><code>${prop}</code> placeholders resolve from properties of the same component; when one changes, the method is called with the value at the new path. Rules: <a href="/docs/misc/dynamic-path">Dynamic paths</a>.</p>
+<pre><code class="language-typescript">const personKey = new DataProviderKey&amp;lt;OnBoard, { seatIndex: number }&amp;gt;(
+  &quot;demoOnBoard.${seatIndex}&quot;,
+);
+
+@property({ type: Number }) seatIndex = 0;
+
+@handle(personKey)
+onPerson(person: OnBoard | null) {
+  this.announcement = person ? `${person.name}, please proceed to gate B12.` : &quot;&quot;;
+}
+</code></pre>
+<pre><code>&lt;docs-demo-sources for=&quot;demo-handle-dynamic&quot;&gt;&lt;/docs-demo-sources&gt;
+    &lt;demo-handle-dynamic&gt;&lt;/demo-handle-dynamic&gt;
+</code></pre>
+<h2 id="multiple-keys">Multiple keys</h2>
+<p>Pass up to three <a href="/docs/misc/dataProviderKey">DataProviderKey</a> 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 <code>null</code>.</p>
+<pre><code class="language-typescript">const flightKey = new DataProviderKey&amp;lt;{ status: string; gate: string }&amp;gt;(&quot;flight&quot;);
+const weatherKey = new DataProviderKey&amp;lt;{ turbulence: boolean }&amp;gt;(&quot;weather&quot;);
+
+@handle(flightKey.status, weatherKey.turbulence)
+onConditions(status: string, turbulence: boolean) {
+  this.seatbeltSign = status === &quot;boarding&quot; || turbulence === true;
+}
+</code></pre>
+<h2 id="wait-for-all-values">Wait for all values</h2>
+<p>With <code>waitForAllDefined: true</code>, the method runs only once every key holds a value other than <code>null</code> or <code>undefined</code>.</p>
+<pre><code class="language-typescript">@handle(flightKey.gate, passengerKey.name, { waitForAllDefined: true })
+announce(gate: string, name: string) {
+  this.message = `${name}, please proceed to gate ${gate}.`;
+}
+</code></pre>
+<h2 id="skip-values">Skip values</h2>
+<p><code>skip</code> lists categories of values that must not call the method. A category is a named test, not a value to compare.</p>
+<table>
+<thead>
+<tr>
+<th>Category</th>
+<th>Matches</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>Skip.Nullish</code></td>
+<td><code>null</code> or <code>undefined</code></td>
+</tr>
+<tr>
+<td><code>Skip.EmptyString</code></td>
+<td><code>&quot;&quot;</code></td>
+</tr>
+<tr>
+<td><code>Skip.EmptyObject</code></td>
+<td><code>{}</code> (arrays excluded)</td>
+</tr>
+<tr>
+<td><code>Skip.EmptyArray</code></td>
+<td><code>[]</code></td>
+</tr>
+</tbody></table>
+<pre><code class="language-typescript">@handle(passengerKey, { skip: [Skip.Nullish, Skip.EmptyObject] })
+onPassenger(passenger: Passenger) {
+  // not called while the publisher still holds {} (not loaded yet)
+  this.displayName = passenger.name;
+}
+</code></pre>
+<p>To reject a specific value, return early inside the method.</p>
+<h2 id="api-reference">API reference</h2>
+<table>
+<thead>
+<tr>
+<th>Argument</th>
+<th>Type</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>key</code> (1 to 3)</td>
+<td><code>DataProviderKey&lt;T, U&gt;</code></td>
+<td>Paths to watch; the method receives one value per key, in order</td>
+</tr>
+<tr>
+<td><code>options.waitForAllDefined</code></td>
+<td><code>boolean</code> (default <code>false</code>)</td>
+<td>Call the method only when no value is <code>null</code> or <code>undefined</code></td>
+</tr>
+<tr>
+<td><code>options.skip</code></td>
+<td><code>Skip[]</code> (default none)</td>
+<td>Do not call the method when any value matches one of these categories</td>
+</tr>
+<tr>
+<td><code>options.skipEmptyPlaceholder</code></td>
+<td><code>boolean</code> (default <code>false</code>)</td>
+<td>Treat a placeholder resolved to <code>&quot;&quot;</code> as not ready</td>
+</tr>
+</tbody></table>
+<p><code>options</code>, if present, is the last argument. <code>@handle</code> replaces the deprecated <a href="/docs/decorators/on-assign">@onAssign</a>: <code>@onAssign(&quot;a&quot;, &quot;b&quot;)</code> is <code>@handle(keyA, keyB, { waitForAllDefined: true })</code>.</p>
+
+    </article>
+  </main>
+</body>
+</html>

package/docs/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/docs/decorators/on-assign.html

@@ -0,0 +1,72 @@
+<!DOCTYPE html>
+<html lang="en" data-doc-url="https://concorde.supersoniks.org/docs/decorators/on-assign" data-doc-id="docs/decorators/on-assign">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>@onAssign — Concorde by Supersoniks</title>
+  <meta name="description" content="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,">
+  <meta name="keywords" content="Concorde, supersoniks, docs/decorators/on-assign, on-assign, @onAssign, decorator, onAssign, { waitForAllDefined: true }, DataProviderKey, null, undefined, connectedCallback, disconnectedCallback, ${prop}, @handle">
+  <meta name="concorde-doc-id" content="docs/decorators/on-assign">
+  <link rel="canonical" href="https://concorde.supersoniks.org/docs/decorators/on-assign">
+  <link rel="alternate" type="text/markdown" href="https://concorde.supersoniks.org/docs/decorators/on-assign.md">
+</head>
+<body>
+  <header>
+    <p><a href="/docs/index.html">Concorde documentation</a> · <a href="https://concorde.supersoniks.org/docs/decorators/on-assign">same URL (interactive)</a> · <a href="/llms.txt">llms.txt</a></p>
+  </header>
+  <main>
+    <article>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde decorator — @onAssign</strong>. 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, <span>Doc ID: <code>docs/decorators/on-assign</code>. Keywords: Concorde, supersoniks, docs/decorators/on-assign, on-assign, @onAssign, decorator, onAssign, { waitForAllDefined: true }, DataProviderKey, null, undefined, connectedCallback, disconnectedCallback, ${prop}, @handle. URL: <a href="https://concorde.supersoniks.org/docs/decorators/on-assign">https://concorde.supersoniks.org/docs/decorators/on-assign</a>.</span></p>
+      <h1 id="onassign">@onAssign</h1>
+<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 <a href="/docs/decorators/handle">@handle</a> with <code>{ waitForAllDefined: true }</code>: same behaviour, with typed <code>DataProviderKey</code> paths.</p>
+<h2 id="import">Import</h2>
+<pre><code class="language-typescript">import { onAssign } from &quot;@supersoniks/concorde/decorators&quot;;
+
+@onAssign(&quot;passenger&quot;, &quot;passengerSettings&quot;)
+onReady(passenger: Passenger, settings: Settings) {}
+</code></pre>
+<h2 id="wait-for-every-path">Wait for every path</h2>
+<p>The method is called only when every path holds a value other than <code>null</code> or <code>undefined</code>, with the values in the order of the paths. After that, each assignment calls it again with the latest values. Subscriptions start after <code>connectedCallback</code> and stop in <code>disconnectedCallback</code>.</p>
+<pre><code>&lt;docs-demo-sources for=&quot;demo-on-assign&quot;&gt;&lt;/docs-demo-sources&gt;
+    &lt;demo-on-assign&gt;&lt;/demo-on-assign&gt;
+</code></pre>
+<h2 id="dynamic-path">Dynamic path</h2>
+<p>Paths accept <code>${prop}</code> placeholders resolved on the host. While a placeholder is <code>null</code> or <code>undefined</code>, that path is unsubscribed. Write the paths as plain strings, not template literals. Rules: <a href="/docs/misc/dynamic-path">Dynamic path placeholders</a>.</p>
+<pre><code class="language-typescript">@property({ type: Number }) seat = 0;
+
+@onAssign(&quot;passengers.${seat}&quot;, &quot;passengerSettings.${seat}&quot;)
+onSeat(passenger: Passenger, settings: Settings) {}
+</code></pre>
+<h2 id="migrate-to-handle">Migrate to @handle</h2>
+<pre><code class="language-typescript">// Before
+@onAssign(&quot;passenger&quot;, &quot;passengerSettings&quot;)
+onReady(passenger: any, settings: any) {}
+
+// After
+const passengerKey = new DataProviderKey&amp;lt;Passenger&amp;gt;(&quot;passenger&quot;);
+const settingsKey = new DataProviderKey&amp;lt;Settings&amp;gt;(&quot;passengerSettings&quot;);
+
+@handle(passengerKey, settingsKey, { waitForAllDefined: true })
+onReady(passenger: Passenger, settings: Settings) {}
+</code></pre>
+<p><code>@handle</code> accepts up to three keys. For more paths, keep <code>@onAssign</code> or split the logic into several <code>@handle</code> methods.</p>
+<h2 id="api-reference">API reference</h2>
+<table>
+<thead>
+<tr>
+<th>Argument</th>
+<th>Type</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>...paths</code></td>
+<td><code>string[]</code></td>
+<td>Dot paths in the store (<code>&quot;flights.0.status&quot;</code>), optionally with <code>${prop}</code> placeholders; the method receives one argument per path, in order</td>
+</tr>
+</tbody></table>
+
+    </article>
+  </main>
+</body>
+</html>

package/docs/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/docs/decorators/patch.html

@@ -0,0 +1,76 @@
+<!DOCTYPE html>
+<html lang="en" data-doc-url="https://concorde.supersoniks.org/docs/decorators/patch" data-doc-id="docs/decorators/patch">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>@patch — Concorde by Supersoniks</title>
+  <meta name="description" content="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">
+  <meta name="keywords" content="Concorde, supersoniks, docs/decorators/patch, patch, @patch, decorator, PATCH, ApiResult, send(component), send, endpoint, Endpoint, bodyKey, DataProviderKey, configurationKey">
+  <meta name="concorde-doc-id" content="docs/decorators/patch">
+  <link rel="canonical" href="https://concorde.supersoniks.org/docs/decorators/patch">
+  <link rel="alternate" type="text/markdown" href="https://concorde.supersoniks.org/docs/decorators/patch.md">
+</head>
+<body>
+  <header>
+    <p><a href="/docs/index.html">Concorde documentation</a> · <a href="https://concorde.supersoniks.org/docs/decorators/patch">same URL (interactive)</a> · <a href="/llms.txt">llms.txt</a></p>
+  </header>
+  <main>
+    <article>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde decorator — @patch</strong>. 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 <span>Doc ID: <code>docs/decorators/patch</code>. Keywords: Concorde, supersoniks, docs/decorators/patch, patch, @patch, decorator, PATCH, ApiResult, send(component), send, endpoint, Endpoint, bodyKey, DataProviderKey, configurationKey. URL: <a href="https://concorde.supersoniks.org/docs/decorators/patch">https://concorde.supersoniks.org/docs/decorators/patch</a>.</span></p>
+      <h1 id="patch">@patch</h1>
+<p>Sends the value of a publisher as the body of a <code>PATCH</code> request, to update part of a resource, and stores the response in an <code>ApiResult&lt;T&gt;</code> property. It takes the same arguments, options and <code>send(component)</code> handle as <a href="/docs/decorators/post">@post</a>; only the HTTP method differs.</p>
+<h2 id="import">Import</h2>
+<pre><code class="language-typescript">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;;
+</code></pre>
+<h2 id="basic-usage">Basic usage</h2>
+<p>The body holds only the fields to change, here a gate change for flight CN 001.</p>
+<pre><code class="language-typescript">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
+}
+</code></pre>
+<p>Triggers, the <code>send</code> method decorator and every option are described on <a href="/docs/decorators/post">@post</a>.</p>
+<h2 id="api-reference">API reference</h2>
+<table>
+<thead>
+<tr>
+<th>Argument</th>
+<th>Type</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>endpoint</code></td>
+<td><code>Endpoint&lt;T&gt;</code></td>
+<td>Resource path and response type</td>
+</tr>
+<tr>
+<td><code>bodyKey</code></td>
+<td><code>DataProviderKey&lt;B&gt;</code></td>
+<td>Publisher read as the partial body</td>
+</tr>
+<tr>
+<td><code>configurationKey</code></td>
+<td><code>DataProviderKey&lt;APIConfiguration&gt;</code> (optional)</td>
+<td>API configuration publisher. Default: HTML scope</td>
+</tr>
+<tr>
+<td><code>options</code></td>
+<td><code>PatchOptions</code></td>
+<td>Same as <a href="/docs/decorators/post">@post options</a></td>
+</tr>
+</tbody></table>
+
+    </article>
+  </main>
+</body>
+</html>