@supersoniks/concorde 5.1.1 → 5.1.2

package/docs/src/core/components/ui/theme/theme.md

@@ -0,0 +1,97 @@
+# Theme
+
+**`sonic-theme`** is the root element of a Concorde UI: it holds the `--sc-*` design tokens, optionally applies a built-in palette, and is where popovers, modals and toasts are mounted. Import `@supersoniks/concorde/theme` once at the app entry and wrap your app in it. Token names and brand overrides are covered in [Theming](/docs/getting-started/theming).
+
+## Basic example
+
+<sonic-code>
+  <template>
+    <sonic-theme color font class="block bg-base p-6 rounded-lg">
+      <sonic-button type="primary">Save changes</sonic-button>
+    </sonic-theme>
+  </template>
+</sonic-code>
+
+## Theme mode
+
+With no `theme` (or `theme="custom"`), only the core tokens and your own `--sc-*` overrides apply. `light` and `dark` apply the built-in palettes; `auto` switches between them with `prefers-color-scheme`.
+
+<sonic-code>
+  <template>
+    <div class="grid gap-4 md:grid-cols-2">
+      <sonic-theme theme="light" color font class="block bg-base p-4 rounded-md border border-neutral-200">
+        <p class="text-sm mb-3 opacity-80">theme="light"</p>
+        <div class="flex flex-wrap gap-2">
+          <sonic-badge type="primary">Primary</sonic-badge>
+          <sonic-badge type="success">Success</sonic-badge>
+          <sonic-badge type="danger">Danger</sonic-badge>
+        </div>
+      </sonic-theme>
+      <sonic-theme theme="dark" color font class="block bg-base p-4 rounded-md">
+        <p class="text-sm mb-3 opacity-80">theme="dark"</p>
+        <div class="flex flex-wrap gap-2">
+          <sonic-badge type="primary">Primary</sonic-badge>
+          <sonic-badge type="success">Success</sonic-badge>
+          <sonic-badge type="danger">Danger</sonic-badge>
+        </div>
+      </sonic-theme>
+    </div>
+  </template>
+</sonic-code>
+
+## Text color and font
+
+`color` sets the host text color to `--sc-base-content`. `font` applies the base font family, weight and style tokens. Both are off by default. To paint the background, add the Tailwind classes `block` and `bg-base` on the host.
+
+<sonic-code>
+  <template>
+    <sonic-theme theme="light" color font class="block bg-base p-6 rounded-lg">
+      <p>Body copy inherits the base content color and font from the theme.</p>
+    </sonic-theme>
+  </template>
+</sonic-code>
+
+## Pop container
+
+Overlays such as `sonic-modal` are appended to the last connected `sonic-theme`, or to `document.body` when there is none. `Theme.getPopContainer()` returns that element.
+
+<sonic-code>
+  <template>
+    <sonic-theme theme="light" color font class="block bg-base p-4 rounded-lg">
+      <sonic-button onclick="document.getElementById('themePopModal').show()">
+        Open modal
+      </sonic-button>
+      <sonic-modal id="themePopModal">
+        <sonic-modal-title>Mounted on theme</sonic-modal-title>
+        <sonic-modal-content>
+          This dialog is appended under the nearest sonic-theme pop container.
+        </sonic-modal-content>
+        <sonic-modal-actions>
+          <sonic-button hideModal>Close</sonic-button>
+        </sonic-modal-actions>
+      </sonic-modal>
+    </sonic-theme>
+  </template>
+</sonic-code>
+
+## Embedded iframes
+
+On connect, the theme posts its resolved `--sc-*` values and linked Google Fonts / Adobe Fonts stylesheets to every iframe on the page (message type `SonicTheme`). An iframe can ask for them again:
+
+<sonic-code language="javascript">
+  <template>
+window.parent.postMessage({ type: "GetSonicTheme" }, "*");
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `theme` | `custom` (default) · `light` · `dark` · `auto` | Built-in palette; `custom` applies core tokens and your overrides only |
+| `color` | boolean | Host text color uses `--sc-base-content` |
+| `font` | boolean | Host uses the base font family, weight and style tokens |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Application content |

