@supersoniks/concorde 5.1.2 → 5.1.3-immutable.2

package/docs/src/docs/decorators/subscribe.md

@@ -1,87 +0,0 @@
-# @subscribe
-
-`@subscribe(key)` keeps a component property in sync with one path of the store: when a publisher assigns that path, the property updates and the component re-renders. It is read-only; use [@publish](/docs/decorators/publish) to write and [sub()](/docs/directives/sub) to read inside a template. See [Data flow](/docs/getting-started/dataFlow) for the overall model.
-
-## Import
-
-<sonic-code language="typescript">
-  <template>
-import { subscribe } from "@supersoniks/concorde/decorators";
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-
-type Cockpit = { altitude: number };
-const cockpitKey = new DataProviderKey&lt;Cockpit&gt;("cockpit");
-
-@subscribe(cockpitKey.altitude)
-@state()
-altitude = 0;
-  </template>
-</sonic-code>
-
-## Static path
-
-The key is a [DataProviderKey](/docs/misc/dataProviderKey): the property type must match `T` at that path. Add `@state()` so Lit re-renders. Until the publisher holds a value, the property keeps its initializer.
-
-<sonic-code language="typescript">
-  <template>
-type Flight = { code: string; gate: string; status: string };
-const flightKey = new DataProviderKey&lt;Flight&gt;("flight");
-
-@subscribe(flightKey)
-@state()
-flight: Flight | null = null;
-  </template>
-</sonic-code>
-
-## Dynamic path
-
-`${prop}` placeholders resolve from properties of the same component. Declare them in the key's second generic so TypeScript requires them on the host. When `seatIndex` changes, the path is resolved again and `person` refreshes; while the placeholder is `null` or `undefined`, the subscription is inactive. Resolution rules: [Dynamic paths](/docs/misc/dynamic-path).
-
-<sonic-code language="typescript">
-  <template>
-type OnBoard = { name: string; role: string; seat: string };
-const personKey = new DataProviderKey&lt;OnBoard, { seatIndex: number }&gt;(
-  "demoOnBoard.${seatIndex}",
-);
-
-@property({ type: Number }) seatIndex = 0;
-
-@subscribe(personKey)
-@state()
-person: OnBoard | null = null;
-  </template>
-</sonic-code>
-
-<sonic-code>
-  <template>
-    <docs-demo-sources for="demo-subscribe-dynamic"></docs-demo-sources>
-    <demo-subscribe-dynamic></demo-subscribe-dynamic>
-  </template>
-</sonic-code>
-
-## Ancestor scope
-
-Inside a list row or a `dataProvider` wrapper, read the path from the closest ancestor with [@ancestorAttribute](/docs/decorators/ancestor-attribute), then use it as the placeholder.
-
-<sonic-code language="typescript">
-  <template>
-const rowKey = new DataProviderKey&lt;OnBoard, { dataProvider: string | null }&gt;(
-  "${dataProvider}",
-);
-
-@ancestorAttribute("dataProvider")
-dataProvider: string | null = null;
-
-@subscribe(rowKey)
-@state()
-person: OnBoard | null = null;
-  </template>
-</sonic-code>
-
-## API reference
-
-| Argument | Type | Description |
-|----------|------|-------------|
-| `key` | `DataProviderKey<T, U>` | Path to read. `U` lists the host properties used by `${…}` placeholders |
-
-The decorated property is typed `T` (optionally `| null` or `| undefined`). The subscription starts when the component connects and stops when it disconnects.

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

