@supersoniks/concorde 5.0.5 → 5.1.1

package/src/core/components/functional/sdui/sdui-safe.spec.ts

@@ -0,0 +1,188 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import TestUtils from "@supersoniks/concorde/test-utils/TestUtils";
+import {
+  markupAndInnerHTML,
+  prefixSuffix,
+  layoutSafe,
+} from "./__fixtures__/descriptors";
+import { snapshotLightDom } from "./sdui-dom-snapshot";
+import {
+  validateSafeDescriptor,
+  isUnsafeSduiNode,
+} from "./sdui-safe";
+import type { SDUIDescriptor } from "./types";
+import "./sdui";
+import type { SonicSDUI } from "./sdui";
+
+function clone<T>(value: T): T {
+  return structuredClone(value);
+}
+
+async function flushSdui(elt: SonicSDUI) {
+  await elt.updateComplete;
+  await Promise.resolve();
+  await Promise.resolve();
+  await elt.updateComplete;
+}
+
+async function render(
+  descriptor: SDUIDescriptor,
+  attrs: Record<string, string> = {}
+): Promise<SonicSDUI> {
+  const attrStr = Object.entries(attrs)
+    .map(([k, v]) => `${k}="${v}"`)
+    .join(" ");
+  const [elt] = TestUtils.bootstrap(
+    `<sonic-sdui ${attrStr}></sonic-sdui>`
+  ) as unknown as SonicSDUI[];
+  elt.props = clone(descriptor) as never;
+  await flushSdui(elt);
+  return elt;
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  vi.restoreAllMocks();
+});
+
+describe("validateSafeDescriptor", () => {
+  it("ne signale rien sur un descripteur sans HTML/JS libre", () => {
+    expect(validateSafeDescriptor(layoutSafe)).toEqual([]);
+  });
+
+  it("signale js, markup, innerHTML, prefix, suffix", () => {
+    const descriptor: SDUIDescriptor = {
+      js: ["https://example.test/x.js"],
+      library: {
+        bad: { markup: "<b>x</b>" },
+      },
+      nodes: [
+        { innerHTML: "a" },
+        { prefix: "p", suffix: "s", tagName: "div" },
+        {
+          tagName: "div",
+          nodes: [{ markup: "<i>nested</i>" }],
+        },
+      ],
+    };
+    const violations = validateSafeDescriptor(descriptor);
+    expect(violations.map((v) => v.path).sort()).toEqual(
+      [
+        "js",
+        "library.bad.markup",
+        "nodes[0].innerHTML",
+        "nodes[1].prefix",
+        "nodes[1].suffix",
+        "nodes[2].nodes[0].markup",
+      ].sort()
+    );
+  });
+
+  it("isUnsafeSduiNode ne regarde que le nœud courant", () => {
+    expect(isUnsafeSduiNode({ tagName: "div", nodes: [{ innerHTML: "x" }] })).toBe(
+      false
+    );
+    expect(isUnsafeSduiNode({ innerHTML: "x" })).toBe(true);
+  });
+});
+
+describe('sonic-sdui profile="safe"', () => {
+  it("sans profile, markup/innerHTML restent rendus (comportement historique)", async () => {
+    const elt = await render(markupAndInnerHTML);
+    const snap = snapshotLightDom(elt);
+    expect(JSON.stringify(snap)).toContain("badge");
+    expect(JSON.stringify(snap)).toContain("gras");
+  });
+
+  it("ignore les nœuds markup/innerHTML avec un warning", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const elt = await render(markupAndInnerHTML, { profile: "safe" });
+    const snap = snapshotLightDom(elt);
+    // Seul le toast subscriber reste
+    expect(snap).toEqual([{ tag: "sonic-toast-message-subscriber" }]);
+    expect(warn).toHaveBeenCalled();
+    expect(
+      warn.mock.calls.some((c) => String(c[0]).includes('profile="safe"'))
+    ).toBe(true);
+  });
+
+  it("ignore prefix/suffix", async () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    const elt = await render(prefixSuffix, { profile: "safe" });
+    expect(snapshotLightDom(elt)).toEqual([
+      { tag: "sonic-toast-message-subscriber" },
+    ]);
+  });
+
+  it("laisse passer un layout sans HTML libre", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const elt = await render(layoutSafe, { profile: "safe" });
+    const snap = snapshotLightDom(elt);
+    expect(JSON.stringify(snap)).toContain("sdui-layout");
+    expect(JSON.stringify(snap)).toContain("sonic-input");
+    expect(JSON.stringify(snap)).toContain("Email");
+    expect(JSON.stringify(snap)).toContain("Titre safe");
+    expect(JSON.stringify(snap)).toContain("Go");
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it("rend textContent en plain text (pas de HTML)", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const elt = await render(
+      {
+        nodes: [
+          {
+            tagName: "p",
+            textContent: "<b>not bold</b> & still text",
+          },
+        ],
+      },
+      { profile: "safe" }
+    );
+    const p = elt.querySelector("p");
+    expect(p?.textContent).toBe("<b>not bold</b> & still text");
+    expect(p?.querySelector("b")).toBeNull();
+    expect(warn).not.toHaveBeenCalled();
+  });
+
+  it("n'appelle pas loadJS pour descriptor.js", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const append = vi.spyOn(document.head, "appendChild");
+    await render(
+      { js: ["https://example.test/unsafe.js"], nodes: [{ tagName: "div" }] },
+      { profile: "safe" }
+    );
+    const scriptAppends = append.mock.calls.filter((c) => {
+      const n = c[0] as Node;
+      return n && (n as HTMLElement).tagName === "SCRIPT";
+    });
+    expect(scriptAppends).toHaveLength(0);
+    expect(
+      warn.mock.calls.some((c) => String(c[0]).includes("chargement js ignoré"))
+    ).toBe(true);
+  });
+
+  it("ignore un enfant dangereux sans casser le parent", async () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    const elt = await render(
+      {
+        nodes: [
+          {
+            tagName: "div",
+            attributes: { class: "parent" },
+            nodes: [
+              { tagName: "span", attributes: { class: "ok" }, nodes: [] },
+              { innerHTML: "<img src=x onerror=alert(1)>" },
+            ],
+          },
+        ],
+      },
+      { profile: "safe" }
+    );
+    const html = JSON.stringify(snapshotLightDom(elt));
+    expect(html).toContain('"class":"parent"');
+    expect(html).toContain('"class":"ok"');
+    expect(html).not.toContain("onerror");
+    expect(html).not.toContain("img");
+  });
+});

