@supersoniks/concorde 5.1.1 → 5.1.3

package/src/docs/home/home.ts

@@ -5,8 +5,8 @@ import { sectionPages } from "../navigation/components-index";
 import { COMPONENT_NOTES } from "./catalog";
 import "./mach-stage";
 
-const GET_STARTED = "#docs/_getting-started/start.md/start";
-const COMPONENTS_PAGE = "#docs/_getting-started/components.md/components";
+const GET_STARTED = "/docs/getting-started/start";
+const COMPONENTS_PAGE = "/docs/getting-started/components";
 
 /**
  * Presets for the theming instrument: palette, typeface and radius all come from tokens.
@@ -125,7 +125,13 @@ const INDEX_TABS = [
   { title: "Functional components", label: "Functional" },
 ];
 
-const ARCHIVE = "./img/archive/";
+/** Components listed in the sidebar, so the count follows the menu (hidden pages excluded). */
+const COMPONENT_COUNT = INDEX_TABS.reduce(
+  (total, tab) => total + sectionPages(tab.title).length,
+  0,
+);
+
+const ARCHIVE = "/img/archive/";
 
 /** Credit lines for the archive pictures (CC BY / CC BY-SA, from assets.mjs --credits). */
 const CREDITS = `Film: <a href="https://commons.wikimedia.org/wiki/File:Concorde_%26_Red_Arrows_2002.webm">“Concorde &amp; Red Arrows 2002”</a> by Steve Elliott, <a href="https://creativecommons.org/licenses/by-sa/2.0/">CC BY-SA 2.0</a>, via Wikimedia Commons.`;
