@supersoniks/concorde 5.1.1 → 5.1.2

package/docs/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/core/components/functional/states/states.html

@@ -0,0 +1,141 @@
+<!DOCTYPE html>
+<html lang="en" data-doc-url="https://concorde.supersoniks.org/core/components/functional/states" data-doc-id="core/components/functional/states/states">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>States — Concorde by Supersoniks</title>
+  <meta name="description" content="sonic-states renders the child &lt;template&gt; 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.">
+  <meta name="keywords" content="Concorde, supersoniks, core/components/functional/states/states, states, States, functional component, sonic-states, web component, , data-value, data-path, state, data-value=&quot;&quot;, dataProviderExpression, dataProvider">
+  <meta name="concorde-doc-id" content="core/components/functional/states/states">
+  <link rel="canonical" href="https://concorde.supersoniks.org/core/components/functional/states">
+  <link rel="alternate" type="text/markdown" href="https://concorde.supersoniks.org/core/components/functional/states.md">
+</head>
+<body>
+  <header>
+    <p><a href="/docs/index.html">Concorde documentation</a> · <a href="https://concorde.supersoniks.org/core/components/functional/states">same URL (interactive)</a> · <a href="/llms.txt">llms.txt</a></p>
+  </header>
+  <main>
+    <article>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde functional component — States</strong>. sonic-states renders the child &lt;template&gt; 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. <span>Doc ID: <code>core/components/functional/states/states</code>. Keywords: Concorde, supersoniks, core/components/functional/states/states, states, States, functional component, sonic-states, web component, , data-value, data-path, state, data-value=&quot;&quot;, dataProviderExpression, dataProvider. URL: <a href="https://concorde.supersoniks.org/core/components/functional/states">https://concorde.supersoniks.org/core/components/functional/states</a>.</span></p>
+      <h1 id="states">States</h1>
+<p><strong><code>sonic-states</code></strong> renders the child <code>&lt;template&gt;</code> whose <code>data-value</code> matches a value of its data provider. Use it to switch views on a status or a selection; point <code>data-path</code> at the value, or set <code>state</code> directly.</p>
+<h2 id="basic-example">Basic example</h2>
+<p>Each <code>data-value</code> is a RegExp tested against the value. All matching templates render; a template with <code>data-value=&quot;&quot;</code> renders while the value is empty.</p>
+<pre><code>&lt;div class=&quot;flex flex-wrap gap-2&quot; formDataProvider=&quot;states-flight-status&quot;&gt;
+      &lt;sonic-button radio name=&quot;status&quot; value=&quot;boarding&quot; size=&quot;xs&quot;&gt;Boarding&lt;/sonic-button&gt;
+      &lt;sonic-button radio name=&quot;status&quot; value=&quot;delayed&quot; size=&quot;xs&quot;&gt;Delayed&lt;/sonic-button&gt;
+      &lt;sonic-button radio name=&quot;status&quot; value=&quot;landed&quot; size=&quot;xs&quot;&gt;Landed&lt;/sonic-button&gt;
+    &lt;/div&gt;
+    &lt;div class=&quot;my-4 rounded border p-4 text-center text-2xl text-neutral-700&quot;&gt;
+      &lt;sonic-states dataProvider=&quot;states-flight-status&quot; data-path=&quot;status&quot;&gt;
+        &lt;template data-value=&quot;&quot;&gt;Select a status
+</code></pre>
+<p>Templates without <code>data-value</code> are ignored, and nothing renders when no template matches.</p>
+<h2 id="captured-values">Captured values</h2>
+<p>Add <code>dataProviderExpression</code> to wrap the template content in an element whose <code>dataProvider</code> is built from the value: <code>$1</code> · <code>$2</code>… for RegExp groups. Children such as <a href="/core/components/functional/fetch">sonic-fetch</a> then read that provider.</p>
+<pre><code>&lt;div serviceURL=&quot;/docs-mock-api&quot;&gt;
+      &lt;div class=&quot;flex flex-wrap gap-2&quot; formDataProvider=&quot;states-flight-pick&quot;&gt;
+        &lt;sonic-button radio name=&quot;flight&quot; value=&quot;flight_001&quot; size=&quot;xs&quot;&gt;CN 001&lt;/sonic-button&gt;
+        &lt;sonic-button radio name=&quot;flight&quot; value=&quot;flight_102&quot; size=&quot;xs&quot;&gt;CN 102&lt;/sonic-button&gt;
+        &lt;sonic-button radio name=&quot;flight&quot; value=&quot;flight_305&quot; size=&quot;xs&quot;&gt;CN 305&lt;/sonic-button&gt;
+      &lt;/div&gt;
+      &lt;sonic-states dataProvider=&quot;states-flight-pick&quot; data-path=&quot;flight&quot;&gt;
+        &lt;template data-value=&quot;flight_(\d+)&quot; dataProviderExpression=&quot;flights?q=$1&quot;&gt;
+          &lt;sonic-fetch key=&quot;flights.0&quot;&gt;&lt;/sonic-fetch&gt;
+          &lt;p class=&quot;my-4&quot;&gt;
+            &lt;sonic-value key=&quot;code&quot;&gt;&lt;/sonic-value&gt; to
+            &lt;sonic-value key=&quot;city&quot;&gt;&lt;/sonic-value&gt;:
+            &lt;sonic-value key=&quot;status&quot;&gt;&lt;/sonic-value&gt;
+          &lt;/p&gt;
+</code></pre>
+<p>With <a href="https://www.npmjs.com/package/url-pattern">url-pattern</a> syntax, name the segments instead: <code>data-value=&quot;flight/:code&quot;</code> and <code>dataProviderExpression=&quot;flights?q=:code&quot;</code>.</p>
+<h2 id="inverted-matching">Inverted matching</h2>
+<p>With <code>inverted</code>, the value is the RegExp and each <code>data-value</code> is the tested text. Use it to show several templates at once.</p>
+<pre><code>&lt;div class=&quot;flex flex-wrap gap-2&quot; formDataProvider=&quot;states-board-filter&quot;&gt;
+      &lt;sonic-button radio name=&quot;filter&quot; value=&quot;.*&quot; size=&quot;xs&quot;&gt;All&lt;/sonic-button&gt;
+      &lt;sonic-button radio name=&quot;filter&quot; value=&quot;delayed|cancelled&quot; size=&quot;xs&quot;&gt;Disrupted&lt;/sonic-button&gt;
+      &lt;sonic-button radio name=&quot;filter&quot; value=&quot;on-time&quot; size=&quot;xs&quot;&gt;On time&lt;/sonic-button&gt;
+    &lt;/div&gt;
+    &lt;sonic-states inverted dataProvider=&quot;states-board-filter&quot; data-path=&quot;filter&quot; class=&quot;my-4 flex flex-col gap-1&quot;&gt;
+      &lt;template data-value=&quot;on-time&quot;&gt;&lt;p&gt;CN 014 · LHR · on time&lt;/p&gt;
+</code></pre>
+<p>While the value is empty, every template renders.</p>
+<h2 id="render-functions">Render functions</h2>
+<p>From Lit, pass a <code>.states</code> 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 <code>fallback</code> renders when no key matches.</p>
+<pre><code class="language-typescript">private states = {
+  boarding: () =&gt; html`&amp;lt;p&amp;gt;Boarding at gate B12&amp;lt;/p&amp;gt;`,
+  &quot;delayed_(\\d+)&quot;: ([minutes]) =&gt; html`&amp;lt;p&amp;gt;Delayed by ${minutes} min&amp;lt;/p&amp;gt;`,
+  &quot;flights/:code/:status&quot;: ({ code, status }) =&gt; html`&amp;lt;p&amp;gt;${code}: ${status}&amp;lt;/p&amp;gt;`,
+  fallback: () =&gt; html`&amp;lt;p&amp;gt;Unknown status&amp;lt;/p&amp;gt;`,
+};
+
+html`&amp;lt;sonic-states dataProvider=&quot;flight&quot; data-path=&quot;status&quot; .states=${this.states}&amp;gt;&amp;lt;/sonic-states&amp;gt;`;
+</code></pre>
+<h2 id="api-reference">API reference</h2>
+<table>
+<thead>
+<tr>
+<th>Attribute</th>
+<th>Values</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>dataProvider</code></td>
+<td>string</td>
+<td>Provider holding the value. Inherited from the closest ancestor when omitted</td>
+</tr>
+<tr>
+<td><code>data-path</code></td>
+<td>string</td>
+<td>Dot path of the value in the provider</td>
+</tr>
+<tr>
+<td><code>state</code></td>
+<td>string</td>
+<td>Value to match when <code>data-path</code> is not set</td>
+</tr>
+<tr>
+<td><code>inverted</code></td>
+<td>boolean (default <code>false</code>)</td>
+<td>Uses the value as the RegExp and each <code>data-value</code> as the tested text</td>
+</tr>
+<tr>
+<td><code>states</code></td>
+<td>object (property)</td>
+<td>Render functions keyed by expression, plus <code>fallback</code>. Templates are used only when nothing in the map renders</td>
+</tr>
+</tbody></table>
+<table>
+<thead>
+<tr>
+<th>Template attribute</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>data-value</code></td>
+<td>RegExp or url-pattern matched against the value. <code>&quot;&quot;</code> matches an empty value</td>
+</tr>
+<tr>
+<td><code>dataProviderExpression</code></td>
+<td>Builds the <code>dataProvider</code> of a wrapper around the template content from <code>$1</code>… or <code>:name</code></td>
+</tr>
+</tbody></table>
+<table>
+<thead>
+<tr>
+<th>Slot</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><em>(default)</em></td>
+<td><code>&lt;template data-value&gt;</code> children</td>
+</tr>
+</tbody></table>
+
+    </article>
+  </main>
+</body>
+</html>

package/docs/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 |