package/src/core/components/functional/sdui/sdui-safe.ts

@@ -0,0 +1,100 @@
+import type { SDUIDescriptor, SDUINode } from "./types";
+
+/** Champs de nœud refusés en profil safe (injection HTML / scripts). */
+export const SAFE_FORBIDDEN_NODE_FIELDS = [
+  "markup",
+  "innerHTML",
+  "prefix",
+  "suffix",
+] as const;
+
+export type SafeForbiddenNodeField = (typeof SAFE_FORBIDDEN_NODE_FIELDS)[number];
+
+export type SafeDescriptorViolation = {
+  /** Chemin JSON-like, ex. `js`, `nodes[0].markup`, `library.card.innerHTML` */
+  path: string;
+  /** Champ en cause */
+  field: "js" | SafeForbiddenNodeField;
+  /** Message lisible */
+  message: string;
+};
+
+function nodeForbiddenFields(node: SDUINode): SafeForbiddenNodeField[] {
+  const found: SafeForbiddenNodeField[] = [];
+  for (const field of SAFE_FORBIDDEN_NODE_FIELDS) {
+    const value = node[field];
+    if (value != null && value !== "") found.push(field);
+  }
+  return found;
+}
+
+function collectNodeViolations(
+  node: SDUINode,
+  path: string,
+  out: SafeDescriptorViolation[]
+) {
+  const fields = nodeForbiddenFields(node);
+  for (const field of fields) {
+    out.push({
+      path: `${path}.${field}`,
+      field,
+      message: `Champ "${field}" interdit en profil safe (${path}).`,
+    });
+  }
+  if (node.nodes) {
+    node.nodes.forEach((child, i) => {
+      collectNodeViolations(child, `${path}.nodes[${i}]`, out);
+    });
+  }
+}
+
+/**
+ * Valide un descripteur SDUI pour le profil `safe`.
+ * Fonction pure : aucun effet de bord, réutilisable côté serveur.
+ */
+export function validateSafeDescriptor(
+  descriptor: SDUIDescriptor | null | undefined
+): SafeDescriptorViolation[] {
+  const violations: SafeDescriptorViolation[] = [];
+  if (!descriptor) return violations;
+
+  if (descriptor.js && descriptor.js.length > 0) {
+    violations.push({
+      path: "js",
+      field: "js",
+      message: `Chargement de scripts (js) interdit en profil safe (${descriptor.js.length} URL).`,
+    });
+  }
+
+  if (descriptor.library) {
+    for (const key of Object.keys(descriptor.library)) {
+      collectNodeViolations(
+        descriptor.library[key],
+        `library.${key}`,
+        violations
+      );
+    }
+  }
+
+  if (descriptor.nodes) {
+    descriptor.nodes.forEach((node, i) => {
+      collectNodeViolations(node, `nodes[${i}]`, violations);
+    });
+  }
+
+  return violations;
+}
+
+/** True si le nœud lui-même (pas ses enfants) porte un champ interdit. */
+export function isUnsafeSduiNode(node: SDUINode): boolean {
+  return nodeForbiddenFields(node).length > 0;
+}
+
+export function formatSafeNodeWarning(path: string, node: SDUINode): string {
+  const fields = nodeForbiddenFields(node);
+  return `sonic-sdui (profile="safe") : nœud ignoré (${path}) — champs refusés : ${fields.join(", ")}`;
+}
+
+export function formatSafeJsWarning(urls: string[]): string {
+  return `sonic-sdui (profile="safe") : chargement js ignoré (${urls.length} URL) — ${urls.join(", ")}`;
+}

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

