@supersoniks/concorde 5.1.0 → 5.1.2

package/docs/src/docs/getting-started/theming.md

@@ -0,0 +1,253 @@
+# Theming 
+
+## Theme-first customization
+
+Concorde components ship with **default styles** (fallback values in each component and in `<sonic-theme>`).  
+You do not need to define any CSS variables to get a usable UI.
+
+To align the kit with your brand, override **only the essential theme tokens** on `<sonic-theme>`, on `:root`, or in a project stylesheet.  
+Concorde derives radius steps, button/input rounding, shadows, and most per-component layout from these primitives—**do not copy long lists of derived variables** unless you have a specific need.
+
+<sonic-code language="html">
+  <template>
+<sonic-theme color font >
+  <!-- your app -->
+</sonic-theme>
+  </template>
+</sonic-code>
+
+<sonic-code language="javascript">
+  <template>
+import "@supersoniks/concorde/theme";
+  </template>
+</sonic-code>
+
+| Attribute | Effect |
+|-----------|--------|
+| *(omit)* \| `theme="custom"` | Default: core tokens + your `--sc-*`; no built-in light/dark palette |
+| `theme="light"` \| `"dark"` \| `"auto"` | Opt-in presets; `auto` follows `prefers-color-scheme` |
+| `class="bg-base block"` (Tailwind) | Page/surface background (`--sc-base`) |
+| `color` | Text color (`--sc-base-content`) |
+| `font` | Base font family/weight (`--sc-font-family-base`, etc.) |
+
+Popovers, modals, and toasts mount under the nearest `<sonic-theme>`.
+
+## Customization example
+
+Example (full brand override on `<sonic-theme>` or `:root`). Set every essential token below; derived radii and shadows still come from the theme engine—only `--sc-rounded` is listed here.
+
+<sonic-code language="css">
+  <template>
+sonic-theme {
+  /* Semantic fills */
+  --sc-primary: #353429;
+  --sc-secondary: #f43f5e;
+  --sc-info: #7c3aed;
+  --sc-danger: #d71839;
+  --sc-warning: #f97316;
+  --sc-success: #10b981;
+  --sc-contrast: #111;
+
+  /* Text/icons on semantic fills */
+  --sc-primary-content: #fff;
+  --sc-secondary-content: #fff;
+  --sc-info-content: #fff;
+  --sc-danger-content: #fff;
+  --sc-warning-content: #fff;
+  --sc-success-content: #fff;
+  --sc-contrast-content: #fff;
+
+  /* Neutral fills */
+  --sc-base: #fff;
+  --sc-base-50: #f6f6f5;
+  --sc-base-100: #ededec;
+  --sc-base-200: #d7d7d4;
+  --sc-base-300: #c8c7c4;
+  --sc-base-400: #a8a7a2;
+  --sc-base-500: #94938c;
+  --sc-base-600: #76756c;
+  --sc-base-700: #59584e;
+  --sc-base-800: #47463b;
+  --sc-base-900: #353429;
+
+  /* Text/icons on neutral surfaces */
+  --sc-base-content: var(--sc-base-900);
+
+  /* Typography */
+  --sc-font-family-base: "Oswald", system-ui, -apple-system, "Segoe UI", Roboto,
+    "Helvetica Neue", Arial, sans-serif;
+  --sc-headings-font-family: "alternate-gothic-compressed", system-ui, sans-serif;
+  --sc-headings-line-height: 1.1;
+  --sc-headings-font-weight: bold;
+  --sc-headings-text-transform: none;
+
+  /* Shape (primitive only) */
+  --sc-rounded: 0;
+
+  /* Forms */
+  --sc-border-width: 0.2rem;
+  --sc-form-height: 2em;
+  --sc-input-bg: var(--sc-base);
+  --sc-input-color: var(--sc-base-content);
+  --sc-input-border-color: var(--sc-input-color);
+  --sc-input-active-bg: var(--sc-primary);
+  --sc-input-active-color: var(--sc-primary-content);
+  --sc-input-active-border-color: var(--sc-primary);
+}
+  </template>
+</sonic-code>
+
+<sonic-button href="https://delanfranchi.github.io/concordecolors/"> Palette generator: concordecolors</sonic-button>
+
+
+**Without these overrides**, components keep Concorde’s per-component fallbacks. Built-in light/dark palettes apply only when you set `theme="light"`, `theme="dark"`, or `theme="auto"`.
+
+**What we intentionally avoid:** large public `--sc-alert-*` / `--sc-badge-*` APIs or `::part()` styling hooks on most components. Prefer attributes (`type`, `status`, `size`, …) and the theme tokens above.
+
+
+## Only essential CSS variables (public theme API)
+
+These are the **smallest set** we recommend customizing. Everything else should stay internal to the theme or to components (`--sc_*` private variables, attributes like `type`, `size`, `variant`).
+
+### Surfaces and foreground
+
+Tokens **without** a `-content` suffix are **fill / background** colors.  
+Tokens **with** `-content` are **text and icons** on top of the matching fill (solid buttons, badges, alerts, etc.).
+
+#### Neutral fills
+
+| Variable | Role |
+|----------|------|
+| `--sc-base` | Main surface / page background |
+| `--sc-base-50` … `--sc-base-900` | Neutral scale (borders, subtle backgrounds, muted UI) |
+
+#### Neutral foreground
+
+| Variable | Role |
+|----------|------|
+| `--sc-base-content` | Default body text and icons on neutral surfaces |
+
+#### Semantic fills
+
+| Variable | Role |
+|----------|------|
+| `--sc-primary` | Primary actions, links, emphasis |
+| `--sc-secondary` | Secondary brand accent (when used) |
+| `--sc-info`, `--sc-success`, `--sc-warning`, `--sc-danger` | Status and feedback |
+| `--sc-contrast` | High-contrast fills (e.g. on media) |
+
+#### Semantic foreground
+
+| Variable | Role |
+|----------|------|
+| `--sc-primary-content`, `--sc-secondary-content`, … | Text/icons on the matching semantic **fill** (`--sc-primary`, etc.) |
+
+### Shape
+
+| Variable | Role |
+|----------|------|
+| `--sc-rounded` | **Single primitive** corner radius; the theme computes `--sc-rounded-sm`, `--sc-btn-rounded`, `--sc-input-rounded`, etc. |
+
+### Typography
+
+| Variable | Role |
+|----------|------|
+| `--sc-font-family-base` | Body UI text |
+| `--sc-font-weight-base`, `--sc-font-style-base` | Optional |
+| `--sc-headings-font-family`, `--sc-headings-line-height`, `--sc-headings-font-weight`, `--sc-headings-text-transform` | Headings (modal titles, etc.) |
+
+### Forms (only if you customize inputs globally)
+
+Interactive controls expose a few extra **theme-level** tokens; prefer these over styling individual inputs from outside.
+
+| Variable | Role |
+|----------|------|
+| `--sc-border-width` | Default border thickness |
+| `--sc-form-height` | Control height |
+| `--sc-input-bg`, `--sc-input-color`, `--sc-input-border-color` | Default field chrome |
+| `--sc-input-active-bg`, `--sc-input-active-color`, `--sc-input-active-border-color` | Focus/active state |
+
+---
+
+## Tailwind in new components ?
+
+Set <code>tailwind.config.js</code> to match concorde style token in your custom component.
+
+<sonic-code language="js">
+  <template>
+...
+theme: {
+  borderRadius: {
+    DEFAULT: "var(--sc-rounded)",
+    none: "0",
+    sm: "var(--sc-rounded-sm)",
+    md: "var(--sc-rounded-md)",
+    lg: "var(--sc-rounded-lg)",
+    xl: "var(--sc-rounded-xl)",
+    full: "9999px",
+  },
+  boxShadow: {
+    DEFAULT: "var(--sc-shadow)",
+    none: "none",
+    sm: "var(--sc-shadow-sm)",
+    md: "var(--sc-shadow-md)",
+    lg: "var(--sc-shadow-lg)",
+    xl: "var(--sc-shadow-xl)",
+  },
+  colors: {
+    transparent: "transparent",
+    current: "currentColor",
+    content: "var(--sc-base-content)",
+    base: "var(--sc-base)",
+    neutral: {
+      0: "var(--sc-base)",
+      50: "var(--sc-base-50)",
+      100: "var(--sc-base-100)",
+      200: "var(--sc-base-200)",
+      300: "var(--sc-base-300)",
+      400: "var(--sc-base-400)",
+      500: "var(--sc-base-500)",
+      600: "var(--sc-base-600)",
+      700: "var(--sc-base-700)",
+      800: "var(--sc-base-800)",
+      900: "var(--sc-base-900)",
+      content: "var(--sc-base)",
+    },
+    primary: {
+      DEFAULT: "var(--sc-primary)",
+      content: "var(--sc-primary-content)",
+    },
+    success: {
+      DEFAULT: "var(--sc-success)",
+      content: "var(--sc-success-content)",
+    },
+    danger: {
+      DEFAULT: "var(--sc-danger)",
+      content: "var(--sc-danger-content)",
+    },
+    warning: {
+      DEFAULT: "var(--sc-warning)",
+      content: "var(--sc-warning-content)",
+    },
+    info: {
+      DEFAULT: "var(--sc-info)",
+      content: "var(--sc-info-content)",
+    },
+    contrast: {
+      DEFAULT: "var(--sc-contrast)",
+      content: "var(--sc-contrast-content)",
+    },
+  },
+  extend: {
+    borderWidth: {
+      DEFAULT: "var(--sc-border-width)",
+    },
+    fontFamily: {
+      headings: ["var(--sc-headings-font-family, var(--sc-font-family-base, sans-serif))"],
+      body: ["var(--sc-font-family-base)"],
+      monospace: ["var(--sc-font-family-monospace, monospace)"],
+    }
+  }
+  </template>
+</sonic-code>
+

package/{src/docs/_misc → docs/src/docs/misc}/api-configuration.md

@@ -1,8 +1,8 @@
 # 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`**.
+`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) / [@post](/docs/decorators/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.
+> **Mock service:** same [Local API demos](/docs/misc/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
 
@@ -21,7 +21,7 @@
 | `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)).
