@supersoniks/concorde 4.6.0 → 4.7.0

package/docs/src/docs/_decorators/get.md

@@ -7,7 +7,7 @@ Pass an [`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint) as the first argument.
 ## 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.
+- **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.
 
 ## When the GET runs again
 
@@ -26,7 +26,7 @@ import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
 
 ## Minimal example
 
-Same demo service as [`sonic-queue`](../../core/components/functional/queue/queue.demo.ts) (`geo.api.gouv.fr`). Publisher setup lives in `decorators-demo-geo.ts` and `decorators-demo-subscribe-publish-get-demos.ts`.
+Same demo service as [`sonic-queue`](../../core/components/functional/queue/queue.demo.ts) (`/docs-mock-api/geo/`). Publisher setup lives in `decorators-demo-geo.ts` and `decorators-demo-subscribe-publish-get-demos.ts`.
 
 <sonic-code language="typescript">
   <template>
@@ -40,6 +40,7 @@ payload: ApiGetResult<User> | null = null;
 
 <sonic-code>
   <template>
+    <docs-demo-sources for="demo-api-get"></docs-demo-sources>
     <demo-api-get></demo-api-get>
   </template>
 </sonic-code>
@@ -48,15 +49,17 @@ Dynamic config and endpoint path (`demo-api-get-configuration-key` in doc source
 
 <sonic-code>
   <template>
+    <docs-demo-sources for="demo-api-get-configuration-key"></docs-demo-sources>
     <demo-api-get-configuration-key></demo-api-get-configuration-key>
   </template>
 </sonic-code>
 
-Scoped `@get` with `@publish` / `@subscribe` on the payload (see [@publish](#docs/_decorators/publish.md/publish) and [@subscribe](#docs/_decorators/subscribe.md/subscribe)) — wrap under an ancestor with `serviceURL="https://geo.api.gouv.fr/"`:
+Scoped `@get` with `@publish` / `@subscribe` on the payload (see [@publish](#docs/_decorators/publish.md/publish) and [@subscribe](#docs/_decorators/subscribe.md/subscribe)) — wrap under an ancestor with `serviceURL="/docs-mock-api/geo/"`:
 
 <sonic-code>
   <template>
-<div serviceURL="https://geo.api.gouv.fr/">
+<div serviceURL="/docs-mock-api/geo/">
+  <docs-demo-sources for="demo-api-get-publish-subscribe"></docs-demo-sources>
   <demo-api-get-publish-subscribe></demo-api-get-publish-subscribe>
 </div>
   </template>

package/docs/src/docs/_decorators/handle.md

@@ -0,0 +1,171 @@
+# @handle
+
+Typed callback on one or more `DataProviderKey<T>` paths: invokes the decorated **method** when a publisher assigns a value (calculations, side effects, updating other `@state` properties, etc.).
+
+Unlike [@subscribe](#docs/_decorators/subscribe.md/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](#docs/_decorators/on-assign.md/on-assign).
+
+By default the method is called on **every** assignment, even when the value is `null` / `undefined`. Use the options below to restrict that.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { handle, Skip } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { get, set } from "@supersoniks/concorde/utils";
+  </template>
+</sonic-code>
+
+## Basic example
+
+<sonic-code language="typescript">
+  <template>
+type DemoCounterData = { count: number };
+const demoDataKey = new DataProviderKey&lt;DemoCounterData&gt;("demoData");
+
+@customElement("demo-handle")
+export class DemoHandle extends LitElement {
+  @state() doubled = 0;
+  @state() lastUpdate = "";
+
+  @handle(demoDataKey.count)
+  onCountChange(count: number) {
+    this.doubled = count * 2;
+    this.lastUpdate = new Date().toLocaleTimeString();
+  }
+
+  incrementCount() {
+    const data = get(demoDataKey);
+    set(demoDataKey, { ...data, count: data.count + 1 });
+  }
+
+  render() {
+    return html`
+      &lt;p&gt;Doubled count: ${this.doubled}&lt;/p&gt;
+      &lt;p&gt;&lt;small&gt;Last update: ${this.lastUpdate}&lt;/small&gt;&lt;/p&gt;
+      &lt;sonic-button @click=${this.incrementCount}&gt;Increment&lt;/sonic-button&gt;
+    `;
+  }
+}
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-handle"></docs-demo-sources>
+    <demo-handle></demo-handle>
+  </template>
+</sonic-code>
+
+## Dynamic path
+
+Placeholders in `DataProviderKey` resolve from the host component’s properties (same rules as `@bind` / `@subscribe`).
+
+<sonic-code language="typescript">
+  <template>
+type User = { firstName: string; lastName: string; email: string };
+
+@customElement("demo-handle-dynamic")
+export class DemoHandleDynamic extends LitElement {
+  @property({ type: Number })
+  userIndex = 0;
+
+  @state() displayName = "";
+  @state() lastUpdate = "";
+
+  @handle(new DataProviderKey&lt;User, { userIndex: number }&gt;("demoUsers.${userIndex}"))
+  onUserAssigned(user: User) {
+    this.displayName = `${user.firstName} ${user.lastName}`;
+    this.lastUpdate = new Date().toLocaleTimeString();
+  }
+
+  render() {
+    return html`...`;
+  }
+}
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-handle-dynamic"></docs-demo-sources>
+    <demo-handle-dynamic></demo-handle-dynamic>
+  </template>
+</sonic-code>
+
+## Multiple paths
+
+`@handle` accepts up to **3 keys**; the method receives one strongly-typed argument per key, in order. Each assignment triggers the method, so make your method safe against partial values (or use `waitForAllDefined`, see below).
+
+<sonic-code language="typescript">
+  <template>
+type QueueConfig = { onInactivity: { stillHere: { show: boolean } } };
+const config = new DataProviderKey&lt;QueueConfig&gt;("sessionQueueConfig");
+const idle = new DataProviderKey&lt;{ isIdle: boolean }&gt;("idleStatus");
+
+@customElement("demo-handle-multi")
+export class DemoHandleMulti extends LitElement {
+
+  // show: boolean, isIdle: boolean — fully typed from the keys
+  @handle(config.onInactivity.stillHere.show, idle.isIdle)
+  onInactivity(show: boolean, isIdle: boolean) {
+    if (show === true && isIdle === true) this.openModal();
+    else this.closeModal();
+  }
+}
+  </template>
+</sonic-code>
+
+## Options (`HandleOptions`)
+
+Pass an options object as the **last** argument. The names map to real situations seen in the apps.
+
+### `waitForAllDefined`
+
+Only call the method once **all** watched keys are defined (non `null` / `undefined`). This reproduces the historical `@onAssign` semantics — use it when the logic only makes sense with every source ready (e.g. building a date from `date` + `timeZone` + `direction`).
+
+<sonic-code language="typescript">
+  <template>
+@handle(trip.departureDate, trip.event.timeZone, form.direction, {
+  waitForAllDefined: true,
+})
+updateDepartureDate(date: number, timeZone: string, direction: string) {
+  // called only when the three values are all available
+  this.formDate = formatDate(date, timeZone, direction);
+}
+  </template>
+</sonic-code>
+
+### `skip`
+
+Do **not** call the method when a received value belongs to one of the listed **categories** (the `Skip` enum). Each entry is a named category — not a value — so there is no value/pattern ambiguity (e.g. `{}` is `Skip.EmptyObject`, an explicit "empty object" category, never a value comparison).
+
+| Category | Matches |
+| --- | --- |
+| `Skip.Nullish` | `null` or `undefined` (a publisher always emits `null`, never `undefined`) |
+| `Skip.EmptyString` | `""` |
+| `Skip.EmptyObject` | object with no keys (`{}`), arrays excluded |
+| `Skip.EmptyArray` | empty array (`[]`) |
+
+Useful when a not-yet-initialized publisher emits `{}` as a "loading" state. For a **specific value** (e.g. a particular string), guard inside the method instead.
+
+<sonic-code language="typescript">
+  <template>
+@handle(user.profile, { skip: [Skip.Nullish, Skip.EmptyObject] })
+onProfile(profile: Profile) {
+  // not called while the publisher still holds {} (not loaded yet)
+  this.displayName = profile.firstName;
+}
+  </template>
+</sonic-code>
+
+> 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.
+
+## Highlights
+
+- Strict typing: the method receives one argument per key, in order.
+- Up to 3 keys; for 4+ keys (rare), keep [@onAssign](#docs/_decorators/on-assign.md/on-assign) for now.
+- 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).

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

@@ -1,10 +1,14 @@
 # @onAssign
 
+> **New apps:** use [@handle](#docs/_decorators/handle.md/handle) with `DataProviderKey` ([Data flow](#docs/_core-concept/dataFlow.md/dataFlow)). `@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](#docs/_decorators/handle.md/handle).
+
 ## Principle
 
-This decorator subscribes to one or more publishers via the `PublisherManager`. When all specified publishers have been assigned values (via `set`), the decorated method is called with all the values as arguments.
+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](#docs/_decorators/handle.md/handle) + `DataProviderKey` and `get` / `set` from [Data flow](#docs/_core-concept/dataFlow.md/dataFlow).
 
 This is particularly useful when you need to wait for multiple data sources to be ready before executing logic.
 
@@ -15,7 +19,6 @@ This is particularly useful when you need to wait for multiple data sources to b
 <sonic-code language="typescript">
   <template>
 import { onAssign } from "@supersoniks/concorde/decorators";
-import { DataProviderKey } from "@supersoniks/concorde/decorators";
   </template>
 </sonic-code>
 
@@ -28,11 +31,11 @@ import { DataProviderKey } from "@supersoniks/concorde/decorators";
 @customElement("demo-on-assign")
 export class DemoOnAssign extends LitElement {
   static styles = [tailwind];
-  //
+
   @state() userWithSettings: any = null;
   @state() isReady: boolean = false;
   @state() lastUpdate: string = "";
-  //
+
   @onAssign("demoUser", "demoUserSettings")
   handleDataReady(user: any, settings: any) {
     this.isReady = Object.keys(user).length > 0 && Object.keys(settings).length > 0;
@@ -40,12 +43,12 @@ export class DemoOnAssign extends LitElement {
     this.lastUpdate = new Date().toLocaleTimeString();
     this.requestUpdate();
   }
-  //
+
   render() {
     const { name, email, theme, language } = this.userWithSettings;
     return //...
   }
-  //
+
   updateData() {
     const user = PublisherManager.get("demoUser");
     const userSettings = PublisherManager.get("demoUserSettings");
@@ -54,7 +57,7 @@ export class DemoOnAssign extends LitElement {
       name: `User n°${userNumber}`,
       email: `user-${userNumber}@example.com`,
     });
-    //
+
     userSettings.set({
       theme: ["light", "dark", "auto"][Math.floor(Math.random() * 3)],
       language: ["en", "fr", "es"][Math.floor(Math.random() * 3)],
@@ -66,6 +69,7 @@ export class DemoOnAssign extends LitElement {
 
 <sonic-code>
   <template>
+    <docs-demo-sources for="demo-on-assign"></docs-demo-sources>
     <demo-on-assign></demo-on-assign>
   </template>
 </sonic-code>
@@ -79,17 +83,17 @@ export class DemoOnAssign extends LitElement {
 export class ProductView extends LitElement {
   product: any = null;
   inventory: any = null;
-  //
+
   @onAssign("store.product", "store.inventory")
   handleProductData(product: any, inventory: any) {
     this.product = product;
     this.inventory = inventory;
     this.requestUpdate();
   }
-  //
+
   render() {
     if (!this.product) return html`<div>Loading...</div>`;
-    //
+
     const stock = this.inventory[this.product.id] || 0;
     return html`
       <div>
@@ -103,31 +107,6 @@ export class ProductView extends LitElement {
   </template>
 </sonic-code>
 
-### Example with `DataProviderKey` (type-safe)
-
-<sonic-code language="typescript">
-  <template>
-type User = { id: string; name: string };
-type Settings = { theme: "light" | "dark" };
-
-const userKey = new DataProviderKey<User>("demoUser");
-const settingsKey = new DataProviderKey<Settings>("demoUserSettings");
-
-@customElement("demo-on-assign-typed")
-export class DemoOnAssignTyped extends LitElement {
-  @state() user: User | null = null;
-  @state() settings: Settings | null = null;
-
-  @onAssign(userKey, settingsKey)
-  handleReady(user: User, settings: Settings) {
-    this.user = user;
-    this.settings = settings;
-    this.requestUpdate();
-  }
-}
-  </template>
-</sonic-code>
-
 ## Path syntax
 
 The path uses dot notation to navigate through the publisher structure:
@@ -155,32 +134,32 @@ Each placeholder is replaced at runtime with the current value of the correspond
 @customElement("demo-on-assign-dynamic")
 export class DemoOnAssignDynamic extends LitElement {
   static styles = [tailwind];
-  //
+
   @property({ type: String })
   dataProvider: "demoUsers" | "demoUsersAlt" = "demoUsers";
-  //
+
   @property({ type: Number })
   userIndex: number = 0;
-  //
+
   @state() user: any = null;
   @state() userSettings: any = null;
-  //
+
   @onAssign("${dataProvider}.${userIndex}", "${dataProvider}Settings.${userIndex}")
   handleUserDataReady(user: any, settings: any) {
     this.user = user;
     this.userSettings = settings;
   }
-  //
+
   updateUserIndex(e: Event) {
     this.userIndex = parseInt((e.target as HTMLInputElement).value);
   }
-  //
+
   updateDataProvider(e: Event) {
     this.dataProvider = (e.target as HTMLSelectElement).value as
       | "demoUsers"
       | "demoUsersAlt";
   }
-  //
+
   updateCurrentUserData() {
     const usersPublisher = PublisherManager.get(this.dataProvider);
     const settingsPublisher = PublisherManager.get(
@@ -194,7 +173,7 @@ export class DemoOnAssignDynamic extends LitElement {
       settingsPublisher,
       [String(this.userIndex)]
     ) as PublisherProxy;
-    //
+
     if (userPublisher && settingPublisher) {
       // Générer de nouvelles données aléatoires
       const randomNames = [
@@ -204,7 +183,7 @@ export class DemoOnAssignDynamic extends LitElement {
       ];
       const randomThemes = ["light", "dark", "auto"];
       const randomLanguages = ["en", "fr", "es"];
-      //
+
       const randomName =
         randomNames[Math.floor(Math.random() * randomNames.length)];
       const randomEmail = `${randomName.firstName.toLowerCase()}.${randomName.lastName.toLowerCase()}@example.com`;
@@ -212,7 +191,7 @@ export class DemoOnAssignDynamic extends LitElement {
         randomThemes[Math.floor(Math.random() * randomThemes.length)];
       const randomLanguage =
         randomLanguages[Math.floor(Math.random() * randomLanguages.length)];
-      //
+
       // Mettre à jour l'utilisateur directement
       const currentUser = userPublisher.get() || {};
       userPublisher.set({
@@ -221,7 +200,7 @@ export class DemoOnAssignDynamic extends LitElement {
         lastName: randomName.lastName,
         email: randomEmail,
       });
-      //
+
       // Mettre à jour les settings directement
       settingPublisher.set({
         theme: randomTheme,
@@ -229,15 +208,15 @@ export class DemoOnAssignDynamic extends LitElement {
       });
     }
   }
-  //
+
   render() {
     return html`
-      <div class="flex flex-col gap-2">
-        <sonic-select label="Users set" @change=${this.updateDataProvider}>
-          <option value="demoUsers">First set of users</option>
-          <option value="demoUsersAlt">Second set of users</option>
-        </sonic-select>
-        <sonic-input
+      &lt;div class="flex flex-col gap-2"&gt;
+        &lt;sonic-select label="Users set" @change=${this.updateDataProvider}&gt;
+          &lt;option value="demoUsers"&gt;First set of users&lt;/option&gt;
+          &lt;option value="demoUsersAlt"&gt;Second set of users&lt;/option&gt;
+        &lt;/sonic-select&gt;
+        &lt;sonic-input
           type="number"
           .value=${this.userIndex}
           @input=${this.updateUserIndex}
@@ -245,26 +224,25 @@ export class DemoOnAssignDynamic extends LitElement {
           max="9"
           label="Index"
           class="block"
-        >
-        </sonic-input>
-        <sonic-button @click=${this.updateCurrentUserData}
-          >Update current user data</sonic-button
-        >
-        <div class="flex flex-col gap-2 border p-2">
-          <div>
-            <sonic-icon name="user" library="heroicons"></sonic-icon>
+        &gt;&lt;/sonic-input&gt;
+        &lt;sonic-button @click=${this.updateCurrentUserData}&gt;
+          Update current user data
+        &lt;/sonic-button&gt;
+        &lt;div class="flex flex-col gap-2 border p-2"&gt;
+          &lt;div&gt;
+            &lt;sonic-icon name="user" library="heroicons"&gt;&lt;/sonic-icon&gt;
             ${this.user?.firstName} ${this.user?.lastName}
-          </div>
-          <div>
-            <sonic-icon name="envelope" library="heroicons"></sonic-icon>
+          &lt;/div&gt;
+          &lt;div&gt;
+            &lt;sonic-icon name="envelope" library="heroicons"&gt;&lt;/sonic-icon&gt;
             ${this.user?.email}
-          </div>
-          <div>
+          &lt;/div&gt;
+          &lt;div&gt;
             Theme: ${this.userSettings?.theme} | Language:
             ${this.userSettings?.language}
-          </div>
-        </div>
-      </div>
+          &lt;/div&gt;
+        &lt;/div&gt;
+      &lt;/div&gt;
     `;
   }
 }
@@ -273,6 +251,7 @@ export class DemoOnAssignDynamic extends LitElement {
 
 <sonic-code>
   <template>
+    <docs-demo-sources for="demo-on-assign-dynamic"></docs-demo-sources>
     <demo-on-assign-dynamic></demo-on-assign-dynamic>
   </template>
 </sonic-code>
@@ -311,13 +290,13 @@ import { html, LitElement } from "lit";
 import { customElement } from "lit/decorators.js";
 import { onAssign } from "@supersoniks/concorde/decorators";
 import { PublisherManager } from "@supersoniks/concorde/core/utils/PublisherProxy";
-//
+
 @customElement("order-summary")
 export class OrderSummary extends LitElement {
   order: any = null;
   customer: any = null;
   shipping: any = null;
-  //
+
   @onAssign("orderData", "customerData", "shippingData")
   handleOrderReady(order: any, customer: any, shipping: any) {
     this.order = order;
@@ -325,12 +304,12 @@ export class OrderSummary extends LitElement {
     this.shipping = shipping;
     this.requestUpdate();
   }
-  //
+
   render() {
     if (!this.order || !this.customer || !this.shipping) {
       return html`<div>Loading order details...</div>`;
     }
-    //
+
     return html`
       <div class="order-summary">
         <h2>Order #${this.order.id}</h2>
@@ -353,6 +332,53 @@ shippingPub.set({ address: "123 Main St" });
   </template>
 </sonic-code>
 
+## Migrating to @handle
+
+`@handle` is the typed successor of `@onAssign`. The key behavioral difference: `@onAssign` waits for **all** values to be defined before calling the method, whereas `@handle` calls it on **every** assignment by default. Use the `waitForAllDefined` option to keep the old semantics.
+
+### Why migrate
+
+- **Typed paths**: keys are `DataProviderKey<T>`, so the method arguments are strongly typed (no more `any`).
+- **Explicit intent**: `waitForAllDefined` and `skip` replace implicit behavior.
+- **Single API**: `@handle` covers the mono- and multi-path cases (up to 3 keys).
+
+### Equivalent semantics (`waitForAllDefined`)
+
+<sonic-code language="typescript">
+  <template>
+// Before
+@onAssign("demoUser", "demoUserSettings")
+handleDataReady(user: any, settings: any) { /* ... */ }
+
+// After — same "wait for everything" behavior, but typed
+const user = new DataProviderKey&lt;User&gt;("demoUser");
+const settings = new DataProviderKey&lt;Settings&gt;("demoUserSettings");
+
+@handle(user, settings, { waitForAllDefined: true })
+handleDataReady(user: User, settings: Settings) { /* ... */ }
+  </template>
+</sonic-code>
+
+### Single path
+
+<sonic-code language="typescript">
+  <template>
+// Before
+@onAssign("settings.modules.logs_route.enabled")
+onLogRoute(value: boolean) { /* ... */ }
+
+// After
+const settings = new DataProviderKey&lt;AppSettings&gt;("settings");
+
+@handle(settings.modules.logs_route.enabled)
+onLogRoute(value: boolean) { /* ... */ }
+  </template>
+</sonic-code>
+
+### 4+ paths
+
+`@handle` is capped at 3 keys. For the rare case of 4 or more publishers, keep `@onAssign` for now, or split the logic into several `@handle` methods that each store their value and call a shared method (guarding against partial values).
+
 ## Notes
 
 - This decorator works with any component that has `connectedCallback` and `disconnectedCallback` methods (such as `LitElement` or components extending `Subscriber`)

package/docs/src/docs/_decorators/publish.md

@@ -38,7 +38,7 @@ export class DemoPublish extends LitElement {
         @input=${(e) => (this.email = (e.target as HTMLInputElement).value)}
         label="Email"
       ></sonic-input>
-      <p>${sub("publishDemo.email")}</p>
+      <p>${sub(publishDemoKey.email)}</p>
     `;
   }
 }
@@ -47,6 +47,7 @@ export class DemoPublish extends LitElement {
 
 <sonic-code>
   <template>
+    <docs-demo-sources for="demo-publish"></docs-demo-sources>
     <demo-publish></demo-publish>
   </template>
 </sonic-code>