@@ -1,76 +0,0 @@
-# @awaitConnectedAncestors
-
-Delays a component's `connectedCallback` until its matching ancestors are defined and connected, so context they set up (a `dataProvider`, a publisher, a fetched payload) is ready when the child starts. Pair it with `@dispatchConnectedEvent` on the ancestors, which signals readiness.
-
-## Import
-
-<sonic-code language="typescript">
-  <template>
-import {
-  awaitConnectedAncestors,
-  dispatchConnectedEvent,
-} from "@supersoniks/concorde/decorators";
-
-@customElement("flight-scope")
-@dispatchConnectedEvent()
-export class FlightScope extends LitElement {}
-
-@customElement("gate-panel")
-@awaitConnectedAncestors("flight-scope")
-export class GatePanel extends LitElement {}
-  </template>
-</sonic-code>
-
-## Wait for an ancestor
-
-Arguments are CSS selectors tested with `element.matches()` on each ancestor, across shadow roots. Here the parent element is not defined yet: the child stays uninitialized until you register it.
-
-<sonic-code>
-  <template>
-    <docs-demo-sources for="demo-wait-ancestors-section"></docs-demo-sources>
-    <demo-wait-ancestors-section></demo-wait-ancestors-section>
-  </template>
-</sonic-code>
-
-## Several ancestors
-
-With several selectors, the child waits for every matching ancestor. Register both to initialize it, in any order.
-
-<sonic-code>
-  <template>
-    <docs-demo-sources for="demo-wait-ancestors-multi-section"></docs-demo-sources>
-    <demo-wait-ancestors-multi-section></demo-wait-ancestors-multi-section>
-  </template>
-</sonic-code>
-
-## Ancestor already connected
-
-When the ancestor is already connected, or no ancestor matches, the child initializes immediately.
-
-<sonic-code>
-  <template>
-    <docs-demo-sources for="demo-wait-ancestors-ready-section"></docs-demo-sources>
-    <demo-wait-ancestors-ready-section></demo-wait-ancestors-ready-section>
-  </template>
-</sonic-code>
-
-## Signal readiness
-
-`@dispatchConnectedEvent()` dispatches a bubbling `sonic-connected` event (exported as `CONNECTED`) at the end of the ancestor's `connectedCallback`. You can listen to it anywhere:
-
-<sonic-code language="typescript">
-  <template>
-import { CONNECTED } from "@supersoniks/concorde/decorators";
-
-document.addEventListener(CONNECTED, (e) => console.log("ready:", e.target));
-  </template>
-</sonic-code>
-
-Elements without a hyphen in their tag name count as connected. A custom element ancestor that never dispatches the event releases the child after a **5 second** timeout, so decorate the ancestors you wait for.
-
-## API reference
-
-| Decorator | Argument | Description |
-|-----------|----------|-------------|
-| `@awaitConnectedAncestors` | `...selectors: string[]` | Class decorator. CSS selectors of the ancestors to wait for; with no selector, the class is left unchanged |
-| `@dispatchConnectedEvent` | none | Class decorator. Dispatches `CONNECTED` (`"sonic-connected"`, bubbles) after `connectedCallback` |

package/docs/src/docs/directives/sub.md