package/docs/src/core/components/ui/toast/toast.md

@@ -0,0 +1,147 @@
+# Toast
+
+Toasts show short-lived feedback in a fixed stack at the bottom right of the page. Call **`SonicToast.add()`** (also `window.SonicToast`); the **`sonic-toast`** host is created on first use. Use **`label`** for a heading and **`preserve`** when the user must read or act before the toast goes away.
+
+## Basic example
+
+<sonic-code>
+  <template>
+    <sonic-button onclick="SonicToast.add({ text: 'Flight CN 001 is now boarding' })">
+      Show toast
+    </sonic-button>
+  </template>
+</sonic-code>
+
+## Status
+
+**`status`** sets the color, the icon and the live-region role. With no `status`, the toast is neutral.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-button onclick="SonicToast.add({ text: 'Default message' })">Default</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Operation succeeded', status: 'success' })">Success</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Something went wrong', status: 'error' })">Error</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Check this detail', status: 'warning' })">Warning</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Helpful context', status: 'info' })">Info</sonic-button>
+    </div>
+  </template>
+</sonic-code>
+
+## Label
+
+**`label`** adds a bold heading above **`text`**. `title` is a deprecated alias.
+
+<sonic-code>
+  <template>
+    <sonic-button
+      onclick="SonicToast.add({ label: 'Gate change', text: 'Flight CN 001 now departs from gate B12.', status: 'warning' })"
+    >
+      Toast with label
+    </sonic-button>
+  </template>
+</sonic-code>
+
+## HTML in text
+
+**`text`** and **`label`** accept HTML strings. A link or form control in **`text`** turns on **`preserve`** automatically.
+
+<sonic-code>
+  <template>
+    <sonic-button
+      onclick="SonicToast.add({ text: 'Message with <strong>HTML</strong> and an <a href=&quot;#&quot;>action link</a>', status: 'info' })"
+    >
+      Toast with HTML
+    </sonic-button>
+  </template>
+</sonic-code>
+
+## Preserve
+
+Toasts hide after 6 seconds; the timer pauses on hover and focus. **`preserve`** keeps the toast until the user closes it.
+
+<sonic-code>
+  <template>
+    <sonic-button
+      onclick="SonicToast.add({ text: 'Turbulence ahead: please fasten your seat belt', status: 'info', preserve: true })"
+    >
+      Persistent toast
+    </sonic-button>
+  </template>
+</sonic-code>
+
+## Dismiss forever
+
+With **`dismissForever`** and a stable **`id`**, closing the toast is stored in `localStorage` and later `add()` calls with that `id` are ignored. A toast identical to one already shown (ignoring `id`) is never added twice.
+
+<sonic-code>
+  <template>
+    <sonic-button
+      onclick="SonicToast.add({ id: 'welcome-toast', label: 'Welcome', text: 'Close me and I will not come back after a reload.', status: 'info', dismissForever: true })"
+    >
+      Dismiss forever
+    </sonic-button>
+  </template>
+</sonic-code>
+
+## Ghost
+
+**`ghost`** renders a semi-transparent, non-interactive toast, for example for a background task.
+
+<sonic-code>
+  <template>
+    <sonic-button
+      onclick="SonicToast.add({ text: 'Syncing in the background', status: 'info', ghost: true })"
+    >
+      Ghost toast
+    </sonic-button>
+  </template>
+</sonic-code>
+
+## Removing toasts
+
+Static helpers clear the stack from script, for example after navigation. **`removeAll()`** keeps ghost toasts; **`removeTemporaryItems()`** keeps preserved ones.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-2">
+      <sonic-button onclick="SonicToast.add({ text: 'Temporary success', status: 'success' })">Add success</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Temporary error', status: 'error' })">Add error</sonic-button>
+      <sonic-button onclick="SonicToast.add({ text: 'Persistent info', status: 'info', preserve: true })">Add persistent</sonic-button>
+    </div>
+    <div class="flex flex-wrap gap-2 mt-3">
+      <sonic-button variant="outline" onclick="SonicToast.removeItemsByStatus('success')">Remove success</sonic-button>
+      <sonic-button variant="outline" onclick="SonicToast.removeTemporaryItems()">Remove temporary</sonic-button>
+      <sonic-button variant="outline" onclick="SonicToast.removeAll()">Remove all</sonic-button>
+    </div>
+  </template>
+</sonic-code>
+
+Inside an iframe, toasts are forwarded to the parent window's stack when the parent also loads Concorde.
+
+## API reference
+
+Options of **`SonicToast.add(options)`**:
+
+| Option | Values | Description |
+|----------|---------|-------------|
+| `text` | string · Lit template | Body, required; HTML strings allowed |
+| `label` | string · Lit template | Heading above `text` |
+| `title` | string · Lit template | Deprecated alias of `label` |
+| `status` | `success` · `error` · `warning` · `info` (default neutral) | Color and icon; `error` gets `role="alert"`, others `role="status"` |
+| `id` | string · number (default timestamp) | Identifier for `removeItemById` and `dismissForever` |
+| `preserve` | boolean | No auto-hide; forced when `text` contains a link or control |
+| `ghost` | boolean | Semi-transparent and non-interactive; kept by `removeAll` |
+| `dismissForever` | boolean | Remember the dismissal in `localStorage`; needs a stable `id` |
+| `styleSheet` | `CSSResult` · `CSSStyleSheet` · array | Extra styles adopted by the toast |
+| `useSlot` | boolean | Legacy: render `text` in the light DOM |
+
+| Method | Description |
+|--------|-------------|
+| `SonicToast.add(options)` | Show a toast; returns the stored config, or `null` when skipped |
+| `SonicToast.removeAll()` | Remove every toast except ghosts |
+| `SonicToast.removeItemsByStatus(status)` | Remove toasts with this `status` |
+| `SonicToast.removeItemById(id)` | Remove one toast |
+| `SonicToast.removeTemporaryItems()` | Remove toasts without `preserve` |
+
+`sonic-toast` and `sonic-toast-item` are created by `add()`; do not write them in markup. `sonic-toast-message-subscriber` shows a toast for each `{ type: "public", content, status }` entry of its `messages` property.

