@supersoniks/concorde 5.1.2 → 5.1.3-immutable.1

package/docs/src/docs/_decorators/ancestor-attribute.md

@@ -0,0 +1,128 @@
+# @ancestorAttribute
+
+The `@ancestorAttribute` decorator automatically injects the value of an ancestor's attribute into a class property at the time of `connectedCallback`.
+
+## Principle
+
+This decorator uses `HTML.getAncestorAttributeValue` to traverse up the DOM tree from the current element and find the first ancestor that has the specified attribute. The value of this attribute is then assigned to the decorated property.
+
+## Usage
+
+### Import
+
+<sonic-code language="typescript">
+  <template>
+import { ancestorAttribute } from "@supersoniks/concorde/decorators";
+  </template>
+</sonic-code>
+
+### Basic example
+
+The component reads `dataProvider` and `testAttribute` from its ancestor wrapper. By default (`dynamic: false`), values are read once at connect.
+
+<sonic-code language="typescript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement } from "lit/decorators.js";
+import { ancestorAttribute } from "@supersoniks/concorde/decorators";
+
+@customElement("demo-ancestor-attribute")
+export class DemoAncestorAttribute extends LitElement {
+  @ancestorAttribute("dataProvider")
+  dataProvider: string | null = null;
+
+  @ancestorAttribute("testAttribute")
+  testAttribute: string | null = null;
+
+  render() {
+    return html`
+      <p>dataProvider: <strong>${this.dataProvider ?? "null"}</strong></p>
+      <p>testAttribute: <strong>${this.testAttribute ?? "null"}</strong></p>
+    `;
+  }
+}
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+<div dataProvider="demoDataProvider" testAttribute="test-value-123">
+  <docs-demo-sources for="demo-ancestor-attribute"></docs-demo-sources>
+  <demo-ancestor-attribute></demo-ancestor-attribute>
+</div>
+  </template>
+</sonic-code>
+
+## Use cases
+
+This decorator is particularly useful for:
+
+- **Retrieving the `dataProvider`** from an ancestor without having to pass it explicitly
+- **Retrieving the `formDataProvider`** in form components
+- **Retrieving the `wordingProvider`** for translation
+- **Retrieving any other attribute** defined on an ancestor
+
+## Behavior
+
+- The search starts from the current element and traverses up the DOM tree
+- The injection happens automatically at the time of `connectedCallback`
+- By default (`dynamic: false`), the value is read once at connect time and is not updated afterward
+- With `{ dynamic: true }`, the property stays in sync when:
+  - an ancestor **changes** the attribute value
+  - a **closer** ancestor **gains** / **loses** the attribute (fallback / `null`)
+  - the component is **reparented** (no extra opt-in) — parent `childList` only reacts if *this* node moves
+- Observers are **shared** (one per ancestor attribute / one per parent) so large lists of `sonic-icon` stay cheap on Firefox.
+- When `dynamic` is enabled, updates also propagate to `@subscribe` / `@bind` paths that depend on the decorated property (e.g. `${dataProvider}`)
+
+### Dynamic mode
+
+Use `{ dynamic: true }` when the decorated property must follow the DOM. With Lit, add **`@state()`** on the same property so template updates are visible when the observer assigns a new value.
+
+The live demo below shows only the resolved attribute value — no store, no reparenting.
+
+<sonic-code language="typescript">
+  <template>
+@customElement("demo-ancestor-attribute-dynamic")
+export class DemoAncestorAttributeDynamic extends LitElement {
+  @ancestorAttribute("dataProvider", { dynamic: true })
+  @state()
+  dataProvider: string | null = null;
+
+  render() {
+    return html`
+      &lt;p&gt;Nearest ancestor: &lt;strong&gt;${this.dataProvider ?? "null"}&lt;/strong&gt;&lt;/p&gt;
+    `;
+  }
+}
+  </template>
+</sonic-code>
+
+Try in the demo:
+
+- **parent-a** / **parent-b** — change the value on the direct parent
+- **Remove parent attr** — falls back to **outer**
+- **Add closer** — a wrapper with `from-closer` becomes the nearest ancestor
+- **Remove closer** — back to parent or outer
+- **Remove outer attr** — if parent has no attribute either, the child shows `null`
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-ancestor-attribute-dynamic-section"></docs-demo-sources>
+    <demo-ancestor-attribute-dynamic-section></demo-ancestor-attribute-dynamic-section>
+  </template>
+</sonic-code>
+
+Static mode (default) — read once at connect, no observer:
+
+<sonic-code language="typescript">
+  <template>
+@ancestorAttribute("dataProvider")
+dataProvider: string | null = null;
+  </template>
+</sonic-code>
+
+## Notes
+
+- This decorator works with any component that has a `connectedCallback` method (such as `LitElement` or components extending `Subscriber`)
+- The search also traverses Shadow DOM if necessary
+- If multiple ancestors have the attribute, the closest one will be used

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

