@supersoniks/concorde 4.5.2 → 4.6.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@supersoniks/concorde",
-  "version": "4.5.2",
+  "version": "4.6.0",
   "license": "MIT",
   "type": "module",
   "main": "",
@@ -288,6 +288,9 @@
     "./decorators/subscriber/dynamicPath": "./src/core/decorators/subscriber/dynamicPath.ts",
     "./decorators/subscriber/dynamicPropertyWatch.spec": "./src/core/decorators/subscriber/dynamicPropertyWatch.spec.ts",
     "./decorators/subscriber/dynamicPropertyWatch": "./src/core/decorators/subscriber/dynamicPropertyWatch.ts",
+    "./decorators/subscriber/handle.disambig.spec": "./src/core/decorators/subscriber/handle.disambig.spec.ts",
+    "./decorators/subscriber/handle.skip.spec": "./src/core/decorators/subscriber/handle.skip.spec.ts",
+    "./decorators/subscriber/handle": "./src/core/decorators/subscriber/handle.ts",
     "./decorators/subscriber/onAssign": "./src/core/decorators/subscriber/onAssign.ts",
     "./decorators/subscriber/publish.spec": "./src/core/decorators/subscriber/publish.spec.ts",
     "./decorators/subscriber/publish": "./src/core/decorators/subscriber/publish.ts",

package/src/core/decorators/Subscriber.ts

@@ -2,6 +2,8 @@ export { bind } from "./subscriber/bind";
 export { publish } from "./subscriber/publish";
 export { subscribe } from "./subscriber/subscribe";
 export { onAssign } from "./subscriber/onAssign";
+export { handle, Skip } from "./subscriber/handle";
+export type { HandleOptions } from "./subscriber/handle";
 export { autoSubscribe } from "./subscriber/autoSubscribe";
 export { autoFill } from "./subscriber/autoFill";
 export { ancestorAttribute } from "./subscriber/ancestorAttribute";

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

@@ -0,0 +1,20 @@
+import { describe, expect, it } from "vitest";
+import { DataProviderKey } from "../../utils/dataProviderKey";
+
+function isDataProviderKey(value: unknown): boolean {
+  return Object.prototype.toString.call(value) === "[object DataProviderKey]";
+}
+
+describe("handle: désambiguïsation clé vs options", () => {
+  it("reconnaît une DataProviderKey (y compris après navigation)", () => {
+    const key = new DataProviderKey<{ total: number }>("cart");
+    expect(isDataProviderKey(key)).toBe(true);
+    expect(isDataProviderKey(key.total)).toBe(true);
+  });
+
+  it("ne confond pas un objet d'options avec une clé", () => {
+    expect(isDataProviderKey({ skip: ["emptyObject"] })).toBe(false);
+    expect(isDataProviderKey({ waitForAllDefined: true })).toBe(false);
+    expect(isDataProviderKey(undefined)).toBe(false);
+  });
+});

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

@@ -0,0 +1,37 @@
+import { describe, expect, it } from "vitest";
+import { Skip, isSkipped } from "./onAssign";
+
+describe("isSkipped (catégories Skip de @handle)", () => {
+  it("Nullish : null et undefined uniquement", () => {
+    expect(isSkipped(null, [Skip.Nullish])).toBe(true);
+    expect(isSkipped(undefined, [Skip.Nullish])).toBe(true);
+    expect(isSkipped(0, [Skip.Nullish])).toBe(false);
+    expect(isSkipped("", [Skip.Nullish])).toBe(false);
+  });
+
+  it("EmptyString : pas de coercition", () => {
+    expect(isSkipped("", [Skip.EmptyString])).toBe(true);
+    expect(isSkipped("a", [Skip.EmptyString])).toBe(false);
+    expect(isSkipped(0, [Skip.EmptyString])).toBe(false);
+  });
+
+  it("EmptyObject : objet sans clé, tableau exclu", () => {
+    expect(isSkipped({}, [Skip.EmptyObject])).toBe(true);
+    expect(isSkipped({ a: 1 }, [Skip.EmptyObject])).toBe(false);
+    expect(isSkipped([], [Skip.EmptyObject])).toBe(false);
+    expect(isSkipped(null, [Skip.EmptyObject])).toBe(false);
+  });
+
+  it("EmptyArray : tableau vide, objet exclu", () => {
+    expect(isSkipped([], [Skip.EmptyArray])).toBe(true);
+    expect(isSkipped([1], [Skip.EmptyArray])).toBe(false);
+    expect(isSkipped({}, [Skip.EmptyArray])).toBe(false);
+  });
+
+  it("combinaison de catégories", () => {
+    const kinds = [Skip.Nullish, Skip.EmptyObject];
+    expect(isSkipped(null, kinds)).toBe(true);
+    expect(isSkipped({}, kinds)).toBe(true);
+    expect(isSkipped({ a: 1 }, kinds)).toBe(false);
+  });
+});

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

