@supersoniks/concorde 4.2.0 → 4.3.0

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/src/docs/{_misc → _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).

package/src/docs/_misc/dataProviderKey.md

@@ -0,0 +1,135 @@
+# DataProviderKey
+
+The `DataProviderKey<T>` utility provides type-safe navigation through composite data structures. Each property or index access extends the path, and the final key can be retrieved via `toString()` or the `path` property.
+
+For a **single HTTP path string** (no dot-syntax), see [Endpoint](#docs/_misc/endpoint.md/endpoint).
+
+## Principle
+
+`DataProviderKey` uses a Proxy to intercept property access and build a cumulative path string. TypeScript infers the nested type at each level, so `myKey.items[0]` is correctly typed as `DataProviderKey<Item>` when `items` is `Item[]`.
+
+## Usage
+
+### Import
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+  </template>
+</sonic-code>
+
+### Basic example
+
+<sonic-code language="typescript">
+  <template>
+type Item = { id: string; name: string };
+//
+type Data = {
+  items: Item[];
+  count: number;
+};
+//
+const myKey = new DataProviderKey&lt;Data&gt;("data").items[0];
+// Equivalent to: new DataProviderKey&lt;Item&gt;("data.items.0")
+myKey.toString();  // "data.items.0"
+myKey.path;        // same value
+// myKey is typed as DataProviderKey&lt;Item&gt;
+  </template>
+</sonic-code>
+
+### Object property access
+
+<sonic-code language="typescript">
+  <template>
+const key = new DataProviderKey&lt;Data&gt;("data");
+const countKey = key.count;
+countKey.path;        // "data.count"
+countKey.toString();  // "data.count"
+  </template>
+</sonic-code>
+
+### Array index access
+
+<sonic-code language="typescript">
+  <template>
+const itemsKey = new DataProviderKey&lt;Data&gt;("data").items;
+itemsKey.path;  // "data.items"
+// itemsKey is DataProviderKey&lt;Item[]&gt;
+//
+const firstItem = itemsKey[0];
+firstItem.path;  // "data.items.0"
+// firstItem is DataProviderKey&lt;Item&gt;
+  </template>
+</sonic-code>
+
+### Dynamic paths
+
+Use placeholders `${prop}` or `{$prop}` in the path string. The path is resolved at runtime from the component's properties. The type remains declarative:
+
+<sonic-code language="typescript">
+  <template>
+type User = { name: string; email: string };
+//
+// Path resolved from component.userIndex at runtime
+@subscribe(new DataProviderKey&lt;User&gt;("users.${userIndex}"))
+@state()
+user: User | null = null;
+  </template>
+</sonic-code>
+
+## Path retrieval
+
+The final path is built by concatenating each accessed property with a dot:
+
+- `new DataProviderKey<T>("base")` → `"base"`
+- `key.prop` → `"base.prop"`
+- `key.items[0]` → `"base.items.0"`
+
+Use `toString()` or `path` to get the full path string:
+
+<sonic-code language="typescript">
+  <template>
+const key = new DataProviderKey&lt;Data&gt;("data").count;
+const pathString = key.toString();  // "data.count"
+const pathProp = key.path;           // "data.count"
+  </template>
+</sonic-code>
+
+## Use cases
+
+- **Type-safe bindings**: paths for `@bind`, `@subscribe`, `@publish`
+- **Dynamic paths**: reusable keys with `${...}` placeholders
+- **Form fields**: form data paths with compile-time checking
+
+## Integration with @subscribe and @publish
+
+Use `DataProviderKey` with `@subscribe` (read-only) or `@publish` (write-only). The decorated property **must** match the key’s value type:
+
+<sonic-code language="typescript">
+  <template>
+import { subscribe } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+//
+type FormData = { email: string };
+const formKey = new DataProviderKey&lt;FormData&gt;("formData");
+//
+@customElement("user-form")
+export class UserForm extends LitElement {
+  @subscribe(formKey.email)
+  @state()
+  email = "";
+//
+  render() {
+    return html`&lt;input .value=${this.email} @input=${(e) => this.email = (e.target as HTMLInputElement).value}&gt;`;
+  }
+}
+  </template>
+</sonic-code>
+
+Both decorators support dynamic paths: `"base.${prop}"` in the constructor. A wrong property type (e.g. `number` for `DataProviderKey<string>`) is a TypeScript error.
+
+## Notes
+
+- Function properties are excluded from navigation (no `key.method()` chaining)
+- Primitives have no navigable properties
+- The `path` property and `toString()` are equivalent for retrieving the key

package/src/docs/_misc/endpoint.md

@@ -0,0 +1,42 @@
+# Endpoint
+
+`Endpoint<T, U>` describes a single HTTP path (or a path accepted by `API.get`) and carries the expected response type `T`. Unlike [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey), there is no dot-navigation: the path is one string.
+
+The optional second generic `U` (default `any`) describes host properties used to resolve dynamic segments in the path (`${…}` / `{$…}`), for example with the [@get](#docs/_decorators/get.md/get) decorator.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
+  </template>
+</sonic-code>
+
+## Construction
+
+<sonic-code language="typescript">
+  <template>
+const users = new Endpoint&lt;User[]&gt;("users?limit=10");
+users.path; // "users?limit=10"
+//
+const one = new Endpoint&lt;User, { userId: string }&gt;("users/${userId}");
+// `userId` on the host class is observed when used with @get
+  </template>
+</sonic-code>
+
+## Normalization
+
+`Endpoint.normalizePath` trims the string, rejects an empty path, strips leading slashes for paths relative to `serviceURL`, collapses duplicate slashes, and validates absolute `http(s)://` URLs.
+
+## Publisher key for payloads
+
+`getDataProviderKey()` returns a typed publisher key whose `path` matches the endpoint path (payload typing follows `ApiGetResult` for this endpoint). Useful when pairing `@get` with `@publish` / `@subscribe` (see [@get](#docs/_decorators/get.md/get)).
+
+## Data-provider paths
+
+`Endpoint.looksLikeDataProviderPath(path)` returns true for strings shaped like `dataProvider(id)…`, which `API.get` can resolve without HTTP.
+
+## See also
+
+- [@get](#docs/_decorators/get.md/get) — decorator that uses `Endpoint<T>`
+- [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) — typed publisher paths (dot notation)