@supersoniks/concorde 4.7.4 → 4.9.0

package/src/core/utils/dpOptions.spec.ts

@@ -0,0 +1,56 @@
+import { describe, it, expect } from "vitest";
+import { DataProviderKey } from "./dataProviderKey";
+import { dp, get, mirrorDp } from "./PublisherProxy";
+
+describe("dp() options", () => {
+  const storageKey = new DataProviderKey<{ label: string }>(
+    "dpOptionsSpecStorage",
+  );
+
+  it("active le localStorage via le 2e argument options", () => {
+    const publisher = dp(storageKey, { localStorageMode: "enabled" });
+    expect((publisher as any)._is_savable_).toBe(true);
+  });
+
+  it("reste désactivé sans option", () => {
+    const plainKey = new DataProviderKey<{ label: string }>(
+      "dpOptionsSpecPlain",
+    );
+    const publisher = dp(plainKey);
+    expect((publisher as any)._is_savable_).toBe(false);
+  });
+});
+
+describe("mirrorDp()", () => {
+  it("alias une clé legacy vers un publisher déjà résolu (appState)", () => {
+    type App = { scan: { code: string } };
+    const appKey = new DataProviderKey<App>("mirrorDpSpecApp");
+    const scanKey = new DataProviderKey<{ code: string }>("mirrorDpSpecScan");
+
+    const appState = dp(appKey);
+    appState.scan.code.set("ABC");
+
+    mirrorDp(scanKey, appState.scan);
+
+    expect(get(scanKey)).toEqual({ code: "ABC" });
+    dp(scanKey).code.set("XYZ");
+    expect(appState.scan.code.get()).toBe("XYZ");
+  });
+
+  it("accepte des chemins string", () => {
+    type App = { legacyApi: { total: number } };
+    const appKey = new DataProviderKey<App>("mirrorDpSpecAppString");
+    const legacyKey = new DataProviderKey<{ total: number }>(
+      "mirrorDpSpecLegacyApi",
+    );
+
+    const appState = dp(appKey);
+    appState.legacyApi.total.set(12);
+
+    mirrorDp(legacyKey.path, `${appKey.path}.legacyApi`);
+
+    expect(get(legacyKey)).toEqual({ total: 12 });
+    dp(legacyKey).total.set(99);
+    expect(appState.legacyApi.total.get()).toBe(99);
+  });
+});

package/src/core/utils/endpoint.ts

@@ -1,4 +1,4 @@
-import { ApiGetResult } from "./api";
+import { ApiResult } from "./api";
 import { DataProviderKey } from "./dataProviderKey";
 
 /**
@@ -25,8 +25,8 @@ export class Endpoint<T, U = any> {
   }
 
   /** Même path qu’`Endpoint` ; le 2ᵉ générique `U` est propagé sur la clé publisher. */