package/docs/src/core/components/ui/tooltip/tooltip.md

@@ -0,0 +1,89 @@
+# Tooltip
+
+**`sonic-tooltip`** shows a short `label` in a bubble when the trigger in the default slot is hovered or receives focus. With no `placement`, the bubble sits on `top`, centered. An empty `label` hides the bubble, like `disabled`.
+
+## Basic example
+
+<sonic-code>
+  <template>
+    <sonic-tooltip label="Cruising at Mach 2.04">
+      <sonic-button variant="outline">Hover me</sonic-button>
+    </sonic-tooltip>
+  </template>
+</sonic-code>
+
+## Placement
+
+`top` · `bottom` · `left` · `right` set the side. Add `-start` or `-end` to align the bubble with an edge of the trigger instead of its center. The bubble is repositioned while open to stay in the viewport.
+
+<sonic-code>
+  <template>
+    <div class="flex flex-wrap gap-3">
+      <sonic-tooltip placement="top" label="top"><sonic-button minWidth="9rem">top</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="top-start" label="top-start"><sonic-button minWidth="9rem">top-start</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="top-end" label="top-end"><sonic-button minWidth="9rem">top-end</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="bottom" label="bottom"><sonic-button minWidth="9rem">bottom</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="bottom-start" label="bottom-start"><sonic-button minWidth="9rem">bottom-start</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="bottom-end" label="bottom-end"><sonic-button minWidth="9rem">bottom-end</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="left" label="left"><sonic-button minWidth="9rem">left</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="left-start" label="left-start"><sonic-button minWidth="9rem">left-start</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="left-end" label="left-end"><sonic-button minWidth="9rem">left-end</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="right" label="right"><sonic-button minWidth="9rem">right</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="right-start" label="right-start"><sonic-button minWidth="9rem">right-start</sonic-button></sonic-tooltip>
+      <sonic-tooltip placement="right-end" label="right-end"><sonic-button minWidth="9rem">right-end</sonic-button></sonic-tooltip>
+    </div>
+  </template>
+</sonic-code>
+
+## Multiline label
+
+Line breaks in `label` (a real newline or `&#10;`) are kept. Each line is trimmed and the bubble wraps at `18rem`.
+
+<sonic-code>
+  <template>
+    <sonic-tooltip label="Gate B12&#10;Boarding at 08:15">
+      <sonic-button variant="outline">Multiline label</sonic-button>
+    </sonic-tooltip>
+  </template>
+</sonic-code>
+
+## Focusable
+
+Set `focusable` when the trigger is not focusable itself (text, icon): the host gets `tabindex="0"` so keyboard users can open the tooltip. The bubble uses `popover="hint"`; without Popover API support, the label falls back to a native `title` on one line.
+
+<sonic-code>
+  <template>
+    <sonic-tooltip
+      focusable
+      label="The Concorde made its first transatlantic crossing on September 26, 1973"
+    >
+      <sonic-icon library="iconoir" name="chat-bubble-question"></sonic-icon>
+      Focus or hover this text
+    </sonic-tooltip>
+  </template>
+</sonic-code>
+
+## Disabled
+
+`disabled` never shows the bubble and sets `tabindex="-1"` on the host.
+
+<sonic-code>
+  <template>
+    <sonic-tooltip disabled label="Not shown">
+      <sonic-button>Tooltip disabled</sonic-button>
+    </sonic-tooltip>
+  </template>
+</sonic-code>
+
+## API reference
+
+| Attribute | Values | Description |
+|----------|---------|-------------|
+| `label` | string | Tooltip text; empty or whitespace-only hides the bubble |
+| `placement` | `top` (default) · `bottom` · `left` · `right`, each with optional `-start` · `-end` | Side and alignment relative to the trigger |
+| `disabled` | boolean | Never show the bubble; sets `tabindex="-1"` on the host |
+| `focusable` | boolean | Sets `tabindex="0"` on the host so the tooltip opens on keyboard focus |
+
+| Slot | Description |
+|------|-------------|
+| *(default)* | Trigger content |

