@supersoniks/concorde 5.1.1 → 5.1.2

package/src/core/components/functional/queue/queue.md

@@ -1,72 +1,51 @@
 # Queue
 
-> **Try offline:** `serviceURL="/docs-mock-api"` — see [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api). Row rendering: [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) (`.items` property binding).
+**`sonic-queue`** loads a paginated API in batches and renders each batch as an internal [List](/core/components/functional/list). Choose it over `sonic-list` for long or endless lists; the key attributes are `dataProviderExpression` · `limit` · `dataFilterProvider`.
 
-**sonic-queue** loads data in **batches**. Each batch is an internal [List](#core/components/functional/list/list.md/list) with its own `dataProvider` (`…/list-item/0`, `…/1`, …).
+## Lazy load
 
-| Mechanism | Role |
-|-----------|------|
-| **`dataProviderExpression`** | API path template; `$offset` and `$limit` are replaced per batch |
-| **`lazyload`** | Load the next batch when the user scrolls near the end |
-| **`dataFilterProvider`** | Publisher id of a form (`formDataProvider`); field values are merged into the request query string |
-| **`filteredFields`** | Optional list of form field names to **exclude** from the query (space-separated) — omit when every field should be sent |
-| **`.items`**, **`.noItems`**, **`.separator`**, **`.skeleton`** | Lit callbacks forwarded to each batch list (use the **dot** — functions are properties, not attributes) |
+`dataProviderExpression` is the request path: `$offset` and `$limit` are replaced for each batch. The first batch starts at `offset` (default `0`) with `limit` rows (default `5`, at most `15`). The next batch loads when the end of the list scrolls into view, and the queue stops at the first empty batch. Put the queue in a box with a fixed height and `overflow-y-auto`, then scroll inside it.
 
-## Lazy load — `$offset` and `$limit`
+<docs-lit-demo for="docs-queue-geo-demo"></docs-lit-demo>
 
-When the expression contains **`$offset`** and **`$limit`**, the queue:
+Rows come from the `.items` callback, as on [List](/core/components/functional/list); `.noItems` and `.skeleton` work the same way. Without `$offset` in the expression, the queue sends one request and behaves like a list. Set `noLazyload` to load every batch in a row without waiting for the scroll.
 
-1. Fetches the first batch with `offset=0` (or the initial `offset` attribute) and `per_page=$limit`.
-2. On scroll, appends a batch with `offset` increased by the previous batch size.
-3. Stops when a batch returns fewer rows than `limit` (or none).
+## Filters
 
-The doc mock implements this on `GET /docs-mock-api/api/users?offset=…&per_page=…` (`paginateUsers` in `src/docs/mock-api/router.ts`).
+`dataFilterProvider` names a form store (`formDataProvider`). Each non-empty field is added to the query string; when a field changes, the queue drops the loaded batches and reloads from the first offset, after a `filterTimeoutMs` debounce (default `400`). Search a city, an airport or a flight number.
 
 <docs-lit-demo for="docs-queue-users-demo"></docs-lit-demo>
 
-Wrap the queue in a **fixed height** with **`overflow-y-auto`** so lazy load triggers when scrolling inside the box (same layout as the [TS starter](https://github.com/supersoniks/create-concorde-ts-starter) `demo-queue-templates`).
-
-Try scrolling after load — batches of 4 users. Search e.g. `George`, `Bluth`, or `zzz` for empty results.
-
-### Expression example
-
-```typescript
-html`<sonic-queue
-  lazyload
-  serviceURL="/docs-mock-api"
-  dataProviderExpression="api/users?offset=$offset&limit=$limit"
-  key="data"
-  limit="4"
-  class="grid max-h-96 overflow-y-auto"
-  .items=${this.renderUser}
-></sonic-queue>`;
-```
-
-Without **`$offset`** in the expression, the queue behaves like a single list (one batch), e.g. geo communes below.
-
-## Filter — `dataFilterProvider` + `q`
-
-One search field (`name="q"`) on `formDataProvider="filter"`. The queue listens via **`dataFilterProvider="filter"`** and, on change:
-
-1. Resets loaded batches.
-2. Appends each non-empty form field to the query (here only **`q`** — no `filteredFields` needed).
-3. Fetches again from offset `0`.
-
-Use **`filteredFields`** only when the form has extra fields that must **not** be sent to the API (e.g. `filteredFields="rememberMe internalId"`).
-
-The mock API filters before pagination — same haystack logic as the starter (`filterDocsUsers` in `src/docs/mock-api/fixtures.ts`, used by `paginateUsers` in `router.ts` / Service Worker):
-
-```typescript
-const haystack = `${first_name} ${last_name} ${email}`.toLowerCase();
-return haystack.includes(q);
-```
-
-## Simple batch (no lazy scroll)
-
-Geo communes: expression uses **`$limit` only** (no `$offset`) — one request, one batch.
-
-<docs-lit-demo for="docs-queue-geo-demo"></docs-lit-demo>
-
-## HTML `<template>` children
-
-Optional for hosts without Lit — see [HTML integration](#docs/_misc/html-integration.md/html-integration).
+To keep some form fields out of the request, list their names in `filteredFields`, separated by spaces.
+
+## API reference
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `dataProviderExpression` | string (default: closest ancestor `dataProvider`) | Request path; `$offset` and `$limit` are replaced for each batch |
+| `serviceURL` | string | API base URL; inherited from the closest ancestor |
+| `key` | string | Response property that holds the rows |
+| `limit` | number (default `5`, max `15`) | Rows per batch |
+| `offset` | number (default `0`) | Offset of the first batch |
+| `idKey` | string (default `id`) | Row property used as identity |
+| `dataFilterProvider` | string | Form store whose fields are added to the query; inherited from the closest ancestor |
+| `filteredFields` | space-separated names | Form fields not sent to the API |
+| `filterTimeoutMs` | number (default `400`) | Debounce before reloading after a filter change |
+| `noLazyload` | boolean | Loads all batches without waiting for the scroll |
+| `lazyBoundsRatio` | number (default `1`) | Lazy-load margin, as a multiple of the viewport size |
+| `loader` | `inline` · `fixed` (default `inline`) | Loader shown while a batch loads |
+| `cache` | `RequestCache` (default `default`) | Fetch cache mode |
+| `invalidateOnPageShow` | boolean | Reloads batches when the page is restored from the back/forward cache |
+| `localStorage` | `disabled` · `enabled` (default `disabled`) | Forwarded to each batch list |
+| `debug` | boolean | Shows a live inspector of each batch list's data |
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `items` | `ListItems` | Row renderer |
+| `noItems` | `ListItems` | Rendered when the first batch is empty |
+| `skeleton` | `ListItems` | Rendered while a batch loads |
+| `itemPropertyMap` | object | Forwarded to each batch list |
+
+The queue publisher exposes `resultCount`, the number of rows loaded so far.
+
+No slots. `<template>` children are used as row templates for hosts without Lit; see [HTML integration](/docs/misc/html-integration).

package/src/core/components/functional/router/router.demo.ts

@@ -5,7 +5,7 @@ import { Routes } from "@supersoniks/concorde/core/utils/route";
 
 import { tailwind } from "../../../../docs/tailwind";
 const defaultRoute = {
-  user: "#user/:id/:slug",
+  flight: "#flights/:code",
 };
 export type AppRoutes = typeof defaultRoute;
 
@@ -17,28 +17,28 @@ export class RouterDemo extends LitElement {
 
   @state()
   private routes = {
-    "#home": () => html`
+    "#departures": () => html`
       <div class="p-4 border border-gray-200 rounded-md">
-        <h1 class="text-xl font-medium mb-2">Accueil</h1>
-        <p class="text-gray-600">Bienvenue sur la démo du router</p>
+        <h1 class="text-xl font-medium mb-2">Departures</h1>
+        <p class="text-gray-600">CN 001 to New York boards at gate B12.</p>
       </div>
     `,
-    [defaultRoute.user]: ({ slug, id }: { id: string; slug: string }) => html`
+    [defaultRoute.flight]: ({ code }: { code: string }) => html`
       <div class="p-4 border border-gray-200 rounded-md">
-        <h1 class="text-xl font-medium mb-2">Profil Utilisateur ${id}</h1>
-        <p class="text-gray-600">Slug: ${slug}</p>
+        <h1 class="text-xl font-medium mb-2">Flight ${code}</h1>
+        <p class="text-gray-600">CDG → JFK</p>
       </div>
     `,
-    "#products/(\\d+)/(\\w+)": ([id, slug]: [string, string]) => html`
+    "#gates/([A-Z])(\\d+)": ([terminal, gate]: [string, string]) => html`
       <div class="p-4 border border-gray-200 rounded-md">
-        <h1 class="text-xl font-medium mb-2">Produit ${id}</h1>
-        <p class="text-gray-600">Slug: ${slug}</p>
+        <h1 class="text-xl font-medium mb-2">Terminal ${terminal}</h1>
+        <p class="text-gray-600">Gate ${gate}</p>
       </div>
     `,
     fallback: () => html`
       <div class="p-4 border border-red-200 bg-red-50 rounded-md">
         <h1 class="text-xl font-medium text-red-800 mb-2">404</h1>
-        <p class="text-red-600">Page non trouvée</p>
+        <p class="text-red-600">Page not found</p>
       </div>
     `,
   };
@@ -46,13 +46,13 @@ export class RouterDemo extends LitElement {
   render() {
     return html`
       <div class="p-4">
-        <h2 class="text-2xl font-medium mb-6">Démo du router</h2>
+        <h2 class="text-2xl font-medium mb-6">Router demo</h2>
 
         <div class="flex gap-4 mb-6">
-          <sonic-button href="#home"> Accueil </sonic-button>
-          <sonic-button href="#user/123/mySlug"> Utilisateur 123 </sonic-button>
-          <sonic-button href="#products/456/mySlug"> Produit 456 </sonic-button>
-          <sonic-button href="#invalid"> 404 </sonic-button>
+          <sonic-button href="#departures">Departures</sonic-button>
+          <sonic-button href="#flights/CN001">Flight CN 001</sonic-button>
+          <sonic-button href="#gates/B12">Gate B12</sonic-button>
+          <sonic-button href="#invalid">404</sonic-button>
         </div>
 
         <sonic-router .routes=${this.routes}></sonic-router>

package/src/core/components/functional/router/router.md

@@ -1,94 +1,93 @@
 # Router
 
-**sonic-router** watches `document.location` (pathname + hash) and renders the matching view.
+**`sonic-router`** watches the location (pathname + hash) and renders the views whose route matches. From Lit, pass a `.routes` map of path patterns to render functions; use **`sonic-redirect`** to navigate when a value appears in a data provider.
 
-From a **Lit** parent, pass a **`.routes`** map (property binding — same rule as [`.items` on list](#core/components/functional/list/list.md/list)): keys are path patterns, values are render functions. Use **`fallback`** when nothing matches.
+## Static routes
 
-Legacy HTML **`<template data-route="…">`** remains for hosts without Lit — [HTML integration](#docs/_misc/html-integration.md/html-integration).
-
-## Static routes (no parameters)
-
-Route keys are matched against `pathname + hash`. A simple hash route `#home` matches when the location contains that segment.
-
-On the **doc site**, the page URL is already a hash (`#…/router.md/router`). Demos append a **second** hash for in-page routes (`#…/router#home`), use **`href` + `autoActive="strict"`** on `sonic-button` for the active state, and `history.replaceState` on click so markdown is not reloaded (`setDocsDemoSubHash` in `src/docs/docs-location.ts`).
+Each key is tested against the pathname + hash, first as a RegExp, then as a [url-pattern](https://www.npmjs.com/package/url-pattern). Every matching route renders; the `fallback` key renders when none does. The demo links append a second hash so the doc page itself stays loaded.
 
 <docs-lit-demo for="docs-router-basic-demo"></docs-lit-demo>
 
-```typescript
-@state()
-private routes = {
-  "#home": () => html`<div>Home</div>`,
-  "#about": () => html`<div>About</div>`,
-  fallback: () => html`<div>Not found</div>`,
-};
+Set `.routes` as a **property** binding: render functions cannot go through an HTML attribute.
 
-html`
-  <sonic-button href="#home">Home</sonic-button>
-  <sonic-router .routes=${this.routes}></sonic-router>
-`;
-```
+## Route parameters
 
-| Key | When it runs |
-|-----|----------------|
-| `"#home"`, `"#about"`, … | `RegExp` or [url-pattern](https://www.npmjs.com/package/url-pattern) test succeeds on current location |
-| **`fallback`** | No other route matched (not an attribute — a key on the same object) |
+A url-pattern key such as `#flights/:code` passes an object (`{ code }`) to its render function. A RegExp key passes its capturing groups as an array, in order.
 
-## Routes with parameters
+<docs-lit-demo for="docs-router-params-demo"></docs-lit-demo>
 
-Two styles (see `router.demo.ts` and `docs-router-params-demo`):
+## Base path
 
-### Url-pattern (`:name`)
+By default, url-pattern keys accept any leading slashes and RegExp keys are not anchored. Set `basePath` to require a prefix: it is prepended to every url-pattern key, and to RegExp keys after `^`.
 
-Key uses **`:param`** segments. The render function receives an **object** `{ param: string }`.
+<sonic-code language="html" noPreview>
+  <template>
+&lt;sonic-router basePath="/app"&gt;&lt;/sonic-router&gt;
+&lt;!-- "/fleet" now matches /app/fleet only --&gt;
+  </template>
+</sonic-code>
 
-<docs-lit-demo for="docs-router-params-demo"></docs-lit-demo>
+## HTML templates
 
-```typescript
-"#couleur/:id": ({ id }) => html`<p>Colour id: ${id}</p>`,
-```
+Without Lit, declare `<template data-route>` children. A `title` attribute sets `document.title` and `data-fallback` marks the template shown when nothing matches. `dataProviderExpression` wraps the content in an element whose `dataProvider` is built from the route (`$1` or `:name`), as in [States](/core/components/functional/states).
 
-### RegExp (capturing groups)
+<sonic-code language="html" noPreview>
+  <template>
+&lt;sonic-router fallBackRoute="/departures"&gt;
+  &lt;template data-route="/departures" title="Departures"&gt;…&lt;/template&gt;
+  &lt;template data-route="/flights/:code" dataProviderExpression="flights/:code"&gt;
+    &lt;sonic-value key="status"&gt;&lt;/sonic-value&gt;
+  &lt;/template&gt;
+&lt;/sonic-router&gt;
+  </template>
+</sonic-code>
 
-Key is a **RegExp** string with `(\d+)` / `(\w+)` groups. The render function receives an **array** of captured strings (in order).
+`fallBackRoute` navigates to its URL when no route matches, even if a `data-fallback` template exists. A `routes.fallback` function prevents it.
 
-```typescript
-"#products/(\\d+)/(\\w+)": ([productId, slug]) =>
-  html`<p>Product ${productId}, slug ${slug}</p>`,
-```
+## Redirect on data
 
-With parameters you usually render data directly in Lit (`${id}`). The old **`<template data-route>` + `dataProviderExpression`** pattern scoped a `dataProvider` for `data-bind` / fetch children — prefer **`@subscribe`** or explicit props when using `.routes`.
+**`sonic-redirect`** navigates to `to` once the value at `onData` (dot path) in its data provider is set and truthy. Here, checking in sends the passenger to the boarding page.
 
-## `.routes` binding
+<sonic-code language="html" noPreview>
+  <template>
+&lt;sonic-redirect to="#boarding" dataProvider="checkin" onData="checkedIn"&gt;&lt;/sonic-redirect&gt;
+&lt;div formDataProvider="checkin"&gt;
+  &lt;sonic-button radio name="checkedIn" value="yes"&gt;Check in&lt;/sonic-button&gt;
+&lt;/div&gt;
+  </template>
+</sonic-code>
 
-Always use **`.routes=${…}`** in Lit templates: route handlers are functions and must be set as **properties**, not HTML attributes.
+Objects do not trigger the redirect: point `onData` at a scalar such as `passenger.id`.
 
-## Optional attributes
+## API reference
 
-| Attribute | Role |
-|-----------|------|
-| **`basePath`** | Prefix for pattern matching (default allows optional leading segments) |
-| **`fallBackRoute`** | If set and no template/route matches, navigates to this URL (redirect). Distinct from **`routes.fallback`** which only renders content |
+`sonic-router`
 
-## `sonic-redirect`
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `routes` | object (property) | Render functions keyed by RegExp or url-pattern, plus `fallback` |
+| `basePath` | string | Prefix required before every route. Default: any leading slashes for url-pattern, no anchor for RegExp |
+| `fallBackRoute` | string | URL to navigate to when no route matches and `routes.fallback` is not set |
 
-Separate component: redirect when data appears on a publisher (login steps, wizards). Not part of the `.routes` map.
+| Template attribute | Description |
+|--------------------|-------------|
+| `data-route` | RegExp or url-pattern matched against the location |
+| `data-fallback` | Template shown when no route matches |
+| `title` | Sets `document.title` when the template renders |
+| `dataProviderExpression` | Builds the `dataProvider` of a wrapper around the content from `$1`… or `:name` |
 
-<sonic-code>
-  <template>
-    <sonic-redirect to="#core/components/functional/router/router.md/router#data-is-set" dataProvider="stupid-data-set-id" onData="theData"></sonic-redirect>
-    <div class="flex gap-2 mb-4" formDataProvider="stupid-data-set-id">
-      <sonic-button radio name="theData" value="Some Data" size="xs">
-        Enter data
-      </sonic-button>
-      <sonic-button radio name="theData" value="" href="javascript:history.back();" size="xs">
-        Delete the data and do a history.back()
-      </sonic-button>
-    </div>
-  </template>
-</sonic-code>
+| Slot | Description |
+|------|-------------|
+| *(default)* | `<template data-route>` children |
 
-Example: combine with **`.routes`** and **submit** for login / logout / profile steps.
+`sonic-redirect`
 
-## Package demo
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `to` | string | Destination. A value starting with `#` only changes the hash |
+| `dataProvider` | string | Provider to watch. Inherited from the closest ancestor when omitted |
+| `onData` | string (required) | Dot path of the value that triggers the redirect when truthy |
+| `onAdded` | boolean | Redirects as soon as the element renders, without waiting for data |
+| `pushState` · `replaceState` | boolean | Navigates with `history.pushState` or `history.replaceState` instead of a full load. Ignored for `#` destinations |
 
-`sonic-router-demo` (`router.demo.ts`) — home, user profile (`#user/:id/:slug`), products RegExp, **fallback** 404.
+No slots.

package/src/core/components/functional/sdui/component-catalog.gaps.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-10-26T08:56:47.308Z",
+  "generatedAt": "2026-10-26T08:58:38.625Z",
   "count": 66,
   "items": [
     {

package/src/core/components/functional/sdui/component-catalog.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-10-26T08:56:47.308Z",
+  "generatedAt": "2026-10-26T08:58:38.625Z",
   "componentCount": 67,
   "components": [
     {

package/src/core/components/functional/sdui/example.json

@@ -1,99 +1,32 @@
 {
   "nodes": [
     {
-      "tagName": "div",
-      "attributes": {
-        "class": "flex gap-2 items-center",
-        "formdataprovider": "states-basic-example"
-      },
+      "tagName": "sonic-card",
+      "attributes": { "class": "block max-w-sm" },
       "nodes": [
         {
-          "tagName": "sonic-button",
-          "attributes": {
-            "radio": "",
-            "name": "selection",
-            "value": "#home",
-            "checked": "",
-            "size": "xs"
-          },
-          "innerHTML": "Home"
-        },
-        {
-          "tagName": "sonic-button",
-          "attributes": {
-            "radio": "",
-            "name": "selection",
-            "value": "#about",
-            "size": "xs"
-          },
-          "innerHTML": "About"
-        },
-        {
-          "tagName": "sonic-button",
-          "attributes": {
-            "radio": "",
-            "name": "selection",
-            "value": "#work",
-            "size": "xs"
-          },
-          "innerHTML": "Work"
-        },
-        {
-          "tagName": "sonic-button",
-          "attributes": {
-            "radio": "",
-            "name": "selection",
-            "value": "#contact",
-            "size": "xs"
-          },
-          "innerHTML": "Contact"
-        }
-      ]
-    },
-    {
-      "tagName": "div",
-      "attributes": {
-        "class": "text-center text-neutral-700 border rounded text-4xl  my-6 p-3 "
-      },
-      "nodes": [
-        {
-          "tagName": "sonic-states",
-          "attributes": {
-            "dataprovider": "states-basic-example",
-            "data-path": "selection"
-          },
+          "tagName": "div",
+          "attributes": { "class": "flex items-center justify-between gap-2" },
           "nodes": [
+            { "tagName": "strong", "textContent": "Boarding pass · CN 001" },
             {
-              "tagName": "template",
-              "attributes": {
-                "data-value": "#home"
-              },
-              "innerHTML": "Home"
-            },
-            {
-              "tagName": "template",
-              "attributes": {
-                "data-value": "#about"
-              },
-              "innerHTML": "About"
-            },
-            {
-              "tagName": "template",
-              "attributes": {
-                "data-value": "#work"
-              },
-              "innerHTML": "Work"
-            },
-            {
-              "tagName": "template",
-              "attributes": {
-                "data-value": "#contact"
-              },
-              "innerHTML": "Contact"
+              "tagName": "sonic-badge",
+              "attributes": { "type": "success" },
+              "textContent": "Boarding"
             }
           ]
+        },
+        {
+          "tagName": "p",
+          "attributes": { "class": "m-0 mt-3 text-2xl" },
+          "textContent": "CDG → JFK"
+        },
+        {
+          "tagName": "p",
+          "attributes": { "class": "m-0 mt-1 text-sm" },
+          "textContent": "Ada Lindqvist · Gate C4 · Seat 2A"
         }
       ]
     }
   ]
-}
+}

package/src/core/components/functional/sdui/sdui-extension-points.md

@@ -3,7 +3,7 @@
 Aide-mémoire pour les dépôts externes (adaptateurs, shells).  
 **Pas une page de la doc site** — à lire dans le package npm  
 (`node_modules/@supersoniks/concorde/src/core/components/functional/sdui/sdui-extension-points.md`).  
-La doc utilisateur / crawl reste `sdui.md` (auto-suffisante).
+La doc utilisateur reste `sdui.md` (auto-suffisante).
 
 **Aucune mention de protocoles tiers ici** : uniquement les API génériques Concorde.