@supersoniks/concorde 5.1.1 → 5.1.2

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

@@ -1,125 +1,108 @@
 # Fetch
 
-> **New apps:** prefer [@get](#docs/_decorators/get.md/get) for a typed GET on a component, or [List](#core/components/functional/list/list.md/list) / [Queue](#core/components/functional/queue/queue.md/queue) with `fetch` for collections. Use [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) (`serviceURL="/docs-mock-api"`) to try examples offline.
-
-The **sonic-fetch** component requests and stores API data. It extends the Fetcher and [Subscriber](#docs/_core-concept/subscriber.md/subscriber) mixins.
-
-
-
-
-
-## Basic usage
-In order to work properly the <b>sonic-fetch</b> component needs at least the following attributes.  
-- **serviceURL** : A base service url. This attribute can be inherited from an ancestor.
-  *ex : /docs-mock-api*
-- **endPoint** : the specific location where requests for information are sent (see the api docs).  
-  *ex : api/users | api/users?page=2 | api/users/2*
-- **dataProvider *(Required)*** : An ID that is used as a reference to the object storing the data returned by the API.
-This attribute can be inherited from an ancestor.
+**`sonic-fetch`** sends a GET request to `serviceURL` + `endPoint` and publishes the response under `dataProvider`, so its children and any subscriber of that provider can render it. In a Lit component, prefer the [@get](/docs/decorators/get) decorator; for collections, use [List](/core/components/functional/list) or [Queue](/core/components/functional/queue).
 
+## Basic example
 
+`dataProvider` is required; `serviceURL` and `dataProvider` can be set on an ancestor. Children are hidden while the request is pending. With no `serviceURL`, requests go to the page origin.
 
 <sonic-code>
   <template>
-<sonic-fetch serviceURL="/docs-mock-api" endPoint="api/users?page=2" dataProvider="myDataObj"></sonic-fetch>
-<sonic-button dataProvider="myDataObj" debug>Hover to see the data</sonic-button>
+    <sonic-fetch serviceURL="/docs-mock-api" endPoint="flights?direction=departures" dataProvider="docsFetchNextDeparture" key="flights.0">
+      <p data-bind ::inner-html="Next departure: <b>$code</b> to $city, gate $gate"></p>
+    </sonic-fetch>
   </template>
 </sonic-code>
 
-## DataProvider as an endPoint
-If no **endPoint** is specified it will be filled by the **dataProvider ID** instead  
+## Data provider as endpoint
+
+With no `endPoint`, the `dataProvider` value is used as the endpoint.
 
 <sonic-code>
   <template>
-    <sonic-fetch serviceURL="/docs-mock-api" dataProvider="api/users?page=2" ></sonic-fetch>
-    <sonic-button dataProvider="api/users?page=2" debug>Hover to see the data</sonic-button>
+    <sonic-fetch serviceURL="/docs-mock-api" dataProvider="flights?direction=arrivals" key="flights.0">
+      <p data-bind ::inner-html="Next arrival: <b>$code</b> from $city at $time"></p>
+    </sonic-fetch>
   </template>
 </sonic-code>
 
-## HeadersDataProvider
-
-<sonic-alert status="error" background>Deprecated</sonic-alert>
-
 ## Key
-When the **key** attribute is present, only a sub-part of the data received is injected into the **dataProvider**.
-We can use the dot syntax to target what we want to keep.
 
-For example if the data is `{my:{data:{a:1,b:2}}}` and the key is `key="my.data"`, the data available in the **dataProvider** will be `{a:1 , b:2}`
+`key` keeps only part of the response, using a dot path: with `{ "flights": [ … ] }` and `key="flights.1"`, the provider holds the second flight. Add `preserveOtherKeys` to merge the target into the parent object instead of dropping its siblings. With no `key`, the whole response is published.
 
 <sonic-code>
   <template>
-    <sonic-fetch serviceURL="/docs-mock-api" dataProvider="api/users/2" ></sonic-fetch>
-    <sonic-button dataProvider="api/users/2" debug>dataProvider object</sonic-button>
-    <!-- Get the user ID -->
-    <sonic-fetch serviceURL="/docs-mock-api" dataProvider="id" endPoint="api/users/2" key="data.id"></sonic-fetch>
-    <sonic-button dataProvider="id" debug>data.id</sonic-button>
-    <!-- Get the user First name -->
-    <sonic-fetch serviceURL="/docs-mock-api" dataProvider="first_name" endPoint="api/users/2" key="data.first_name"></sonic-fetch>
-    <sonic-button dataProvider="first_name" debug>data.first_name</sonic-button>
-    <!-- Get the user Last name -->
-    <sonic-fetch serviceURL="/docs-mock-api" dataProvider="last_name" endPoint="api/users/2" key="data.last_name"></sonic-fetch>
-    <sonic-button dataProvider="last_name" debug>data.last_name</sonic-button>
-    <!-- Get the user email -->
-    <sonic-fetch serviceURL="/docs-mock-api" dataProvider="email" endPoint="api/users/2" key="data.email"></sonic-fetch>
-    <sonic-button dataProvider="email" debug>data.email</sonic-button>
+    <sonic-fetch serviceURL="/docs-mock-api" endPoint="flights?direction=departures" dataProvider="docsFetchKey" key="flights.1">
+      <p data-bind ::inner-html="$code to $city ($airport), status $status"></p>
+    </sonic-fetch>
   </template>
 </sonic-code>
 
-## Text mode
+## Loader and skeleton
 
-if the mime type of the content returned by the service begins with **text/**, then the dataProvider has a key named "text" which contains the text returned by the service.
+With no `loader`, nothing is shown during the request. Set `loader` (`fixed` overlay) or `loader="inline"` to show a [Loader](/core/components/ui/loader), or add a `<template skeleton>` child rendered in place of the content while loading.
 
 <sonic-code>
   <template>
-    <sonic-fetch endPoint="README.md" dataProvider="fetchText"></sonic-fetch>
-    <sonic-button dataProvider="fetchText" debug>Hover to see the data</sonic-button>
+    <sonic-fetch loader="inline" serviceURL="/docs-mock-api" endPoint="flights?direction=arrivals" dataProvider="docsFetchLoader" key="flights.2">
+      <template skeleton>
+        <p class="text-neutral-400">Loading arrivals…</p>
+      </template>
+      <p data-bind ::inner-html="<b>$code</b> from $city: $status"></p>
+    </sonic-fetch>
   </template>
 </sonic-code>
 
-## NoLoader
+## Text responses
 
-The noLoader attribute disables display of the default loader
+When the response type starts with `text/`, the provider holds `{ text: "…" }`.
 
 <sonic-code>
   <template>
-    <sonic-fetch noLoader serviceURL="/docs-mock-api" endPoint="api/users?page=2" dataProvider="myDataObj"></sonic-fetch>
-    <sonic-button dataProvider="myDataObj" debug>Basic fetch with noLoader attribute</sonic-button>
+    <sonic-fetch endPoint="robots.txt" dataProvider="docsFetchText">
+      <pre class="max-h-40 overflow-auto text-xs" data-bind ::inner-html="$text"></pre>
+    </sonic-fetch>
   </template>
 </sonic-code>
 
+## Reloading
 
+`endPoint` is reactive: changing it fetches again. Call `invalidate()` on the publisher to reload the same endpoint, or set `refetchEveryMs` to poll. A request that fails with no data shows an error toast.
 
+<sonic-code language="typescript">
+  <template>
+import { PublisherManager } from "@supersoniks/concorde/utils";
 
-<!--
- ## Summary
- Extends mixins : Fetcher, [Subscriber](#core/components/functional/subscriber/subscriber.md/subscriber)
- 
- ### Configuration via les attributs
-
-| nom          | sur quelle balise | Description | Exemple de valeur | défaut / requis |
-|-----|-----|---|---|---|
-| serviceURL   |Fetcher ou un de ses parents | URL de base des services. | http://la-billetterie.net/api/v2 | domain du site |
-| endpoint   |Fetcher | point d'accès d'un service | user/2 | valeur de l'attribut dataProvider |
-| dataProvider  |Fetcher ou un de ses parents | Identifiant d'un publisher qui stock les données, voir [subscriber](#core/components/functional/subscriber/subscriber.md/subscriber). | billetterie/user/2 | *REQUIS* |
-| headersDataProvider  |Fetcher ou un de ses parents | Identifiant d'un publisher qui stock les données destinées à être envoyées en entêtes de la requetes | MyCoockieHEaders | null |
-| key  |Fetcher  | extrait une sous propriété de la donnée chargée avant de l'assignée à son publisher | ma.data | null |
-
- *Si la données est `{ma:{data:{a:1,b:2}}}` et `key="ma.data"`, la données disponible dans le composant sera `{a:1, b:2}`*
- 
- ### Intégration auto de basic auth (pour tester une api qui nécessite une authentification) 
-
- Fetch utilise le service pour générer le token et l'ajoute au header de l'appel qui récupère les données.
-
-| nom           | sur quelle balise | Description | Exemple de valeur | défaut / requis |
-|-----|-----|---|---|---|
-| userName      | Fetcher ou un de ses parents | Nom de l'utilisateur | DjuDju | null |
-| password      | Fetcher ou un de ses parents | mot de passe | pom_549 | null |
-| tokenProvider | Fetcher ou un de ses parents | point d'accès du service fournissant le token | auth | null |
-| token | Fetcher ou un de ses parents | A fournir à la place des autres attributs si on le possède | q<d34gb | null |
-
- ### Autres choses utiles
- L'attribut *noLoader* du composant permet de désactiver l'affichage du loader par défaut.
- On peut appeler la methode invalidate() sur le publisher associé au  composant pour declencher le rechargement des données.
- endPoint est une propriété réctive, par conséquent, sa modification, manuelle via template ou data binbding provoque la mise à jour du contenu.
--->
+PublisherManager.get("docsFetchNextDeparture").invalidate();
+  </template>
+</sonic-code>
 
+## API reference
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `dataProvider` | string | **Required.** Publisher that receives the data. Also the endpoint when `endPoint` is empty. Inherited from ancestors |
+| `serviceURL` | URL (default page origin) | Base URL of the API. Inherited from ancestors |
+| `endPoint` | string | Path appended to `serviceURL`. Reactive |
+| `key` | dot path | Part of the response to publish |
+| `preserveOtherKeys` | boolean | With `key`, keeps the sibling properties of the target |
+| `loader` | `fixed` (when empty) · `inline` | Loader shown during the request. None by default |
+| `lazyload` | boolean | Fetches when the element nears the viewport |
+| `lazyBoundsRatio` | number (default `1`) | Viewport ratio used as margin by `lazyload` |
+| `refetchEveryMs` | number (default `0`) | Polling interval in milliseconds; `0` disables it |
+| `headersDataProvider` | string | Publisher whose data is sent as request headers. Inherited from ancestors |
+| `token` | string | Bearer token. Inherited from ancestors |
+| `userName` · `password` · `tokenProvider` | string | Basic auth used to get a token from `tokenProvider` when no `token` is set. Inherited from ancestors |
+| `credentials` | `omit` · `same-origin` · `include` | `fetch` credentials mode. Inherited from ancestors |
+| `cache` | `RequestCache` value | `fetch` cache mode |
+| `addHTTPResponse` | boolean | Adds the HTTP response as `_sonic_http_response_` on the data. Inherited from ancestors |
+| `localStorage` | `disabled` (default) · `enabled` | Persists the publisher in `localStorage` |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Content, hidden while the request is pending |
+
+| Event | Description |
+|-------|-------------|
+| `loading` | The request starts |
+| `load` | The data is published |

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

@@ -1,9 +1,34 @@
-# if
+# If
 
-The **sonic-if** component shows its slot when **`.condition`** is true. In Lit, bind `.condition` from store-driven state (`@subscribe` on a `formDataProvider` field) — live preview and **TypeScript source are the same file** (`docs-lit-demo`):
+**`sonic-if`** renders its default slot only while `condition` is true. Use it to show or hide a block from reactive state; with no `condition`, the content is not rendered. The host uses `display: contents`, so it adds no box to the layout.
+
+## Basic example
+
+<sonic-code>
+  <template>
+    <sonic-if condition>
+      <sonic-badge type="success">CN 001 · Boarding</sonic-badge>
+    </sonic-if>
+    <sonic-if>
+      <sonic-badge type="danger">Never rendered</sonic-badge>
+    </sonic-if>
+  </template>
+</sonic-code>
+
+`condition` is a boolean attribute: **any value, even `condition="false"`, counts as true**. To toggle it, remove the attribute or bind the property.
+
+## Reactive condition
+
+In Lit, bind `.condition` to state read with `@subscribe`. Here a checkbox writes to a `formDataProvider` and the component re-renders from it.
 
 <docs-lit-demo for="docs-toggle-if-demo"></docs-lit-demo>
 
-Plain HTML without Lit: [HTML integration](#docs/_misc/html-integration.md/html-integration).
+## API reference
 
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `condition` | boolean (default `false`) | Renders the default slot when true |
 
+| Slot | Description |
+|------|-------------|
+| *(default)* | Content rendered while `condition` is true |

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

@@ -1,56 +1,61 @@
 # Jsonata
 
-`sonic-jsonata` : **1 input → expression → 1 output** (readonly).
+**`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.
 
-Unidirectional (fetch → compute → display), unlike [`sonic-mix`](#core/components/functional/mix/mix.md/mix).
+## Group and sort
 
-> Offline : `serviceURL="/docs-mock-api"` — [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api).
-
-## Demos
-
-### Groupby + top N
-
-Change **Top N** → recalcul sans refetch.
+`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.
 
 <docs-lit-demo for="docs-jsonata-space-cats-demo"></docs-lit-demo>
 
-### Totaux (somme + taxe)
-
-Change **Tax %** → même idée.
-
-<docs-lit-demo for="docs-jsonata-table-totals-demo"></docs-lit-demo>
-
-## Attributes
+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.
 
-| 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`) |
+## Totals
 
-## Helpers
+A `( … )` block declares local variables and returns an object; read its fields with `sonic-value`. Change the reserve to recompute the block fuel.
 
-`$ucFirst` · `$currency` · `$percent` · `$date` · `$toChart(items, labelKey, valueKey, datasetLabel?)`
+<docs-lit-demo for="docs-jsonata-table-totals-demo"></docs-lit-demo>
 
-Pas de DOM, pas de réseau, pas d’`eval`.
+## States
 
-## Markup
+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).
 
-<sonic-code language="html">
+<sonic-code>
   <template>
-&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;
+    <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>
   </template>
 </sonic-code>
 
-Pour du multi-entrées ou une fonction TS : primitive [`derive`](#docs/_core-concept/dataFlow.md/dataFlow).
+## API reference
 
-## States
+| 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.
 
-`{output}/_state_` → `{ status, error? }` (`loading` | `ready` | `error` | `empty`). Brancher avec `sonic-states`.
+No slots.

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

@@ -1,65 +1,121 @@
 # List
 
-> **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).
+**`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>`.
 
-The **sonic-list** component renders one row per entry in **`props`** (array from fetch or set on the element).
+## Basic example
 
-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))
+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.
 
-## Row renderer (`items`) — recommended
+<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>
 
-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`).
+Fetch attributes (`lazyload` · `refetchEveryMs` · headers · authentication) are shared with [Fetch](/core/components/functional/fetch).
 
-```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>
-`;
+## Row renderer
 
-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`):
+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`.
 
 <docs-lit-demo for="docs-list-alternate-demo"></docs-lit-demo>
 
-<docs-lit-demo for="docs-list-template-key-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>
 
 ## 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>
 
-## Fetch + `extractValues`
+## Limit and offset
 
-<docs-lit-demo for="docs-list-extract-values-demo"></docs-lit-demo>
+`limit` caps the number of rendered rows and `offset` skips the first ones, without changing the data. With no `limit`, every row is rendered.
 
-## HTML `<template>` children (integration without Lit)
+<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>
 
-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.
+## Objects and `extractValues`
 
-Each list row still gets `dataProvider="[list]/list-item/[index]"`.
+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 }`.
 
-## Additionnal tips
+<docs-lit-demo for="docs-list-extract-values-demo"></docs-lit-demo>
 
-* 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.
+## 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` |

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

@@ -1,41 +1,46 @@
 # Mix
 
-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.
+**`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.
 
-Dot notation is supported to extract a sub-part of the data.
+## 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.
 
-For example, if we declare dataproviders as follows :
-<sonic-code>
-  <template>
-    <sonic-subscriber dataProvider="dataToMixA" props='{"foo":{"bar":2}}'></sonic-subscriber>
-    <sonic-subscriber dataProvider="dataToMixB" props='{"baz":3}'></sonic-subscriber>
-  </template>
-</sonic-code>
-We can rearrange the data as follows
 <sonic-code>
   <template>
-    <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-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>
   </template>
 </sonic-code>
-Then we can change values in both dataProviders programaticaly this way, they will stay in sync
-<sonic-code language="javascript">
+
+## 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`.
+
+<sonic-code>
   <template>
-  SonicPublisherManager.get("mixedData").either.baz=6;
-  SonicPublisherManager.get("dataToMixB").baz=8;
-  SonicPublisherManager.get("dataToMixA").foo.bar=8;
-  SonicPublisherManager.get("mixedData").orThat=6;
+    <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>
   </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/src/core/components/functional/queue/queue.demo.ts

@@ -4,19 +4,21 @@ import { customElement } from "lit/decorators.js";
 import "./queue";
 import { tailwind } from "../../../../docs/tailwind";
 
+type FlightRow = { code: string; city: string; airport: string; time: string };
+
 @customElement("sonic-queue-demo")
 export class QueueDemo extends LitElement {
   static styles = [tailwind];
 
-  private items = (item: any) => html`
+  private items = (item: FlightRow) => html`
     <div class="bg-neutral-100 p-2 rounded-md">
-      <div class="font-medium">${item.nom}</div>
-      <div class="text-sm text-gray-600">Code: ${item.code}</div>
+      <div class="font-medium">${item.code} · ${item.city}</div>
+      <div class="text-sm text-gray-600">${item.airport} · ${item.time}</div>
     </div>
   `;
   private noItems = () => html`
     <div class="flex flex-col items-center justify-center p-4 text-gray-500">
-      <p>Aucune commune trouvée</p>
+      <p>No flight found</p>
     </div>
   `;
 
@@ -24,9 +26,10 @@ export class QueueDemo extends LitElement {
     return html`
       <sonic-queue
         class="grid grid-cols-3 gap-3"
-        serviceurl="/docs-mock-api/geo/"
-        dataproviderexpression="communes?limit=$limit"
-        limit="30"
+        serviceURL="/docs-mock-api"
+        dataProviderExpression="flights?limit=$limit"
+        key="flights"
+        limit="15"
         .items=${this.items}
         .noItems=${this.noItems}
       ></sonic-queue>