@supersoniks/concorde 4.2.1 → 4.4.0

package/src/core/utils/dataProviderKey.ts

@@ -0,0 +1,86 @@
+/**
+ * Type-safe navigation through composite data structures (publisher paths).
+ * Each property or index access extends the path. Retrieve the final path via toString() or path.
+ * Supports dynamic paths: use placeholders like "users.${userIndex}" in the constructor.
+ *
+ * @example
+ * const myKey = new DataProviderKey<Data>("data").items[0];
+ * myKey.toString();  // "data.items.0"
+ * myKey.path;        // same
+ *
+ * @example
+ * // U = dépendances dynamiques sur l’hôte (voir DataProviderKeyHost) — propagé sur .foo.bar
+ * new DataProviderKey<User, { userIndex: number }>("demoUsers.${userIndex}");
+ */
+
+type IsAny<T> = 0 extends 1 & T ? true : false;
+
+/**
+ * Prototype de classe décorée : propriétés minimales attendues sur l’hôte quand la clé est
+ * `DataProviderKey<…, U>` (U renseigné à la construction). Avec `U` par défaut (`any`), pas de contrainte.
+ */
+export type DataProviderKeyHost<U> = IsAny<U> extends true
+  ? object
+  : keyof U extends never
+    ? object
+    : object & U;
+
+/**
+ * U : forme minimale du composant pour résoudre les placeholders `${…}` du path ; inchangée lors de la navigation.
+ */
+type DataProviderKeyProxy<T, U = any> = T extends object
+  ? {
+      [K in keyof T as T[K] extends (...args: unknown[]) => unknown
+        ? never
+        : K]: DataProviderKey<T[K], U>;
+    }
+  : object;
+
+export type DataProviderKey<T, U = any> = DataProviderKeyImpl<T, U> &
+  DataProviderKeyProxy<T, U>;
+
+class DataProviderKeyImpl<T, U = any> {
+  declare readonly _phantom?: T;
+  declare readonly _phantomDeps?: U;
+
+  constructor(public readonly path: string) {}
+
+  toString(): string {
+    return this.path;
+  }
+}
+
+function createDataProviderKeyProxy<T, U = any>(
+  key: DataProviderKeyImpl<T, U>,
+): DataProviderKey<T, U> {
+  return new Proxy(key, {
+    get(target, prop: string | symbol) {
+      if (prop === "path") return target.path;
+      if (prop === "toString") return target.toString.bind(target);
+      if (prop === Symbol.toStringTag) return "DataProviderKey";
+      if (typeof prop === "symbol")
+        return (target as unknown as Record<symbol, unknown>)[prop];
+      const newPath = target.path
+        ? `${target.path}.${String(prop)}`
+        : String(prop);
+      return createDataProviderKeyProxy(
+        new DataProviderKeyImpl<unknown, U>(newPath),
+      );
+    },
+  }) as DataProviderKey<T, U>;
+}
+
+export interface DataProviderKeyConstructor {
+  new <T, U = any>(path: string): DataProviderKey<T, U>;
+}
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export const DataProviderKey: DataProviderKeyConstructor = function (
+  this: any,
+  path: string,
+): DataProviderKey<unknown, any> {
+  if (!(this instanceof DataProviderKey)) {
+    return new (DataProviderKey as DataProviderKeyConstructor)(path);
+  }
+  return createDataProviderKeyProxy(new DataProviderKeyImpl(path));
+} as any;

package/src/core/utils/endpoint.spec.ts

@@ -0,0 +1,41 @@
+import { describe, it, expect } from "vitest";
+import { Endpoint } from "./endpoint";
+
+describe("Endpoint", () => {
+  it("expose le path normalisé (trim)", () => {
+    const e = new Endpoint<{ x: number }>("  communes?limit=1  ");
+    expect(e.path).toBe("communes?limit=1");
+    expect(e.toString()).toBe("communes?limit=1");
+  });
+
+  it("refuse le path vide", () => {
+    expect(() => new Endpoint("")).toThrow(RangeError);
+    expect(() => new Endpoint("   ")).toThrow(RangeError);
+  });
+
+  it("normalizePath et isNonEmpty", () => {
+    expect(Endpoint.normalizePath("a")).toBe("a");
+    expect(Endpoint.isNonEmpty(" x ")).toBe(true);
+    expect(Endpoint.isNonEmpty("")).toBe(false);
+  });
+
+  it("normalizePath enlève le slash initial et les doubles slash (relatif)", () => {
+    expect(Endpoint.normalizePath("/users/1")).toBe("users/1");
+    expect(Endpoint.normalizePath("//users//1")).toBe("users/1");
+    expect(Endpoint.normalizePath("v1//users//x?limit=1")).toBe(
+      "v1/users/x?limit=1",
+    );
+  });
+
+  it("normalizePath pour URL absolue : pathname sans doubles slash", () => {
+    expect(
+      Endpoint.normalizePath("https://example.com/api//v1//x"),
+    ).toBe("https://example.com/api/v1/x");
+  });
+
+  it("looksLikeDataProviderPath", () => {
+    expect(Endpoint.looksLikeDataProviderPath("dataProvider(foo)")).toBe(true);
+    expect(Endpoint.looksLikeDataProviderPath("  DataProvider(x)")).toBe(true);
+    expect(Endpoint.looksLikeDataProviderPath("users/1")).toBe(false);
+  });
+});