package/docs/src/docs/decorators/ancestor-attribute.md

@@ -0,0 +1,59 @@
+# @ancestorAttribute
+
+Copies the value of an attribute from the nearest element that carries it (the host itself, then its ancestors, across shadow roots) into a class property. Use it to pick up a scope such as `dataProvider` without passing it down by hand, typically to feed a dynamic key of [@subscribe](/docs/decorators/subscribe).
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { ancestorAttribute } from "@supersoniks/concorde/decorators";
+
+@ancestorAttribute("dataProvider")
+dataProvider: string | null = null;
+  </template>
+</sonic-code>
+
+## Read once at connect
+
+By default the value is read once, just before the component's `connectedCallback`, and never updated. The closest element with the attribute wins. If no ancestor has it, the property keeps its initial value.
+
+<sonic-code>
+  <template>
+<div dataProvider="flights.CN001" gate="B12">
+  <docs-demo-sources for="demo-ancestor-attribute"></docs-demo-sources>
+  <demo-ancestor-attribute></demo-ancestor-attribute>
+</div>
+  </template>
+</sonic-code>
+
+An attribute present without a value (`<div gate>`) resolves to `""`. A camelCase name also matches its lowercase form (`dataProvider` and `dataprovider`).
+
+## Follow DOM changes
+
+With `{ dynamic: true }`, the property stays in sync while the component is connected: when an ancestor changes the attribute, when a closer ancestor gains or loses it, and when the component is moved. When no ancestor has the attribute, the property becomes `null`. Add `@state()` so Lit re-renders on each assignment.
+
+<sonic-code language="typescript">
+  <template>
+@ancestorAttribute("dataProvider", { dynamic: true })
+@state()
+dataProvider: string | null = null;
+  </template>
+</sonic-code>
+
+Change the parent or outer value, insert a closer wrapper, or remove an attribute: the child always shows the nearest one.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-ancestor-attribute-dynamic-section"></docs-demo-sources>
+    <demo-ancestor-attribute-dynamic-section></demo-ancestor-attribute-dynamic-section>
+  </template>
+</sonic-code>
+
+Keys of [@subscribe](/docs/decorators/subscribe) and [@bind](/docs/decorators/bind) that use the property as a placeholder (`"${dataProvider}"`) are re-resolved on each change.
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `attributeName` | `string` | Attribute to look up on the host, then on its ancestors |
+| `options.dynamic` | `boolean` (default `false`) | Keep the property in sync with attribute changes and reparenting until disconnect; assigns `null` when no ancestor has the attribute |

