@supersoniks/concorde 4.7.3 → 4.8.0

package/src/core/decorators/subscriber/bind.ts

@@ -4,10 +4,15 @@ import type {
 } from "../../utils/dataProviderKey";
 import { ConnectedComponent, setSubscribable } from "./common";
 import {
+  type DynamicPathOptions,
   extractDynamicDependencies,
   hasPath,
   resolveDynamicPath,
 } from "./dynamicPath";
+
+export type BindOptions = DynamicPathOptions & {
+  reflect?: boolean;
+};
 import {
   bindDynamicWatchKeys,
   observeDynamicProperty,
@@ -16,9 +21,12 @@ import { getPublisherFromPath } from "./publisherPath";
 
 function bindImpl(
   path: string,
-  options?: { reflect?: boolean },
+  options?: BindOptions,
 ): (target: unknown, propertyKey: string) => void {
   const reflect = options?.reflect ?? false;
+  const pathOptions: DynamicPathOptions = {
+    skipEmptyPlaceholder: options?.skipEmptyPlaceholder,
+  };
   const dynamicDependencies = extractDynamicDependencies(path);
   const isDynamicPath = dynamicDependencies.length > 0;
 
@@ -139,7 +147,7 @@ function bindImpl(
 
       const refreshSubscription = () => {
         if (isDynamicPath) {
-          const resolution = resolveDynamicPath(component, path);
+          const resolution = resolveDynamicPath(component, path, pathOptions);
           if (!resolution.ready) {
             subscribeToPath(null);
             return;
@@ -201,18 +209,18 @@ function bindImpl(
  */
 export function bind(
   path: string,
-  options?: { reflect?: boolean },
+  options?: BindOptions,
 ): (target: unknown, propertyKey: string) => void;
 export function bind<T, U = any>(
   key: DataProviderKey<T, U>,
-  options?: { reflect?: boolean },
+  options?: BindOptions,
 ): <K extends string>(
   target: DataProviderKeyHost<U> & { [P in K]?: T | null | undefined },
   propertyKey: K,
 ) => void;
 export function bind(
   pathOrKey: string | DataProviderKey<unknown, unknown>,
-  options?: { reflect?: boolean },
+  options?: BindOptions,
 ): (target: unknown, propertyKey: string) => void {
   const path = hasPath(pathOrKey) ? pathOrKey.path : pathOrKey;
   return bindImpl(path, options);

package/src/core/decorators/subscriber/dynamicPath.spec.ts

@@ -0,0 +1,53 @@
+import { describe, it, expect } from "vitest";
+import { resolveDynamicPath } from "./dynamicPath";
+
+describe("resolveDynamicPath", () => {
+  const host = { sessionId: "alpha", count: 0, label: "", missing: null as null };
+
+  it("est prêt avec une valeur définie", () => {
+    expect(resolveDynamicPath(host, "api/sessions/${sessionId}/sync")).toEqual({
+      ready: true,
+      path: "api/sessions/alpha/sync",
+    });
+  });
+
+  it("n'est pas prêt pour undefined/null", () => {
+    expect(resolveDynamicPath({}, "api/sessions/${sessionId}/sync")).toEqual({
+      ready: false,
+      path: null,
+    });
+    expect(
+      resolveDynamicPath({ sessionId: null }, "api/sessions/${sessionId}/sync"),
+    ).toEqual({ ready: false, path: null });
+  });
+
+  it("insère 0 et false par défaut", () => {
+    expect(resolveDynamicPath(host, "items/${count}")).toEqual({
+      ready: true,
+      path: "items/0",
+    });
+    expect(
+      resolveDynamicPath({ flag: false }, "flags/${flag}"),
+    ).toEqual({ ready: true, path: "flags/false" });
+  });
+
+  it("accepte une chaîne vide par défaut", () => {
+    expect(resolveDynamicPath(host, "api/sessions/${label}/sync")).toEqual({
+      ready: true,
+      path: "api/sessions//sync",
+    });
+  });
+
+  it("skipEmptyPlaceholder: true — chaîne vide non prête", () => {
+    expect(
+      resolveDynamicPath(host, "api/sessions/${label}/sync", {
+        skipEmptyPlaceholder: true,
+      }),
+    ).toEqual({ ready: false, path: null });
+    expect(
+      resolveDynamicPath(host, "api/sessions/${sessionId}/sync", {
+        skipEmptyPlaceholder: true,
+      }),
+    ).toEqual({ ready: true, path: "api/sessions/alpha/sync" });
+  });
+});

package/src/core/decorators/subscriber/dynamicPath.ts

@@ -1,5 +1,17 @@
 /** Lit / décorateurs : chemins publisher avec `${prop}` ou `{$prop}`. */
 
+/**
+ * Options de résolution des placeholders dynamiques.
+ * `skipEmptyPlaceholder` ne concerne que les chaînes vides `''` — pas `0`, `false`, `null`, etc.
+ */
+export type DynamicPathOptions = {
+  /**
+   * Si `true`, un placeholder résolu en `''` est traité comme non prêt (`ready: false`).
+   * N'affecte pas les autres valeurs (`0` → `"0"`, `false` → `"false"`, …).
+   */
+  skipEmptyPlaceholder?: boolean;
+};
+
 export function cleanPlaceholder(value: string): string {
   return value.trim().replace(/^this\./, "");
 }
@@ -25,15 +37,25 @@ export function getValueFromExpression(
   return current;
 }
 
+function isPlaceholderUnresolved(
+  resolved: unknown,
+  options?: DynamicPathOptions,
+): boolean {
+  if (resolved === undefined || resolved === null) return true;
+  if (options?.skipEmptyPlaceholder && resolved === "") return true;
+  return false;
+}
+
 export function resolveDynamicPath(
   component: unknown,
   template: string,
+  options?: DynamicPathOptions,
 ): { ready: boolean; path: string | null } {
   let missing = false;
   const replaceValue = (_match: string, expression: string) => {
     const cleaned = cleanPlaceholder(expression);
     const resolved = getValueFromExpression(component, cleaned);
-    if (resolved === undefined || resolved === null) {
+    if (isPlaceholderUnresolved(resolved, options)) {
       missing = true;
       return "";
     }

package/src/core/decorators/subscriber/handle.ts

@@ -2,6 +2,7 @@ import type {
   DataProviderKey,
   DataProviderKeyHost,
 } from "../../utils/dataProviderKey";
+import type { DynamicPathOptions } from "./dynamicPath";
 import { createOnAssign, Skip } from "./onAssign";
 
 export { Skip } from "./onAssign";
@@ -14,7 +15,7 @@ export { Skip } from "./onAssign";
  * assignation**, même quand la valeur reçue est `null`/`undefined` (c'est la
  * différence de comportement voulue par rapport à `@onAssign`).
  */
-export type HandleOptions = {
+export type HandleOptions = DynamicPathOptions & {
   /**
    * Attendre que **toutes** les clés surveillées soient définies (non
    * `null`/`undefined`) avant d'appeler la méthode. Reproduit la sémantique
@@ -122,6 +123,7 @@ export function handle(
     {
       dispatchWhenUndefined: !options.waitForAllDefined,
       skip: options.skip,
+      skipEmptyPlaceholder: options.skipEmptyPlaceholder,
     },
     paths,
   );

package/src/core/decorators/subscriber/onAssign.ts

@@ -1,6 +1,10 @@
 import DataProvider from "../../utils/PublisherProxy";
 import { ConnectedComponent, setSubscribable } from "./common";
-import { extractDynamicDependencies, resolveDynamicPath } from "./dynamicPath";
+import {
+  type DynamicPathOptions,
+  extractDynamicDependencies,
+  resolveDynamicPath,
+} from "./dynamicPath";
 import {
   onAssignDynamicWatchKeys,
   observeDynamicProperty,
@@ -60,7 +64,7 @@ export function isSkipped(value: unknown, kinds: Skip[]): boolean {
   return kinds.some((kind) => SKIP_PREDICATES[kind](value));
 }
 
-export type OnAssignOptions = {
+export type OnAssignOptions = DynamicPathOptions & {
   /**
    * Quand `true`, le callback est invoqué à chaque assignation, même si la
    * valeur reçue est `null`/`undefined`.
@@ -125,6 +129,9 @@ export function createOnAssign(
       isDynamic: dynamicDependencies.length > 0,
     };
   });
+  const pathOptions: DynamicPathOptions = {
+    skipEmptyPlaceholder: options.skipEmptyPlaceholder,
+  };
 
   return function (
     target: unknown,
@@ -215,6 +222,7 @@ export function createOnAssign(
             const resolution = resolveDynamicPath(
               component,
               conf.pathConfig.originalPath,
+              pathOptions,
             );
             if (!resolution.ready) {
               subscribeToPath(conf, null);

package/src/core/decorators/subscriber/publish.ts

@@ -4,7 +4,13 @@ import type {
 } from "../../utils/dataProviderKey";
 import DataProvider from "../../utils/PublisherProxy";
 import { ConnectedComponent, setSubscribable } from "./common";
-import { extractDynamicDependencies, resolveDynamicPath } from "./dynamicPath";
+import {
+  type DynamicPathOptions,
+  extractDynamicDependencies,
+  resolveDynamicPath,
+} from "./dynamicPath";
+
+export type PublishOptions = DynamicPathOptions;
 import {
   publishDynamicWatchKeys,
   observeDynamicProperty,
@@ -29,11 +35,15 @@ import { getPublisherFromPath } from "./publisherPath";
  */
 export function publish<T, U = any>(
   key: DataProviderKey<T, U>,
+  options?: PublishOptions,
 ): <K extends string>(
   target: DataProviderKeyHost<U> & { [P in K]?: T | null | undefined },
   propertyKey: K,
 ) => void {
   const path = key.path;
+  const pathOptions: DynamicPathOptions = {
+    skipEmptyPlaceholder: options?.skipEmptyPlaceholder,
+  };
   const dynamicDependencies = extractDynamicDependencies(path);
 
   return function (target: object, propertyKey: string) {
@@ -93,7 +103,7 @@ export function publish<T, U = any>(
       const updatePublisher = () => {
         let resolvedPath: string | null;
         if (dynamicDependencies.length) {
-          const resolution = resolveDynamicPath(component, path);
+          const resolution = resolveDynamicPath(component, path, pathOptions);
           resolvedPath = resolution.ready ? resolution.path : null;
         } else {
           resolvedPath = path;

package/src/core/utils/PublisherProxy.ts

@@ -28,6 +28,24 @@ type PublisherProxyOptions = {
   invalidateOnPageShow?: boolean;
 };
 
+/** Options de `dp()` / `dataProvider()` — même surface que `PublisherManager.get()`. */
+export type DpOptions = PublisherProxyOptions;
+
+const DP_OPTION_KEYS = new Set<keyof DpOptions>([
+  "localStorageMode",
+  "expirationDelayMs",
+  "invalidateOnPageShow",
+]);
+
+function isDpOptions(value: unknown): value is DpOptions {
+  if (value == null || typeof value !== "object" || Array.isArray(value)) {
+    return false;
+  }
+  return Object.keys(value).some((key) =>
+    DP_OPTION_KEYS.has(key as keyof DpOptions),
+  );
+}
+
 function isLeaf(value: any) {
   return Object.prototype.hasOwnProperty.call(value, "__value");
 }
@@ -1041,6 +1059,7 @@ try {
 
 export const getObservables = <T = any>(
   observable: string,
+  options?: DpOptions,
 ): Set<DataProvider<T>> => {
   if (typeof observable === "function") {
     const func = observable as () => any;
@@ -1051,7 +1070,7 @@ export const getObservables = <T = any>(
   if (typeof observable === "string") {
     const split = observable.split(".");
     const dataProvider: string = split.shift() || "";
-    let publisher = PublisherManager.get(dataProvider);
+    let publisher = PublisherManager.get(dataProvider, options);
     publisher = Objects.traverse(publisher, split);
     const set = new Set<DataProvider<T>>();
     set.add(publisher as DataProvider<T>);
@@ -1068,9 +1087,14 @@ export function get<T>(id: string | DataProviderKey<T>): T {
   return getObservables<T>(path).values().next().value?.get() as T;
 }
 
-function deepee<T>(id: string | DataProviderKey<T>, _defaultValue?: T) {
+function deepee<T>(
+  id: string | DataProviderKey<T>,
+  _defaultValue?: T,
+  options?: DpOptions,
+) {
   const path = resolveStaticPublisherPath(id);
-  const value = getObservables<T>(path).values().next().value as DataProvider<T>;
+  const value = getObservables<T>(path, options).values().next()
+    .value as DataProvider<T>;
   // if (defaultValue !== undefined && value) {
   //   const innerValue = value.get();
   //   if (Objects.isEmpty(innerValue as Record<string, any>)) {
@@ -1081,19 +1105,79 @@ function deepee<T>(id: string | DataProviderKey<T>, _defaultValue?: T) {
   return value;
 }
 
-export function dataProvider<T>(id: DataProviderKey<T>, defaultValue?: T): DataProvider<T>;
-export function dataProvider<T = any>(id: string, defaultValue?: T): DataProvider<T>;
+type MirrorDpSource = DataProvider<any> | string | DataProviderKey<any>;
+
+function isDataProvider(value: unknown): value is DataProvider<any> {
+  return (
+    value != null &&
+    typeof value === "object" &&
+    typeof (value as DataProvider<any>).get === "function" &&
+    typeof (value as DataProvider<any>).set === "function" &&
+    typeof (value as DataProvider<any>).onAssign === "function"
+  );
+}
+
+function resolvePublisherRef(
+  ref: MirrorDpSource,
+  options?: DpOptions,
+): DataProvider<any> {
+  if (isDataProvider(ref)) return ref;
+  return deepee(ref, undefined, options);
+}
+
+export function dataProvider<T>(
+  id: DataProviderKey<T>,
+  options: DpOptions,
+): DataProvider<T>;
+export function dataProvider<T = any>(id: string, options: DpOptions): DataProvider<T>;
+export function dataProvider<T>(id: DataProviderKey<T>): DataProvider<T>;
+export function dataProvider<T = any>(id: string): DataProvider<T>;
+export function dataProvider<T>(id: DataProviderKey<T>, defaultValue: T): DataProvider<T>;
+export function dataProvider<T = any>(id: string, defaultValue: T): DataProvider<T>;
 export function dataProvider<T>(
   id: string | DataProviderKey<T>,
-  defaultValue?: T,
+  second?: T | DpOptions,
 ): DataProvider<T> {
-  return deepee(id, defaultValue);
+  if (isDpOptions(second)) return deepee(id, undefined, second);
+  return deepee(id, second as T | undefined);
 }
 
-export function dp<T>(id: DataProviderKey<T>, defaultValue?: T): DataProvider<T>;
-export function dp<T = any>(id: string, defaultValue?: T): DataProvider<T>;
-export function dp<T>(id: string | DataProviderKey<T>, defaultValue?: T): DataProvider<T> {
-  return deepee(id, defaultValue);
+export function dp<T>(id: DataProviderKey<T>, options: DpOptions): DataProvider<T>;
+export function dp<T = any>(id: string, options: DpOptions): DataProvider<T>;
+export function dp<T>(id: DataProviderKey<T>): DataProvider<T>;
+export function dp<T = any>(id: string): DataProvider<T>;
+export function dp<T>(id: DataProviderKey<T>, defaultValue: T): DataProvider<T>;
+export function dp<T = any>(id: string, defaultValue: T): DataProvider<T>;
+export function dp<T>(
+  id: string | DataProviderKey<T>,
+  second?: T | DpOptions,
+): DataProvider<T> {
+  if (isDpOptions(second)) return deepee(id, undefined, second);
+  return deepee(id, second as T | undefined);
+}
+
+/**
+ * Alias sémantique pour `PublisherManager.set` : enregistre `aliasKey` sur la même
+ * instance publisher que `source`. Utile pour exposer une clé legacy (`scan`) tout en
+ * stockant l'état sous une racine (`app.scan`) — `dp("scan")` et `appState.scan` partagent
+ * alors la même instance, sans copie à chaque assignation.
+ */
+export function mirrorDp<T>(
+  aliasKey: string | DataProviderKey<any>,
+  source: DataProvider<T>,
+): void;
+export function mirrorDp(
+  aliasKey: string | DataProviderKey<any>,
+  source: string | DataProviderKey<any>,
+): void;
+export function mirrorDp(
+  aliasKey: string | DataProviderKey<any>,
+  source: DataProvider<any> | string | DataProviderKey<any>,
+): void {
+  PublisherManager.getInstance().set(
+    resolveStaticPublisherPath(aliasKey),
+    resolvePublisherRef(source),
+  );
 }
 
 export function set<T>(id: DataProviderKey<T>, value: T): void;

package/src/core/utils/api.ts

@@ -37,8 +37,8 @@ export type APIResponse = {
   processed: ResultTypeInterface;
 };
 
-/** Valeur assignée par `@get` : requête native, réponse `fetch` si HTTP, résultat métier typé `T`. */
-export type ApiGetResult<T> = {
+/** Valeur assignée par `@get`, `@post`, `@put`, `@patch`. */
+export type ApiResult<T> = {
   request: Request;
   /** Absent / `undefined` pour les chemins `dataProvider(...)` (pas d’appel réseau). */
   response?: Response;
@@ -46,6 +46,9 @@ export type ApiGetResult<T> = {
   result: T;
 };
 
+/** @deprecated Utiliser `ApiResult`. */
+export type ApiGetResult<T> = ApiResult<T>;
+
 /** Extrait le corps typé depuis le résultat traité par `handleResult`. */
 export function extractTypedApiResult<T>(
   processed: ResultTypeInterface | null | undefined,
@@ -434,7 +437,7 @@ class API {
   async getDetailed<T>(
     path: string,
     additionalHeaders?: HeadersInit,
-  ): Promise<ApiGetResult<T> | undefined> {
+  ): Promise<ApiResult<T> | undefined> {
     const isDataProvider = /dataProvider\((.*?)\)(.*?)$/.test(path);
 
     const processed = await this.get<T>(path, additionalHeaders);
@@ -468,6 +471,72 @@ class API {
     };
   }
 
+  /**
+   * S’appuie sur `post()` puis reformate la réponse : `Request` avec body JSON,
+   * `Response` via `lastResult`, `result` typé `T`.
+   */
+  async sendDetailed<T, B>(
+    path: string,
+    body: B,
+    method: "POST" | "PUT" | "PATCH",
+    additionalHeaders?: HeadersInit,
+  ): Promise<ApiResult<T> | undefined> {
+    const processed = await this.send<T, B>(
+      path,
+      body,
+      method,
+      additionalHeaders,
+    );
+    if (processed == null) {
+      return undefined;
+    }
+
+    const result = extractTypedApiResult<T>(processed as ResultTypeInterface);
+    const url = this.computeURL(path);
+    const headers = await this.createHeaders({
+      Accept: "application/json",
+      "Content-Type": "application/json",
+      ...(additionalHeaders as Record<string, string> | undefined),
+    });
+    const request = new Request(url, {
+      method,
+      headers: new Headers(headers as HeadersInit),
+      credentials: this.credentials,
+      body: JSON.stringify(body),
+      keepalive: this.keepAlive,
+    });
+
+    return {
+      request,
+      response: this.lastResult,
+      result,
+    };
+  }
+
+  async postDetailed<T, B>(
+    path: string,
+    body: B,
+    additionalHeaders?: HeadersInit,
+  ): Promise<ApiResult<T> | undefined> {
+    return this.sendDetailed<T, B>(path, body, "POST", additionalHeaders);
+  }
+
+  async putDetailed<T, B>(
+    path: string,
+    body: B,
+    additionalHeaders?: HeadersInit,
+  ): Promise<ApiResult<T> | undefined> {
+    return this.sendDetailed<T, B>(path, body, "PUT", additionalHeaders);
+  }
+
+  async patchDetailed<T, B>(
+    path: string,
+    body: B,
+    additionalHeaders?: HeadersInit,
+  ): Promise<ApiResult<T> | undefined> {
+    return this.sendDetailed<T, B>(path, body, "PATCH", additionalHeaders);
+  }
+
   /**
    * Création du header, avec authentification si besoin
    * ajout du language via le header accept-language qui contient le langue du navigateur

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/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/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/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.