@supersoniks/concorde 5.0.0 → 5.0.2

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), [@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

@@ -1,162 +0,0 @@
-# @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

@@ -1,175 +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.
-
-### `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).