@supersoniks/concorde 4.7.4 → 4.8.0

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

@@ -1,167 +0,0 @@
-# @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).
-
-## 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.
-
-> 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

@@ -1,68 +0,0 @@
-# @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. See [API configuration](#docs/_misc/api-configuration.md/api-configuration) for mock demos.
-
-## 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) (`/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: ApiGetResult<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.

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

@@ -1,171 +0,0 @@
-# @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.
-
-## 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).