@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

package/src/docs/misc/dataProviderKey.md

@@ -0,0 +1,168 @@
+# DataProviderKey
+
+The `DataProviderKey<T>` utility provides type-safe navigation through composite data structures. Each property or index access extends the path, and the final key can be retrieved via `toString()` or the `path` property.
+
+For a **single HTTP path string** (no dot-syntax), see [Endpoint](/docs/misc/endpoint). For **`DataProviderKey<APIConfiguration>`**, see [API configuration](/docs/misc/api-configuration).
+
+## Principle
+
+`DataProviderKey` uses a Proxy to intercept property access and build a cumulative path string. TypeScript infers the nested type at each level, so `myKey.items[0]` is correctly typed as `DataProviderKey<Item>` when `items` is `Item[]`.
+
+In Lit demos, bind HTML attributes from a key’s **`.path`** (single source of truth), and use **`get` / `set` / `dp`** instead of `PublisherManager.get("…")`:
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { get, set } from "@supersoniks/concorde/utils";
+
+export const myFormKey = new DataProviderKey&lt;{ email: string }&gt;("myForm");
+set(myFormKey, { email: "a@b.c" });
+
+// template: formDataProvider=${myFormKey.path}
+  </template>
+</sonic-code>
+
+## Usage
+
+### Import
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+  </template>
+</sonic-code>
+
+### Basic example
+
+<sonic-code language="typescript">
+  <template>
+type Item = { id: string; name: string };
+//
+type Data = {
+  items: Item[];
+  count: number;
+};
+//
+const myKey = new DataProviderKey&lt;Data&gt;("data").items[0];
+// Equivalent to: new DataProviderKey&lt;Item&gt;("data.items.0")
+myKey.toString();  // "data.items.0"
+myKey.path;        // same value
+// myKey is typed as DataProviderKey&lt;Item&gt;
+  </template>
+</sonic-code>
+
+### Object property access
+
+<sonic-code language="typescript">
+  <template>
+const key = new DataProviderKey&lt;Data&gt;("data");
+const countKey = key.count;
+countKey.path;        // "data.count"
+countKey.toString();  // "data.count"
+  </template>
+</sonic-code>
+
+### Array index access
+
+<sonic-code language="typescript">
+  <template>
+const itemsKey = new DataProviderKey&lt;Data&gt;("data").items;
+itemsKey.path;  // "data.items"
+// itemsKey is DataProviderKey&lt;Item[]&gt;
+//
+const firstItem = itemsKey[0];
+firstItem.path;  // "data.items.0"
+// firstItem is DataProviderKey&lt;Item&gt;
+  </template>
+</sonic-code>
+
+### Dynamic paths
+
+Use placeholders `${prop}` or `{$prop}` in the path string. The path is resolved at runtime from the component's properties. See [Dynamic path placeholders](/docs/misc/dynamic-path) for resolution rules and `skipEmptyPlaceholder`. The type remains declarative:
+
+<sonic-code language="typescript">
+  <template>
+type User = { name: string; email: string };
+//
+// Path resolved from component.userIndex at runtime
+@subscribe(new DataProviderKey&lt;User&gt;("users.${userIndex}"))
+@state()
+user: User | null = null;
+  </template>
+</sonic-code>
+
+Dynamic keys are **not** supported by `get`, `set`, or `dp` — those APIs take a snapshot at call time with no component context. For dynamic paths use decorators (`@subscribe`, `@publish`, `@handle`) or **`sub(key)`** in Lit templates (resolves `${…}` from the host component). See [sub()](/docs/directives/sub).
+
+### get / set / dp with static keys
+
+For programmatic access, pass a `DataProviderKey` or a static path string. Dynamic placeholders are rejected:
+
+<sonic-code language="typescript">
+  <template>
+import { dp, get, set } from "@supersoniks/concorde/utils";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+//
+const counterKey = new DataProviderKey&lt;{ count: number }&gt;("myCounter");
+//
+set(counterKey, { count: 0 });
+dp(counterKey.count).set(1);
+get(counterKey);  // snapshot: { count: 1 }
+  </template>
+</sonic-code>
+
+## Path retrieval
+
+The final path is built by concatenating each accessed property with a dot:
+
+- `new DataProviderKey<T>("base")` → `"base"`
+- `key.prop` → `"base.prop"`
+- `key.items[0]` → `"base.items.0"`
+
+Use `toString()` or `path` to get the full path string:
+
+<sonic-code language="typescript">
+  <template>
+const key = new DataProviderKey&lt;Data&gt;("data").count;
+const pathString = key.toString();  // "data.count"
+const pathProp = key.path;           // "data.count"
+  </template>
+</sonic-code>
+
+## Use cases
+
+- **Type-safe bindings**: paths for `@bind`, `@subscribe`, `@publish`, `@handle`
+- **Dynamic paths**: reusable keys with `${...}` placeholders
+- **Form fields**: form data paths with compile-time checking
+
+## Integration with @subscribe, @publish and @handle
+
+Use `DataProviderKey` with `@subscribe` (read-only), `@publish` (write-only), or `@handle` (method callback on assign). With `@subscribe` / `@publish`, the decorated property **must** match the key’s value type. With `@handle`, the method receives `(value: T)`.
+
+<sonic-code language="typescript">
+  <template>
+import { subscribe } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+//
+type FormData = { email: string };
+const formKey = new DataProviderKey&lt;FormData&gt;("formData");
+//
+@customElement("user-form")
+export class UserForm extends LitElement {
+  @subscribe(formKey.email)
+  @state()
+  email = "";
+//
+  render() {
+    return html`&lt;input .value=${this.email} @input=${(e) => this.email = (e.target as HTMLInputElement).value}&gt;`;
+  }
+}
+  </template>
+</sonic-code>
+
+These decorators support dynamic paths: `"base.${prop}"` in the constructor. A wrong property type (e.g. `number` for `DataProviderKey<string>`) is a TypeScript error. Resolution rules: [Dynamic path placeholders](/docs/misc/dynamic-path). See [@handle](/docs/decorators/handle) for method callbacks.
+
+## Notes
+
+- Function properties are excluded from navigation (no `key.method()` chaining)
+- Primitives have no navigable properties
+- The `path` property and `toString()` are equivalent for retrieving the key

