@supersoniks/concorde 5.1.0 → 5.1.2

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

@@ -0,0 +1,62 @@
+# Local API demos (offline)
+
+The Concorde doc site does not call fragile third-party APIs during `yarn dev`. A **Service Worker** and the Vite dev middleware serve **`/docs-mock-api/*`** on the same origin.
+
+## How it works
+
+1. On load, `registerDocsMockApiServiceWorker()` registers `/docs-mock-api-sw.js`.
+2. Requests to `/docs-mock-api/...` are handled by the SW (production build) or Vite middleware (dev).
+3. Live examples use `serviceURL="/docs-mock-api"` and relative paths.
+
+TypeScript constants: `src/docs/mock-api/urls.ts` (`DOCS_MOCK_REQRES_SERVICE`, `DOCS_MOCK_GEO_SERVICE`, …).
+
+## Routes
+
+| Path | Used in |
+|------|---------|
+| `/docs-mock-api/api/users` | [My first component](/docs/getting-started/my-first-component) users list |
+| `/docs-mock-api/api/users/:id` | Single user, `docs-user` |
+| `/docs-mock-api/api/space-cats` | Fixtures shared with the jsonata unit tests |
+| `/docs-mock-api/api/coffee-bags` | fixtures / tests jsonata (`?roast=`) |
+| `/docs-mock-api/api/market-order` | Fixtures shared with the jsonata unit tests |
+| `POST /docs-mock-api/api/register` | **sonic-submit** — JSON, `multipart/form-data` (`sendAsFormData`), or `application/x-www-form-urlencoded` (native `<form>`); response includes parsed `email` + `token` |
+| `POST /docs-mock-api/api/register/nested` | Wrapped body `{ data: { id, token } }` for the `submitResultKey` demo |
+| `GET /docs-mock-api/api/register/echo` | Echoes query string (`method="get"` on submit) |
+| `GET /docs-mock-api/auth/token` | [API configuration](/docs/misc/api-configuration) — tokenProvider (Basic or `eventsApiToken`) |
+| `GET /docs-mock-api/api/config/protected` | Bearer / Basic; `docs-mock-stale-token` → **498** |
+| `GET /docs-mock-api/wording/labels` | Wording batch (`labels[]`, `lang`) |
+| `/docs-mock-api/geo/communes` | `@get` demos |
+| `GET /docs-mock-api/flights` | Flight board (`key="flights"`): `sonic-list` · `sonic-fetch` · `sonic-queue` · `sonic-jsonata` · `sonic-states` and the input / select / radio / switch filter demos |
+
+### Filters `GET /flights`
+
+| Query | Meaning |
+|-------|---------|
+| `direction` | `departures` · `arrivals` |
+| `q` | Substring on flight number, city or airport code |
+| `status` | Comma-separated statuses to keep: `on-time` · `boarding` · `delayed` · `landed` · `cancelled` (`all` = no filter) |
+| `offset` + `limit` | Pagination for **sonic-queue** lazy load |
+
+### Pagination `GET /api/users`
+
+| Query | Meaning |
+|-------|---------|
+| `offset` + `per_page` | Index-based slice on the filtered set — **sonic-queue** (`offset=$offset&per_page=$limit`) |
+| `page` + `per_page` | 1-based page — static fetch examples (`?page=2`) |
+| `limit` | Alias of `per_page` |
+| `q` | Search on first name, last name, email (optional; **sonic-queue** + `dataFilterProvider`, field `name="q"`) |
+
+**ALTCHA** (`sonic-captcha`) is **not** mocked — it still uses the Supersoniks service.
+
+In TypeScript demos, import from `src/docs/mock-api/urls.ts` (e.g. `DOCS_MOCK_REQRES_SERVICE` on `serviceURL`).
+
+## Source files
+
+- `src/docs/mock-api/` — router, fixtures, service worker, `urls.ts`
+- `scripts/docs-mock-api-vite-plugin.ts` — SW build + middleware
+- `public/docs-mock-api-sw.js` — generated on `yarn dev` / `yarn build-docs`
+
+```bash
+yarn dev          # mock API on by default
+yarn build-docs   # includes SW bundle
+```

package/src/docs/misc/dynamic-path.md

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