@@ -0,0 +1,128 @@
+import type {
+  DataProviderKey,
+  DataProviderKeyHost,
+} from "../../utils/dataProviderKey";
+import { createOnAssign, Skip } from "./onAssign";
+
+export { Skip } from "./onAssign";
+
+/**
+ * Options de `@handle`, nommées d'après les cas d'usage réels rencontrés dans
+ * les projets (panier, file d'attente, formulaires multi-publishers, etc.).
+ *
+ * Par défaut (aucune option), `@handle` appelle la méthode **à chaque
+ * 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 = {
+  /**
+   * Attendre que **toutes** les clés surveillées soient définies (non
+   * `null`/`undefined`) avant d'appeler la méthode. Reproduit la sémantique
+   * historique de `@onAssign`.
+   *
+   * À utiliser quand la logique combine plusieurs sources et n'a de sens que
+   * lorsque toutes sont prêtes (ex. calcul de date à partir de
+   * `date` + `timeZone` + `direction`).
+   */
+  waitForAllDefined?: boolean;
+  /**
+   * Ne pas appeler la méthode si la valeur reçue appartient à l'une de ces
+   * catégories. Chaque entrée est une catégorie nommée (pas une valeur), donc
+   * aucune ambiguïté valeur/motif.
+   *
+   * - `Skip.Nullish` ignore `null`/`undefined` ;
+   * - `Skip.EmptyObject` / `Skip.EmptyArray` ignorent `{}` / `[]` ;
+   * - `Skip.EmptyString` ignore `""`.
+   *
+   * Pratique quand un publisher non initialisé émet `{}` comme état « pas encore
+   * chargé » : `skip: [Skip.EmptyObject]`. Pour une validation arbitraire sur une
+   * valeur précise, faire le test directement dans la méthode.
+   */
+  skip?: Skip[];
+};
+
+type HandleDecorator<Host, Fn> = (
+  target: Host,
+  propertyKey: string,
+  descriptor: TypedPropertyDescriptor<Fn>,
+) => void;
+
+/**
+ * Détecte une `DataProviderKey` (Proxy marqué `Symbol.toStringTag`) afin de la
+ * distinguer d'un objet d'options passé en dernier argument.
+ */
+function isDataProviderKey(value: unknown): value is DataProviderKey<unknown> {
+  return Object.prototype.toString.call(value) === "[object DataProviderKey]";
+}
+
+/**
+ * Callback typé déclenché lorsqu'un (ou plusieurs) chemin(s) publisher sont
+ * assignés via `DataProviderKey<T>`. Invoque la méthode décorée avec la/les
+ * valeur(s) assignée(s) (calculs, effets de bord, mise à jour d'autres `@state`…).
+ *
+ * Supporte les chemins dynamiques : placeholders type `"users.${userIndex}"`.
+ *
+ * Contrairement à `@onAssign`, la méthode est appelée à chaque assignation,
+ * même quand la valeur reçue est `null`/`undefined` — sauf si une option
+ * (`waitForAllDefined`, `skip`) restreint le déclenchement.
+ *
+ * @example
+ * // Mono-clé
+ * const cart = new DataProviderKey<Cart>("cart");
+ * @handle(cart.total)
+ * updateSummary(total: number) {
+ *   this.summary = total * this.taxRate;
+ * }
+ *
+ * @example
+ * // Multi-clés (coordination de plusieurs publishers)
+ * @handle(config.show, idle.isIdle, { waitForAllDefined: true })
+ * onModal(show: boolean, isIdle: boolean) {
+ *   if (show && isIdle) this.open(); else this.close();
+ * }
+ *
+ * @example
+ * // Ignorer un objet vide émis par un publisher non initialisé
+ * @handle(user.profile, { skip: [Skip.EmptyObject] })
+ * onProfile(profile: Profile) { this.name = profile.name; }
+ */
+export function handle<A, U = any>(
+  key: DataProviderKey<A, U>,
+  options?: HandleOptions,
+): HandleDecorator<DataProviderKeyHost<U>, (a: A) => void>;
+export function handle<A, B, UA = any, UB = any>(
+  keyA: DataProviderKey<A, UA>,
+  keyB: DataProviderKey<B, UB>,
+  options?: HandleOptions,
+): HandleDecorator<
+  DataProviderKeyHost<UA> & DataProviderKeyHost<UB>,
+  (a: A, b: B) => void
+>;
+export function handle<A, B, C, UA = any, UB = any, UC = any>(
+  keyA: DataProviderKey<A, UA>,
+  keyB: DataProviderKey<B, UB>,
+  keyC: DataProviderKey<C, UC>,
+  options?: HandleOptions,
+): HandleDecorator<
+  DataProviderKeyHost<UA> & DataProviderKeyHost<UB> & DataProviderKeyHost<UC>,
+  (a: A, b: B, c: C) => void
+>;
+export function handle(
+  ...args: Array<DataProviderKey<unknown> | HandleOptions | undefined>
+) {
+  const last = args[args.length - 1];
+  const hasOptions = last !== undefined && !isDataProviderKey(last);
+  const options = (hasOptions ? last : {}) as HandleOptions;
+  const keys = (hasOptions ? args.slice(0, -1) : args) as Array<
+    DataProviderKey<unknown>
+  >;
+  const paths = keys.map((key) => key.path);
+
+  return createOnAssign(
+    {
+      dispatchWhenUndefined: !options.waitForAllDefined,
+      skip: options.skip,
+    },
+    paths,
+  );
+}

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