package/src/docs/misc/docs-mock-api.md

@@ -0,0 +1,62 @@
+# Local API demos (offline)
+
+The Concorde doc site does not call fragile third-party APIs during `yarn dev`. A **Service Worker** and the Vite dev middleware serve **`/docs-mock-api/*`** on the same origin.
+
+## How it works
+
+1. On load, `registerDocsMockApiServiceWorker()` registers `/docs-mock-api-sw.js`.
+2. Requests to `/docs-mock-api/...` are handled by the SW (production build) or Vite middleware (dev).
+3. Live examples use `serviceURL="/docs-mock-api"` and relative paths.
+
+TypeScript constants: `src/docs/mock-api/urls.ts` (`DOCS_MOCK_REQRES_SERVICE`, `DOCS_MOCK_GEO_SERVICE`, …).
+
+## Routes
+
+| Path | Used in |
+|------|---------|
+| `/docs-mock-api/api/users` | [My first component](/docs/getting-started/my-first-component) users list |
+| `/docs-mock-api/api/users/:id` | Single user, `docs-user` |
+| `/docs-mock-api/api/space-cats` | Fixtures shared with the jsonata unit tests |
+| `/docs-mock-api/api/coffee-bags` | fixtures / tests jsonata (`?roast=`) |
+| `/docs-mock-api/api/market-order` | Fixtures shared with the jsonata unit tests |
+| `POST /docs-mock-api/api/register` | **sonic-submit** — JSON, `multipart/form-data` (`sendAsFormData`), or `application/x-www-form-urlencoded` (native `<form>`); response includes parsed `email` + `token` |
+| `POST /docs-mock-api/api/register/nested` | Wrapped body `{ data: { id, token } }` for the `submitResultKey` demo |
+| `GET /docs-mock-api/api/register/echo` | Echoes query string (`method="get"` on submit) |
+| `GET /docs-mock-api/auth/token` | [API configuration](/docs/misc/api-configuration) — tokenProvider (Basic or `eventsApiToken`) |
+| `GET /docs-mock-api/api/config/protected` | Bearer / Basic; `docs-mock-stale-token` → **498** |
+| `GET /docs-mock-api/wording/labels` | Wording batch (`labels[]`, `lang`) |
+| `/docs-mock-api/geo/communes` | `@get` demos |
+| `GET /docs-mock-api/flights` | Flight board (`key="flights"`): `sonic-list` · `sonic-fetch` · `sonic-queue` · `sonic-jsonata` · `sonic-states` and the input / select / radio / switch filter demos |
+
+### Filters `GET /flights`
+
+| Query | Meaning |
+|-------|---------|
+| `direction` | `departures` · `arrivals` |
+| `q` | Substring on flight number, city or airport code |
+| `status` | Comma-separated statuses to keep: `on-time` · `boarding` · `delayed` · `landed` · `cancelled` (`all` = no filter) |
+| `offset` + `limit` | Pagination for **sonic-queue** lazy load |
+
+### Pagination `GET /api/users`
+
+| Query | Meaning |
+|-------|---------|
+| `offset` + `per_page` | Index-based slice on the filtered set — **sonic-queue** (`offset=$offset&per_page=$limit`) |
+| `page` + `per_page` | 1-based page — static fetch examples (`?page=2`) |
+| `limit` | Alias of `per_page` |
+| `q` | Search on first name, last name, email (optional; **sonic-queue** + `dataFilterProvider`, field `name="q"`) |
+
+**ALTCHA** (`sonic-captcha`) is **not** mocked — it still uses the Supersoniks service.
+
+In TypeScript demos, import from `src/docs/mock-api/urls.ts` (e.g. `DOCS_MOCK_REQRES_SERVICE` on `serviceURL`).
+
+## Source files
+
+- `src/docs/mock-api/` — router, fixtures, service worker, `urls.ts`
+- `scripts/docs-mock-api-vite-plugin.ts` — SW build + middleware
+- `public/docs-mock-api-sw.js` — generated on `yarn dev` / `yarn build-docs`
+
+```bash
+yarn dev          # mock API on by default
+yarn build-docs   # includes SW bundle
+```