-  getDataProviderKey(): DataProviderKey<ApiGetResult<T>, U> {
-    return new DataProviderKey<ApiGetResult<T>, U>(this.path);
+  getDataProviderKey(): DataProviderKey<ApiResult<T>, U> {
+    return new DataProviderKey<ApiResult<T>, U>(this.path);
   }
 
   /**

package/src/css.d.ts

@@ -0,0 +1,19 @@
+declare module "*.css" {
+  const css: import("lit").CSSResult;
+  export default css;
+}
+
+declare module "*.css?inline" {
+  const css: string;
+  export default css;
+}
+
+declare module "*.scss" {
+  const css: import("lit").CSSResult;
+  export default css;
+}
+
+declare module "*.scss?inline" {
+  const css: string;
+  export default css;
+}

package/src/decorators.ts

@@ -16,12 +16,25 @@ export const ancestorAttribute = mySubscriber.ancestorAttribute;
 export const autoSubscribe = mySubscriber.autoSubscribe;
 export const autoFill = mySubscriber.autoFill;
 export const get = api.get;
+export const post = api.post;
+export const put = api.put;
+export const patch = api.patch;
 export {
   DataProviderKey,
   type DataProviderKeyHost,
 } from "./core/utils/dataProviderKey";
 export { Endpoint };
-export type { ApiGetResult } from "./core/utils/api";
+export type { ApiResult, ApiGetResult } from "./core/utils/api";
+export type {
+  ApiSendOptions,
+  GetOptions,
+  PostOptions,
+  PutOptions,
+  PatchOptions,
+} from "./core/decorators/api";
+export type { DynamicPathOptions } from "./core/decorators/subscriber/dynamicPath";
+export type { BindOptions } from "./core/decorators/subscriber/bind";
+export type { PublishOptions } from "./core/decorators/subscriber/publish";
 export const awaitConnectedAncestors = lifecycle.awaitConnectedAncestors;
 export const dispatchConnectedEvent = lifecycle.dispatchConnectedEvent;
 export const CONNECTED = lifecycle.CONNECTED;
@@ -41,4 +54,7 @@ window["concorde-decorator-subscriber"] = {
   autoSubscribe: mySubscriber.autoSubscribe,
   autoFill: mySubscriber.autoFill,
   get: api.get,
+  post: api.post,
+  put: api.put,
+  patch: api.patch,
 };

package/src/directives.ts

@@ -1,5 +1,6 @@
 import * as directives from "@supersoniks/concorde/core/directives/DataProvider";
 import {dp as pubDp, dataProvider as pubDataProvider, get as pubGet, set as pubSet} from "@supersoniks/concorde/core/utils/PublisherProxy";
+import type {DirectiveResult} from "lit/async-directive.js";
 
 import {ConcordeWindow} from "./core/_types/types";
 /**
@@ -10,8 +11,8 @@ export const dp = pubDp;
  * @deprecated @see pubDataProvider
  */
 export const dataProvider = pubDataProvider;
-export const subscribe = directives.subscribe;
-export const sub = directives.sub;
+export const subscribe = directives.subscribe as DirectiveResult;
+export const sub = directives.sub as DirectiveResult;
 
 /**
  * @deprecated @see pubGet

package/src/docs/_core-concept/dataFlow.md

@@ -13,6 +13,8 @@ Recommended patterns for new Concorde apps (Lit + TypeScript). Under the hood, d
 | Write from component state | `@publish` |
 | React to assignments | `@handle` |
 | HTTP GET | `@get` + `Endpoint`, or `sonic-list` / `sonic-queue` with `fetch` |
+| HTTP POST (body from store) | `@post` + `Endpoint` + body `DataProviderKey` |
+| HTTP PUT / PATCH (body from store) | `@put` / `@patch` — same model as `@post` |
 | Forms | `formDataProvider` + `name` on fields |
 | Offline doc demos | `serviceURL="/docs-mock-api"` — [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) |
 
@@ -33,7 +35,7 @@ get(cartKey);
   </template>
 </sonic-code>
 
-Dynamic paths (`users.${userId}`) → decorators or `sub()` — not `get("users.${id}")` in imperative code.
+Dynamic paths (`users.${userId}`) → decorators or `sub()` — not `get("users.${id}")` in imperative code. Resolution rules: [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
 
 [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey)
 
@@ -45,13 +47,17 @@ Dynamic paths (`users.${userId}`) → decorators or `sub()` — not `get("users.
 | `@publish` | Push property writes to store |
 | `@handle` | Method called on assignment |
 | `@ancestorAttribute` | Copy ancestor HTML attribute onto property |
-| `@get` | HTTP GET into `ApiGetResult&lt;T&gt;` |
+| `@get` | HTTP GET into `ApiResult&lt;T&gt;` |
+| `@post` | HTTP POST into `ApiResult&lt;T&gt;` (body from a publisher) |
+| `@put` / `@patch` | HTTP PUT / PATCH into `ApiResult&lt;T&gt;` |
 
 Walkthrough: [My first component](#docs/_getting-started/my-first-component.md/my-first-component)
 
 ## HTTP and lists
 
-- [@get](#docs/_decorators/get.md/get) — single request on a component
+- [@get](#docs/_decorators/get.md/get) — single GET on a component
+- [@post](#docs/_decorators/post.md/post) — POST with body read from a `DataProviderKey`
+- [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch) — PUT / PATCH (same options as `@post`)
 - [List](#core/components/functional/list/list.md/list) — `fetch` + `key="data"` + `/docs-mock-api/api/users`
 - [Queue](#core/components/functional/queue/queue.md/queue) — lazy `offset=$offset&per_page=$limit` + optional `dataFilterProvider` (form → query)
 

package/src/docs/_decorators/ancestor-attribute.md

@@ -18,7 +18,7 @@ import { ancestorAttribute } from "@supersoniks/concorde/decorators";
 
 ### Basic example
 
-The component reads `dataProvider` and `testAttribute` from its ancestor wrapper.
+The component reads `dataProvider` and `testAttribute` from its ancestor wrapper. By default (`dynamic: false`), values are read once at connect.
 
 <sonic-code language="typescript">
   <template>
@@ -36,10 +36,8 @@ export class DemoAncestorAttribute extends LitElement {
 
   render() {
     return html`
-      <section>
-        <p>dataProvider: <strong>${this.dataProvider || "null"}</strong></p>
-        <p>testAttribute: <strong>${this.testAttribute || "null"}</strong></p>
-      </section>
+      <p>dataProvider: <strong>${this.dataProvider ?? "null"}</strong></p>
+      <p>testAttribute: <strong>${this.testAttribute ?? "null"}</strong></p>
     `;
   }
 }
@@ -55,7 +53,6 @@ export class DemoAncestorAttribute extends LitElement {
   </template>
 </sonic-code>
 
-
 ## Use cases
 
 This decorator is particularly useful for:
@@ -68,9 +65,60 @@ This decorator is particularly useful for:
 ## Behavior
 
 - The search starts from the current element and traverses up the DOM tree
-- If the attribute is not found, the property will be assigned `null`
 - The injection happens automatically at the time of `connectedCallback`
-- The value is not reactive: it is only updated once when the element is connected to the DOM
+- By default (`dynamic: false`), the value is read once at connect time and is not updated afterward
+- With `{ dynamic: true }`, the property stays in sync when:
+  - an ancestor **changes** the attribute value
+  - a **closer** ancestor **gains** the attribute (that value wins)
+  - the **nearest** ancestor **loses** the attribute (falls back to the next one up, or `null`)
+- When `dynamic` is enabled, updates also propagate to `@subscribe` / `@bind` paths that depend on the decorated property (e.g. `${dataProvider}`)
+
+### Dynamic mode
+
+Use `{ dynamic: true }` when the decorated property must follow the DOM. With Lit, add **`@state()`** on the same property so template updates are visible when the observer assigns a new value.
+
+The live demo below shows only the resolved attribute value — no store, no reparenting.
+
+<sonic-code language="typescript">
+  <template>
+@customElement("demo-ancestor-attribute-dynamic")
+export class DemoAncestorAttributeDynamic extends LitElement {
+  @ancestorAttribute("dataProvider", { dynamic: true })
+  @state()
+  dataProvider: string | null = null;
+
+  render() {
+    return html`
+      &lt;p&gt;Nearest ancestor: &lt;strong&gt;${this.dataProvider ?? "null"}&lt;/strong&gt;&lt;/p&gt;
+    `;
+  }
+}
+  </template>
+</sonic-code>
+
+Try in the demo:
+
+- **parent-a** / **parent-b** — change the value on the direct parent
+- **Remove parent attr** — falls back to **outer**
+- **Add closer** — a wrapper with `from-closer` becomes the nearest ancestor
+- **Remove closer** — back to parent or outer
+- **Remove outer attr** — if parent has no attribute either, the child shows `null`
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-ancestor-attribute-dynamic-section"></docs-demo-sources>
+    <demo-ancestor-attribute-dynamic-section></demo-ancestor-attribute-dynamic-section>
+  </template>
+</sonic-code>
+
+Static mode (default) — read once at connect, no observer:
+
+<sonic-code language="typescript">
+  <template>
+@ancestorAttribute("dataProvider")
+dataProvider: string | null = null;
+  </template>
+</sonic-code>
 
 ## Notes
 

package/src/docs/_decorators/bind.md

@@ -4,7 +4,7 @@ Binds a class property to a path in a publisher. The property updates when publi
 
 For Lit re-renders, also add `@state()` on the same property.
 
-**See also:** [@subscribe](#docs/_decorators/subscribe.md/subscribe), [@handle](#docs/_decorators/handle.md/handle), [@publish](#docs/_decorators/publish.md/publish), [@get](#docs/_decorators/get.md/get).
+**See also:** [@subscribe](#docs/_decorators/subscribe.md/subscribe), [@handle](#docs/_decorators/handle.md/handle), [@publish](#docs/_decorators/publish.md/publish), [@get](#docs/_decorators/get.md/get), [@post](#docs/_decorators/post.md/post), [@put](#docs/_decorators/put.md/put), [@patch](#docs/_decorators/patch.md/patch).
 
 ## Principle
 
@@ -144,7 +144,7 @@ export class DemoBindReflect extends LitElement {
 
 ### Dynamic paths
 
-Use `${prop}` or `${this.prop}` inside a **normal string literal** (not a JS template literal with backticks). `@bind` re-subscribes when a reactive dependency changes.
+Use `${prop}` or `${this.prop}` inside a **normal string literal** (not a JS template literal with backticks). `@bind` re-subscribes when a reactive dependency changes. While a placeholder is `null`/`undefined`, the bind is inactive; optional `{ skipEmptyPlaceholder: true }` also waits on `""`. See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
 
 > Properties referenced in the pattern must be reactive (`@property`, etc.) or you must call `requestUpdate` manually.
 

package/src/docs/_decorators/get.md

@@ -1,14 +1,18 @@
 # @get
 
-Loads data through [`API.getDetailed`](../../core/utils/api.ts). The decorated property is **`ApiGetResult<T> | null`**: `request`, `response` (or `null` for `dataProvider(...)` resolution without HTTP), and typed `result`.
+Loads data through [`API.getDetailed`](../../core/utils/api.ts). The decorated property is **`ApiResult<T> | null`**: `request`, `response` (or `null` for `dataProvider(...)` resolution without HTTP), and typed `result`.
 
-Pass an [`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint) as the first argument. Import `get` and `ApiGetResult` from `@supersoniks/concorde/decorators`, and `Endpoint` from `@supersoniks/concorde/utils/endpoint`.
+Pass an [`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint) as the first argument. Import `get` and `ApiResult` from `@supersoniks/concorde/decorators`, and `Endpoint` from `@supersoniks/concorde/utils/endpoint`.
 
 ## Configuration
 
 - **Default:** `HTML.getApiConfiguration(host)` (ancestor `serviceURL`, etc.).
 - **Second argument:** `DataProviderKey<APIConfiguration>` — config is read from the publisher at the resolved path; internal mutations trigger another GET. See [API configuration](#docs/_misc/api-configuration.md/api-configuration) for mock demos.
 
+## Dynamic path
+
+`${prop}` on the endpoint or config key is resolved on the host. While a placeholder is `null` or `undefined`, no GET runs. Optional `skipEmptyPlaceholder: true` also blocks `""` (empty string only). Details: [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
+
 ## When the GET runs again
 
 - A referenced Lit property changes (endpoint path and/or config key contains `${...}`).
@@ -18,7 +22,7 @@ Pass an [`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint) as the first argument.
 
 <sonic-code language="typescript">
   <template>
-import { get, type ApiGetResult } from "@supersoniks/concorde/decorators";
+import { get, type ApiResult } from "@supersoniks/concorde/decorators";
 import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
 import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
   </template>
@@ -32,7 +36,7 @@ Same demo service as [`sonic-queue`](../../core/components/functional/queue/queu
   <template>
 @get(new Endpoint<User>("users/${userId}"))
 @state()
-payload: ApiGetResult<User> | null = null;
+payload: ApiResult<User> | null = null;
   </template>
 </sonic-code>
 
@@ -66,3 +70,8 @@ Scoped `@get` with `@publish` / `@subscribe` on the payload (see [@publish](#doc
 </sonic-code>
 
 Stale responses are ignored if the path or generation changed before the request finished.
+
+## See also
+
+- [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path)
+- [@post](#docs/_decorators/post.md/post) · [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch) — send decorators (same path rules)

package/src/docs/_decorators/handle.md

@@ -161,6 +161,10 @@ onProfile(profile: Profile) {
 
 > Options can be combined, e.g. `@handle(a, b, { waitForAllDefined: true, skip: [Skip.Nullish] })`. For any **arbitrary** validation on a specific value, just guard inside the method (`if (!isValid(v)) return;`) — that is exactly what an `accept`-style predicate would do, since `@handle` only runs your method.
 
+### `skipEmptyPlaceholder`
+
+On a **dynamic key path** (`"items.${itemId}"`), if `true`, a placeholder resolved to `''` is treated as not ready (no subscription) — **empty string only**, not `0` or `false`. See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
+
 ## Highlights
 
 - Strict typing: the method receives one argument per key, in order.
@@ -168,4 +172,4 @@ onProfile(profile: Profile) {
 - By default the method runs on **every** assignment, even with `null` / `undefined` (unlike `@onAssign`, which waits for all values). Opt back into that behavior with `waitForAllDefined`.
 - `skip` filters out values by **named category** (e.g. `[Skip.Nullish, Skip.EmptyObject]`); for arbitrary checks on a specific value, guard inside the method.
 
-See also [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey).
+See also [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) and [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).

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

@@ -128,6 +128,8 @@ Each placeholder is replaced at runtime with the current value of the correspond
 - 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>

package/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/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/src/docs/_decorators/publish.md

@@ -52,4 +52,4 @@ export class DemoPublish extends LitElement {
   </template>
 </sonic-code>
 
-Dynamic paths use the same placeholder rules as `@bind` / `@subscribe`.
+Dynamic paths use the same placeholder rules as `@bind` / `@subscribe`. Resolution and `skipEmptyPlaceholder`: [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).

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

package/src/docs/_decorators/subscribe.md

@@ -45,7 +45,9 @@ cart: { items: string[] } | null = null;
 
 ## Dynamic path and scope
 
-Placeholders `${prop}` in the key string are resolved from **properties on the same component**. Declare them in the key’s second generic so TypeScript expects them on the host:
+Placeholders `${prop}` in the key string are resolved from **properties on the same component**. While a value is `null`/`undefined`, the subscription is inactive; optional `{ skipEmptyPlaceholder: true }` also waits on `""`. Full rules: [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
+
+Declare dynamic props in the key’s second generic so TypeScript expects them on the host:
 
 <sonic-code language="typescript">
   <template>
@@ -94,4 +96,5 @@ user: User | null = null;
 
 - [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) — overview
 - [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) — paths and host generics
+- [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) — `${prop}` resolution and `skipEmptyPlaceholder`
 - [sub()](#docs/_directives/sub.md/sub) — same paths inside `html` templates

package/src/docs/_directives/sub.md

@@ -37,7 +37,7 @@ render() {
 
 ## Dynamic DataProviderKey (`${prop}`)
 
-Like `@subscribe`: the path is resolved on the template **host component**; the directive re-subscribes when observed props change.
+Like `@subscribe`: the path is resolved on the template **host component**; the directive re-subscribes when observed props change. Placeholder values (`null`, `""`, `0`, …): [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) (`skipEmptyPlaceholder` not available on `sub()` yet).
 
 <sonic-code language="typescript">
   <template>

package/src/docs/_getting-started/my-first-component.md

@@ -81,7 +81,7 @@ export const docsUserRowKey = new DataProviderKey<
   </template>
 </sonic-code>
 
-The second generic (`{ dataProvider: string | null }`) lists what the host must expose so `"${dataProvider}"` can be resolved. See [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey).
+The second generic (`{ dataProvider: string | null }`) lists what the host must expose so `"${dataProvider}"` can be resolved. See [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) and [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
 
 ### Scope — which store segment applies
 

package/src/docs/_misc/api-configuration.md

@@ -1,6 +1,6 @@
 # API configuration
 
-`APIConfiguration` is the object built by [`HTML.getApiConfiguration`](../../core/utils/HTML.ts) from **ancestor attributes** on the DOM (or from a typed publisher — see [@get configuration key](#docs/_decorators/get.md/get)). It is passed to [`API`](../../core/utils/api.ts) by fetchers, **sonic-submit**, the **`wording()`** directive, and **`@get`**.
+`APIConfiguration` is the object built by [`HTML.getApiConfiguration`](../../core/utils/HTML.ts) from **ancestor attributes** on the DOM (or from a typed publisher — see [@get](#docs/_decorators/get.md/get) / [@post](#docs/_decorators/post.md/post) configuration key). It is passed to [`API`](../../core/utils/api.ts) by fetchers, **sonic-submit**, the **`wording()`** directive, **`@get`**, **`@post`**, **`@put`**, and **`@patch`**.
 
 > **Mock service:** same [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) Service Worker / Vite middleware. Routes used on this page are listed in the [API config routes](#api-config-routes) section below.
 
@@ -74,6 +74,8 @@ Implementation: `src/docs/mock-api/api-config-mock.ts` (bundled in the Service W
 ## See also
 
 - [@get](#docs/_decorators/get.md/get) — `APIConfiguration` + `Endpoint`
+- [@post](#docs/_decorators/post.md/post) — same configuration model for POST
+- [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch) — PUT / PATCH
 - [Endpoint](#docs/_misc/endpoint.md/endpoint) — typed path
 - [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) — offline `serviceURL`
 - [Fetch](#core/components/functional/fetch/fetch.md/fetch) — attribute table (legacy sonic-fetch)

package/src/docs/_misc/dataProviderKey.md

@@ -78,7 +78,7 @@ firstItem.path;  // "data.items.0"
 
 ### Dynamic paths
 
-Use placeholders `${prop}` or `{$prop}` in the path string. The path is resolved at runtime from the component's properties. The type remains declarative:
+Use placeholders `${prop}` or `{$prop}` in the path string. The path is resolved at runtime from the component's properties. See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) for resolution rules and `skipEmptyPlaceholder`. The type remains declarative:
 
 <sonic-code language="typescript">
   <template>
@@ -159,7 +159,7 @@ export class UserForm extends LitElement {
   </template>
 </sonic-code>
 
-These decorators support dynamic paths: `"base.${prop}"` in the constructor. A wrong property type (e.g. `number` for `DataProviderKey<string>`) is a TypeScript error. See [@handle](#docs/_decorators/handle.md/handle) for method callbacks.
+These decorators support dynamic paths: `"base.${prop}"` in the constructor. A wrong property type (e.g. `number` for `DataProviderKey<string>`) is a TypeScript error. Resolution rules: [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path). See [@handle](#docs/_decorators/handle.md/handle) for method callbacks.
 
 ## Notes