package/src/docs/misc/endpoint.md

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

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

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

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

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

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

@@ -97,281 +97,3 @@ export const DOCS_GEO_COMMUNES: GeoCommuneRow[] = [
   { nom: "Montpellier", code: "34172" },
   { nom: "Rennes", code: "35238" },
 ];
-
-/** JokeAPI-style content flags (checkbox / radio / switch blacklist demos). */
-export type DocsJokeFlagKey =
-  | "nsfw"
-  | "religious"
-  | "political"
-  | "racist"
-  | "sexist"
-  | "explicit";
-
-/** Forme proche de JokeAPI v2 (`key="jokes"` sur sonic-queue / list). */
-export type DocsJokeItem = {
-  categories: string[];
-  createdAt: string;
-  id: number;
-  joke: string;
-  lang: "fr" | "en";
-  flags: Record<DocsJokeFlagKey, boolean>;
-  safe: boolean;
-  type: string;
-  setup?: string;
-  delivery?: string;
-};
-
-const jokeFlags = (
-  partial: Partial<Record<DocsJokeFlagKey, boolean>> = {},
-): Record<DocsJokeFlagKey, boolean> => ({
-  nsfw: false,
-  religious: false,
-  political: false,
-  racist: false,
-  sexist: false,
-  explicit: false,
-  ...partial,
-});
-
-export type DocsJokeApiResponse = {
-  error: boolean;
-  amount: number;
-  jokes: DocsJokeItem[];
-};
-
-const SAMPLE_JOKES: DocsJokeItem[] = [
-  {
-    categories: ["Programming"],
-    createdAt: "2020-01-01 00:00:00",
-    id: 1,
-    lang: "en",
-    joke: "Why do programmers prefer dark mode? Because light attracts bugs.",
-    flags: jokeFlags(),
-    safe: true,
-    type: "single",
-  },
-  {
-    categories: ["Misc"],
-    createdAt: "2020-01-02 00:00:00",
-    id: 2,
-    lang: "en",
-    joke: "I told my computer I needed a break — it said: no problem, I'll go to sleep.",
-    flags: jokeFlags({ nsfw: true }),
-    safe: false,
-    type: "single",
-  },
-  {
-    categories: ["Pun"],
-    createdAt: "2020-01-03 00:00:00",
-    id: 3,
-    lang: "en",
-    joke: "Concorde docs run offline: even the API is a local joke.",
-    flags: jokeFlags(),
-    safe: true,
-    type: "single",
-  },
-  {
-    categories: ["Animals"],
-    createdAt: "2020-01-04 00:00:00",
-    id: 4,
-    lang: "en",
-    joke: "The dog ate my homework and my pull request.",
-    flags: jokeFlags({ political: true }),
-    safe: true,
-    type: "single",
-  },
-  {
-    categories: ["Animals", "Pun"],
-    createdAt: "2020-01-05 00:00:00",
-    id: 5,
-    lang: "fr",
-    joke: "Quel est le chien préféré des développeurs ? Le labrador Retriever.",
-    flags: jokeFlags(),
-    safe: true,
-    type: "single",
-  },
-  {
-    categories: ["Animals"],
-    createdAt: "2020-01-06 00:00:00",
-    id: 6,
-    lang: "fr",
-    joke: "Un chat et un chien discutent de TypeScript : le chien dit « woof », le chat compile.",
-    flags: jokeFlags({ racist: true }),
-    safe: false,
-    type: "single",
-  },
-  {
-    categories: ["Misc"],
-    createdAt: "2020-01-07 00:00:00",
-    id: 7,
-    lang: "fr",
-    joke: "Pourquoi les blagues offline sont-elles fiables ? Parce qu'elles passent par le Service Worker.",
-    flags: jokeFlags({ religious: true }),
-    safe: true,
-    type: "single",
-  },
-  {
-    categories: ["Programming"],
-    createdAt: "2020-01-08 00:00:00",
-    id: 8,
-    lang: "fr",
-    joke: "Mon compilateur et mon chien : tous deux ignorent mes commandes jusqu'au build.",
-    flags: jokeFlags({ sexist: true }),
-    safe: false,
-    type: "single",
-  },
-  {
-    categories: ["Misc"],
-    createdAt: "2020-01-09 00:00:00",
-    id: 9,
-    lang: "en",
-    joke: "A SQL query walks into a bar, walks up to two tables and asks: Can I join you?",
-    flags: jokeFlags({ explicit: true }),
-    safe: false,
-    type: "single",
-  },
-  {
-    categories: ["Pun"],
-    createdAt: "2020-01-10 00:00:00",
-    id: 10,
-    lang: "fr",
-    joke: "J'ai cherché « chien » dans la doc : le mock API a répondu.",
-    flags: jokeFlags(),
-    safe: true,
-    type: "single",
-  },
-  {
-    categories: ["Misc"],
-    createdAt: "2020-01-11 00:00:00",
-    id: 11,
-    lang: "en",
-    joke: "There are only two hard things in Computer Science: cache invalidation and naming things.",
-    flags: jokeFlags({ political: true, explicit: true }),
-    safe: false,
-    type: "single",
-  },
-  {
-    categories: ["Animals"],
-    createdAt: "2020-01-12 00:00:00",
-    id: 12,
-    lang: "fr",
-    joke: "Le golden retriever a récupéré la donnée du publisher.",
-    flags: jokeFlags({ racist: true, sexist: true }),
-    safe: false,
-    type: "two-liner",
-    setup: "Pourquoi le chien aime Concorde ?",
-    delivery: "Parce qu'il sait fetch.",
-  },
-  {
-    categories: ["Misc"],
-    createdAt: "2020-01-13 00:00:00",
-    id: 13,
-    lang: "en",
-    joke: "My code and my conscience: both have too many warnings.",
-    flags: jokeFlags(),
-    safe: true,
-    type: "single",
-  },
-  {
-    categories: ["Programming"],
-    createdAt: "2020-01-14 00:00:00",
-    id: 14,
-    lang: "en",
-    joke: "Git blame is just a mirror.",
-    flags: jokeFlags({ religious: true, political: true }),
-    safe: false,
-    type: "single",
-  },
-];
-
-/** `blacklistFlags` from queue filter form (comma-separated or repeated param). */
-export function parseBlacklistFlags(url: URL): DocsJokeFlagKey[] {
-  const keys = new Set<DocsJokeFlagKey>();
-  const valid: DocsJokeFlagKey[] = [
-    "nsfw",
-    "religious",
-    "political",
-    "racist",
-    "sexist",
-    "explicit",
-  ];
-  const add = (raw: string) => {
-    raw
-      .split(",")
-      .map((s) => s.trim().toLowerCase())
-      .forEach((part) => {
-        if (valid.includes(part as DocsJokeFlagKey)) keys.add(part as DocsJokeFlagKey);
-      });
-  };
-  url.searchParams.getAll("blacklistFlags").forEach(add);
-  const single = url.searchParams.get("blacklistFlags");
-  if (single) add(single);
-  return [...keys];
-}
-
-/** Exclude jokes that match any blacklisted flag (JokeAPI-style). */
-export function applyJokeBlacklist(
-  jokes: DocsJokeItem[],
-  blacklist: DocsJokeFlagKey[],
-): DocsJokeItem[] {
-  if (!blacklist.length) return jokes;
-  return jokes.filter(
-    (j) => !blacklist.some((flag) => j.flags[flag] === true),
-  );
-}
-
-/** Filtre doc joke queue (`contains`, `lang`, `blacklistFlags` via `dataFilterProvider`). */
-export function filterDocsJokes(
-  jokes: DocsJokeItem[],
-  url: URL,
-): DocsJokeItem[] {
-  let pool = jokes;
-  const contains = url.searchParams.get("contains")?.trim().toLowerCase();
-  if (contains) {
-    pool = pool.filter((j) => {
-      const haystack = [j.joke, j.setup, j.delivery, ...j.categories]
-        .filter(Boolean)
-        .join(" ")
-        .toLowerCase();
-      return haystack.includes(contains);
-    });
-  }
-  const lang = url.searchParams.get("lang")?.trim().toLowerCase();
-  if (lang === "fr" || lang === "en") {
-    pool = pool.filter((j) => j.lang === lang);
-  }
-  pool = applyJokeBlacklist(pool, parseBlacklistFlags(url));
-  return pool;
-}
-
-/**
- * Réponse type JokeAPI v2.
- * - `amount` : taille du lot si pas de `offset`
- * - `offset` + `limit` / `per_page` : pagination (sonic-queue lazy)
- * - `contains`, `lang`, `blacklistFlags` : filtres formulaire (queue « Remove following jokes »)
- */
-export function buildJokeApiResponse(url: URL): DocsJokeApiResponse {
-  const pool = filterDocsJokes(SAMPLE_JOKES, url);
-  const amount = Math.max(
-    1,
-    parseInt(url.searchParams.get("amount") || "10", 10),
-  );
-  const hasOffset = url.searchParams.has("offset");
-  const limit = Math.max(
-    1,
-    parseInt(
-      url.searchParams.get("limit") ||
-        url.searchParams.get("per_page") ||
-        String(amount),
-      10,
-    ),
-  );
-  const offset = Math.max(0, parseInt(url.searchParams.get("offset") || "0", 10));
-  const start = hasOffset ? offset : 0;
-  const count = hasOffset ? limit : amount;
-  const jokes = pool.slice(start, start + count).map((j, i) => ({
-    ...j,
-    id: start + i + 1,
-  }));
-  return { error: false, amount: jokes.length, jokes };
-}

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

