@supersoniks/concorde 5.1.1 → 5.1.3

package/docs/src/core/components/functional/sdui/default-library.json

@@ -0,0 +1,108 @@
+{
+    "checkbox": {
+        "tagName": "sonic-checkbox"
+    },
+    "date": {
+        "tagName": "sonic-input",
+        "attributes": {
+            "type": "date"
+        }
+    },
+    "fieldset": {
+        "tagName": "sonic-fieldset",
+        "nodes":[{"libraryKey":"formLayout"}],
+        "contentElementSelector":"sonic-form-layout"
+    },
+    "managed_file": {
+        "tagName": "sonic-input",
+        "attributes": {
+            "variant":"ghost",
+            "type": "file"
+        }
+    },
+    "password": {
+        "tagName": "sonic-input",
+        "attributes": {
+            "type": "password"
+        }
+    },
+    "radio": {
+        "tagName": "sonic-radio"
+    },
+    "select": {
+        "tagName": "sonic-select"
+    },
+    "textarea": {
+        "tagName": "sonic-textarea"
+    },
+    "textfield": {
+        "tagName": "sonic-input",
+        "attributes": {
+            "type": "text"
+        }
+    },
+    "hidden": {
+        "tagName": "sonic-input",
+        "attributes": {
+            "type": "hidden"
+        }
+    },
+    "button": {
+        "tagName": "sonic-button"
+    },
+    "form": {
+        "tagName": "sonic-submit",
+        "attributes": {
+            "onEnterKey": true
+        }
+    },
+    "submit": {
+        "tagName": "sonic-submit",
+        "attributes": {
+            "onClick": true
+        },
+        "contentElementSelector":"sonic-button",
+        "nodes":[
+            {
+                "libraryKey":"button",
+                "attributes":{"type":"success"},
+                "nodes":[
+                    {
+                        "tagName":"sonic-icon",
+                        "attributes":{
+                            "name":"check",
+                            "slot":"prefix"
+                        }
+                    }
+                ]
+            }
+        ]
+    },
+    "email": {
+        "tagName": "sonic-input",
+        "attributes": {
+            "type": "email"
+        }
+    },
+    "formItemContainer": {
+        "tagName": "div",
+        "attributes": {
+            "class": "form-item-container"
+        }
+    },
+    "formLayout": {
+        "tagName": "sonic-form-layout"
+    },
+    "formActions": {
+        "tagName": "sonic-form-actions"
+    },
+    "passwordHelper": {
+        "tagName": "sonic-password-helper"
+    },
+    "sameValueHelper": {
+        "tagName": "sonic-same-value-helper"
+    },
+    "divider": {
+        "tagName": "sonic-divider"
+    }
+}

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

