@supersoniks/concorde 5.0.4 → 5.1.0

package/src/core/components/functional/sdui/component-catalog.spec.ts

@@ -0,0 +1,23 @@
+import { describe, expect, it } from "vitest";
+import catalog from "./component-catalog.json";
+
+describe("component-catalog.json (artefact publié)", () => {
+  it("contient des composants avec tag et props", () => {
+    expect(catalog.version).toBe(1);
+    expect(catalog.componentCount).toBeGreaterThan(10);
+    expect(catalog.components.length).toBe(catalog.componentCount);
+
+    const button = catalog.components.find(
+      (c: { tag: string }) => c.tag === "sonic-button"
+    );
+    expect(button).toBeTruthy();
+    expect(button!.props.some((p: { name: string }) => p.name === "type")).toBe(
+      true
+    );
+  });
+
+  it("expose un compteur de gaps d'annotations", () => {
+    expect(typeof catalog.insufficientAnnotationCount).toBe("number");
+    expect(catalog.insufficientAnnotationCount).toBeGreaterThan(0);
+  });
+});

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

@@ -0,0 +1,99 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import TestUtils from "@supersoniks/concorde/test-utils/TestUtils";
+import { formFields } from "./__fixtures__/descriptors";
+import { snapshotLightDom } from "./sdui-dom-snapshot";
+import type { SDUIActionDetail, 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): Promise<SonicSDUI> {
+  const [elt] = TestUtils.bootstrap(
+    `<sonic-sdui></sonic-sdui>`
+  ) as unknown as SonicSDUI[];
+  elt.props = clone(descriptor) as never;
+  await flushSdui(elt);
+  return elt;
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+describe("sonic-sdui sdui-action", () => {
+  it("émet sdui-action au clic avec name, context et sourceNodeId", async () => {
+    const elt = await render({
+      nodes: [
+        {
+          tagName: "button",
+          nodeId: "confirm-btn",
+          textContent: "Confirm",
+          action: { name: "confirm", context: { step: 1 } },
+        },
+      ],
+    });
+
+    const handler = vi.fn();
+    elt.addEventListener("sdui-action", handler as EventListener);
+
+    const button = elt.querySelector("button");
+    expect(button).toBeTruthy();
+    button!.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+
+    expect(handler).toHaveBeenCalledTimes(1);
+    const event = handler.mock.calls[0][0] as CustomEvent<SDUIActionDetail>;
+    expect(event.type).toBe("sdui-action");
+    expect(event.bubbles).toBe(true);
+    expect(event.composed).toBe(true);
+    expect(event.detail).toEqual({
+      name: "confirm",
+      context: { step: 1 },
+      sourceNodeId: "confirm-btn",
+    });
+  });
+
+  it("n'émet rien sans champ action", async () => {
+    const elt = await render({
+      nodes: [{ tagName: "button", textContent: "No action" }],
+    });
+    const handler = vi.fn();
+    elt.addEventListener("sdui-action", handler as EventListener);
+    elt.querySelector("button")!.dispatchEvent(
+      new MouseEvent("click", { bubbles: true })
+    );
+    expect(handler).not.toHaveBeenCalled();
+  });
+
+  it("context par défaut = {} si omis", async () => {
+    const elt = await render({
+      nodes: [
+        {
+          tagName: "button",
+          textContent: "Go",
+          action: { name: "go" },
+        },
+      ],
+    });
+    const handler = vi.fn();
+    elt.addEventListener("sdui-action", handler as EventListener);
+    elt.querySelector("button")!.click();
+    const event = handler.mock.calls[0][0] as CustomEvent<SDUIActionDetail>;
+    expect(event.detail.context).toEqual({});
+    expect(event.detail.sourceNodeId).toBeUndefined();
+  });
+
+  it("ne change pas le rendu formulaire (snapshot structurelle)", async () => {
+    const elt = await render(formFields);
+    expect(snapshotLightDom(elt)).toMatchSnapshot();
+  });
+});

package/src/core/components/functional/sdui/sdui-dom-snapshot.ts

@@ -0,0 +1,61 @@
+/**
+ * Sérialisation stable du light-DOM produit par sonic-sdui,
+ * pour des snapshots de non-régression.
+ */
+
+export type DomSnapshot =
+  | string
+  | {
+      tag: string;
+      attrs?: Record<string, string>;
+      children?: DomSnapshot[];
+    };
+
+function snapshotNode(node: Node): DomSnapshot | null {
+  if (node.nodeType === Node.TEXT_NODE) {
+    const text = (node.textContent || "").replace(/\s+/g, " ").trim();
+    return text || null;
+  }
+  if (node.nodeType !== Node.ELEMENT_NODE) return null;
+
+  const el = node as HTMLElement;
+  const tag = el.tagName.toLowerCase();
+  const attrs: Record<string, string> = {};
+  const names = Array.from(el.attributes)
+    .map((a) => a.name)
+    .sort();
+  for (const name of names) {
+    // style inline volatile (display:contents posé par prefix/suffix / markup)
+    if (name === "style") {
+      const style = el.getAttribute(name) || "";
+      if (style.replace(/\s+/g, "") === "display:contents") {
+        attrs[name] = "display: contents";
+      } else {
+        attrs[name] = style;
+      }
+      continue;
+    }
+    attrs[name] = el.getAttribute(name) || "";
+  }
+
+  const children: DomSnapshot[] = [];
+  for (const child of Array.from(el.childNodes)) {
+    const snap = snapshotNode(child);
+    if (snap != null) children.push(snap);
+  }
+
+  const result: DomSnapshot = { tag };
+  if (Object.keys(attrs).length > 0) result.attrs = attrs;
+  if (children.length > 0) result.children = children;
+  return result;
+}
+
+/** Snapshot des enfants light-DOM d’un hôte (typiquement sonic-sdui). */
+export function snapshotLightDom(host: HTMLElement): DomSnapshot[] {
+  const out: DomSnapshot[] = [];
+  for (const child of Array.from(host.childNodes)) {
+    const snap = snapshotNode(child);
+    if (snap != null) out.push(snap);
+  }
+  return out;
+}

package/src/core/components/functional/sdui/sdui-extension-points.md

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

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

@@ -0,0 +1,137 @@
+import { afterEach, describe, expect, it } from "vitest";
+import TestUtils from "@supersoniks/concorde/test-utils/TestUtils";
+import { set } from "@supersoniks/concorde/core/utils/PublisherProxy";
+import { layoutNested } from "./__fixtures__/descriptors";
+import { snapshotLightDom } from "./sdui-dom-snapshot";
+import {
+  SDUI_NODE_ID_ATTR,
+  SDUI_PLACEHOLDER_ATTR,
+} from "./sdui-partial";
+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): Promise<SonicSDUI> {
+  const [elt] = TestUtils.bootstrap(
+    `<sonic-sdui></sonic-sdui>`
+  ) as unknown as SonicSDUI[];
+  elt.props = clone(descriptor) as never;
+  await flushSdui(elt);
+  return elt;
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+});
+
+describe("sonic-sdui ops incrémentales", () => {
+  it("upsertNode remplit un placeholder sans détruire le frère (valeur input)", async () => {
+    const [elt] = TestUtils.bootstrap(
+      `<sonic-sdui partial></sonic-sdui>`
+    ) as unknown as SonicSDUI[];
+    elt.props = {
+      nodes: [
+        {
+          nodeId: "root",
+          tagName: "div",
+          attributes: { class: "root" },
+          childNodeIds: ["field", "later"],
+        },
+      ],
+      nodeById: {
+        field: {
+          nodeId: "field",
+          tagName: "input",
+          attributes: { type: "text", name: "email" },
+        },
+      },
+    } as never;
+    await flushSdui(elt);
+
+    const input = elt.querySelector("input") as HTMLInputElement;
+    expect(input).toBeTruthy();
+    input.value = "keep-me";
+    expect(
+      elt.querySelector(`[${SDUI_PLACEHOLDER_ATTR}][data-node-id="later"]`)
+    ).toBeTruthy();
+
+    elt.upsertNode(
+      {
+        nodeId: "later",
+        tagName: "span",
+        attributes: { class: "later" },
+        textContent: "arrived",
+      },
+      "root"
+    );
+
+    expect(elt.querySelector(".later")?.textContent).toBe("arrived");
+    expect(
+      elt.querySelector(`[${SDUI_PLACEHOLDER_ATTR}][data-node-id="later"]`)
+    ).toBeNull();
+    const inputAfter = elt.querySelector("input") as HTMLInputElement;
+    expect(inputAfter.value).toBe("keep-me");
+    expect(inputAfter).toBe(input);
+  });
+
+  it("removeNode retire le nœud ciblé uniquement", async () => {
+    const elt = await render({
+      nodes: [
+        {
+          nodeId: "root",
+          tagName: "div",
+          childNodeIds: ["a", "b"],
+        },
+      ],
+      nodeById: {
+        a: { nodeId: "a", tagName: "span", textContent: "A" },
+        b: { nodeId: "b", tagName: "span", textContent: "B" },
+      },
+    });
+
+    elt.removeNode("a");
+    expect(elt.querySelector(`[${SDUI_NODE_ID_ATTR}="a"]`)).toBeNull();
+    expect(elt.querySelector(`[${SDUI_NODE_ID_ATTR}="b"]`)?.textContent).toBe(
+      "B"
+    );
+  });
+
+  it("setData met à jour un dataProvider par chemin", async () => {
+    set("sdui-inc-form", { email: "" });
+    const elt = await render({ nodes: [{ tagName: "div" }] });
+    elt.setAttribute("dataProvider", "sdui-inc-form");
+    // dataProvider property may need connected publisher — set via path absolute
+    elt.setData("sdui-inc-form.email", "hi@test");
+    const { get } = await import("@supersoniks/concorde/core/utils/PublisherProxy");
+    expect(get("sdui-inc-form").email).toBe("hi@test");
+  });
+
+  it("applyOp délègue correctement", async () => {
+    const elt = await render({ nodes: [] });
+    elt.applyOp({
+      op: "upsertNode",
+      node: { nodeId: "x", tagName: "p", textContent: "X" },
+    });
+    expect(elt.querySelector(`[${SDUI_NODE_ID_ATTR}="x"]`)?.textContent).toBe(
+      "X"
+    );
+    elt.applyOp({ op: "removeNode", nodeId: "x" });
+    expect(elt.querySelector(`[${SDUI_NODE_ID_ATTR}="x"]`)).toBeNull();
+  });
+
+  it("ne régresse pas le chemin descripteur entier", async () => {
+    const elt = await render(layoutNested);
+    expect(snapshotLightDom(elt)).toMatchSnapshot();
+  });
+});

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

