@supersoniks/concorde 4.5.2 → 4.7.0

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:
@@ -97,13 +130,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 +159,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
 

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)

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

@@ -0,0 +1,13 @@
+# 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.
+
+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-joke-search-demo>`.
+
+| Goal | Use |
+|------|-----|
+| Learn modern patterns | [My first component](#docs/_getting-started/my-first-component.md/my-first-component), [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) |
+| Author doc examples | `<docs-lit-demo>` + `src/docs/example/*.ts` — see [My first component](#docs/_getting-started/my-first-component.md/my-first-component) |
+| Embed in plain HTML only | `data-bind` / Subscriber docs in **Legacy** — [Subscriber mixin](#docs/_core-concept/subscriber.md/subscriber) |
+
+New application code in TypeScript should use **`@subscribe`**, **`formDataProvider` + `name`**, and Lit templates — not HTML `data-bind`.

package/src/docs/code.ts

@@ -27,7 +27,7 @@ export class DocsCode extends LitElement {
     css`
       :host(:not([inline])) {
         display: block;
-        margin: 1rem 0;
+        margin: 1.1rem 0;
       }
 
       :host([inline]) {
@@ -84,6 +84,11 @@ export class DocsCode extends LitElement {
   //States
   @state() codeEdited = false;
 
+  /** Aperçu live uniquement pour les blocs markup (évite d’injecter du HTML depuis des exemples JS). */
+  private get rendersLiveOutput(): boolean {
+    return this.language === "markup" && !this.noOutput;
+  }
+
   // createRenderRoot() {
   //   return this;
   // }
@@ -95,10 +100,7 @@ export class DocsCode extends LitElement {
     }
 
     this.templateEl = this.querySelector("template");
-    this.defaultCode = this.templateEl?.innerHTML
-      .toString()
-      .replace(/&lt;/g, "<")
-      .replace(/&gt;/g, ">");
+    this.defaultCode = this.readTemplateSourceCode();
 
     if (this.defaultCode) {
       Prism.plugins.NormalizeWhitespace.setDefaults({
@@ -120,11 +122,40 @@ export class DocsCode extends LitElement {
       this.currentCode = Prism.highlight(
         normalizedCode,
         Prism.languages[this.language],
-        this.language
+        this.language,
       );
     }
 
-    this.codeOutput = this.defaultCode;
+    if (this.rendersLiveOutput) {
+      this.codeOutput = this.defaultCode;
+    } else {
+      this.removeOutputSlot();
+    }
+  }
+
+  private decodeTemplateEntities(html: string): string {
+    return html
+      .replace(/&lt;/g, "<")
+      .replace(/&gt;/g, ">")
+      .replace(/&amp;/g, "&");
+  }
+
+  /**
+   * Markup demos: serialized HTML for the live preview.
+   * TS/JS with Lit `html\`…\``: browser parses tags in &lt;template&gt; — use innerHTML
+   * when the fragment has elements; otherwise textContent (imports, types, etc.).
+   */
+  private readTemplateSourceCode(): string {
+    const template = this.templateEl;
+    if (!template) return "";
+
+    if (this.language === "markup") {
+      return this.decodeTemplateEntities(template.innerHTML);
+    }
+
+    // TS/JS/bash/json: never use innerHTML — the browser parses tags in <template>
+    // (e.g. <sonic-button> in Lit examples) and the source would be truncated.
+    return template.content.textContent ?? "";
   }
 
   updateCodeRender() {
@@ -143,11 +174,13 @@ export class DocsCode extends LitElement {
         this.currentCode = Prism.highlight(
           this.defaultCode || "",
           Prism.languages[this.language],
-          this.language
+          this.language,
         );
       });
     }
-    this.codeOutput = this.defaultCode;
+    if (this.rendersLiveOutput) {
+      this.codeOutput = this.defaultCode;
+    }
   }
 
   handleToggleCode() {
@@ -155,8 +188,9 @@ export class DocsCode extends LitElement {
   }
 
   handleCopyCode(e: Event) {
-    if (this.codeOutput) {
-      navigator.clipboard.writeText(this.codeOutput);
+    const text = this.codeOutput ?? this.defaultCode;
+    if (text) {
+      navigator.clipboard.writeText(text);
       const button = e.currentTarget as HTMLButtonElement;
       button?.setAttribute("active", "");
       setTimeout(() => {
@@ -167,12 +201,24 @@ export class DocsCode extends LitElement {
 
   updated(changedProperties: PropertyValues) {
     super.updated(changedProperties);
-    if (changedProperties.has("codeOutput")) {
+    if (
+      changedProperties.has("codeOutput") ||
+      changedProperties.has("language") ||
+      changedProperties.has("noOutput")
+    ) {
       this.appendOutput();
     }
   }
 
+  removeOutputSlot() {
+    this.querySelector("[slot=output]")?.remove();
+  }
+
   appendOutput() {
+    if (!this.rendersLiveOutput) {
+      this.removeOutputSlot();
+      return;
+    }
     let output = this.querySelector("[slot=output]") as HTMLElement;
     if (!output) {
       output = document.createElement("div");