@@ -0,0 +1,89 @@
+/** Fictional flight board for list / queue filter demos (`key="flights"`). */
+export type DocsFlightStatus =
+  | "on-time"
+  | "boarding"
+  | "delayed"
+  | "landed"
+  | "cancelled";
+
+export type DocsFlight = {
+  id: number;
+  code: string;
+  direction: "departures" | "arrivals";
+  airport: string;
+  city: string;
+  time: string;
+  gate: string;
+  status: DocsFlightStatus;
+};
+
+const row = (
+  code: string,
+  direction: DocsFlight["direction"],
+  airport: string,
+  city: string,
+  time: string,
+  gate: string,
+  status: DocsFlightStatus,
+): Omit<DocsFlight, "id"> => ({
+  code,
+  direction,
+  airport,
+  city,
+  time,
+  gate,
+  status,
+});
+
+const FLIGHTS: Omit<DocsFlight, "id">[] = [
+  row("CN 001", "departures", "JFK", "New York", "08:15", "B12", "boarding"),
+  row("CN 014", "departures", "LHR", "London", "08:40", "A03", "on-time"),
+  row("CN 102", "departures", "GIG", "Rio de Janeiro", "09:05", "C21", "delayed"),
+  row("CN 220", "departures", "DKR", "Dakar", "09:30", "C07", "on-time"),
+  row("CN 305", "departures", "IAD", "Washington", "10:10", "B04", "cancelled"),
+  row("CN 412", "departures", "BAH", "Bahrain", "10:45", "D02", "delayed"),
+  row("CN 518", "departures", "SIN", "Singapore", "11:20", "D14", "on-time"),
+  row("CN 633", "departures", "YUL", "Montreal", "12:00", "A11", "on-time"),
+  row("CN 002", "arrivals", "JFK", "New York", "07:50", "B10", "landed"),
+  row("CN 015", "arrivals", "LHR", "London", "08:25", "A05", "landed"),
+  row("CN 103", "arrivals", "GIG", "Rio de Janeiro", "09:15", "C20", "delayed"),
+  row("CN 221", "arrivals", "DKR", "Dakar", "09:55", "C08", "on-time"),
+  row("CN 306", "arrivals", "IAD", "Washington", "10:35", "B06", "on-time"),
+  row("CN 413", "arrivals", "BAH", "Bahrain", "11:05", "D03", "cancelled"),
+  row("CN 519", "arrivals", "SIN", "Singapore", "11:40", "D15", "delayed"),
+  row("CN 634", "arrivals", "YUL", "Montreal", "12:30", "A12", "on-time"),
+];
+
+/**
+ * `GET /flights` — filters:
+ * - `direction`: `departures` · `arrivals`
+ * - `q`: substring on code / city / airport
+ * - `status`: comma-separated statuses to keep (`all` or empty = no filter)
+ * - `offset` + `limit`: pagination for sonic-queue
+ */
+export function buildFlightsResponse(url: URL): { flights: DocsFlight[] } {
+  const p = url.searchParams;
+  let pool = FLIGHTS.map((f, i) => ({ ...f, id: i + 1 }));
+
+  const direction = p.get("direction");
+  if (direction === "departures" || direction === "arrivals") {
+    pool = pool.filter((f) => f.direction === direction);
+  }
+  const q = p.get("q")?.trim().toLowerCase();
+  if (q) {
+    pool = pool.filter((f) =>
+      [f.code, f.city, f.airport].join(" ").toLowerCase().includes(q),
+    );
+  }
+  const statuses = (p.get("status") || "")
+    .split(",")
+    .map((s) => s.trim())
+    .filter((s) => s && s !== "all");
+  if (statuses.length) {
+    pool = pool.filter((f) => statuses.includes(f.status));
+  }
+
+  const offset = Math.max(0, parseInt(p.get("offset") || "0", 10));
+  const limit = Math.max(1, parseInt(p.get("limit") || "20", 10));
+  return { flights: pool.slice(offset, offset + limit) };
+}

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

