@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

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

@@ -1,94 +1,93 @@
 # Router
 
-**sonic-router** watches `document.location` (pathname + hash) and renders the matching view.
+**`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.
 
-From a **Lit** parent, pass a **`.routes`** map (property binding — same rule as [`.items` on list](#core/components/functional/list/list.md/list)): keys are path patterns, values are render functions. Use **`fallback`** when nothing matches.
+## Static routes
 
-Legacy HTML **`<template data-route="…">`** remains for hosts without Lit — [HTML integration](#docs/_misc/html-integration.md/html-integration).
-
-## Static routes (no parameters)
-
-Route keys are matched against `pathname + hash`. A simple hash route `#home` matches when the location contains that segment.
-
-On the **doc site**, the page URL is already a hash (`#…/router.md/router`). Demos append a **second** hash for in-page routes (`#…/router#home`), use **`href` + `autoActive="strict"`** on `sonic-button` for the active state, and `history.replaceState` on click so markdown is not reloaded (`setDocsDemoSubHash` in `src/docs/docs-location.ts`).
+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>
 
-```typescript
-@state()
-private routes = {
-  "#home": () => html`<div>Home</div>`,
-  "#about": () => html`<div>About</div>`,
-  fallback: () => html`<div>Not found</div>`,
-};
+Set `.routes` as a **property** binding: render functions cannot go through an HTML attribute.
 
-html`
-  <sonic-button href="#home">Home</sonic-button>
-  <sonic-router .routes=${this.routes}></sonic-router>
-`;
-```
+## Route parameters
 
-| Key | When it runs |
-|-----|----------------|
-| `"#home"`, `"#about"`, … | `RegExp` or [url-pattern](https://www.npmjs.com/package/url-pattern) test succeeds on current location |
-| **`fallback`** | No other route matched (not an attribute — a key on the same object) |
+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.
 
-## Routes with parameters
+<docs-lit-demo for="docs-router-params-demo"></docs-lit-demo>
 
-Two styles (see `router.demo.ts` and `docs-router-params-demo`):
+## Base path
 
-### Url-pattern (`:name`)
+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 `^`.
 
-Key uses **`:param`** segments. The render function receives an **object** `{ param: string }`.
+<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>
 
-<docs-lit-demo for="docs-router-params-demo"></docs-lit-demo>
+## HTML templates
 
-```typescript
-"#couleur/:id": ({ id }) => html`<p>Colour id: ${id}</p>`,
-```
+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).
 
-### RegExp (capturing groups)
+<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>
 
-Key is a **RegExp** string with `(\d+)` / `(\w+)` groups. The render function receives an **array** of captured strings (in order).
+`fallBackRoute` navigates to its URL when no route matches, even if a `data-fallback` template exists. A `routes.fallback` function prevents it.
 
-```typescript
-"#products/(\\d+)/(\\w+)": ([productId, slug]) =>
-  html`<p>Product ${productId}, slug ${slug}</p>`,
-```
+## Redirect on data
 
-With parameters you usually render data directly in Lit (`${id}`). The old **`<template data-route>` + `dataProviderExpression`** pattern scoped a `dataProvider` for `data-bind` / fetch children — prefer **`@subscribe`** or explicit props when using `.routes`.
+**`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.
 
-## `.routes` binding
+<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>
 
-Always use **`.routes=${…}`** in Lit templates: route handlers are functions and must be set as **properties**, not HTML attributes.
+Objects do not trigger the redirect: point `onData` at a scalar such as `passenger.id`.
 
-## Optional attributes
+## API reference
 
-| Attribute | Role |
-|-----------|------|
-| **`basePath`** | Prefix for pattern matching (default allows optional leading segments) |
-| **`fallBackRoute`** | If set and no template/route matches, navigates to this URL (redirect). Distinct from **`routes.fallback`** which only renders content |
+`sonic-router`
 
-## `sonic-redirect`
+| 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 |
 
-Separate component: redirect when data appears on a publisher (login steps, wizards). Not part of the `.routes` map.
+| 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` |
 
