@supersoniks/concorde 4.8.0 → 4.9.0

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

@@ -0,0 +1,390 @@
+# @onAssign
+
+> **New apps:** use [@handle](#docs/_decorators/handle.md/handle) with `DataProviderKey` ([Data flow](#docs/_core-concept/dataFlow.md/dataFlow)). `@onAssign` uses untyped string paths; it remains documented for existing codebases — see **Migrating to @handle** below.
+
+The `@onAssign` decorator allows you to execute a method when one or more publishers are updated. The method is called only when all specified publishers have been assigned values.
+
+For a **typed** equivalent (recommended), use [@handle](#docs/_decorators/handle.md/handle).
+
+## Principle
+
+This decorator subscribes to one or more publishers by **string path** (legacy). When all specified publishers have been assigned values (via `set`), the decorated method is called with all the values as arguments. Prefer [@handle](#docs/_decorators/handle.md/handle) + `DataProviderKey` and `get` / `set` from [Data flow](#docs/_core-concept/dataFlow.md/dataFlow).
+
+This is particularly useful when you need to wait for multiple data sources to be ready before executing logic.
+
+## Usage
+
+### Import
+
+<sonic-code language="typescript">
+  <template>
+import { onAssign } from "@supersoniks/concorde/decorators";
+  </template>
+</sonic-code>
+
+### Basic example 
+
+
+<sonic-code language="typescript">
+  <template>
+//...
+@customElement("demo-on-assign")
+export class DemoOnAssign extends LitElement {
+  static styles = [tailwind];
+
+  @state() userWithSettings: any = null;
+  @state() isReady: boolean = false;
+  @state() lastUpdate: string = "";
+
+  @onAssign("demoUser", "demoUserSettings")
+  handleDataReady(user: any, settings: any) {
+    this.isReady = Object.keys(user).length > 0 && Object.keys(settings).length > 0;
+    this.userWithSettings = { ...user, ...settings };
+    this.lastUpdate = new Date().toLocaleTimeString();
+    this.requestUpdate();
+  }
+
+  render() {
+    const { name, email, theme, language } = this.userWithSettings;
+    return //...
+  }
+
+  updateData() {
+    const user = PublisherManager.get("demoUser");
+    const userSettings = PublisherManager.get("demoUserSettings");
+    const userNumber = Math.floor(Math.random() * 100);
+    user.set({
+      name: `User n°${userNumber}`,
+      email: `user-${userNumber}@example.com`,
+    });
+
+    userSettings.set({
+      theme: ["light", "dark", "auto"][Math.floor(Math.random() * 3)],
+      language: ["en", "fr", "es"][Math.floor(Math.random() * 3)],
+    });
+  }
+}
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-on-assign"></docs-demo-sources>
+    <demo-on-assign></demo-on-assign>
+  </template>
+</sonic-code>
+
+
+### Example with nested paths
+
+<sonic-code language="typescript">
+  <template>
+@customElement("product-view")
+export class ProductView extends LitElement {
+  product: any = null;
+  inventory: any = null;
+
+  @onAssign("store.product", "store.inventory")
+  handleProductData(product: any, inventory: any) {
+    this.product = product;
+    this.inventory = inventory;
+    this.requestUpdate();
+  }
+
+  render() {
+    if (!this.product) return html`<div>Loading...</div>`;
+
+    const stock = this.inventory[this.product.id] || 0;
+    return html`
+      <div>
+        <h2>${this.product.name}</h2>
+        <p>Price: ${this.product.price}€</p>
+        <p>Stock: ${stock}</p>
+      </div>
+    `;
+  }
+}
+  </template>
+</sonic-code>
+
+## Path syntax
+
+The path uses dot notation to navigate through the publisher structure:
+
+- **First segment**: dataProvider identifier (e.g., `"userData"`)
+- **Following segments**: nested properties (e.g., `"store.product"`)
+- **Array access**: use numeric index (e.g., `"data.items.0"`)
+
+### Dynamic path driven by class properties
+
+You can now build the paths dynamically by referencing the host class properties inside the strings passed to `@onAssign`. Two placeholder syntaxes are supported:
+
+- `` ${myProperty} `` or `` ${this.myProperty} ``
+- `` {$myProperty} ``
+
+Each placeholder is replaced at runtime with the current value of the corresponding property. `@onAssign` automatically watches those properties and:
+
+- re-evaluates the final paths when one of them changes,
+- removes the previous subscriptions before attaching the new ones,
+- observe the changes inside `willUpdate(changedProperties)` so nothing touches the getters/setters.
+
+While a placeholder is `null`/`undefined`, subscriptions are detached. Optional `skipEmptyPlaceholder` on [@handle](#docs/_decorators/handle.md/handle) (typed replacement). Details: [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
+
+
+<sonic-code language="typescript">
+  <template>
+@customElement("demo-on-assign-dynamic")
+export class DemoOnAssignDynamic extends LitElement {
+  static styles = [tailwind];
+
+  @property({ type: String })
+  dataProvider: "demoUsers" | "demoUsersAlt" = "demoUsers";
+
+  @property({ type: Number })
+  userIndex: number = 0;
+
+  @state() user: any = null;
+  @state() userSettings: any = null;
+
+  @onAssign("${dataProvider}.${userIndex}", "${dataProvider}Settings.${userIndex}")
+  handleUserDataReady(user: any, settings: any) {
+    this.user = user;
+    this.userSettings = settings;
+  }
+
+  updateUserIndex(e: Event) {
+    this.userIndex = parseInt((e.target as HTMLInputElement).value);
+  }
+
+  updateDataProvider(e: Event) {
+    this.dataProvider = (e.target as HTMLSelectElement).value as
+      | "demoUsers"
+      | "demoUsersAlt";
+  }
+
+  updateCurrentUserData() {
+    const usersPublisher = PublisherManager.get(this.dataProvider);
+    const settingsPublisher = PublisherManager.get(
+      `${this.dataProvider}Settings`
+    );
+    const userPublisher = Objects.traverse(
+      usersPublisher,
+      [String(this.userIndex)]
+    ) as PublisherProxy;
+    const settingPublisher = Objects.traverse(
+      settingsPublisher,
+      [String(this.userIndex)]
+    ) as PublisherProxy;
+
+    if (userPublisher && settingPublisher) {
+      // Générer de nouvelles données aléatoires
+      const randomNames = [
+        { firstName: "Alice", lastName: "Wonder" },
+        { firstName: "Bob", lastName: "Builder" },
+        { firstName: "Charlie", lastName: "Chaplin" },
+      ];
+      const randomThemes = ["light", "dark", "auto"];
+      const randomLanguages = ["en", "fr", "es"];
+
+      const randomName =
+        randomNames[Math.floor(Math.random() * randomNames.length)];
+      const randomEmail = `${randomName.firstName.toLowerCase()}.${randomName.lastName.toLowerCase()}@example.com`;
+      const randomTheme =
+        randomThemes[Math.floor(Math.random() * randomThemes.length)];
+      const randomLanguage =
+        randomLanguages[Math.floor(Math.random() * randomLanguages.length)];
+
+      // Mettre à jour l'utilisateur directement
+      const currentUser = userPublisher.get() || {};
+      userPublisher.set({
+        ...currentUser,
+        firstName: randomName.firstName,
+        lastName: randomName.lastName,
+        email: randomEmail,
+      });
+
+      // Mettre à jour les settings directement
+      settingPublisher.set({
+        theme: randomTheme,
+        language: randomLanguage,
+      });
+    }
+  }
+
+  render() {
+    return html`
+      &lt;div class="flex flex-col gap-2"&gt;
+        &lt;sonic-select label="Users set" @change=${this.updateDataProvider}&gt;
+          &lt;option value="demoUsers"&gt;First set of users&lt;/option&gt;
+          &lt;option value="demoUsersAlt"&gt;Second set of users&lt;/option&gt;
+        &lt;/sonic-select&gt;
+        &lt;sonic-input
+          type="number"
+          .value=${this.userIndex}
+          @input=${this.updateUserIndex}
+          min="0"
+          max="9"
+          label="Index"
+          class="block"
+        &gt;&lt;/sonic-input&gt;
+        &lt;sonic-button @click=${this.updateCurrentUserData}&gt;
+          Update current user data
+        &lt;/sonic-button&gt;
+        &lt;div class="flex flex-col gap-2 border p-2"&gt;
+          &lt;div&gt;
+            &lt;sonic-icon name="user" library="heroicons"&gt;&lt;/sonic-icon&gt;
+            ${this.user?.firstName} ${this.user?.lastName}
+          &lt;/div&gt;
+          &lt;div&gt;
+            &lt;sonic-icon name="envelope" library="heroicons"&gt;&lt;/sonic-icon&gt;
+            ${this.user?.email}
+          &lt;/div&gt;
+          &lt;div&gt;
+            Theme: ${this.userSettings?.theme} | Language:
+            ${this.userSettings?.language}
+          &lt;/div&gt;
+        &lt;/div&gt;
+      &lt;/div&gt;
+    `;
+  }
+}
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-on-assign-dynamic"></docs-demo-sources>
+    <demo-on-assign-dynamic></demo-on-assign-dynamic>
+  </template>
+</sonic-code>
+
+> ⚠️ Use classic string literals: `@onAssign("${dataProvider}.${profileId}", "settings.${profileId}")`. Do **not** use template literals (backticks), otherwise JavaScript would try to interpolate the value immediately.
+
+Additional constraints:
+
+- The hosting class must expose a `willUpdate(changedProperties?: Map<PropertyKey, unknown>)` method (LitElement already provides it) so that `@onAssign` can listen to dependency changes.
+- Dependencies need to be reactive (e.g. `@property()` on LitElement) or you must call `this.requestUpdate("myProp")` manually after changing them, otherwise `willUpdate` will never be notified.
+- If you use nested expressions like `${user.id}`, the first segment (`user`) is the one being observed: you need to reassign `this.user` (e.g. with a new object) so that the binding can detect the change.
+
+## Behavior
+
+- The method is called only when **all** specified publishers have been assigned values
+- The method receives the values of all publishers as arguments, in the same order as specified
+- Subscription happens at the time of `connectedCallback`
+- Unsubscription happens automatically at the time of `disconnectedCallback`
+- If a publisher doesn't exist yet, it will be created with the value `null`
+- The method is called with `this` bound to the component instance
+
+## Use cases
+
+This decorator is particularly useful for:
+
+- **Waiting for multiple data sources** before rendering or executing logic
+- **Synchronizing data** from different publishers
+- **Initializing components** that depend on multiple data providers
+- **Handling complex data dependencies** where you need all data to be ready
+
+## Complete example
+
+<sonic-code language="typescript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement } from "lit/decorators.js";
+import { onAssign } from "@supersoniks/concorde/decorators";
+import { PublisherManager } from "@supersoniks/concorde/core/utils/PublisherProxy";
+
+@customElement("order-summary")
+export class OrderSummary extends LitElement {
+  order: any = null;
+  customer: any = null;
+  shipping: any = null;
+
+  @onAssign("orderData", "customerData", "shippingData")
+  handleOrderReady(order: any, customer: any, shipping: any) {
+    this.order = order;
+    this.customer = customer;
+    this.shipping = shipping;
+    this.requestUpdate();
+  }
+
+  render() {
+    if (!this.order || !this.customer || !this.shipping) {
+      return html`<div>Loading order details...</div>`;
+    }
+
+    return html`
+      <div class="order-summary">
+        <h2>Order #${this.order.id}</h2>
+        <p>Customer: ${this.customer.name}</p>
+        <p>Shipping to: ${this.shipping.address}</p>
+        <p>Total: ${this.order.total}€</p>
+      </div>
+    `;
+  }
+}
+// Somewhere in your code, update the publishers:
+const orderPub = PublisherManager.get("orderData");
+const customerPub = PublisherManager.get("customerData");
+const shippingPub = PublisherManager.get("shippingData");
+// The method will be called only when all three are set:
+orderPub.set({ id: "123", total: 99.99 });
+customerPub.set({ name: "John Doe", email: "john@example.com" });
+shippingPub.set({ address: "123 Main St" });
+// handleOrderReady will be called with all three values
+  </template>
+</sonic-code>
+
+## Migrating to @handle
+
+`@handle` is the typed successor of `@onAssign`. The key behavioral difference: `@onAssign` waits for **all** values to be defined before calling the method, whereas `@handle` calls it on **every** assignment by default. Use the `waitForAllDefined` option to keep the old semantics.
+
+### Why migrate
+
+- **Typed paths**: keys are `DataProviderKey<T>`, so the method arguments are strongly typed (no more `any`).
+- **Explicit intent**: `waitForAllDefined` and `skip` replace implicit behavior.
+- **Single API**: `@handle` covers the mono- and multi-path cases (up to 3 keys).
+
+### Equivalent semantics (`waitForAllDefined`)
+
+<sonic-code language="typescript">
+  <template>
+// Before
+@onAssign("demoUser", "demoUserSettings")
+handleDataReady(user: any, settings: any) { /* ... */ }
+
+// After — same "wait for everything" behavior, but typed
+const user = new DataProviderKey&lt;User&gt;("demoUser");
+const settings = new DataProviderKey&lt;Settings&gt;("demoUserSettings");
+
+@handle(user, settings, { waitForAllDefined: true })
+handleDataReady(user: User, settings: Settings) { /* ... */ }
+  </template>
+</sonic-code>
+
+### Single path
+
+<sonic-code language="typescript">
+  <template>
+// Before
+@onAssign("settings.modules.logs_route.enabled")
+onLogRoute(value: boolean) { /* ... */ }
+
+// After
+const settings = new DataProviderKey&lt;AppSettings&gt;("settings");
+
+@handle(settings.modules.logs_route.enabled)
+onLogRoute(value: boolean) { /* ... */ }
+  </template>
+</sonic-code>
+
+### 4+ paths
+
+`@handle` is capped at 3 keys. For the rare case of 4 or more publishers, keep `@onAssign` for now, or split the logic into several `@handle` methods that each store their value and call a shared method (guarding against partial values).
+
+## Notes
+
+- This decorator works with any component that has `connectedCallback` and `disconnectedCallback` methods (such as `LitElement` or components extending `Subscriber`)
+- The method is called synchronously when all publishers are ready
+- If you need to update the UI, remember to call `this.requestUpdate()` inside the method
+- For more information about publishers, see the documentation on [Sharing data](#docs/_getting-started/pubsub.md/pubsub)
+

package/docs/src/docs/_decorators/patch.md

@@ -0,0 +1,45 @@
+# @patch
+
+Sends data through [`API.patchDetailed`](../../core/utils/api.ts). Same model as [@post](#docs/_decorators/post.md/post): decorated property is **`ApiResult<T> | null`** (`request`, `response`, `result`).
+
+Pass an [`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint) and a `DataProviderKey` for the **request body**. Import `patch` and `ApiResult` from `@supersoniks/concorde/decorators`.
+
+## Configuration
+
+Same as [@post](#docs/_decorators/post.md/post) / [@get](#docs/_decorators/get.md/get): scoped `HTML.getApiConfiguration(host)` or `DataProviderKey<APIConfiguration>` as third argument.
+
+## Options (`PatchOptions`)
+
+Same shape as `PostOptions` on [@post](#docs/_decorators/post.md/post) (`ApiSendOptions`): `refetchEveryMs`, `skipIfBodyMissing`, `autoPostOnBodyMutation`, `triggerKey`, `skipEmptyPlaceholder`. See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) for `${sessionId}` and empty-string behaviour.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { patch, type ApiResult } from "@supersoniks/concorde/decorators";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+  </template>
+</sonic-code>
+
+## Example
+
+<sonic-code language="typescript">
+  <template>
+const patchBodyKey = new DataProviderKey&lt;Partial&lt;Resource&gt;&gt;("resourcePatch");
+
+@patch(
+  new Endpoint&lt;Resource, { resourceId: string }&gt;("resources/${resourceId}"),
+  patchBodyKey,
+  { skipEmptyPlaceholder: true },
+)
+@state()
+payload?: ApiResult&lt;Resource&gt; | null;
+  </template>
+</sonic-code>
+
+## See also
+
+- [@post](#docs/_decorators/post.md/post) — POST (live demos)
+- [@put](#docs/_decorators/put.md/put) — full replacement (PUT)
+- [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path)

package/docs/src/docs/_decorators/post.md

@@ -0,0 +1,93 @@
+# @post
+
+Sends data through [`API.postDetailed`](../../core/utils/api.ts). The decorated property is **`ApiResult<T> | null`**: `request`, `response`, and typed `result`.
+
+Pass an [`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint) as the first argument and a `DataProviderKey` for the **request body** as the second. Import `post` and `ApiResult` from `@supersoniks/concorde/decorators`, and `Endpoint` from `@supersoniks/concorde/utils/endpoint`.
+
+## Configuration
+
+Same as [@get](#docs/_decorators/get.md/get): scoped `HTML.getApiConfiguration(host)` by default, or `DataProviderKey<APIConfiguration>` as third argument. See [API configuration](#docs/_misc/api-configuration.md/api-configuration) for mock demos.
+
+## Optional `PostOptions` (third or fourth argument)
+
+| Option | Description |
+|--------|-------------|
+| `refetchEveryMs` | Re-post on an interval (ms). |
+| `skipIfBodyMissing` | Skip when body publisher is `null`/`undefined` (default: `true`). |
+| `autoPostOnBodyMutation` | Re-post when the body publisher mutates (default: `true`). `false` = manual via `triggerKey.invalidate()`. |
+| `skipEmptyPlaceholder` | If `true`, a placeholder resolved to `''` blocks the request (empty string only — not `0` or `false`). See [Dynamic paths](#docs/_misc/dynamic-path.md/dynamic-path). |
+| `triggerKey` | `DataProviderKey` — `invalidate()` re-runs the POST with the current body. |
+
+## When the POST runs again
+
+- Body publisher `onInternalMutation` when `autoPostOnBodyMutation` is `true` (default). Plusieurs mutations synchrones dans la même frame sont regroupées en **un seul POST** via `requestAnimationFrame`.
+- Endpoint path dependency changes (`${sessionId}` on the host).
+- Configuration publisher mutation.
+- `triggerKey` publisher `invalidate()`.
+- `refetchEveryMs` timer (if set).
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { post, publish, type ApiResult } from "@supersoniks/concorde/decorators";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+  </template>
+</sonic-code>
+
+## Minimal example
+
+Mock service: `POST /docs-mock-api/api/register` (same route as [`sonic-submit`](#core/components/functional/submit/submit.md/submit) demos). Publisher setup lives in `decorators-demo-post.ts`.
+
+<sonic-code language="typescript">
+  <template>
+const syncRequest = new DataProviderKey&lt;SyncRequest&gt;("syncRequest");
+const syncTrigger = new DataProviderKey&lt;number&gt;("syncTrigger");
+
+@post(
+  new Endpoint&lt;SyncResponse, { sessionId: string }&gt;("sessions/${sessionId}/sync"),
+  syncRequest,
+  { triggerKey: syncTrigger },
+)
+@state()
+payload?: ApiResult&lt;SyncResponse&gt; | null;
+  </template>
+</sonic-code>
+
+## Live demos
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-api-post"></docs-demo-sources>
+    <demo-api-post></demo-api-post>
+  </template>
+</sonic-code>
+
+Dynamic endpoint path — changing `sessionId` on the host re-runs the POST (`POST /docs-mock-api/api/sessions/{id}/sync`):
+
+<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>
+
+`@post` + `@publish` on the same property (see [@publish](#docs/_decorators/publish.md/publish)):
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-api-post-publish"></docs-demo-sources>
+    <demo-api-post-publish></demo-api-post-publish>
+  </template>
+</sonic-code>
+
+Stale responses are ignored if the path or generation changed before the request finished.
+
+**Note:** plusieurs composants `@post` sur la même page qui partagent le même `bodyKey` enverront chacun une requête à chaque mutation du body — utiliser une clé par composant (voir les deux démos live ci-dessus).
+
+Path placeholders (`${sessionId}`, …): [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
+
+## See also
+
+- [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch) — same decorator model, `PUT` / `PATCH` via `putDetailed` / `patchDetailed`

package/docs/src/docs/_decorators/publish.md

@@ -0,0 +1,55 @@
+# @publish
+
+Write-only binding: assigning to the property publishes to the `DataProviderKey` path. No read subscription (inverse of [@subscribe](#docs/_decorators/subscribe.md/subscribe)).
+
+Similar to the “reflect” half of [@bind](#docs/_decorators/bind.md/bind) without listening to the publisher.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { publish } from "@supersoniks/concorde/decorators";
+import { sub } from "@supersoniks/concorde/directives";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+  </template>
+</sonic-code>
+
+## Example
+
+<sonic-code language="typescript">
+  <template>
+type PublishDemoData = { email: string; message: string };
+const publishDemoKey = new DataProviderKey<PublishDemoData>("publishDemo");
+//
+@customElement("demo-publish")
+export class DemoPublish extends LitElement {
+  @publish(publishDemoKey.email)
+  @state()
+  email = "";
+  //
+  @publish(publishDemoKey.message)
+  @state()
+  message = "";
+  //
+  render() {
+    return html`
+      <sonic-input
+        .value=${this.email}
+        @input=${(e) => (this.email = (e.target as HTMLInputElement).value)}
+        label="Email"
+      ></sonic-input>
+      <p>${sub(publishDemoKey.email)}</p>
+    `;
+  }
+}
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-publish"></docs-demo-sources>
+    <demo-publish></demo-publish>
+  </template>
+</sonic-code>
+
+Dynamic paths use the same placeholder rules as `@bind` / `@subscribe`. Resolution and `skipEmptyPlaceholder`: [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).

package/docs/src/docs/_decorators/put.md

@@ -0,0 +1,43 @@
+# @put
+
+Sends data through [`API.putDetailed`](../../core/utils/api.ts). Same model as [@post](#docs/_decorators/post.md/post): decorated property is **`ApiResult<T> | null`** (`request`, `response`, `result`).
+
+Pass an [`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint) and a `DataProviderKey` for the **request body**. Import `put` and `ApiResult` from `@supersoniks/concorde/decorators`.
+
+## Configuration
+
+Same as [@post](#docs/_decorators/post.md/post) / [@get](#docs/_decorators/get.md/get): scoped `HTML.getApiConfiguration(host)` or `DataProviderKey<APIConfiguration>` as third argument.
+
+## Options (`PutOptions`)
+
+Same shape as `PostOptions` on [@post](#docs/_decorators/post.md/post) (`ApiSendOptions`): `refetchEveryMs`, `skipIfBodyMissing`, `autoPostOnBodyMutation`, `triggerKey`, `skipEmptyPlaceholder`. See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) for `${sessionId}` and empty-string behaviour.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { put, type ApiResult } from "@supersoniks/concorde/decorators";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+  </template>
+</sonic-code>
+
+## Example
+
+<sonic-code language="typescript">
+  <template>
+const bodyKey = new DataProviderKey&lt;UpdatePayload&gt;("resourceBody");
+
+@put(new Endpoint&lt;Resource, { resourceId: string }&gt;("resources/${resourceId}"), bodyKey)
+@state()
+payload?: ApiResult&lt;Resource&gt; | null;
+  </template>
+</sonic-code>
+
+Changing `resourceId` on the host re-runs the PUT when the path becomes ready — see [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
+
+## See also
+
+- [@post](#docs/_decorators/post.md/post) — POST (live demos, polling, `@publish`)
+- [@patch](#docs/_decorators/patch.md/patch) — partial update (PATCH)
+- [Endpoint](#docs/_misc/endpoint.md/endpoint) · [API configuration](#docs/_misc/api-configuration.md/api-configuration)