package/docs/src/docs/decorators/auto-subscribe.md

@@ -0,0 +1,40 @@
+# @autoSubscribe
+
+Legacy decorator that re-runs a method whenever one of the store values it reads is assigned. For new code, prefer [@subscribe](/docs/decorators/subscribe) with a [`DataProviderKey`](/docs/misc/dataProviderKey): dependencies are explicit and typed.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { autoSubscribe } from "@supersoniks/concorde/decorators";
+import { get } from "@supersoniks/concorde/utils";
+
+@autoSubscribe()
+updateDisplay() {
+  this.total = get(passengersKey) + get(crewKey);
+}
+  </template>
+</sonic-code>
+
+## Tracked reads
+
+The method runs once after `connectedCallback`. Every store value read during that run becomes a dependency; assigning any of them runs the method again. Write the result to a `@state()` property (or call `requestUpdate()`) so the component re-renders.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-auto-subscribe"></docs-demo-sources>
+    <demo-auto-subscribe></demo-auto-subscribe>
+  </template>
+</sonic-code>
+
+## Notes
+
+- Several assignments in the same task trigger a single re-run (batched with `queueMicrotask`).
+- Keep reads unconditional: a value read only behind a condition becomes a dependency the first time that branch runs.
+- Subscriptions are removed in `disconnectedCallback`.
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| none | | `@autoSubscribe()` takes no argument; apply it to a method of a custom element |

package/docs/src/docs/decorators/bind.md