package/src/docs/misc/dynamic-path.md

@@ -0,0 +1,71 @@
+# Dynamic path placeholders
+
+Decorators and `DataProviderKey` paths can include **placeholders** resolved on the host component at runtime:
+
+- `${prop}` or `{$prop}` — e.g. `"users/${userId}"`, `"api/sessions/${sessionId}/sync"`
+- Nested expressions — e.g. `"teams.${teamId}.members"`
+
+Resolution is done by [`resolveDynamicPath`](../../core/decorators/subscriber/dynamicPath.ts). The root property names (`userId`, `sessionId`, …) are watched via `requestAnimationFrame` (see `dynamicPropertyWatch.ts`).
+
+## Default behaviour (`ready` / `not ready`)
+
+| Placeholder value | Path `ready`? | Inserted segment | Notes |
+|-------------------|---------------|------------------|-------|
+| `undefined` | **no** | — | Wait until defined |
+| `null` | **no** | — | Same as undefined |
+| `""` | **yes** | empty string | e.g. `sessions//sync` — request may still run |
+| `0` | **yes** | `"0"` | Not treated as “missing” |
+| `false` | **yes** | `"false"` | |
+| `42`, `"alpha"` | **yes** | `"42"`, `"alpha"` | |
+
+When `ready: false`, decorators **do not** call the network (for `@get` / `@post` / `@put` / `@patch`), **unsubscribe** (`@bind` / `@subscribe`), or skip publisher binding (`@publish` / `@handle`). The decorated property is often left unchanged or set to `undefined` (HTTP decorators).
+
+When the placeholder later becomes valid, observers run again and behaviour resumes.
+
+## `skipEmptyPlaceholder` option
+
+Some APIs should not run while an id is still `""`. Opt in per decorator:
+
+```typescript
+@get(new Endpoint<User, { userId: string }>("users/${userId}"), {
+  skipEmptyPlaceholder: true,
+})
+```
+
+| Option | Scope |
+|--------|--------|
+| `skipEmptyPlaceholder?: boolean` | **Only** empty string `''` on a placeholder |
+| Default `false` | `""` is inserted into the path (legacy behaviour) |
+| `true` | `""` → `ready: false`, same as `null` / `undefined` for that segment |
+
+Does **not** affect `0`, `false`, `null`, or `undefined` (nullish stays “not ready” regardless).
+
+Available on:
+
+| API | Where |
+|-----|--------|
+| `@get` | 2nd or 3rd argument (`GetOptions`) |
+| `@post` / `@put` / `@patch` | `PostOptions` / `ApiSendOptions` |
+| `@bind` | `BindOptions` |
+| `@publish` | 2nd argument `PublishOptions` |
+| `@handle` | `HandleOptions` |
+
+## Per-decorator summary
+
+| Decorator | `ready: false` | `ready: true` |
+|-----------|----------------|---------------|
+| `@get` | No HTTP; `payload` → `undefined` | `ApiResult` assigned |
+| `@post` / `@put` / `@patch` | No HTTP; `payload` → `undefined` | `ApiResult` assigned |
+| `@subscribe` / `@bind` | Unsubscribe; prop keeps last value | Subscribe `onAssign` |
+| `@publish` | Internal publisher `null`; writes ignored | `publisher.set` on assign |
+| `@handle` | No subscription; with `waitForAllDefined`, method not called | Callback on assign |
+
+## See also
+
+- [DataProviderKey](/docs/misc/dataProviderKey) — path syntax
+- [Endpoint](/docs/misc/endpoint) — HTTP paths + host generic `U`
+- HTTP: [@get](/docs/decorators/get) · [@post](/docs/decorators/post) · [@put](/docs/decorators/put) · [@patch](/docs/decorators/patch)
+- Store: [@subscribe](/docs/decorators/subscribe) · [@bind](/docs/decorators/bind) · [@publish](/docs/decorators/publish) · [@handle](/docs/decorators/handle)
+- Legacy strings: [@onAssign](/docs/decorators/on-assign) (dynamic paths section)
+- Templates: [sub()](/docs/directives/sub) — dynamic paths in Lit (no `skipEmptyPlaceholder` yet)
+- Tutorial: [My first component](/docs/getting-started/my-first-component) — `"${dataProvider}"` scope pattern