package/src/core/utils/endpoint.ts

@@ -0,0 +1,87 @@
+import { ApiGetResult } from "./api";
+import { DataProviderKey } from "./dataProviderKey";
+
+/**
+ * Représente un chemin d’endpoint HTTP (ou path accepté par `API.get`),
+ * typé par la forme de la réponse attendue `T`.
+ *
+ * **`U` (optionnel, défaut `any`)** : propriétés minimales sur le composant pour résoudre les
+ * segments dynamiques du path (`${…}` / `{$…}`), comme pour `DataProviderKey<T, U>`. Utilisé par `@get`.
+ *
+ * Contrairement à `DataProviderKey`, il n’y a **pas** de navigation par propriétés
+ * (pas de dot-syntax) : le path est une seule chaîne.
+ *
+ * @example
+ * new Endpoint<User, { userId: string }>("users/${userId}");
+ */
+export class Endpoint<T, U = any> {
+  declare readonly _phantom?: T;
+  declare readonly _phantomHost?: U;
+
+  readonly path: string;
+
+  constructor(path: string) {
+    this.path = Endpoint.normalizePath(path);
+  }
+
+  /** Même path qu’`Endpoint` ; le 2ᵉ générique `U` est propagé sur la clé publisher. */
+  getDataProviderKey(): DataProviderKey<ApiGetResult<T>, U> {
+    return new DataProviderKey<ApiGetResult<T>, U>(this.path);
+  }
+
+  /**
+   * Trim, refuse le path vide, enlève les `/` en tête (path relatif au `serviceURL`),
+   * et fusionne les `/` successifs en un seul.
+   * Pour une URL absolue (`http://` / `https://`), normalise surtout le pathname (pas de `//` redondants).
+   */
+  static normalizePath(path: string): string {
+    const t = String(path).trim();
+    if (!t) {
+      throw new RangeError("Endpoint: path cannot be empty");
+    }
+
+    if (/^https?:\/\//i.test(t)) {
+      let u: URL;
+      try {
+        u = new URL(t);
+      } catch {
+        throw new RangeError("Endpoint: invalid absolute URL");
+      }
+      u.pathname = u.pathname.replace(/\/+/g, "/");
+      return u.href;
+    }
+
+    const q = t.indexOf("?");
+    const hash = t.indexOf("#");
+    let end = t.length;
+    if (q >= 0) end = Math.min(end, q);
+    if (hash >= 0) end = Math.min(end, hash);
+    let base = t.slice(0, end);
+    const tail = t.slice(end);
+
+    base = base.replace(/^\/+/, "");
+    base = base.replace(/\/+/g, "/");
+
+    if (!base && tail) {
+      throw new RangeError("Endpoint: path cannot be empty");
+    }
+
+    return base + tail;
+  }
+
+  /** Utile avant construction dynamique. */
+  static isNonEmpty(path: string): boolean {
+    return String(path).trim().length > 0;
+  }
+
+  /**
+   * Indique un path local du type `dataProvider(id)…` reconnu par `API.get`.
+   */
+  static looksLikeDataProviderPath(path: string): boolean {
+    return /^\s*dataProvider\s*\(/i.test(String(path));
+  }
+
+  toString(): string {
+    return this.path;
+  }
+}

package/src/decorators.ts

@@ -1,11 +1,22 @@
 import * as mySubscriber from "@supersoniks/concorde/core/decorators/Subscriber";
+import * as api from "@supersoniks/concorde/core/decorators/api";
+import { Endpoint } from "./core/utils/endpoint";
 import * as lifecycle from "@supersoniks/concorde/core/decorators/lifecycle";
 
 export const bind = mySubscriber.bind;
+export const publish = mySubscriber.publish;
+export const subscribe = mySubscriber.subscribe;
 export const onAssign = mySubscriber.onAssign;
 export const ancestorAttribute = mySubscriber.ancestorAttribute;
 export const autoSubscribe = mySubscriber.autoSubscribe;
 export const autoFill = mySubscriber.autoFill;
+export const get = api.get;
+export {
+  DataProviderKey,
+  type DataProviderKeyHost,
+} from "./core/utils/dataProviderKey";
+export { Endpoint };
+export type { ApiGetResult } from "./core/utils/api";
 export const awaitConnectedAncestors = lifecycle.awaitConnectedAncestors;
 export const dispatchConnectedEvent = lifecycle.dispatchConnectedEvent;
 export const CONNECTED = lifecycle.CONNECTED;
@@ -17,8 +28,11 @@ window["concorde-decorator-subscriber"] =
   window["concorde-decorator-subscriber"] || {};
 window["concorde-decorator-subscriber"] = {
   bind: mySubscriber.bind,
+  publish: mySubscriber.publish,
+  subscribe: mySubscriber.subscribe,
   onAssing: mySubscriber.onAssign,
   ancestorAttribute: mySubscriber.ancestorAttribute,
   autoSubscribe: mySubscriber.autoSubscribe,
   autoFill: mySubscriber.autoFill,
+  get: api.get,
 };

package/{docs/src/docs/_misc → src/docs/_decorators}/ancestor-attribute.md

@@ -17,45 +17,29 @@ import { ancestorAttribute } from "@supersoniks/concorde/decorators";
 </sonic-code>
 
 ### Basic example
-Le composant lit les attributs `dataProvider` et `testAttribute` exposés par son conteneur ancêtre.
+
+The component reads `dataProvider` and `testAttribute` from its ancestor wrapper.
 
 <sonic-code language="typescript">
   <template>
-//...
-@customElement("demo-bind-reflect")
-export class DemoBindReflect extends LitElement {
-  static styles = [tailwind];
+import { html, LitElement } from "lit";
+import { customElement } from "lit/decorators.js";
+import { ancestorAttribute } from "@supersoniks/concorde/decorators";
 //
-  @bind("bindReflectDemo.count", { reflect: true })
-  @state()
-  withReflect: number = 0;
+@customElement("demo-ancestor-attribute")
+export class DemoAncestorAttribute extends LitElement {
+  @ancestorAttribute("dataProvider")
+  dataProvider: string | null = null;
 //
-  @bind("bindReflectDemo.count")
-  @state()
-  withoutReflect: number = 0;
-  // initialize the publisher data
-  connectedCallback() {
-    super.connectedCallback();
-    this.resetData();
-  }
+  @ancestorAttribute("testAttribute")
+  testAttribute: string | null = null;
 //
-  resetData() {
-    PublisherManager.get("bindReflectDemo").set({ count: 0 });
-  }
   render() {
     return html`
-      <div class="mb-3">
-        from publisher : ${sub("bindReflectDemo.count")} <br />
-        from component with reflect : ${this.withReflect} <br />
-        from component without reflect : ${this.withoutReflect}
-      </div>
-      <sonic-button @click=${() => this.withReflect++}
-        >Increment with reflect</sonic-button
-      >
-      <sonic-button @click=${() => this.withoutReflect++}
-        >Increment without reflect</sonic-button
-      >
-      <sonic-button @click=${this.resetData}>Reset publisher data</sonic-button>
+      <section>
+        <p>dataProvider: <strong>${this.dataProvider || "null"}</strong></p>
+        <p>testAttribute: <strong>${this.testAttribute || "null"}</strong></p>
+      </section>
     `;
   }
 }

package/src/docs/_decorators/bind.md

@@ -0,0 +1,164 @@
+# @bind
+
+Binds a class property to a path in a publisher. The property updates when publisher data changes.
+
+For Lit re-renders, also add `@state()` on the same property.
+
+**See also:** [@subscribe](#docs/_decorators/subscribe.md/subscribe), [@publish](#docs/_decorators/publish.md/publish), [@get](#docs/_decorators/get.md/get).
+
+## Principle
+
+The decorator subscribes via `PublisherManager` using dot notation. Publisher updates flow into the decorated property.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { bind } from "@supersoniks/concorde/decorators";
+  </template>
+</sonic-code>
+
+## Example
+
+<sonic-code language="typescript">
+<template>
+@customElement("demo-bind")
+export class DemoBind extends LitElement {
+  static styles = [tailwind];
+  //
+  @bind("demoData.firstName")
+  @state()
+  firstName = "";
+  //
+  @bind("demoData.lastName")
+  @state()
+  lastName: string = "";
+  //
+  @bind("demoData.count")
+  @state()
+  count: number = 0;
+  //
+  render() {
+    return //......
+  }
+  //
+  updateData() {
+    const demoData = PublisherManager.get("demoData");
+    const demoUsers = PublisherManager.get("demoUsers");
+    const randomIndex = Math.floor(Math.random() * demoUsers.get().length);
+    const randomUser = demoUsers.get()[randomIndex];
+    demoData.set({
+      firstName: randomUser.firstName,
+      lastName: randomUser.lastName,
+      count: (demoData.count.get() || 0) + 1,
+    });
+  }
+}
+//
+</template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <demo-bind></demo-bind>
+  </template>
+</sonic-code>
+
+## `DataProviderKey` (strict typing)
+
+`@bind` accepts either a string path (legacy) or a `DataProviderKey<T>`. The property type must match `T`. Use `reflect: true` to push local writes back to the publisher (see below). See [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey).
+
+<sonic-code language="typescript">
+  <template>
+import { bind } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+//
+type Data = { count: number };
+const dataKey = new DataProviderKey<Data>("data");
+//
+@bind(dataKey.count, { reflect: true })
+@state()
+count: number = 0;
+  </template>
+</sonic-code>
+
+## Reflect (`reflect: true`)
+
+Two-way sync: reads from the publisher and local assignments call `publisher.set(...)`. An internal guard avoids infinite loops.
+
+<sonic-code language="typescript">
+  <template>
+@bind("userData.profile.avatarUrl", { reflect: true })
+@state()
+avatar: string;
+  </template>
+</sonic-code>
+
+<sonic-code language="typescript">
+  <template>
+@customElement("demo-bind-reflect")
+export class DemoBindReflect extends LitElement {
+  static styles = [tailwind];
+//
+  @bind("bindReflectDemo.count", { reflect: true })
+  @state()
+  withReflect: number = 0;
+//
+  @bind("bindReflectDemo.count")
+  @state()
+  withoutReflect: number = 0;
+//
+  render() {
+    return html`
+      <div class="mb-3">
+        from publisher : ${sub("bindReflectDemo.count") || 0} <br />
+        from component with reflect : ${this.withReflect || 0} <br />
+        from component without reflect : ${this.withoutReflect || 0}
+      </div>
+      <sonic-button @click=${() => this.withReflect++}
+        >Increment with reflect</sonic-button
+      >
+      <sonic-button @click=${() => this.withoutReflect++}
+        >Increment without reflect</sonic-button
+      >
+    `;
+  }
+}
+//
+</template>
+</sonic-code>
+
+<sonic-code toggleCode>
+  <template>
+<demo-bind-reflect></demo-bind-reflect>
+  </template>
+</sonic-code>
+
+## Path syntax
+
+- First segment: data provider id.
+- Nested properties: dot notation.
+- Arrays: numeric index (`items.0`).
+
+### Dynamic paths
+
+Use `${prop}` or `${this.prop}` inside a **normal string literal** (not a JS template literal with backticks). `@bind` re-subscribes when a reactive dependency changes.
+
+> Properties referenced in the pattern must be reactive (`@property`, etc.) or you must call `requestUpdate` manually.
+
+<sonic-code>
+  <template>
+    <demo-bind-dynamic></demo-bind-dynamic>
+  </template>
+</sonic-code>
+
+## Behavior
+
+- Subscribes at `connectedCallback`, unsubscribes at `disconnectedCallback`.
+- If the path does not exist yet, a publisher may be created with `null`.
+
+## Notes
+
+Works with any component that has the usual DOM lifecycle (`LitElement`, `Subscriber` mixin, etc.).
+
+Shared data: [Sharing data](#docs/_getting-started/pubsub.md/pubsub).

package/src/docs/_decorators/get.md

@@ -0,0 +1,65 @@
+# @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/src/docs/_decorators/publish.md

@@ -0,0 +1,54 @@
+# @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/src/docs/_decorators/subscribe.md

@@ -0,0 +1,36 @@
+# @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).