@supersoniks/concorde 5.1.2 → 5.1.3-immutable.1

package/docs/src/docs/_getting-started/concorde-manual-install.md

@@ -0,0 +1,133 @@
+# Manual installation (Vite)
+
+> **Legacy** — for brownfield apps or custom stacks. New projects should use the [starter](#docs/_getting-started/concorde-outside.md/concorde-outside).
+
+## Brand New Vite Project
+
+Tailwind configuration is not covered here yet.
+
+### Creating the Project
+
+<sonic-code language="shell">
+  <template>
+# Pure JavaScript project
+yarn create vite --template vanilla-js
+# TypeScript project
+# (it is recommended to use this approach, which installs Lit separately if needed, via "yarn add lit")
+yarn create vite --template vanilla-ts
+# TypeScript + Lit project
+# (creating new web components, for example, to extend the fetch or subscriber mixins)
+yarn create vite --template lit-ts
+  </template>
+</sonic-code>
+
+Using Lit with TypeScript requires the following configuration in the "compilerOptions" section of the `tsconfig.json` file:
+
+<sonic-code language="json">
+  <template>
+"experimentalDecorators": true,
+"useDefineForClassFields": false
+  </template>
+</sonic-code>
+
+### Installing Concorde
+
+Navigate to the project folder created and perform the installation:
+
+<sonic-code language="shell">
+  <template>
+yarn add @supersoniks/concorde
+  </template>
+</sonic-code>
+
+Agent skills (`AGENTS.md`, Cursor / JetBrains): see [AI agents](#docs/_getting-started/ai-agents.md/ai-agents) — run `node node_modules/@supersoniks/concorde/scripts/ai-init.mjs` after install.
+
+### Development / Build
+
+<sonic-code language="shell">
+  <template>
+# Development (you can add `--host` after the command chain in package.json's dev script instead of typing it each time as shown below)
+yarn dev --host
+# Build
+yarn build
+  </template>
+</sonic-code>
+
+## Shortcut Imports
+
+Shortcut imports work by default in JavaScript, but in TypeScript, they are activated by choice as they inject data into *tsconfig.json*. Here is the command:
+
+<sonic-code language="shell">
+  <template>
+npx concorde enable-short-paths
+  </template>
+</sonic-code>
+
+Shortcut imports replace the actual paths with aliases as follows:
+
+* `@supersoniks/concorde/core/components/functional_or_ui/component/component` becomes `@supersoniks/concorde/functional_or_ui/component`
+* `@supersoniks/concorde/core/mixins_or_utils/class_name` becomes `@supersoniks/concorde/mixins_or_utils/class_name`
+
+The original paths remain accessible. Shortcut imports are used for the examples later in this documentation.
+
+## Usage
+
+### Simple Integration in HTML
+
+Import needed component in `main.ts` or wherever you want to use it:
+
+<sonic-code language="typescript">
+  <template>
+import "@supersoniks/concorde/ui/button";
+  </template>
+</sonic-code>
+
+Then in the render function ofyour component or in the HTML of the web page that includes the compiled JS, use the component as follows:
+
+<sonic-code>
+  <template>
+<sonic-button variant="outline">My button</sonic-button>
+  </template>
+</sonic-code>
+
+### Using a Mixin to Create a New Lit Component
+
+For example, create a file `my-element.ts` at the root:
+
+<sonic-code language="typescript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement, property } from "lit/decorators.js";
+import Fetcher from "@supersoniks/concorde/mixins/Fetcher";
+import Subscriber from "@supersoniks/concorde/mixins/Subscriber";
+
+@customElement("my-element")
+export class SonicComponent extends Fetcher(Subscriber(LitElement)) {
+  @property() email = "";
+  @property() first_name = "";
+  @property() last_name = "";
+
+  render() {
+    return html`<div>
+      ${this.first_name} ${this.last_name} : ${this.email}
+    </div>`;
+  }
+}
+  </template>
+</sonic-code>
+
+Import component `main.ts` or `main.js` or any other component that uses it to be compiled
+
+<sonic-code language="typescript">
+  <template>
+import "./my-element";
+  </template>
+</sonic-code>
+
+In the HTML of a JS or TS component or in the HTML of the web page containing the compiled JS:
+
+<sonic-code language="html">
+  <template>
+<my-element serviceURL="/docs-mock-api" dataProvider="api/users/2" key="data"></my-element>
+  </template>
+</sonic-code>

package/docs/src/docs/_getting-started/concorde-outside.md

@@ -0,0 +1,33 @@
+# Installation
+
+<sonic-alert status="info" label="Recommended — use the starter" background>
+<p>For almost all new projects, use <a href="https://www.npmjs.com/package/@supersoniks/create-concorde-ts-starter">create-concorde-ts-starter</a></p>
+<p>You get Vite + TypeScript + Lit + Tailwind, an example component, <code>npx concorde enable-short-paths</code> ready to run, and <code>yarn ai:sync</code> for <a href="#docs/_getting-started/ai-agents.md/ai-agents">AI agent skills</a> (<code>AGENTS.md</code>, Cursor / JetBrains rules) without extra setup.</p>
+</sonic-alert>
+
+## Starter
+
+The following command creates a new Vite project in TypeScript mode with Tailwind and an example component to get started.
+
+<sonic-code language="shell">
+  <template>
+npx @supersoniks/create-concorde-ts-starter "project_name"
+  </template>
+</sonic-code>
+
+Then, from the project folder:
+
+<sonic-code language="shell">
+  <template>
+yarn install
+yarn dev --host
+  </template>
+</sonic-code>
+
+## Next steps
+
+| Step | Page |
+|------|------|
+| Learn patterns | [My first component](#docs/_getting-started/my-first-component.md/my-first-component) |
+| Agent skills | [AI agents (skills)](#docs/_getting-started/ai-agents.md/ai-agents) — `yarn ai:sync` on the starter |
+| Brownfield / manual Vite | [Legacy: Manual installation](#docs/_getting-started/concorde-manual-install.md/concorde-manual-install) |

package/docs/{docs/getting-started → src/docs/_getting-started}/create-a-component.md

@@ -1,6 +1,6 @@
 # Creating components
 
-> **New app components:** start with [My first component](/docs/getting-started/my-first-component) and [Data flow](/docs/getting-started/dataFlow). The `Subscriber` mixin below is legacy.
+> **New app components:** start with [My first component](#docs/_getting-started/my-first-component.md/my-first-component) and [Data flow](#docs/_core-concept/dataFlow.md/dataFlow). The `Subscriber` mixin below is [legacy](#docs/_core-concept/subscriber.md/subscriber).
 
 ## Where to put it?
 
@@ -63,7 +63,10 @@ export class SonicComponent extends LitElement {
   </template>
 </sonic-code>
 
-Regarding data sharing, see [Data flow](/docs/getting-started/dataFlow).
+Regarding `Subscriber`, see:
+
+- [🔔 Subscriber](#docs/_core-concept/subscriber.md/subscriber)
+- [🥨 Sharing Data](#docs/_getting-started/pubsub.md/pubsub)
 
 ### Naming the Component
 
@@ -91,7 +94,7 @@ For example, for a "title" component in the "event" destination, the name would
 
 #### Creating Reactive Properties and Modifying the Render Function
 
-To do this, study the functioning of https://lit.dev and also refer to [Data flow](/docs/getting-started/dataFlow).
+To do this, study the functioning of https://lit.dev and also refer to [Subscriber](#docs/_core-concept/subscriber.md/subscriber).
 
 #### HTML Structure of a Component
 

package/docs/src/docs/{getting-started → _getting-started}/my-first-component.md

@@ -2,6 +2,8 @@
 
 Build a **Lit** user card with Tailwind and Concorde UI, then connect it to the **DataProvider** store: declare the **data configuration** (type, key, scope), and let **`@subscribe`** keep the card in sync.
 
+> Legacy approach with the **Subscriber mixin**: [Legacy: My first subscriber](#docs/_getting-started/my-first-subscriber.md/my-first-subscriber).
+
 ## 1. Lit component + Tailwind
 
 Export Tailwind once (e.g. `src/docs/tailwind.ts` in this repo):
@@ -79,11 +81,11 @@ export const docsUserRowKey = new DataProviderKey<
   </template>
 </sonic-code>
 
-The second generic (`{ dataProvider: string | null }`) lists what the host must expose so `"${dataProvider}"` can be resolved. See [DataProviderKey](/docs/misc/dataProviderKey) and [Dynamic path placeholders](/docs/misc/dynamic-path).
+The second generic (`{ dataProvider: string | null }`) lists what the host must expose so `"${dataProvider}"` can be resolved. See [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) and [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
 
 ### Scope — which store segment applies
 
-A parent sets `dataProvider=${docsUserScopeAKey.path}` (or a list row sets `…/list-item/0`). [`@ancestorAttribute`](/docs/decorators/ancestor-attribute) copies that attribute onto `this.dataProvider`, so the key resolves to the correct branch.
+A parent sets `dataProvider=${docsUserScopeAKey.path}` (or a list row sets `…/list-item/0`). [`@ancestorAttribute`](#docs/_decorators/ancestor-attribute.md/ancestor-attribute) copies that attribute onto `this.dataProvider`, so the key resolves to the correct branch.
 
 <sonic-code language="typescript">
   <template>
@@ -94,7 +96,7 @@ dataProvider: string | null = null;
 
 ### Subscribe — keep the card in sync
 
-[`@subscribe`](/docs/decorators/subscribe) watches `docsUserRowKey` and updates `user` when the store changes. Use `@state()` so Lit re-renders. The template reads `this.user` like any other property.
+[`@subscribe`](#docs/_decorators/subscribe.md/subscribe) watches `docsUserRowKey` and updates `user` when the store changes. Use `@state()` so Lit re-renders. The template reads `this.user` like any other property.
 
 <sonic-code language="typescript">
   <template>
@@ -201,7 +203,7 @@ export class DocsUsersList extends LitElement {
   </template>
 </sonic-code>
 
-See [Local API demos](/docs/misc/docs-mock-api) for `serviceURL="/docs-mock-api"`.
+See [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) for `serviceURL="/docs-mock-api"`.
 
 ## 4. Form preview with `formDataProvider`
 
@@ -224,4 +226,11 @@ Edit fields in a form; the card follows the same `docsUserRowKey` when the previ
   </template>
 </sonic-code>
 
-Use `formDataProvider` + `name` on inputs — no manual `@input` handlers ([Data flow](/docs/getting-started/dataFlow)).
+Use `formDataProvider` + `name` on inputs — no manual `@input` handlers ([Data flow](#docs/_core-concept/dataFlow.md/dataFlow)).
+
+## Next steps
+
+- [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) — full map
+- [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) — typed paths and host constraints
+- [@subscribe](#docs/_decorators/subscribe.md/subscribe) / [sub()](#docs/_directives/sub.md/sub) — read-only in templates
+- [List](#core/components/functional/list/list.md/list) — `.items`, `.noItems`, `.skeleton`

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

@@ -0,0 +1,120 @@
+# Legacy: My first subscriber component
+
+> **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
+
+<sonic-code language="javascript" >
+  <template>
+  import { html, LitElement, nothing } from "lit";
+  import { customElement, property } from "lit/decorators.js";
+  @customElement("docs-user")
+  export class user extends LitElement {
+    @property({ type: String }) first_name = "";
+    @property({ type: String }) last_name = "";
+    @property({ type: String }) avatar = "";
+    @property({ type: String }) email = "";
+    render() {
+      return html`
+        &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
+
+<sonic-code language="javascript">
+  <template>
+  import { css, unsafeCSS } from "lit";
+  import tailwindImport from "./css/tailwind.css?inline";
+  export const tailwind = css`${unsafeCSS(tailwindImport)}`;
+  </template>
+</sonic-code>
+
+<sonic-code language="javascript">
+  <template>
+    import { html, LitElement } from "lit";
+    import { customElement, property } from "lit/decorators.js";
+    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 {
+      static styles = [tailwind];
+      @property({ type: String }) first_name = "";
+      @property({ type: String }) last_name = "";
+      @property({ type: String }) avatar = "";
+      @property({ type: String }) email = "";
+      render() {
+        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>
+
+## Add Subscriber mixin
+
+<sonic-code language="javascript">
+  <template>
+    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>
+
+See [Legacy: Subscriber mixin](#docs/_core-concept/subscriber.md/subscriber).
+
+## Autofill from a dataProvider
+
+<sonic-code >
+<template>
+<docs-demo-sources for="list-users-fetch"></docs-demo-sources>
+<div serviceURL="/docs-mock-api">
+<sonic-fetch 
+    serviceURL="/docs-mock-api"
+    dataProvider="api/users/3" 
+    key="data">
+     <docs-user></docs-user>
+</sonic-fetch>
+</div>
+</template>
+</sonic-code>
+
+<sonic-code >
+<template>
+<sonic-fetch 
+    serviceURL="/docs-mock-api"
+    dataProvider="api/users/2" 
+    key="data"></sonic-fetch>
+<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" 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>
+<div dataProvider="userPreview">
+  <docs-user></docs-user>
+</div>
+</div>
+</template>
+</sonic-code>

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

@@ -0,0 +1,37 @@
+# Legacy: Sharing data
+
+> **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`, …).
+
+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/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) that holds data.<br>
+  Example: `{foo:{hello:["world"]}, bar:"baz"}`
+
+* Accessing a property (`myPublisher.foo.hello`) returns another **publisher** for that segment.
+
+* Missing properties create a publisher with internal data `null`, filled later.
+
+* **Subscribers** listen via `onAssign`, `onInternalMutation`, template filling on the **Subscriber mixin**, etc.
+
+* Updates use `publisher.set(...)` or nested assignment; changes propagate to subscribers.
+
+❇️ Order of creation vs subscription theoretically does not matter.
+
+### Methods
+
+* **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/docs/src/docs/{getting-started → _getting-started}/start.md

@@ -24,6 +24,18 @@ One composable web-component library replaced many one-off apps. Lit was chosen
 * Lists, queues, lazy loading
 * Router, states, UI kit with status variants
 
+## Learn Concorde
+
+| 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 |
+
+Legacy (Subscriber mixin, Publisher API): **Legacy** section at the bottom of the sidebar.
+
 ## Start a new project
 
 <sonic-code language="bash">
@@ -32,4 +44,4 @@ 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).
+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/docs/src/docs/{getting-started → _getting-started}/theming.md

@@ -1,4 +1,4 @@
-# Theming 
+# Customization
 
 ## Theme-first customization
 
@@ -10,7 +10,7 @@ Concorde derives radius steps, button/input rounding, shadows, and most per-comp
 
 <sonic-code language="html">
   <template>
-<sonic-theme color font >
+<sonic-theme color font class="block bg-base min-h-screen">
   <!-- your app -->
 </sonic-theme>
   </template>

package/docs/src/docs/{misc → _misc}/api-configuration.md

@@ -1,8 +1,8 @@
 # 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`**.
+`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.md/get) / [@post](#docs/_decorators/post.md/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.
+> **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
 
@@ -21,7 +21,7 @@
 | `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)).
+**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)
 
@@ -49,7 +49,9 @@ Attribute **`eventsApiToken`** on an ancestor maps to **`authToken`** in config
 
 ## Wording API
 
-`wordingProvider` and `wordingVersionProvider` are read by the translation directive: see [t()](/docs/directives/t).
+`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)
 
@@ -71,9 +73,9 @@ Implementation: `src/docs/mock-api/api-config-mock.ts` (bundled in the Service W
 
 ## 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)
+- [@get](#docs/_decorators/get.md/get) — `APIConfiguration` + `Endpoint`
+- [@post](#docs/_decorators/post.md/post) — same configuration model for POST
+- [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch) — PUT / PATCH
+- [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/docs/src/docs/{misc → _misc}/dataProviderKey.md

@@ -2,7 +2,7 @@
 
 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).
+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
 
@@ -78,7 +78,7 @@ firstItem.path;  // "data.items.0"
 
 ### 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:
+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.md/dynamic-path) for resolution rules and `skipEmptyPlaceholder`. The type remains declarative:
 
 <sonic-code language="typescript">
   <template>
@@ -91,7 +91,7 @@ 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).
+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
 
@@ -159,7 +159,7 @@ export class UserForm extends LitElement {
   </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.
+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.md/dynamic-path). See [@handle](#docs/_decorators/handle.md/handle) for method callbacks.
 
 ## Notes
 

package/docs/{docs/misc → src/docs/_misc}/docs-mock-api.md

@@ -14,28 +14,29 @@ TypeScript constants: `src/docs/mock-api/urls.ts` (`DOCS_MOCK_REQRES_SERVICE`, `
 
 | Path | Used in |
 |------|---------|
-| `/docs-mock-api/api/users` | [My first component](/docs/getting-started/my-first-component) users list |
+| `/docs-mock-api/api/users` | `sonic-list`, `sonic-fetch`, `sonic-queue` (users) |
 | `/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/space-cats` | `sonic-jsonata` top-N demo |
 | `/docs-mock-api/api/coffee-bags` | fixtures / tests jsonata (`?roast=`) |
-| `/docs-mock-api/api/market-order` | Fixtures shared with the jsonata unit tests |
+| `/docs-mock-api/api/market-order` | `sonic-jsonata` totals demo |
 | `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 |
+| `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) — tokenProvider (Basic or `eventsApiToken`) |
+| `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` | `@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 |
+| `/docs-mock-api/geo/communes` | Geo list, `@get` demos |
+| `/docs-mock-api/jokes/joke/:category` | JokeAPI-shaped list (`key="jokes"` on queue/list) |
 
-### Filters `GET /flights`
+### Filtres `GET /jokes/joke/…`
 
 | 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 |
+| `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`
 

package/docs/{docs/misc → src/docs/_misc}/dynamic-path.md

@@ -46,7 +46,7 @@ Available on:
 |-----|--------|
 | `@get` | 2nd or 3rd argument (`GetOptions`) |
 | `@post` / `@put` / `@patch` | `PostOptions` / `ApiSendOptions` |
-| `@bind` | `BindOptions` |
+| `@bind` / `@subscribe` | `BindOptions` |
 | `@publish` | 2nd argument `PublishOptions` |
 | `@handle` | `HandleOptions` |
 
@@ -62,10 +62,10 @@ Available on:
 
 ## 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
+- [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) — path syntax
+- [Endpoint](#docs/_misc/endpoint.md/endpoint) — HTTP paths + host generic `U`
+- HTTP: [@get](#docs/_decorators/get.md/get) · [@post](#docs/_decorators/post.md/post) · [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch)
+- Store: [@subscribe](#docs/_decorators/subscribe.md/subscribe) · [@bind](#docs/_decorators/bind.md/bind) · [@publish](#docs/_decorators/publish.md/publish) · [@handle](#docs/_decorators/handle.md/handle)
+- Legacy strings: [@onAssign](#docs/_decorators/on-assign.md/on-assign) (dynamic paths section)
+- Templates: [sub()](#docs/_directives/sub.md/sub) — dynamic paths in Lit (no `skipEmptyPlaceholder` yet)
+- Tutorial: [My first component](#docs/_getting-started/my-first-component.md/my-first-component) — `"${dataProvider}"` scope pattern