@supersoniks/concorde 3.3.3 → 4.1.0

package/src/directives.ts

@@ -1,21 +1,35 @@
-import * as myDataProvider from "@supersoniks/concorde/core/directives/DataProvider";
+import * as directives from "@supersoniks/concorde/core/directives/DataProvider";
+import {dp as pubDp, dataProvider as pubDataProvider, get as pubGet, set as pubSet} from "@supersoniks/concorde/core/utils/PublisherProxy";
 
 import {ConcordeWindow} from "./core/_types/types";
-export const dp = myDataProvider.dp;
-export const dataProvider = myDataProvider.dataProvider;
-export const subscribe = myDataProvider.subscribe;
-export const sub = myDataProvider.sub;
-export const get = myDataProvider.get;
-export const set = myDataProvider.set;
+/**
+ * @deprecated @see pubDp
+ */
+export const dp = pubDp;
+/**
+ * @deprecated @see pubDataProvider
+ */
+export const dataProvider = pubDataProvider;
+export const subscribe = directives.subscribe;
+export const sub = directives.sub;
+
+/**
+ * @deprecated @see pubGet
+ */
+export const get = pubGet;
+/**
+ * @deprecated @see pubSet
+ */
+export const set = pubSet;
 
 declare const window: ConcordeWindow;
 
 window["concorde-directives-data-provider"] = window["concorde-directives-data-provider"] || {};
 window["concorde-directives-data-provider"] = {
-  dp: myDataProvider.dp,
-  dataProvider: myDataProvider.dataProvider,
-  sub: myDataProvider.sub,
-  subscribe: myDataProvider.subscribe,
-  get: myDataProvider.get,
-  set: myDataProvider.set,
+  dp: pubDp,
+  dataProvider: pubDataProvider,
+  sub: directives.sub,
+  subscribe: directives.subscribe,
+  get: pubGet,
+  set: pubSet,
 };

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",