@supersoniks/concorde 4.8.0 → 4.9.1

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,77 @@
+# @get
+
+Loads data through [`API.getDetailed`](../../core/utils/api.ts). The decorated property is **`ApiResult<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 `ApiResult` 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. See [API configuration](#docs/_misc/api-configuration.md/api-configuration) for mock demos.
+
+## Dynamic path
+
+`${prop}` on the endpoint or config key is resolved on the host. While a placeholder is `null` or `undefined`, no GET runs. Optional `skipEmptyPlaceholder: true` also blocks `""` (empty string only). Details: [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
+
+## 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 ApiResult } 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) (`/docs-mock-api/geo/`). 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: ApiResult<User> | null = null;
+  </template>
+</sonic-code>
+
+## Live demos
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-api-get"></docs-demo-sources>
+    <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>
+    <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>
+
+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="/docs-mock-api/geo/"`:
+
+<sonic-code>
+  <template>
+<div serviceURL="/docs-mock-api/geo/">
+  <docs-demo-sources for="demo-api-get-publish-subscribe"></docs-demo-sources>
+  <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.
+
+## See also
+
+- [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path)
+- [@post](#docs/_decorators/post.md/post) · [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch) — send decorators (same path rules)

package/docs/src/docs/_decorators/handle.md

@@ -0,0 +1,175 @@
+# @handle
+
+Typed callback on one or more `DataProviderKey<T>` paths: invokes the decorated **method** when a publisher assigns a value (calculations, side effects, updating other `@state` properties, etc.).
+
+Unlike [@subscribe](#docs/_decorators/subscribe.md/subscribe), nothing is bound to the decorated member — only your method runs. `@handle` is typed and accepts up to **3 keys** plus an optional trailing `HandleOptions` object. It supersedes the string-based [@onAssign](#docs/_decorators/on-assign.md/on-assign).
+
+By default the method is called on **every** assignment, even when the value is `null` / `undefined`. Use the options below to restrict that.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { handle, Skip } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { get, set } from "@supersoniks/concorde/utils";
+  </template>
+</sonic-code>
+
+## Basic example
+
+<sonic-code language="typescript">
+  <template>
+type DemoCounterData = { count: number };
+const demoDataKey = new DataProviderKey&lt;DemoCounterData&gt;("demoData");
+
+@customElement("demo-handle")
+export class DemoHandle extends LitElement {
+  @state() doubled = 0;
+  @state() lastUpdate = "";
+
+  @handle(demoDataKey.count)
+  onCountChange(count: number) {
+    this.doubled = count * 2;
+    this.lastUpdate = new Date().toLocaleTimeString();
+  }
+
+  incrementCount() {
+    const data = get(demoDataKey);
+    set(demoDataKey, { ...data, count: data.count + 1 });
+  }
+
+  render() {
+    return html`
+      &lt;p&gt;Doubled count: ${this.doubled}&lt;/p&gt;
+      &lt;p&gt;&lt;small&gt;Last update: ${this.lastUpdate}&lt;/small&gt;&lt;/p&gt;
+      &lt;sonic-button @click=${this.incrementCount}&gt;Increment&lt;/sonic-button&gt;
+    `;
+  }
+}
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-handle"></docs-demo-sources>
+    <demo-handle></demo-handle>
+  </template>
+</sonic-code>
+
+## Dynamic path
+
+Placeholders in `DataProviderKey` resolve from the host component’s properties (same rules as `@bind` / `@subscribe`).
+
+<sonic-code language="typescript">
+  <template>
+type User = { firstName: string; lastName: string; email: string };
+
+@customElement("demo-handle-dynamic")
+export class DemoHandleDynamic extends LitElement {
+  @property({ type: Number })
+  userIndex = 0;
+
+  @state() displayName = "";
+  @state() lastUpdate = "";
+
+  @handle(new DataProviderKey&lt;User, { userIndex: number }&gt;("demoUsers.${userIndex}"))
+  onUserAssigned(user: User) {
+    this.displayName = `${user.firstName} ${user.lastName}`;
+    this.lastUpdate = new Date().toLocaleTimeString();
+  }
+
+  render() {
+    return html`...`;
+  }
+}
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-handle-dynamic"></docs-demo-sources>
+    <demo-handle-dynamic></demo-handle-dynamic>
+  </template>
+</sonic-code>
+
+## Multiple paths
+
+`@handle` accepts up to **3 keys**; the method receives one strongly-typed argument per key, in order. Each assignment triggers the method, so make your method safe against partial values (or use `waitForAllDefined`, see below).
+
+<sonic-code language="typescript">
+  <template>
+type QueueConfig = { onInactivity: { stillHere: { show: boolean } } };
+const config = new DataProviderKey&lt;QueueConfig&gt;("sessionQueueConfig");
+const idle = new DataProviderKey&lt;{ isIdle: boolean }&gt;("idleStatus");
+
+@customElement("demo-handle-multi")
+export class DemoHandleMulti extends LitElement {
+
+  // show: boolean, isIdle: boolean — fully typed from the keys
+  @handle(config.onInactivity.stillHere.show, idle.isIdle)
+  onInactivity(show: boolean, isIdle: boolean) {
+    if (show === true && isIdle === true) this.openModal();
+    else this.closeModal();
+  }
+}
+  </template>
+</sonic-code>
+
+## Options (`HandleOptions`)
+
+Pass an options object as the **last** argument. The names map to real situations seen in the apps.
+
+### `waitForAllDefined`
+
+Only call the method once **all** watched keys are defined (non `null` / `undefined`). This reproduces the historical `@onAssign` semantics — use it when the logic only makes sense with every source ready (e.g. building a date from `date` + `timeZone` + `direction`).
+
+<sonic-code language="typescript">
+  <template>
+@handle(trip.departureDate, trip.event.timeZone, form.direction, {
+  waitForAllDefined: true,
+})
+updateDepartureDate(date: number, timeZone: string, direction: string) {
+  // called only when the three values are all available
+  this.formDate = formatDate(date, timeZone, direction);
+}
+  </template>
+</sonic-code>
+
+### `skip`
+
+Do **not** call the method when a received value belongs to one of the listed **categories** (the `Skip` enum). Each entry is a named category — not a value — so there is no value/pattern ambiguity (e.g. `{}` is `Skip.EmptyObject`, an explicit "empty object" category, never a value comparison).
+
+| Category | Matches |
+| --- | --- |
+| `Skip.Nullish` | `null` or `undefined` (a publisher always emits `null`, never `undefined`) |
+| `Skip.EmptyString` | `""` |
+| `Skip.EmptyObject` | object with no keys (`{}`), arrays excluded |
+| `Skip.EmptyArray` | empty array (`[]`) |
+
+Useful when a not-yet-initialized publisher emits `{}` as a "loading" state. For a **specific value** (e.g. a particular string), guard inside the method instead.
+
+<sonic-code language="typescript">
+  <template>
+@handle(user.profile, { skip: [Skip.Nullish, Skip.EmptyObject] })
+onProfile(profile: Profile) {
+  // not called while the publisher still holds {} (not loaded yet)
+  this.displayName = profile.firstName;
+}
+  </template>
+</sonic-code>
+
+> Options can be combined, e.g. `@handle(a, b, { waitForAllDefined: true, skip: [Skip.Nullish] })`. For any **arbitrary** validation on a specific value, just guard inside the method (`if (!isValid(v)) return;`) — that is exactly what an `accept`-style predicate would do, since `@handle` only runs your method.
+
+### `skipEmptyPlaceholder`
+
+On a **dynamic key path** (`"items.${itemId}"`), if `true`, a placeholder resolved to `''` is treated as not ready (no subscription) — **empty string only**, not `0` or `false`. See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
+
+## Highlights
+
+- Strict typing: the method receives one argument per key, in order.
+- Up to 3 keys; for 4+ keys (rare), keep [@onAssign](#docs/_decorators/on-assign.md/on-assign) for now.
+- By default the method runs on **every** assignment, even with `null` / `undefined` (unlike `@onAssign`, which waits for all values). Opt back into that behavior with `waitForAllDefined`.
+- `skip` filters out values by **named category** (e.g. `[Skip.Nullish, Skip.EmptyObject]`); for arbitrary checks on a specific value, guard inside the method.
+
+See also [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) and [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).