@supersoniks/concorde 5.1.2 → 5.1.3-immutable.1

package/docs/crawl/hubs/decorators.html

@@ -0,0 +1,547 @@
+<!DOCTYPE html>
+<html lang="fr" data-crawl-url="https://concorde.supersoniks.org/crawl/hubs/decorators.html" data-doc-id="hubs/decorators">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Concorde decorators reference — Concorde</title>
+  <meta name="description" content="Hub for all Concorde Lit decorators: @get @post @put @patch @subscribe @publish @bind @handle and related. Use this page when asking about any decorator.">
+  <meta name="keywords" content="decorator, @get, @post, @put, @patch, @subscribe, @publish, @bind, @handle, ApiResult, Endpoint, DataProviderKey">
+  <meta name="concorde-doc-id" content="hubs/decorators">
+  <link rel="canonical" href="https://concorde.supersoniks.org/crawl/hubs/decorators.html">
+</head>
+<body>
+  <header>
+    <p><a href="../index.html">Concorde documentation (crawl)</a></p>
+  </header>
+  <main>
+    <article>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde documentation — Concorde decorators reference</strong>. Hub for all Concorde Lit decorators: @get @post @put @patch @subscribe @publish @bind @handle and related. Use this page when asking about any decorator. <span>Doc ID: <code>hubs/decorators</code>. Keywords: decorator, @get, @post, @put, @patch, @subscribe, @publish, @bind, @handle, ApiResult, Endpoint, DataProviderKey. URL: <a href="https://concorde.supersoniks.org/crawl/hubs/decorators.html">https://concorde.supersoniks.org/crawl/hubs/decorators.html</a>.</span></p>
+      <section id="docs-_decorators-ancestor-attribute" data-doc-id="docs/_decorators/ancestor-attribute">
+  <h2><a href="../docs/_decorators/ancestor-attribute.html">@ancestorAttribute</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/_decorators/ancestor-attribute</code> · <a href="../docs/_decorators/ancestor-attribute.html">full page</a></p>
+  <p>The @ancestorAttribute decorator automatically injects the value of an ancestor's attribute into a class property at the time of connectedCallback.</p>
+  <pre class="doc-excerpt">@ancestorAttribute
+
+The @ancestorAttribute decorator automatically injects the value of an ancestor's attribute into a class property at the time of connectedCallback.
+
+Principle
+
+This decorator uses HTML.getAncestorAttributeValue to traverse up the DOM tree from the current element and find the first ancestor that has the specified attribute. The value of this attribute is then assigned to the decorated property.
+
+Usage
+
+Import
+
+import { ancestorAttribute } from &quot;@supersoniks/concorde/decorators&quot;;
+
+Basic example
+
+The component reads dataProvider and testAttribute from its ancestor wrapper. By default (dynamic: false), values are read once at connect.
+
+import { html, LitElement } from &quot;lit&quot;;
+import { customElement } from &quot;lit/decorators.js&quot;;
+import { ancestorAttribute } from &quot;@supersoniks/concorde/decorators&quot;;
+
+@customElement(&quot;demo-ancestor-attribute&quot;)
+export class DemoAncestorAttribute extends LitElement {
+  @ancestorAttribute(&quot;dataProvider&quot;)
+  dataProvider: string | null = null;
+
+  @ancestorAttribute(&quot;testAttribute&quot;)
+  testAttribute: string | null = null;
+
+  render() {
+    return html
+       dataProvider:  ${this.dataProvider ?? &quot;null&quot;}
+       testAttribute:  ${this.testAttribute</pre>
+</section>
+<section id="docs-_decorators-auto-subscribe" data-doc-id="docs/_decorators/auto-subscribe">
+  <h2><a href="../docs/_decorators/auto-subscribe.html">@autoSubscribe</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/_decorators/auto-subscribe</code> · <a href="../docs/_decorators/auto-subscribe.html">full page</a></p>
+  <p>&gt; Legacy: prefer @subscribe + DataProviderKey. Examples below may still show PublisherManager for existing codebases.</p>
+  <pre class="doc-excerpt">@autoSubscribe
+
+&gt; Legacy: prefer @subscribe + DataProviderKey. Examples below may still show PublisherManager for existing codebases.
+
+The @autoSubscribe decorator automatically detects which publishers are accessed within a method and subscribes to them. When any of these publishers change, the method is automatically re-executed.
+
+Principle
+
+This decorator wraps a method to track which publishers are accessed during its execution. It then subscribes to all accessed publishers, and when any of them change, the method is re-executed. This provides automatic reactivity without manually managing subscriptions.
+
+Usage
+
+Import
+
+import { autoSubscribe } from &quot;@supersoniks/concorde/decorators&quot;;
+
+Basic example
+
+@customElement(&quot;demo-auto-subscribe&quot;)
+export class DemoAutoSubscribe extends LitElement {
+  static styles = [tailwind];
+
+  @state() displayText: string = &quot;&quot;;
+  @state() computedValue: number = 0;
+
+  @autoSubscribe()
+  updateDisplay() {
+    const value1 = PublisherManager.get(&quot;autoValue1&quot;).get() || 0;
+    const value2 = PublisherManager.get(&quot;autoValue2&quot;).get() || 0;
+    this.computedValue = value1 + value2;
+    this.displayText = ${value1} + ${value2} = ${this.computedValue};
+  }
+
+ </pre>
+</section>
+<section id="docs-_decorators-bind" data-doc-id="docs/_decorators/bind">
+  <h2><a href="../docs/_decorators/bind.html">@bind</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/_decorators/bind</code> · <a href="../docs/_decorators/bind.html">full page</a></p>
+  <p>Binds a class property to a path in a publisher. The property updates when publisher data changes.</p>
+  <pre class="doc-excerpt">@bind
+
+Binds a class property to a path in a publisher. The property updates when publisher data changes.
+
+For Lit re-renders, also add @state() on the same property.
+
+See also: @subscribe, @handle, @publish, @get, @post, @put, @patch.
+
+Principle
+
+The decorator subscribes to the DataProvider store using dot notation or a DataProviderKey. Updates flow into the decorated property (Data flow).
+
+Import
+
+import { bind } from &quot;@supersoniks/concorde/decorators&quot;;
+
+Example
+
+@customElement(&quot;demo-bind&quot;)
+export class DemoBind extends LitElement {
+  static styles = [tailwind];
+
+  @bind(&quot;demoData.firstName&quot;)
+  @state()
+  firstName = &quot;&quot;;
+
+  @bind(&quot;demoData.lastName&quot;)
+  @state()
+  lastName: string = &quot;&quot;;
+
+  @bind(&quot;demoData.count&quot;)
+  @state()
+  count: number = 0;
+
+  render() {
+    return //......
+  }
+
+  updateData() {
+    set(demoDataKey, { ...get(demoDataKey), count: get(demoDataKey).count + 1 });
+    // see demo-bind in src/docs/example/decorators-demo-bind-demos.ts
+    const randomIndex = Math.floor(Math.random()  demoUsers.get().length);
+    const randomUser = demoUsers.get()[randomIndex];
+    demoData.set({
+      firstName: randomUser.firstName,
+      lastName: randomUser.lastName,
+      count:</pre>
+</section>
+<section id="docs-_decorators-get" data-doc-id="docs/_decorators/get">
+  <h2><a href="../docs/_decorators/get.html">@get</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/_decorators/get</code> · <a href="../docs/_decorators/get.html">full page</a></p>
+  <p>@get loads data and stores the result in an optional ApiResult&lt;T&gt; property.</p>
+  <pre class="doc-excerpt">@get
+
+@get loads data and stores the result in an optional ApiResult  property.
+The property is undefined until a result is available.
+
+- payload.result: typed data;
+- payload.response: the HTTP response;
+- payload.request: the request that was sent.
+
+Minimal usage
+
+const usersEndpoint = new Endpoint (&quot;users&quot;);
+
+@get(usersEndpoint)
+@state()
+payload?: ApiResult ;
+
+The same decorator adapts to a method. The method receives the complete
+ApiResult  payload after each GET:
+
+@get(usersEndpoint)
+handleUsers(payload?: ApiResult ) {
+  if (!payload) return;
+
+  console.log(payload.response?.status);
+  console.log(payload.result);
+}
+
+The first argument is always an
+Endpoint . API configuration is read
+from the HTML scope (serviceURL, token, etc.), so the component is usually
+placed below an element that provides this configuration.
+
+Refetching a GET
+
+From the component
+
+Keep the decorator in a constant to access refetch(component). Refetch only
+targets the instance passed as the argument, even before it has received a
+result.
+
+const usersGet = get(new Endpoint (&quot;users&quot;));
+
+@usersGet
+@state()
+payload?: ApiResult ;
+
+async refresh() {
+  const payload = await usersGet.refetch(this);
+  console.log(</pre>
+</section>
+<section id="docs-_decorators-handle" data-doc-id="docs/_decorators/handle">
+  <h2><a href="../docs/_decorators/handle.html">@handle</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/_decorators/handle</code> · <a href="../docs/_decorators/handle.html">full page</a></p>
+  <p>Typed callback on one or more DataProviderKey&lt;T&gt; paths: invokes the decorated method when a publisher assigns a value (calculations, side effects, updating other @state properties, etc.).</p>
+  <pre class="doc-excerpt">@handle
+
+Typed callback on one or more DataProviderKey  paths: invokes the decorated method when a publisher assigns a value (calculations, side effects, updating other @state properties, etc.).
+
+Unlike @subscribe, nothing is bound to the decorated member — only your method runs. @handle is typed and accepts up to 3 keys plus an optional trailing HandleOptions object. It supersedes the string-based @onAssign.
+
+By default the method is called on every assignment, even when the value is null / undefined. Use the options below to restrict that.
+
+Import
+
+import { handle, Skip } from &quot;@supersoniks/concorde/decorators&quot;;
+import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+import { get, set } from &quot;@supersoniks/concorde/utils&quot;;
+
+Basic example
+
+type DemoCounterData = { count: number };
+const demoDataKey = new DataProviderKey&amp;lt;DemoCounterData&amp;gt;(&quot;demoData&quot;);
+
+@customElement(&quot;demo-handle&quot;)
+export class DemoHandle extends LitElement {
+  @state() doubled = 0;
+  @state() lastUpdate = &quot;&quot;;
+
+  @handle(demoDataKey.count)
+  onCountChange(count: number) {
+    this.doubled = count  2;
+    this.lastUpdate = new Date().toLocaleTimeString();
+  }
+
+  incrementCount() {
+    const data</pre>
+</section>
+<section id="docs-_decorators-on-assign" data-doc-id="docs/_decorators/on-assign">
+  <h2><a href="../docs/_decorators/on-assign.html">@onAssign</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/_decorators/on-assign</code> · <a href="../docs/_decorators/on-assign.html">full page</a></p>
+  <p>&gt; New apps: use @handle with DataProviderKey (Data flow). @onAssign uses untyped string paths; it remains documented for existing codebases — see Migrating to @handle below.</p>
+  <pre class="doc-excerpt">@onAssign
+
+&gt; New apps: use @handle with DataProviderKey (Data flow). @onAssign uses untyped string paths; it remains documented for existing codebases — see Migrating to @handle below.
+
+The @onAssign decorator allows you to execute a method when one or more publishers are updated. The method is called only when all specified publishers have been assigned values.
+
+For a typed equivalent (recommended), use @handle.
+
+Principle
+
+This decorator subscribes to one or more publishers by string path (legacy). When all specified publishers have been assigned values (via set), the decorated method is called with all the values as arguments. Prefer @handle + DataProviderKey and get / set from Data flow.
+
+This is particularly useful when you need to wait for multiple data sources to be ready before executing logic.
+
+Usage
+
+Import
+
+import { onAssign } from &quot;@supersoniks/concorde/decorators&quot;;
+
+Basic example
+
+//...
+@customElement(&quot;demo-on-assign&quot;)
+export class DemoOnAssign extends LitElement {
+  static styles = [tailwind];
+
+  @state() userWithSettings: any = null;
+  @state() isReady: boolean = false;
+  @state() lastUpdate: string = &quot;&quot;;
+
+  @onAssign(&quot;demoUser&quot;, &quot;demoUserSettings&quot;)
+  handleDataReady</pre>
+</section>
+<section id="docs-_decorators-patch" data-doc-id="docs/_decorators/patch">
+  <h2><a href="../docs/_decorators/patch.html">@patch</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/_decorators/patch</code> · <a href="../docs/_decorators/patch.html">full page</a></p>
+  <p>@patch applies a partial update with the body from a publisher. It uses the</p>
+  <pre class="doc-excerpt">@patch
+
+@patch applies a partial update with the body from a publisher. It uses the
+same model as @post:
+Endpoint , DataProviderKey , ApiResult , options, and the
+send(component) handle.
+
+Minimal usage
+
+const bodyKey = new DataProviderKey &gt;(&quot;users.patch&quot;);
+const patchUser = patch(new Endpoint (&quot;users/42&quot;), bodyKey);
+
+@patchUser
+@state()
+payload?: ApiResult ;
+
+The same decorator adapts to a method:
+
+@patch(new Endpoint (&quot;users/42&quot;), bodyKey)
+handlePatch(payload?: ApiResult ) {
+  if (payload?.response?.ok) console.log(payload.result);
+}
+
+To run the operation again from the component:
+
+async savePatch() {
+  await patchUser.send(this);
+}
+
+send(component) returns a Promise resolved after the PATCH completes. See
+@post for the method-decorator form and the
+when: &quot;before&quot; option.
+
+The PATCH is also sent automatically when the body mutates, unless
+autoPostOnBodyMutation: false is set. The available options are described in
+@post:
+
+- autoPostOnBodyMutation
+- skipIfBodyMissing
+- refetchEveryMs
+- skipEmptyPlaceholder
+- triggerKey
+
+Pass explicit API configuration as the third argument:
+
+@patch(endpoint, bodyKey, apiConfigurationKey)
+
+Import
+
+import { patch, type ApiResult } from &quot;@supersoniks/</pre>
+</section>
+<section id="docs-_decorators-post" data-doc-id="docs/_decorators/post">
+  <h2><a href="../docs/_decorators/post.html">@post</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/_decorators/post</code> · <a href="../docs/_decorators/post.html">full page</a></p>
+  <p>@post sends the contents of a publisher and stores the response in an</p>
+  <pre class="doc-excerpt">@post
+
+@post sends the contents of a publisher and stores the response in an
+optional ApiResult  property. The property is undefined until a result
+is available.
+
+Minimal usage
+
+Pass an Endpoint  and a DataProviderKey  for the request body.
+
+const userBodyKey = new DataProviderKey (&quot;users.form&quot;);
+const createUser = post(new Endpoint (&quot;users&quot;), userBodyKey);
+
+@createUser
+@state()
+payload?: ApiResult ;
+
+The same decorator adapts to a method and receives the complete payload:
+
+@post(new Endpoint (&quot;users&quot;), userBodyKey)
+handleCreate(payload?: ApiResult ) {
+  if (payload?.response?.ok) console.log(payload.result);
+}
+
+The current body is read from userBodyKey. By default, the POST is sent when
+the component connects and after each body mutation. Mutations in the same
+frame are coalesced into one request.
+
+API configuration is read from the HTML scope, as with
+@get.
+
+Sending the POST again
+
+From the component
+
+Keep the decorator to access send(component). The body is read again when the
+operation runs.
+
+async saveAgain() {
+  const payload = await createUser.send(this);
+  console.log(payload?.result);
+}
+
+send() returns a Promise  | undefined&gt; that resolves after the
+operation completes. It</pre>
+</section>
+<section id="docs-_decorators-publish" data-doc-id="docs/_decorators/publish">
+  <h2><a href="../docs/_decorators/publish.html">@publish</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/_decorators/publish</code> · <a href="../docs/_decorators/publish.html">full page</a></p>
+  <p>Write-only binding: assigning to the property publishes to the DataProviderKey path. No read subscription (inverse of @subscribe).</p>
+  <pre class="doc-excerpt">@publish
+
+Write-only binding: assigning to the property publishes to the DataProviderKey path. No read subscription (inverse of @subscribe).
+
+Similar to the “reflect” half of @bind without listening to the publisher.
+
+Import
+
+import { publish } from &quot;@supersoniks/concorde/decorators&quot;;
+import { sub } from &quot;@supersoniks/concorde/directives&quot;;
+import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+
+Example
+
+type PublishDemoData = { email: string; message: string };
+const publishDemoKey = new DataProviderKey (&quot;publishDemo&quot;);
+//
+@customElement(&quot;demo-publish&quot;)
+export class DemoPublish extends LitElement {
+  @publish(publishDemoKey.email)
+  @state()
+  email = &quot;&quot;;
+  //
+  @publish(publishDemoKey.message)
+  @state()
+  message = &quot;&quot;;
+  //
+  render() {
+    return html
+        (this.email = (e.target as HTMLInputElement).value)}
+        label=&quot;Email&quot;
+      &gt;
+       ${sub(publishDemoKey.email)}
+    ;
+  }
+}
+
+Dynamic paths use the same placeholder rules as @bind / @subscribe. Resolution and skipEmptyPlaceholder: Dynamic path placeholders.</pre>
+</section>
+<section id="docs-_decorators-put" data-doc-id="docs/_decorators/put">
+  <h2><a href="../docs/_decorators/put.html">@put</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/_decorators/put</code> · <a href="../docs/_decorators/put.html">full page</a></p>
+  <p>@put replaces a resource with the body from a publisher. It uses exactly the</p>
+  <pre class="doc-excerpt">@put
+
+@put replaces a resource with the body from a publisher. It uses exactly the
+same model as @post:
+Endpoint , DataProviderKey , ApiResult , options, and the
+send(component) handle.
+
+Minimal usage
+
+const bodyKey = new DataProviderKey (&quot;users.form&quot;);
+const updateUser = put(new Endpoint (&quot;users/42&quot;), bodyKey);
+
+@updateUser
+@state()
+payload?: ApiResult ;
+
+The same decorator adapts to a method:
+
+@put(new Endpoint (&quot;users/42&quot;), bodyKey)
+handleUpdate(payload?: ApiResult ) {
+  if (payload?.response?.ok) console.log(payload.result);
+}
+
+To run the operation again from the component:
+
+async update() {
+  await updateUser.send(this);
+}
+
+send(component) returns a Promise resolved after the PUT completes. See
+@post for the method-decorator form and the
+when: &quot;before&quot; option.
+
+The PUT is also sent automatically when the body mutates, unless
+autoPostOnBodyMutation: false is set. See
+@post for the option details:
+
+- autoPostOnBodyMutation
+- skipIfBodyMissing
+- refetchEveryMs
+- skipEmptyPlaceholder
+- triggerKey
+
+Pass explicit API configuration as the third argument:
+
+@put(endpoint, bodyKey, apiConfigurationKey)
+
+Import
+
+import { put, type ApiResult } from &quot;@supersoniks/concorde/decorators&quot;;
+impo</pre>
+</section>
+<section id="docs-_decorators-subscribe" data-doc-id="docs/_decorators/subscribe">
+  <h2><a href="../docs/_decorators/subscribe.html">@subscribe</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/_decorators/subscribe</code> · <a href="../docs/_decorators/subscribe.html">full page</a></p>
+  <p>Keeps a Lit property in sync with a read-only slice of the DataProvider store. You pass a DataProviderKey; when that path changes, the property updates and the component re-renders.</p>
+  <pre class="doc-excerpt">@subscribe
+
+Keeps a Lit property in sync with a read-only slice of the DataProvider store. You pass a DataProviderKey; when that path changes, the property updates and the component re-renders.
+
+Typical setup (same idea as My first component):
+
+| Piece | Role |
+|-------|------|
+| Type T | Shape of the object at that path (DocsUserData, { count: number }, …) |
+| Key | DataProviderKey  — static path (&quot;cart&quot;) or dynamic (&quot;users.${userIndex}&quot;, &quot;${dataProvider}&quot;) |
+| Scope on the host | Properties listed in U (e.g. dataProvider, userIndex) — often filled via @ancestorAttribute |
+| @subscribe(key) | Mirrors the store into @state() (or another property); read-only from the component side |
+
+For writing back to the store from component state, use @publish. In templates, the same paths work with sub().
+
+Import
+
+import { subscribe } from &quot;@supersoniks/concorde/decorators&quot;;
+import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+
+type Data = { count: number };
+const dataKey = new DataProviderKey&amp;lt;Data&amp;gt;(&quot;data&quot;);
+
+@subscribe(dataKey.count)
+@state()
+count = 0;
+
+Static path
+
+The key path is fixed. The property type must match T at that segment.
+
+const cartKey = new DataProvi</pre>
+</section>
+<section id="docs-_decorators-wait-for-ancestors" data-doc-id="docs/_decorators/wait-for-ancestors">
+  <h2><a href="../docs/_decorators/wait-for-ancestors.html">@awaitConnectedAncestors and @dispatchConnectedEvent</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/_decorators/wait-for-ancestors</code> · <a href="../docs/_decorators/wait-for-ancestors.html">full page</a></p>
+  <p>The @awaitConnectedAncestors and @dispatchConnectedEvent decorators delay a web component's initialization until its matching ancestors have executed their connectedCallback. This is when contextual e</p>
+  <pre class="doc-excerpt">@awaitConnectedAncestors and @dispatchConnectedEvent
+
+The @awaitConnectedAncestors and @dispatchConnectedEvent decorators delay a web component's initialization until its matching ancestors have executed their connectedCallback. This is when contextual elements (publisher, dataProvider, etc.) are configured.
+
+Principle
+
+When a child component attaches to the DOM, its ancestors may not yet be initialized (especially if custom element definitions are loaded asynchronously). The @awaitConnectedAncestors decorator delays the component's connectedCallback until all ancestors matching the provided CSS selectors have executed their connectedCallback.
+
+The @dispatchConnectedEvent decorator allows ancestors to signal they are ready by dispatching the sonic-connected event at the end of their connectedCallback. The event bubbles, so it can be listened to from anywhere (e.g. document.addEventListener(CONNECTED, handler)).
+
+Ancestors that are not web components (no hyphen in tag name) are considered connected by default and do not need to emit the event.
+
+Usage
+
+Import
+
+import { awaitConnectedAncestors, dispatchConnectedEvent, ancestorAttribute } from &quot;@supersoniks/concorde/decorators&quot;;
+
+Basic</pre>
+</section>
+    </article>
+  </main>
+</body>
+</html>