@@ -0,0 +1,202 @@
+# @autoSubscribe
+
+> **Legacy:** prefer [@subscribe](#docs/_decorators/subscribe.md/subscribe) + `DataProviderKey`. Examples below may still show `PublisherManager` for existing codebases.
+
+The `@autoSubscribe` decorator automatically detects which publishers are accessed within a method and subscribes to them. When any of these publishers change, the method is automatically re-executed.
+
+## Principle
+
+This decorator wraps a method to track which publishers are accessed during its execution. It then subscribes to all accessed publishers, and when any of them change, the method is re-executed. This provides automatic reactivity without manually managing subscriptions.
+
+## Usage
+
+### Import
+
+<sonic-code language="typescript">
+  <template>
+import { autoSubscribe } from "@supersoniks/concorde/decorators";
+  </template>
+</sonic-code>
+
+### Basic example
+
+
+<sonic-code language="typescript">
+<template>
+@customElement("demo-auto-subscribe")
+export class DemoAutoSubscribe extends LitElement {
+  static styles = [tailwind];
+
+  @state() displayText: string = "";
+  @state() computedValue: number = 0;
+
+  @autoSubscribe()
+  updateDisplay() {
+    const value1 = PublisherManager.get("autoValue1").get() || 0;
+    const value2 = PublisherManager.get("autoValue2").get() || 0;
+    this.computedValue = value1 + value2;
+    this.displayText = `${value1} + ${value2} = ${this.computedValue}`;
+  }
+
+  render() {
+    return html`
+      <p><strong>${this.displayText}</strong></p>
+      <div>
+        <sonic-button @click=${() => this.randomizeValue("autoValue1")}>
+          Randomize Value 1
+        </sonic-button>
+        <sonic-button @click=${() => this.randomizeValue("autoValue2")}>
+          Randomize Value 2
+        </sonic-button>
+      </div>
+    `;
+  }
+
+  randomizeValue(publisherId: string) {
+    const value = PublisherManager.get(publisherId);
+    value.set(Math.floor(Math.random() * 100));
+  }
+}
+</template>
+</sonic-code>
+
+
+<sonic-code >
+  <template>
+    <docs-demo-sources for="demo-auto-subscribe"></docs-demo-sources>
+    <demo-auto-subscribe></demo-auto-subscribe>
+  </template>
+</sonic-code>
+
+### Example with render method
+
+<sonic-code language="typescript">
+  <template>
+@customElement("reactive-view")
+export class ReactiveView extends LitElement {
+  @autoSubscribe()
+  render() {
+    const data = PublisherManager.get("myData");
+    const config = PublisherManager.get("config");
+
+    // This render method will be automatically re-executed
+    // when myData or config change
+    const value = data.get()?.value || 0;
+    const multiplier = config.get()?.multiplier || 1;
+
+    return html`
+      <div>
+        <h1>Result: ${value * multiplier}</h1>
+        <p>Value: ${value}</p>
+        <p>Multiplier: ${multiplier}</p>
+      </div>
+    `;
+  }
+}
+  </template>
+</sonic-code>
+
+## How it works
+
+1. **First execution**: When the method is called, `PublisherManager.collectModifiedPublisher()` is used to track which publishers are accessed
+2. **Subscription**: After execution, the decorator subscribes to all detected publishers
+3. **Re-execution**: When any subscribed publisher changes, the method is automatically called again
+4. **Cleanup**: On `disconnectedCallback`, all subscriptions are automatically removed
+
+## Behavior
+
+- The method is automatically called on `connectedCallback`
+- The method is re-executed whenever any accessed publisher changes
+- Subscriptions are managed automatically (no manual cleanup needed)
+- Only publishers accessed during method execution are subscribed to
+- The decorator uses `queueMicrotask` to batch multiple updates and avoid unnecessary re-renders
+
+## Use cases
+
+This decorator is particularly useful for:
+
+- **Reactive rendering** where the render method depends on multiple publishers
+- **Data transformation** that needs to update when source data changes
+- **Computed properties** that depend on multiple data sources
+- **Automatic synchronization** between publishers and component state
+
+## Complete example
+
+<sonic-code language="typescript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement } from "lit/decorators.js";
+import { autoSubscribe } from "@supersoniks/concorde/decorators";
+import { PublisherManager } from "@supersoniks/concorde/core/utils/PublisherProxy";
+
+@customElement("shopping-cart")
+export class ShoppingCart extends LitElement {
+  items: any[] = [];
+  total: number = 0;
+  discount: number = 0;
+
+  @autoSubscribe()
+  calculateTotal() {
+    const cart = PublisherManager.get("cart");
+    const promo = PublisherManager.get("promo");
+
+    // Access cart items
+    this.items = cart.items.get() || [];
+
+    // Access promo code
+    const promoCode = promo.code.get() || "";
+    const discountPercent = promoCode === "SAVE10" ? 0.1 : 0;
+
+    // Calculate totals
+    const subtotal = this.items.reduce((sum, item) => 
+      sum + (item.price * item.quantity), 0
+    );
+    this.discount = subtotal * discountPercent;
+    this.total = subtotal - this.discount;
+
+    this.requestUpdate();
+  }
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.calculateTotal();
+  }
+
+  render() {
+    return html`
+      <div class="cart">
+        <h2>Shopping Cart</h2>
+        ${this.items.map(item => html`
+          <div>${item.name} x${item.quantity} - ${item.price}€</div>
+        `)}
+        <div class="total">
+          <p>Subtotal: ${this.total + this.discount}€</p>
+          <p>Discount: -${this.discount}€</p>
+          <p><strong>Total: ${this.total}€</strong></p>
+        </div>
+      </div>
+    `;
+  }
+}
+
+// When you update the publishers, calculateTotal is automatically called:
+const cart = PublisherManager.get("cart");
+cart.items.set([
+  { name: "Product 1", price: 10, quantity: 2 },
+  { name: "Product 2", price: 15, quantity: 1 }
+]);
+
+const promo = PublisherManager.get("promo");
+promo.code.set("SAVE10");
+// calculateTotal will be automatically called and the UI will update
+  </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 automatically on `connectedCallback`
+- Remember to call `this.requestUpdate()` if you're updating component properties
+- The decorator uses debouncing via `queueMicrotask` to prevent excessive re-executions
+- For more information about publishers, see the documentation on [Sharing data](#docs/_getting-started/pubsub.md/pubsub)
+

package/docs/src/docs/_decorators/bind.md

@@ -0,0 +1,167 @@
+# @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), [@handle](#docs/_decorators/handle.md/handle), [@publish](#docs/_decorators/publish.md/publish), [@get](#docs/_decorators/get.md/get), [@post](#docs/_decorators/post.md/post), [@put](#docs/_decorators/put.md/put), [@patch](#docs/_decorators/patch.md/patch).
+
+## Principle
+
+The decorator subscribes to the DataProvider store using dot notation or a `DataProviderKey`. Updates flow into the decorated property ([Data flow](#docs/_core-concept/dataFlow.md/dataFlow)).
+
+## 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() {
+    set(demoDataKey, { ...get(demoDataKey), count: get(demoDataKey).count + 1 });
+    // see demo-bind in src/docs/example/decorators-demo-bind-demos.ts
+    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>
+    <docs-demo-sources for="demo-bind"></docs-demo-sources>
+    <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>
+    <docs-demo-sources for="demo-bind-reflect"></docs-demo-sources>
+    <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. While a placeholder is `null`/`undefined`, the bind is inactive; optional `{ skipEmptyPlaceholder: true }` also waits on `""`. See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
+
+> Properties referenced in the pattern must be reactive (`@property`, etc.) or you must call `requestUpdate` manually.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-bind-dynamic"></docs-demo-sources>
+    <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/docs/src/docs/_decorators/get.md

@@ -0,0 +1,162 @@
+# @get
+
+`@get` loads data and stores the result in an optional `ApiResult<T>` property.
+The property is `undefined` until a result is available.
+
+- `payload.result`: typed data;
+- `payload.response`: the HTTP response;
+- `payload.request`: the request that was sent.
+
+## Minimal usage
+
+```typescript
+const usersEndpoint = new Endpoint<User[]>("users");
+
+@get(usersEndpoint)
+@state()
+payload?: ApiResult<User[]>;
+```
+
+The same decorator adapts to a method. The method receives the complete
+`ApiResult<T>` payload after each GET:
+
+```typescript
+@get(usersEndpoint)
+handleUsers(payload?: ApiResult<User[]>) {
+  if (!payload) return;
+
+  console.log(payload.response?.status);
+  console.log(payload.result);
+}
+```
+
+The first argument is always an
+[`Endpoint<T>`](#docs/_misc/endpoint.md/endpoint). API configuration is read
+from the HTML scope (`serviceURL`, token, etc.), so the component is usually
+placed below an element that provides this configuration.
+
+## Refetching a GET
+
+### From the component
+
+Keep the decorator in a constant to access `refetch(component)`. Refetch only
+targets the instance passed as the argument, even before it has received a
+result.
+
+```typescript
+const usersGet = get(new Endpoint<User[]>("users"));
+
+@usersGet
+@state()
+payload?: ApiResult<User[]>;
+
+async refresh() {
+  const payload = await usersGet.refetch(this);
+  console.log(payload?.result);
+}
+```
+
+`refetch(component)` returns a `Promise<ApiResult<T> | undefined>` that resolves
+after the GET has completed.
+
+The named handle can also decorate a method and be reused for refetching:
+
+```typescript
+const usersGet = get(new Endpoint<User[]>("users"));
+
+@usersGet
+handleUsers(payload?: ApiResult<User[]>) {
+  // ...
+}
+
+@refetch(usersGet)
+reloadUsers() {
+  // The GET runs and handleUsers receives its payload.
+}
+```
+
+### From a method decorator
+
+The refetch can decorate a local method. The default is `after`; if the
+method returns a Promise, the GET waits for its resolution. The decorated method
+call also waits for the refetch to complete.
+
+```typescript
+import { refetch } from "@supersoniks/concorde/decorators";
+
+@refetch(usersGet)
+async reload() {
+  this.userId = "42";
+}
+```
+
+Use `{ when: "before" }` when the GET must complete before the method runs:
+
+```typescript
+@refetch(usersGet, { when: "before" })
+reloadBefore() {
+  // The refetch has completed before this method runs.
+}
+```
+
+The method decorator adds an explicit trigger; changes to dynamic endpoint
+properties and configuration publishers keep their existing automatic behavior.
+
+## Options (`GetOptions`)
+
+Options are the second argument, or the third argument when an API
+configuration key is provided.
+
+- `skipEmptyPlaceholder`: blocks the GET when `${prop}` is `""`.
+- `refetchEveryMs`: automatically runs the GET again after this interval
+  (milliseconds). Omit the option, or use `0`, to disable polling.
+- `triggerKey`: a publisher whose `invalidate()` runs the GET again.
+
+With a configuration key, use:
+
+```typescript
+@get(usersEndpoint, apiConfigurationKey)
+```
+
+## When the GET runs again
+
+- when the component connects and configuration is available;
+- when a property used in `${...}` changes;
+- when a configuration publisher changes;
+- when the `triggerKey` publisher is invalidated;
+- after each response when `refetchEveryMs` is set.
+
+See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) for
+dynamic path details.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { get, 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-get"></docs-demo-sources>
+    <demo-api-get></demo-api-get>
+    <docs-demo-sources for="demo-api-get-method"></docs-demo-sources>
+    <demo-api-get-method></demo-api-get-method>
+    <docs-demo-sources for="demo-api-get-configuration-key"></docs-demo-sources>
+    <demo-api-get-configuration-key></demo-api-get-configuration-key>
+  </template>
+</sonic-code>
+
+See [@post](#docs/_decorators/post.md/post),
+[@put](#docs/_decorators/put.md/put), and
+[@patch](#docs/_decorators/patch.md/patch) for write operations.
+
+## Advanced
+
+External invalidation is currently available through `triggerKey`; it is kept
+out of the main usage examples.