@supersoniks/concorde 4.7.4 → 4.8.0

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. 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. 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,60 +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` |
-| `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/endpoint.md

@@ -1,43 +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 the [@get](#docs/_decorators/get.md/get) decorator.
-
-## 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 `ApiGetResult` 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) — decorator that uses `Endpoint<T>`
-- [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) — typed publisher paths (dot notation)

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

@@ -1,13 +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.
-
-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`.