@supersoniks/concorde 4.9.98-visual-stack.1 → 5.0.1

package/docs/src/docs/_misc/api-configuration.md

@@ -1,81 +0,0 @@
-# API configuration
-
-`APIConfiguration` is the object built by [`HTML.getApiConfiguration`](../../core/utils/HTML.ts) from **ancestor attributes** on the DOM (or from a typed publisher — see [@get](#docs/_decorators/get.md/get) / [@post](#docs/_decorators/post.md/post) configuration key). It is passed to [`API`](../../core/utils/api.ts) by fetchers, **sonic-submit**, the **`wording()`** directive, **`@get`**, **`@post`**, **`@put`**, and **`@patch`**.
-
-> **Mock service:** same [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) Service Worker / Vite middleware. Routes used on this page are listed in the [API config routes](#api-config-routes) section below.
-
-## Attribute map
-
-| Attribute (ancestor) | `APIConfiguration` field | Role |
-|---------------------|---------------------------|------|
-| `serviceURL` | `serviceURL` | Base URL (e.g. `/docs-mock-api`) |
-| `token` | `token` | Static Bearer sent on REST calls |
-| `userName` / `password` | `userName` / `password` | Basic auth for **tokenProvider** fetch only |
-| `eventsApiToken` | `authToken` | Bearer for **tokenProvider** when no Basic |
-| `tokenProvider` | `tokenProvider` | Path to GET a new token (`{ token }` JSON) |
-| `wordingProvider` | — (read by `wording()`) | Base path + query for label batch GET |
-| `wordingVersionProvider` | — | Publisher id; bump version → reload wordings |
-| `credentials` | `credentials` | `fetch` credentials mode |
-| `addHTTPResponse` | `addHTTPResponse` | Attach `_sonic_http_response_` on result |
-| `cache` | `cache` | `fetch` cache mode |
-| `blockUntilDone` | `blockUntilDone` | Serialize calls per `serviceURL` |
-| `keepAlive` | `keepAlive` | `fetch` keepalive |
-
-**Lit / TypeScript:** store the same shape in a publisher and pass `DataProviderKey<APIConfiguration>` as the second argument of `@get` (see [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey)).
-
-## Bearer token (static)
-
-Publisher `docsApiConfBearerKey` (`set(docsApiConfBearerKey, { token: "docs-mock-valid-token", … })`) — mock returns the protected payload.
-
-<docs-lit-demo for="docs-api-config-bearer-demo"></docs-lit-demo>
-
-## tokenProvider + Basic auth
-
-No static `token`: `API.auth()` calls `GET /docs-mock-api/auth/token` with Basic **demo** / **secret**, stores `token`, then calls the protected route.
-
-<docs-lit-demo for="docs-api-config-token-provider-demo"></docs-lit-demo>
-
-## HTTP 498 — stale token refresh
-
-Initial `token="docs-mock-stale-token"` → mock responds **498** → Concorde invalidates the token, runs `auth()` again (same `tokenProvider` + Basic), retries with `docs-mock-fresh-token`.
-
-<docs-lit-demo for="docs-api-config-stale-token-demo"></docs-lit-demo>
-
-## eventsApiToken
-
-Attribute **`eventsApiToken`** on an ancestor maps to **`authToken`** in config (used as Bearer when calling `tokenProvider`, instead of Basic).
-
-<docs-lit-demo for="docs-api-config-events-token-demo"></docs-lit-demo>
-
-## Wording API
-
-`wordingProvider="wording/labels?lang=fr"` + `wording('api-config.greeting')` in Lit. Mock returns label map from `labels[]` query params.
-
-<docs-lit-demo for="docs-api-config-wording-demo"></docs-lit-demo>
-
-## Scoped attributes (HTML / sonic-scope)
-
-Attributes on **`sonic-scope`** (or any ancestor) are visible to descendants via `getAncestorAttributeValue`.
-
-<docs-lit-demo for="docs-api-config-scoped-attrs-demo"></docs-lit-demo>
-
-## API config routes
-
-| Route | Demo |
-|-------|------|
-| `GET /docs-mock-api/auth/token` | tokenProvider, eventsApiToken |
-| `GET /docs-mock-api/api/config/protected` | Bearer / Basic / 498 |
-| `GET /docs-mock-api/wording/labels?labels[]=…&lang=fr` | `wording()` |
-
-Mock tokens (doc only): `docs-mock-valid-token`, `docs-mock-stale-token` (498), `docs-mock-fresh-token` (after refresh). Basic: **demo** / **secret**. Events token: `docs-mock-events-token`.
-
-Implementation: `src/docs/mock-api/api-config-mock.ts` (bundled in the Service Worker with `router.ts`).
-
-## See also
-
-- [@get](#docs/_decorators/get.md/get) — `APIConfiguration` + `Endpoint`
-- [@post](#docs/_decorators/post.md/post) — same configuration model for POST
-- [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch) — PUT / PATCH
-- [Endpoint](#docs/_misc/endpoint.md/endpoint) — typed path
-- [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) — offline `serviceURL`
-- [Fetch](#core/components/functional/fetch/fetch.md/fetch) — attribute table (legacy sonic-fetch)

package/docs/src/docs/_misc/dataProviderKey.md

@@ -1,168 +0,0 @@
-# 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.md/endpoint). For **`DataProviderKey<APIConfiguration>`**, see [API configuration](#docs/_misc/api-configuration.md/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.md/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.md/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.md/dynamic-path). See [@handle](#docs/_decorators/handle.md/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/docs/src/docs/_misc/docs-mock-api.md

@@ -1,63 +0,0 @@
-# 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` | `sonic-list`, `sonic-fetch`, `sonic-queue` (users) |
-| `/docs-mock-api/api/users/:id` | Single user, `docs-user` |
-| `/docs-mock-api/api/space-cats` | `sonic-jsonata` top-N demo |
-| `/docs-mock-api/api/coffee-bags` | fixtures / tests jsonata (`?roast=`) |
-| `/docs-mock-api/api/market-order` | `sonic-jsonata` totals demo |
-| `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 `submit-result-key` 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.md/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` | Geo list, `@get` demos |
-| `/docs-mock-api/jokes/joke/:category` | JokeAPI-shaped list (`key="jokes"` on queue/list) |
-
-### Filtres `GET /jokes/joke/…`
-
-| Query | Meaning |
-|-------|---------|
-| `amount` | Max jokes per request when not using `offset` |
-| `offset` + `limit` / `per_page` | Pagination for **sonic-queue** lazy load |
-| `contains` | Substring on joke text, setup/delivery, categories (**input** demo, `name="contains"`) |
-| `lang` | `fr` or `en` — filters the local dataset (**select** demo, `name="lang"`) |
-| `blacklistFlags` | Comma-separated flags to **exclude** (`nsfw`, `religious`, `political`, `racist`, `sexist`, `explicit`) — checkbox/radio/switch « Remove following jokes » demos; each joke has matching `flags` in fixtures |
-
-### 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/docs/src/docs/_misc/dynamic-path.md

@@ -1,71 +0,0 @@
-# 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` / `@subscribe` | `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.md/dataProviderKey) — path syntax
-- [Endpoint](#docs/_misc/endpoint.md/endpoint) — HTTP paths + host generic `U`
-- HTTP: [@get](#docs/_decorators/get.md/get) · [@post](#docs/_decorators/post.md/post) · [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch)
-- Store: [@subscribe](#docs/_decorators/subscribe.md/subscribe) · [@bind](#docs/_decorators/bind.md/bind) · [@publish](#docs/_decorators/publish.md/publish) · [@handle](#docs/_decorators/handle.md/handle)
-- Legacy strings: [@onAssign](#docs/_decorators/on-assign.md/on-assign) (dynamic paths section)
-- Templates: [sub()](#docs/_directives/sub.md/sub) — dynamic paths in Lit (no `skipEmptyPlaceholder` yet)
-- Tutorial: [My first component](#docs/_getting-started/my-first-component.md/my-first-component) — `"${dataProvider}"` scope pattern

package/docs/src/docs/_misc/endpoint.md

@@ -1,45 +0,0 @@
-# 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.md/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.md/get) or [@post](#docs/_decorators/post.md/post). See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/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.md/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.md/api-configuration) — `serviceURL`, token, wording (mock demos)
-- [@get](#docs/_decorators/get.md/get) — GET decorator
-- [@post](#docs/_decorators/post.md/post) — POST decorator (body from a `DataProviderKey`)
-- [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch) — PUT / PATCH decorators
-- [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) — typed publisher paths (dot notation)

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

@@ -1,15 +0,0 @@
-# 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` (Subscriber was removed from FormElement — see [FormElement without Subscriber](#docs/_misc/formelement-subscriber-removal.md/formelement-subscriber-removal)).
-
-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-joke-search-demo>`.
-
-| Goal | Use |
-|------|-----|
-| Learn modern patterns | [My first component](#docs/_getting-started/my-first-component.md/my-first-component), [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) |
-| Author doc examples | `<docs-lit-demo>` + `src/docs/example/*.ts` — see [My first component](#docs/_getting-started/my-first-component.md/my-first-component) |
-| Embed in plain HTML only | `data-bind` / Subscriber docs in **Legacy** — [Subscriber mixin](#docs/_core-concept/subscriber.md/subscriber) |
-
-New application code in TypeScript should use **`@subscribe`**, **`formDataProvider` + `name`**, and Lit templates — not HTML `data-bind`.