@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

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

@@ -0,0 +1,36 @@
+# 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/src/docs/getting-started/my-first-component.md

@@ -0,0 +1,227 @@
+# My first component
+
+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.
+
+## 1. Lit component + Tailwind
+
+Export Tailwind once (e.g. `src/docs/tailwind.ts` in this repo):
+
+<sonic-code language="typescript">
+  <template>
+import { css, unsafeCSS } from "lit";
+import tailwindImport from "./css/tailwind.css?inline";
+
+export const tailwind = css`${unsafeCSS(tailwindImport)}`;
+  </template>
+</sonic-code>
+
+User card — plain Lit properties and UI components (no store yet):
+
+<sonic-code language="typescript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement, property } from "lit/decorators.js";
+import { tailwind } from "../tailwind";
+
+@customElement("docs-user")
+export class DocsUser extends LitElement {
+  static styles = [tailwind];
+
+  @property({ type: String }) first_name = "";
+  @property({ type: String }) last_name = "";
+  @property({ type: String }) email = "";
+  @property({ type: String }) avatar = "";
+
+  render() {
+    return html`&lt;div class="flex items-center gap-3 rounded-md 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;
+        &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;
+    &lt;/div&gt;`;
+  }
+}
+  </template>
+</sonic-code>
+
+## 2. Data configuration
+
+The card does not hard-code user fields anymore. You declare **what** is stored, **where** it lives, and **which ancestor scope** applies — then `@subscribe` mirrors that object on the component.
+
+### Type — shape of the data
+
+`DocsUserData` documents the fields you expect at this scope (first name, email, avatar, …). TypeScript checks that `user` matches that shape.
+
+<sonic-code language="typescript">
+  <template>
+export type DocsUserData = {
+  first_name: string;
+  last_name: string;
+  email: string;
+  avatar: string;
+};
+  </template>
+</sonic-code>
+
+### Key — path in the DataProvider
+
+`docsUserRowKey` points at the store segment to read. The path `"${dataProvider}"` is resolved at runtime from a property on the component (see scope below).
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/core/utils/dataProviderKey";
+
+export const docsUserRowKey = new DataProviderKey&lt;
+  DocsUserData,
+  { dataProvider: string | null }
+&gt;("${dataProvider}");
+  </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).
+
+### 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.
+
+<sonic-code language="typescript">
+  <template>
+@ancestorAttribute("dataProvider")
+dataProvider: string | null = null;
+  </template>
+</sonic-code>
+
+### 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.
+
+<sonic-code language="typescript">
+  <template>
+import { html, LitElement, nothing } from "lit";
+import { customElement, state } from "lit/decorators.js";
+import {
+  ancestorAttribute,
+  subscribe,
+} from "@supersoniks/concorde/core/decorators/Subscriber";
+import { docsUserRowKey, type DocsUserData } from "./users";
+import { tailwind } from "../tailwind";
+
+@customElement("docs-user")
+export class DocsUser extends LitElement {
+  static styles = [tailwind];
+
+  @ancestorAttribute("dataProvider")
+  dataProvider: string | null = null;
+
+  @subscribe(docsUserRowKey)
+  @state()
+  user: DocsUserData | null = null;
+
+  render() {
+    const u = this.user;
+    if (!u) return nothing;
+    return html`&lt;div class="flex items-center gap-3 rounded-md p-2"&gt;
+      &lt;sonic-image src=${u.avatar} rounded="md" ratio="1/1" class="w-16"&gt;&lt;/sonic-image&gt;
+      &lt;div&gt;
+        &lt;div&gt;${u.first_name} &lt;span class="font-bold"&gt;${u.last_name}&lt;/span&gt;&lt;/div&gt;
+        &lt;div class="text-sm text-neutral-400"&gt;${u.email}&lt;/div&gt;
+      &lt;/div&gt;
+    &lt;/div&gt;`;
+  }
+}
+  </template>
+</sonic-code>
+
+Live code: `src/docs/example/users.ts`. In this repo, imports use **`core/…` paths** (short `@supersoniks/concorde/…` exports apply in **consumer apps** only).
+
+### Two scopes, one component
+
+The same `docs-user` is mounted twice. Each copy inherits a **different** nearest `dataProvider` — that is the row/list **scope**:
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="docs-user-two-scopes"></docs-demo-sources>
+    <docs-user-two-scopes></docs-user-two-scopes>
+  </template>
+</sonic-code>
+
+Markup (two isolated stores; keys from `docs-provider-keys.ts`):
+
+<sonic-code language="markup">
+  <template>
+    &lt;div class="grid md:grid-cols-2 gap-6"&gt;
+      &lt;div dataProvider="${docsUserScopeAKey.path}"&gt;
+        &lt;docs-user&gt;&lt;/docs-user&gt;
+      &lt;/div&gt;
+      &lt;div dataProvider="${docsUserScopeBKey.path}"&gt;
+        &lt;docs-user&gt;&lt;/docs-user&gt;
+      &lt;/div&gt;
+    &lt;/div&gt;
+  </template>
+</sonic-code>
+
+Seeded in `docs-provider-keys.ts` (`set(docsUserScopeAKey, …)`): **Paul** / **Marie**. Without `@ancestorAttribute`, both cards would not know which store to read.
+
+## 3. Fetch users — `sonic-list` with `.items`
+
+Use a Lit parent and the **`items`** renderer (not HTML `<template>` children). The callback receives each row object from fetch — render fields directly (`${item.first_name}`, …), like porting a template that used `data-bind` / `<sonic-value>`.
+
+<sonic-code>
+  <template>
+      <docs-lit-demo for="docs-users-list"></docs-lit-demo>
+  </template>
+</sonic-code>
+
+Wrapper (`docs-users-list.ts`):
+
+<sonic-code language="typescript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement } from "lit/decorators.js";
+import "../../core/components/functional/list/list";
+import "./users";
+
+@customElement("docs-users-list")
+export class DocsUsersList extends LitElement {
+  private items = ({ first_name, last_name, email, avatar }) => html`
+    &lt;div class="flex gap-3"&gt;
+      &lt;sonic-image src=${avatar} ...&gt;&lt;/sonic-image&gt;
+      &lt;div&gt;${first_name} &lt;b&gt;${last_name}&lt;/b&gt;&lt;/div&gt;
+      &lt;div class="text-sm text-neutral-400"&gt;${email}&lt;/div&gt;
+    &lt;/div&gt;
+  `;
+
+  render() {
+    return html`
+      &lt;sonic-list fetch dataProvider=${usersListEndpoint.path} key="data" .items=${this.items}&gt;&lt;/sonic-list&gt;
+    `;
+  }
+}
+  </template>
+</sonic-code>
+
+See [Local API demos](/docs/misc/docs-mock-api) for `serviceURL="/docs-mock-api"`.
+
+## 4. Form preview with `formDataProvider`
+
+Edit fields in a form; the card follows the same `docsUserRowKey` when the preview host sets `dataProvider="userPreview"`.
+
+<sonic-code>
+  <template>
+    <div class="grid grid-cols-1 gap-4 max-w-xl">
+      <form formDataProvider="${docsUserPreviewKey.path}" class="grid grid-cols-2 gap-3">
+        <sonic-input label="First name" name="first_name" value="Paul" size="sm"></sonic-input>
+        <sonic-input label="Last name" name="last_name" value="Metrand" size="sm"></sonic-input>
+        <sonic-input class="col-span-2" label="Email" name="email" value="paul@example.com" size="sm"></sonic-input>
+        <sonic-input class="col-span-2" label="Avatar URL" name="avatar" value="https://i.pravatar.cc/150?u=paul" size="sm"></sonic-input>
+      </form>
+      <sonic-divider align="left">Preview</sonic-divider>
+      <div dataProvider="${docsUserPreviewKey.path}">
+        <docs-user></docs-user>
+      </div>
+    </div>
+  </template>
+</sonic-code>
+
+Use `formDataProvider` + `name` on inputs — no manual `@input` handlers ([Data flow](/docs/getting-started/dataFlow)).

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

