@supersoniks/concorde 5.1.1 → 5.1.3

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

@@ -0,0 +1,51 @@
+# 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`.
+
+## Lazy load
+
+`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.
+
+<docs-lit-demo for="docs-queue-geo-demo"></docs-lit-demo>
+
+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.
+
+## Filters
+
+`dataFilterProvider` names a form store (`formDataProvider`). Each non-empty field is added to the query string; when a field changes, the queue drops the loaded batches and reloads from the first offset, after a `filterTimeoutMs` debounce (default `400`). Search a city, an airport or a flight number.
+
+<docs-lit-demo for="docs-queue-users-demo"></docs-lit-demo>
+
+To keep some form fields out of the request, list their names in `filteredFields`, separated by spaces.
+
+## API reference
+
+| Attribute | Values | Description |
+|-----------|--------|-------------|
+| `dataProviderExpression` | string (default: closest ancestor `dataProvider`) | Request path; `$offset` and `$limit` are replaced for each batch |
+| `serviceURL` | string | API base URL; inherited from the closest ancestor |
+| `key` | string | Response property that holds the rows |
+| `limit` | number (default `5`, max `15`) | Rows per batch |
+| `offset` | number (default `0`) | Offset of the first batch |
+| `idKey` | string (default `id`) | Row property used as identity |
+| `dataFilterProvider` | string | Form store whose fields are added to the query; inherited from the closest ancestor |
+| `filteredFields` | space-separated names | Form fields not sent to the API |
+| `filterTimeoutMs` | number (default `400`) | Debounce before reloading after a filter change |
+| `noLazyload` | boolean | Loads all batches without waiting for the scroll |
+| `lazyBoundsRatio` | number (default `1`) | Lazy-load margin, as a multiple of the viewport size |
+| `loader` | `inline` · `fixed` (default `inline`) | Loader shown while a batch loads |
+| `cache` | `RequestCache` (default `default`) | Fetch cache mode |
+| `invalidateOnPageShow` | boolean | Reloads batches when the page is restored from the back/forward cache |
+| `localStorage` | `disabled` · `enabled` (default `disabled`) | Forwarded to each batch list |
+| `debug` | boolean | Shows a live inspector of each batch list's data |
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `items` | `ListItems` | Row renderer |
+| `noItems` | `ListItems` | Rendered when the first batch is empty |
+| `skeleton` | `ListItems` | Rendered while a batch loads |
+| `itemPropertyMap` | object | Forwarded to each batch list |
+
+The queue publisher exposes `resultCount`, the number of rows loaded so far.
+
+No slots. `<template>` children are used as row templates for hosts without Lit; see [HTML integration](/docs/misc/html-integration).

package/docs/core/components/functional/router/router.html

@@ -0,0 +1,154 @@
+<!DOCTYPE html>
+<html lang="en" data-doc-url="https://concorde.supersoniks.org/core/components/functional/router" data-doc-id="core/components/functional/router/router">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Router — Concorde by Supersoniks</title>
+  <meta name="description" content="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 ">
+  <meta name="keywords" content="Concorde, supersoniks, core/components/functional/router/router, router, Router, functional component, sonic-router, web component, .routes, sonic-redirect, fallback, #flights/:code, { code }, basePath, , title">
+  <meta name="concorde-doc-id" content="core/components/functional/router/router">
+  <link rel="canonical" href="https://concorde.supersoniks.org/core/components/functional/router">
+  <link rel="alternate" type="text/markdown" href="https://concorde.supersoniks.org/core/components/functional/router.md">
+</head>
+<body>
+  <header>
+    <p><a href="/docs/index.html">Concorde documentation</a> · <a href="https://concorde.supersoniks.org/core/components/functional/router">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 — Router</strong>. 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  <span>Doc ID: <code>core/components/functional/router/router</code>. Keywords: Concorde, supersoniks, core/components/functional/router/router, router, Router, functional component, sonic-router, web component, .routes, sonic-redirect, fallback, #flights/:code, { code }, basePath, , title. URL: <a href="https://concorde.supersoniks.org/core/components/functional/router">https://concorde.supersoniks.org/core/components/functional/router</a>.</span></p>
+      <h1 id="router">Router</h1>
+<p><strong><code>sonic-router</code></strong> watches the location (pathname + hash) and renders the views whose route matches. From Lit, pass a <code>.routes</code> map of path patterns to render functions; use <strong><code>sonic-redirect</code></strong> to navigate when a value appears in a data provider.</p>
+<h2 id="static-routes">Static routes</h2>
+<p>Each key is tested against the pathname + hash, first as a RegExp, then as a <a href="https://www.npmjs.com/package/url-pattern">url-pattern</a>. Every matching route renders; the <code>fallback</code> key renders when none does. The demo links append a second hash so the doc page itself stays loaded.</p>
+<p><docs-lit-demo for="docs-router-basic-demo"></docs-lit-demo></p>
+<p>Set <code>.routes</code> as a <strong>property</strong> binding: render functions cannot go through an HTML attribute.</p>
+<h2 id="route-parameters">Route parameters</h2>
+<p>A url-pattern key such as <code>#flights/:code</code> passes an object (<code>{ code }</code>) to its render function. A RegExp key passes its capturing groups as an array, in order.</p>
+<p><docs-lit-demo for="docs-router-params-demo"></docs-lit-demo></p>
+<h2 id="base-path">Base path</h2>
+<p>By default, url-pattern keys accept any leading slashes and RegExp keys are not anchored. Set <code>basePath</code> to require a prefix: it is prepended to every url-pattern key, and to RegExp keys after <code>^</code>.</p>
+<pre><code class="language-html">&amp;lt;sonic-router basePath=&quot;/app&quot;&amp;gt;&amp;lt;/sonic-router&amp;gt;
+&amp;lt;!-- &quot;/fleet&quot; now matches /app/fleet only --&amp;gt;
+</code></pre>
+<h2 id="html-templates">HTML templates</h2>
+<p>Without Lit, declare <code>&lt;template data-route&gt;</code> children. A <code>title</code> attribute sets <code>document.title</code> and <code>data-fallback</code> marks the template shown when nothing matches. <code>dataProviderExpression</code> wraps the content in an element whose <code>dataProvider</code> is built from the route (<code>$1</code> or <code>:name</code>), as in <a href="/core/components/functional/states">States</a>.</p>
+<pre><code class="language-html">&amp;lt;sonic-router fallBackRoute=&quot;/departures&quot;&amp;gt;
+  &amp;lt;template data-route=&quot;/departures&quot; title=&quot;Departures&quot;&amp;gt;…&amp;lt;/template&amp;gt;
+  &amp;lt;template data-route=&quot;/flights/:code&quot; dataProviderExpression=&quot;flights/:code&quot;&amp;gt;
+    &amp;lt;sonic-value key=&quot;status&quot;&amp;gt;&amp;lt;/sonic-value&amp;gt;
+  &amp;lt;/template&amp;gt;
+&amp;lt;/sonic-router&amp;gt;
+</code></pre>
+<p><code>fallBackRoute</code> navigates to its URL when no route matches, even if a <code>data-fallback</code> template exists. A <code>routes.fallback</code> function prevents it.</p>
+<h2 id="redirect-on-data">Redirect on data</h2>
+<p><strong><code>sonic-redirect</code></strong> navigates to <code>to</code> once the value at <code>onData</code> (dot path) in its data provider is set and truthy. Here, checking in sends the passenger to the boarding page.</p>
+<pre><code class="language-html">&amp;lt;sonic-redirect to=&quot;#boarding&quot; dataProvider=&quot;checkin&quot; onData=&quot;checkedIn&quot;&amp;gt;&amp;lt;/sonic-redirect&amp;gt;
+&amp;lt;div formDataProvider=&quot;checkin&quot;&amp;gt;
+  &amp;lt;sonic-button radio name=&quot;checkedIn&quot; value=&quot;yes&quot;&amp;gt;Check in&amp;lt;/sonic-button&amp;gt;
+&amp;lt;/div&amp;gt;
+</code></pre>
+<p>Objects do not trigger the redirect: point <code>onData</code> at a scalar such as <code>passenger.id</code>.</p>
+<h2 id="api-reference">API reference</h2>
+<p><code>sonic-router</code></p>
+<table>
+<thead>
+<tr>
+<th>Attribute</th>
+<th>Values</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>routes</code></td>
+<td>object (property)</td>
+<td>Render functions keyed by RegExp or url-pattern, plus <code>fallback</code></td>
+</tr>
+<tr>
+<td><code>basePath</code></td>
+<td>string</td>
+<td>Prefix required before every route. Default: any leading slashes for url-pattern, no anchor for RegExp</td>
+</tr>
+<tr>
+<td><code>fallBackRoute</code></td>
+<td>string</td>
+<td>URL to navigate to when no route matches and <code>routes.fallback</code> is not set</td>
+</tr>
+</tbody></table>
+<table>
+<thead>
+<tr>
+<th>Template attribute</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>data-route</code></td>
+<td>RegExp or url-pattern matched against the location</td>
+</tr>
+<tr>
+<td><code>data-fallback</code></td>
+<td>Template shown when no route matches</td>
+</tr>
+<tr>
+<td><code>title</code></td>
+<td>Sets <code>document.title</code> when the template renders</td>
+</tr>
+<tr>
+<td><code>dataProviderExpression</code></td>
+<td>Builds the <code>dataProvider</code> of a wrapper around the 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-route&gt;</code> children</td>
+</tr>
+</tbody></table>
+<p><code>sonic-redirect</code></p>
+<table>
+<thead>
+<tr>
+<th>Attribute</th>
+<th>Values</th>
+<th>Description</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>to</code></td>
+<td>string</td>
+<td>Destination. A value starting with <code>#</code> only changes the hash</td>
+</tr>
+<tr>
+<td><code>dataProvider</code></td>
+<td>string</td>
+<td>Provider to watch. Inherited from the closest ancestor when omitted</td>
+</tr>
+<tr>
+<td><code>onData</code></td>
+<td>string (required)</td>
+<td>Dot path of the value that triggers the redirect when truthy</td>
+</tr>
+<tr>
+<td><code>onAdded</code></td>
+<td>boolean</td>
+<td>Redirects as soon as the element renders, without waiting for data</td>
+</tr>
+<tr>
+<td><code>pushState</code> · <code>replaceState</code></td>
+<td>boolean</td>
+<td>Navigates with <code>history.pushState</code> or <code>history.replaceState</code> instead of a full load. Ignored for <code>#</code> destinations</td>
+</tr>
+</tbody></table>
+<p>No slots.</p>
+
+    </article>
+  </main>
+</body>
+</html>

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

@@ -0,0 +1,93 @@
+# 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.
+
+## Static routes
+
+Each key is tested against the pathname + hash, first as a RegExp, then as a [url-pattern](https://www.npmjs.com/package/url-pattern). Every matching route renders; the `fallback` key renders when none does. The demo links append a second hash so the doc page itself stays loaded.
+
+<docs-lit-demo for="docs-router-basic-demo"></docs-lit-demo>
+
+Set `.routes` as a **property** binding: render functions cannot go through an HTML attribute.
+
+## Route parameters
+
+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.
+
+<docs-lit-demo for="docs-router-params-demo"></docs-lit-demo>
+
+## Base path
+
+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 `^`.
+
+<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>
+
+## HTML templates
+
+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).
+
+<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>
+
+`fallBackRoute` navigates to its URL when no route matches, even if a `data-fallback` template exists. A `routes.fallback` function prevents it.
+
+## Redirect on data
+
+**`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.
+
+<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>
+
+Objects do not trigger the redirect: point `onData` at a scalar such as `passenger.id`.
+
+## API reference
+
+`sonic-router`
+
+| 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 |
+
+| 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` |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | `<template data-route>` children |
+
+`sonic-redirect`
+
+| 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 |
+
+No slots.

package/docs/core/components/functional/sdui/sdui-extension-points.html

@@ -0,0 +1,127 @@
+<!DOCTYPE html>
+<html lang="en" data-doc-url="https://concorde.supersoniks.org/core/components/functional/sdui/sdui-extension-points" data-doc-id="core/components/functional/sdui/sdui-extension-points">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>SDUI — points d’extension publics — Concorde by Supersoniks</title>
+  <meta name="description" content="Aide-mémoire pour les dépôts externes (adaptateurs, shells).">
+  <meta name="keywords" content="Concorde, supersoniks, core/components/functional/sdui/sdui-extension-points, sdui-extension-points, SDUI — points d’extension publics, functional component, sonic-sdui-extension-points, web component, ).  
+La doc utilisateur reste , safe, html
+
+, js, markup, innerHTML, prefix, suffix, textContent, action">
+  <meta name="concorde-doc-id" content="core/components/functional/sdui/sdui-extension-points">
+  <link rel="canonical" href="https://concorde.supersoniks.org/core/components/functional/sdui/sdui-extension-points">
+  <link rel="alternate" type="text/markdown" href="https://concorde.supersoniks.org/core/components/functional/sdui/sdui-extension-points.md">
+</head>
+<body>
+  <header>
+    <p><a href="/docs/index.html">Concorde documentation</a> · <a href="https://concorde.supersoniks.org/core/components/functional/sdui/sdui-extension-points">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 — SDUI — points d’extension publics</strong>. Aide-mémoire pour les dépôts externes (adaptateurs, shells). <span>Doc ID: <code>core/components/functional/sdui/sdui-extension-points</code>. Keywords: Concorde, supersoniks, core/components/functional/sdui/sdui-extension-points, sdui-extension-points, SDUI — points d’extension publics, functional component, sonic-sdui-extension-points, web component, ).  
+La doc utilisateur reste , safe, html
+
+, js, markup, innerHTML, prefix, suffix, textContent, action. URL: <a href="https://concorde.supersoniks.org/core/components/functional/sdui/sdui-extension-points">https://concorde.supersoniks.org/core/components/functional/sdui/sdui-extension-points</a>.</span></p>
+      <h1 id="sdui--points-dextension-publics">SDUI — points d’extension publics</h1>
+<p>Aide-mémoire pour les dépôts externes (adaptateurs, shells).<br><strong>Pas une page de la doc site</strong> — à lire dans le package npm<br>(<code>node_modules/@supersoniks/concorde/src/core/components/functional/sdui/sdui-extension-points.md</code>).<br>La doc utilisateur reste <code>sdui.md</code> (auto-suffisante).</p>
+<p><strong>Aucune mention de protocoles tiers ici</strong> : uniquement les API génériques Concorde.</p>
+<h2 id="1-profil-safe-opt-in">1. Profil <code>safe</code> (opt-in)</h2>
+<pre><code class="language-html">&lt;sonic-sdui profile=&quot;safe&quot; …&gt;
+</code></pre>
+<table>
+<thead>
+<tr>
+<th>Refusé</th>
+<th>Autorisé</th>
+</tr>
+</thead>
+<tbody><tr>
+<td><code>js</code>, <code>markup</code>, <code>innerHTML</code>, <code>prefix</code>, <code>suffix</code></td>
+<td><code>textContent</code>, structure, attributs, <code>action</code>, <code>childNodeIds</code></td>
+</tr>
+</tbody></table>
+<ul>
+<li>Nœud refusé → ignoré + <code>console.warn</code> (pas de crash)</li>
+<li>Helper pur : <code>validateSafeDescriptor(descriptor)</code> depuis <code>sdui-safe</code></li>
+</ul>
+<h2 id="2-événement-sdui-action">2. Événement <code>sdui-action</code></h2>
+<p>Sur un nœud :</p>
+<pre><code class="language-json">{
+  &quot;tagName&quot;: &quot;sonic-button&quot;,
+  &quot;nodeId&quot;: &quot;confirm&quot;,
+  &quot;textContent&quot;: &quot;OK&quot;,
+  &quot;action&quot;: { &quot;name&quot;: &quot;confirm&quot;, &quot;context&quot;: { &quot;step&quot;: 1 } }
+}
+</code></pre>
+<p>Au clic, <code>sonic-sdui</code> émet :</p>
+<ul>
+<li>type : <code>sdui-action</code></li>
+<li><code>detail</code> : <code>{ name, context, sourceNodeId? }</code></li>
+<li><code>bubbles: true</code>, <code>composed: true</code></li>
+</ul>
+<p>Ne remplace pas <code>sonic-submit</code> / POST / <code>messagesKey</code>.</p>
+<h2 id="3-catalogue-de-composants-build-only">3. Catalogue de composants (build only)</h2>
+<ul>
+<li>Fichier publié : <code>component-catalog.json</code></li>
+<li>Import : <code>@supersoniks/concorde/sdui/component-catalog.json</code></li>
+<li>Régénération : <code>yarn generate:sdui-catalog</code> (aussi <code>prebuild</code>)</li>
+<li>Gaps d’annotations : <code>component-catalog.gaps.json</code></li>
+<li><strong>Aucun impact runtime</strong></li>
+</ul>
+<h2 id="4-rendu-partiel-opt-in">4. Rendu partiel (opt-in)</h2>
+<pre><code class="language-html">&lt;sonic-sdui partial …&gt;
+</code></pre>
+<ul>
+<li>Registre plat : <code>nodeById</code></li>
+<li>Enfants par id : <code>childNodeIds</code></li>
+<li>Id manquant + <code>partial</code> → placeholder (<code>data-sdui-placeholder</code>, <code>data-sdui-node-id</code>, <code>display: contents</code>)</li>
+<li>Sans <code>partial</code> → warning + skip</li>
+</ul>
+<h2 id="5-ops-incrémentales-opt-in-chemin-à-côté">5. Ops incrémentales (opt-in, chemin à côté)</h2>
+<p>Le descripteur entier + rebuild reste le chemin par défaut. Les ops mutent un descripteur local et mettent à jour le DOM <strong>chirurgicalement</strong> (frères préservés : focus, valeurs d’input, état composants).</p>
+<h3 id="méthodes-publiques-sur-sonic-sdui">Méthodes publiques sur <code>sonic-sdui</code></h3>
+<pre><code class="language-ts">upsertNode(node, parentId?, index?)  // node.nodeId requis
+removeNode(nodeId)
+setData(path, value)                 // chemin publisher, ex. &quot;form.email&quot;
+applyOp(op)                          // { op: &quot;upsertNode&quot;|&quot;removeNode&quot;|&quot;setData&quot;, … }
+endIncremental()                     // revient au mode props → rebuild
+</code></pre>
+<h3 id="flux-optionnel">Flux optionnel</h3>
+<p>Attribut <code>opsDataProvider</code> : chaque valeur assignée (<code>SDUIOp</code> ou <code>SDUIOp[]</code>) est passée à <code>applyOp</code>.</p>
+<h3 id="comportement">Comportement</h3>
+<ul>
+<li>Première op → clone local du descripteur + mode partial automatique</li>
+<li><code>data-sdui-node-id</code> marque les nœuds rendus</li>
+<li>Remplacement d’un placeholder / nœud existant via <code>replaceWith</code> (pas de <code>removeChildren</code> global)</li>
+</ul>
+<h2 id="imports-utiles">Imports utiles</h2>
+<table>
+<thead>
+<tr>
+<th>Artefact</th>
+<th>Chemin</th>
+</tr>
+</thead>
+<tbody><tr>
+<td>Composant</td>
+<td><code>@supersoniks/concorde/sdui</code></td>
+</tr>
+<tr>
+<td>Types</td>
+<td><code>…/sdui/types</code> (via package exports / short path)</td>
+</tr>
+<tr>
+<td>Safe</td>
+<td><code>@supersoniks/concorde/sdui-safe</code></td>
+</tr>
+<tr>
+<td>Catalogue</td>
+<td><code>@supersoniks/concorde/sdui/component-catalog.json</code></td>
+</tr>
+</tbody></table>
+
+    </article>
+  </main>
+</body>
+</html>

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