@supersoniks/concorde 5.1.2 → 5.1.3-immutable.1

package/docs/src/core/components/functional/jsonata/jsonata.md

@@ -1,61 +1,56 @@
 # Jsonata
 
-**`sonic-jsonata`** reads one data provider, evaluates a [JSONata](https://jsonata.org) expression on it and writes the result to another data provider. Use it for read-only aggregates such as groups, rankings and totals; use [Mix](/core/components/functional/mix) to compose data in both directions, and [`derive`](/docs/getting-started/dataFlow) for several inputs or a TypeScript function.
+`sonic-jsonata` : **1 input → expression → 1 output** (readonly).
 
-## Group and sort
+Unidirectional (fetch → compute → display), unlike [`sonic-mix`](#core/components/functional/mix/mix.md/mix).
 
-`inputProvider` is available as `$input` and the result is written to `outputProvider`. Each field of the optional `formDataProvider` store becomes a variable (`$direction` here): changing it recomputes the output without fetching again.
+> Offline : `serviceURL="/docs-mock-api"` — [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api).
 
-<docs-lit-demo for="docs-jsonata-space-cats-demo"></docs-lit-demo>
+## Demos
+
+### Groupby + top N
+
+Change **Top N** → recalcul sans refetch.
 
-JSONata returns a single object instead of an array when only one item matches. Wrap the expression in `$append([], …)` when a list renders the output.
+<docs-lit-demo for="docs-jsonata-space-cats-demo"></docs-lit-demo>
 
-## Totals
+### Totaux (somme + taxe)
 
-A `( … )` block declares local variables and returns an object; read its fields with `sonic-value`. Change the reserve to recompute the block fuel.
+Change **Tax %** → même idée.
 
 <docs-lit-demo for="docs-jsonata-table-totals-demo"></docs-lit-demo>
 
-## States
+## Attributes
+
+| Attribute | Role |
+|-----------|------|
+| `inputProvider` | Entrée (`$input` dans l’expression) |
+| `outputProvider` | Sortie (readonly) |
+| `expression` | Expression JSONata |
+| `formDataProvider` | Form optionnel (`$top`, `$taxPercent`, …) — même id que le form |
+| `outputSchema` | Schéma léger optionnel (`type`, `required`) |
 
-The evaluation state is published on `{outputProvider}/_state_` as `{ status, error }`, with `status` among `loading` · `ready` · `empty` · `error`. Display it with [States](/core/components/functional/states).
+## Helpers
 
-<sonic-code>
+`$ucFirst` · `$currency` · `$percent` · `$date` · `$toChart(items, labelKey, valueKey, datasetLabel?)`
+
+Pas de DOM, pas de réseau, pas d’`eval`.
+
+## Markup
+
+<sonic-code language="html">
   <template>
-    <div serviceURL="/docs-mock-api">
-      <sonic-fetch dataProvider="jsonataStateFlights" endPoint="flights" key="flights"></sonic-fetch>
-      <sonic-jsonata
-        inputProvider="jsonataStateFlights"
-        outputProvider="jsonataLanded"
-        expression='{"landed": $count($input[status="landed"])}'
-      ></sonic-jsonata>
-      <sonic-states dataProvider="jsonataLanded/_state_" data-path="status">
-        <template data-value="loading">Counting flights…</template>
-        <template data-value="ready">Landed flights: <sonic-value dataProvider="jsonataLanded" key="landed"></sonic-value></template>
-        <template data-value="error">Expression error</template>
-      </sonic-states>
-    </div>
+&lt;sonic-jsonata
+  inputProvider="api/space-cats"
+  outputProvider="leaderboard"
+  formDataProvider="topForm"
+  expression='$input{name: $sum(points)} ~> $each(function($v,$k){{"name":$k,"points":$v}}) ^(>points)[[0..$number($top)-1]]'
+&gt;&lt;/sonic-jsonata&gt;
   </template>
 </sonic-code>
 
-## API reference
+Pour du multi-entrées ou une fonction TS : primitive [`derive`](#docs/_core-concept/dataFlow.md/dataFlow).
 
-| Attribute | Values | Description |
-|-----------|--------|-------------|
-| `inputProvider` | string | Source data provider, bound to `$input`. Required |
-| `outputProvider` | string | Data provider that receives the result. Required |
-| `expression` | JSONata string (max 8,000 characters) | Expression to evaluate. Required |
-| `formDataProvider` | string | Store whose fields become variables (`$name`) |
-| `outputSchema` | object | Light check of the result: `type` and `required` only; a mismatch sets the `error` state |
-
-| Helper | Description |
-|--------|-------------|
-| `$ucFirst(value)` | Upper-cases the first letter |
-| `$currency(value, locale?, currency?)` | Formats a price (default `fr-FR` and `EUR`) |
-| `$percent(value, locale?, digits?)` | Formats a ratio as a percentage (default `fr-FR` and `0` digits) |
-| `$date(value, locale?, optionsJson?)` | Formats a date (default `fr-FR`, medium style) |
-| `$toChart(items, labelKey, valueKey, datasetLabel?)` | Converts rows to `{ labels, datasets }` for a chart |
-
-Expressions have no access to the DOM or the network.
+## States
 
-No slots.
+`{output}/_state_` → `{ status, error? }` (`loading` | `ready` | `error` | `empty`). Brancher avec `sonic-states`.

package/docs/src/core/components/functional/list/list.md

@@ -1,121 +1,65 @@
 # List
 
-**`sonic-list`** renders one row per entry of its `props` array, either set directly or loaded with `fetch`. From Lit, pass a row renderer on the `items` property; in plain HTML, declare `<template>` children. Each row gets its own data provider at `<dataProvider>/list-item/<index>`.
+> **Try offline:** `serviceURL="/docs-mock-api"` and `dataProvider="api/users"` with `key="data"` — see [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api). Recommended patterns: [Data flow](#docs/_core-concept/dataFlow.md/dataFlow).
 
-## Basic example
+The **sonic-list** component renders one row per entry in **`props`** (array from fetch or set on the element).
 
-Add `fetch` to load `props` from `serviceURL` + `endPoint` (or `dataProvider` when `endPoint` is empty). `key` picks the array inside the response. Without `fetch`, the list only renders the `props` it receives.
+List extends [Subscriber](#docs/_core-concept/subscriber.md/subscriber) and **Fetcher**:
+* **Subscriber** — `props` + `dataProvider`
+* **Fetcher** — optional `fetch` + `serviceURL` / `key` (see [Fetch](#core/components/functional/fetch/fetch.md/fetch))
 
-<sonic-code>
-  <template>
-    <sonic-list fetch serviceURL="/docs-mock-api" dataProvider="flights?direction=arrivals" key="flights" class="grid gap-1">
-      <template>
-        <div class="text-sm" data-bind ::inner-html="<b>$time</b> $code from $city ($airport)"></div>
-      </template>
-    </sonic-list>
-  </template>
-</sonic-code>
+## Row renderer (`items`) — recommended
 
-Fetch attributes (`lazyload` · `refetchEveryMs` · headers · authentication) are shared with [Fetch](/core/components/functional/fetch).
+From a **Lit** parent, pass a function on the **`items`** property (`ListItems`). Each row is wrapped in a `sonic-subscriber` with `dataProvider="…/list-item/n"` (hover rows with `debug`).
 
-## Row renderer
+```typescript
+private items = ({ first_name, last_name, email, avatar }) => html`
+  <sonic-image src=${avatar} …></sonic-image>
+  <div>${first_name} <b>${last_name}</b></div>
+  <div>${email}</div>
+`;
 
-From a Lit component, set `.items` to a function `(item, metadata) => TemplateResult`. Functions only pass as properties, so always use the `.` binding: the same applies to `.separator` · `.noItems` · `.skeleton`. `metadata` holds `key` · `even` · `odd` · `firstChild` · `lastChild` · `onlyChild`.
+html`<sonic-list
+  fetch
+  dataProvider="api/users"
+  key="data"
+  serviceURL="/docs-mock-api"
+  .items=${this.items}
+></sonic-list>`;
+```
+
+Use **`.items=${fn}`** (property binding): Lit passes functions only as properties, not as HTML attributes — `@property({ type: Function })` does not change that. Same for **`.noItems`**, **`.separator`**, **`.skeleton`**. The callback receives each row object (replacing `data-bind` / `<sonic-value>` in a `<template>`).
+
+Live demo + TypeScript source (one file, no Markdown copy):
+
+<docs-lit-demo for="docs-users-list"></docs-lit-demo>
+
+Implementation: `src/docs/example/docs-users-list.ts` — row markup in the **`items`** callback (`item.first_name`, …), same idea as replacing `data-bind` / `<sonic-value>` in a `<template>`.
+
+## Alternating row layouts
+
+Use **`metadata`** (`even`, `odd`, `firstChild`, …) or fields on each item (e.g. `tpl` with `templateKey`):
 
 <docs-lit-demo for="docs-list-alternate-demo"></docs-lit-demo>
 
-## Row variants
-
-In HTML, `templateKey` (default `template`) names the row field that selects a `<template data-value="…">`. Rows without a match cycle through the `<template>` children that have no `data-value`. From Lit, branch inside the `items` callback instead.
-
-<sonic-code>
-  <template>
-    <sonic-list fetch serviceURL="/docs-mock-api" dataProvider="flights?direction=departures" key="flights" templateKey="status" class="grid gap-1">
-      <template>
-        <div class="text-sm" data-bind ::inner-html="$code to $city"></div>
-      </template>
-      <template data-value="delayed">
-        <div class="text-sm text-warning" data-bind ::inner-html="$code to $city: delayed"></div>
-      </template>
-      <template data-value="cancelled">
-        <div class="text-sm text-danger line-through" data-bind ::inner-html="$code to $city"></div>
-      </template>
-    </sonic-list>
-  </template>
-</sonic-code>
+<docs-lit-demo for="docs-list-template-key-demo"></docs-lit-demo>
 
 ## Separator and empty list
 
-`.separator` renders between rows (not after the last one). `.noItems` renders when the array is empty. In HTML, use `<template data-value="separator">` and `<template data-value="no-item">`.
-
 <docs-lit-demo for="docs-list-separator-demo"></docs-lit-demo>
 
-## Limit and offset
+## Fetch + `extractValues`
 
-`limit` caps the number of rendered rows and `offset` skips the first ones, without changing the data. With no `limit`, every row is rendered.
+<docs-lit-demo for="docs-list-extract-values-demo"></docs-lit-demo>
 
-<sonic-code>
-  <template>
-    <sonic-list fetch serviceURL="/docs-mock-api" dataProvider="flights?direction=departures" key="flights" limit="3" class="grid gap-1">
-      <template>
-        <div class="text-sm" data-bind ::inner-html="<b>$time</b> $code to $city"></div>
-      </template>
-    </sonic-list>
-  </template>
-</sonic-code>
+## HTML `<template>` children (integration without Lit)
 
-## Objects and `extractValues`
+For **plain HTML** hosts, you can still declare **`<template>`** children (and `data-value` for `templateKey`, `separator`, `no-item`). That path is for [HTML integration](#docs/_misc/html-integration.md/html-integration) — not used in Concorde doc live demos.
 
-When the data is an object, the list wraps it in a one-row array. Add `extractValues` to render one row per property instead, as `{ key, value }`.
+Each list row still gets `dataProvider="[list]/list-item/[index]"`.
 
-<docs-lit-demo for="docs-list-extract-values-demo"></docs-lit-demo>
+## Additionnal tips
 
-## Loading state
-
-With no `loader`, nothing is shown while fetching. Set `loader` (`fixed`) or `loader="inline"` to show a [Loader](/core/components/ui/loader), or provide `.skeleton` / `<template skeleton>` to render placeholder rows; a skeleton replaces the loader. Call `invalidate()` on the list publisher to fetch again.
-
-<sonic-code>
-  <template>
-    <sonic-list fetch loader="inline" serviceURL="/docs-mock-api" dataProvider="flights?direction=arrivals&status=landed" key="flights" class="grid gap-1">
-      <template>
-        <div class="text-sm" data-bind ::inner-html="$code from $city: landed"></div>
-      </template>
-    </sonic-list>
-  </template>
-</sonic-code>
-
-## API reference
-
-| Attribute | Values | Description |
-|-----------|--------|-------------|
-| `dataProvider` | string | Publisher of the list. Also the endpoint when `endPoint` is empty. Inherited from ancestors |
-| `fetch` | boolean | Loads `props` from the API. Without it, the list never fetches |
-| `serviceURL` · `endPoint` · `key` | string | Request configuration, see [Fetch](/core/components/functional/fetch) |
-| `templateKey` | string (default `template`) | Row field that selects a `<template data-value>` |
-| `extractValues` | boolean | Renders an object as one `{ key, value }` row per property |
-| `limit` | number (default unlimited) | Maximum number of rendered rows |
-| `offset` | number (default `0`) | Index of the first rendered row |
-| `loader` | `fixed` (when empty) · `inline` | Loader shown while fetching. None by default |
-| `debug` | boolean | Shows each row's data on hover |
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `props` | array · object | Rows to render |
-| `items` | `(item, metadata) => TemplateResult` | Row renderer |
-| `separator` | `() => TemplateResult` | Rendered between rows |
-| `noItems` | `() => TemplateResult` | Rendered when there are no rows |
-| `skeleton` | `() => TemplateResult` | Rendered while fetching |
-| `itemPropertyMap` | object | `propertyMap` passed to each row subscriber |
-
-| Template | Description |
-|----------|-------------|
-| `<template>` | Row markup; several are used in turn |
-| `<template data-value="…">` | Row variant selected by `templateKey` |
-| `<template data-value="separator">` | Between rows |
-| `<template data-value="no-item">` | Empty list |
-| `<template skeleton>` | While fetching |
-
-| Event | Description |
-|-------|-------------|
-| `loading` | A fetch starts |
-| `load` | Data is loaded and assigned to `props` |
+* If the request returns an object, it is wrapped in an array (unless `extractValues` is set).
+* Call **`invalidate()`** on the list publisher to reload fetch data.
+* Each row publisher exposes **`_parent_`** pointing at the list publisher.

package/docs/src/core/components/functional/mix/mix.md

@@ -1,46 +1,41 @@
 # Mix
 
-**`sonic-mix`** builds a new data provider from parts of other ones. Each key of `composition` maps to a source data provider id, with an optional dot path to a sub-value. The mixed provider is named by the `dataProvider` attribute and stays in sync with its sources in both directions.
+Mix allows you to mix several subsets of dataProvider in a new key/value structure which is itself associated with a new dataProvider. The data update is then bidirectional.
 
-## Basic example
-
-Two sources hold the flight and its gate. The mix exposes the whole flight under `flight` and only the gate number under `gate`; children read them like any other data provider.
+Dot notation is supported to extract a sub-part of the data.
 
+For example, if we declare dataproviders as follows :
 <sonic-code>
   <template>
-    <sonic-subscriber dataProvider="docs-mix-flight" props='{"code":"CN 001","route":"CDG → JFK"}'></sonic-subscriber>
-    <sonic-subscriber dataProvider="docs-mix-gate" props='{"gate":"B12","terminal":"2E"}'></sonic-subscriber>
-    <sonic-mix dataProvider="docs-mix-board" composition='{"flight":"docs-mix-flight","gate":"docs-mix-gate.gate"}'>
-      <p>
-        <sonic-value key="flight.code"></sonic-value> ·
-        <sonic-value key="flight.route"></sonic-value> ·
-        gate <sonic-value key="gate"></sonic-value>
-      </p>
-    </sonic-mix>
+    <sonic-subscriber dataProvider="dataToMixA" props='{"foo":{"bar":2}}'></sonic-subscriber>
+    <sonic-subscriber dataProvider="dataToMixB" props='{"baz":3}'></sonic-subscriber>
   </template>
 </sonic-code>
-
-## Two-way sync
-
-Writing to a source updates the mix, and writing to the mix updates the source. The button changes `docs-mix-gate`; the field writes to `docs-mix-board.gate`.
-
+We can rearrange the data as follows
 <sonic-code>
   <template>
-    <div class="flex flex-wrap items-end gap-4">
-      <sonic-button size="sm" onclick="SonicPublisherManager.get('docs-mix-gate').gate = 'C34'">Gate change to C34</sonic-button>
-      <sonic-input label="Gate (mixed provider)" formDataProvider="docs-mix-board" name="gate"></sonic-input>
-    </div>
-    <p class="mt-2">Source gate: <sonic-value dataProvider="docs-mix-gate" key="gate"></sonic-value></p>
+    <sonic-mix dataProvider="mixedData" composition='{"either":"dataToMixB","orThat":"dataToMixA.foo.bar"}'>
+      <div>Value of dataToMixA.foo.bar and mixedData.orThat : <sonic-value key="orThat"></sonic-value></div>
+      <div>Value of dataToMixB.baz and mixedData.either.baz : <sonic-value key="either.baz"></sonic-value></div>
+    </sonic-mix>
+  </template>
+</sonic-code>
+Then we can change values in both dataProviders programaticaly this way, they will stay in sync
+<sonic-code language="javascript">
+  <template>
+  SonicPublisherManager.get("mixedData").either.baz=6;
+  SonicPublisherManager.get("dataToMixB").baz=8;
+  SonicPublisherManager.get("dataToMixA").foo.bar=8;
+  SonicPublisherManager.get("mixedData").orThat=6;
   </template>
 </sonic-code>
+Or by using a form element
+<sonic-code>
+<template>
+<sonic-input label="mixedData.orThat" formDataProvider="mixedData" name="orThat"></sonic-input>
+</template>
+</sonic-code>
+
 
-## API reference
 
-| Attribute | Values | Description |
-|-----------|--------|-------------|
-| `dataProvider` | string | Id of the mixed data provider. Its content is reset when the composition changes |
-| `composition` | object (JSON) | Keys of the mixed provider mapped to `"providerId"` or `"providerId.path.to.value"` |
 
-| Slot | Description |
-|------|-------------|
-| *(default)* | Content that reads the mixed provider |

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

@@ -1,51 +1,72 @@
 # Queue
 
-**`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`.
+> **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).
 
-## Lazy load
+**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`, …).
 
-`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.
+| 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) |
 
-<docs-lit-demo for="docs-queue-geo-demo"></docs-lit-demo>
+## Lazy load — `$offset` and `$limit`
 
-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.
+When the expression contains **`$offset`** and **`$limit`**, the queue:
 
-## Filters
+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).
 
-`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.
+The doc mock implements this on `GET /docs-mock-api/api/users?offset=…&per_page=…` (`paginateUsers` in `src/docs/mock-api/router.ts`).
 
 <docs-lit-demo for="docs-queue-users-demo"></docs-lit-demo>
 
-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).
+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).

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

@@ -1,93 +1,94 @@
 # Router
 
-**`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.
+**sonic-router** watches `document.location` (pathname + hash) and renders the matching view.
 
-## Static routes
+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.
 
-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.
+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`).
 
 <docs-lit-demo for="docs-router-basic-demo"></docs-lit-demo>
 
-Set `.routes` as a **property** binding: render functions cannot go through an HTML attribute.
+```typescript
+@state()
+private routes = {
+  "#home": () => html`<div>Home</div>`,
+  "#about": () => html`<div>About</div>`,
+  fallback: () => html`<div>Not found</div>`,
+};
 
-## Route parameters
+html`
+  <sonic-button href="#home">Home</sonic-button>
+  <sonic-router .routes=${this.routes}></sonic-router>
+`;
+```
 
-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.
+| 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) |
 
-<docs-lit-demo for="docs-router-params-demo"></docs-lit-demo>
+## Routes with parameters
 
-## Base path
+Two styles (see `router.demo.ts` and `docs-router-params-demo`):
 
-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 `^`.
+### Url-pattern (`:name`)
 
-<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>
+Key uses **`:param`** segments. The render function receives an **object** `{ param: string }`.
 
-## HTML templates
+<docs-lit-demo for="docs-router-params-demo"></docs-lit-demo>
 
-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).
+```typescript
+"#couleur/:id": ({ id }) => html`<p>Colour id: ${id}</p>`,
+```
 
-<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>
+### RegExp (capturing groups)
 
-`fallBackRoute` navigates to its URL when no route matches, even if a `data-fallback` template exists. A `routes.fallback` function prevents it.
+Key is a **RegExp** string with `(\d+)` / `(\w+)` groups. The render function receives an **array** of captured strings (in order).
 
-## Redirect on data
+```typescript
+"#products/(\\d+)/(\\w+)": ([productId, slug]) =>
+  html`<p>Product ${productId}, slug ${slug}</p>`,
+```
 
-**`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.
+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-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>
+## `.routes` binding
 
-Objects do not trigger the redirect: point `onData` at a scalar such as `passenger.id`.
+Always use **`.routes=${…}`** in Lit templates: route handlers are functions and must be set as **properties**, not HTML attributes.
 
-## API reference
+## Optional attributes
 
-`sonic-router`
+| 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 |
 
-| 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 |
+## `sonic-redirect`
 
-| 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` |
+Separate component: redirect when data appears on a publisher (login steps, wizards). Not part of the `.routes` map.
 
-| Slot | Description |
-|------|-------------|
-| *(default)* | `<template data-route>` children |
+<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>
 
-`sonic-redirect`
+Example: combine with **`.routes`** and **submit** for login / logout / profile steps.
 
-| 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 |
+## Package demo
 
-No slots.
+`sonic-router-demo` (`router.demo.ts`) — home, user profile (`#user/:id/:slug`), products RegExp, **fallback** 404.

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

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-10-26T08:58:38.625Z",
+  "generatedAt": "2026-10-08T11:47:30.055Z",
   "count": 66,
   "items": [
     {