@supersoniks/concorde 5.1.2 → 5.1.3-immutable.1

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` | `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/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), 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/docs/src/docs/misc/html-integration.md

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