@supersoniks/concorde 4.6.0 → 4.7.3

package/src/docs/_decorators/handle.md

@@ -12,6 +12,7 @@ By default the method is called on **every** assignment, even when the value is
   <template>
 import { handle, Skip } from "@supersoniks/concorde/decorators";
 import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { get, set } from "@supersoniks/concorde/utils";
   </template>
 </sonic-code>
 
@@ -21,24 +22,23 @@ import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
   <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 });
+    const data = get(demoDataKey);
+    set(demoDataKey, { ...data, count: data.count + 1 });
   }
-  //
+
   render() {
     return html`
       &lt;p&gt;Doubled count: ${this.doubled}&lt;/p&gt;
@@ -52,6 +52,7 @@ export class DemoHandle extends LitElement {
 
 <sonic-code>
   <template>
+    <docs-demo-sources for="demo-handle"></docs-demo-sources>
     <demo-handle></demo-handle>
   </template>
 </sonic-code>
@@ -63,21 +64,21 @@ Placeholders in `DataProviderKey` resolve from the host component’s properties
 <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`...`;
   }
@@ -87,6 +88,7 @@ export class DemoHandleDynamic extends LitElement {
 
 <sonic-code>
   <template>
+    <docs-demo-sources for="demo-handle-dynamic"></docs-demo-sources>
     <demo-handle-dynamic></demo-handle-dynamic>
   </template>
 </sonic-code>
@@ -100,10 +102,10 @@ export class DemoHandleDynamic extends LitElement {
 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) {

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

@@ -1,7 +1,6 @@
 # @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.
+> **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.
 
@@ -9,7 +8,7 @@ For a **typed** equivalent (recommended), use [@handle](#docs/_decorators/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.
 
@@ -32,11 +31,11 @@ import { onAssign } 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;
@@ -44,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");
@@ -58,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)],
@@ -70,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>
@@ -83,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>
@@ -134,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(
@@ -173,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 = [
@@ -183,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`;
@@ -191,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({
@@ -200,7 +200,7 @@ export class DemoOnAssignDynamic extends LitElement {
         lastName: randomName.lastName,
         email: randomEmail,
       });
-      //
+
       // Mettre à jour les settings directement
       settingPublisher.set({
         theme: randomTheme,
@@ -208,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}
@@ -224,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;
     `;
   }
 }
@@ -252,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>
@@ -290,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;
@@ -304,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>
@@ -349,11 +349,11 @@ shippingPub.set({ address: "123 Main St" });
 // 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>
@@ -366,10 +366,10 @@ handleDataReady(user: User, settings: Settings) { /* ... */ }
 // 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>

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

package/src/docs/_decorators/subscribe.md

@@ -1,8 +1,17 @@
 # @subscribe
 
-Read-only binding: **only** `DataProviderKey<T>` (no legacy string path). No `reflect` option — the publisher updates the property, not the other way around.
+Keeps a **Lit property** in sync with a **read-only** slice of the DataProvider store. You pass a [`DataProviderKey`](#docs/_misc/dataProviderKey.md/dataProviderKey); when that path changes, the property updates and the component re-renders.
 
-For bidirectional binding or string paths, use [@bind](#docs/_decorators/bind.md/bind).
+Typical setup (same idea as [My first component](#docs/_getting-started/my-first-component.md/my-first-component)):
+
+| Piece | Role |
+|-------|------|
+| **Type** `T` | Shape of the object at that path (`DocsUserData`, `{ count: number }`, …) |
+| **Key** | `DataProviderKey<T, U>` — static path (`"cart"`) or dynamic (`"users.${userIndex}"`, `"${dataProvider}"`) |
+| **Scope on the host** | Properties listed in `U` (e.g. `dataProvider`, `userIndex`) — often filled via [`@ancestorAttribute`](#docs/_decorators/ancestor-attribute.md/ancestor-attribute) |
+| **`@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](#docs/_decorators/publish.md/publish). In templates, the same paths work with [sub()](#docs/_directives/sub.md/sub).
 
 ## Import
 
@@ -10,27 +19,79 @@ For bidirectional binding or string paths, use [@bind](#docs/_decorators/bind.md
   <template>
 import { subscribe } from "@supersoniks/concorde/decorators";
 import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-//
+
 type Data = { count: number };
-const dataKey = new DataProviderKey<Data>("data");
-//
+const dataKey = new DataProviderKey&lt;Data&gt;("data");
+
 @subscribe(dataKey.count)
 @state()
 count = 0;
   </template>
 </sonic-code>
 
-## Highlights
+## Static path
 
-- Strict typing: the property type must match `T`.
-- Dynamic paths: placeholders in `DataProviderKey`, resolved from the host component’s properties.
+The key path is fixed. The property type must match `T` at that segment.
+
+<sonic-code language="typescript">
+  <template>
+const cartKey = new DataProviderKey&lt;{ items: string[] }&gt;("cart");
+
+@subscribe(cartKey)
+@state()
+cart: { items: string[] } | null = null;
+  </template>
+</sonic-code>
+
+## Dynamic path and scope
+
+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:
+
+<sonic-code language="typescript">
+  <template>
+type User = { firstName: string; lastName: string; email: string };
+
+@subscribe(new DataProviderKey&lt;User, { userIndex: number }&gt;("demoUsers.${userIndex}"))
+@state()
+user: User | null = null;
+
+@property({ type: Number }) userIndex = 0;
+  </template>
+</sonic-code>
+
+When `userIndex` changes, `@subscribe` re-resolves the path and refreshes `user`.
+
+## Row / ancestor scope
+
+List items (and wrappers like `<div dataProvider="…">`) set which branch the child reads. Pattern from the tutorial:
+
+<sonic-code language="typescript">
+  <template>
+export const rowKey = new DataProviderKey&lt;
+  User,
+  { dataProvider: string | null }
+&gt;("${dataProvider}");
+
+@ancestorAttribute("dataProvider")
+dataProvider: string | null = null;
+
+@subscribe(rowKey)
+@state()
+user: User | null = null;
+  </template>
+</sonic-code>
 
 ## Demo
 
 <sonic-code>
   <template>
+    <docs-demo-sources for="demo-subscribe-dynamic"></docs-demo-sources>
     <demo-subscribe-dynamic></demo-subscribe-dynamic>
   </template>
 </sonic-code>
 
-See also [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey).
+## See also
+
+- [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) — overview
+- [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) — paths and host generics
+- [sub()](#docs/_directives/sub.md/sub) — same paths inside `html` templates

package/src/docs/_decorators/wait-for-ancestors.md

@@ -30,7 +30,7 @@ The parent is registered via `customElements.define()` (vanilla JS) rather than
   <template>
 import { html, LitElement } from "lit";
 import { customElement, state } from "lit/decorators.js";
-//
+
 // Parent: registered later via customElements.define(), not @customElement
 @dispatchConnectedEvent()
 export class DemoWaitAncestorContainer extends LitElement {
@@ -38,21 +38,21 @@ export class DemoWaitAncestorContainer extends LitElement {
     return html`<slot></slot>`;
   }
 }
-//
+
 // Child: waits for parent before initializing
 @customElement("demo-wait-ancestor-value")
 @awaitConnectedAncestors("demo-wait-ancestor-container[dataProvider]")
 export class DemoWaitAncestorValue extends LitElement {
   @ancestorAttribute("dataProvider")
   dataProvider: string | null = null;
-  //
+
   @state() initializedAt: string = "";
-  //
+
   connectedCallback() {
     super.connectedCallback();
     this.initializedAt = new Date().toISOString();
   }
-  //
+
   render() {
     return html`
       <p>DataProvider from ancestor: <strong>${this.dataProvider || "—"}</strong></p>
@@ -60,7 +60,7 @@ export class DemoWaitAncestorValue extends LitElement {
     `;
   }
 }
-//
+
 // Demo section: register parent via customElements.define() when user clicks
 @customElement("demo-wait-ancestors-section")
 export class DemoWaitAncestorsSection extends LitElement {
@@ -83,7 +83,8 @@ export class DemoWaitAncestorsSection extends LitElement {
 
 <sonic-code>
   <template>
-<demo-wait-ancestors-section></demo-wait-ancestors-section>
+    <docs-demo-sources for="demo-wait-ancestors-section"></docs-demo-sources>
+    <demo-wait-ancestors-section></demo-wait-ancestors-section>
   </template>
 </sonic-code>
 
@@ -105,7 +106,8 @@ When the parent is defined at load and already in the DOM, the child initializes
 
 <sonic-code>
   <template>
-<demo-wait-ancestors-static-section></demo-wait-ancestors-static-section>
+    <docs-demo-sources for="demo-wait-ancestors-static-section"></docs-demo-sources>
+    <demo-wait-ancestors-static-section></demo-wait-ancestors-static-section>
   </template>
 </sonic-code>
 
@@ -113,7 +115,8 @@ When the parent is defined at load and already in the DOM, the child initializes
 
 <sonic-code>
   <template>
-<demo-wait-ancestors-ready-section></demo-wait-ancestors-ready-section>
+    <docs-demo-sources for="demo-wait-ancestors-ready-section"></docs-demo-sources>
+    <demo-wait-ancestors-ready-section></demo-wait-ancestors-ready-section>
   </template>
 </sonic-code>
 
@@ -145,7 +148,7 @@ The `sonic-connected` event bubbles, so you can listen to it from anywhere:
 <sonic-code language="typescript">
   <template>
 import { CONNECTED } from "@supersoniks/concorde/decorators";
-//
+
 someConnectable.addEventListener(CONNECTED, (e) => {
   console.log("Component connected:", e.target);
 });

package/src/docs/_directives/sub.md

@@ -0,0 +1,91 @@
+# sub()
+
+Read-only Lit directive: displays the current **DataProvider** value and updates whenever it is assigned.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { sub } from "@supersoniks/concorde/directives";
+  </template>
+</sonic-code>
+
+## String path
+
+<sonic-code language="typescript">
+  <template>
+render() {
+  return html`&lt;p&gt;Count: ${sub("myCounter.count")}&lt;/p&gt;`;
+}
+  </template>
+</sonic-code>
+
+## DataProviderKey (static)
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { sub } from "@supersoniks/concorde/directives";
+
+const counterKey = new DataProviderKey&lt;{ count: number }&gt;("myCounter");
+
+render() {
+  return html`&lt;p&gt;${sub(counterKey.count)}&lt;/p&gt;`;
+}
+  </template>
+</sonic-code>
+
+## Dynamic DataProviderKey (`${prop}`)
+
+Like `@subscribe`: the path is resolved on the template **host component**; the directive re-subscribes when observed props change.
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { sub } from "@supersoniks/concorde/directives";
+
+type User = { firstName: string; lastName: string; email: string };
+const userKey = new DataProviderKey&lt;User, { userIndex: number }&gt;(
+  "demoUsers.${userIndex}",
+);
+
+@customElement("demo-sub-dynamic")
+export class DemoSubDynamic extends LitElement {
+  @property({ type: Number }) userIndex = 0;
+
+  render() {
+    return html`
+      &lt;p&gt;${sub(userKey.email)}&lt;/p&gt;
+    `;
+  }
+}
+  </template>
+</sonic-code>
+
+## Demo
+
+<sonic-code toggleCode>
+  <template>
+    <docs-demo-sources for="demo-sub-template"></docs-demo-sources>
+    <demo-sub-template></demo-sub-template>
+  </template>
+</sonic-code>
+
+## Concatenation (forms)
+
+<sonic-code language="typescript">
+  <template>
+html`&lt;span&gt;${sub(this.formDataProvider + ".email")}&lt;/span&gt;`
+  </template>
+</sonic-code>
+
+## sub() vs get() / set() / dp()
+
+| API | Context | Dynamic `${…}` |
+|-----|----------|------------------|
+| `sub()` | Lit template, reactive | Yes |
+| `get` / `set` / `dp` | Imperative code | No |
+
+Do not replace `sub(path)` with `get(path)` in a template: `get` returns a one-time snapshot.
+
+See [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey), [@subscribe](#docs/_decorators/subscribe.md/subscribe), and the `concorde-get-set-dp` migration skill.