@@ -1,75 +0,0 @@
-# sub()
-
-`sub(path)` is a Lit directive that renders the current value of a store path and updates in place on every assignment. Use it inside `html` templates for read-only display; in a decorator, the same path goes to [@subscribe](/docs/decorators/subscribe). See [Data flow](/docs/getting-started/dataFlow) for the overall model.
-
-## Import
-
-<sonic-code language="typescript">
-  <template>
-import { sub } from "@supersoniks/concorde/directives";
-
-render() {
-  return html`&lt;p&gt;Altitude: ${sub("cockpit.altitude")} ft&lt;/p&gt;`;
-}
-  </template>
-</sonic-code>
-
-## DataProviderKey
-
-Pass a [DataProviderKey](/docs/misc/dataProviderKey) instead of a string to get a typo-safe path. Until the publisher holds a value, nothing is rendered.
-
-<sonic-code language="typescript">
-  <template>
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-
-const flightKey = new DataProviderKey&lt;{ code: string; gate: string }&gt;("flight");
-
-render() {
-  return html`&lt;p&gt;${sub(flightKey.code)} · gate ${sub(flightKey.gate)}&lt;/p&gt;`;
-}
-  </template>
-</sonic-code>
-
-## Dynamic path
-
-`${prop}` placeholders resolve from properties of the component that renders the template; the directive re-subscribes when they change. While a placeholder is `null` or `undefined`, nothing is rendered. Rules: [Dynamic paths](/docs/misc/dynamic-path). `skipEmptyPlaceholder` is not available on `sub()`.
-
-<sonic-code language="typescript">
-  <template>
-const personKey = new DataProviderKey&lt;OnBoard, { seatIndex: number }&gt;(
-  "demoOnBoard.${seatIndex}",
-);
-
-@property({ type: Number }) seatIndex = 0;
-
-render() {
-  return html`&lt;strong&gt;${sub(personKey.name)}&lt;/strong&gt; · ${sub(personKey.role)}`;
-}
-  </template>
-</sonic-code>
-
-<sonic-code>
-  <template>
-    <docs-demo-sources for="demo-sub-template"></docs-demo-sources>
-    <demo-sub-template></demo-sub-template>
-  </template>
-</sonic-code>
-
-## sub() or get()
-
-`get(path)` from `@supersoniks/concorde/utils` returns a one-time snapshot: in a template it never updates. Use `sub()` in templates and `get` / `set` / `dp` in imperative code.
-
-<sonic-code language="typescript">
-  <template>
-html`${sub(flightKey.gate)}`; // updates on gate change
-html`${get(flightKey.gate)}`; // frozen at first render
-  </template>
-</sonic-code>
-
-## API reference
-
-| Argument | Type | Description |
-|----------|------|-------------|
-| `path` | `string` or `DataProviderKey<T, U>` | Path to read. Placeholders resolve on the template host |
-
-The directive subscribes when its part connects and unsubscribes when it disconnects.

package/docs/src/docs/directives/t.md

@@ -1,73 +0,0 @@
-# t()
-
-Lit directive that renders a translated label by key. Keys are batched into one GET to the endpoint set by the nearest `wordingProvider` ancestor attribute, and results are cached in `localStorage`.
-
-## Import
-
-<sonic-code language="typescript">
-  <template>
-import { t } from "@supersoniks/concorde/directives/Wording";
-  </template>
-</sonic-code>
-
-`wording` and `w` are aliases of `t`. In plain HTML, use the [`sonic-t`](/core/components/functional/translation) element.
-
-## Usage
-
-Set `serviceURL` and `wordingProvider` on the host component or one of its ancestors, then call `t(key)` in a template. Attributes on elements **inside** the component's own template are not read. Click the button to bump the version and reload the labels.
-
-<docs-lit-demo for="docs-api-config-wording-demo"></docs-lit-demo>
-
-## Endpoint contract
-
-All keys requested in the same tick are sent in one request, appended to `wordingProvider` as `labels[]`:
-
-<sonic-code language="shell">
-  <template>
-GET {serviceURL}/wording/labels?lang=fr&labels[]=greeting&labels[]=farewell
-  </template>
-</sonic-code>
-
-The response is a flat map of key to label:
-
-<sonic-code language="json">
-  <template>
-{ "greeting": "Bonjour", "farewell": "Au revoir" }
-  </template>
-</sonic-code>
-
-Until the label arrives, `t()` renders an empty string.
-
-## HTML labels
-
-`t()` escapes the label. Use `unsafeWording(key)` for labels that contain trusted HTML.
-
-<sonic-code language="typescript">
-  <template>
-import { unsafeWording } from "@supersoniks/concorde/directives/Wording";
-
-html`&lt;p&gt;${unsafeWording("terms.notice")}&lt;/p&gt;`;
-  </template>
-</sonic-code>
-
-## Reloading labels
-
-Labels are fetched again when:
-
-- the `lang` attribute of `<html>` changes
-- the number stored at `wordingVersionProvider` changes — bump it after publishing new labels to invalidate the `localStorage` cache
-
-## API reference
-
-| Function | Description |
-|----------|-------------|
-| `t(key)` · `wording(key)` · `w(key)` | Renders the escaped label for `key` |
-| `unsafeWording(key)` | Renders the label as HTML |
-| `isWordingReady(key)` | `true` once the label for `key` is loaded |
-
-| Ancestor attribute | Description |
-|--------------------|-------------|
-| `wordingProvider` | Endpoint path and query, relative to `serviceURL` |
-| `wordingVersionProvider` | DataProvider path holding a version number |
-
-Other ancestor attributes (`serviceURL`, `token`, …) apply as for any request: see [API configuration](/docs/misc/api-configuration).

