@supersoniks/concorde 4.7.4 → 4.8.0

package/src/docs/search/docs-search.json

@@ -3245,7 +3245,7 @@
     }
   },
   {
-    "search": "Dynamic paths (users.${userId}) → decorators or sub() — not get("users.${id}") in imperative code.\n",
+    "search": "Dynamic paths (users.${userId}) → decorators or sub() — not get("users.${id}") in imperative code. Resolution rules: Dynamic path placeholders.\n",
     "files": {
       "docs/_core-concept/dataFlow.md": {
         "title": "Data flow",
@@ -4340,7 +4340,7 @@
     }
   },
   {
-    "search": "See also: @subscribe, @handle, @publish, @get.\n",
+    "search": "See also: @subscribe, @handle, @publish, @get, @post, @put, @patch.\n",
     "files": {
       "docs/_decorators/bind.md": {
         "title": "@bind",
@@ -4550,7 +4550,7 @@
     }
   },
   {
-    "search": "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.\n",
+    "search": "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.\n",
     "files": {
       "docs/_decorators/bind.md": {
         "title": "@bind",
@@ -4625,7 +4625,7 @@
     }
   },
   {
-    "search": "Loads data through API.getDetailed. The decorated property is ApiGetResult<T> | null: request, response (or null for dataProvider(...) resolution without HTTP), and typed result.\n",
+    "search": "Loads data through API.getDetailed. The decorated property is ApiResult<T> | null: request, response (or null for dataProvider(...) resolution without HTTP), and typed result.\n",
     "files": {
       "docs/_decorators/get.md": {
         "title": "@get",
@@ -4640,7 +4640,7 @@
     }
   },
   {
-    "search": "Pass an Endpoint<T> as the first argument. Import get and ApiGetResult from @supersoniks/concorde/decorators, and Endpoint from @supersoniks/concorde/utils/endpoint.\n",
+    "search": "Pass an Endpoint<T> as the first argument. Import get and ApiResult from @supersoniks/concorde/decorators, and Endpoint from @supersoniks/concorde/utils/endpoint.\n",
     "files": {
       "docs/_decorators/get.md": {
         "title": "@get",
@@ -4654,6 +4654,21 @@
       }
     }
   },
+  {
+    "search": "${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.\n",
+    "files": {
+      "docs/_decorators/get.md": {
+        "title": "@get",
+        "hashes": {
+          "dynamic-path": {
+            "count": 1,
+            "title": "Dynamic path",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
   {
     "search": "Same demo service as sonic-queue (/docs-mock-api/geo/). Publisher setup lives in decorators-demo-geo.ts and decorators-demo-subscribe-publish-get-demos.ts.\n",
     "files": {
@@ -4711,6 +4726,16 @@
             "type": "paragraph"
           }
         }
+      },
+      "docs/_decorators/post.md": {
+        "title": "@post",
+        "hashes": {
+          "live-demos": {
+            "count": 1,
+            "title": "Live demos",
+            "type": "paragraph"
+          }
+        }
       }
     }
   },
@@ -5030,7 +5055,22 @@
     }
   },
   {
-    "search": "See also DataProviderKey.\n",
+    "search": "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.\n",
+    "files": {
+      "docs/_decorators/handle.md": {
+        "title": "@handle",
+        "hashes": {
+          "skipemptyplaceholder": {
+            "count": 1,
+            "title": "`skipEmptyPlaceholder`",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "See also DataProviderKey and Dynamic path placeholders.\n",
     "files": {
       "docs/_decorators/handle.md": {
         "title": "@handle",
@@ -5269,6 +5309,21 @@
       }
     }
   },
+  {
+    "search": "While a placeholder is null/undefined, subscriptions are detached. Optional skipEmptyPlaceholder on @handle (typed replacement). Details: Dynamic path placeholders.\n",
+    "files": {
+      "docs/_decorators/on-assign.md": {
+        "title": "@onAssign",
+        "hashes": {
+          "dynamic-path-driven-by-class-properties": {
+            "count": 1,
+            "title": "Dynamic path driven by class properties",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
   {
     "search": "  @property({ type: String })\n  dataProvider: "demoUsers" | "demoUsersAlt" = "demoUsers";\n",
     "files": {
@@ -5569,6 +5624,266 @@
       }
     }
   },
+  {
+    "search": "@patch",
+    "files": {
+      "docs/_decorators/patch.md": {
+        "title": "@patch",
+        "hashes": {
+          "patch": {
+            "count": 1,
+            "title": "",
+            "type": "page"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Sends data through API.patchDetailed. Same model as @post: decorated property is ApiResult<T> | null (request, response, result).\n",
+    "files": {
+      "docs/_decorators/patch.md": {
+        "title": "@patch",
+        "hashes": {
+          "patch": {
+            "count": 1,
+            "title": "",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Pass an Endpoint<T> and a DataProviderKey for the request body. Import patch and ApiResult from @supersoniks/concorde/decorators.\n",
+    "files": {
+      "docs/_decorators/patch.md": {
+        "title": "@patch",
+        "hashes": {
+          "patch": {
+            "count": 1,
+            "title": "",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Same as @post / @get: scoped HTML.getApiConfiguration(host) or DataProviderKey<APIConfiguration> as third argument.\n",
+    "files": {
+      "docs/_decorators/patch.md": {
+        "title": "@patch",
+        "hashes": {
+          "configuration": {
+            "count": 1,
+            "title": "Configuration",
+            "type": "paragraph"
+          }
+        }
+      },
+      "docs/_decorators/put.md": {
+        "title": "@put",
+        "hashes": {
+          "configuration": {
+            "count": 1,
+            "title": "Configuration",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Same shape as PostOptions on @post (ApiSendOptions): refetchEveryMs, skipIfBodyMissing, autoPostOnBodyMutation, triggerKey, skipEmptyPlaceholder. See Dynamic path placeholders for ${sessionId} and empty-string behaviour.\n",
+    "files": {
+      "docs/_decorators/patch.md": {
+        "title": "@patch",
+        "hashes": {
+          "options-patchoptions": {
+            "count": 1,
+            "title": "Options (`PatchOptions`)",
+            "type": "paragraph"
+          }
+        }
+      },
+      "docs/_decorators/put.md": {
+        "title": "@put",
+        "hashes": {
+          "options-putoptions": {
+            "count": 1,
+            "title": "Options (`PutOptions`)",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "@patch(\n  new Endpoint<Resource, { resourceId: string }>("resources/${resourceId}"),\n  patchBodyKey,\n  { skipEmptyPlaceholder: true },\n)\n@state()\npayload?: ApiResult<Resource> | null;\n  \n\n",
+    "files": {
+      "docs/_decorators/patch.md": {
+        "title": "@patch",
+        "hashes": {
+          "example": {
+            "count": 1,
+            "title": "Example",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "@post",
+    "files": {
+      "docs/_decorators/post.md": {
+        "title": "@post",
+        "hashes": {
+          "post": {
+            "count": 1,
+            "title": "",
+            "type": "page"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Sends data through API.postDetailed. The decorated property is ApiResult<T> | null: request, response, and typed result.\n",
+    "files": {
+      "docs/_decorators/post.md": {
+        "title": "@post",
+        "hashes": {
+          "post": {
+            "count": 1,
+            "title": "",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Pass an Endpoint<T> 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.\n",
+    "files": {
+      "docs/_decorators/post.md": {
+        "title": "@post",
+        "hashes": {
+          "post": {
+            "count": 1,
+            "title": "",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Same as @get: scoped HTML.getApiConfiguration(host) by default, or DataProviderKey<APIConfiguration> as third argument. See API configuration for mock demos.\n",
+    "files": {
+      "docs/_decorators/post.md": {
+        "title": "@post",
+        "hashes": {
+          "configuration": {
+            "count": 1,
+            "title": "Configuration",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Mock service: POST /docs-mock-api/api/register (same route as sonic-submit demos). Publisher setup lives in decorators-demo-post.ts.\n",
+    "files": {
+      "docs/_decorators/post.md": {
+        "title": "@post",
+        "hashes": {
+          "minimal-example": {
+            "count": 1,
+            "title": "Minimal example",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "@post(\n  new Endpoint<SyncResponse, { sessionId: string }>("sessions/${sessionId}/sync"),\n  syncRequest,\n  { triggerKey: syncTrigger },\n)\n@state()\npayload?: ApiResult<SyncResponse> | null;\n  \n\n",
+    "files": {
+      "docs/_decorators/post.md": {
+        "title": "@post",
+        "hashes": {
+          "minimal-example": {
+            "count": 1,
+            "title": "Minimal example",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Dynamic endpoint path — changing sessionId on the host re-runs the POST (POST /docs-mock-api/api/sessions/{id}/sync):\n",
+    "files": {
+      "docs/_decorators/post.md": {
+        "title": "@post",
+        "hashes": {
+          "live-demos": {
+            "count": 1,
+            "title": "Live demos",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "@post + @publish on the same property (see @publish):\n",
+    "files": {
+      "docs/_decorators/post.md": {
+        "title": "@post",
+        "hashes": {
+          "live-demos": {
+            "count": 1,
+            "title": "Live demos",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "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).\n",
+    "files": {
+      "docs/_decorators/post.md": {
+        "title": "@post",
+        "hashes": {
+          "live-demos": {
+            "count": 1,
+            "title": "Live demos",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Path placeholders (${sessionId}, …): Dynamic path placeholders.\n",
+    "files": {
+      "docs/_decorators/post.md": {
+        "title": "@post",
+        "hashes": {
+          "live-demos": {
+            "count": 1,
+            "title": "Live demos",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
   {
     "search": "@publish",
     "files": {
@@ -5615,7 +5930,7 @@
     }
   },
   {
-    "search": "Dynamic paths use the same placeholder rules as @bind / @subscribe.\n",
+    "search": "Dynamic paths use the same placeholder rules as @bind / @subscribe. Resolution and skipEmptyPlaceholder: Dynamic path placeholders.\n",
     "files": {
       "docs/_decorators/publish.md": {
         "title": "@publish",
@@ -5629,6 +5944,81 @@
       }
     }
   },
+  {
+    "search": "@put",
+    "files": {
+      "docs/_decorators/put.md": {
+        "title": "@put",
+        "hashes": {
+          "put": {
+            "count": 1,
+            "title": "",
+            "type": "page"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Sends data through API.putDetailed. Same model as @post: decorated property is ApiResult<T> | null (request, response, result).\n",
+    "files": {
+      "docs/_decorators/put.md": {
+        "title": "@put",
+        "hashes": {
+          "put": {
+            "count": 1,
+            "title": "",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Pass an Endpoint<T> and a DataProviderKey for the request body. Import put and ApiResult from @supersoniks/concorde/decorators.\n",
+    "files": {
+      "docs/_decorators/put.md": {
+        "title": "@put",
+        "hashes": {
+          "put": {
+            "count": 1,
+            "title": "",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "@put(new Endpoint<Resource, { resourceId: string }>("resources/${resourceId}"), bodyKey)\n@state()\npayload?: ApiResult<Resource> | null;\n  \n\n",
+    "files": {
+      "docs/_decorators/put.md": {
+        "title": "@put",
+        "hashes": {
+          "example": {
+            "count": 1,
+            "title": "Example",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Changing resourceId on the host re-runs the PUT when the path becomes ready — see Dynamic path placeholders.\n",
+    "files": {
+      "docs/_decorators/put.md": {
+        "title": "@put",
+        "hashes": {
+          "example": {
+            "count": 1,
+            "title": "Example",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
   {
     "search": "@subscribe",
     "files": {
@@ -5750,7 +6140,22 @@
     }
   },
   {
-    "search": "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:\n",
+    "search": "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.\n",
+    "files": {
+      "docs/_decorators/subscribe.md": {
+        "title": "@subscribe",
+        "hashes": {
+          "dynamic-path-and-scope": {
+            "count": 1,
+            "title": "Dynamic path and scope",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Declare dynamic props in the key’s second generic so TypeScript expects them on the host:\n",
     "files": {
       "docs/_decorators/subscribe.md": {
         "title": "@subscribe",
@@ -6230,7 +6635,7 @@
     }
   },
   {
-    "search": "Like @subscribe: the path is resolved on the template host component; the directive re-subscribes when observed props change.\n",
+    "search": "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 (skipEmptyPlaceholder not available on sub() yet).\n",
     "files": {
       "docs/_directives/sub.md": {
         "title": "sub()",
@@ -7165,7 +7570,7 @@
     }
   },
   {
-    "search": "The second generic ({ dataProvider: string | null }) lists what the host must expose so "${dataProvider}" can be resolved. See DataProviderKey.\n",
+    "search": "The second generic ({ dataProvider: string | null }) lists what the host must expose so "${dataProvider}" can be resolved. See DataProviderKey and Dynamic path placeholders.\n",
     "files": {
       "docs/_getting-started/my-first-component.md": {
         "title": "My first component",
@@ -7915,7 +8320,7 @@
     }
   },
   {
-    "search": "APIConfiguration is the object built by HTML.getApiConfiguration from ancestor attributes on the DOM (or from a typed publisher — see @get configuration key). It is passed to API by fetchers, sonic-submit, the wording() directive, and @get.\n",
+    "search": "APIConfiguration is the object built by HTML.getApiConfiguration from ancestor attributes on the DOM (or from a typed publisher — see @get / @post configuration key). It is passed to API by fetchers, sonic-submit, the wording() directive, @get, @post, @put, and @patch.\n",
     "files": {
       "docs/_misc/api-configuration.md": {
         "title": "API configuration",
@@ -8185,7 +8590,7 @@
     }
   },
   {
-    "search": "Use placeholders ${prop} or {$prop} in the path string. The path is resolved at runtime from the component's properties. The type remains declarative:\n",
+    "search": "Use placeholders ${prop} or {$prop} in the path string. The path is resolved at runtime from the component's properties. See Dynamic path placeholders for resolution rules and skipEmptyPlaceholder. The type remains declarative:\n",
     "files": {
       "docs/_misc/dataProviderKey.md": {
         "title": "DataProviderKey",
@@ -8275,7 +8680,7 @@
     }
   },
   {
-    "search": "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 for method callbacks.\n",
+    "search": "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. See @handle for method callbacks.\n",
     "files": {
       "docs/_misc/dataProviderKey.md": {
         "title": "DataProviderKey",
@@ -8364,6 +8769,126 @@
       }
     }
   },
+  {
+    "search": "Dynamic path placeholders",
+    "files": {
+      "docs/_misc/dynamic-path.md": {
+        "title": "Dynamic path placeholders",
+        "hashes": {
+          "dynamic-path-placeholders": {
+            "count": 1,
+            "title": "",
+            "type": "page"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Decorators and DataProviderKey paths can include placeholders resolved on the host component at runtime:\n",
+    "files": {
+      "docs/_misc/dynamic-path.md": {
+        "title": "Dynamic path placeholders",
+        "hashes": {
+          "dynamic-path-placeholders": {
+            "count": 1,
+            "title": "",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Resolution is done by resolveDynamicPath. The root property names (userId, sessionId, …) are watched via requestAnimationFrame (see dynamicPropertyWatch.ts).\n",
+    "files": {
+      "docs/_misc/dynamic-path.md": {
+        "title": "Dynamic path placeholders",
+        "hashes": {
+          "dynamic-path-placeholders": {
+            "count": 1,
+            "title": "",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "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).\n",
+    "files": {
+      "docs/_misc/dynamic-path.md": {
+        "title": "Dynamic path placeholders",
+        "hashes": {
+          "default-behaviour-ready--not-ready": {
+            "count": 1,
+            "title": "Default behaviour (`ready` / `not ready`)",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "When the placeholder later becomes valid, observers run again and behaviour resumes.\n",
+    "files": {
+      "docs/_misc/dynamic-path.md": {
+        "title": "Dynamic path placeholders",
+        "hashes": {
+          "default-behaviour-ready--not-ready": {
+            "count": 1,
+            "title": "Default behaviour (`ready` / `not ready`)",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Some APIs should not run while an id is still "". Opt in per decorator:\n",
+    "files": {
+      "docs/_misc/dynamic-path.md": {
+        "title": "Dynamic path placeholders",
+        "hashes": {
+          "skipemptyplaceholder-option": {
+            "count": 1,
+            "title": "`skipEmptyPlaceholder` option",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Does not affect 0, false, null, or undefined (nullish stays “not ready” regardless).\n",
+    "files": {
+      "docs/_misc/dynamic-path.md": {
+        "title": "Dynamic path placeholders",
+        "hashes": {
+          "skipemptyplaceholder-option": {
+            "count": 1,
+            "title": "`skipEmptyPlaceholder` option",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
+  {
+    "search": "Available on:\n",
+    "files": {
+      "docs/_misc/dynamic-path.md": {
+        "title": "Dynamic path placeholders",
+        "hashes": {
+          "skipemptyplaceholder-option": {
+            "count": 1,
+            "title": "`skipEmptyPlaceholder` option",
+            "type": "paragraph"
+          }
+        }
+      }
+    }
+  },
   {
     "search": "Endpoint",
     "files": {
@@ -8395,7 +8920,7 @@
     }
   },
   {
-    "search": "The optional second generic U (default any) describes host properties used to resolve dynamic segments in the path (${…} / {$…}), for example with the @get decorator.\n",
+    "search": "The optional second generic U (default any) describes host properties used to resolve dynamic segments in the path (${…} / {$…}), for example with @get or @post. See Dynamic path placeholders for null / undefined / "" / 0 and skipEmptyPlaceholder.\n",
     "files": {
       "docs/_misc/endpoint.md": {
         "title": "Endpoint",
@@ -8440,7 +8965,7 @@
     }
   },
   {
-    "search": "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).\n",
+    "search": "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).\n",
     "files": {
       "docs/_misc/endpoint.md": {
         "title": "Endpoint",