@@ -0,0 +1,77 @@
+# @bind
+
+Keeps a class property in sync with a path of the DataProvider store, in both directions when needed. Pass a dot-notation string or a [DataProviderKey](/docs/misc/dataProviderKey); add `{ reflect: true }` to push local writes back to the store. For read-only sync prefer [@subscribe](/docs/decorators/subscribe), and see [Data flow](/docs/getting-started/dataFlow) for the overall model.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { bind } from "@supersoniks/concorde/decorators";
+
+@bind("flight.gate")
+@state()
+gate = "";
+  </template>
+</sonic-code>
+
+## Basic usage
+
+The first path segment is the data provider id, the rest is dot notation (array items use a numeric index: `passengers.0`). The property updates each time the store value changes. Add `@state()` so Lit re-renders.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-bind"></docs-demo-sources>
+    <demo-bind></demo-bind>
+  </template>
+</sonic-code>
+
+## Typed key
+
+With a `DataProviderKey<T>`, TypeScript checks that the property type matches `T` at that path.
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+
+type Flight = { flight: string; gate: string; boarded: number };
+const flightKey = new DataProviderKey&lt;Flight&gt;("flight");
+
+@bind(flightKey.boarded, { reflect: true })
+@state()
+boarded = 0;
+  </template>
+</sonic-code>
+
+## Reflect
+
+By default (`reflect: false`) the binding is one-way: assigning the property does not touch the store. With `reflect: true`, each assignment calls `set()` on the publisher, so every other subscriber sees the new value. An internal guard prevents update loops.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-bind-reflect"></docs-demo-sources>
+    <demo-bind-reflect></demo-bind-reflect>
+  </template>
+</sonic-code>
+
+## Dynamic path
+
+Placeholders such as `${index}` are resolved from properties of the same component, and `@bind` re-subscribes when they change. Write them in a plain string, not a backtick template literal. While a placeholder is `null` or `undefined` the binding is inactive; `{ skipEmptyPlaceholder: true }` also waits on `""`. Full rules: [Dynamic paths](/docs/misc/dynamic-path).
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-bind-dynamic"></docs-demo-sources>
+    <demo-bind-dynamic></demo-bind-dynamic>
+  </template>
+</sonic-code>
+
+## Lifecycle
+
+The decorator subscribes in `connectedCallback` and unsubscribes in `disconnectedCallback`. It works on any element with that lifecycle (`LitElement`, the `Subscriber` mixin).
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `path` | `string` or `DataProviderKey<T>` | Store path to bind. Supports `${prop}` placeholders |
+| `options.reflect` | `boolean` (default `false`) | Write local assignments back to the store |
+| `options.skipEmptyPlaceholder` | `boolean` (default `false`) | Treat a placeholder resolved to `""` as not ready |

package/docs/src/docs/decorators/get.md