@@ -0,0 +1,32 @@
+{
+  "nodes": [
+    {
+      "tagName": "sonic-card",
+      "attributes": { "class": "block max-w-sm" },
+      "nodes": [
+        {
+          "tagName": "div",
+          "attributes": { "class": "flex items-center justify-between gap-2" },
+          "nodes": [
+            { "tagName": "strong", "textContent": "Boarding pass · CN 001" },
+            {
+              "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/docs/src/core/components/functional/sdui/sdui-extension-points.md

@@ -0,0 +1,94 @@
+# SDUI — points d’extension publics
+
+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 reste `sdui.md` (auto-suffisante).
+
+**Aucune mention de protocoles tiers ici** : uniquement les API génériques Concorde.
+
+## 1. Profil `safe` (opt-in)
+
+```html
+<sonic-sdui profile="safe" …>
+```
+
+| Refusé | Autorisé |
+|--------|----------|
+| `js`, `markup`, `innerHTML`, `prefix`, `suffix` | `textContent`, structure, attributs, `action`, `childNodeIds` |
+
+- Nœud refusé → ignoré + `console.warn` (pas de crash)
+- Helper pur : `validateSafeDescriptor(descriptor)` depuis `sdui-safe`
+
+## 2. Événement `sdui-action`
+
+Sur un nœud :
+
+```json
+{
+  "tagName": "sonic-button",
+  "nodeId": "confirm",
+  "textContent": "OK",
+  "action": { "name": "confirm", "context": { "step": 1 } }
+}
+```
+
+Au clic, `sonic-sdui` émet :
+
+- type : `sdui-action`
+- `detail` : `{ name, context, sourceNodeId? }`
+- `bubbles: true`, `composed: true`
+
+Ne remplace pas `sonic-submit` / POST / `messagesKey`.
+
+## 3. Catalogue de composants (build only)
+
+- Fichier publié : `component-catalog.json`
+- Import : `@supersoniks/concorde/sdui/component-catalog.json`
+- Régénération : `yarn generate:sdui-catalog` (aussi `prebuild`)
+- Gaps d’annotations : `component-catalog.gaps.json`
+- **Aucun impact runtime**
+
+## 4. Rendu partiel (opt-in)
+
+```html
+<sonic-sdui partial …>
+```
+
+- Registre plat : `nodeById`
+- Enfants par id : `childNodeIds`
+- Id manquant + `partial` → placeholder (`data-sdui-placeholder`, `data-sdui-node-id`, `display: contents`)
+- Sans `partial` → warning + skip
+
+## 5. Ops incrémentales (opt-in, chemin à côté)
+
+Le descripteur entier + rebuild reste le chemin par défaut. Les ops mutent un descripteur local et mettent à jour le DOM **chirurgicalement** (frères préservés : focus, valeurs d’input, état composants).
+
+### Méthodes publiques sur `sonic-sdui`
+
+```ts
+upsertNode(node, parentId?, index?)  // node.nodeId requis
+removeNode(nodeId)
+setData(path, value)                 // chemin publisher, ex. "form.email"
+applyOp(op)                          // { op: "upsertNode"|"removeNode"|"setData", … }
+endIncremental()                     // revient au mode props → rebuild
+```
+
+### Flux optionnel
+
+Attribut `opsDataProvider` : chaque valeur assignée (`SDUIOp` ou `SDUIOp[]`) est passée à `applyOp`.
+
+### Comportement
+
+- Première op → clone local du descripteur + mode partial automatique
+- `data-sdui-node-id` marque les nœuds rendus
+- Remplacement d’un placeholder / nœud existant via `replaceWith` (pas de `removeChildren` global)
+
+## Imports utiles
+
+| Artefact | Chemin |
+|----------|--------|
+| Composant | `@supersoniks/concorde/sdui` |
+| Types | `…/sdui/types` (via package exports / short path) |
+| Safe | `@supersoniks/concorde/sdui-safe` |
+| Catalogue | `@supersoniks/concorde/sdui/component-catalog.json` |

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

@@ -0,0 +1,307 @@
+# SDUI
+
+**`sonic-sdui`** builds an interface from a JSON descriptor (server-driven UI). Pass the descriptor through `props`, or add `fetch` and an endpoint to load it like [Fetch](/core/components/functional/fetch). It renders in the light DOM with `display: contents`, so an empty instance does not affect layout.
+
+## Basic example
+
+Each entry of `nodes` becomes an element: `tagName` (default `div`) · `attributes` · `textContent` · nested `nodes`.
+
+<sonic-code>
+  <template>
+    <sonic-sdui
+      dataProvider="sdui-basic-example"
+      props='{
+        "nodes":[{
+          "tagName":"div",
+          "attributes":{ "class":"flex items-center gap-2" },
+          "nodes":[
+            { "tagName":"strong", "textContent":"CN 001 · CDG → JFK" },
+            { "tagName":"sonic-badge", "attributes":{ "type":"warning" }, "textContent":"Delayed" }
+          ]
+        }]
+      }'
+    ></sonic-sdui>
+  </template>
+</sonic-code>
+
+## Fetching a descriptor
+
+Fetching is off by default: add the boolean `fetch` attribute, then configure `serviceURL` / `endPoint` / `dataProvider` as on [Fetch](/core/components/functional/fetch). Invalidating the publisher or changing the endpoint reloads the interface.
+
+<sonic-code>
+  <template>
+    <sonic-sdui fetch dataProvider="sdui-fetch-example" endPoint="/src/core/components/functional/sdui/example.json"></sonic-sdui>
+  </template>
+</sonic-code>
+
+## HTML content
+
+`markup` builds the node from an HTML string, `innerHTML` appends HTML inside the element, and `prefix` / `suffix` wrap it. Prefer `textContent` for anything coming from user data.
+
+<sonic-code>
+  <template>
+    <sonic-sdui
+      dataProvider="sdui-html-example"
+      props='{
+        "nodes":[
+          { "markup":"Cruising at &lt;sonic-badge&gt;Mach 2.04&lt;/sonic-badge&gt;" },
+          { "tagName":"p", "prefix":"&lt;hr&gt;", "innerHTML":"Altitude: &lt;b&gt;60,000 ft&lt;/b&gt;" }
+        ]
+      }'
+    ></sonic-sdui>
+  </template>
+</sonic-code>
+
+## Library
+
+A node with `libraryKey` uses a library entry as its model, then adds its own attributes and children. In the model, `contentElementSelector` sets where those children go. The descriptor `library` is merged over a default library of form fields (`textfield` · `email` · `password` · `date` · `select` · `checkbox` · `radio` · `textarea` · `button` · `submit` · `fieldset`…, see `default-library.json`). The `library` attribute replaces it with a JSON file loaded from a URL.
+
+<sonic-code>
+  <template>
+    <sonic-sdui
+      dataProvider="sdui-library-example"
+      props='{
+        "library":{
+          "flightCard":{
+            "tagName":"sonic-card",
+            "attributes":{ "class":"block max-w-sm" },
+            "nodes":[{ "tagName":"div", "attributes":{ "class":"text-sm" } }],
+            "contentElementSelector":"div"
+          }
+        },
+        "nodes":[
+          { "libraryKey":"flightCard", "nodes":[{ "tagName":"span", "textContent":"CN 001 · Gate C4" }] },
+          { "libraryKey":"email", "attributes":{ "label":"Passenger email", "name":"email", "class":"block mt-4 max-w-sm" } }
+        ]
+      }'
+    ></sonic-sdui>
+  </template>
+</sonic-code>
+
+## Child placement
+
+A child with `parentElementSelector` is appended to the first element matching that selector inside its parent, instead of the parent itself. It has no effect on top-level nodes.
+
+<sonic-code>
+  <template>
+    <sonic-sdui
+      dataProvider="sdui-parent-selector-example"
+      props='{
+        "nodes":[{
+          "nodes":[
+            { "tagName":"strong", "textContent":"Departures" },
+            { "tagName":"ul" },
+            { "tagName":"li", "parentElementSelector":"ul", "textContent":"CN 001 · CDG → JFK" },
+            { "tagName":"li", "parentElementSelector":"ul", "textContent":"CN 003 · LHR → JFK" }
+          ]
+        }]
+      }'
+    ></sonic-sdui>
+  </template>
+</sonic-code>
+
+## Actions
+
+A node with `action: { name, context? }` makes a click on its element dispatch an `sdui-action` event from `sonic-sdui`. `detail` is `{ name, context, sourceNodeId? }`, where `sourceNodeId` is the node `nodeId`. The event bubbles and is composed, so a page shell can listen once for every node. Form posting stays with [Submit](/core/components/functional/submit).
+
+<sonic-code>
+  <template>
+    <sonic-sdui
+      id="sdui-action-example"
+      dataProvider="sdui-action-example"
+      props='{
+        "nodes":[{
+          "tagName":"sonic-button",
+          "nodeId":"check-in",
+          "textContent":"Check in",
+          "action":{ "name":"check-in", "context":{ "flight":"CN 001" } }
+        }]
+      }'
+    ></sonic-sdui>
+  </template>
+</sonic-code>
+
+<sonic-code language="typescript">
+  <template>
+document.querySelector("#sdui-action-example")?.addEventListener("sdui-action", (e) => {
+  const { name, context, sourceNodeId } = (e as CustomEvent).detail;
+});
+  </template>
+</sonic-code>
+
+## Safe profile
+
+With `profile="safe"`, the descriptor cannot inject HTML or scripts: `js` URLs are not loaded, and nodes using `markup` / `innerHTML` / `prefix` / `suffix` (directly or through their library model) are skipped with a `console.warn`. `textContent`, attributes and actions still work. Without the attribute, everything is rendered.
+
+<sonic-code>
+  <template>
+    <sonic-sdui
+      profile="safe"
+      dataProvider="sdui-safe-example"
+      props='{
+        "nodes":[
+          { "tagName":"p", "textContent":"Gate C4 · Boarding at 10:40" },
+          { "innerHTML":"&lt;b&gt;Skipped: HTML is refused&lt;/b&gt;" }
+        ]
+      }'
+    ></sonic-sdui>
+  </template>
+</sonic-code>
+
+To check a descriptor before rendering it, `validateSafeDescriptor(descriptor)` from `@supersoniks/concorde/sdui-safe` returns the violations as `{ path, field, message }[]` without side effects.
+
+## Partial rendering
+
+Declare nodes once in `nodeById` and reference them with `childNodeIds`. With the boolean `partial`, a missing id renders an empty placeholder (`data-sdui-placeholder` · `aria-hidden` · `display: contents`) so the node can arrive later. Without it, the missing child is skipped with a `console.warn`.
+
+<sonic-code>
+  <template>
+    <sonic-sdui
+      partial
+      dataProvider="sdui-partial-example"
+      props='{
+        "nodes":[{ "tagName":"div", "childNodeIds":["flight", "gate"] }],
+        "nodeById":{
+          "flight":{ "tagName":"strong", "textContent":"CN 001 · CDG → JFK" }
+        }
+      }'
+    ></sonic-sdui>
+  </template>
+</sonic-code>
+
+## Incremental updates
+
+`upsertNode` · `removeNode` · `setData` patch the rendered interface without a full rebuild, so sibling nodes keep their state (focus, input values). A node needs a `nodeId` to be updated. The first operation switches the component to incremental mode, where `props` changes are ignored until `endIncremental()`. To drive it from data, set `opsDataProvider`: each value assigned to that publisher (`SDUIOp` or `SDUIOp[]`) goes through `applyOp`.
+
+<sonic-code>
+  <template>
+    <sonic-sdui
+      id="sdui-ops-example"
+      dataProvider="sdui-ops-example"
+      props='{
+        "nodes":[
+          { "nodeId":"cn001", "tagName":"p", "textContent":"CN 001 · CDG → JFK · On time" },
+          { "nodeId":"cn003", "tagName":"p", "textContent":"CN 003 · LHR → JFK · Boarding" }
+        ]
+      }'
+    ></sonic-sdui>
+    <sonic-button size="sm" onclick="document.getElementById('sdui-ops-example').upsertNode({ nodeId: 'cn001', tagName: 'p', textContent: 'CN 001 · CDG → JFK · Delayed 20 min' })">Delay CN 001</sonic-button>
+    <sonic-button size="sm" variant="outline" onclick="document.getElementById('sdui-ops-example').removeNode('cn003')">Remove CN 003</sonic-button>
+  </template>
+</sonic-code>
+
+## Transformations
+
+The `transformation` attribute points to a JSON file applied to the descriptor before rendering. Its `library` is merged into the descriptor library; each entry of `transforms` runs an action on the nodes matching `patterns`.
+
+<sonic-code language="typescript">
+  <template>
+{
+  "transforms": [
+    { "action": "remap", "patterns": [{ "libraryKey": "textfield" }], "ui": { "tagName": "sonic-input", "attributes": { "size": "lg" } } },
+    { "action": "insert", "after": { "libraryKey": "email" }, "ui": { "tagName": "p", "textContent": "Boarding pass sent by email" } }
+  ]
+}
+  </template>
+</sonic-code>
+
+| Action | Effect |
+|--------|--------|
+| `remap` | Replaces each matched node with `ui`, keeping its attributes, content and children unless `ui` redefines them |
+| `unwrap` | Replaces each matched node with its children |
+| `wrap` | Groups the matched nodes into the `ui` node |
+| `delete` | Removes the matched nodes |
+| `insert` | Inserts `ui` relative to the node matched by `before` · `after` · `in` |
+| `move` | Moves the matched nodes next to the node matched by `before` or `after` |
+
+## Wrapped descriptor
+
+When the descriptor is one key of a larger payload, set `sduiKey` to that key. Set `messagesKey` to render the toast messages found at that key with `sonic-toast-message-subscriber` (`{ content, status, type }` items).
+
+<sonic-code>
+  <template>
+    <sonic-sdui
+      sduiKey="ui"
+      dataProvider="sdui-key-example"
+      props='{
+        "flight":"CN 001",
+        "ui":{ "nodes":[{ "tagName":"p", "textContent":"Weather warning: turbulence expected over the Atlantic" }] }
+      }'
+    ></sonic-sdui>
+  </template>
+</sonic-code>
+
+## Component catalog
+
+The package ships a JSON catalog of every custom element (`tag`; `props` with attribute / type / allowed values / default; slots and events), generated at build time for descriptor authors and tools. It has no runtime cost. Elements with thin annotations are listed in `component-catalog.gaps.json`.
+
+<sonic-code language="typescript">
+  <template>
+import catalog from "@supersoniks/concorde/sdui/component-catalog.json";
+  </template>
+</sonic-code>
+
+## Playground
+
+Edit the descriptor and leave the field to render it.
+
+<sonic-code>
+  <template>
+    <sonic-textarea
+      rows="8"
+      onChange="SonicPublisherManager.get('sdui-playground').set(JSON.parse(this.value))"
+      value='{"nodes":[{"tagName":"sonic-badge", "attributes":{"type":"success"}, "textContent":"CN 001 landed"}]}'
+    ></sonic-textarea>
+    <sonic-sdui dataProvider="sdui-playground" props='{"nodes":[{"tagName":"sonic-badge", "attributes":{"type":"success"}, "textContent":"CN 001 landed"}]}'></sonic-sdui>
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `dataProvider` | string | Publisher holding the descriptor. Required |
+| `props` | `SDUIDescriptor` (JSON) | Descriptor to render |
+| `fetch` | boolean | Loads the descriptor from `serviceURL` + `endPoint` (or `dataProvider`). Other request attributes as on [Fetch](/core/components/functional/fetch) |
+| `sduiKey` | string | Reads the descriptor from `props[sduiKey]` |
+| `messagesKey` | string | Path in `props` of the toast messages to display |
+| `profile` | `safe` | Refuses `js` / `markup` / `innerHTML` / `prefix` / `suffix`. Unset by default |
+| `partial` | boolean | Renders a placeholder for missing `childNodeIds` |
+| `library` | URL | JSON library that replaces the descriptor library |
+| `transformation` | URL | JSON transform description applied before rendering |
+| `opsDataProvider` | string | Publisher whose assigned values are passed to `applyOp` |
+
+| Descriptor key | Description |
+|----------------|-------------|
+| `nodes` | Root nodes |
+| `nodeById` | Flat registry of nodes for `childNodeIds` |
+| `library` | Node models by key, merged over the default library |
+| `js` / `css` | Script and stylesheet URLs to load (`js` refused in safe profile) |
+
+| Node field | Description |
+|------------|-------------|
+| `tagName` | Element tag (default `div`) |
+| `attributes` | Attribute name → value (objects are serialized to JSON) |
+| `nodes` | Child nodes |
+| `childNodeIds` | Child `nodeId`s resolved from `nodeById` or the tree |
+| `textContent` | Plain text. Ignored when the node has children |
+| `markup` · `innerHTML` · `prefix` · `suffix` | HTML strings (refused in safe profile) |
+| `libraryKey` | Library entry used as the model |
+| `contentElementSelector` | In a library model: where children are appended |
+| `parentElementSelector` | Appends the node to a matching element of its parent |
+| `nodeId` | Logical id for actions, `childNodeIds` and incremental updates (rendered as `data-sdui-node-id`) |
+| `action` | `{ name, context? }` dispatched as `sdui-action` on click |
+
+| Method | Description |
+|--------|-------------|
+| `upsertNode(node, parentId?, index?)` | Adds or replaces a node by `nodeId` |
+| `removeNode(nodeId)` | Removes a node |
+| `setData(path, value)` | Sets a publisher path (`form.email`), absolute or relative to `dataProvider` |
+| `applyOp(op)` | Runs an `SDUIOp`: `upsertNode` · `removeNode` · `setData` |
+| `endIncremental()` | Leaves incremental mode; the next `props` change rebuilds everything |
+
+| Event | Detail |
+|-------|--------|
+| `sdui-action` | `{ name, context, sourceNodeId? }` |
+
+No slots.

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