@@ -0,0 +1,83 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import TestUtils from "@supersoniks/concorde/test-utils/TestUtils";
+import { layoutNested } from "./__fixtures__/descriptors";
+import { snapshotLightDom } from "./sdui-dom-snapshot";
+import { SDUI_PLACEHOLDER_ATTR } from "./sdui-partial";
+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();
+});
+
+const partialDescriptor: SDUIDescriptor = {
+  nodes: [
+    {
+      tagName: "div",
+      attributes: { class: "root" },
+      childNodeIds: ["present", "missing"],
+    },
+  ],
+  nodeById: {
+    present: {
+      nodeId: "present",
+      tagName: "span",
+      attributes: { class: "ok" },
+      textContent: "here",
+    },
+  },
+};
+
+describe("sonic-sdui rendu partiel", () => {
+  it("sans partial : enfant manquant ignoré (warning), pas de placeholder", async () => {
+    const warn = vi.spyOn(console, "warn").mockImplementation(() => {});
+    const elt = await render(partialDescriptor);
+    expect(elt.querySelector(`[${SDUI_PLACEHOLDER_ATTR}]`)).toBeNull();
+    expect(elt.querySelector(".ok")?.textContent).toBe("here");
+    expect(
+      warn.mock.calls.some((c) => String(c[0]).includes('childNodeId "missing"'))
+    ).toBe(true);
+  });
+
+  it("avec partial : placeholder léger pour l'enfant manquant", async () => {
+    vi.spyOn(console, "warn").mockImplementation(() => {});
+    const elt = await render(partialDescriptor, { partial: "" });
+    const ph = elt.querySelector(`[${SDUI_PLACEHOLDER_ATTR}]`);
+    expect(ph).toBeTruthy();
+    expect(ph?.getAttribute("data-node-id")).toBe("missing");
+    expect(elt.querySelector(".ok")?.textContent).toBe("here");
+  });
+
+  it("ne régresse pas sur un descripteur classique (snapshot)", async () => {
+    const elt = await render(layoutNested);
+    expect(snapshotLightDom(elt)).toMatchSnapshot();
+  });
+});

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

@@ -0,0 +1,19 @@
+/** Marqueur DOM des placeholders de rendu partiel. */
+export const SDUI_PLACEHOLDER_ATTR = "data-sdui-placeholder";
+
+/** Attribut DOM portant le `nodeId` logique (pas l'id HTML). */
+export const SDUI_NODE_ID_ATTR = "data-sdui-node-id";
+
+/**
+ * Placeholder léger pour un enfant référencé pas encore disponible.
+ * `display: contents` pour ne pas perturber le layout.
+ */
+export function createSduiPlaceholder(nodeId: string): HTMLElement {
+  const el = document.createElement("div");
+  el.setAttribute(SDUI_PLACEHOLDER_ATTR, "");
+  el.setAttribute("data-node-id", nodeId);
+  el.setAttribute(SDUI_NODE_ID_ATTR, nodeId);
+  el.setAttribute("aria-hidden", "true");
+  el.style.display = "contents";
+  return el;
+}