@supersoniks/concorde 4.4.2 → 4.5.1

package/docs/src/docs/_decorators/get.md

@@ -1,65 +0,0 @@
-# @get
-
-Loads data through [`API.getDetailed`](../../core/utils/api.ts). The decorated property is **`ApiGetResult<T> | null`**: `request`, `response` (or `null` for `dataProvider(...)` resolution without HTTP), and typed `result`.
-
-Pass an [`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint) as the first argument. Import `get` and `ApiGetResult` from `@supersoniks/concorde/decorators`, and `Endpoint` from `@supersoniks/concorde/utils/endpoint`.
-
-## Configuration
-
-- **Default:** `HTML.getApiConfiguration(host)` (ancestor `serviceURL`, etc.).
-- **Second argument:** `DataProviderKey<APIConfiguration>` — config is read from the publisher at the resolved path; internal mutations trigger another GET.
-
-## When the GET runs again
-
-- A referenced Lit property changes (endpoint path and/or config key contains `${...}`).
-- `set` on the active configuration publisher (`onInternalMutation`).
-
-## Import
-
-<sonic-code language="typescript">
-  <template>
-import { get, type ApiGetResult } from "@supersoniks/concorde/decorators";
-import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-  </template>
-</sonic-code>
-
-## Minimal example
-
-Same demo service as [`sonic-queue`](../../core/components/functional/queue/queue.demo.ts) (`geo.api.gouv.fr`). Publisher setup lives in `decorators-demo-geo.ts` and `decorators-demo-subscribe-publish-get-demos.ts`.
-
-<sonic-code language="typescript">
-  <template>
-@get(new Endpoint<User>("users/${userId}"))
-@state()
-payload: ApiGetResult<User> | null = null;
-  </template>
-</sonic-code>
-
-## Live demos
-
-<sonic-code>
-  <template>
-    <demo-api-get></demo-api-get>
-  </template>
-</sonic-code>
-
-Dynamic config and endpoint path (`demo-api-get-configuration-key` in doc sources):
-
-<sonic-code>
-  <template>
-    <demo-api-get-configuration-key></demo-api-get-configuration-key>
-  </template>
-</sonic-code>
-
-Scoped `@get` with `@publish` / `@subscribe` on the payload (see [@publish](#docs/_decorators/publish.md/publish) and [@subscribe](#docs/_decorators/subscribe.md/subscribe)) — wrap under an ancestor with `serviceURL="https://geo.api.gouv.fr/"`:
-
-<sonic-code>
-  <template>
-<div serviceURL="https://geo.api.gouv.fr/">
-  <demo-api-get-publish-subscribe></demo-api-get-publish-subscribe>
-</div>
-  </template>
-</sonic-code>
-
-Stale responses are ignored if the path or generation changed before the request finished.

package/docs/src/docs/_decorators/on-assign.md

@@ -1,336 +0,0 @@
-# @onAssign
-
-The `@onAssign` decorator allows you to execute a method when one or more publishers are updated. The method is called only when all specified publishers have been assigned values.
-
-## Principle
-
-This decorator subscribes to one or more publishers via the `PublisherManager`. When all specified publishers have been assigned values (via `set`), the decorated method is called with all the values as arguments.
-
-This is particularly useful when you need to wait for multiple data sources to be ready before executing logic.
-
-## Usage
-
-### Import
-
-<sonic-code language="typescript">
-  <template>
-import { onAssign } from "@supersoniks/concorde/decorators";
-  </template>
-</sonic-code>
-
-### Basic example 
-
-
-<sonic-code language="typescript">
-  <template>
-//...
-@customElement("demo-on-assign")
-export class DemoOnAssign extends LitElement {
-  static styles = [tailwind];
-  //
-  @state() userWithSettings: any = null;
-  @state() isReady: boolean = false;
-  @state() lastUpdate: string = "";
-  //
-  @onAssign("demoUser", "demoUserSettings")
-  handleDataReady(user: any, settings: any) {
-    this.isReady = Object.keys(user).length > 0 && Object.keys(settings).length > 0;
-    this.userWithSettings = { ...user, ...settings };
-    this.lastUpdate = new Date().toLocaleTimeString();
-    this.requestUpdate();
-  }
-  //
-  render() {
-    const { name, email, theme, language } = this.userWithSettings;
-    return //...
-  }
-  //
-  updateData() {
-    const user = PublisherManager.get("demoUser");
-    const userSettings = PublisherManager.get("demoUserSettings");
-    const userNumber = Math.floor(Math.random() * 100);
-    user.set({
-      name: `User n°${userNumber}`,
-      email: `user-${userNumber}@example.com`,
-    });
-    //
-    userSettings.set({
-      theme: ["light", "dark", "auto"][Math.floor(Math.random() * 3)],
-      language: ["en", "fr", "es"][Math.floor(Math.random() * 3)],
-    });
-  }
-}
-  </template>
-</sonic-code>
-
-<sonic-code>
-  <template>
-    <demo-on-assign></demo-on-assign>
-  </template>
-</sonic-code>
-
-
-### Example with nested paths
-
-<sonic-code language="typescript">
-  <template>
-@customElement("product-view")
-export class ProductView extends LitElement {
-  product: any = null;
-  inventory: any = null;
-  //
-  @onAssign("store.product", "store.inventory")
-  handleProductData(product: any, inventory: any) {
-    this.product = product;
-    this.inventory = inventory;
-    this.requestUpdate();
-  }
-  //
-  render() {
-    if (!this.product) return html`<div>Loading...</div>`;
-    //
-    const stock = this.inventory[this.product.id] || 0;
-    return html`
-      <div>
-        <h2>${this.product.name}</h2>
-        <p>Price: ${this.product.price}€</p>
-        <p>Stock: ${stock}</p>
-      </div>
-    `;
-  }
-}
-  </template>
-</sonic-code>
-
-## Path syntax
-
-The path uses dot notation to navigate through the publisher structure:
-
-- **First segment**: dataProvider identifier (e.g., `"userData"`)
-- **Following segments**: nested properties (e.g., `"store.product"`)
-- **Array access**: use numeric index (e.g., `"data.items.0"`)
-
-### Dynamic path driven by class properties
-
-You can now build the paths dynamically by referencing the host class properties inside the strings passed to `@onAssign`. Two placeholder syntaxes are supported:
-
-- `` ${myProperty} `` or `` ${this.myProperty} ``
-- `` {$myProperty} ``
-
-Each placeholder is replaced at runtime with the current value of the corresponding property. `@onAssign` automatically watches those properties and:
-
-- re-evaluates the final paths when one of them changes,
-- removes the previous subscriptions before attaching the new ones,
-- observe the changes inside `willUpdate(changedProperties)` so nothing touches the getters/setters.
-
-
-<sonic-code language="typescript">
-  <template>
-@customElement("demo-on-assign-dynamic")
-export class DemoOnAssignDynamic extends LitElement {
-  static styles = [tailwind];
-  //
-  @property({ type: String })
-  dataProvider: "demoUsers" | "demoUsersAlt" = "demoUsers";
-  //
-  @property({ type: Number })
-  userIndex: number = 0;
-  //
-  @state() user: any = null;
-  @state() userSettings: any = null;
-  //
-  @onAssign("${dataProvider}.${userIndex}", "${dataProvider}Settings.${userIndex}")
-  handleUserDataReady(user: any, settings: any) {
-    this.user = user;
-    this.userSettings = settings;
-  }
-  //
-  updateUserIndex(e: Event) {
-    this.userIndex = parseInt((e.target as HTMLInputElement).value);
-  }
-  //
-  updateDataProvider(e: Event) {
-    this.dataProvider = (e.target as HTMLSelectElement).value as
-      | "demoUsers"
-      | "demoUsersAlt";
-  }
-  //
-  updateCurrentUserData() {
-    const usersPublisher = PublisherManager.get(this.dataProvider);
-    const settingsPublisher = PublisherManager.get(
-      `${this.dataProvider}Settings`
-    );
-    const userPublisher = Objects.traverse(
-      usersPublisher,
-      [String(this.userIndex)]
-    ) as PublisherProxy;
-    const settingPublisher = Objects.traverse(
-      settingsPublisher,
-      [String(this.userIndex)]
-    ) as PublisherProxy;
-    //
-    if (userPublisher && settingPublisher) {
-      // Générer de nouvelles données aléatoires
-      const randomNames = [
-        { firstName: "Alice", lastName: "Wonder" },
-        { firstName: "Bob", lastName: "Builder" },
-        { firstName: "Charlie", lastName: "Chaplin" },
-      ];
-      const randomThemes = ["light", "dark", "auto"];
-      const randomLanguages = ["en", "fr", "es"];
-      //
-      const randomName =
-        randomNames[Math.floor(Math.random() * randomNames.length)];
-      const randomEmail = `${randomName.firstName.toLowerCase()}.${randomName.lastName.toLowerCase()}@example.com`;
-      const randomTheme =
-        randomThemes[Math.floor(Math.random() * randomThemes.length)];
-      const randomLanguage =
-        randomLanguages[Math.floor(Math.random() * randomLanguages.length)];
-      //
-      // Mettre à jour l'utilisateur directement
-      const currentUser = userPublisher.get() || {};
-      userPublisher.set({
-        ...currentUser,
-        firstName: randomName.firstName,
-        lastName: randomName.lastName,
-        email: randomEmail,
-      });
-      //
-      // Mettre à jour les settings directement
-      settingPublisher.set({
-        theme: randomTheme,
-        language: randomLanguage,
-      });
-    }
-  }
-  //
-  render() {
-    return html`
-      <div class="flex flex-col gap-2">
-        <sonic-select label="Users set" @change=${this.updateDataProvider}>
-          <option value="demoUsers">First set of users</option>
-          <option value="demoUsersAlt">Second set of users</option>
-        </sonic-select>
-        <sonic-input
-          type="number"
-          .value=${this.userIndex}
-          @input=${this.updateUserIndex}
-          min="0"
-          max="9"
-          label="Index"
-          class="block"
-        >
-        </sonic-input>
-        <sonic-button @click=${this.updateCurrentUserData}
-          >Update current user data</sonic-button
-        >
-        <div class="flex flex-col gap-2 border p-2">
-          <div>
-            <sonic-icon name="user" library="heroicons"></sonic-icon>
-            ${this.user?.firstName} ${this.user?.lastName}
-          </div>
-          <div>
-            <sonic-icon name="envelope" library="heroicons"></sonic-icon>
-            ${this.user?.email}
-          </div>
-          <div>
-            Theme: ${this.userSettings?.theme} | Language:
-            ${this.userSettings?.language}
-          </div>
-        </div>
-      </div>
-    `;
-  }
-}
-  </template>
-</sonic-code>
-
-<sonic-code>
-  <template>
-    <demo-on-assign-dynamic></demo-on-assign-dynamic>
-  </template>
-</sonic-code>
-
-> ⚠️ Use classic string literals: `@onAssign("${dataProvider}.${profileId}", "settings.${profileId}")`. Do **not** use template literals (backticks), otherwise JavaScript would try to interpolate the value immediately.
-
-Additional constraints:
-
-- The hosting class must expose a `willUpdate(changedProperties?: Map<PropertyKey, unknown>)` method (LitElement already provides it) so that `@onAssign` can listen to dependency changes.
-- Dependencies need to be reactive (e.g. `@property()` on LitElement) or you must call `this.requestUpdate("myProp")` manually after changing them, otherwise `willUpdate` will never be notified.
-- If you use nested expressions like `${user.id}`, the first segment (`user`) is the one being observed: you need to reassign `this.user` (e.g. with a new object) so that the binding can detect the change.
-
-## Behavior
-
-- The method is called only when **all** specified publishers have been assigned values
-- The method receives the values of all publishers as arguments, in the same order as specified
-- Subscription happens at the time of `connectedCallback`
-- Unsubscription happens automatically at the time of `disconnectedCallback`
-- If a publisher doesn't exist yet, it will be created with the value `null`
-- The method is called with `this` bound to the component instance
-
-## Use cases
-
-This decorator is particularly useful for:
-
-- **Waiting for multiple data sources** before rendering or executing logic
-- **Synchronizing data** from different publishers
-- **Initializing components** that depend on multiple data providers
-- **Handling complex data dependencies** where you need all data to be ready
-
-## Complete example
-
-<sonic-code language="typescript">
-  <template>
-import { html, LitElement } from "lit";
-import { customElement } from "lit/decorators.js";
-import { onAssign } from "@supersoniks/concorde/decorators";
-import { PublisherManager } from "@supersoniks/concorde/core/utils/PublisherProxy";
-//
-@customElement("order-summary")
-export class OrderSummary extends LitElement {
-  order: any = null;
-  customer: any = null;
-  shipping: any = null;
-  //
-  @onAssign("orderData", "customerData", "shippingData")
-  handleOrderReady(order: any, customer: any, shipping: any) {
-    this.order = order;
-    this.customer = customer;
-    this.shipping = shipping;
-    this.requestUpdate();
-  }
-  //
-  render() {
-    if (!this.order || !this.customer || !this.shipping) {
-      return html`<div>Loading order details...</div>`;
-    }
-    //
-    return html`
-      <div class="order-summary">
-        <h2>Order #${this.order.id}</h2>
-        <p>Customer: ${this.customer.name}</p>
-        <p>Shipping to: ${this.shipping.address}</p>
-        <p>Total: ${this.order.total}€</p>
-      </div>
-    `;
-  }
-}
-// Somewhere in your code, update the publishers:
-const orderPub = PublisherManager.get("orderData");
-const customerPub = PublisherManager.get("customerData");
-const shippingPub = PublisherManager.get("shippingData");
-// The method will be called only when all three are set:
-orderPub.set({ id: "123", total: 99.99 });
-customerPub.set({ name: "John Doe", email: "john@example.com" });
-shippingPub.set({ address: "123 Main St" });
-// handleOrderReady will be called with all three values
-  </template>
-</sonic-code>
-
-## Notes
-
-- This decorator works with any component that has `connectedCallback` and `disconnectedCallback` methods (such as `LitElement` or components extending `Subscriber`)
-- The method is called synchronously when all publishers are ready
-- If you need to update the UI, remember to call `this.requestUpdate()` inside the method
-- For more information about publishers, see the documentation on [Sharing data](#docs/_getting-started/pubsub.md/pubsub)
-

package/docs/src/docs/_decorators/publish.md

@@ -1,54 +0,0 @@
-# @publish
-
-Write-only binding: assigning to the property publishes to the `DataProviderKey` path. No read subscription (inverse of [@subscribe](#docs/_decorators/subscribe.md/subscribe)).
-
-Similar to the “reflect” half of [@bind](#docs/_decorators/bind.md/bind) without listening to the publisher.
-
-## Import
-
-<sonic-code language="typescript">
-  <template>
-import { publish } from "@supersoniks/concorde/decorators";
-import { sub } from "@supersoniks/concorde/directives";
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-  </template>
-</sonic-code>
-
-## Example
-
-<sonic-code language="typescript">
-  <template>
-type PublishDemoData = { email: string; message: string };
-const publishDemoKey = new DataProviderKey<PublishDemoData>("publishDemo");
-//
-@customElement("demo-publish")
-export class DemoPublish extends LitElement {
-  @publish(publishDemoKey.email)
-  @state()
-  email = "";
-  //
-  @publish(publishDemoKey.message)
-  @state()
-  message = "";
-  //
-  render() {
-    return html`
-      <sonic-input
-        .value=${this.email}
-        @input=${(e) => (this.email = (e.target as HTMLInputElement).value)}
-        label="Email"
-      ></sonic-input>
-      <p>${sub("publishDemo.email")}</p>
-    `;
-  }
-}
-  </template>
-</sonic-code>
-
-<sonic-code>
-  <template>
-    <demo-publish></demo-publish>
-  </template>
-</sonic-code>
-
-Dynamic paths use the same placeholder rules as `@bind` / `@subscribe`.

package/docs/src/docs/_decorators/subscribe.md

@@ -1,36 +0,0 @@
-# @subscribe
-
-Read-only binding: **only** `DataProviderKey<T>` (no legacy string path). No `reflect` option — the publisher updates the property, not the other way around.
-
-For bidirectional binding or string paths, use [@bind](#docs/_decorators/bind.md/bind).
-
-## Import
-
-<sonic-code language="typescript">
-  <template>
-import { subscribe } from "@supersoniks/concorde/decorators";
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-//
-type Data = { count: number };
-const dataKey = new DataProviderKey<Data>("data");
-//
-@subscribe(dataKey.count)
-@state()
-count = 0;
-  </template>
-</sonic-code>
-
-## Highlights
-
-- Strict typing: the property type must match `T`.
-- Dynamic paths: placeholders in `DataProviderKey`, resolved from the host component’s properties.
-
-## Demo
-
-<sonic-code>
-  <template>
-    <demo-subscribe-dynamic></demo-subscribe-dynamic>
-  </template>
-</sonic-code>
-
-See also [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey).

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

@@ -1,160 +0,0 @@
-# @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`