@supersoniks/concorde 5.1.1 → 5.1.3

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

@@ -0,0 +1,150 @@
+<!DOCTYPE html>
+<html lang="en" data-doc-url="https://concorde.supersoniks.org/docs/decorators/post" data-doc-id="docs/decorators/post">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>@post — Concorde by Supersoniks</title>
+  <meta name="description" content="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">
+  <meta name="keywords" content="Concorde, supersoniks, docs/decorators/post, post, @post, decorator, POST, ApiResult, undefined, request, response, result, POST /docs-mock-api/api/register, send(component), Promise | undefined&gt;">
+  <meta name="concorde-doc-id" content="docs/decorators/post">
+  <link rel="canonical" href="https://concorde.supersoniks.org/docs/decorators/post">
+  <link rel="alternate" type="text/markdown" href="https://concorde.supersoniks.org/docs/decorators/post.md">
+</head>
+<body>
+  <header>
+    <p><a href="/docs/index.html">Concorde documentation</a> · <a href="https://concorde.supersoniks.org/docs/decorators/post">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 — @post</strong>. 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 <span>Doc ID: <code>docs/decorators/post</code>. Keywords: Concorde, supersoniks, docs/decorators/post, post, @post, decorator, POST, ApiResult, undefined, request, response, result, POST /docs-mock-api/api/register, send(component), Promise | undefined&gt;. URL: <a href="https://concorde.supersoniks.org/docs/decorators/post">https://concorde.supersoniks.org/docs/decorators/post</a>.</span></p>
+      <h1 id="post">@post</h1>
+<p>Sends the value of a publisher as the body of a <code>POST</code> request and stores the response in an <code>ApiResult&lt;T&gt;</code> property. Pass an <a href="/docs/misc/endpoint">Endpoint</a> and a <a href="/docs/misc/dataProviderKey">DataProviderKey</a> for the body; the request runs on connect and again whenever the body changes. <a href="/docs/decorators/put">@put</a> and <a href="/docs/decorators/patch">@patch</a> work the same way.</p>
+<h2 id="import">Import</h2>
+<pre><code class="language-typescript">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;;
+</code></pre>
+<h2 id="basic-usage">Basic usage</h2>
+<p>The property is <code>undefined</code> until a response arrives, then holds <code>request</code> · <code>response</code> · the typed <code>result</code>. Each body mutation sends a new request; mutations in the same frame are coalesced into one. The demo posts to the local mock <code>POST /docs-mock-api/api/register</code>.</p>
+<pre><code>&lt;docs-demo-sources for=&quot;demo-api-post&quot;&gt;&lt;/docs-demo-sources&gt;
+    &lt;demo-api-post&gt;&lt;/demo-api-post&gt;
+</code></pre>
+<h2 id="method-form">Method form</h2>
+<p>On a method, the decorator calls it with the full <code>ApiResult&lt;T&gt;</code> after each request instead of assigning a property.</p>
+<pre><code>&lt;docs-demo-sources for=&quot;demo-api-post-method&quot;&gt;&lt;/docs-demo-sources&gt;
+    &lt;demo-api-post-method&gt;&lt;/demo-api-post-method&gt;
+</code></pre>
+<h2 id="sending-again">Sending again</h2>
+<p>Keep the decorator in a constant to call <code>send(component)</code>. It reads the current body and returns a <code>Promise&lt;ApiResult&lt;T&gt; | undefined&gt;</code> resolved once the request completes. Use it for &quot;Save&quot; or &quot;Retry&quot; buttons.</p>
+<pre><code class="language-typescript">const signUp = post(new Endpoint&amp;lt;CrewMember&amp;gt;(&quot;api/register&quot;), signUpKey);
+
+@signUp
+@state()
+payload?: ApiResult&amp;lt;CrewMember&amp;gt;;
+
+async retry() {
+  const payload = await signUp.send(this);
+  console.log(payload?.result?.id);
+}
+</code></pre>
+<p>The <code>send</code> method decorator does the same around a method. It runs after the method by default (waiting for a returned Promise); <code>{ when: &quot;before&quot; }</code> sends first.</p>
+<pre><code class="language-typescript">import { send } from &quot;@supersoniks/concorde/decorators&quot;;
+
+@send(signUp)
+async confirmCheckIn() {
+  // Validate the check-in form, then the POST is sent.
+}
+</code></pre>
+<h2 id="manual-trigger">Manual trigger</h2>
+<p>Set <code>autoPostOnBodyMutation: false</code> when the body is edited field by field (a check-in form) and the request must only go out on <code>send()</code> or <code>triggerKey</code>. A <code>triggerKey</code> publisher lets another component resend: calling <code>invalidate()</code> on it sends the current body.</p>
+<pre><code class="language-typescript">const submitKey = new DataProviderKey&amp;lt;number&amp;gt;(&quot;checkInSubmit&quot;);
+
+@post(checkInEndpoint, checkInKey, {
+  autoPostOnBodyMutation: false,
+  triggerKey: submitKey,
+})
+@state()
+payload?: ApiResult&amp;lt;CheckIn&amp;gt;;
+
+// Anywhere: dp(submitKey).invalidate();
+</code></pre>
+<p>By default (<code>skipIfBodyMissing: true</code>) nothing is sent while the body is <code>null</code> or <code>undefined</code>. <code>refetchEveryMs</code> repeats the request at a fixed interval after each response; use it only when repeating the operation is safe.</p>
+<h2 id="api-configuration">API configuration</h2>
+<p>Without a configuration key, <code>serviceURL</code> and credentials come from the HTML scope, as with <a href="/docs/decorators/get">@get</a>. Pass a <code>DataProviderKey&lt;APIConfiguration&gt;</code> as third argument to read them from a publisher; options then move to the fourth argument. See <a href="/docs/misc/api-configuration">API configuration</a>.</p>
+<pre><code class="language-typescript">@post(signUpEndpoint, signUpKey, apiConfigurationKey, { skipIfBodyMissing: false })
+</code></pre>
+<h2 id="dynamic-path">Dynamic path</h2>
+<p>Placeholders in the endpoint (<code>${flight}</code>) are read from the host component; changing the property sends the same body to the new URL. See <a href="/docs/misc/dynamic-path">Dynamic paths</a>.</p>
+<pre><code>&lt;docs-demo-sources for=&quot;demo-api-post-dynamic&quot;&gt;&lt;/docs-demo-sources&gt;
+    &lt;demo-api-post-dynamic&gt;&lt;/demo-api-post-dynamic&gt;
+</code></pre>
+<h2 id="api-reference">API reference</h2>
+<p><code>post(endpoint, bodyKey, configurationKey?, options?)</code> returns a decorator for a property or a method, with a <code>send(component)</code> method.</p>
+<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>Path and response type. Supports <code>${prop}</code> placeholders</td>
+</tr>
+<tr>
+<td><code>bodyKey</code></td>
+<td><code>DataProviderKey&lt;B&gt;</code></td>
+<td>Publisher read as request 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.autoPostOnBodyMutation</code></td>
+<td><code>boolean</code> (default <code>true</code>)</td>
+<td>Send on connect and after each body mutation</td>
+</tr>
+<tr>
+<td><code>options.skipIfBodyMissing</code></td>
+<td><code>boolean</code> (default <code>true</code>)</td>
+<td>Skip while the body is <code>null</code> or <code>undefined</code></td>
+</tr>
+<tr>
+<td><code>options.triggerKey</code></td>
+<td><code>DataProviderKey&lt;unknown&gt;</code></td>
+<td>Publisher whose <code>invalidate()</code> resends</td>
+</tr>
+<tr>
+<td><code>options.refetchEveryMs</code></td>
+<td><code>number</code> (default <code>0</code>, off)</td>
+<td>Resend interval in ms after each response</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>
+<tr>
+<td><code>send(handle, { when })</code></td>
+<td><code>&quot;after&quot;</code> (default) or <code>&quot;before&quot;</code></td>
+<td>Method decorator sending after or before the method</td>
+</tr>
+</tbody></table>
+
+    </article>
+  </main>
+</body>
+</html>

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