package/docs/src/docs/getting-started/components.md

@@ -1,5 +0,0 @@
-# Components
-
-Every Concorde web component, grouped like the sidebar. Pick one to see its live demos, attributes and import path.
-
-<docs-components-index></docs-components-index>

package/docs/src/docs/getting-started/create-a-component.md

@@ -1,136 +0,0 @@
-# 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.
-
-## Where to put it?
-
-In this document, we consider the src directory of the project as the root.<br>
-We describe how we organize our components as an example, however it depends on your project.
-
-In concorde each component is currently organized in the following directory structure (at least we try):
-
-- **/core/components/functional/component-name/component-name.ts**  
-  Generic/functional/generally unstyled component.
-  The component usually doesn't use any other concrete components.
-- **/core/components/ui/component-name/component-name.ts**  
-  Generic but UI-oriented component.
-  The component usually only uses generic components and other UI components.
-- **la-billetterie/components/atoms/component-name/component-name.ts**  
-  The component is intended to have a concrete usage within our ticketing system **"la-billetterie"**.
-  It usually only uses generic components from `core` and possibly other atoms.
-- **la-billetterie/components/concrete-destination/component-name/component-name.ts**  
-  The component has a specific destination: (event / cart / gift card): `/components/destination/`
-  The component uses various components, usually from the `/components/atoms` directory.
-  It does not use components at the same level in the file hierarchy.
-
-## Starting from a Simple Model
-
-You can copy `example.ts` from the source to the desired destination to start with.
-This file contains a web component in the form of a class that extends the `Subscriber` mixin, with a reactive property and a render function.
-
-<sonic-code language="javascript">
-  <template>
-import { html, LitElement } from "lit";
-import { customElement, property } from "lit/decorators.js";
-import Subscriber from "@supersoniks/concorde/core/mixins/Subscriber";
-
-@customElement("sonic-example")
-export class SonicComponent extends Subscriber(LitElement) {
-  @property() text = "Example";
-  render() {
-    return html`${this.text}`;
-  }
-}
-  </template>
-</sonic-code>
-
-**You can remove the dependency on `Subscriber`** if automatic population of the component with external data is not required.
-For example, for a UI component:
-
-
-<sonic-code language="javascript">
-  <template>
-import { html, LitElement } from "lit";
-import { customElement, property } from "lit/decorators.js";
-
-@customElement("sonic-example")
-export class SonicComponent extends LitElement {
-  @property() text = "Example";
-  render() {
-    return html`${this.text}`;
-  }
-}
-  </template>
-</sonic-code>
-
-Regarding data sharing, see [Data flow](/docs/getting-started/dataFlow).
-
-### Naming the Component
-
-The class name is not necessarily important. However, it is important to **give it a component name prefixed with "sonic"** (or a prefix of your own) using the dedicated metadata already present in the copied document. For example, a button component would be named as follows:
-
-
-<sonic-code language="typescript">
-  <template>
-@customElement("sonic-button")
-  </template>
-</sonic-code>
-
-For less generic components with a specific destination, we advise to include the destination in the name.
-For example, for a "title" component in the "event" destination, the name would be simply:
-
-
-<sonic-code language="typescript">
-  <template>
-@customElement("sonic-event-title")
-  </template>
-</sonic-code>
-
-
-## Modifying It
-
-#### 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).
-
-#### HTML Structure of a Component
-
-The HTML structure of a component should remain as simple as possible.
-
-Ideally, there should be only one additional level of elements in addition to slots.
-
-- **The main component is already a wrapper**.
-  It receives classes to manage its layout, but it should not style internal elements.
-- **Slots handle the visual organization** of elements.
-- **The specificity of the component is expressed in this additional level** by adding a list, a functional native element (e.g., button), or another component.
-
-This leads to the creation of more components and thus raises questions about the hierarchical organization of files. However, this tends to atomize their roles.
-
-## Referencing It
-
-To compile the component, it needs to be referenced somewhere through an import statement. In particular, it is important to reference it in any component that uses it.
-
-In the case where it can be directly used in a page, it should also be globally referenced, especially considering the creation of **specific bundles** in the future.
-
-Here's where we add imports based on the component's location inside concorde as an example
-
-- **/core/components/functional/component-name/component-name.ts**  
-  In `/core/components/functional/functional.ts`, which is referenced in core.ts and imported in `index.ts`.
-- **/core/components/ui/component-name/component-name.ts**  
-  In `/core/components/ui/ui.ts`, which is referenced in core.ts and imported in `index.ts`.
-- **la-billetterie/components/atoms/component-name/component-name.ts**  
-  Nowhere else but where it will be used, except for possible **temporary** tests, for example, in `index.ts`.
-- **la-billetterie/components/concrete-destination/component-name/component-name.ts**  
-  In `la-billetterie/components/concrete-destination/destination-concrete.ts`. 
-  If it's a new destination, you'll need to create the corresponding import .ts file and import it in `la-billetterie.ts`.
-
-## Using It
-
-As a reminder, the component is simply integrated into the context by adding a tag with the component's name, for example:
-
-
-<sonic-code language="html">
-  <template>
-<sonic-event-title></sonic-event-title>
-  </template>
-</sonic-code>