@@ -24,6 +24,119 @@ As a fetcher, invalidating the publisher or updating the endpoint will trigger a
 
 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.
+
+<sonic-code>
+  <template>
+    <sonic-sdui
+      profile="safe"
+      dataProvider="sdui-safe-example"
+      props='{
+        "nodes":[
+          { "tagName":"p", "textContent":"Plain text is fine" },
+          { "innerHTML":"&lt;script&gt;/* refused */&lt;/script&gt;" }
+        ]
+      }'
+    ></sonic-sdui>
+  </template>
+</sonic-code>
+
+### Component catalog (build-only)
+
+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
+
+<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>
+  </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
+
+This does **not** replace form submit (`sonic-submit` / POST / `messagesKey`). Those keep working as before; only nodes that declare `action` emit `sdui-action`.
+
+<sonic-code>
+  <template>
+    <sonic-sdui
+      dataProvider="sdui-action-example"
+      props='{
+        "nodes":[{
+          "tagName":"sonic-button",
+          "nodeId":"confirm-btn",
+          "textContent":"Confirm",
+          "action":{ "name":"confirm", "context":{ "step":1 } }
+        }]
+      }'
+    ></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:
@@ -34,6 +147,7 @@ It has no shadowdom, and its display style is set to `contents`, so an empty SDU
       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>
@@ -44,6 +158,7 @@ It has no shadowdom, and its display style is set to `contents`, so an empty SDU
 * **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
 
@@ -60,12 +175,15 @@ TypeScript definition:
       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>
@@ -75,12 +193,16 @@ Summary of properties:
 * **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.

package/src/core/components/functional/sdui/sdui.regression.spec.ts

@@ -0,0 +1,64 @@
+import { afterEach, describe, expect, it } from "vitest";
+import TestUtils from "@supersoniks/concorde/test-utils/TestUtils";
+import SDUIDescriptorTransformer from "./SDUIDescriptorTransformer";
+import {
+  renderFixtures,
+  transformRemapDescription,
+  transformRemapInput,
+} from "./__fixtures__/descriptors";
+import { snapshotLightDom } from "./sdui-dom-snapshot";
+import type { SDUIDescriptor } from "./types";
+import "./sdui";
+import type { SonicSDUI } from "./sdui";
+
+function clone<T>(value: T): T {
+  return structuredClone(value);
+}
+
+/** Attendre la fin de updateContents (await loadLibrary / transform). */
+async function flushSdui(elt: SonicSDUI) {
+  await elt.updateComplete;
+  await Promise.resolve();
+  await Promise.resolve();
+  await elt.updateComplete;
+}
+
+async function renderDescriptor(descriptor: SDUIDescriptor): Promise<SonicSDUI> {
+  const [elt] = TestUtils.bootstrap(
+    `<sonic-sdui></sonic-sdui>`
+  ) as unknown as SonicSDUI[];
+  // Clone : parseRootNodes mute nodes (toast) et updateContents mute library
+  elt.props = clone(descriptor) as never;
+  await flushSdui(elt);
+  return elt;
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+describe("sonic-sdui non-régression (DOM snapshots)", () => {
+  for (const [name, descriptor] of Object.entries(renderFixtures)) {
+    it(`fixture "${name}"`, async () => {
+      const elt = await renderDescriptor(descriptor);
+      expect(snapshotLightDom(elt)).toMatchSnapshot();
+    });
+  }
+});
+
+describe("SDUIDescriptorTransformer non-régression", () => {
+  it("remap legacy-button → sonic-button (descripteur)", async () => {
+    const descriptor = clone(transformRemapInput);
+    const transformer = new SDUIDescriptorTransformer();
+    await transformer.transform(descriptor, clone(transformRemapDescription));
+    expect(descriptor).toMatchSnapshot();
+  });
+
+  it("remap puis rendu DOM", async () => {
+    const descriptor = clone(transformRemapInput);
+    const transformer = new SDUIDescriptorTransformer();
+    await transformer.transform(descriptor, clone(transformRemapDescription));
+    const elt = await renderDescriptor(descriptor);
+    expect(snapshotLightDom(elt)).toMatchSnapshot();
+  });
+});