@supersoniks/concorde 4.0.0 → 4.2.0

package/src/core/utils/HTML.ts

@@ -147,6 +147,68 @@ class HTML {
   static getClosestForm(node: SearchableDomElement) {
     return HTML.getClosestElement(node, "form");
   }
+
+  /**
+   * Parcourt les ancêtres (parentNode / shadow host) et collecte ceux dont le tagName
+   * correspond à l'un des noms fournis (comparaison insensible à la casse).
+   * @param node Élément de départ
+   * @param tagNames Noms de balises à rechercher (ex: ['sonic-subscriber', 'sonic-sdui'])
+   * @returns Tableau des ancêtres correspondants
+   */
+  static getAncestorsByTagNames(
+    node: SearchableDomElement,
+    tagNames: string[]
+  ): Element[] {
+    const normalized = new Set(tagNames.map((t) => t.toLowerCase()));
+    const result: Element[] = [];
+    let current = (node.parentNode ||
+      (node as ShadowRoot).host) as SearchableDomElement;
+    while (current) {
+      if (
+        current instanceof Element &&
+        normalized.has(current.tagName.toLowerCase())
+      ) {
+        result.push(current);
+      }
+      current = (current.parentNode ||
+        (current as ShadowRoot).host) as SearchableDomElement;
+    }
+    return result;
+  }
+
+  /**
+   * Parcourt les ancêtres (parentNode / shadow host) et collecte ceux qui matchent
+   * l'un des sélecteurs CSS fournis (element.matches(selector)).
+   * @param node Élément de départ
+   * @param selectors Sélecteurs CSS (ex: ['sonic-subscriber', 'sonic-sdui', 'div.container'])
+   * @returns Tableau des ancêtres correspondants
+   */
+  static getAncestorsBySelectors(
+    node: SearchableDomElement,
+    selectors: string[]
+  ): Element[] {
+    const result: Element[] = [];
+    let current = (node.parentNode ||
+      (node as ShadowRoot).host) as SearchableDomElement;
+    while (current) {
+      if (current instanceof Element) {
+        for (const selector of selectors) {
+          try {
+            if (current.matches(selector)) {
+              result.push(current);
+              break;
+            }
+          } catch {
+            // Invalid selector, skip
+          }
+        }
+      }
+      current = (current.parentNode ||
+        (current as ShadowRoot).host) as SearchableDomElement;
+    }
+    return result;
+  }
+
   /**
    * Lance le chargement d'un js et retourne une promise qui resoud à true lorsque le chargement à réussi et à false, sinon.
    * */

package/src/core/utils/PublisherProxy.ts

@@ -31,7 +31,7 @@ function isLeaf(value: any) {
 }
 
 function isComplex(value: any) {
-  return typeof value === "object" && value != null;
+  return typeof value === "object" && value !== null;
 }
 
 declare const __BUILD_DATE__: string;
@@ -315,11 +315,13 @@ export class PublisherProxy<T = any> {
      * et qu'elle est primitive
      */
     if (
-      this._value_ &&
-      newValue &&
-      isLeaf(this._value_) &&
-      isLeaf(newValue) &&
-      (this._value_ as any).__value === (newValue as any).__value
+      (isComplex(this._value_) &&
+        isComplex(newValue) &&
+        newValue &&
+        isLeaf(this._value_) &&
+        isLeaf(newValue) &&
+        (this._value_ as any).__value === (newValue as any).__value) ||
+      (!isComplex(newValue) && newValue === (this._value_ as any).__value)
     ) {
       return true;
     }

package/src/core/utils/route.ts

@@ -30,10 +30,28 @@ export class Route<RoutesData = any> {
   matchesLocation() {
     return this.matchesCurrentPath();
   }
+
   matchesCurrentPath() {
     return this.extract() !== null;
   }
 
+  removeQuery() {
+    const url = new URL(this.route, window.location.origin);
+    url.search = "";
+    this.route = url.href.replace(window.location.origin, "");
+    return this;
+  }
+
+  withoutQuery() {
+    return this.clone().removeQuery();
+  }
+
+  clone() {
+    const clonedRoute = new Route();
+    clonedRoute.route = this.route;
+    return clonedRoute;
+  }
+
   fill(properties: Object) {
     this.route = new URLPattern(this.route).stringify(properties);
     return this;
@@ -98,7 +116,7 @@ export class Routes {
   static register<RouteData = any>(
     routes: Partial<RouteData>,
     baseUrlOrOpt: { baseUrl?: string; prefix?: string } | string = "",
-    prefix = ""
+    prefix = "",
   ) {
     const newRoutes: Partial<RouteData> = {};
     Object.keys(routes).forEach((key) => {
@@ -125,7 +143,7 @@ export class Routes {
   }
   static get<RouteData extends Record<keyof RouteData, string | undefined>>(
     name: keyof RouteData,
-    args?: RouteArgs
+    args?: RouteArgs,
   ) {
     const routes = Routes.routes as Partial<RouteData>;
     let route = routes[name] || "";
@@ -134,7 +152,7 @@ export class Routes {
     }
     const url = new URL(
       route,
-      route.startsWith("#") ? window.location.href : window.location.origin
+      route.startsWith("#") ? window.location.href : window.location.origin,
     );
     if (args?.query) {
       Object.entries(args.query).forEach(([key, value]) => {

package/src/decorators.ts

@@ -1,9 +1,14 @@
 import * as mySubscriber from "@supersoniks/concorde/core/decorators/Subscriber";
+import * as lifecycle from "@supersoniks/concorde/core/decorators/lifecycle";
+
 export const bind = mySubscriber.bind;
 export const onAssign = mySubscriber.onAssign;
 export const ancestorAttribute = mySubscriber.ancestorAttribute;
 export const autoSubscribe = mySubscriber.autoSubscribe;
 export const autoFill = mySubscriber.autoFill;
+export const awaitConnectedAncestors = lifecycle.awaitConnectedAncestors;
+export const dispatchConnectedEvent = lifecycle.dispatchConnectedEvent;
+export const CONNECTED = lifecycle.CONNECTED;
 
 import { ConcordeWindow } from "./core/_types/types";
 declare const window: ConcordeWindow;

package/src/docs/_misc/wait-for-ancestors.md

@@ -0,0 +1,160 @@
+# @awaitConnectedAncestors and @dispatchConnectedEvent
+
+The `@awaitConnectedAncestors` and `@dispatchConnectedEvent` decorators delay a web component's initialization until its matching ancestors have executed their `connectedCallback`. This is when contextual elements (publisher, dataProvider, etc.) are configured.
+
+## Principle
+
+When a child component attaches to the DOM, its ancestors may not yet be initialized (especially if custom element definitions are loaded asynchronously). The `@awaitConnectedAncestors` decorator delays the component's `connectedCallback` until all ancestors matching the provided CSS selectors have executed their `connectedCallback`.
+
+The `@dispatchConnectedEvent` decorator allows ancestors to signal they are ready by dispatching the `sonic-connected` event at the end of their `connectedCallback`. The event bubbles, so it can be listened to from anywhere (e.g. `document.addEventListener(CONNECTED, handler)`).
+
+Ancestors that are not web components (no hyphen in tag name) are considered connected by default and do not need to emit the event.
+
+## Usage
+
+### Import
+
+<sonic-code language="typescript">
+  <template>
+import { awaitConnectedAncestors, dispatchConnectedEvent, ancestorAttribute } from "@supersoniks/concorde/decorators";
+  </template>
+</sonic-code>
+
+### Basic example
+
+An ancestor container decorated with `@dispatchConnectedEvent()` signals when it is ready. A child component decorated with `@awaitConnectedAncestors("demo-wait-ancestor-container[dataProvider]")` waits for this container to be initialized before initializing itself. Parameters are CSS selectors (`element.matches()`).
+
+The parent is registered via `customElements.define()` (vanilla JS) rather than `@customElement`, so it can be defined later—e.g. when the user clicks a button. This demonstrates the child waiting until the parent exists.
+
+<sonic-code language="typescript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement, state } from "lit/decorators.js";
+//
+// Parent: registered later via customElements.define(), not @customElement
+@dispatchConnectedEvent()
+export class DemoWaitAncestorContainer extends LitElement {
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+//
+// Child: waits for parent before initializing
+@customElement("demo-wait-ancestor-value")
+@awaitConnectedAncestors("demo-wait-ancestor-container[dataProvider]")
+export class DemoWaitAncestorValue extends LitElement {
+  @ancestorAttribute("dataProvider")
+  dataProvider: string | null = null;
+  //
+  @state() initializedAt: string = "";
+  //
+  connectedCallback() {
+    super.connectedCallback();
+    this.initializedAt = new Date().toISOString();
+  }
+  //
+  render() {
+    return html`
+      <p>DataProvider from ancestor: <strong>${this.dataProvider || "—"}</strong></p>
+      <p>Initialized at: ${this.initializedAt || "(waiting for parent…)"}</p>
+    `;
+  }
+}
+//
+// Demo section: register parent via customElements.define() when user clicks
+@customElement("demo-wait-ancestors-section")
+export class DemoWaitAncestorsSection extends LitElement {
+  registerParent() {
+    if (!customElements.get("demo-wait-ancestor-container")) {
+      customElements.define("demo-wait-ancestor-container", DemoWaitAncestorContainer);
+    }
+  }
+  render() {
+    return html`
+      <sonic-button @click=${this.registerParent}>Register parent component</sonic-button>
+      <demo-wait-ancestor-container dataProvider="waitAncestorDemo">
+        <demo-wait-ancestor-value></demo-wait-ancestor-value>
+      </demo-wait-ancestor-container>
+    `;
+  }
+}
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+<demo-wait-ancestors-section></demo-wait-ancestors-section>
+  </template>
+</sonic-code>
+
+### Multiple ancestors
+
+The child waits for all specified ancestors. Register outer first, then inner — the child initializes only when both are ready.
+
+<sonic-code>
+  <template>
+<demo-wait-ancestors-multi-section></demo-wait-ancestors-multi-section>
+  </template>
+</sonic-code>
+
+### Ancestors already connected
+
+When the parent is defined at load and already in the DOM, the child initializes immediately (no delay).
+
+**Static (both in DOM from start):**
+
+<sonic-code>
+  <template>
+<demo-wait-ancestors-static-section></demo-wait-ancestors-static-section>
+  </template>
+</sonic-code>
+
+**Dynamic (child added on button click):**
+
+<sonic-code>
+  <template>
+<demo-wait-ancestors-ready-section></demo-wait-ancestors-ready-section>
+  </template>
+</sonic-code>
+
+## CSS selector support
+
+Parameters are CSS selectors matched via `element.matches()` — e.g. `"sonic-subscriber"`, `"sonic-subscriber[dataProvider]"`, `".my-container"`, or multiple: `"sonic-subscriber", "sonic-sdui"`.
+
+## Behavior
+
+- Ancestor search uses CSS selectors (`element.matches(selector)`) — supports tag names, classes, attributes, combinators, etc.
+- Traversal includes shadow roots (parentNode / host)
+- Non-web components (no hyphen in tag name) are considered connected by default
+- For web component ancestors, it waits for `customElements.whenDefined(tagName)` and the `sonic-connected` event (or a timeout as fallback)
+- If no matching ancestor is found, the original `connectedCallback` is called immediately
+- Ancestors that do not emit `sonic-connected` trigger the fallback after the timeout (compatibility with existing components)
+
+## Use cases
+
+These decorators are particularly useful for:
+
+- **sonic-value** inside a **sonic-subscriber**: the value waits for the subscriber to configure its publisher
+- **Components inside sonic-sdui**: wait for the SDUI to load and configure its context
+- **Any component** depending on context provided by an ancestor custom element
+
+## Listening to the connected event
+
+The `sonic-connected` event bubbles, so you can listen to it from anywhere:
+
+<sonic-code language="typescript">
+  <template>
+import { CONNECTED } from "@supersoniks/concorde/decorators";
+//
+someConnectable.addEventListener(CONNECTED, (e) => {
+  console.log("Component connected:", e.target);
+});
+  </template>
+</sonic-code>
+
+## Notes
+
+- These decorators apply only to web components (classes extending `HTMLElement`)
+- The fallback timeout ensures compatibility with components that do not yet use `@dispatchConnectedEvent`
+- Traversal includes shadow roots
+- For a guarantee without relying on the timeout, decorate ancestors (Subscriber, Fetcher, etc.) with `@dispatchConnectedEvent`

package/src/docs/example/decorators-demo.ts

@@ -5,6 +5,8 @@ import {
   ancestorAttribute,
   onAssign,
   autoSubscribe,
+  awaitConnectedAncestors,
+  dispatchConnectedEvent,
 } from "@supersoniks/concorde/decorators";
 import { sub } from "@supersoniks/concorde/directives";
 import {
@@ -56,6 +58,7 @@ const initializeDecoratorsDemoData = () => {
 
   ensurePublisherValue("autoValue1", 10);
   ensurePublisherValue("autoValue2", 20);
+  ensurePublisherValue("waitAncestorDemo", { message: "Context from ancestor" });
 
   ensurePublisherValue("combinedData", { title: "Combined Title" });
   ensurePublisherValue("combinedUser", { name: "Combined User" });
@@ -656,3 +659,265 @@ export class DemoAutoSubscribe extends LitElement {
     value.set(Math.floor(Math.random() * 100));
   }
 }
+
+/**
+ * Parent component for awaitConnectedAncestors demo.
+ * Registered via customElements.define() on button click (not @customElement).
+ */
+@dispatchConnectedEvent()
+export class DemoWaitAncestorContainer extends LitElement {
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+/**
+ * Demo component showcasing @awaitConnectedAncestors decorator (child).
+ * Uses CSS selector: tag + attribute.
+ */
+@customElement("demo-wait-ancestor-value")
+@awaitConnectedAncestors("demo-wait-ancestor-container[dataProvider]")
+export class DemoWaitAncestorValue extends LitElement {
+  @ancestorAttribute("dataProvider")
+  dataProvider: string | null = null;
+
+  @state() initializedAt = "";
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.initializedAt = new Date().toISOString();
+  }
+
+  render() {
+    return html`
+      <p>
+        DataProvider from ancestor:
+        <strong>${this.dataProvider || "—"}</strong>
+      </p>
+      <p>Initialized at: ${this.initializedAt || "(waiting for parent…)"}</p>
+    `;
+  }
+}
+
+/**
+ * Demo section with button to register parent component on demand.
+ * Demonstrates that the child waits until the parent is defined.
+ */
+@customElement("demo-wait-ancestors-section")
+export class DemoWaitAncestorsSection extends LitElement {
+  static styles = [tailwind];
+
+  @state() parentRegistered = false;
+
+  registerParent() {
+    if (customElements.get("demo-wait-ancestor-container")) {
+      this.parentRegistered = true;
+      return;
+    }
+    customElements.define(
+      "demo-wait-ancestor-container",
+      DemoWaitAncestorContainer
+    );
+    this.parentRegistered = true;
+  }
+
+  render() {
+    return html`
+      <div class="space-y-4">
+        <sonic-button
+          ?disabled=${this.parentRegistered}
+          @click=${this.registerParent}
+        >
+          ${this.parentRegistered
+            ? "Parent already registered"
+            : "Register parent component"}
+        </sonic-button>
+        <demo-wait-ancestor-container dataProvider="waitAncestorDemo">
+          <demo-wait-ancestor-value></demo-wait-ancestor-value>
+        </demo-wait-ancestor-container>
+      </div>
+    `;
+  }
+}
+
+// --- Multiple ancestors demo ---
+
+@dispatchConnectedEvent()
+export class DemoWaitAncestorOuter extends LitElement {
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+@dispatchConnectedEvent()
+export class DemoWaitAncestorInner extends LitElement {
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+@customElement("demo-wait-ancestor-value-multi")
+@awaitConnectedAncestors("demo-wait-ancestor-outer", "demo-wait-ancestor-inner")
+export class DemoWaitAncestorValueMulti extends LitElement {
+  @ancestorAttribute("dataProvider")
+  dataProvider: string | null = null;
+
+  @state() initializedAt = "";
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.initializedAt = new Date().toISOString();
+  }
+
+  render() {
+    return html`
+      <p>
+        DataProvider from ancestor:
+        <strong>${this.dataProvider || "—"}</strong>
+      </p>
+      <p>Initialized at: ${this.initializedAt || "(waiting for both ancestors…)"}</p>
+    `;
+  }
+}
+
+/**
+ * Demo: child waits for multiple ancestors.
+ * Register outer first, then inner — child initializes only when both are ready.
+ */
+@customElement("demo-wait-ancestors-multi-section")
+export class DemoWaitAncestorsMultiSection extends LitElement {
+  static styles = [tailwind];
+
+  @state() outerRegistered = false;
+  @state() innerRegistered = false;
+
+  registerOuter() {
+    if (!customElements.get("demo-wait-ancestor-outer")) {
+      customElements.define("demo-wait-ancestor-outer", DemoWaitAncestorOuter);
+    }
+    this.outerRegistered = true;
+  }
+
+  registerInner() {
+    if (!customElements.get("demo-wait-ancestor-inner")) {
+      customElements.define("demo-wait-ancestor-inner", DemoWaitAncestorInner);
+    }
+    this.innerRegistered = true;
+  }
+
+  render() {
+    return html`
+      <div class="space-y-4">
+        <div class="flex gap-2 flex-wrap">
+          <sonic-button
+            ?disabled=${this.outerRegistered}
+            @click=${this.registerOuter}
+          >
+            ${this.outerRegistered ? "Outer registered" : "Register outer"}
+          </sonic-button>
+          <sonic-button
+            ?disabled=${this.innerRegistered}
+            @click=${this.registerInner}
+          >
+            ${this.innerRegistered ? "Inner registered" : "Register inner"}
+          </sonic-button>
+        </div>
+        <demo-wait-ancestor-outer>
+          <demo-wait-ancestor-inner dataProvider="waitAncestorDemo">
+            <demo-wait-ancestor-value-multi></demo-wait-ancestor-value-multi>
+          </demo-wait-ancestor-inner>
+        </demo-wait-ancestor-outer>
+      </div>
+    `;
+  }
+}
+
+// --- Ancestors already connected demo ---
+
+@customElement("demo-wait-ancestor-ready")
+@dispatchConnectedEvent()
+export class DemoWaitAncestorReady extends LitElement {
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+@customElement("demo-wait-ancestor-value-ready")
+@awaitConnectedAncestors("demo-wait-ancestor-ready")
+export class DemoWaitAncestorValueReady extends LitElement {
+  @ancestorAttribute("dataProvider")
+  dataProvider: string | null = null;
+
+  @state() initializedAt = "";
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.initializedAt = new Date().toISOString();
+  }
+
+  render() {
+    return html`
+      <p>
+        DataProvider: <strong>${this.dataProvider || "—"}</strong>
+      </p>
+      <p>Initialized at: ${this.initializedAt}</p>
+    `;
+  }
+}
+
+/**
+ * Demo: ancestors already connected at load.
+ * Parent is defined with @customElement. Child is added dynamically — it
+ * initializes immediately because the ancestor is already ready.
+ */
+@customElement("demo-wait-ancestors-ready-section")
+export class DemoWaitAncestorsReadySection extends LitElement {
+  static styles = [tailwind];
+
+  @state() childInDom = false;
+
+  addChild() {
+    this.childInDom = true;
+  }
+
+  render() {
+    return html`
+      <div class="space-y-4">
+        <p class="text-sm text-neutral-600 dark:text-neutral-400">
+          Parent is defined at load. Click to add child dynamically — it
+          initializes immediately because the ancestor is already ready.
+        </p>
+        <sonic-button ?disabled=${this.childInDom} @click=${this.addChild}>
+          ${this.childInDom ? "Child added" : "Add child dynamically"}
+        </sonic-button>
+        <demo-wait-ancestor-ready dataProvider="waitAncestorDemo">
+          ${this.childInDom
+            ? html`<demo-wait-ancestor-value-ready></demo-wait-ancestor-value-ready>`
+            : html``}
+        </demo-wait-ancestor-ready>
+      </div>
+    `;
+  }
+}
+
+/**
+ * Demo: parent and child both in DOM from start, parent defined at load.
+ * Child initializes immediately (no delay) because ancestor is already ready.
+ */
+@customElement("demo-wait-ancestors-static-section")
+export class DemoWaitAncestorsStaticSection extends LitElement {
+  static styles = [tailwind];
+
+  render() {
+    return html`
+      <p class="text-sm text-neutral-600 dark:text-neutral-400 mb-4">
+        Parent and child both in DOM from load. Child initializes immediately
+        because the ancestor is already defined and connected.
+      </p>
+      <demo-wait-ancestor-ready dataProvider="waitAncestorDemo">
+        <demo-wait-ancestor-value-ready></demo-wait-ancestor-value-ready>
+      </demo-wait-ancestor-ready>
+    `;
+  }
+}
+

package/src/docs/navigation/navigation.ts

@@ -146,7 +146,10 @@ export class DocsNavigation extends LitElement {
       label: "@autoSubscribe",
       href: "#docs/_misc/auto-subscribe.md/auto-subscribe",
     },
-
+    {
+      label: "@awaitConnectedAncestors",
+      href: "#docs/_misc/wait-for-ancestors.md/wait-for-ancestors",
+    },
     {
       label: "Templates Demo",
       href: "#docs/_misc/templates-demo.md/templates-demo",