package/docs/src/docs/getting-started/dataFlow.md

@@ -1,87 +0,0 @@
-# Data flow
-
-Recommended patterns for new Concorde apps (Lit + TypeScript). Under the hood, data lives in a **DataProvider** store.
-
-## Quick map
-
-| Need | Use |
-|------|-----|
-| Read/write in code | `get` / `set` / `dp` + `DataProviderKey` (static paths only) |
-| Reactive Lit template | `sub(key)` or `@subscribe` |
-| Read component state from store | `@subscribe` + `DataProviderKey<T, U>` + `@state` |
-| Inherit ancestor attributes | `@ancestorAttribute` |
-| Write from component state | `@publish` |
-| React to assignments | `@handle` |
-| HTTP GET | `@get` + `Endpoint`, or `sonic-list` / `sonic-queue` with `fetch` |
-| HTTP POST (body from store) | `@post` + `Endpoint` + body `DataProviderKey` |
-| HTTP PUT / PATCH (body from store) | `@put` / `@patch` — same model as `@post` |
-| Forms | `formDataProvider` + `name` on fields (no Subscriber on form elements) |
-| Derived / aggregate (JSONata) | `derive()` or `sonic-jsonata` — [Jsonata](/core/components/functional/jsonata) |
-| Offline doc demos | `serviceURL="/docs-mock-api"` — [Local API demos](/docs/misc/docs-mock-api) |
-
-Skill: `concorde-get-set-dp` in the package `ai/` folder.
-
-## DataProviderKey
-
-<sonic-code language="typescript">
-  <template>
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-import { dp, get, set } from "@supersoniks/concorde/utils";
-
-const cartKey = new DataProviderKey&lt;{ items: string[] }&gt;("cart");
-
-set(cartKey, { items: [] });
-dp(cartKey.items).set(["a", "b"]);
-get(cartKey);
-  </template>
-</sonic-code>
-
-Dynamic paths (`users.${userId}`) → decorators or `sub()` — not `get("users.${id}")` in imperative code. Resolution rules: [Dynamic path placeholders](/docs/misc/dynamic-path).
-
-[DataProviderKey](/docs/misc/dataProviderKey)
-
-## Decorators
-
-| Decorator | Role |
-|-----------|------|
-| `@subscribe` | Read-only property from store — [data configuration](/docs/getting-started/my-first-component) (type + key + scope) |
-| `@publish` | Push property writes to store |
-| `@handle` | Method called on assignment |
-| `@ancestorAttribute` | Copy ancestor HTML attribute onto property |
-| `@get` | HTTP GET into `ApiResult&lt;T&gt;` |
-| `@post` | HTTP POST into `ApiResult&lt;T&gt;` (body from a publisher) |
-| `@put` / `@patch` | HTTP PUT / PATCH into `ApiResult&lt;T&gt;` |
-
-Walkthrough: [My first component](/docs/getting-started/my-first-component)
-
-## HTTP and lists
-
-- [@get](/docs/decorators/get) — single GET on a component
-- [@post](/docs/decorators/post) — POST with body read from a `DataProviderKey`
-- [@put](/docs/decorators/put) · [@patch](/docs/decorators/patch) — PUT / PATCH (same options as `@post`)
-- [List](/core/components/functional/list) — `fetch` + `key="data"` + `/docs-mock-api/api/users`
-- [Queue](/core/components/functional/queue) — lazy `offset=$offset&per_page=$limit` + optional `dataFilterProvider` (form → query)
-
-## Starter kit
-
-```bash
-npx @supersoniks/create-concorde-ts-starter my-app
-```
-
-Interactive routes mirror these patterns (`/concepts/*`, `/demo/*`).
-
-## Derived data (`derive` / `sonic-jsonata`)
-
-Use when you need **client-side aggregations** (groupby, top N, chart shapes) from existing DataProviders — without inline app JS in SDUI.
-
-- Primitive: `derive({ inputs, compute, output, variables? })` from `@supersoniks/concorde/utils` (read-only output, debounce, generation, cycle detection, `{output}/_state_`).
-- SDUI adapter: [`sonic-jsonata`](/core/components/functional/jsonata) (`inputProvider` → `expression` → `outputProvider`, optional `formDataProvider`).
-- vs [`sonic-mix`](/core/components/functional/mix): mix composes bidirectionally; jsonata **computes** unidirectionally.
-
-## Legacy integration
-
-| Topic | Page |
-|-------|------|
-| `data-bind` HTML (plain HTML hosts) | [HTML integration](/docs/misc/html-integration) — doc demos use Lit in `src/docs/example/` |
-| `@onAssign` | [@onAssign](/docs/decorators/on-assign) (prefer `@handle`) |
-| `sonic-fetch` alone | [Fetch](/core/components/functional/fetch) |

