@supersoniks/concorde 5.0.2 → 5.0.3

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.

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).