+**Lit / TypeScript:** store the same shape in a publisher and pass `DataProviderKey<APIConfiguration>` as the second argument of `@get` (see [DataProviderKey](/docs/misc/dataProviderKey)).
 
 ## Bearer token (static)
 
@@ -49,9 +49,7 @@ Attribute **`eventsApiToken`** on an ancestor maps to **`authToken`** in config
 
 ## 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>
+`wordingProvider` and `wordingVersionProvider` are read by the translation directive: see [t()](/docs/directives/t).
 
 ## Scoped attributes (HTML / sonic-scope)
 
@@ -73,9 +71,9 @@ Implementation: `src/docs/mock-api/api-config-mock.ts` (bundled in the Service W
 
 ## 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)
+- [@get](/docs/decorators/get) — `APIConfiguration` + `Endpoint`
+- [@post](/docs/decorators/post) — same configuration model for POST
+- [@put](/docs/decorators/put) · [@patch](/docs/decorators/patch) — PUT / PATCH
+- [Endpoint](/docs/misc/endpoint) — typed path
+- [Local API demos](/docs/misc/docs-mock-api) — offline `serviceURL`
+- [Fetch](/core/components/functional/fetch) — attribute table (legacy sonic-fetch)

package/docs/src/docs/{_misc → misc}/dataProviderKey.md

@@ -2,7 +2,7 @@
 
 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).