package/src/docs/misc/endpoint.md

@@ -0,0 +1,45 @@
+# Endpoint
+
+`Endpoint<T, U>` describes a single HTTP path (or a path accepted by `API.get`) and carries the expected response type `T`. Unlike [DataProviderKey](/docs/misc/dataProviderKey), there is no dot-navigation: the path is one string.
+
+The optional second generic `U` (default `any`) describes host properties used to resolve dynamic segments in the path (`${…}` / `{$…}`), for example with [@get](/docs/decorators/get) or [@post](/docs/decorators/post). See [Dynamic path placeholders](/docs/misc/dynamic-path) for `null` / `undefined` / `""` / `0` and `skipEmptyPlaceholder`.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
+  </template>
+</sonic-code>
+
+## Construction
+
+<sonic-code language="typescript">
+  <template>
+const users = new Endpoint&lt;User[]&gt;("users?limit=10");
+users.path; // "users?limit=10"
+
+const one = new Endpoint&lt;User, { userId: string }&gt;("users/${userId}");
+// `userId` on the host class is observed when used with @get
+  </template>
+</sonic-code>
+
+## Normalization
+
+`Endpoint.normalizePath` trims the string, rejects an empty path, strips leading slashes for paths relative to `serviceURL`, collapses duplicate slashes, and validates absolute `http(s)://` URLs.
+
+## Publisher key for payloads
+
+`getDataProviderKey()` returns a typed publisher key whose `path` matches the endpoint path (payload typing follows `ApiResult` for this endpoint). Useful when pairing `@get` with `@publish` / `@subscribe` (see [@get](/docs/decorators/get)).
+
+## Data-provider paths
+
+`Endpoint.looksLikeDataProviderPath(path)` returns true for strings shaped like `dataProvider(id)…`, which `API.get` can resolve without HTTP.
+
+## See also
+
+- [API configuration](/docs/misc/api-configuration) — `serviceURL`, token, wording (mock demos)
+- [@get](/docs/decorators/get) — GET decorator
+- [@post](/docs/decorators/post) — POST decorator (body from a `DataProviderKey`)
+- [@put](/docs/decorators/put) · [@patch](/docs/decorators/patch) — PUT / PATCH decorators
+- [DataProviderKey](/docs/misc/dataProviderKey) — typed publisher paths (dot notation)

package/src/docs/misc/html-integration.md

@@ -0,0 +1,14 @@
+# HTML integration (no Lit)
+
+Some hosts (legacy PHP pages, static HTML) embed Concorde components **without** a Lit build step. They can use HTML attributes such as **`data-bind`**, **`dataProvider`**, and **`formDataProvider`** on tags directly in the page.
+
+**Form fields** (`sonic-input`, checkbox, select, …) bind only via **`formDataProvider` + `name`**. They do not autofill from ancestor `dataProvider`.
+
+That style is **not** what we demonstrate in this doc site: live examples are **Lit components** under `src/docs/example/`, registered once and reused from Markdown via tags like `<docs-flight-search-demo>`.
+
+| Goal | Use |
+|------|-----|
+| Learn modern patterns | [My first component](/docs/getting-started/my-first-component), [Data flow](/docs/getting-started/dataFlow) |
+| Author doc examples | `<docs-lit-demo>` + `src/docs/example/*.ts` — see [My first component](/docs/getting-started/my-first-component) |
+
+New application code in TypeScript should use **`@subscribe`**, **`formDataProvider` + `name`**, and Lit templates — not HTML `data-bind`.