@@ -0,0 +1,35 @@
+# Introduction
+
+## What is Concorde?
+
+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 the smallest set of CSS variables needed to define a theme.
+
+## Why and use case
+
+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
+* Vite
+* Tailwind (starter kit, not required in the core package)
+
+### Functional features
+
+* **DataProvider** store (decorators, `get` / `set`)
+* Forms (`formDataProvider`)
+* Lists, queues, lazy loading
+* Router, states, UI kit with status variants
+
+## Start a new project
+
+<sonic-code language="bash">
+  <template>
+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).

package/src/docs/header/header.ts

@@ -120,11 +120,13 @@ export class SonicComponent extends Subscriber(LitElement) {
       }
     });
 
-    // on hash change, hide search and mobile navigation
-    window.addEventListener("hashchange", () => {
+    // on navigation, hide search and mobile navigation
+    const onNav = () => {
       this.hideSearch();
       this.closeNavigation();
-    });
+    };
+    window.addEventListener("hashchange", onNav);
+    window.addEventListener("popstate", onNav);
   }
 
   handleColorScheme() {
@@ -181,7 +183,7 @@ export class SonicComponent extends Subscriber(LitElement) {
           <sonic-icon name="menu" library="iconoir"></sonic-icon>
         </sonic-button>
         <div class="min-w-0">
-          <sonic-link href="/" class="logo flex items-end gap-x-1">
+          <sonic-link pushState href="/" class="logo flex items-end gap-x-1">
             <svg
               class="size-8 sm:size-[2.4rem] inline-block rotate-[55deg]"
               viewBox="0 0 66 66"
@@ -217,14 +219,16 @@ export class SonicComponent extends Subscriber(LitElement) {
             class="hidden md:block"
             variant="ghost"
             size="sm"
-            href="#docs/_getting-started/start.md/start"
+            pushState
+            href="/docs/getting-started/start"
             >Docs</sonic-button
           >
           <sonic-button
             class="hidden md:block"
             variant="ghost"
             size="sm"
-            href="#docs/_getting-started/components.md/components"
+            pushState
+            href="/docs/getting-started/components"
             >Components</sonic-button
           >
           <sonic-button
@@ -375,6 +379,7 @@ export class SonicComponent extends Subscriber(LitElement) {
                   <docs-search
                     setFocus
                     class="max-w-[30rem] lg:max-w-[35rem] w-full block"
+                    @docs-search-close=${() => this.hideSearch()}
                   >
                   </docs-search>
                 </div>

package/src/docs/home/catalog.ts

@@ -14,7 +14,6 @@ export const COMPONENT_NOTES: Record<string, { tag: string; note: string }> = {
   Icon: { tag: "sonic-icon", note: "Inline SVG icons from the core set or a CDN library." },
   Image: { tag: "sonic-image", note: "Responsive image with ratio, cover fit and load transition." },
   Input: { tag: "sonic-input", note: "Text field that publishes its value to a form provider." },
-  "Input autocomplete": { tag: "sonic-input-autocomplete", note: "Field with suggestions fed by a queue." },
   Link: { tag: "sonic-link", note: "Navigation for routes, anchors and external URLs." },
   Loader: { tag: "sonic-loader", note: "Loading animation, inline or as an overlay." },
   Menu: { tag: "sonic-menu", note: "Row or column of menu items for navigation or actions." },
@@ -40,5 +39,6 @@ export const COMPONENT_NOTES: Record<string, { tag: string; note: string }> = {
   SDUI: { tag: "sonic-sdui", note: "Builds an interface from a JSON descriptor." },
   States: { tag: "sonic-states", note: "Switches content on a data value or a pattern." },
   Submit: { tag: "sonic-submit", note: "Sends a form provider to an API endpoint." },
+  Translation: { tag: "sonic-t", note: "Renders a translated label in plain HTML, by key." },
   Value: { tag: "sonic-value", note: "Prints a live value from a data provider." },
 };

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)