@@ -0,0 +1,112 @@
+# States
+
+**`sonic-states`** renders the child `<template>` whose `data-value` matches a value of its data provider. Use it to switch views on a status or a selection; point `data-path` at the value, or set `state` directly.
+
+## Basic example
+
+Each `data-value` is a RegExp tested against the value. All matching templates render; a template with `data-value=""` renders while the value is empty.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2" formDataProvider="states-flight-status">
+      <sonic-button radio name="status" value="boarding" size="xs">Boarding</sonic-button>
+      <sonic-button radio name="status" value="delayed" size="xs">Delayed</sonic-button>
+      <sonic-button radio name="status" value="landed" size="xs">Landed</sonic-button>
+    </div>
+    <div class="my-4 rounded border p-4 text-center text-2xl text-neutral-700">
+      <sonic-states dataProvider="states-flight-status" data-path="status">
+        <template data-value="">Select a status</template>
+        <template data-value="^boarding$">CN 001 is boarding at gate B12</template>
+        <template data-value="^delayed$">CN 001 is delayed by 45 minutes</template>
+        <template data-value="^landed$">CN 001 has landed at JFK</template>
+      </sonic-states>
+    </div>
+  </template>
+</sonic-code>
+
+Templates without `data-value` are ignored, and nothing renders when no template matches.
+
+## Captured values
+
+Add `dataProviderExpression` to wrap the template content in an element whose `dataProvider` is built from the value: `$1` · `$2`… for RegExp groups. Children such as [sonic-fetch](/core/components/functional/fetch) then read that provider.
+
+<sonic-code>
+  <template>
+    <div serviceURL="/docs-mock-api">
+      <div class="flex flex-wrap gap-2" formDataProvider="states-flight-pick">
+        <sonic-button radio name="flight" value="flight_001" size="xs">CN 001</sonic-button>
+        <sonic-button radio name="flight" value="flight_102" size="xs">CN 102</sonic-button>
+        <sonic-button radio name="flight" value="flight_305" size="xs">CN 305</sonic-button>
+      </div>
+      <sonic-states dataProvider="states-flight-pick" data-path="flight">
+        <template data-value="flight_(\d+)" dataProviderExpression="flights?q=$1">
+          <sonic-fetch key="flights.0"></sonic-fetch>
+          <p class="my-4">
+            <sonic-value key="code"></sonic-value> to
+            <sonic-value key="city"></sonic-value>:
+            <sonic-value key="status"></sonic-value>
+          </p>
+        </template>
+      </sonic-states>
+    </div>
+  </template>
+</sonic-code>
+
+With [url-pattern](https://www.npmjs.com/package/url-pattern) syntax, name the segments instead: `data-value="flight/:code"` and `dataProviderExpression="flights?q=:code"`.
+
+## Inverted matching
+
+With `inverted`, the value is the RegExp and each `data-value` is the tested text. Use it to show several templates at once.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2" formDataProvider="states-board-filter">
+      <sonic-button radio name="filter" value=".*" size="xs">All</sonic-button>
+      <sonic-button radio name="filter" value="delayed|cancelled" size="xs">Disrupted</sonic-button>
+      <sonic-button radio name="filter" value="on-time" size="xs">On time</sonic-button>
+    </div>
+    <sonic-states inverted dataProvider="states-board-filter" data-path="filter" class="my-4 flex flex-col gap-1">
+      <template data-value="on-time"><p>CN 014 · LHR · on time</p></template>
+      <template data-value="delayed"><p>CN 102 · GIG · delayed</p></template>
+      <template data-value="cancelled"><p>CN 305 · IAD · cancelled</p></template>
+    </sonic-states>
+  </template>
+</sonic-code>
+
+While the value is empty, every template renders.
+
+## Render functions
+
+From Lit, pass a `.states` map instead of templates: keys are RegExp or url-pattern expressions, values are render functions. RegExp groups arrive as an array, url-pattern segments as an object, and `fallback` renders when no key matches.
+
+<sonic-code language="typescript">
+  <template>
+private states = {
+  boarding: () => html`&lt;p&gt;Boarding at gate B12&lt;/p&gt;`,
+  "delayed_(\\d+)": ([minutes]) => html`&lt;p&gt;Delayed by ${minutes} min&lt;/p&gt;`,
+  "flights/:code/:status": ({ code, status }) => html`&lt;p&gt;${code}: ${status}&lt;/p&gt;`,
+  fallback: () => html`&lt;p&gt;Unknown status&lt;/p&gt;`,
+};
+
+html`&lt;sonic-states dataProvider="flight" data-path="status" .states=${this.states}&gt;&lt;/sonic-states&gt;`;
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `dataProvider` | string | Provider holding the value. Inherited from the closest ancestor when omitted |
+| `data-path` | string | Dot path of the value in the provider |
+| `state` | string | Value to match when `data-path` is not set |
+| `inverted` | boolean (default `false`) | Uses the value as the RegExp and each `data-value` as the tested text |
+| `states` | object (property) | Render functions keyed by expression, plus `fallback`. Templates are used only when nothing in the map renders |
+
+| Template attribute | Description |
+|--------------------|-------------|
+| `data-value` | RegExp or url-pattern matched against the value. `""` matches an empty value |
+| `dataProviderExpression` | Builds the `dataProvider` of a wrapper around the template content from `$1`… or `:name` |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | `<template data-value>` children |