@@ -0,0 +1,74 @@
+<!DOCTYPE html>
+<html lang="en" data-doc-url="https://concorde.supersoniks.org/docs/decorators/publish" data-doc-id="docs/decorators/publish">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>@publish — Concorde by Supersoniks</title>
+  <meta name="description" content="@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">
+  <meta name="keywords" content="Concorde, supersoniks, docs/decorators/publish, publish, @publish, decorator, @publish(key), set(), undefined, reflect: true, passenger, seat, ${prop}, null, skipEmptyPlaceholder">
+  <meta name="concorde-doc-id" content="docs/decorators/publish">
+  <link rel="canonical" href="https://concorde.supersoniks.org/docs/decorators/publish">
+  <link rel="alternate" type="text/markdown" href="https://concorde.supersoniks.org/docs/decorators/publish.md">
+</head>
+<body>
+  <header>
+    <p><a href="/docs/index.html">Concorde documentation</a> · <a href="https://concorde.supersoniks.org/docs/decorators/publish">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 — @publish</strong>. @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 <span>Doc ID: <code>docs/decorators/publish</code>. Keywords: Concorde, supersoniks, docs/decorators/publish, publish, @publish, decorator, @publish(key), set(), undefined, reflect: true, passenger, seat, ${prop}, null, skipEmptyPlaceholder. URL: <a href="https://concorde.supersoniks.org/docs/decorators/publish">https://concorde.supersoniks.org/docs/decorators/publish</a>.</span></p>
+      <h1 id="publish">@publish</h1>
+<p><code>@publish(key)</code> 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 <a href="/docs/decorators/subscribe">@subscribe</a>. 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 { 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;;
+</code></pre>
+<h2 id="basic-usage">Basic usage</h2>
+<p>Each assignment calls <code>set()</code> on the publisher at the <a href="/docs/misc/dataProviderKey">DataProviderKey</a> path. <strong>On connect, a defined property value is published immediately</strong>, so the initializer overwrites what the store held. Leave the property <code>undefined</code> to keep the store value. To read and write the same path, use <a href="/docs/decorators/bind">@bind</a> with <code>reflect: true</code>.</p>
+<p>The check-in form below publishes <code>passenger</code> and <code>seat</code>; the boarding pass reads them back with <a href="/docs/directives/sub">sub()</a>.</p>
+<pre><code>&lt;docs-demo-sources for=&quot;demo-publish&quot;&gt;&lt;/docs-demo-sources&gt;
+    &lt;demo-publish&gt;&lt;/demo-publish&gt;
+</code></pre>
+<h2 id="dynamic-path">Dynamic path</h2>
+<p><code>${prop}</code> placeholders resolve from properties of the same component. When a placeholder changes, the property is published to the new path. While it is <code>null</code> or <code>undefined</code>, nothing is published. Rules and <code>skipEmptyPlaceholder</code>: <a href="/docs/misc/dynamic-path">Dynamic paths</a>.</p>
+<pre><code class="language-typescript">@property({ type: Number }) seatIndex = 0;
+
+@publish(
+  new DataProviderKey&amp;lt;string, { seatIndex: number }&amp;gt;(&quot;onBoard.${seatIndex}.seat&quot;),
+  { skipEmptyPlaceholder: true },
+)
+@state()
+seat = &quot;1A&quot;;
+</code></pre>
+<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></td>
+<td><code>DataProviderKey&lt;T, U&gt;</code></td>
+<td>Path to write. <code>U</code> lists the host properties used by <code>${…}</code> placeholders</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>
+
+    </article>
+  </main>
+</body>
+</html>

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

@@ -0,0 +1,83 @@
+<!DOCTYPE html>
+<html lang="en" data-doc-url="https://concorde.supersoniks.org/docs/decorators/put" data-doc-id="docs/decorators/put">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>@put — Concorde by Supersoniks</title>
+  <meta name="description" content="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">
+  <meta name="keywords" content="Concorde, supersoniks, docs/decorators/put, put, @put, decorator, PUT, ApiResult, send(component), ${passengerId}, send, endpoint, Endpoint, bodyKey, DataProviderKey, configurationKey">
+  <meta name="concorde-doc-id" content="docs/decorators/put">
+  <link rel="canonical" href="https://concorde.supersoniks.org/docs/decorators/put">
+  <link rel="alternate" type="text/markdown" href="https://concorde.supersoniks.org/docs/decorators/put.md">
+</head>
+<body>
+  <header>
+    <p><a href="/docs/index.html">Concorde documentation</a> · <a href="https://concorde.supersoniks.org/docs/decorators/put">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 — @put</strong>. 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 <span>Doc ID: <code>docs/decorators/put</code>. Keywords: Concorde, supersoniks, docs/decorators/put, put, @put, decorator, PUT, ApiResult, send(component), ${passengerId}, send, endpoint, Endpoint, bodyKey, DataProviderKey, configurationKey. URL: <a href="https://concorde.supersoniks.org/docs/decorators/put">https://concorde.supersoniks.org/docs/decorators/put</a>.</span></p>
+      <h1 id="put">@put</h1>
+<p>Sends the value of a publisher as the body of a <code>PUT</code> request, to replace 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 { 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;;
+</code></pre>
+<h2 id="basic-usage">Basic usage</h2>
+<p>The full passenger record is sent on connect and after each body mutation. Placeholders such as <code>${passengerId}</code> are resolved on the host component.</p>
+<pre><code class="language-typescript">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);
+}
+</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 full replacement 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>PutOptions</code></td>
+<td>Same as <a href="/docs/decorators/post">@post options</a></td>
+</tr>
+</tbody></table>
+
+    </article>
+  </main>
+</body>
+</html>

package/docs/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) |