+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
 
@@ -78,7 +78,7 @@ firstItem.path;  // "data.items.0"
 
 ### 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:
+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>
@@ -91,7 +91,7 @@ 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).
+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
 
@@ -159,7 +159,7 @@ export class UserForm extends LitElement {
   </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.
+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
 

package/{src/docs/_misc → docs/src/docs/misc}/docs-mock-api.md

@@ -14,29 +14,28 @@ TypeScript constants: `src/docs/mock-api/urls.ts` (`DOCS_MOCK_REQRES_SERVICE`, `
 
 | Path | Used in |
 |------|---------|
-| `/docs-mock-api/api/users` | `sonic-list`, `sonic-fetch`, `sonic-queue` (users) |
+| `/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` | `sonic-jsonata` top-N demo |
+| `/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` | `sonic-jsonata` totals demo |
+| `/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 `submit-result-key` demo |
+| `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.md/api-configuration) — tokenProvider (Basic or `eventsApiToken`) |
+| `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` | Geo list, `@get` demos |
-| `/docs-mock-api/jokes/joke/:category` | JokeAPI-shaped list (`key="jokes"` on queue/list) |
+| `/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 |
 
-### Filtres `GET /jokes/joke/…`
+### Filters `GET /flights`
 
 | 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 |
+| `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`
 

package/docs/src/docs/{_misc → misc}/dynamic-path.md

@@ -46,7 +46,7 @@ Available on:
 |-----|--------|
 | `@get` | 2nd or 3rd argument (`GetOptions`) |
 | `@post` / `@put` / `@patch` | `PostOptions` / `ApiSendOptions` |
-| `@bind` / `@subscribe` | `BindOptions` |
+| `@bind` | `BindOptions` |
 | `@publish` | 2nd argument `PublishOptions` |
 | `@handle` | `HandleOptions` |
 
@@ -62,10 +62,10 @@ Available on:
 
 ## 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
+- [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 → misc}/endpoint.md

@@ -1,8 +1,8 @@
 # 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.
+`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.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`.
+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
 
@@ -30,7 +30,7 @@ const one = new Endpoint&lt;User, { userId: string }&gt;("users/${userId}");
 
 ## 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)).
+`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
 
@@ -38,8 +38,8 @@ const one = new Endpoint&lt;User, { userId: string }&gt;("users/${userId}");
 
 ## 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)
+- [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 → docs/src/docs/misc}/html-integration.md

@@ -2,14 +2,13 @@
 
 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)).
+**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-joke-search-demo>`.
+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.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) |
+| 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`.