@@ -23,7 +23,100 @@ type Configuration = {
   index: number;
 };
 
+/**
+ * Catégories de valeurs « ignorables » par le garde `skip`. Chaque catégorie est
+ * un prédicat nommé (et non une égalité de valeur), ce qui lève toute ambiguïté
+ * entre « valeur » et « motif » (notamment pour l'objet vide).
+ */
+export enum Skip {
+  /**
+   * `null` ou `undefined`. En pratique un publisher renvoie toujours `null`
+   * (jamais `undefined`) car `get()` coerce `undefined → null`.
+   */
+  Nullish = "nullish",
+  /** Chaîne vide `""`. */
+  EmptyString = "emptyString",
+  /** Objet sans clé (`{}`), tableau exclu. */
+  EmptyObject = "emptyObject",
+  /** Tableau vide (`[]`). */
+  EmptyArray = "emptyArray",
+}
+
+const SKIP_PREDICATES: Record<Skip, (value: unknown) => boolean> = {
+  [Skip.Nullish]: (v) => v === null || v === undefined,
+  [Skip.EmptyString]: (v) => v === "",
+  [Skip.EmptyObject]: (v) =>
+    typeof v === "object" &&
+    v !== null &&
+    !Array.isArray(v) &&
+    Object.keys(v).length === 0,
+  [Skip.EmptyArray]: (v) => Array.isArray(v) && v.length === 0,
+};
+
+/**
+ * `true` si `value` appartient à au moins une des catégories `kinds`.
+ */
+export function isSkipped(value: unknown, kinds: Skip[]): boolean {
+  return kinds.some((kind) => SKIP_PREDICATES[kind](value));
+}
+
+export type OnAssignOptions = {
+  /**
+   * Quand `true`, le callback est invoqué à chaque assignation, même si la
+   * valeur reçue est `null`/`undefined`.
+   * Quand `false` (défaut), le callback n'est invoqué que lorsque toutes les
+   * valeurs surveillées sont définies (non `null` et non `undefined`).
+   */
+  dispatchWhenUndefined?: boolean;
+  /**
+   * Ne pas invoquer le callback si une valeur reçue appartient à l'une de ces
+   * catégories (ex. `[Skip.Nullish, Skip.EmptyObject]`).
+   */
+  skip?: Skip[];
+};
+
+function shouldDispatch(
+  currentValues: unknown[],
+  expectedCount: number,
+  options: OnAssignOptions,
+): boolean {
+  // Garde structurelle : toutes les valeurs doivent être définies.
+  if (!options.dispatchWhenUndefined) {
+    const definedCount = currentValues
+      .slice(0, expectedCount)
+      .filter((v) => v !== null && v !== undefined).length;
+    if (definedCount !== expectedCount) return false;
+  }
+  // Garde de contenu : catégories skip.
+  if (options.skip && options.skip.length > 0) {
+    for (let i = 0; i < expectedCount; i++) {
+      if (isSkipped(currentValues[i], options.skip)) return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * @deprecated Utiliser `@handle` à la place.
+ *
+ * `@onAssign` prend des chemins sous forme de **chaînes** non typées et n'appelle
+ * la méthode que lorsque **toutes** les valeurs sont définies. `@handle` offre la
+ * même chose en **typé** (via `DataProviderKey`), avec des options explicites :
+ *
+ * - équivalent direct : `@onAssign("a", "b")` → `@handle(keyA, keyB, { waitForAllDefined: true })`
+ * - comportement par défaut de `@handle` : appel à chaque assignation (même `null`/`undefined`)
+ * - `skip` pour ignorer des catégories de valeurs (ex. `[Skip.Nullish, Skip.EmptyObject]`)
+ *
+ * `@onAssign` reste fonctionnel et inchangé le temps de la migration.
+ */
 export function onAssign(...values: Array<string>) {
+  return createOnAssign({}, values);
+}
+
+export function createOnAssign(
+  options: OnAssignOptions,
+  values: Array<string>,
+) {
   const pathConfigs: PathConfiguration[] = values.map((path) => {
     const dynamicDependencies = extractDynamicDependencies(path);
     return {
@@ -69,10 +162,7 @@ export function onAssign(...values: Array<string>) {
         const callbacks: Set<Callback> = new Set();
         const onAssign = (assignedValue: unknown) => {
           onAssignValues[i] = assignedValue;
-          if (
-            onAssignValues.filter((v) => v !== null && v !== undefined)
-              .length === values.length
-          ) {
+          if (shouldDispatch(onAssignValues, values.length, options)) {
             callbacks.forEach((callback) => callback(...onAssignValues));
           }
         };

package/src/decorators.ts

@@ -7,6 +7,11 @@ export const bind = mySubscriber.bind;
 export const publish = mySubscriber.publish;
 export const subscribe = mySubscriber.subscribe;
 export const onAssign = mySubscriber.onAssign;
+export const handle = mySubscriber.handle;
+export {
+  Skip,
+  type HandleOptions,
+} from "@supersoniks/concorde/core/decorators/Subscriber";
 export const ancestorAttribute = mySubscriber.ancestorAttribute;
 export const autoSubscribe = mySubscriber.autoSubscribe;
 export const autoFill = mySubscriber.autoFill;
@@ -31,6 +36,7 @@ window["concorde-decorator-subscriber"] = {
   publish: mySubscriber.publish,
   subscribe: mySubscriber.subscribe,
   onAssing: mySubscriber.onAssign,
+  handle: mySubscriber.handle,
   ancestorAttribute: mySubscriber.ancestorAttribute,
   autoSubscribe: mySubscriber.autoSubscribe,
   autoFill: mySubscriber.autoFill,

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), [@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).
 
 ## Principle
 

package/src/docs/_decorators/handle.md

@@ -0,0 +1,169 @@
+# @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";
+  </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 publisher = PublisherManager.get("demoData");
+    const data = publisher.get() as DemoCounterData;
+    publisher.set({ ...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>
+    <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>
+    <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/src/docs/_decorators/on-assign.md

@@ -1,7 +1,12 @@
 # @onAssign
 
+> **⚠️ Deprecated — use [@handle](#docs/_decorators/handle.md/handle) instead.**
+> `@onAssign` takes untyped **string** paths; `@handle` does the same with full typing via `DataProviderKey`, supports up to 3 keys, and exposes explicit options. `@onAssign` stays functional and unchanged during the migration. See the **Migrating to @handle** section 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.
@@ -327,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/src/docs/_misc/dataProviderKey.md

@@ -97,13 +97,13 @@ const pathProp = key.path;           // "data.count"
 
 ## Use cases
 
-- **Type-safe bindings**: paths for `@bind`, `@subscribe`, `@publish`
+- **Type-safe bindings**: paths for `@bind`, `@subscribe`, `@publish`, `@handle`
 - **Dynamic paths**: reusable keys with `${...}` placeholders
 - **Form fields**: form data paths with compile-time checking
 
-## Integration with @subscribe and @publish
+## Integration with @subscribe, @publish and @handle
 
-Use `DataProviderKey` with `@subscribe` (read-only) or `@publish` (write-only). The decorated property **must** match the key’s value type:
+Use `DataProviderKey` with `@subscribe` (read-only), `@publish` (write-only), or `@handle` (method callback on assign). With `@subscribe` / `@publish`, the decorated property **must** match the key’s value type. With `@handle`, the method receives `(value: T)`.
 
 <sonic-code language="typescript">
   <template>
@@ -126,7 +126,7 @@ export class UserForm extends LitElement {
   </template>
 </sonic-code>
 
-Both decorators support dynamic paths: `"base.${prop}"` in the constructor. A wrong property type (e.g. `number` for `DataProviderKey<string>`) is a TypeScript error.
+These decorators support dynamic paths: `"base.${prop}"` in the constructor. A wrong property type (e.g. `number` for `DataProviderKey<string>`) is a TypeScript error. See [@handle](#docs/_decorators/handle.md/handle) for method callbacks.
 
 ## Notes