@supersoniks/concorde 5.0.0 → 5.0.1

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

@@ -1,390 +0,0 @@
-# @onAssign
-
-> **New apps:** use [@handle](#docs/_decorators/handle.md/handle) with `DataProviderKey` ([Data flow](#docs/_core-concept/dataFlow.md/dataFlow)). `@onAssign` uses untyped string paths; it remains documented for existing codebases — see **Migrating to @handle** below.
-
-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.
-
-For a **typed** equivalent (recommended), use [@handle](#docs/_decorators/handle.md/handle).
-
-## Principle
-
-This decorator subscribes to one or more publishers by **string path** (legacy). When all specified publishers have been assigned values (via `set`), the decorated method is called with all the values as arguments. Prefer [@handle](#docs/_decorators/handle.md/handle) + `DataProviderKey` and `get` / `set` from [Data flow](#docs/_core-concept/dataFlow.md/dataFlow).
-
-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>
-    <docs-demo-sources for="demo-on-assign"></docs-demo-sources>
-    <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.
-
-While a placeholder is `null`/`undefined`, subscriptions are detached. Optional `skipEmptyPlaceholder` on [@handle](#docs/_decorators/handle.md/handle) (typed replacement). Details: [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
-
-
-<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`
-      &lt;div class="flex flex-col gap-2"&gt;
-        &lt;sonic-select label="Users set" @change=${this.updateDataProvider}&gt;
-          &lt;option value="demoUsers"&gt;First set of users&lt;/option&gt;
-          &lt;option value="demoUsersAlt"&gt;Second set of users&lt;/option&gt;
-        &lt;/sonic-select&gt;
-        &lt;sonic-input
-          type="number"
-          .value=${this.userIndex}
-          @input=${this.updateUserIndex}
-          min="0"
-          max="9"
-          label="Index"
-          class="block"
-        &gt;&lt;/sonic-input&gt;
-        &lt;sonic-button @click=${this.updateCurrentUserData}&gt;
-          Update current user data
-        &lt;/sonic-button&gt;
-        &lt;div class="flex flex-col gap-2 border p-2"&gt;
-          &lt;div&gt;
-            &lt;sonic-icon name="user" library="heroicons"&gt;&lt;/sonic-icon&gt;
-            ${this.user?.firstName} ${this.user?.lastName}
-          &lt;/div&gt;
-          &lt;div&gt;
-            &lt;sonic-icon name="envelope" library="heroicons"&gt;&lt;/sonic-icon&gt;
-            ${this.user?.email}
-          &lt;/div&gt;
-          &lt;div&gt;
-            Theme: ${this.userSettings?.theme} | Language:
-            ${this.userSettings?.language}
-          &lt;/div&gt;
-        &lt;/div&gt;
-      &lt;/div&gt;
-    `;
-  }
-}
-  </template>
-</sonic-code>
-
-<sonic-code>
-  <template>
-    <docs-demo-sources for="demo-on-assign-dynamic"></docs-demo-sources>
-    <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>
-
-## Migrating to @handle
-
-`@handle` is the typed successor of `@onAssign`. The key behavioral difference: `@onAssign` waits for **all** values to be defined before calling the method, whereas `@handle` calls it on **every** assignment by default. Use the `waitForAllDefined` option to keep the old semantics.
-
-### Why migrate
-
-- **Typed paths**: keys are `DataProviderKey<T>`, so the method arguments are strongly typed (no more `any`).
-- **Explicit intent**: `waitForAllDefined` and `skip` replace implicit behavior.
-- **Single API**: `@handle` covers the mono- and multi-path cases (up to 3 keys).
-
-### Equivalent semantics (`waitForAllDefined`)
-
-<sonic-code language="typescript">
-  <template>
-// Before
-@onAssign("demoUser", "demoUserSettings")
-handleDataReady(user: any, settings: any) { /* ... */ }
-
-// After — same "wait for everything" behavior, but typed
-const user = new DataProviderKey&lt;User&gt;("demoUser");
-const settings = new DataProviderKey&lt;Settings&gt;("demoUserSettings");
-
-@handle(user, settings, { waitForAllDefined: true })
-handleDataReady(user: User, settings: Settings) { /* ... */ }
-  </template>
-</sonic-code>
-
-### Single path
-
-<sonic-code language="typescript">
-  <template>
-// Before
-@onAssign("settings.modules.logs_route.enabled")
-onLogRoute(value: boolean) { /* ... */ }
-
-// After
-const settings = new DataProviderKey&lt;AppSettings&gt;("settings");
-
-@handle(settings.modules.logs_route.enabled)
-onLogRoute(value: boolean) { /* ... */ }
-  </template>
-</sonic-code>
-
-### 4+ paths
-
-`@handle` is capped at 3 keys. For the rare case of 4 or more publishers, keep `@onAssign` for now, or split the logic into several `@handle` methods that each store their value and call a shared method (guarding against partial values).
-
-## 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/patch.md

@@ -1,70 +0,0 @@
-# @patch
-
-`@patch` applies a partial update with the body from a publisher. It uses the
-same model as [@post](#docs/_decorators/post.md/post):
-`Endpoint<T>`, `DataProviderKey<B>`, `ApiResult<T>`, options, and the
-`send(component)` handle.
-
-## Minimal usage
-
-```typescript
-const bodyKey = new DataProviderKey<Partial<User>>("users.patch");
-const patchUser = patch(new Endpoint<User>("users/42"), bodyKey);
-
-@patchUser
-@state()
-payload?: ApiResult<User>;
-```
-
-The same decorator adapts to a method:
-
-```typescript
-@patch(new Endpoint<User>("users/42"), bodyKey)
-handlePatch(payload?: ApiResult<User>) {
-  if (payload?.response?.ok) console.log(payload.result);
-}
-```
-
-To run the operation again from the component:
-
-```typescript
-async savePatch() {
-  await patchUser.send(this);
-}
-```
-
-`send(component)` returns a Promise resolved after the PATCH completes. See
-[@post](#docs/_decorators/post.md/post) for the method-decorator form and the
-`when: "before"` option.
-
-The PATCH is also sent automatically when the body mutates, unless
-`autoPostOnBodyMutation: false` is set. The available options are described in
-[@post](#docs/_decorators/post.md/post):
-
-- `autoPostOnBodyMutation`
-- `skipIfBodyMissing`
-- `refetchEveryMs`
-- `skipEmptyPlaceholder`
-- `triggerKey`
-
-Pass explicit API configuration as the third argument:
-
-```typescript
-@patch(endpoint, bodyKey, apiConfigurationKey)
-```
-
-## Import
-
-<sonic-code language="typescript">
-  <template>
-import { patch, type ApiResult } from "@supersoniks/concorde/decorators";
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
-  </template>
-</sonic-code>
-
-## See also
-
-- [@post](#docs/_decorators/post.md/post) — options and triggers
-- [@put](#docs/_decorators/put.md/put) — full replacement
-- [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path)

package/docs/src/docs/_decorators/post.md

@@ -1,146 +0,0 @@
-# @post
-
-`@post` sends the contents of a publisher and stores the response in an
-optional `ApiResult<T>` property. The property is `undefined` until a result
-is available.
-
-## Minimal usage
-
-Pass an `Endpoint<T>` and a `DataProviderKey<B>` for the request body.
-
-```typescript
-const userBodyKey = new DataProviderKey<CreateUser>("users.form");
-const createUser = post(new Endpoint<User>("users"), userBodyKey);
-
-@createUser
-@state()
-payload?: ApiResult<User>;
-```
-
-The same decorator adapts to a method and receives the complete payload:
-
-```typescript
-@post(new Endpoint<User>("users"), userBodyKey)
-handleCreate(payload?: ApiResult<User>) {
-  if (payload?.response?.ok) console.log(payload.result);
-}
-```
-
-The current body is read from `userBodyKey`. By default, the POST is sent when
-the component connects and after each body mutation. Mutations in the same
-frame are coalesced into one request.
-
-API configuration is read from the HTML scope, as with
-[@get](#docs/_decorators/get.md/get).
-
-## Sending the POST again
-
-### From the component
-
-Keep the decorator to access `send(component)`. The body is read again when the
-operation runs.
-
-```typescript
-async saveAgain() {
-  const payload = await createUser.send(this);
-  console.log(payload?.result);
-}
-```
-
-`send()` returns a `Promise<ApiResult<T> | undefined>` that resolves after the
-operation completes. It is useful for “Save” or “Retry” buttons and can repeat
-an operation with side effects.
-
-### From a method decorator
-
-The send action can decorate a local method. It runs after the method by
-default, waits for an eventual Promise to resolve, and the decorated method
-call waits for the send to complete:
-
-```typescript
-import { send } from "@supersoniks/concorde/decorators";
-
-@send(createUser)
-async save() {
-  // Prepare local state or validate the form.
-}
-```
-
-Use `{ when: "before" }` when the send must complete before the method runs:
-
-```typescript
-@send(createUser, { when: "before" })
-saveBefore() {
-  // The POST has completed before this method runs.
-}
-```
-
-The method decorator adds an explicit send. If the method also mutates the body
-publisher, set `autoPostOnBodyMutation: false` when the decorated method must
-be the only trigger.
-
-## Options (`PostOptions`)
-
-Options are the third argument, or the fourth argument when a configuration key
-is provided.
-
-- `autoPostOnBodyMutation`: send after a body mutation (default: `true`). Set
-  it to `false` to use `send()`.
-- `skipIfBodyMissing`: skip when the body is `null` or `undefined` (default:
-  `true`).
-- `refetchEveryMs`: repeat the POST at this interval. Use it only when
-  repeating the operation is intended.
-- `skipEmptyPlaceholder`: block the request when a `${...}` placeholder is
-  `""`.
-- `triggerKey`: a publisher whose `invalidate()` sends the POST again.
-
-With a configuration key:
-
-```typescript
-@post(endpoint, userBodyKey, apiConfigurationKey)
-```
-
-See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) for
-dynamic path details.
-
-## When the POST is sent
-
-- when the component connects and the body and configuration are available;
-- after a body mutation, unless `autoPostOnBodyMutation: false`;
-- when a property used in `${...}` changes;
-- when a configuration publisher changes;
-- when the `triggerKey` publisher is invalidated;
-- when `send()` is called;
-- after each response when `refetchEveryMs` is set.
-
-## Import
-
-<sonic-code language="typescript">
-  <template>
-import { post, type ApiResult } from "@supersoniks/concorde/decorators";
-import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
-  </template>
-</sonic-code>
-
-## Demos
-
-<sonic-code>
-  <template>
-    <docs-demo-sources for="demo-api-post"></docs-demo-sources>
-    <demo-api-post></demo-api-post>
-    <docs-demo-sources for="demo-api-post-method"></docs-demo-sources>
-    <demo-api-post-method></demo-api-post-method>
-    <docs-demo-sources for="demo-api-post-dynamic"></docs-demo-sources>
-    <demo-api-post-dynamic></demo-api-post-dynamic>
-  </template>
-</sonic-code>
-
-See [@put](#docs/_decorators/put.md/put) and
-[@patch](#docs/_decorators/patch.md/patch): they use the same model with a
-different HTTP method.
-
-## Advanced
-
-External invalidation is currently available through `triggerKey`; it is kept
-out of the main usage examples.

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

@@ -1,55 +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(publishDemoKey.email)}</p>
-    `;
-  }
-}
-  </template>
-</sonic-code>
-
-<sonic-code>
-  <template>
-    <docs-demo-sources for="demo-publish"></docs-demo-sources>
-    <demo-publish></demo-publish>
-  </template>
-</sonic-code>
-
-Dynamic paths use the same placeholder rules as `@bind` / `@subscribe`. Resolution and `skipEmptyPlaceholder`: [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).