-<sonic-code>
-  <template>
-    <sonic-redirect to="#core/components/functional/router/router.md/router#data-is-set" dataProvider="stupid-data-set-id" onData="theData"></sonic-redirect>
-    <div class="flex gap-2 mb-4" formDataProvider="stupid-data-set-id">
-      <sonic-button radio name="theData" value="Some Data" size="xs">
-        Enter data
-      </sonic-button>
-      <sonic-button radio name="theData" value="" href="javascript:history.back();" size="xs">
-        Delete the data and do a history.back()
-      </sonic-button>
-    </div>
-  </template>
-</sonic-code>
+| Slot | Description |
+|------|-------------|
+| *(default)* | `<template data-route>` children |
 
-Example: combine with **`.routes`** and **submit** for login / logout / profile steps.
+`sonic-redirect`
 
-## Package demo
+| 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 |
 
-`sonic-router-demo` (`router.demo.ts`) — home, user profile (`#user/:id/:slug`), products RegExp, **fallback** 404.
+No slots.

package/src/core/components/functional/sdui/component-catalog.gaps.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-10-26T08:56:47.308Z",
+  "generatedAt": "2026-10-29T21:35:24.462Z",
   "count": 66,
   "items": [
     {

package/src/core/components/functional/sdui/component-catalog.json

@@ -1,6 +1,6 @@
 {
   "version": 1,
-  "generatedAt": "2026-10-26T08:56:47.308Z",
+  "generatedAt": "2026-10-29T21:35:24.462Z",
   "componentCount": 67,
   "components": [
     {
@@ -755,7 +755,7 @@
         {
           "name": "geoCommunesResult",
           "attribute": "geoCommunesResult",
-          "type": "City[] | undefined"
+          "type": "Frozen<City[]> | undefined"
         }
       ]
     },

package/src/core/components/functional/sdui/example.json

@@ -1,99 +1,32 @@
 {
   "nodes": [
     {
-      "tagName": "div",
-      "attributes": {
-        "class": "flex gap-2 items-center",
-        "formdataprovider": "states-basic-example"
-      },
+      "tagName": "sonic-card",
+      "attributes": { "class": "block max-w-sm" },
       "nodes": [
         {
-          "tagName": "sonic-button",
-          "attributes": {
-            "radio": "",
-            "name": "selection",
-            "value": "#home",
-            "checked": "",
-            "size": "xs"
-          },
-          "innerHTML": "Home"
-        },
-        {
-          "tagName": "sonic-button",
-          "attributes": {
-            "radio": "",
-            "name": "selection",
-            "value": "#about",
-            "size": "xs"
-          },
-          "innerHTML": "About"
-        },
-        {
-          "tagName": "sonic-button",
-          "attributes": {
-            "radio": "",
-            "name": "selection",
-            "value": "#work",
-            "size": "xs"
-          },
-          "innerHTML": "Work"
-        },
-        {
-          "tagName": "sonic-button",
-          "attributes": {
-            "radio": "",
-            "name": "selection",
-            "value": "#contact",
-            "size": "xs"
-          },
-          "innerHTML": "Contact"
-        }
-      ]
-    },
-    {
-      "tagName": "div",
-      "attributes": {
-        "class": "text-center text-neutral-700 border rounded text-4xl  my-6 p-3 "
-      },
-      "nodes": [
-        {
-          "tagName": "sonic-states",
-          "attributes": {
-            "dataprovider": "states-basic-example",
-            "data-path": "selection"
-          },
+          "tagName": "div",
+          "attributes": { "class": "flex items-center justify-between gap-2" },
           "nodes": [
+            { "tagName": "strong", "textContent": "Boarding pass · CN 001" },
             {
-              "tagName": "template",
-              "attributes": {
-                "data-value": "#home"
-              },
-              "innerHTML": "Home"
-            },
-            {
-              "tagName": "template",
-              "attributes": {
-                "data-value": "#about"
-              },
-              "innerHTML": "About"
-            },
-            {
-              "tagName": "template",
-              "attributes": {
-                "data-value": "#work"
-              },
-              "innerHTML": "Work"
-            },
-            {
-              "tagName": "template",
-              "attributes": {
-                "data-value": "#contact"
-              },
-              "innerHTML": "Contact"
+              "tagName": "sonic-badge",
+              "attributes": { "type": "success" },
+              "textContent": "Boarding"
             }
           ]
+        },
+        {
+          "tagName": "p",
+          "attributes": { "class": "m-0 mt-3 text-2xl" },
+          "textContent": "CDG → JFK"
+        },
+        {
+          "tagName": "p",
+          "attributes": { "class": "m-0 mt-1 text-sm" },
+          "textContent": "Ada Lindqvist · Gate C4 · Seat 2A"
         }
       ]
     }
   ]
-}
+}

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

@@ -3,7 +3,7 @@
 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).
+La doc utilisateur reste `sdui.md` (auto-suffisante).
 
 **Aucune mention de protocoles tiers ici** : uniquement les API génériques Concorde.
 

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

@@ -0,0 +1,74 @@
+import { afterEach, describe, expect, it } from "vitest";
+import TestUtils from "@supersoniks/concorde/test-utils/TestUtils";
+import { PublisherManager } from "@supersoniks/concorde/core/utils/PublisherProxy";
+import { snapshotLightDom } from "./sdui-dom-snapshot";
+import type { SDUIDescriptor } from "./types";
+import "./sdui";
+import type { SonicSDUI } from "./sdui";
+
+async function flushSdui(elt: SonicSDUI) {
+  await elt.updateComplete;
+  await Promise.resolve();
+  await Promise.resolve();
+  await elt.updateComplete;
+}
+
+afterEach(() => {
+  document.body.innerHTML = "";
+  PublisherManager.getInstance().delete("sdui-immutable-spec");
+});
+
+describe("sonic-sdui + immutable publisher props", () => {
+  it("rend un descripteur servi par un publisher frozen (cas doc / dataProvider)", async () => {
+    const descriptor: SDUIDescriptor = {
+      nodes: [
+        {
+          tagName: "div",
+          attributes: { class: "sdui-imm-ok" },
+          textContent: "FROM_FROZEN_PROPS",
+        },
+      ],
+    };
+
+    const [elt] = TestUtils.bootstrap(
+      `<sonic-sdui dataProvider="sdui-immutable-spec"></sonic-sdui>`
+    ) as unknown as SonicSDUI[];
+
+    // Même chemin que Subscriber : props → publisher.set → get() frozen → willUpdate
+    elt.props = descriptor as never;
+    await flushSdui(elt);
+
+    expect(Object.isFrozen(elt.props)).toBe(true);
+    expect(elt.querySelector(".sdui-imm-ok")?.textContent).toBe(
+      "FROM_FROZEN_PROPS"
+    );
+    expect(JSON.stringify(snapshotLightDom(elt))).toContain("FROM_FROZEN_PROPS");
+  });
+
+  it("supporte libraryKey avec props frozen (merge library mutable en local)", async () => {
+    const descriptor: SDUIDescriptor = {
+      library: {
+        card: {
+          tagName: "div",
+          attributes: { class: "lib-card" },
+          nodes: [{ tagName: "span" }],
+          contentElementSelector: "span",
+        },
+      },
+      nodes: [
+        {
+          libraryKey: "card",
+          nodes: [{ tagName: "em", textContent: "LIB_OK" }],
+        },
+      ],
+    };
+
+    const [elt] = TestUtils.bootstrap(
+      `<sonic-sdui dataProvider="sdui-immutable-spec"></sonic-sdui>`
+    ) as unknown as SonicSDUI[];
+    elt.props = descriptor as never;
+    await flushSdui(elt);
+
+    expect(elt.querySelector(".lib-card em")?.textContent).toBe("LIB_OK");
+  });
+});