@supersoniks/concorde 5.1.1 → 5.1.3

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

@@ -1,281 +1,98 @@
 # SDUI
 
-## What is 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.
 
-SDUI stands for `Server Driven User Interfaces`.
-Basically, it generates a user interface based on a JSON SDUI Descriptor.
+## Basic example
 
-### Subscriber extension:
-
-SDUI extends the mixin [Subscriber](#docs/_core-concept/subscriber.md/subscriber).
-This means that you must set a dataProvider with an id pointing to the publisher that will hold your SDUI Descriptor.
-This also means that it has a reactive property named `props` that you can set with the JSON SDUI Descriptor in order to configure it.
-
-### Fetcher extension:
-
-SDUI extends the mixin Fetcher as [Fetch](#core/components/functional/fetch/fetch.md/fetch) and [List](#core/components/functional/list/list.md/list).
-
-In this case, it will parse the JSON coming from the request.
-The JSON must comply with the SDUI descriptor format.
-
-As a fetcher, invalidating the publisher or updating the endpoint will trigger a new fetch and update accordingly.
-
-### Rendering:
-
-It has no shadowdom, and its display style is set to `contents`, so an empty SDUI has the fewest impact on the layout.
-
-### Safe profile (opt-in)
-
-Set `profile="safe"` on `sonic-sdui` to refuse untrusted HTML/JS from the descriptor:
-
-* `js` URLs are **not** loaded
-* nodes that use `markup`, `innerHTML`, `prefix`, or `suffix` are **skipped** (not rendered)
-* `textContent` is **allowed** (plain text, no HTML parsing)
-* a clear `console.warn` is emitted for each refusal
-* without the attribute, behaviour is unchanged
-
-Use the pure helper `validateSafeDescriptor(descriptor)` (from `sdui-safe`) to list violations server-side or in a custom validator — it returns `{ path, field, message }[]` and has no side effects.
+Each entry of `nodes` becomes an element: `tagName` (default `div`) · `attributes` · `textContent` · nested `nodes`.
 
 <sonic-code>
   <template>
     <sonic-sdui
-      profile="safe"
-      dataProvider="sdui-safe-example"
+      dataProvider="sdui-basic-example"
       props='{
-        "nodes":[
-          { "tagName":"p", "textContent":"Plain text is fine" },
-          { "innerHTML":"&lt;script&gt;/* refused */&lt;/script&gt;" }
-        ]
+        "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>
 
-### Component catalog (build-only)
+## Fetching a descriptor
 
-At build time, Concorde generates a **neutral JSON catalog** of custom elements for SDUI / external agents:
-
-* file: `src/core/components/functional/sdui/component-catalog.json`
-* import: `@supersoniks/concorde/sdui/component-catalog.json` (or the long `core/components/functional/sdui/…` path)
-* regenerate: `yarn generate:sdui-catalog` (also runs in `prebuild`)
-* source: Custom Elements Manifest via `@custom-elements-manifest/analyzer` (Lit)
-* no runtime impact
-
-Each entry includes `tag`, `props` (name, attribute, type, allowed `values` when detectable, `default`, description), plus slots/events when present.
-
-Components with thin JSDoc are listed in `component-catalog.gaps.json` (same folder) — annotations are **not** mass-rewritten in this step.
-
-### Incremental operations (opt-in)
-
-Beside the full-descriptor rebuild path, `sonic-sdui` exposes surgical ops (siblings keep DOM state):
-
-* `upsertNode(node, parentId?, index?)` — `node.nodeId` required
-* `removeNode(nodeId)`
-* `setData(path, value)` — updates a publisher path (`form.email` or `provider.nested`)
-* `applyOp(op)` / optional `opsDataProvider` for a stream of `SDUIOp`
-* `endIncremental()` — return to props → full rebuild
-
-Public extension surface (also covered above): `profile="safe"`, `textContent`, `sdui-action` / `action`, component catalog JSON, `partial` + `childNodeIds` / `nodeById`, and these incremental ops.
-
-### Partial rendering (opt-in)
-
-Set the boolean attribute `partial` on `sonic-sdui` to tolerate missing child references:
-
-* Declare a flat registry with `nodeById` and point to children with `childNodeIds: ["a", "b"]`
-* If a `childNodeId` is **missing** and `partial` is set → a light placeholder is inserted  
-  (`data-sdui-placeholder`, `data-node-id`, `display: contents`, `aria-hidden`)
-* If `partial` is **not** set → `console.warn` and the missing child is skipped (no crash)
-* Nested `nodes` arrays keep working as before; without `childNodeIds` / `partial`, behaviour is unchanged
-* Incremental ops (later) reuse the same placeholder path
+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
-      partial
-      dataProvider="sdui-partial-example"
-      props='{
-        "nodes":[{
-          "tagName":"div",
-          "childNodeIds":["title", "body"]
-        }],
-        "nodeById":{
-          "title":{ "nodeId":"title", "tagName":"h2", "textContent":"Hello" }
-        }
-      }'
-    ></sonic-sdui>
+    <sonic-sdui fetch dataProvider="sdui-fetch-example" endPoint="/src/core/components/functional/sdui/example.json"></sonic-sdui>
   </template>
 </sonic-code>
 
-### Actions (`sdui-action`)
-
-Declarative opt-in on a node: set `action: { name, context? }` (and optionally `nodeId`).
-A click on the rendered element dispatches a `CustomEvent` named **`sdui-action`** on `sonic-sdui` with:
-
-* `detail: { name, context, sourceNodeId? }`
-* `bubbles: true`, `composed: true` — so a host (page shell, parent) can listen without binding each node
+## HTML content
 
-This does **not** replace form submit (`sonic-submit` / POST / `messagesKey`). Those keep working as before; only nodes that declare `action` emit `sdui-action`.
+`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-action-example"
+      dataProvider="sdui-html-example"
       props='{
-        "nodes":[{
-          "tagName":"sonic-button",
-          "nodeId":"confirm-btn",
-          "textContent":"Confirm",
-          "action":{ "name":"confirm", "context":{ "step":1 } }
-        }]
+        "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>
-    <script type="module">
-      document.querySelector("sonic-sdui")?.addEventListener("sdui-action", (e) => {
-        console.log(e.detail); // { name, context, sourceNodeId }
-      });
-    </script>
-  </template>
-</sonic-code>
-
-## SDUI descriptor
-
-### TypeScript definition:
-<sonic-code language="typescript">
-  <template>
-    export type SDUIDescriptor = {
-      js?: Array&lt;string&gt;;
-      css?: Array&lt;string&gt;;
-      library?: Record&lt;string, SDUINode&gt;;
-      nodes?: Array&lt;SDUINode&gt;;
-      nodeById?: Record&lt;string, SDUINode&gt;;
-    };
   </template>
 </sonic-code>
 
-### Meaning of the keys:
+## Library
 
-* **js**: An array of URLs pointing to JavaScript files to load.
-* **css**: An array of URLs pointing to CSS files to load.
-* **library**: A record of SDUINode definitions intended to be used as a model for other nodes. The keys of the record can be used as the libraryKey of the node. This node will then specialize the model with its own descriptor.
-* **nodes**: An array of SDUINode descriptors. Each SDUINode will result in an HTMLElement added to the root of the component.
-* **nodeById**: Optional flat map of nodes by `nodeId`, used with `childNodeIds` for partial / incremental graphs.
-
-## SDUINode
-
-### Descriptor
-
-An SDUINode represents an HTMLElement.
-
-TypeScript definition:
-
-<sonic-code language="typescript">
-  <template>
-    export type SDUINode = {
-      markup?: string;
-      tagName?: string;
-      attributes?: Record&lt;string, string&gt;;
-      nodes?: Array&lt;SDUINode&gt;;
-      textContent?: string;
-      innerHTML?: string;
-      prefix?: string;
-      suffix?: string;
-      libraryKey?: string;
-      contentElementSelector?: string;
-      parentElementSelector?: string;
-      action?: { name: string; context?: Record&lt;string, unknown&gt; };
-      nodeId?: string;
-    };
-  </template>
-</sonic-code>
-
-Summary of properties:
-* **markup**: Use it if you prefer to define your node entirely using an HTML string.
-* **tagName**: The tag name of the HTML element.
-* **attributes**: A string key/value pair storing each attribute name/value of the HTML element created.
-* **nodes**: An array of SDUINode descriptors. The children of the HTMLElement are created this way.
-* **textContent**: Plain text for the node (no HTML parsing). Preferred for safe UIs; ignored when `nodes` is non-empty. Allowed with `profile="safe"`.
-* **innerHTML**: The inner HTML of the current node is defined here if needed.
-* **prefix**: Use it if you want to wrap the component with some HTML string in conjunction with the suffix.
-* **suffix**: Use it if you want to wrap the component with some HTML string in conjunction with the prefix.
-* **libraryKey**: An identifier that points to an SDUINode to be used as a model for this node.
-* **contentElementSelector**: For SDUINodes defined in the library only. It is a CSS selector that defines where child nodes are added.
-* **parentElementSelector**: If the current node, as a future child, has a `parentElementSelector` attribute, it is added to the node corresponding to the associated CSS selector rather than directly to the element.
-* **action**: Optional `{ name, context? }`. Click emits `sdui-action` (see above).
-* **nodeId**: Optional logical id (not the DOM `id` attribute). Copied into `sdui-action.detail.sourceNodeId` when set.
-* **childNodeIds**: Optional list of `nodeId`s to append as children (from `nodeById` / tree index). See Partial rendering.
-
-### Markup
-Use it if you prefer to define your node entirely using an HTML string.
+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-markup-example" 
-      props='{
-          "nodes":[
-            {
-              "markup":"keep shouting <sonic-badge>foo</sonic-badge> <sonic-badge>bar</sonic-badge> !"
-            }
-          ]}'
-    ></sonic-sdui>
-  </template>
-</sonic-code>
-
-### Tag name
-Here we use the field `tagName` of SDUINode to create an element with tag name `sonic-input`.
-
-<sonic-code>
-  <template>
-    <sonic-sdui 
-      dataProvider="sdui-tagName-example" 
-      props='{
-          "nodes":[
-            {
-              "tagName":"sonic-input"
-            }
-          ]}'
-    ></sonic-sdui>
-  </template>
-</sonic-code>
-
-### Attributes
-A string key/value pair storing each attribute name/value of the HTML element created.
-As no tag name is defined, a div element is created.
-Here we define the style attribute to create a tiny red square.
-
-<sonic-code>
-  <template>
-    <sonic-sdui 
-      dataProvider="sdui-attributes-example" 
+    <sonic-sdui
+      dataProvider="sdui-library-example"
       props='{
-        "nodes":[{
-          "attributes":{
-            "style":"width:50px;height:10px;background:red;"
+        "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>
 
-### Nodes
-Children of the current node can be added using the field `nodes` recursively.
+## 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-nodes-example" 
+    <sonic-sdui
+      dataProvider="sdui-parent-selector-example"
       props='{
         "nodes":[{
           "nodes":[
-            {"innerHTML":"A"},
-            {
-              "prefix":"B",
-              "nodes":[
-                {"innerHTML":"👉 B.1"},
-                {"innerHTML":"👉 B.2"}
-              ]
-            }
+            { "tagName":"strong", "textContent":"Departures" },
+            { "tagName":"ul" },
+            { "tagName":"li", "parentElementSelector":"ul", "textContent":"CN 001 · CDG → JFK" },
+            { "tagName":"li", "parentElementSelector":"ul", "textContent":"CN 003 · LHR → JFK" }
           ]
         }]
       }'
@@ -283,196 +100,208 @@ Children of the current node can be added using the field `nodes` recursively.
   </template>
 </sonic-code>
 
-### InnerHTML
-As no tag name is defined, a div element is created, and then we use `innerHTML` to add content to it.
+## 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 
-      dataProvider="sdui-html-example" 
+    <sonic-sdui
+      id="sdui-action-example"
+      dataProvider="sdui-action-example"
       props='{
         "nodes":[{
-          "innerHTML":"keep shouting <sonic-badge>foo</sonic-badge> <sonic-badge>bar</sonic-badge> !"
+          "tagName":"sonic-button",
+          "nodeId":"check-in",
+          "textContent":"Check in",
+          "action":{ "name":"check-in", "context":{ "flight":"CN 001" } }
         }]
       }'
     ></sonic-sdui>
   </template>
 </sonic-code>
 
-### Prefix and suffix
-Use them if you want to wrap the component with some HTML string.
-
-<sonic-code>
+<sonic-code language="typescript">
   <template>
-    <sonic-sdui 
-      dataProvider="sdui-prefixSuffix-example" 
-      props='{
-        "nodes":[{
-          "prefix":"👇",
-          "suffix":"☝️",
-          "innerHTML":"The node content"
-        }]
-      }'
-    ></sonic-sdui>
+document.querySelector("#sdui-action-example")?.addEventListener("sdui-action", (e) => {
+  const { name, context, sourceNodeId } = (e as CustomEvent).detail;
+});
   </template>
 </sonic-code>
 
-### Library key and contentElementSelector
-The libraryKey of SDUINode is an identifier that points to an SDUINode description in the library to be used as a model for this node.
-
-Note that the SDUI has a default library containing some basic component definitions useful for form declaration (see default-library.json).
-
-This example uses the library key `submit` which points to a `sonic-submit` containing a button also coming from the library.
+## Safe profile
 
-The element named `button` in the library is a `sonic-button` of type `success` containing a check icon as a prefix.
-
-Since the `submit` library element contains an attribute `contentElementSelector` with the value `sonic-button`, the "injected content" is put inside the button.
-
-We used `innerHTML` for the sake of simplicity, but you can use nodes to add any complex content.
+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 dataProvider="sdui-library-example" props='
-          {
-            "nodes":[
-              {
-                "libraryKey":"submit",
-                "innerHTML":"Injected content"
-              }
-            ]
-          }
-    '></sonic-sdui>
+    <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>
 
-### parentElementSelector
+To check a descriptor before rendering it, `validateSafeDescriptor(descriptor)` from `@supersoniks/concorde/sdui-safe` returns the violations as `{ path, field, message }[]` without side effects.
 
-This special field lets you inject the content at any place in the HTML flow already set inside the parent SDUI component by using a CSS selector.
+## Partial rendering
 
-⚠️ Note that it doesn't work with top-level nodes.
+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 dataProvider="sdui-parentElementSelector-example" props='
-          {
-            "nodes":[
-              {
-                "nodes":[
-                  {
-                    "prefix":"👇 Selected parent element",
-                    "suffix":"☝️ End of selected parent element",
-                    "tagName":"span"
-                  },
-                  {
-                    "parentElementSelector":"span",
-                    "innerHTML":"Content having a parentElementSelector attribute"
-                  }
-                ]
-              }
-            ]
-          }
-    '></sonic-sdui>
+    <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>
 
-### Fetch example:
+## 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 dataProvider="sdui-fetch-example" endPoint="/src/core/components/functional/sdui/example.json"></sonic-sdui>
+    <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>
 
-## Transformers:
+## Transformations
 
-The transformers let you transform the structure of the SDUI Descriptor into a new one before parsing and rendering it.
-
-To enable it, you must fill the `transformation` attribute of the component with a URL pointing to a Transform descriptor.
+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>
-  export type SDUITransformDescription = {
-    library?: Record&lt;string, SDUINode&gt;;
-    transforms: Array&lt;SDUITransformAction&gt;;
-  };
+{
+  "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>
 
-### The library:
-
-Each key of the library will be merged with the current library in the SDUI Descriptor, by replacing or creating items library key by key.
-
-### The transform actions:
-
-Each transform represents an action that will be done on the SDUI descriptor before the creation of the entire UI.
+| 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` |
 
-<sonic-code language="typescript">
-  <template>
-export type SDUITransformAction = {
-  action: SDUITransformActionName;
-  patterns?: Array&lt;SDUINode&gt;;
-  after?: SDUINode;
-  before?: SDUINode;
-  in?: SDUINode;
-  ui?: SDUINode;
-};
-  </template>
-</sonic-code>
+## Wrapped descriptor
 
-The action that will be done is a verb:
+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 language="typescript">
+<sonic-code>
   <template>
-export type SDUITransformActionName = "remap" | "unwrap" | "wrap" | "delete" | "insert" | "move";
+    <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>
 
-* **remap**: The properties (tagName, innerHTML, etc.) of the targeted SDUINode will be created/changed according to their presence in the `ui` (SDUINode) property of the transformAction.
-* **unwrap**: Replaces the targeted SDUINode in place with its children.
-* **wrap**: Groups all SDUINodes targeted by the patterns into the new SDUINode described in the `ui` prop of the transformAction.
-* **delete**: Deletes the targeted item.
-* **insert**: Inserts a new SDUINode described by the `ui` prop into the flow. The position of insertion depends on the presence of the attributes `before`, `after`, `in`, which is a pattern to target an existing SDUINode.
+## Component catalog
 
-## Misc Tricks:
+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`.
 
-### sduiKey
-
-This is an HTML attribute to set on the component if needed. In this case, the component will not treat its props value directly as an SDUI descriptor. Internally, it will basically extract the SDUIDescriptor by doing something like this: `const sduiDescriptor = this.props[this.sduikey]`.
-
-### messageKey
-
-This is an HTML attribute to set on the component if needed. In this case, the component will automatically create a `sonic-toast-message-subscriber` component. The data found in `props[messageKey]` will be treated as the data expected by the `sonic-toast-message-subscriber`. So, by respecting the format of data supported by this component, you will be able to show multiple toasts in the result of a request.
-
-Example of JSON with `messageKey`=`messages`:
 <sonic-code language="typescript">
   <template>
-{
-  "messages": [{
-    "content": "The product has been added to your cart", 
-    "status": "success", 
-    "type": "public"
-  }]
-}
+import catalog from "@supersoniks/concorde/sdui/component-catalog.json";
   </template>
 </sonic-code>
 
-### library
-
-This is an HTML attribute to set on the component if needed. You can set a URL pointing to a JSON describing a library with the same structure as the library in the SDUIDescriptor. The component will simply override its library with the given one.
-
 ## Playground
 
-Here is a little playground to let you test some simple tricks.
+Edit the descriptor and leave the field to render it.
 
 <sonic-code>
   <template>
-    <sonic-textarea 
-    rows="10" 
-    onChange="SonicPublisherManager.get('sdui-playground').set(JSON.parse(this.value))" 
-    value='{"nodes":[{"tagName":"div", "innerHTML":"test"}]}'
-    >
-    </sonic-textarea>
-    <sonic-sdui dataProvider="sdui-playground" props='{"nodes":[{"tagName":"div", "innerHTML":"test"}]}'>
-    </sonic-sdui>
+    <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.