@@ -209,10 +215,10 @@ this.querySelectorAll("[data-reveal]").forEach((el) =>
           Web components<br />for every stack.
         </h1>
         <div class="hero-actions hero-in" style="--d:180ms">
-          <sonic-button size="lg" type="primary" class="signal-button" href=${GET_STARTED}
+          <sonic-button size="lg" type="primary" class="signal-button" pushState href=${GET_STARTED}
             >Open the manual</sonic-button
           >
-          <sonic-link href=${COMPONENTS_PAGE} class="text-link"
+          <sonic-link pushState href=${COMPONENTS_PAGE} class="text-link"
             >Browse the components</sonic-link
           >
         </div>
@@ -229,7 +235,7 @@ this.querySelectorAll("[data-reveal]").forEach((el) =>
   private renderManifesto() {
     return html`<section class="manifesto" aria-label="What Concorde is">
       <p class="manifesto-text" data-reveal>
-        Concorde is a Lit library of 41 web components. They bind data, call
+        Concorde is a Lit library of ${COMPONENT_COUNT} web components. They bind data, call
         APIs and theme themselves from plain HTML, in React, Vue, PHP or a
         static page.
       </p>
@@ -251,7 +257,7 @@ this.querySelectorAll("[data-reveal]").forEach((el) =>
     const focus = COMPONENT_NOTES[this.focus] ?? COMPONENT_NOTES[pages[0]?.label];
     return html`<section class="index" aria-labelledby="index-title">
       <div class="index-head" data-reveal>
-        <h2 id="index-title" class="section-title">41 components,<br />one tag each.</h2>
+        <h2 id="index-title" class="section-title">${COMPONENT_COUNT} components,<br />one tag each.</h2>
         <div class="index-filters" role="group" aria-label="Component families" data-ui>
           ${INDEX_TABS.map((t, i) => {
             const on = this.families.has(i);
@@ -268,9 +274,10 @@ this.querySelectorAll("[data-reveal]").forEach((el) =>
         </div>
       </div>
       <p class="index-wall">
-        ${pages.map(
+          ${pages.map(
           (page) => html`<span class="wall-item"
               ><sonic-link
+                pushState
                 href=${page.href}
                 class="wall-name ${page.label === this.focus ? "is-focus" : ""}"
                 @mouseenter=${() => (this.focus = page.label)}
@@ -283,7 +290,7 @@ this.querySelectorAll("[data-reveal]").forEach((el) =>
       <div class="index-caption" aria-live="polite">
         <code class="index-caption-tag">&lt;${focus?.tag ?? ""}&gt;</code>
         <span class="index-caption-note">${focus?.note ?? ""}</span>
-        <sonic-link href=${COMPONENTS_PAGE} class="text-link index-caption-all"
+        <sonic-link pushState href=${COMPONENTS_PAGE} class="text-link index-caption-all"
           >All components</sonic-link
         >
       </div>
@@ -489,11 +496,13 @@ this.querySelectorAll("[data-reveal]").forEach((el) =>
       <div class="footer-line">
         <span>Concorde, web components by Supersoniks</span>
         <nav class="footer-links" aria-label="Footer">
-          <sonic-link href=${GET_STARTED}>Docs</sonic-link>
-          <sonic-link href=${COMPONENTS_PAGE}>Components</sonic-link>
+          <sonic-link pushState href=${GET_STARTED}>Docs</sonic-link>
+          <sonic-link pushState href=${COMPONENTS_PAGE}>Components</sonic-link>
           <sonic-link href="https://www.npmjs.com/package/@supersoniks/concorde" target="_blank"
             >npm</sonic-link
           >
+          <sonic-link href="/about">About</sonic-link>
+          <sonic-link href="/privacy">Privacy</sonic-link>
         </nav>
         <span class="footer-end">MIT licence · ${new Date().getFullYear()}</span>
       </div>

package/src/docs/layout.ts

@@ -1,20 +1,19 @@
-const onLocationChange = (location: Location) => {
-  // Docs pages all live in the hash: no hash means the home, whatever the path
-  // (served at /, /index.html or from a sub-folder).
-  if (location.hash === "") {
+import LocationHandler from "@supersoniks/concorde/core/utils/LocationHandler";
+import { parseDocsLocation } from "./docs-location";
+
+const onLocationChange = (locationHref: string) => {
+  const { url } = parseDocsLocation(locationHref);
+  // No markdown path → home.
+  if (!url) {
     document.documentElement.setAttribute("data-home", "");
   } else {
     document.documentElement.removeAttribute("data-home");
   }
 };
-const getCurrentLocation = () => document.location;
-const currentLocation: Location = getCurrentLocation();
-onLocationChange(currentLocation);
-window.addEventListener("popstate", (event) => {
-  onLocationChange(getCurrentLocation());
-});
 
-// Listen for changes in the URL hash
-window.addEventListener("hashchange", () => {
-  onLocationChange(getCurrentLocation());
+// LocationHandler polls document.location (covers pushState; popstate alone does not).
+LocationHandler.onChange({
+  set location(value: string) {
+    onLocationChange(value);
+  },
 });

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](/docs/decorators/get) / [@post](/docs/decorators/post) configuration key). It is passed to [`API`](../../core/utils/api.ts) by fetchers, **sonic-submit**, the **`wording()`** directive, **`@get`**, **`@post`**, **`@put`**, and **`@patch`**.
+
+> **Mock service:** same [Local API demos](/docs/misc/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)).
+
+## 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` and `wordingVersionProvider` are read by the translation directive: see [t()](/docs/directives/t).
+
+## 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) — `APIConfiguration` + `Endpoint`
+- [@post](/docs/decorators/post) — same configuration model for POST
+- [@put](/docs/decorators/put) · [@patch](/docs/decorators/patch) — PUT / PATCH
+- [Endpoint](/docs/misc/endpoint) — typed path
+- [Local API demos](/docs/misc/docs-mock-api) — offline `serviceURL`
+- [Fetch](/core/components/functional/fetch) — attribute table (legacy sonic-fetch)

package/src/docs/misc/dataProviderKey.md

@@ -0,0 +1,168 @@
+# DataProviderKey
+
+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). For **`DataProviderKey<APIConfiguration>`**, see [API configuration](/docs/misc/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
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+  </template>
+</sonic-code>
+
+### Basic example
+
+<sonic-code language="typescript">
+  <template>
+type Item = { id: string; name: string };
+//
+type Data = {
+  items: Item[];
+  count: number;
+};
+//
+const myKey = new DataProviderKey&lt;Data&gt;("data").items[0];
+// Equivalent to: new DataProviderKey&lt;Item&gt;("data.items.0")
+myKey.toString();  // "data.items.0"
+myKey.path;        // same value
+// myKey is typed as DataProviderKey&lt;Item&gt;
+  </template>
+</sonic-code>
+
+### Object property access
+
+<sonic-code language="typescript">
+  <template>
+const key = new DataProviderKey&lt;Data&gt;("data");
+const countKey = key.count;
+countKey.path;        // "data.count"
+countKey.toString();  // "data.count"
+  </template>
+</sonic-code>
+
+### Array index access
+
+<sonic-code language="typescript">
+  <template>
+const itemsKey = new DataProviderKey&lt;Data&gt;("data").items;
+itemsKey.path;  // "data.items"
+// itemsKey is DataProviderKey&lt;Item[]&gt;
+//
+const firstItem = itemsKey[0];
+firstItem.path;  // "data.items.0"
+// firstItem is DataProviderKey&lt;Item&gt;
+  </template>
+</sonic-code>
+
+### Dynamic paths
+
+Use placeholders `${prop}` or `{$prop}` in the path string. The path is resolved at runtime from the component's properties. See [Dynamic path placeholders](/docs/misc/dynamic-path) for resolution rules and `skipEmptyPlaceholder`. The type remains declarative:
+
+<sonic-code language="typescript">
+  <template>
+type User = { name: string; email: string };
+//
+// Path resolved from component.userIndex at runtime
+@subscribe(new DataProviderKey&lt;User&gt;("users.${userIndex}"))
+@state()
+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).
+
+### 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:
+
+- `new DataProviderKey<T>("base")` → `"base"`
+- `key.prop` → `"base.prop"`
+- `key.items[0]` → `"base.items.0"`
+
+Use `toString()` or `path` to get the full path string:
+
+<sonic-code language="typescript">
+  <template>
+const key = new DataProviderKey&lt;Data&gt;("data").count;
+const pathString = key.toString();  // "data.count"
+const pathProp = key.path;           // "data.count"
+  </template>
+</sonic-code>
+
+## Use cases
+
+- **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, @publish and @handle
+
+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>
+import { subscribe } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+//
+type FormData = { email: string };
+const formKey = new DataProviderKey&lt;FormData&gt;("formData");
+//
+@customElement("user-form")
+export class UserForm extends LitElement {
+  @subscribe(formKey.email)
+  @state()
+  email = "";
+//
+  render() {
+    return html`&lt;input .value=${this.email} @input=${(e) => this.email = (e.target as HTMLInputElement).value}&gt;`;
+  }
+}
+  </template>
+</sonic-code>
+
+These decorators support dynamic paths: `"base.${prop}"` in the constructor. A wrong property type (e.g. `number` for `DataProviderKey<string>`) is a TypeScript error. Resolution rules: [Dynamic path placeholders](/docs/misc/dynamic-path). See [@handle](/docs/decorators/handle) for method callbacks.
+
+## Notes
+
+- Function properties are excluded from navigation (no `key.method()` chaining)
+- Primitives have no navigable properties
+- The `path` property and `toString()` are equivalent for retrieving the key

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

@@ -0,0 +1,62 @@
+# 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` | [My first component](/docs/getting-started/my-first-component) users list |
+| `/docs-mock-api/api/users/:id` | Single user, `docs-user` |
+| `/docs-mock-api/api/space-cats` | Fixtures shared with the jsonata unit tests |
+| `/docs-mock-api/api/coffee-bags` | fixtures / tests jsonata (`?roast=`) |
+| `/docs-mock-api/api/market-order` | Fixtures shared with the jsonata unit tests |
+| `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 the `submitResultKey` 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) — 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` | `@get` demos |
+| `GET /docs-mock-api/flights` | Flight board (`key="flights"`): `sonic-list` · `sonic-fetch` · `sonic-queue` · `sonic-jsonata` · `sonic-states` and the input / select / radio / switch filter demos |
+
+### Filters `GET /flights`
+
+| Query | Meaning |
+|-------|---------|
+| `direction` | `departures` · `arrivals` |
+| `q` | Substring on flight number, city or airport code |
+| `status` | Comma-separated statuses to keep: `on-time` · `boarding` · `delayed` · `landed` · `cancelled` (`all` = no filter) |
+| `offset` + `limit` | Pagination for **sonic-queue** lazy load |
+
+### 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/dynamic-path.md

@@ -0,0 +1,71 @@
+# Dynamic path placeholders
+
+Decorators and `DataProviderKey` paths can include **placeholders** resolved on the host component at runtime:
+
+- `${prop}` or `{$prop}` — e.g. `"users/${userId}"`, `"api/sessions/${sessionId}/sync"`
+- Nested expressions — e.g. `"teams.${teamId}.members"`
+
+Resolution is done by [`resolveDynamicPath`](../../core/decorators/subscriber/dynamicPath.ts). The root property names (`userId`, `sessionId`, …) are watched via `requestAnimationFrame` (see `dynamicPropertyWatch.ts`).
+
+## Default behaviour (`ready` / `not ready`)
+
+| Placeholder value | Path `ready`? | Inserted segment | Notes |
+|-------------------|---------------|------------------|-------|
+| `undefined` | **no** | — | Wait until defined |
+| `null` | **no** | — | Same as undefined |
+| `""` | **yes** | empty string | e.g. `sessions//sync` — request may still run |
+| `0` | **yes** | `"0"` | Not treated as “missing” |
+| `false` | **yes** | `"false"` | |
+| `42`, `"alpha"` | **yes** | `"42"`, `"alpha"` | |
+
+When `ready: false`, decorators **do not** call the network (for `@get` / `@post` / `@put` / `@patch`), **unsubscribe** (`@bind` / `@subscribe`), or skip publisher binding (`@publish` / `@handle`). The decorated property is often left unchanged or set to `undefined` (HTTP decorators).
+
+When the placeholder later becomes valid, observers run again and behaviour resumes.
+
+## `skipEmptyPlaceholder` option
+
+Some APIs should not run while an id is still `""`. Opt in per decorator:
+
+```typescript
+@get(new Endpoint<User, { userId: string }>("users/${userId}"), {
+  skipEmptyPlaceholder: true,
+})
+```
+
+| Option | Scope |
+|--------|--------|
+| `skipEmptyPlaceholder?: boolean` | **Only** empty string `''` on a placeholder |
+| Default `false` | `""` is inserted into the path (legacy behaviour) |
+| `true` | `""` → `ready: false`, same as `null` / `undefined` for that segment |
+
+Does **not** affect `0`, `false`, `null`, or `undefined` (nullish stays “not ready” regardless).
+
+Available on:
+
+| API | Where |
+|-----|--------|
+| `@get` | 2nd or 3rd argument (`GetOptions`) |
+| `@post` / `@put` / `@patch` | `PostOptions` / `ApiSendOptions` |
+| `@bind` | `BindOptions` |
+| `@publish` | 2nd argument `PublishOptions` |
+| `@handle` | `HandleOptions` |
+
+## Per-decorator summary
+
+| Decorator | `ready: false` | `ready: true` |
+|-----------|----------------|---------------|
+| `@get` | No HTTP; `payload` → `undefined` | `ApiResult` assigned |
+| `@post` / `@put` / `@patch` | No HTTP; `payload` → `undefined` | `ApiResult` assigned |
+| `@subscribe` / `@bind` | Unsubscribe; prop keeps last value | Subscribe `onAssign` |
+| `@publish` | Internal publisher `null`; writes ignored | `publisher.set` on assign |
+| `@handle` | No subscription; with `waitForAllDefined`, method not called | Callback on assign |
+
+## See also
+
+- [DataProviderKey](/docs/misc/dataProviderKey) — path syntax
+- [Endpoint](/docs/misc/endpoint) — HTTP paths + host generic `U`
+- HTTP: [@get](/docs/decorators/get) · [@post](/docs/decorators/post) · [@put](/docs/decorators/put) · [@patch](/docs/decorators/patch)
+- Store: [@subscribe](/docs/decorators/subscribe) · [@bind](/docs/decorators/bind) · [@publish](/docs/decorators/publish) · [@handle](/docs/decorators/handle)
+- Legacy strings: [@onAssign](/docs/decorators/on-assign) (dynamic paths section)
+- Templates: [sub()](/docs/directives/sub) — dynamic paths in Lit (no `skipEmptyPlaceholder` yet)
+- Tutorial: [My first component](/docs/getting-started/my-first-component) — `"${dataProvider}"` scope pattern

package/src/docs/misc/endpoint.md

@@ -0,0 +1,45 @@
+# Endpoint
+
+`Endpoint<T, U>` describes a single HTTP path (or a path accepted by `API.get`) and carries the expected response type `T`. Unlike [DataProviderKey](/docs/misc/dataProviderKey), there is no dot-navigation: the path is one string.
+
+The optional second generic `U` (default `any`) describes host properties used to resolve dynamic segments in the path (`${…}` / `{$…}`), for example with [@get](/docs/decorators/get) or [@post](/docs/decorators/post). See [Dynamic path placeholders](/docs/misc/dynamic-path) for `null` / `undefined` / `""` / `0` and `skipEmptyPlaceholder`.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
+  </template>
+</sonic-code>
+
+## Construction
+
+<sonic-code language="typescript">
+  <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>
+</sonic-code>
+
+## Normalization
+
+`Endpoint.normalizePath` trims the string, rejects an empty path, strips leading slashes for paths relative to `serviceURL`, collapses duplicate slashes, and validates absolute `http(s)://` URLs.
+
+## Publisher key for payloads
+
+`getDataProviderKey()` returns a typed publisher key whose `path` matches the endpoint path (payload typing follows `ApiResult` for this endpoint). Useful when pairing `@get` with `@publish` / `@subscribe` (see [@get](/docs/decorators/get)).
+
+## Data-provider paths
+
+`Endpoint.looksLikeDataProviderPath(path)` returns true for strings shaped like `dataProvider(id)…`, which `API.get` can resolve without HTTP.
+
+## See also
+
+- [API configuration](/docs/misc/api-configuration) — `serviceURL`, token, wording (mock demos)
+- [@get](/docs/decorators/get) — GET decorator
+- [@post](/docs/decorators/post) — POST decorator (body from a `DataProviderKey`)
+- [@put](/docs/decorators/put) · [@patch](/docs/decorators/patch) — PUT / PATCH decorators
+- [DataProviderKey](/docs/misc/dataProviderKey) — typed publisher paths (dot notation)

package/src/docs/misc/html-integration.md

@@ -0,0 +1,14 @@
+# HTML integration (no Lit)
+
+Some hosts (legacy PHP pages, static HTML) embed Concorde components **without** a Lit build step. They can use HTML attributes such as **`data-bind`**, **`dataProvider`**, and **`formDataProvider`** on tags directly in the page.
+
+**Form fields** (`sonic-input`, checkbox, select, …) bind only via **`formDataProvider` + `name`**. They do not autofill from ancestor `dataProvider`.
+
+That style is **not** what we demonstrate in this doc site: live examples are **Lit components** under `src/docs/example/`, registered once and reused from Markdown via tags like `<docs-flight-search-demo>`.
+
+| Goal | Use |
+|------|-----|
+| Learn modern patterns | [My first component](/docs/getting-started/my-first-component), [Data flow](/docs/getting-started/dataFlow) |
+| Author doc examples | `<docs-lit-demo>` + `src/docs/example/*.ts` — see [My first component](/docs/getting-started/my-first-component) |
+
+New application code in TypeScript should use **`@subscribe`**, **`formDataProvider` + `name`**, and Lit templates — not HTML `data-bind`.

package/src/docs/mock-api/api-config-mock.ts

@@ -15,6 +15,11 @@ export const DOCS_MOCK_EVENTS_API_TOKEN = "docs-mock-events-token";
 const WORDING_CATALOG: Record<string, Record<string, string>> = {
   "api-config.greeting": { fr: "Bonjour", en: "Hello" },
   "api-config.farewell": { fr: "Au revoir", en: "Goodbye" },
+  "flight.boarding": { fr: "Embarquement immédiat", en: "Now boarding" },
+  "flight.gate": {
+    fr: "Rendez-vous porte <strong>B12</strong>",
+    en: "Please proceed to gate <strong>B12</strong>",
+  },
   "api-config.hint": {
     fr: "Libellés servis par le mock /wording/labels",
     en: "Labels served by mock /wording/labels",