@supersoniks/concorde 4.2.1 → 4.4.0

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)

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

@@ -0,0 +1,210 @@
+import { html, LitElement } from "lit";
+import { customElement, property, state } from "lit/decorators.js";
+import { bind } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/core/utils/dataProviderKey";
+import { sub } from "@supersoniks/concorde/directives";
+import {
+  PublisherManager,
+  PublisherProxy,
+} from "@supersoniks/concorde/core/utils/PublisherProxy";
+import { Objects } from "@supersoniks/concorde/utils";
+import { tailwind } from "../tailwind";
+import "./decorators-demo-init";
+
+@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 html`
+      <div>
+        <sonic-button @click=${this.updateData}>Update Data</sonic-button>
+      </div>
+      <div class="p-3">
+        <p>Title: <strong>${this.firstName || "Not set"}</strong></p>
+        <p>User Name: <strong>${this.lastName || "Not set"}</strong></p>
+        <p>Number of updates: <strong>${this.count}</strong></p>
+      </div>
+    `;
+  }
+
+  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,
+    });
+  }
+}
+
+@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;
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.resetData();
+  }
+
+  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>
+    `;
+  }
+}
+
+type BindReflectDemoData = { count: number };
+const bindReflectDemoKey = new DataProviderKey<BindReflectDemoData>("bindReflectDemo");
+
+@customElement("demo-bind-key")
+export class DemoBindKey extends LitElement {
+  static styles = [tailwind];
+
+  @bind(bindReflectDemoKey.count, { reflect: true })
+  @state()
+  count: number = 0;
+
+  connectedCallback() {
+    super.connectedCallback();
+    PublisherManager.get("bindReflectDemo").set({ count: 0 });
+  }
+
+  render() {
+    return html`
+      <div class="mb-3">
+        <p>@bind with DataProviderKey&lt;number&gt; (type-safe): ${this.count}</p>
+      </div>
+      <sonic-button @click=${() => this.count++}>Increment</sonic-button>
+    `;
+  }
+}
+
+@customElement("demo-bind-dynamic")
+export class DemoBindDynamic extends LitElement {
+  static styles = [tailwind];
+
+  @property({ type: String })
+  dataProvider: "demoUsers" | "demoUsersAlt" = "demoUsers";
+
+  @property({ type: Number })
+  userIndex: number = 1;
+
+  @bind("${dataProvider}.${userIndex}")
+  @state()
+  user: any = {};
+
+  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 userPublisher = Objects.traverse(usersPublisher, [
+      String(this.userIndex),
+    ]) as PublisherProxy;
+
+    if (userPublisher) {
+      const randomNames = [
+        { firstName: "Alice", lastName: "Wonder" },
+        { firstName: "Bob", lastName: "Builder" },
+        { firstName: "Charlie", lastName: "Chaplin" },
+        { firstName: "Diana", lastName: "Prince" },
+        { firstName: "Eve", lastName: "Adams" },
+      ];
+
+      const randomName =
+        randomNames[Math.floor(Math.random() * randomNames.length)];
+      const randomEmail = `${randomName.firstName.toLowerCase()}.${randomName.lastName.toLowerCase()}@example.com`;
+
+      const currentUser = userPublisher.get() || {};
+      userPublisher.set({
+        ...currentUser,
+        firstName: randomName.firstName,
+        lastName: randomName.lastName,
+        email: randomEmail,
+      });
+    }
+  }
+
+  render() {
+    return html`
+      <div class="flex flex-col gap-2">
+        <sonic-select
+          .value=${this.dataProvider}
+          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>
+      </div>
+    `;
+  }
+}

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

@@ -0,0 +1,45 @@
+import type { APIConfiguration } from "@supersoniks/concorde/core/utils/api";
+import type { ApiGetResult } from "@supersoniks/concorde/core/utils/api";
+import { Endpoint } from "@supersoniks/concorde/core/utils/endpoint";
+import { DataProviderKey } from "@supersoniks/concorde/core/utils/dataProviderKey";
+import { PublisherManager } from "@supersoniks/concorde/core/utils/PublisherProxy";
+import "./decorators-demo-init";
+
+export type GeoCommuneRow = { nom: string; code: string };
+
+export const geoApiDemoConfiguration: APIConfiguration = {
+  serviceURL: "https://geo.api.gouv.fr/",
+  token: null,
+  userName: null,
+  password: null,
+  authToken: null,
+  tokenProvider: null,
+};
+
+const docsDemoGeoApiConfigurationId = "docsDemoGeoApiConfiguration";
+PublisherManager.get(docsDemoGeoApiConfigurationId).set(geoApiDemoConfiguration);
+
+export const docsDemoGeoApiConfigurationKey = new DataProviderKey<APIConfiguration>(
+  docsDemoGeoApiConfigurationId,
+);
+
+export const geoCommunesApiGetEndpoint = new Endpoint<GeoCommuneRow[]>(
+  "communes?limit=5&fields=nom,code",
+);
+
+export const docsDemoDynApiConfKeyTemplate = new DataProviderKey<APIConfiguration>(
+  "docsDemoDynApiConf${configSlot}",
+);
+
+PublisherManager.get("docsDemoDynApiConfA").set(geoApiDemoConfiguration);
+PublisherManager.get("docsDemoDynApiConfB").set({
+  ...geoApiDemoConfiguration,
+  serviceURL: "https://geo.api.gouv.fr/",
+});
+
+export const geoCommunesApiGetEndpointDynamic = new Endpoint<GeoCommuneRow[]>(
+  "communes?limit=${communeLimit}&fields=nom,code",
+);
+
+export const geoCommunesApiGetPublishKey =
+  new DataProviderKey<ApiGetResult<GeoCommuneRow[]>>(geoCommunesApiGetEndpoint.path);

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

@@ -0,0 +1,228 @@
+import { PublisherManager } from "@supersoniks/concorde/core/utils/PublisherProxy";
+
+export const ensurePublisherValue = <T>(
+  publisherId: string,
+  defaultValue: T,
+): void => {
+  const publisher = PublisherManager.get(publisherId);
+  const currentValue =
+    typeof publisher.get === "function" ? publisher.get() : undefined;
+
+  const isUnset =
+    currentValue === undefined ||
+    currentValue === null ||
+    (typeof currentValue === "object" &&
+      !Array.isArray(currentValue) &&
+      Object.keys(currentValue).length === 0);
+
+  if (isUnset) {
+    publisher.set(defaultValue as T);
+  }
+};
+
+export const initializeDecoratorsDemoData = () => {
+  ensurePublisherValue("demoData", {
+    title: "Initial Title",
+    user: { name: "Initial User" },
+    count: 0,
+  });
+
+  ensurePublisherValue("demoUser", {
+    name: "Demo User",
+    email: "demo@example.com",
+  });
+
+  ensurePublisherValue("demoSettings", {
+    theme: "light",
+    language: "en",
+  });
+
+  ensurePublisherValue("demoUserSettings", {
+    theme: "light",
+    language: "en",
+  });
+
+  ensurePublisherValue("autoValue1", 10);
+  ensurePublisherValue("autoValue2", 20);
+  ensurePublisherValue("waitAncestorDemo", {
+    message: "Context from ancestor",
+  });
+
+  ensurePublisherValue("combinedData", { title: "Combined Title" });
+  ensurePublisherValue("combinedUser", { name: "Combined User" });
+  ensurePublisherValue("combinedSettings", { theme: "dark" });
+
+  ensurePublisherValue("reflectData", {
+    title: "Initial Reflected Title",
+    count: 0,
+  });
+
+  ensurePublisherValue("publishDemo", {
+    email: "",
+    message: "",
+  });
+
+  ensurePublisherValue("dynamicProfiles", {
+    alpha: { info: { title: "Profil Alpha" } },
+    beta: { info: { title: "Profil Beta" } },
+  });
+
+  ensurePublisherValue("dynamicProfilesAlt", {
+    alpha: { info: { title: "Profil Alpha (Alt)" } },
+    beta: { info: { title: "Profil Beta (Alt)" } },
+  });
+
+  ensurePublisherValue("demoUsers", [
+    {
+      id: 1,
+      firstName: "Alice",
+      lastName: "Smith",
+      email: "alice.smith@example.com",
+    },
+    {
+      id: 2,
+      firstName: "Bob",
+      lastName: "Johnson",
+      email: "bob.johnson@example.com",
+    },
+    {
+      id: 3,
+      firstName: "Carol",
+      lastName: "Williams",
+      email: "carol.williams@example.com",
+    },
+    {
+      id: 4,
+      firstName: "David",
+      lastName: "Brown",
+      email: "david.brown@example.com",
+    },
+    {
+      id: 5,
+      firstName: "Eve",
+      lastName: "Jones",
+      email: "eve.jones@example.com",
+    },
+    {
+      id: 6,
+      firstName: "Frank",
+      lastName: "Garcia",
+      email: "frank.garcia@example.com",
+    },
+    {
+      id: 7,
+      firstName: "Grace",
+      lastName: "Miller",
+      email: "grace.miller@example.com",
+    },
+    {
+      id: 8,
+      firstName: "Henry",
+      lastName: "Davis",
+      email: "henry.davis@example.com",
+    },
+    {
+      id: 9,
+      firstName: "Ivy",
+      lastName: "Martinez",
+      email: "ivy.martinez@example.com",
+    },
+    {
+      id: 10,
+      firstName: "Jack",
+      lastName: "Taylor",
+      email: "jack.taylor@example.com",
+    },
+  ]);
+
+  ensurePublisherValue("demoUsersAlt", [
+    {
+      id: 11,
+      firstName: "Sophie",
+      lastName: "Lindquist",
+      email: "sophie.lindquist@example.com",
+    },
+    {
+      id: 12,
+      firstName: "Mateo",
+      lastName: "Ortega",
+      email: "mateo.ortega@example.com",
+    },
+    {
+      id: 13,
+      firstName: "Jin",
+      lastName: "Park",
+      email: "jin.park@example.com",
+    },
+    {
+      id: 14,
+      firstName: "Fatima",
+      lastName: "El-Sayed",
+      email: "fatima.el-sayed@example.com",
+    },
+    {
+      id: 15,
+      firstName: "Lars",
+      lastName: "Johansson",
+      email: "lars.johansson@example.com",
+    },
+    {
+      id: 16,
+      firstName: "Amara",
+      lastName: "Singh",
+      email: "amara.singh@example.com",
+    },
+    {
+      id: 17,
+      firstName: "Zuri",
+      lastName: "Okafor",
+      email: "zuri.okafor@example.com",
+    },
+    {
+      id: 18,
+      firstName: "Luca",
+      lastName: "Rossi",
+      email: "luca.rossi@example.com",
+    },
+    {
+      id: 19,
+      firstName: "Ava",
+      lastName: "Murphy",
+      email: "ava.murphy@example.com",
+    },
+    {
+      id: 20,
+      firstName: "Noah",
+      lastName: "Keller",
+      email: "noah.keller@example.com",
+    },
+  ]);
+
+  ensurePublisherValue("demoUsersSettings", [
+    { theme: "light", language: "en" },
+    { theme: "dark", language: "fr" },
+    { theme: "auto", language: "es" },
+    { theme: "light", language: "en" },
+    { theme: "dark", language: "fr" },
+    { theme: "auto", language: "es" },
+    { theme: "light", language: "en" },
+    { theme: "dark", language: "fr" },
+    { theme: "auto", language: "es" },
+    { theme: "light", language: "en" },
+  ]);
+
+  ensurePublisherValue("demoUsersAltSettings", [
+    { theme: "dark", language: "de" },
+    { theme: "light", language: "it" },
+    { theme: "auto", language: "ja" },
+    { theme: "dark", language: "pt" },
+    { theme: "light", language: "ru" },
+    { theme: "auto", language: "zh" },
+    { theme: "dark", language: "ar" },
+    { theme: "light", language: "sv" },
+    { theme: "auto", language: "nl" },
+    { theme: "dark", language: "pl" },
+  ]);
+};
+
+initializeDecoratorsDemoData();