package/docs/src/docs/getting-started/installation.md

@@ -1,36 +0,0 @@
-# Installation
-
-Start a new project from the official starter. It sets up Vite, TypeScript, Lit, Tailwind and Concorde in one command.
-
-## Use the starter
-
-<sonic-code language="shell">
-  <template>
-npx @supersoniks/create-concorde-ts-starter my-app
-cd my-app
-yarn install
-yarn dev --host
-  </template>
-</sonic-code>
-
-The project includes:
-
-- an example component to copy from
-- `npx concorde enable-short-paths` for short import paths
-- `yarn ai:sync` for [AI agent skills](/docs/getting-started/ai-agents)
-
-Package: [create-concorde-ts-starter](https://www.npmjs.com/package/@supersoniks/create-concorde-ts-starter).
-
-## Stack
-
-| Tool | Role |
-|------|------|
-| [Lit](https://lit.dev) | Base class, templates and reactive properties for web components |
-| [TypeScript](https://www.typescriptlang.org) | Decorators and typed store paths |
-| [Vite](https://vite.dev) | Dev server and build |
-| [Tailwind](https://tailwindcss.com) | Optional, layout in your components. Concorde components ship their own styles, driven by [theme](/docs/getting-started/theming) variables |
-
-## Gotchas
-
-- `yarn dev` does not type-check. Run `tsc --noEmit` or a production build to catch type errors.
-- Scripts that query the global document (`document.querySelector`, jQuery plugins, icon replacers) cannot see inside a shadow root. Query from the component's `renderRoot`, or pass the element as slotted content.

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

@@ -1,62 +0,0 @@
-# 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
-```