@@ -1,8 +1,8 @@
 import { handleApiConfigMockRequest } from "./api-config-mock";
+import { buildFlightsResponse } from "./flights";
 import {
   DOCS_GEO_COMMUNES,
   DOCS_REQRES_USERS,
-  buildJokeApiResponse,
   filterDocsUsers,
   type GeoCommuneRow,
   type ReqresUserResponse,
@@ -291,9 +291,8 @@ export async function handleDocsMockApiRequest(
     });
   }
 
-  const jokeMatch = subPath.match(/^\/jokes\/joke\/([^/]+)$/);
-  if (jokeMatch) {
-    return json(buildJokeApiResponse(url));
+  if (subPath === "/flights") {
+    return json(buildFlightsResponse(url));
   }
 
   return json({ error: "Not found", path: subPath }, { status: 404 });

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

@@ -7,5 +7,4 @@ export const DOCS_MOCK_REQRES_SERVICE = DOCS_MOCK_API_BASE;
 /** Remplace https://geo.api.gouv.fr/ — chemins `communes?…`. */
 export const DOCS_MOCK_GEO_SERVICE = `${DOCS_MOCK_API_BASE}/geo/`;
 
-/** Remplace https://v2.jokeapi.dev — chemins `joke/Any?…`. */
-export const DOCS_MOCK_JOKES_SERVICE = `${DOCS_MOCK_API_BASE}/jokes`;
+

package/src/docs/navigation/components-index.ts

@@ -0,0 +1,56 @@
+import { html, LitElement } from "lit";
+import { customElement } from "lit/decorators.js";
+import { docsNavigation } from "./navigation";
+
+export type Page = { label: string; href: string };
+
+/** Sidebar sections listed on the Components page, in display order. */
+const SECTIONS = [
+  { title: "UI components", id: "ui-components" },
+  { title: "Functional components", id: "functional-components" },
+];
+
+/** Pages of a sidebar section: the items between its title and the next one. */
+export function sectionPages(title: string): Page[] {
+  const start = docsNavigation.indexOf(title);
+  if (start < 0) return [];
+  const pages: Page[] = [];
+  for (const item of docsNavigation.slice(start + 1)) {
+    if (typeof item === "string") break;
+    pages.push(item);
+  }
+  return pages;
+}
+
+const tagName = "docs-components-index";
+/**
+ * Plain index of every component, grouped like the sidebar.
+ * Light DOM so the page headings feed the "On this page" navigation.
+ */
+@customElement(tagName)
+export class DocsComponentsIndex extends LitElement {
+  createRenderRoot() {
+    return this;
+  }
+
+  render() {
+    return SECTIONS.map(
+      (section) => html`
+        <h2 id=${section.id}>${section.title}</h2>
+        <div
+          class="not-prose grid grid-cols-2 sm:grid-cols-3 gap-x-8 gap-y-3 mt-6 mb-12"
+        >
+          ${sectionPages(section.title).map(
+            (page) =>
+              html`<sonic-link
+                href=${page.href}
+                pushState
+                class="hover:underline underline-offset-4"
+                >${page.label}</sonic-link
+              >`,
+          )}
+        </div>
+      `,
+    );
+  }
+}