@supersoniks/concorde 5.1.1 → 5.1.3

package/docs/hubs/remote-data.html

@@ -0,0 +1,367 @@
+<!DOCTYPE html>
+<html lang="en" data-doc-url="https://concorde.supersoniks.org/hubs/remote-data.html" data-doc-id="hubs/remote-data">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>Fetching remote data in Concorde — Concorde by Supersoniks</title>
+  <meta name="description" content="Hub for loading online data: @get decorator, Endpoint, API configuration, dynamic paths, sonic-list fetch, sonic-queue, legacy sonic-fetch.">
+  <meta name="keywords" content="@get, fetch, remote data, API, Endpoint, ApiResult, serviceURL, sonic-list, sonic-queue, HTTP GET">
+  <meta name="concorde-doc-id" content="hubs/remote-data">
+  <link rel="canonical" href="https://concorde.supersoniks.org/hubs/remote-data.html">
+</head>
+<body>
+  <header>
+    <p><a href="/docs/index.html">Concorde documentation</a></p>
+  </header>
+  <main>
+    <article>
+      <p class="doc-lead" id="doc-summary"><strong>Concorde documentation — Fetching remote data in Concorde</strong>. Hub for loading online data: @get decorator, Endpoint, API configuration, dynamic paths, sonic-list fetch, sonic-queue, legacy sonic-fetch. <span>Doc ID: <code>hubs/remote-data</code>. Keywords: @get, fetch, remote data, API, Endpoint, ApiResult, serviceURL, sonic-list, sonic-queue, HTTP GET. URL: <a href="https://concorde.supersoniks.org/hubs/remote-data.html">https://concorde.supersoniks.org/hubs/remote-data.html</a>.</span></p>
+      <section id="core-components-functional-fetch-fetch" data-doc-id="core/components/functional/fetch/fetch">
+  <h2><a href="/core/components/functional/fetch">Fetch</a></h2>
+  <p><strong>Doc ID:</strong> <code>core/components/functional/fetch/fetch</code> · <a href="/core/components/functional/fetch">full page</a></p>
+  <p>sonic-fetch sends a GET request to serviceURL + endPoint and publishes the response under dataProvider, so its children and any subscriber of that provider can render it. In a Lit component, prefer th</p>
+  <pre class="doc-excerpt">Fetch
+
+sonic-fetch sends a GET request to serviceURL + endPoint and publishes the response under dataProvider, so its children and any subscriber of that provider can render it. In a Lit component, prefer the @get decorator; for collections, use List or Queue.
+
+Basic example
+
+dataProvider is required; serviceURL and dataProvider can be set on an ancestor. Children are hidden while the request is pending. With no serviceURL, requests go to the page origin.
+
+       $code  to $city, gate $gate&quot;&gt;
+
+Data provider as endpoint
+
+With no endPoint, the dataProvider value is used as the endpoint.
+
+       $code  from $city at $time&quot;&gt;
+
+Key
+
+key keeps only part of the response, using a dot path: with { &quot;flights&quot;: [ … ] } and key=&quot;flights.1&quot;, the provider holds the second flight. Add preserveOtherKeys to merge the target into the parent object instead of dropping its siblings. With no key, the whole response is published.
+
+Loader and skeleton
+
+With no loader, nothing is shown during the request. Set loader (fixed overlay) or loader=&quot;inline&quot; to show a Loader, or add a   child rendered in place of the content while loading.
+
+         Loading arrivals…
+
+Text responses
+
+When the response type starts w</pre>
+</section>
+<section id="core-components-functional-list-list" data-doc-id="core/components/functional/list/list">
+  <h2><a href="/core/components/functional/list">List</a></h2>
+  <p><strong>Doc ID:</strong> <code>core/components/functional/list/list</code> · <a href="/core/components/functional/list">full page</a></p>
+  <p>sonic-list renders one row per entry of its props array, either set directly or loaded with fetch. In TypeScript, prefer the .items row renderer (with .separator · .noItems · .skeleton); &lt;template&gt; ch</p>
+  <pre class="doc-excerpt">List
+
+sonic-list renders one row per entry of its props array, either set directly or loaded with fetch. In TypeScript, prefer the .items row renderer (with .separator · .noItems · .skeleton);   children are for plain HTML hosts without Lit. Each row gets its own data provider at  /list-item/ .
+
+Basic example
+
+Add fetch to load props from serviceURL + endPoint (or dataProvider when endPoint is empty). key picks the array inside the response. Without fetch, the list only renders the props it receives.
+
+         $time  $code from $city ($airport)&quot;&gt;
+
+This example uses HTML templates; from Lit, use the row renderer instead. Fetch attributes (lazyload · refetchEveryMs · headers · authentication) are shared with Fetch.
+
+Row renderer
+
+From a Lit component, set .items to a function (item, metadata) =&gt; TemplateResult. Functions only pass as properties, so always use the . binding: the same applies to .separator · .noItems · .skeleton. metadata holds key · even · odd · firstChild · lastChild · onlyChild.
+
+Row variants
+
+In HTML, templateKey (default template) names the row field that selects a  . Rows without a match cycle through the   children that have no data-value. From Lit, branch insid</pre>
+</section>
+<section id="core-components-functional-queue-queue" data-doc-id="core/components/functional/queue/queue">
+  <h2><a href="/core/components/functional/queue">Queue</a></h2>
+  <p><strong>Doc ID:</strong> <code>core/components/functional/queue/queue</code> · <a href="/core/components/functional/queue">full page</a></p>
+  <p>sonic-queue loads a paginated API in batches and renders each batch as an internal List. Choose it over sonic-list for long or endless lists; the key attributes are dataProviderExpression · limit · da</p>
+  <pre class="doc-excerpt">Queue
+
+sonic-queue loads a paginated API in batches and renders each batch as an internal List. Choose it over sonic-list for long or endless lists; the key attributes are dataProviderExpression · limit · dataFilterProvider.
+
+Lazy load
+
+dataProviderExpression is the request path: $offset and $limit are replaced for each batch. The first batch starts at offset (default 0) with limit rows (default 5, at most 15). The next batch loads when the end of the list scrolls into view, and the queue stops at the first empty batch. Put the queue in a box with a fixed height and overflow-y-auto, then scroll inside it.
+
+Rows come from the .items callback, as on List; .noItems and .skeleton work the same way. Without $offset in the expression, the queue sends one request and behaves like a list. Set noLazyload to load every batch in a row without waiting for the scroll.
+
+Filters
+
+dataFilterProvider names a form store (formDataProvider). Each non-empty field is added to the query string; when a field changes, the queue drops the loaded batches and reloads from the first offset, after a filterTimeoutMs debounce (default 400). Search a city, an airport or a flight number.
+
+To keep some form fields o</pre>
+</section>
+<section id="docs-decorators-get" data-doc-id="docs/decorators/get">
+  <h2><a href="/docs/decorators/get">@get</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/decorators/get</code> · <a href="/docs/decorators/get">full page</a></p>
+  <p>@get(endpoint) runs an HTTP GET on an Endpoint and stores the full ApiResult&lt;T&gt; in a property, or passes it to a method. It runs again when the endpoint's placeholders or the API configuration change,</p>
+  <pre class="doc-excerpt">@get
+
+@get(endpoint) runs an HTTP GET on an Endpoint and stores the full ApiResult  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, @put and @patch.
+
+Import
+
+import { get, Endpoint, type ApiResult } from &quot;@supersoniks/concorde/decorators&quot;;
+
+type FlightBoard = { flights: Flight[] };
+const departuresEndpoint = new Endpoint&amp;lt;FlightBoard&amp;gt;(&quot;flights?direction=departures&quot;);
+
+@get(departuresEndpoint)
+@state()
+departures?: ApiResult&amp;lt;FlightBoard&amp;gt;;
+
+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). The GET waits until serviceURL is available.
+
+Method
+
+Decorate a method to receive the ApiResult  after each GET instead of storing it.
+
+@get(departuresEndpoint)
+onDepartures(payload?: ApiResult&amp;lt;FlightBoard&amp;gt;) {
+  this.boarding = payload?.result?.flights.filter(</pre>
+</section>
+<section id="docs-decorators-patch" data-doc-id="docs/decorators/patch">
+  <h2><a href="/docs/decorators/patch">@patch</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/decorators/patch</code> · <a href="/docs/decorators/patch">full page</a></p>
+  <p>Sends the value of a publisher as the body of a PATCH request, to update part of a resource, and stores the response in an ApiResult&lt;T&gt; property. It takes the same arguments, options and send(componen</p>
+  <pre class="doc-excerpt">@patch
+
+Sends the value of a publisher as the body of a PATCH request, to update part of a resource, and stores the response in an ApiResult  property. It takes the same arguments, options and send(component) handle as @post; only the HTTP method differs.
+
+Import
+
+import { patch, type ApiResult } from &quot;@supersoniks/concorde/decorators&quot;;
+import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+import { Endpoint } from &quot;@supersoniks/concorde/utils/endpoint&quot;;
+
+Basic usage
+
+The body holds only the fields to change, here a gate change for flight CN 001.
+
+type Flight = { flight: string; route: string; gate: string };
+
+const gateChangeKey = new DataProviderKey&amp;lt;Partial&amp;lt;Flight&amp;gt;&amp;gt;(&quot;gateChange&quot;);
+
+@patch(new Endpoint&amp;lt;Flight&amp;gt;(&quot;flights/CN001&quot;), gateChangeKey)
+@state()
+payload?: ApiResult&amp;lt;Flight&amp;gt;;
+
+moveToB12() {
+  set(gateChangeKey, { gate: &quot;B12&quot; }); // sends the PATCH
+}
+
+Triggers, the send method decorator and every option are described on @post.
+
+API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| endpoint | Endpoint  | Resource path and response type |
+| bodyKey | DataProviderKey  | Publisher read as the partial body |
+| </pre>
+</section>
+<section id="docs-decorators-post" data-doc-id="docs/decorators/post">
+  <h2><a href="/docs/decorators/post">@post</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/decorators/post</code> · <a href="/docs/decorators/post">full page</a></p>
+  <p>Sends the value of a publisher as the body of a POST request and stores the response in an ApiResult&lt;T&gt; property. Pass an Endpoint and a DataProviderKey for the body; the request runs on connect and a</p>
+  <pre class="doc-excerpt">@post
+
+Sends the value of a publisher as the body of a POST request and stores the response in an ApiResult  property. Pass an Endpoint and a DataProviderKey for the body; the request runs on connect and again whenever the body changes. @put and @patch work the same way.
+
+Import
+
+import { post, type ApiResult } from &quot;@supersoniks/concorde/decorators&quot;;
+import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+import { Endpoint } from &quot;@supersoniks/concorde/utils/endpoint&quot;;
+
+type SignUp = { email: string; password: string };
+type CrewMember = { id: number; email: string };
+
+const signUpKey = new DataProviderKey&amp;lt;SignUp&amp;gt;(&quot;crewSignUp&quot;);
+
+@post(new Endpoint&amp;lt;CrewMember&amp;gt;(&quot;api/register&quot;), signUpKey)
+@state()
+payload?: ApiResult&amp;lt;CrewMember&amp;gt;;
+
+Basic usage
+
+The property is undefined until a response arrives, then holds request · response · the typed result. Each body mutation sends a new request; mutations in the same frame are coalesced into one. The demo posts to the local mock POST /docs-mock-api/api/register.
+
+Method form
+
+On a method, the decorator calls it with the full ApiResult  after each request instead of assigning a property.
+
+Sending again
+
+Keep th</pre>
+</section>
+<section id="docs-decorators-put" data-doc-id="docs/decorators/put">
+  <h2><a href="/docs/decorators/put">@put</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/decorators/put</code> · <a href="/docs/decorators/put">full page</a></p>
+  <p>Sends the value of a publisher as the body of a PUT request, to replace a resource, and stores the response in an ApiResult&lt;T&gt; property. It takes the same arguments, options and send(component) handle</p>
+  <pre class="doc-excerpt">@put
+
+Sends the value of a publisher as the body of a PUT request, to replace a resource, and stores the response in an ApiResult  property. It takes the same arguments, options and send(component) handle as @post; only the HTTP method differs.
+
+Import
+
+import { put, type ApiResult } from &quot;@supersoniks/concorde/decorators&quot;;
+import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+import { Endpoint } from &quot;@supersoniks/concorde/utils/endpoint&quot;;
+
+Basic usage
+
+The full passenger record is sent on connect and after each body mutation. Placeholders such as ${passengerId} are resolved on the host component.
+
+type Passenger = { name: string; flight: string; seat: string };
+
+const passengerKey = new DataProviderKey&amp;lt;Passenger&amp;gt;(&quot;passengerForm&quot;);
+const savePassenger = put(
+  new Endpoint&amp;lt;Passenger, { passengerId: string }&amp;gt;(&quot;passengers/${passengerId}&quot;),
+  passengerKey,
+  { autoPostOnBodyMutation: false },
+);
+
+@property() passengerId = &quot;ada-lindqvist&quot;;
+
+@savePassenger
+@state()
+payload?: ApiResult&amp;lt;Passenger&amp;gt;;
+
+async save() {
+  await savePassenger.send(this);
+}
+
+Triggers, the send method decorator and every option are described on @post.
+
+API reference
+
+| Argumen</pre>
+</section>
+<section id="docs-getting-started-dataFlow" data-doc-id="docs/getting-started/dataFlow">
+  <h2><a href="/docs/getting-started/dataFlow">Data flow</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/getting-started/dataFlow</code> · <a href="/docs/getting-started/dataFlow">full page</a></p>
+  <p>Recommended patterns for new Concorde apps (Lit + TypeScript). Under the hood, data lives in a DataProvider store.</p>
+  <pre class="doc-excerpt">Data flow
+
+Recommended patterns for new Concorde apps (Lit + TypeScript). Under the hood, data lives in a DataProvider store.
+
+Quick map
+
+| Need | Use |
+|------|-----|
+| Read/write in code | get / set / dp + DataProviderKey (static paths only) |
+| Reactive Lit template | sub(key) or @subscribe |
+| Read component state from store | @subscribe + DataProviderKey  + @state |
+| Inherit ancestor attributes | @ancestorAttribute |
+| Write from component state | @publish |
+| React to assignments | @handle |
+| HTTP GET | @get + Endpoint, or sonic-list / sonic-queue with fetch |
+| HTTP POST (body from store) | @post + Endpoint + body DataProviderKey |
+| HTTP PUT / PATCH (body from store) | @put / @patch — same model as @post |
+| Forms | formDataProvider + name on fields (no Subscriber on form elements) |
+| Derived / aggregate (JSONata) | derive() or sonic-jsonata — Jsonata |
+| Offline doc demos | serviceURL=&quot;/docs-mock-api&quot; — Local API demos |
+
+Agent skill: concorde (rules/data.md), see AI agents.
+
+DataProviderKey
+
+import { DataProviderKey } from &quot;@supersoniks/concorde/dataProviderKey&quot;;
+import { dp, get, set } from &quot;@supersoniks/concorde/utils&quot;;
+
+const cartKey = new DataProviderKey&amp;lt;{ items</pre>
+</section>
+<section id="docs-misc-api-configuration" data-doc-id="docs/misc/api-configuration">
+  <h2><a href="/docs/misc/api-configuration">API configuration</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/misc/api-configuration</code> · <a href="/docs/misc/api-configuration">full page</a></p>
+  <p>APIConfiguration is the object built by HTML.getApiConfiguration from ancestor attributes on the DOM (or from a typed publisher — see @get / @post configuration key). It is passed to API by fetchers, </p>
+  <pre class="doc-excerpt">API configuration
+
+APIConfiguration is the object built by HTML.getApiConfiguration from ancestor attributes on the DOM (or from a typed publisher — see @get / @post configuration key). It is passed to API by fetchers, sonic-submit, the wording() directive, @get, @post, @put, and @patch.
+
+&gt; Mock service: same Local API demos Service Worker / Vite middleware. Routes used on this page are listed in the 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 sonichttpresponse </pre>
+</section>
+<section id="docs-misc-dynamic-path" data-doc-id="docs/misc/dynamic-path">
+  <h2><a href="/docs/misc/dynamic-path">Dynamic path placeholders</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/misc/dynamic-path</code> · <a href="/docs/misc/dynamic-path">full page</a></p>
+  <p>Decorators and DataProviderKey paths can include placeholders resolved on the host component at runtime:</p>
+  <pre class="doc-excerpt">Dynamic path placeholders
+
+Decorators and DataProviderKey paths can include placeholders resolved on the host component at runtime:
+
+- ${prop} or {$prop} — e.g. &quot;users/${userId}&quot;, &quot;api/sessions/${sessionId}/sync&quot;
+- Nested expressions — e.g. &quot;teams.${teamId}.members&quot;
+
+Resolution is done by resolveDynamicPath. 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 |
+| &quot;&quot; | yes | empty string | e.g. sessions//sync — request may still run |
+| 0 | yes | &quot;0&quot; | Not treated as “missing” |
+| false | yes | &quot;false&quot; | |
+| 42, &quot;alpha&quot; | yes | &quot;42&quot;, &quot;alpha&quot; | |
+
+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 r</pre>
+</section>
+<section id="docs-misc-endpoint" data-doc-id="docs/misc/endpoint">
+  <h2><a href="/docs/misc/endpoint">Endpoint</a></h2>
+  <p><strong>Doc ID:</strong> <code>docs/misc/endpoint</code> · <a href="/docs/misc/endpoint">full page</a></p>
+  <p>Endpoint&lt;T, U&gt; describes a single HTTP path (or a path accepted by API.get) and carries the expected response type T. Unlike DataProviderKey, there is no dot-navigation: the path is one string.</p>
+  <pre class="doc-excerpt">Endpoint
+
+Endpoint  describes a single HTTP path (or a path accepted by API.get) and carries the expected response type T. Unlike 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 or @post. See Dynamic path placeholders for null / undefined / &quot;&quot; / 0 and skipEmptyPlaceholder.
+
+Import
+
+import { Endpoint } from &quot;@supersoniks/concorde/utils/endpoint&quot;;
+
+Construction
+
+const users = new Endpoint&amp;lt;User[]&amp;gt;(&quot;users?limit=10&quot;);
+users.path; // &quot;users?limit=10&quot;
+
+const one = new Endpoint&amp;lt;User, { userId: string }&amp;gt;(&quot;users/${userId}&quot;);
+// userId on the host class is observed when used with @get
+
+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</pre>
+</section>
+    </article>
+  </main>
+</body>
+</html>

package/docs/img/archive/credits.json

@@ -0,0 +1,28 @@
+[
+  {
+    "file": "public/img/archive/concorde-red-arrows-2002.webm",
+    "media": "video",
+    "poster": "public/img/archive/concorde-red-arrows-2002-poster.jpg",
+    "ref": "commons:191164291",
+    "title": "Concorde & Red Arrows 2002",
+    "creator": "Steve Elliott from UK",
+    "creatorUrl": null,
+    "date": "2002",
+    "license": "CC BY-SA 2.0",
+    "licenseCode": "by-sa",
+    "licenseUrl": "https://creativecommons.org/licenses/by-sa/2.0",
+    "creditRequired": true,
+    "page": "https://commons.wikimedia.org/wiki/File:Concorde_%26_Red_Arrows_2002.webm",
+    "via": "Wikimedia Commons",
+    "video": "https://upload.wikimedia.org/wikipedia/commons/0/07/Concorde_%26_Red_Arrows_2002.webm",
+    "width": 640,
+    "height": 360,
+    "duration": 10.4,
+    "bytes": 402387,
+    "credit": "\"Concorde & Red Arrows 2002\" by Steve Elliott from UK, CC BY-SA 2.0, via Wikimedia Commons",
+    "notes": [
+      "Share-alike: an altered version (recoloured, combined with other pictures) must be shared under the same licence."
+    ],
+    "saved": "2026-10-25T16:21:03.878Z"
+  }
+]