@supersoniks/concorde 4.6.0 → 4.7.0

package/src/docs/_getting-started/my-first-subscriber.md

@@ -1,7 +1,8 @@
-# My first subscriber component
+# Legacy: My first subscriber component
 
-Learn how to build a subscriber component, styled with tailwind, 
-which could be used as a regular component or could be filled from a dataprovider.
+> **New projects:** use [My first component](#docs/_getting-started/my-first-component.md/my-first-component) (`@ancestorAttribute`, `@subscribe` + `DataProviderKey`, `.items` on lists) and [Data flow](#docs/_core-concept/dataFlow.md/dataFlow). This page documents the **Subscriber mixin** used by older apps and core components.
+
+Learn how to build a component with the **Subscriber** mixin, styled with Tailwind, filled from a DataProvider via automatic property mapping.
 
 ## Create a classic lit component
 
@@ -9,30 +10,24 @@ which could be used as a regular component or could be filled from a dataprovide
   <template>
   import { html, LitElement, nothing } from "lit";
   import { customElement, property } from "lit/decorators.js";
-  // name component
   @customElement("docs-user")
   export class user extends LitElement {
-    // set a few props
     @property({ type: String }) first_name = "";
     @property({ type: String }) last_name = "";
     @property({ type: String }) avatar = "";
     @property({ type: String }) email = "";
-    // output
     render() {
       return html`
-        <img src="${this.avatar}"  /> <br>
-        ${this.first_name} ${this.last_name} <br>
+        &lt;img src="${this.avatar}" /&gt; &lt;br&gt;
+        ${this.first_name} ${this.last_name} &lt;br&gt;
         ${this.email}`;
     }
   }
   </template>
 </sonic-code>
 
-
 ### Style with tailwind and ui components
 
-First export tailwind, in a tailwind.ts file, stylesheet to add it in our component when needed.
-
 <sonic-code language="javascript">
   <template>
   import { css, unsafeCSS } from "lit";
@@ -43,132 +38,83 @@ First export tailwind, in a tailwind.ts file, stylesheet to add it in our compon
 
 <sonic-code language="javascript">
   <template>
-    import { html, LitElement, nothing } from "lit";
+    import { html, LitElement } from "lit";
     import { customElement, property } from "lit/decorators.js";
-    // add tailwind and needed components
     import { tailwind } from "../tailwind";
     import '@supersoniks/concode/ui/image'
     import '@supersoniks/concode/ui/button'
     import '@supersoniks/concode/ui/icon'
-    //
     @customElement("docs-user")
     export class user extends LitElement {
-      // add tailwind stylesheed
       static styles = [tailwind];
       @property({ type: String }) first_name = "";
       @property({ type: String }) last_name = "";
       @property({ type: String }) avatar = "";
       @property({ type: String }) email = "";
-      // use utility class in your markup
       render() {
-        return html`<div
-          class="flex items-center gap-3 rounded-md hover:bg-neutral-50 -mx-2 p-2"
-        >
-          <sonic-image
-            src=${this.avatar}
-            rounded="md"
-            ratio="1/1"
-            class="w-16 block"
-          ></sonic-image>
-          <div>
-            <div>
-              ${this.first_name} <span class="font-bold">${this.last_name}</span>
-            </div>
-            <div class="text-sm text-neutral-400">${this.email}</div>
-          </div>
-          <div class="ml-auto relative">
-            <sonic-button
-              href="mailto:${this.email}"
-              size="sm"
-              variant="outline"
-              shape="circle"
-              class="relative"
-              icon
-            >
-              <sonic-icon library="iconoir" name="chat-bubble"></sonic-icon>
-            </sonic-button>
-          </div>
-        </div>`;
+        return html`&lt;div class="flex items-center gap-3 p-2"&gt;
+          &lt;sonic-image src=${this.avatar} rounded="md" ratio="1/1" class="w-16"&gt;&lt;/sonic-image&gt;
+          &lt;div&gt;${this.first_name} &lt;span class="font-bold"&gt;${this.last_name}&lt;/span&gt;&lt;/div&gt;
+          &lt;div class="text-sm text-neutral-400"&gt;${this.email}&lt;/div&gt;
+        &lt;/div&gt;`;
       }
     }
   </template>
 </sonic-code>
 
-### Basic usage
-
-Reactive properties can be filled by its attributes as a simple lit component.
-
-<sonic-code>
-<template>
-<docs-user
-  first_name="Paul"
-  last_name="Metrand"
-  avatar="/img/paul_metrand_xs.jpg"
-  email="paulmetrand@concorde.fr"
-  ></docs-user>
-</template>
-</sonic-code>
-
 ## Add Subscriber mixin
 
-Import Subscriber mixin, and add it around LitElement.
 <sonic-code language="javascript">
   <template>
-    import { html, LitElement, nothing } from "lit";
-    import { customElement, property } from "lit/decorators.js";
-    import { tailwind } from "../tailwind";
     import Subscriber from "@supersoniks/concorde/core/mixins/Subscriber";
     @customElement("docs-user")
     export class user extends Subscriber(LitElement) {
-      //...
+      // properties auto-filled from DataProvider when names match
     }
   </template>
 </sonic-code>
 
-## Autofill properties from a dataProvider
+See [Legacy: Subscriber mixin](#docs/_core-concept/subscriber.md/subscriber).
+
+## Autofill from a dataProvider
 
-Without a dataProvider attribute, a subscriber set its own dataprovider from first ancestor found, and then reactive properties automatically filled and update from it.
-A fetcher is a simple component which set its fetch result to props of its dataprovider.
 <sonic-code >
 <template>
+<docs-demo-sources for="list-users-fetch"></docs-demo-sources>
+<div serviceURL="/docs-mock-api">
 <sonic-fetch 
-    serviceURL="https://reqres.in"
+    serviceURL="/docs-mock-api"
     dataProvider="api/users/3" 
     key="data">
      <docs-user></docs-user>
 </sonic-fetch>
+</div>
 </template>
 </sonic-code>
 
-A subscriber can subscribe data from anywhere in the DOM, with its dataprovider set as a provider id.  
 <sonic-code >
 <template>
 <sonic-fetch 
-    serviceURL="https://reqres.in"
+    serviceURL="/docs-mock-api"
     dataProvider="api/users/2" 
     key="data"></sonic-fetch>
 <docs-user dataProvider="api/users/2" ></docs-user>
-<docs-user dataProvider="api/users/2" ></docs-user>
-<docs-user dataProvider="api/users/2" ></docs-user>
 </template>
 </sonic-code>
 
-
 <sonic-code >
 <template>
-
 <div class="grid grid-cols-1 gap-4">
 <form formDataProvider="userPreview" class="grid grid-cols-4 gap-3" >
-  <sonic-input label="First name" type="text" name="first_name" placeholder="John" value="Paul"></sonic-input>
-  <sonic-input label="Last name" type="text" name="last_name" placeholder="Doe" value="Metrand"></sonic-input>
-  <sonic-input class="col-span-2"  label="email" type="text" name="email" placeholder="johndoe@concorde.fr" value="paulmetrand@concorde.fr"></sonic-input>
-  <sonic-input type="file" name="avatar" value="/img/paul_metrand_xs.jpg"></sonic-input>
+  <sonic-input label="First name" type="text" name="first_name" value="Paul" size="sm"></sonic-input>
+  <sonic-input label="Last name" type="text" name="last_name" value="Metrand" size="sm"></sonic-input>
+  <sonic-input class="col-span-2" label="email" type="text" name="email" value="paul@example.com" size="sm"></sonic-input>
+  <sonic-input label="Image url" type="text" name="avatar" value="https://i.pravatar.cc/150?u=paul" size="sm"></sonic-input>
 </form>
 <sonic-divider align="left">Preview before submit</sonic-divider>
-<docs-user dataProvider="userPreview" ></docs-user>
-<sonic-button onClick="alert(JSON.stringify(SonicPublisherManager.get('userPreview').get()))">
-  Update data
-</sonic-button>
+<div dataProvider="userPreview">
+  <docs-user></docs-user>
+</div>
 </div>
 </template>
-</sonic-code>
+</sonic-code>

package/src/docs/_getting-started/pubsub.md

@@ -1,150 +1,37 @@
-# Sharing data
+# Legacy: Sharing data
 
-This section describes how we share data between graphical and non graphical components and classes.
+> **New apps:** [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) (`get` / `set` / `DataProviderKey`, decorators). This page documents the historical **Publisher** proxy API (`PublisherManager`, `publisher.set`, `onAssign`, …).
 
-Especialy, graphical components should not reference each other in order to **remain decoupled**.
-
-Thats why we use **publish/subscribe** paradigm to addresse this issue.
+This section describes how data is shared between graphical and non-graphical components.
 
+Graphical components should not reference each other directly — they stay decoupled via a **publish/subscribe** store.
 
 ## The Publisher
 
 ### Principle
 
-* The **publisher** is a [JavaScript proxy](https://developer.mozilla.org/fr/docs/Web/JavaScript/Reference/Global_Objects/Proxy) that contains some data.<br>**
-Example of data : `{foo:{hello:["world"]}, bar:"baz"}`
-
-* if a property of the **publisher** (dot syntax / array access), it returns another **publisher**.
-Using the previous example `myPublisher.foo.hello` is also a publisher containing `["world"]`
+* The **publisher** is a [JavaScript proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) that holds data.<br>
+  Example: `{foo:{hello:["world"]}, bar:"baz"}`
 
-* If the property doesn't exist at the time of the request, a publisher is created. its internal data is set to `null`.<br>
-The value that can then be provided later.
+* Accessing a property (`myPublisher.foo.hello`) returns another **publisher** for that segment.
 
-* **Subscribers** can subscribe to the publisher's modifications and be updated in different ways (see : onAssign, onInternalMutation, startTemplateFilling).
+* Missing properties create a publisher with internal data `null`, filled later.
 
-* Data inside the publisher is updated by modifying the publisher itself, for example `myPublisher.foo.hello = ["Joey", "Smith"]`
-  
-* The publisher publishes modifications to any of its **Subscribers**.
+* **Subscribers** listen via `onAssign`, `onInternalMutation`, template filling on the **Subscriber mixin**, etc.
 
+* Updates use `publisher.set(...)` or nested assignment; changes propagate to subscribers.
 
-❇️ The order of data creation and subscription theoretically has no importance.
+❇️ Order of creation vs subscription theoretically does not matter.
 
 ### Methods
 
-* **set (complete replacement):** Assign/modifies the internal value of the publisher.
-  <sonic-code language="javascript">
-  <template>
-  publisher.set({foo:{hello:["world"]}, bar:"baz"});  
-  </template>
-</sonic-code>
-* **get:** Get the internal value of the publisher.
- <sonic-code language="javascript">
-  <template>
-  publisher.get() //{foo:{hello:["world"]}, bar:"baz"};
-  </template>
-</sonic-code>
-* **onAssign/offAssign:** Subscribe/unsubscribe to value assignments (via `set`) of the publisher.
-<sonic-code language="javascript">
-  <template>
-  publisher.a.b.onAssign(console.log);
-  //indirect
-  publisher.a = {b:"dramatic change"}; //log: "dramatic change"
-  //via set
-  publisher.a.b.set(["Hello"]) //log: ["Hello"]
-  </template>
-</sonic-code>
-* **onInternalMutation/offInternalMutation:** Listen to any internal mutation regardless of its depth level.
-<sonic-code language="javascript">
-  <template>
-  function save(){
-  	console.log("Something has changed, let's save");
-  }
-  publisher.onInternalMutation(save);
-  publisher.a.b[0] = "e";
-  </template>
-</sonic-code>
-* **startTemplateFilling/stopTemplateFilling:** Fill an object model, a principle used with the Subscriber mixin on which most Concorde components rely.
-<sonic-code language="javascript">
-  <template>
-  const fillableTemplate =  { title: "A title to be replaced"};
-  publisher.startTemplateFilling(fillableTemplate);
-  state.title = "Good morning";
-  publisher.stopTemplateFilling(fillableTemplate);
-  state.title = "Oops";
-  console.log(fillableTemplate);
-  </template>
-</sonic-code>
-* **invalidate:** Flag the data as invalid. Used by sonic-fetch and sonic-list to trigger data reloading.
-<sonic-code language="javascript">
-  <template>
-publisher.invalidate();
-  </template>
-</sonic-code>
-* **onInvalidate/offInvalidate:** Subscribe/unsubscribe to data invalidation of the publisher. Used by sonic-fetch and sonic-list to trigger data reloading.
-<sonic-code language="javascript">
-  <template>
-function reloadData(){
-  console.log("Reload data to inject it again into the publisher");
-}
-publisher.onInvalidate(reloadData);
-  </template>
-</sonic-code>
-
-## DataProvider
-
-Denotes the identifier of a publisher as referenced in the PublisherManager (see below).
-Uses the dataProvider attribut in html tags to scop the content with some data.
-see [Subscribers](#docs/_core-concept/subscriber.md/subscriber).
-
-
-## PublisherManager
-
-The **PublisherManager** is a utility class to get publishers
-
-It plays a central role in the components, especially through the "subscriber" mixin.<br>
-Automatic data communication between components in concorde uses this principle in conjunction with Lit's reactive properties. <br>
-Refer to the documentation for [Subscriber](#docs/_core-concept/subscriber.md/subscriber).
-
-<sonic-code language="javascript">
-  <template>
-import { PublisherManager } from "publisherproxy";
-let dataProvider = "cart";
-let publisher = PublisherManager.get(dataProvider);
-
-  </template>
-</sonic-code>
-
-It is declared on the `window` object to allow usage in a web page, so the equivalent one-liner would be:
-
-<sonic-code language="javascript">
-  <template>
-let dataProvider = "cart";
-let publisher = SonicPublisherManager.get(dataProvider);
-
-  </template>
-</sonic-code>
-
-
-## Basic Example
-
-This example can be tested in a console when Concorde is loaded on the page (for example, in a ticketing system).
-In a component, you will need to perform an `import` as explained earlier.
-
-<sonic-code language="javascript">
-  <template>
-// Anywhere, anytime
-SonicPublisherManager.get("mySubject").title.onAssign(console.log) 
-
-  </template>
-</sonic-code>
-
-<sonic-code language="javascript">
-  <template>
-// Anywhere, anytime
-let publisher = SonicPublisherManager.get("mySubject");
-// ...
-publisher.set({title: "A title"});
-publisher.title.set("A second title");
-
-  </template>
-</sonic-code>
+* **set** — replace internal value  
+  <sonic-code language="javascript"><template>publisher.set({foo:{hello:["world"]}, bar:"baz"});</template></sonic-code>
+
+* **get** — read internal value  
+  <sonic-code language="javascript"><template>publisher.get()</template></sonic-code>
+
+* **onAssign / offAssign** — react to `set`  
+  <sonic-code language="javascript"><template>publisher.a.b.onAssign(console.log);</template></sonic-code>
+
+Modern equivalent: `get` / `set` / `@handle` — see [Data flow](#docs/_core-concept/dataFlow.md/dataFlow).

package/src/docs/_getting-started/start.md

@@ -1,39 +1,47 @@
 # Introduction
 
-## What is Concorde ? 
+## What is Concorde?
 
-Based on **[lit.dev](https://lit.dev)**, Concorde is a collection of webcomponents made to build shared apps or websites.  
-Develop user interfaces without thinking about the implementation context, where everything is scoped, but preserving graphic consistency by setting the strict minimum of css variables.
+Based on **[lit.dev](https://lit.dev)**, Concorde is a collection of web components for shared apps and websites.  
+Build UIs without tying components to a specific host stack, while keeping visual consistency through a small set of CSS variables.
 
 ## Why and use case
 
-In 2022, Supersoniks wanted to create a new version of his ticketing app, in production un nearly 100 websites. We needed shared components which could be implemented in mobile apps, modern websites, and also old ones made in php, without bundlers or whatever.  
-Instead of building a new app for each type of project, which would become impossible to maintain, we've decided to create one app, composed by a few webcomponents wich could easily be recomposed on any website.
-Webcomponents appeared to be a the perfect solution to guarantee that compatibility with all past, present and futures environment, and lit seemed to be the best choice to build them.
+In 2022, Supersoniks needed a new ticketing stack for nearly 100 sites — mobile apps, modern sites, and legacy PHP without bundlers.  
+One composable web-component library replaced many one-off apps. Lit was chosen for broad runtime compatibility.
 
 ### Stack
 
 * Lit
-* Typescript
+* TypeScript
 * Vite
-* Tailwind, not in the core, but in the starter kit
+* Tailwind (starter kit, not required in the core package)
 
-### Functionnal features and components
+### Functional features
 
-* Data management with Publisher / Subscriber pattern
-* Form management
-* Fetching data, lists, queue with lazyload
-* Data binding
-* Simple router, state component, ...
-* And all ui component, with status variants to build an app with a consistent design
+* **DataProvider** store (decorators, `get` / `set`)
+* Forms (`formDataProvider`)
+* Lists, queues, lazy loading
+* Router, states, UI kit with status variants
 
+## Learn Concorde
 
-## Start a new project easily 
+| Step | Page |
+|------|------|
+| 1 | [My first component](#docs/_getting-started/my-first-component.md/my-first-component) — Lit card, `@ancestorAttribute`, `@bind`, mock API |
+| 2 | [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) — Core concepts: decorators and APIs |
+| 3 | [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) — offline `serviceURL` for this site (Misc) |
+| 4 | [create-concorde-ts-starter](https://www.npmjs.com/package/@supersoniks/create-concorde-ts-starter) — **recommended** project kit (Vite, Tailwind, `yarn ai:sync`) |
+| 5 | [AI agents (skills)](#docs/_getting-started/ai-agents.md/ai-agents) — `AGENTS.md`, Cursor / JetBrains rules |
 
-A new project with Vite, Typescript and Tailwind already configured and a simple example of a subscriber component : 
+Legacy (Subscriber mixin, Publisher API): **Legacy** section at the bottom of the sidebar.
+
+## Start a new project
 
 <sonic-code language="bash">
   <template>
-  npx @supersoniks/create-concorde-ts-starter "project_name"
+npx @supersoniks/create-concorde-ts-starter "project_name"
   </template>
 </sonic-code>
+
+The starter runs **`yarn ai:sync`** for you. Details: [AI agents (skills)](#docs/_getting-started/ai-agents.md/ai-agents). Manual Vite setup: [Legacy: Manual installation](#docs/_getting-started/concorde-manual-install.md/concorde-manual-install).

package/src/docs/_misc/api-configuration.md

@@ -0,0 +1,79 @@
+# API configuration
+
+`APIConfiguration` is the object built by [`HTML.getApiConfiguration`](../../core/utils/HTML.ts) from **ancestor attributes** on the DOM (or from a typed publisher — see [@get configuration key](#docs/_decorators/get.md/get)). It is passed to [`API`](../../core/utils/api.ts) by fetchers, **sonic-submit**, the **`wording()`** directive, and **`@get`**.
+
+> **Mock service:** same [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) Service Worker / Vite middleware. Routes used on this page are listed in the [API config routes](#api-config-routes) section below.
+
+## Attribute map
+
+| Attribute (ancestor) | `APIConfiguration` field | Role |
+|---------------------|---------------------------|------|
+| `serviceURL` | `serviceURL` | Base URL (e.g. `/docs-mock-api`) |
+| `token` | `token` | Static Bearer sent on REST calls |
+| `userName` / `password` | `userName` / `password` | Basic auth for **tokenProvider** fetch only |
+| `eventsApiToken` | `authToken` | Bearer for **tokenProvider** when no Basic |
+| `tokenProvider` | `tokenProvider` | Path to GET a new token (`{ token }` JSON) |
+| `wordingProvider` | — (read by `wording()`) | Base path + query for label batch GET |
+| `wordingVersionProvider` | — | Publisher id; bump version → reload wordings |
+| `credentials` | `credentials` | `fetch` credentials mode |
+| `addHTTPResponse` | `addHTTPResponse` | Attach `_sonic_http_response_` on result |
+| `cache` | `cache` | `fetch` cache mode |
+| `blockUntilDone` | `blockUntilDone` | Serialize calls per `serviceURL` |
+| `keepAlive` | `keepAlive` | `fetch` keepalive |
+
+**Lit / TypeScript:** store the same shape in a publisher and pass `DataProviderKey<APIConfiguration>` as the second argument of `@get` (see [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey)).
+
+## Bearer token (static)
+
+Publisher `docsApiConfBearerKey` (`set(docsApiConfBearerKey, { token: "docs-mock-valid-token", … })`) — mock returns the protected payload.
+
+<docs-lit-demo for="docs-api-config-bearer-demo"></docs-lit-demo>
+
+## tokenProvider + Basic auth
+
+No static `token`: `API.auth()` calls `GET /docs-mock-api/auth/token` with Basic **demo** / **secret**, stores `token`, then calls the protected route.
+
+<docs-lit-demo for="docs-api-config-token-provider-demo"></docs-lit-demo>
+
+## HTTP 498 — stale token refresh
+
+Initial `token="docs-mock-stale-token"` → mock responds **498** → Concorde invalidates the token, runs `auth()` again (same `tokenProvider` + Basic), retries with `docs-mock-fresh-token`.
+
+<docs-lit-demo for="docs-api-config-stale-token-demo"></docs-lit-demo>
+
+## eventsApiToken
+
+Attribute **`eventsApiToken`** on an ancestor maps to **`authToken`** in config (used as Bearer when calling `tokenProvider`, instead of Basic).
+
+<docs-lit-demo for="docs-api-config-events-token-demo"></docs-lit-demo>
+
+## Wording API
+
+`wordingProvider="wording/labels?lang=fr"` + `wording('api-config.greeting')` in Lit. Mock returns label map from `labels[]` query params.
+
+<docs-lit-demo for="docs-api-config-wording-demo"></docs-lit-demo>
+
+## Scoped attributes (HTML / sonic-scope)
+
+Attributes on **`sonic-scope`** (or any ancestor) are visible to descendants via `getAncestorAttributeValue`.
+
+<docs-lit-demo for="docs-api-config-scoped-attrs-demo"></docs-lit-demo>
+
+## API config routes
+
+| Route | Demo |
+|-------|------|
+| `GET /docs-mock-api/auth/token` | tokenProvider, eventsApiToken |
+| `GET /docs-mock-api/api/config/protected` | Bearer / Basic / 498 |
+| `GET /docs-mock-api/wording/labels?labels[]=…&lang=fr` | `wording()` |
+
+Mock tokens (doc only): `docs-mock-valid-token`, `docs-mock-stale-token` (498), `docs-mock-fresh-token` (after refresh). Basic: **demo** / **secret**. Events token: `docs-mock-events-token`.
+
+Implementation: `src/docs/mock-api/api-config-mock.ts` (bundled in the Service Worker with `router.ts`).
+
+## See also
+
+- [@get](#docs/_decorators/get.md/get) — `APIConfiguration` + `Endpoint`
+- [Endpoint](#docs/_misc/endpoint.md/endpoint) — typed path
+- [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) — offline `serviceURL`
+- [Fetch](#core/components/functional/fetch/fetch.md/fetch) — attribute table (legacy sonic-fetch)

package/src/docs/_misc/dataProviderKey.md

@@ -2,12 +2,26 @@
 
 The `DataProviderKey<T>` utility provides type-safe navigation through composite data structures. Each property or index access extends the path, and the final key can be retrieved via `toString()` or the `path` property.
 
-For a **single HTTP path string** (no dot-syntax), see [Endpoint](#docs/_misc/endpoint.md/endpoint).
+For a **single HTTP path string** (no dot-syntax), see [Endpoint](#docs/_misc/endpoint.md/endpoint). For **`DataProviderKey<APIConfiguration>`**, see [API configuration](#docs/_misc/api-configuration.md/api-configuration).
 
 ## Principle
 
 `DataProviderKey` uses a Proxy to intercept property access and build a cumulative path string. TypeScript infers the nested type at each level, so `myKey.items[0]` is correctly typed as `DataProviderKey<Item>` when `items` is `Item[]`.
 
+In Lit demos, bind HTML attributes from a key’s **`.path`** (single source of truth), and use **`get` / `set` / `dp`** instead of `PublisherManager.get("…")`:
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { get, set } from "@supersoniks/concorde/utils";
+
+export const myFormKey = new DataProviderKey&lt;{ email: string }&gt;("myForm");
+set(myFormKey, { email: "a@b.c" });
+
+// template: formDataProvider=${myFormKey.path}
+  </template>
+</sonic-code>
+
 ## Usage
 
 ### Import
@@ -77,6 +91,25 @@ user: User | null = null;
   </template>
 </sonic-code>
 
+Dynamic keys are **not** supported by `get`, `set`, or `dp` — those APIs take a snapshot at call time with no component context. For dynamic paths use decorators (`@subscribe`, `@publish`, `@handle`) or **`sub(key)`** in Lit templates (resolves `${…}` from the host component). See [sub()](#docs/_directives/sub.md/sub).
+
+### get / set / dp with static keys
+
+For programmatic access, pass a `DataProviderKey` or a static path string. Dynamic placeholders are rejected:
+
+<sonic-code language="typescript">
+  <template>
+import { dp, get, set } from "@supersoniks/concorde/utils";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+//
+const counterKey = new DataProviderKey&lt;{ count: number }&gt;("myCounter");
+//
+set(counterKey, { count: 0 });
+dp(counterKey.count).set(1);
+get(counterKey);  // snapshot: { count: 1 }
+  </template>
+</sonic-code>
+
 ## Path retrieval
 
 The final path is built by concatenating each accessed property with a dot:

package/src/docs/_misc/docs-mock-api.md

@@ -0,0 +1,60 @@
+# Local API demos (offline)
+
+The Concorde doc site does not call fragile third-party APIs during `yarn dev`. A **Service Worker** and the Vite dev middleware serve **`/docs-mock-api/*`** on the same origin.
+
+## How it works
+
+1. On load, `registerDocsMockApiServiceWorker()` registers `/docs-mock-api-sw.js`.
+2. Requests to `/docs-mock-api/...` are handled by the SW (production build) or Vite middleware (dev).
+3. Live examples use `serviceURL="/docs-mock-api"` and relative paths.
+
+TypeScript constants: `src/docs/mock-api/urls.ts` (`DOCS_MOCK_REQRES_SERVICE`, `DOCS_MOCK_GEO_SERVICE`, …).
+
+## Routes
+
+| Path | Used in |
+|------|---------|
+| `/docs-mock-api/api/users` | `sonic-list`, `sonic-fetch`, `sonic-queue` (users) |
+| `/docs-mock-api/api/users/:id` | Single user, `docs-user` |
+| `POST /docs-mock-api/api/register` | **sonic-submit** — JSON, `multipart/form-data` (`sendAsFormData`), or `application/x-www-form-urlencoded` (native `<form>`); response includes parsed `email` + `token` |
+| `POST /docs-mock-api/api/register/nested` | Wrapped body `{ data: { id, token } }` for `submit-result-key` demo |
+| `GET /docs-mock-api/api/register/echo` | Echoes query string (`method="get"` on submit) |
+| `GET /docs-mock-api/auth/token` | [API configuration](#docs/_misc/api-configuration.md/api-configuration) — tokenProvider (Basic or `eventsApiToken`) |
+| `GET /docs-mock-api/api/config/protected` | Bearer / Basic; `docs-mock-stale-token` → **498** |
+| `GET /docs-mock-api/wording/labels` | Wording batch (`labels[]`, `lang`) |
+| `/docs-mock-api/geo/communes` | Geo list, `@get` demos |
+| `/docs-mock-api/jokes/joke/:category` | JokeAPI-shaped list (`key="jokes"` on queue/list) |
+
+### Filtres `GET /jokes/joke/…`
+
+| Query | Meaning |
+|-------|---------|
+| `amount` | Max jokes per request when not using `offset` |
+| `offset` + `limit` / `per_page` | Pagination for **sonic-queue** lazy load |
+| `contains` | Substring on joke text, setup/delivery, categories (**input** demo, `name="contains"`) |
+| `lang` | `fr` or `en` — filters the local dataset (**select** demo, `name="lang"`) |
+| `blacklistFlags` | Comma-separated flags to **exclude** (`nsfw`, `religious`, `political`, `racist`, `sexist`, `explicit`) — checkbox/radio/switch « Remove following jokes » demos; each joke has matching `flags` in fixtures |
+
+### Pagination `GET /api/users`
+
+| Query | Meaning |
+|-------|---------|
+| `offset` + `per_page` | Index-based slice on the filtered set — **sonic-queue** (`offset=$offset&per_page=$limit`) |
+| `page` + `per_page` | 1-based page — static fetch examples (`?page=2`) |
+| `limit` | Alias of `per_page` |
+| `q` | Search on first name, last name, email (optional; **sonic-queue** + `dataFilterProvider`, field `name="q"`) |
+
+**ALTCHA** (`sonic-captcha`) is **not** mocked — it still uses the Supersoniks service.
+
+In TypeScript demos, import from `src/docs/mock-api/urls.ts` (e.g. `DOCS_MOCK_REQRES_SERVICE` on `serviceURL`).
+
+## Source files
+
+- `src/docs/mock-api/` — router, fixtures, service worker, `urls.ts`
+- `scripts/docs-mock-api-vite-plugin.ts` — SW build + middleware
+- `public/docs-mock-api-sw.js` — generated on `yarn dev` / `yarn build-docs`
+
+```bash
+yarn dev          # mock API on by default
+yarn build-docs   # includes SW bundle
+```

package/src/docs/_misc/endpoint.md

@@ -18,7 +18,7 @@ import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
   <template>
 const users = new Endpoint&lt;User[]&gt;("users?limit=10");
 users.path; // "users?limit=10"
-//
+
 const one = new Endpoint&lt;User, { userId: string }&gt;("users/${userId}");
 // `userId` on the host class is observed when used with @get
   </template>
@@ -38,5 +38,6 @@ const one = new Endpoint&lt;User, { userId: string }&gt;("users/${userId}");
 
 ## See also
 
+- [API configuration](#docs/_misc/api-configuration.md/api-configuration) — `serviceURL`, token, wording (mock demos)
 - [@get](#docs/_decorators/get.md/get) — decorator that uses `Endpoint<T>`
 - [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) — typed publisher paths (dot notation)