@@ -0,0 +1,160 @@
+# @get
+
+`@get(endpoint)` runs an HTTP GET on an [Endpoint](/docs/misc/endpoint) and stores the full `ApiResult<T>` in a property, or passes it to a method. It runs again when the endpoint's placeholders or the API configuration change, and on demand through `refetch`. For writes, see [@post](/docs/decorators/post), [@put](/docs/decorators/put) and [@patch](/docs/decorators/patch).
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { get, Endpoint, type ApiResult } from "@supersoniks/concorde/decorators";
+
+type FlightBoard = { flights: Flight[] };
+const departuresEndpoint = new Endpoint&lt;FlightBoard&gt;("flights?direction=departures");
+
+@get(departuresEndpoint)
+@state()
+departures?: ApiResult&lt;FlightBoard&gt;;
+  </template>
+</sonic-code>
+
+## Property
+
+The property is `undefined` until the first response, then holds `result` (typed `T`), `response` (the HTTP response) and `request`. It is reset to `undefined` when the component disconnects.
+
+Without a configuration key, `serviceURL` and the token are read from the HTML scope: place the component under an element that sets them (see [API configuration](/docs/misc/api-configuration)). The GET waits until `serviceURL` is available.
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-api-get"></docs-demo-sources>
+    <demo-api-get></demo-api-get>
+  </template>
+</sonic-code>
+
+## Method
+
+Decorate a method to receive the `ApiResult<T>` after each GET instead of storing it.
+
+<sonic-code language="typescript">
+  <template>
+@get(departuresEndpoint)
+onDepartures(payload?: ApiResult&lt;FlightBoard&gt;) {
+  this.boarding = payload?.result?.flights.filter((f) =&gt; f.status === "boarding") ?? [];
+}
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-api-get-method"></docs-demo-sources>
+    <demo-api-get-method></demo-api-get-method>
+  </template>
+</sonic-code>
+
+## Configuration key
+
+Pass a `DataProviderKey<APIConfiguration>` as the second argument to read the configuration from the store instead of the HTML scope. Any change to that publisher runs the GET again.
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import type { APIConfiguration } from "@supersoniks/concorde/utils/api";
+
+const flightsApi = new DataProviderKey&lt;APIConfiguration&gt;("flightsApi");
+
+@get(departuresEndpoint, flightsApi)
+@state()
+departures?: ApiResult&lt;FlightBoard&gt;;
+  </template>
+</sonic-code>
+
+## Dynamic endpoint
+
+`${prop}` placeholders in the endpoint resolve from properties of the same component; each change runs a new GET. While a placeholder is `null` or `undefined`, no request is sent and the property is `undefined`. Rules: [Dynamic paths](/docs/misc/dynamic-path).
+
+<sonic-code language="typescript">
+  <template>
+const boardEndpoint = new Endpoint&lt;FlightBoard, { direction: string }&gt;(
+  "flights?direction=${direction}",
+);
+
+@property() direction = "departures";
+
+@get(boardEndpoint, flightsApi)
+@state()
+board?: ApiResult&lt;FlightBoard&gt;;
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-api-get-configuration-key"></docs-demo-sources>
+    <demo-api-get-configuration-key></demo-api-get-configuration-key>
+  </template>
+</sonic-code>
+
+## Refetch
+
+Keep the decorator in a constant to reuse it. `refetch(component)` runs the GET for that instance only and resolves with the new `ApiResult<T>` (or `undefined`).
+
+<sonic-code language="typescript">
+  <template>
+const departuresGet = get(departuresEndpoint);
+
+@departuresGet
+@state()
+departures?: ApiResult&lt;FlightBoard&gt;;
+
+async refresh() {
+  await departuresGet.refetch(this);
+}
+  </template>
+</sonic-code>
+
+`@refetch(handle)` does the same around a method. By default the GET runs **after** the method (and after its Promise, if it returns one); use `{ when: "before" }` to run it first. The method call resolves once the GET is done.
+
+<sonic-code language="typescript">
+  <template>
+import { refetch } from "@supersoniks/concorde/decorators";
+
+@refetch(departuresGet)
+async showArrivals() {
+  this.direction = "arrivals";
+}
+  </template>
+</sonic-code>
+
+## Polling and triggers
+
+`refetchEveryMs` runs the GET again that many milliseconds after each response (default `0`: off). `triggerKey` runs it whenever another component calls `invalidate()` on that publisher.
+
+<sonic-code language="typescript">
+  <template>
+import { dp } from "@supersoniks/concorde/utils";
+
+const boardRefresh = new DataProviderKey&lt;number&gt;("boardRefresh");
+
+@get(departuresEndpoint, { refetchEveryMs: 30000, triggerKey: boardRefresh })
+@state()
+departures?: ApiResult&lt;FlightBoard&gt;;
+
+// anywhere else
+dp(boardRefresh).invalidate();
+  </template>
+</sonic-code>
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `endpoint` | `Endpoint<T, U>` | Path relative to `serviceURL`. `U` lists the host properties used by `${…}` placeholders |
+| `configurationKey` | `DataProviderKey<APIConfiguration>` (optional) | Read the configuration from the store instead of the HTML scope |
+| `options.refetchEveryMs` | `number` (default `0`) | Polling interval after each response; `0` disables it |
+| `options.triggerKey` | `DataProviderKey<unknown>` | Publisher whose `invalidate()` runs the GET again |
+| `options.skipEmptyPlaceholder` | `boolean` (default `false`) | Treat a placeholder resolved to `""` as not ready |
+
+`options` is the second argument, or the third when a `configurationKey` is passed. The returned decorator exposes `refetch(component): Promise<ApiResult<T> | undefined>`.
+
+| `@refetch` argument | Type | Description |
+|---------------------|------|-------------|
+| `handle` | value returned by `get(…)` | GET to run |
+| `options.when` | `"before"` or `"after"` (default `"after"`) | Run the GET before or after the method |