@supersoniks/concorde 4.7.4 → 4.8.0

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
 

package/src/docs/_misc/dynamic-path.md

@@ -0,0 +1,71 @@
+# Dynamic path placeholders
+
+Decorators and `DataProviderKey` paths can include **placeholders** resolved on the host component at runtime:
+
+- `${prop}` or `{$prop}` — e.g. `"users/${userId}"`, `"api/sessions/${sessionId}/sync"`
+- Nested expressions — e.g. `"teams.${teamId}.members"`
+
+Resolution is done by [`resolveDynamicPath`](../../core/decorators/subscriber/dynamicPath.ts). The root property names (`userId`, `sessionId`, …) are watched via `requestAnimationFrame` (see `dynamicPropertyWatch.ts`).
+
+## Default behaviour (`ready` / `not ready`)
+
+| Placeholder value | Path `ready`? | Inserted segment | Notes |
+|-------------------|---------------|------------------|-------|
+| `undefined` | **no** | — | Wait until defined |
+| `null` | **no** | — | Same as undefined |
+| `""` | **yes** | empty string | e.g. `sessions//sync` — request may still run |
+| `0` | **yes** | `"0"` | Not treated as “missing” |
+| `false` | **yes** | `"false"` | |
+| `42`, `"alpha"` | **yes** | `"42"`, `"alpha"` | |
+
+When `ready: false`, decorators **do not** call the network (for `@get` / `@post` / `@put` / `@patch`), **unsubscribe** (`@bind` / `@subscribe`), or skip publisher binding (`@publish` / `@handle`). The decorated property is often left unchanged or set to `undefined` (HTTP decorators).
+
+When the placeholder later becomes valid, observers run again and behaviour resumes.
+
+## `skipEmptyPlaceholder` option
+
+Some APIs should not run while an id is still `""`. Opt in per decorator:
+
+```typescript
+@get(new Endpoint<User, { userId: string }>("users/${userId}"), {
+  skipEmptyPlaceholder: true,
+})
+```
+
+| Option | Scope |
+|--------|--------|
+| `skipEmptyPlaceholder?: boolean` | **Only** empty string `''` on a placeholder |
+| Default `false` | `""` is inserted into the path (legacy behaviour) |
+| `true` | `""` → `ready: false`, same as `null` / `undefined` for that segment |
+
+Does **not** affect `0`, `false`, `null`, or `undefined` (nullish stays “not ready” regardless).
+
+Available on:
+
+| API | Where |
+|-----|--------|
+| `@get` | 2nd or 3rd argument (`GetOptions`) |
+| `@post` / `@put` / `@patch` | `PostOptions` / `ApiSendOptions` |
+| `@bind` / `@subscribe` | `BindOptions` |
+| `@publish` | 2nd argument `PublishOptions` |
+| `@handle` | `HandleOptions` |
+
+## Per-decorator summary
+
+| Decorator | `ready: false` | `ready: true` |
+|-----------|----------------|---------------|
+| `@get` | No HTTP; `payload` → `undefined` | `ApiResult` assigned |
+| `@post` / `@put` / `@patch` | No HTTP; `payload` → `undefined` | `ApiResult` assigned |
+| `@subscribe` / `@bind` | Unsubscribe; prop keeps last value | Subscribe `onAssign` |
+| `@publish` | Internal publisher `null`; writes ignored | `publisher.set` on assign |
+| `@handle` | No subscription; with `waitForAllDefined`, method not called | Callback on assign |
+
+## See also
+
+- [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) — path syntax
+- [Endpoint](#docs/_misc/endpoint.md/endpoint) — HTTP paths + host generic `U`
+- HTTP: [@get](#docs/_decorators/get.md/get) · [@post](#docs/_decorators/post.md/post) · [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch)
+- Store: [@subscribe](#docs/_decorators/subscribe.md/subscribe) · [@bind](#docs/_decorators/bind.md/bind) · [@publish](#docs/_decorators/publish.md/publish) · [@handle](#docs/_decorators/handle.md/handle)
+- Legacy strings: [@onAssign](#docs/_decorators/on-assign.md/on-assign) (dynamic paths section)
+- Templates: [sub()](#docs/_directives/sub.md/sub) — dynamic paths in Lit (no `skipEmptyPlaceholder` yet)
+- Tutorial: [My first component](#docs/_getting-started/my-first-component.md/my-first-component) — `"${dataProvider}"` scope pattern

package/src/docs/_misc/endpoint.md

@@ -2,7 +2,7 @@
 
 `Endpoint<T, U>` describes a single HTTP path (or a path accepted by `API.get`) and carries the expected response type `T`. Unlike [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey), there is no dot-navigation: the path is one string.
 
-The optional second generic `U` (default `any`) describes host properties used to resolve dynamic segments in the path (`${…}` / `{$…}`), for example with the [@get](#docs/_decorators/get.md/get) decorator.
+The optional second generic `U` (default `any`) describes host properties used to resolve dynamic segments in the path (`${…}` / `{$…}`), for example with [@get](#docs/_decorators/get.md/get) or [@post](#docs/_decorators/post.md/post). See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) for `null` / `undefined` / `""` / `0` and `skipEmptyPlaceholder`.
 
 ## Import
 
@@ -30,7 +30,7 @@ const one = new Endpoint&lt;User, { userId: string }&gt;("users/${userId}");
 
 ## Publisher key for payloads
 
-`getDataProviderKey()` returns a typed publisher key whose `path` matches the endpoint path (payload typing follows `ApiGetResult` for this endpoint). Useful when pairing `@get` with `@publish` / `@subscribe` (see [@get](#docs/_decorators/get.md/get)).
+`getDataProviderKey()` returns a typed publisher key whose `path` matches the endpoint path (payload typing follows `ApiResult` for this endpoint). Useful when pairing `@get` with `@publish` / `@subscribe` (see [@get](#docs/_decorators/get.md/get)).
 
 ## Data-provider paths
 
@@ -39,5 +39,7 @@ const one = new Endpoint&lt;User, { userId: string }&gt;("users/${userId}");
 ## See also
 
 - [API configuration](#docs/_misc/api-configuration.md/api-configuration) — `serviceURL`, token, wording (mock demos)
-- [@get](#docs/_decorators/get.md/get) — decorator that uses `Endpoint<T>`
+- [@get](#docs/_decorators/get.md/get) — GET decorator
+- [@post](#docs/_decorators/post.md/post) — POST decorator (body from a `DataProviderKey`)
+- [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch) — PUT / PATCH decorators
 - [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) — typed publisher paths (dot notation)

package/src/docs/components/docs-demo-sources.ts

@@ -1,6 +1,14 @@
-import { html, LitElement, nothing } from "lit";
-import { customElement, property } from "lit/decorators.js";
+import { css, html, LitElement, nothing } from "lit";
+import { customElement, property, state } from "lit/decorators.js";
+import { unsafeHTML } from "lit/directives/unsafe-html.js";
+import { tailwind } from "../tailwind";
 import { docsSourceLinks, type DocsSource } from "./docs-source-link";
+import { DOCS_SOURCE_RAW } from "./docs-source-raw";
+import { resolveSourceExcerpt } from "./docs-source-excerpt";
+import "../prism/prism";
+import { prismCSS } from "../prism";
+import * as Prism from "prismjs";
+import "prismjs/components/prism-typescript";
 
 export type { DocsSource };
 
@@ -260,6 +268,30 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
     },
     { path: "src/docs/example/decorators-demo-geo.ts", label: "geo API" },
   ],
+  "demo-api-post": [
+    {
+      path: "src/docs/example/decorators-demo-post.ts",
+      line: 53,
+      label: "demo-api-post",
+    },
+    { path: "src/docs/mock-api/router.ts", label: "mock router" },
+  ],
+  "demo-api-post-dynamic": [
+    {
+      path: "src/docs/example/decorators-demo-post.ts",
+      line: 143,
+      label: "demo-api-post-dynamic",
+    },
+    { path: "src/docs/mock-api/router.ts", label: "mock router (sessions sync)" },
+  ],
+  "demo-api-post-publish": [
+    {
+      path: "src/docs/example/decorators-demo-post.ts",
+      line: 209,
+      label: "demo-api-post-publish",
+    },
+    { path: "src/docs/mock-api/router.ts", label: "mock router" },
+  ],
   "demo-handle": [
     {
       path: "src/docs/example/decorators-demo-subscribe-publish-get-demos.ts",
@@ -384,14 +416,81 @@ export const DOCS_DEMO_SOURCE_REGISTRY: Record<string, DocsSource[]> = {
   ],
 };
 
+function highlightTs(code: string): string {
+  return Prism.highlight(code, Prism.languages.typescript, "typescript");
+}
+
 @customElement("docs-demo-sources")
 export class DocsDemoSources extends LitElement {
+  static styles = [
+    tailwind,
+    prismCSS,
+    css`
+      :host {
+        display: block;
+        margin-bottom: 0.75rem;
+      }
+      pre {
+        font-size: 13px !important;
+        margin: 0;
+      }
+    `,
+  ];
+
   /** Registry key matching the live demo custom element tag. */
   @property({ attribute: "for" }) forTag = "";
 
+  @property({ type: Boolean, attribute: "show-code" }) showCode = true;
+
+  @state() private highlighted = "";
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.refreshHighlight();
+  }
+
+  updated(changed: Map<string, unknown>) {
+    super.updated(changed);
+    if (changed.has("forTag") || changed.has("showCode")) {
+      this.refreshHighlight();
+    }
+  }
+
+  private refreshHighlight() {
+    if (!this.showCode) {
+      this.highlighted = "";
+      return;
+    }
+    const sources = DOCS_DEMO_SOURCE_REGISTRY[this.forTag];
+    const primary = sources?.[0];
+    if (!primary) {
+      this.highlighted = "";
+      return;
+    }
+    const raw = DOCS_SOURCE_RAW[primary.path];
+    if (!raw) {
+      console.warn(`[docs-demo-sources] No raw source for ${primary.path}`);
+      this.highlighted = "";
+      return;
+    }
+    const excerpt = resolveSourceExcerpt(raw, this.forTag, {
+      line: primary.line,
+    });
+    this.highlighted = highlightTs(excerpt);
+  }
+
   render() {
     const sources = DOCS_DEMO_SOURCE_REGISTRY[this.forTag];
     if (!sources?.length) return nothing;
-    return docsSourceLinks(sources);
+    return html`
+      ${docsSourceLinks(sources)}
+      ${this.showCode && this.highlighted
+        ? html`
+            <pre
+              class="rounded-md custom-scroll language-typescript overflow-auto border border-neutral-200/80 dark:border-neutral-700/80"
+            ><code>${unsafeHTML(this.highlighted)}</code></pre>
+          `
+        : nothing}
+    `;
   }
 }

package/src/docs/components/docs-lit-demo-raw.ts

@@ -1,28 +1,4 @@
 /**
- * Raw sources for `<docs-lit-demo>` — explicit imports only (no import.meta.glob).
- * Included in the **docs** bundle (`src/docs.ts`), not in the **core** library build (`src/index.ts`).
- * Add one import + map entry when registering a new file in `DOCS_LIT_DEMO_REGISTRY`.
+ * @deprecated Importez `DOCS_SOURCE_RAW` depuis `./docs-source-raw`.
  */
-import docsJokeDemos from "../example/docs-joke-demos.ts?raw";
-import docsListDemos from "../example/docs-list-demos.ts?raw";
-import docsQueueDemos from "../example/docs-queue-demos.ts?raw";
-import docsToggleDemos from "../example/docs-toggle-demos.ts?raw";
-import docsUserTwoScopes from "../example/docs-user-two-scopes.ts?raw";
-import docsRouterDemos from "../example/docs-router-demos.ts?raw";
-import docsSubmitDemos from "../example/docs-submit-demos.ts?raw";
-import docsApiConfigDemos from "../example/docs-api-config-demos.ts?raw";
-import docsUsersList from "../example/docs-users-list.ts?raw";
-import users from "../example/users.ts?raw";
-
-export const DOCS_LIT_DEMO_RAW: Record<string, string> = {
-  "src/docs/example/docs-toggle-demos.ts": docsToggleDemos,
-  "src/docs/example/docs-joke-demos.ts": docsJokeDemos,
-  "src/docs/example/docs-queue-demos.ts": docsQueueDemos,
-  "src/docs/example/docs-list-demos.ts": docsListDemos,
-  "src/docs/example/docs-router-demos.ts": docsRouterDemos,
-  "src/docs/example/docs-submit-demos.ts": docsSubmitDemos,
-  "src/docs/example/docs-api-config-demos.ts": docsApiConfigDemos,
-  "src/docs/example/docs-users-list.ts": docsUsersList,
-  "src/docs/example/docs-user-two-scopes.ts": docsUserTwoScopes,
-  "src/docs/example/users.ts": users,
-};
+export { DOCS_LIT_DEMO_RAW, DOCS_SOURCE_RAW } from "./docs-source-raw";