@supersoniks/concorde 5.1.1 → 5.1.3

package/src/docs/example/docs-router-demos.ts

@@ -1,7 +1,7 @@
 import { html, LitElement } from "lit";
 import { customElement, state } from "lit/decorators.js";
 import { tailwind } from "../tailwind";
-import { DOC_ROUTER_PAGE_HASH, setDocsDemoSubHash } from "../docs-location";
+import { DOC_ROUTER_PAGE_PATH, setDocsDemoSubHash } from "../docs-location";
 
 import "../../core/components/functional/router/router";
 import "../../core/components/ui/button/button";
@@ -16,7 +16,7 @@ const panel = (title: string, body?: string) => html`
 `;
 
 function navButton(label: string, subRoute: string, variant?: string) {
-  const href = `${DOC_ROUTER_PAGE_HASH}#${subRoute.replace(/^#/, "")}`;
+  const href = `${DOC_ROUTER_PAGE_PATH}#${subRoute.replace(/^#/, "")}`;
   return html`<sonic-button
     size="xs"
     variant=${variant ?? "default"}
@@ -24,7 +24,7 @@ function navButton(label: string, subRoute: string, variant?: string) {
     href=${href}
     @click=${(e: Event) => {
       e.preventDefault();
-      setDocsDemoSubHash(subRoute, DOC_ROUTER_PAGE_HASH);
+      setDocsDemoSubHash(subRoute, DOC_ROUTER_PAGE_PATH);
     }}
     >${label}</sonic-button
   >`;
@@ -36,21 +36,21 @@ export class DocsRouterBasicDemo extends LitElement {
 
   @state()
   private routes = {
-    "#home": () => panel("Home"),
-    "#about": () => panel("About"),
-    "#work": () => panel("Work"),
-    "#contact": () => panel("Contact"),
+    "#departures": () => panel("Departures", "CN 001 to New York boards at B12."),
+    "#arrivals": () => panel("Arrivals", "CN 002 from New York has landed."),
+    "#fleet": () => panel("Fleet", "Seven aircraft, cruising at Mach 2.04."),
+    "#crew": () => panel("Crew", "Captain Leo Marchand is on duty."),
     fallback: () =>
-      panel("404", "No route matched — `routes.fallback` is rendered."),
+      panel("404", "No route matched: routes.fallback is rendered."),
   };
 
   render() {
     return html`
       <div class="mb-4 flex flex-wrap gap-2">
-        ${navButton("Home", "home")}
-        ${navButton("About", "about")}
-        ${navButton("Work", "work")}
-        ${navButton("Contact", "contact")}
+        ${navButton("Departures", "departures")}
+        ${navButton("Arrivals", "arrivals")}
+        ${navButton("Fleet", "fleet")}
+        ${navButton("Crew", "crew")}
         ${navButton("Unknown", "unknown", "outline")}
       </div>
       <sonic-router .routes=${this.routes}></sonic-router>
@@ -64,24 +64,19 @@ export class DocsRouterParamsDemo extends LitElement {
 
   @state()
   private routes = {
-    "#couleur/:id": ({ id }: { id: string }) =>
-      panel("Url-pattern", `Param :id = ${id}`),
-    "#products/(\\d+)/(\\w+)": ([productId, slug]: [string, string]) =>
-      panel("RegExp", `productId = ${productId}, slug = ${slug}`),
-    fallback: () => panel("No match", "Try a link below."),
+    "#flights/:code": ({ code }: { code: string }) =>
+      panel(`Flight ${code}`, "url-pattern: params is { code }"),
+    "#gates/([A-Z])(\\d+)": ([terminal, gate]: [string, string]) =>
+      panel(`Terminal ${terminal}, gate ${gate}`, "RegExp: params is [terminal, gate]"),
+    fallback: () => panel("No flight selected", "Pick a link above."),
   };
 
   render() {
     return html`
-      <p class="mb-3 text-sm text-neutral-500">
-        Dynamic segments are passed to the route function (object for
-        <code>url-pattern</code>, array for capturing groups). Navigation uses
-        <code>history.replaceState</code> with a second hash segment so the doc
-        page does not reload.
-      </p>
       <div class="mb-4 flex flex-wrap gap-2">
-        ${navButton("#couleur/3", "couleur/3")}
-        ${navButton("#products/42/widget", "products/42/widget")}
+        ${navButton("#flights/CN001", "flights/CN001")}
+        ${navButton("#flights/CN102", "flights/CN102")}
+        ${navButton("#gates/B12", "gates/B12")}
       </div>
       <sonic-router .routes=${this.routes}></sonic-router>
     `;

package/src/docs/example/docs-submit-demos.ts

@@ -96,7 +96,7 @@ export class DocsSubmitDemo extends LitElement {
     if (!r || (!r.id && !r.token && !r.error && !r.messages?.length)) {
       return html`
         <p class="mt-4 text-sm text-neutral-500">
-          Submit the form to see <code>id</code> and <code>token</code> here.
+          Sign up to see the crew <code>id</code> and <code>token</code> here.
         </p>
       `;
     }
@@ -120,19 +120,19 @@ export class DocsSubmitDemo extends LitElement {
             <sonic-input
               required
               name="email"
-              type="email"
-              value="eve.holt@reqres.in"
+              type="email" label="Email"
+              value="ada.lindqvist@example.com"
             ></sonic-input>
             <sonic-input
               required
-              type="password"
+              type="password" label="Password"
               name="password"
-              value="pistol"
+              value="concorde"
             ></sonic-input>
           </div>
         </sonic-submit>
         <sonic-submit onClick>
-          <sonic-button type="success" class="w-full">Submit</sonic-button>
+          <sonic-button type="success" class="w-full">Join the crew</sonic-button>
         </sonic-submit>
       </sonic-scope>
       ${this.resultBlock()}
@@ -159,28 +159,28 @@ export class DocsSubmitClearDemo extends LitElement {
             <sonic-input
               required
               name="email"
-              type="email"
-              value="eve.holt@reqres.in"
+              type="email" label="Email"
+              value="ada.lindqvist@example.com"
             ></sonic-input>
             <sonic-input
               required
-              type="password"
+              type="password" label="Password"
               name="password"
-              value="pistol"
+              value="concorde"
             ></sonic-input>
           </div>
-          <sonic-button type="success" class="w-full">Submit and clear form</sonic-button>
+          <sonic-button type="success" class="w-full">Check in and clear form</sonic-button>
         </sonic-submit>
       </sonic-scope>
       <p class="mt-3 text-sm text-neutral-500">
-        After submit, <code>clearedDataOnSuccess="submit-clear-form"</code> resets
-        the publisher (inputs should empty).
+        After check-in, <code>clearedDataOnSuccess="submit-clear-form"</code> resets
+        the publisher and empties the fields.
       </p>
     `;
   }
 }
 
-/** `submit-result-key` keeps only a nested part of the JSON before writing the result publisher. */
+/** `submitResultKey` keeps only a nested part of the JSON before writing the result publisher. */
 @customElement("docs-submit-result-key-demo")
 export class DocsSubmitResultKeyDemo extends LitElement {
   static styles = [tailwind];
@@ -199,29 +199,29 @@ export class DocsSubmitResultKeyDemo extends LitElement {
         submitResultDataProvider=${submitNestedResultKey.path}
         class="max-w-lg block"
       >
-        <sonic-submit onClick submit-result-key="data">
+        <sonic-submit onClick submitResultKey="data">
           <div class="mb-4 grid grid-cols-2 gap-4">
             <sonic-input
               required
               name="email"
-              type="email"
-              value="eve.holt@reqres.in"
+              type="email" label="Email"
+              value="ada.lindqvist@example.com"
             ></sonic-input>
             <sonic-input
               required
-              type="password"
+              type="password" label="Password"
               name="password"
-              value="pistol"
+              value="concorde"
             ></sonic-input>
           </div>
-          <sonic-button type="primary" class="w-full">Submit (nested JSON)</sonic-button>
+          <sonic-button type="primary" class="w-full">Check in (nested JSON)</sonic-button>
         </sonic-submit>
       </sonic-scope>
       <sonic-divider align="left" class="mt-4">Stored in publisher</sonic-divider>
       <div class="mt-2 text-sm">
         ${r?.id != null
           ? html`<div>id from <code>data</code> : ${r.id}</div>`
-          : html`<p class="text-neutral-500">Submit to extract <code>data.id</code> / <code>data.token</code>.</p>`}
+          : html`<p class="text-neutral-500">Check in to extract <code>data.id</code> and <code>data.token</code>.</p>`}
       </div>
     `;
   }
@@ -250,23 +250,23 @@ export class DocsSubmitFormDataDemo extends LitElement {
             <sonic-input
               required
               name="email"
-              type="email"
-              value="eve.holt@reqres.in"
+              type="email" label="Email"
+              value="ada.lindqvist@example.com"
             ></sonic-input>
             <sonic-input
               required
-              type="password"
+              type="password" label="Password"
               name="password"
-              value="pistol"
+              value="concorde"
             ></sonic-input>
           </div>
-          <sonic-button type="primary" class="w-full">Submit as FormData</sonic-button>
+          <sonic-button type="primary" class="w-full">Send passenger details as FormData</sonic-button>
         </sonic-submit>
       </sonic-scope>
       <div class="mt-3 text-sm">
         ${this.result?.token
           ? html`Token received: <span class="font-mono">${this.result.token}</span>`
-          : html`<p class="text-neutral-500">Mock accepts JSON and multipart for <code>/api/register</code>.</p>`}
+          : html`<p class="text-neutral-500">The mock accepts JSON and multipart on <code>/api/register</code>.</p>`}
       </div>
     `;
   }
@@ -292,10 +292,10 @@ export class DocsSubmitGetDemo extends LitElement {
       >
         <sonic-submit onClick method="get">
           <div class="mb-4 grid grid-cols-2 gap-4">
-            <sonic-input name="email" type="email" value="demo@example.com"></sonic-input>
-            <sonic-input name="password" type="password" value="secret"></sonic-input>
+            <sonic-input name="email" type="email" label="Crew email" value="leo.marchand@example.com"></sonic-input>
+            <sonic-input name="password" type="password" label="Crew code" value="mach2"></sonic-input>
           </div>
-          <sonic-button type="neutral" class="w-full">GET with query string</sonic-button>
+          <sonic-button type="neutral" class="w-full">Look up crew member (GET)</sonic-button>
         </sonic-submit>
       </sonic-scope>
       <div class="mt-3 space-y-1 text-sm">${resultLines(this.result)}</div>
@@ -324,25 +324,25 @@ export class DocsSubmitNativeDemo extends LitElement {
               <sonic-input
                 required
                 name="email"
-                type="email"
-                value="eve.holt@reqres.in"
+                type="email" label="Email"
+                value="ada.lindqvist@example.com"
               ></sonic-input>
               <sonic-input
                 required
-                type="password"
+                type="password" label="Password"
                 name="password"
-                value="pistol"
+                value="concorde"
               ></sonic-input>
             </div>
             <sonic-button type="success" class="w-full"
-              >Native form POST</sonic-button
+              >Check in (native form POST)</sonic-button
             >
           </sonic-submit>
         </sonic-scope>
       </form>
       <p class="mt-2 text-sm text-neutral-500">
-        Response loads in the iframe below (full page navigation is avoided via
-        <code>target</code>).
+        The response loads in the iframe below: <code>target</code> avoids a
+        full page navigation.
       </p>
       <iframe
         name="docs-submit-native-frame"
@@ -381,23 +381,23 @@ export class DocsSubmitEventDemo extends LitElement {
             <sonic-input
               required
               name="email"
-              type="email"
-              value="eve.holt@reqres.in"
+              type="email" label="Email"
+              value="ada.lindqvist@example.com"
             ></sonic-input>
             <sonic-input
               required
-              type="password"
+              type="password" label="Password"
               name="password"
-              value="pistol"
+              value="concorde"
             ></sonic-input>
           </div>
-          <sonic-button type="primary" class="w-full">Submit (listen event)</sonic-button>
+          <sonic-button type="primary" class="w-full">Board (listen to event)</sonic-button>
         </sonic-submit>
       </sonic-scope>
       <p class="mt-3 text-sm">
         ${this.lastEvent
           ? html`Last <code>submit</code> event: <span class="font-mono">${this.lastEvent}</span>`
-          : html`<span class="text-neutral-500">Click submit — handler reads <code>event.detail</code>.</span>`}
+          : html`<span class="text-neutral-500">Click Board: the handler reads <code>event.detail</code>.</span>`}
       </p>
     `;
   }
@@ -426,14 +426,14 @@ export class DocsSubmitEndpointDemo extends LitElement {
             <sonic-input
               required
               name="email"
-              type="email"
-              value="eve.holt@reqres.in"
+              type="email" label="Email"
+              value="ada.lindqvist@example.com"
             ></sonic-input>
             <sonic-input
               required
-              type="password"
+              type="password" label="Password"
               name="password"
-              value="pistol"
+              value="concorde"
             ></sonic-input>
           </div>
           <sonic-button type="primary" class="w-full"
@@ -443,7 +443,7 @@ export class DocsSubmitEndpointDemo extends LitElement {
       </sonic-scope>
       <div class="mt-3 text-sm">
         ${this.result?.token
-          ? html`Registered (scope <code>dataProvider</code> is <code>api/users</code>, request went to <code>api/register</code>).`
+          ? html`Signed up: the scope <code>dataProvider</code> is <code>api/users</code> but the request went to <code>api/register</code>.`
           : html`<p class="text-neutral-500">
               <code>dataProvider=${usersListEndpoint.path}</code> but
               <code>endPoint=${registerEndpoint.path}</code> on

package/src/docs/example/docs-toggle-demos.ts

@@ -28,7 +28,7 @@ export class DocsToggleIfDemo extends LitElement {
     return html`
       <div formDataProvider=${docsToggleVisibilityKey.path}>
         <sonic-checkbox
-          label="Show evacuation plan"
+          label="Show aircraft"
           name="togglePlan"
           unique
           checked
@@ -36,9 +36,10 @@ export class DocsToggleIfDemo extends LitElement {
         ></sonic-checkbox>
         <sonic-if .condition=${show} class="mt-4 block">
           <sonic-image
-            src="https://www.thebaron.info/assets/mail/concorde-evacuation.jpg"
+            src="/img/concorde/plane_07.jpg"
+            alt="Crowd gathered around Concorde at night"
             rounded="md"
-            ratio="654/463"
+            ratio="3/2"
           ></sonic-image>
         </sonic-if>
       </div>

package/src/docs/getting-started/ai-agents.md

@@ -0,0 +1,50 @@
+# AI agents (skill)
+
+Concorde ships one [Agent Skill](https://agentskills.io), `concorde`, so coding agents follow the framework patterns. Cursor, Claude Code, JetBrains Junie and other agents load it on their own when they work on Concorde code; there is nothing to add to your `AGENTS.md`.
+
+On a [starter](/docs/getting-started/installation) project, run `yarn ai:sync` after install. On an existing project, install Concorde first, then run `ai-init`.
+
+## Commands
+
+| Context | Command |
+|---------|---------|
+| [create-concorde-ts-starter](https://www.npmjs.com/package/@supersoniks/create-concorde-ts-starter) project | `yarn ai:sync` |
+| Any consumer app (after `yarn add @supersoniks/concorde`) | `node node_modules/@supersoniks/concorde/scripts/ai-init.mjs` |
+| Concorde repo (contributors) | `yarn ai-init` |
+
+Re-run the same command after each Concorde upgrade to refresh the skill.
+
+## The skill
+
+`SKILL.md` is the entry point: where to find the truth (the project, these docs, `custom-elements.json`), the critical rules and the imports. Details live in `rules/` files that the agent reads only for the topic at hand.
+
+| File | Topic |
+|------|-------|
+| `SKILL.md` | Sources, critical rules, component shape, imports |
+| `rules/data.md` | Store, `DataProviderKey`, `@subscribe` / `@publish` / `@bind` / `@handle`, `sub()`, `get` / `set` / `dp` |
+| `rules/http.md` | `Endpoint`, `@get` / `@post`, API configuration |
+| `rules/lists-forms.md` | `sonic-list` / `sonic-queue`, form fields |
+| `rules/styling.md` | Theme, tokens, classes, styling rules |
+| `rules/composition.md` | Parts of compound components, built-in states |
+| `rules/troubleshooting.md` | Symptom → cause → fix: values not updating, requests not sent, empty lists |
+
+## What gets installed
+
+| Path | Role |
+|------|------|
+| `.agents/skills/concorde/` | The skill (read directly by Cursor) |
+| `.claude/skills/concorde` | Symlink for Claude Code |
+| `.junie/skills/concorde` | Symlink for JetBrains Junie |
+
+Where symlinks are not allowed (some Windows setups), the skill is copied instead. Your own skills in these folders are never touched. Commit `.agents/` and the links if your team shares agent settings.
+
+**`AGENTS.md` stays yours:** `ai-init` never reads or writes it.
+
+## Flags
+
+| Flag | Effect |
+|------|--------|
+| `--no-links` | Install `.agents/skills` only, without the `.claude` / `.junie` links |
+| `--overlay <dir>` | Also install the skills found in `<dir>/skills/` (project kit) |
+
+Source files in the npm package: `node_modules/@supersoniks/concorde/ai/skills/concorde/`.

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

@@ -0,0 +1,5 @@
+# Components
+
+Every Concorde web component, grouped like the sidebar. Pick one to see its live demos, attributes and import path.
+
+<docs-components-index></docs-components-index>

package/src/docs/getting-started/create-a-component.md

@@ -0,0 +1,136 @@
+# Creating components
+
+> **New app components:** start with [My first component](/docs/getting-started/my-first-component) and [Data flow](/docs/getting-started/dataFlow). The `Subscriber` mixin below is legacy.
+
+## Where to put it?
+
+In this document, we consider the src directory of the project as the root.<br>
+We describe how we organize our components as an example, however it depends on your project.
+
+In concorde each component is currently organized in the following directory structure (at least we try):
+
+- **/core/components/functional/component-name/component-name.ts**  
+  Generic/functional/generally unstyled component.
+  The component usually doesn't use any other concrete components.
+- **/core/components/ui/component-name/component-name.ts**  
+  Generic but UI-oriented component.
+  The component usually only uses generic components and other UI components.
+- **la-billetterie/components/atoms/component-name/component-name.ts**  
+  The component is intended to have a concrete usage within our ticketing system **"la-billetterie"**.
+  It usually only uses generic components from `core` and possibly other atoms.
+- **la-billetterie/components/concrete-destination/component-name/component-name.ts**  
+  The component has a specific destination: (event / cart / gift card): `/components/destination/`
+  The component uses various components, usually from the `/components/atoms` directory.
+  It does not use components at the same level in the file hierarchy.
+
+## Starting from a Simple Model
+
+You can copy `example.ts` from the source to the desired destination to start with.
+This file contains a web component in the form of a class that extends the `Subscriber` mixin, with a reactive property and a render function.
+
+<sonic-code language="javascript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement, property } from "lit/decorators.js";
+import Subscriber from "@supersoniks/concorde/core/mixins/Subscriber";
+
+@customElement("sonic-example")
+export class SonicComponent extends Subscriber(LitElement) {
+  @property() text = "Example";
+  render() {
+    return html`${this.text}`;
+  }
+}
+  </template>
+</sonic-code>
+
+**You can remove the dependency on `Subscriber`** if automatic population of the component with external data is not required.
+For example, for a UI component:
+
+
+<sonic-code language="javascript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement, property } from "lit/decorators.js";
+
+@customElement("sonic-example")
+export class SonicComponent extends LitElement {
+  @property() text = "Example";
+  render() {
+    return html`${this.text}`;
+  }
+}
+  </template>
+</sonic-code>
+
+Regarding data sharing, see [Data flow](/docs/getting-started/dataFlow).
+
+### Naming the Component
+
+The class name is not necessarily important. However, it is important to **give it a component name prefixed with "sonic"** (or a prefix of your own) using the dedicated metadata already present in the copied document. For example, a button component would be named as follows:
+
+
+<sonic-code language="typescript">
+  <template>
+@customElement("sonic-button")
+  </template>
+</sonic-code>
+
+For less generic components with a specific destination, we advise to include the destination in the name.
+For example, for a "title" component in the "event" destination, the name would be simply:
+
+
+<sonic-code language="typescript">
+  <template>
+@customElement("sonic-event-title")
+  </template>
+</sonic-code>
+
+
+## Modifying It
+
+#### Creating Reactive Properties and Modifying the Render Function
+
+To do this, study the functioning of https://lit.dev and also refer to [Data flow](/docs/getting-started/dataFlow).
+
+#### HTML Structure of a Component
+
+The HTML structure of a component should remain as simple as possible.
+
+Ideally, there should be only one additional level of elements in addition to slots.
+
+- **The main component is already a wrapper**.
+  It receives classes to manage its layout, but it should not style internal elements.
+- **Slots handle the visual organization** of elements.
+- **The specificity of the component is expressed in this additional level** by adding a list, a functional native element (e.g., button), or another component.
+
+This leads to the creation of more components and thus raises questions about the hierarchical organization of files. However, this tends to atomize their roles.
+
+## Referencing It
+
+To compile the component, it needs to be referenced somewhere through an import statement. In particular, it is important to reference it in any component that uses it.
+
+In the case where it can be directly used in a page, it should also be globally referenced, especially considering the creation of **specific bundles** in the future.
+
+Here's where we add imports based on the component's location inside concorde as an example
+
+- **/core/components/functional/component-name/component-name.ts**  
+  In `/core/components/functional/functional.ts`, which is referenced in core.ts and imported in `index.ts`.
+- **/core/components/ui/component-name/component-name.ts**  
+  In `/core/components/ui/ui.ts`, which is referenced in core.ts and imported in `index.ts`.
+- **la-billetterie/components/atoms/component-name/component-name.ts**  
+  Nowhere else but where it will be used, except for possible **temporary** tests, for example, in `index.ts`.
+- **la-billetterie/components/concrete-destination/component-name/component-name.ts**  
+  In `la-billetterie/components/concrete-destination/destination-concrete.ts`. 
+  If it's a new destination, you'll need to create the corresponding import .ts file and import it in `la-billetterie.ts`.
+
+## Using It
+
+As a reminder, the component is simply integrated into the context by adding a tag with the component's name, for example:
+
+
+<sonic-code language="html">
+  <template>
+<sonic-event-title></sonic-event-title>
+  </template>
+</sonic-code>

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

@@ -0,0 +1,87 @@
+# 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<T, U>` + `@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](/core/components/functional/jsonata) |
+| Offline doc demos | `serviceURL="/docs-mock-api"` — [Local API demos](/docs/misc/docs-mock-api) |
+
+Agent skill: `concorde` (`rules/data.md`), see [AI agents](/docs/getting-started/ai-agents).
+
+## DataProviderKey
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { dp, get, set } from "@supersoniks/concorde/utils";
+
+const cartKey = new DataProviderKey&lt;{ items: string[] }&gt;("cart");
+
+set(cartKey, { items: [] });
+dp(cartKey.items).set(["a", "b"]);
+get(cartKey);
+  </template>
+</sonic-code>
+
+Dynamic paths (`users.${userId}`) → decorators or `sub()` — not `get("users.${id}")` in imperative code. Resolution rules: [Dynamic path placeholders](/docs/misc/dynamic-path).
+
+[DataProviderKey](/docs/misc/dataProviderKey)
+
+## Decorators
+
+| Decorator | Role |
+|-----------|------|
+| `@subscribe` | Read-only property from store — [data configuration](/docs/getting-started/my-first-component) (type + key + scope) |
+| `@publish` | Push property writes to store |
+| `@handle` | Method called on assignment |
+| `@ancestorAttribute` | Copy ancestor HTML attribute onto property |
+| `@get` | HTTP GET into `ApiResult&lt;T&gt;` |
+| `@post` | HTTP POST into `ApiResult&lt;T&gt;` (body from a publisher) |
+| `@put` / `@patch` | HTTP PUT / PATCH into `ApiResult&lt;T&gt;` |
+
+Walkthrough: [My first component](/docs/getting-started/my-first-component)
+
+## HTTP and lists
+
+- [@get](/docs/decorators/get) — single GET on a component
+- [@post](/docs/decorators/post) — POST with body read from a `DataProviderKey`
+- [@put](/docs/decorators/put) · [@patch](/docs/decorators/patch) — PUT / PATCH (same options as `@post`)
+- [List](/core/components/functional/list) — `fetch` + `key="data"` + `/docs-mock-api/api/users`
+- [Queue](/core/components/functional/queue) — lazy `offset=$offset&per_page=$limit` + optional `dataFilterProvider` (form → query)
+
+## Starter kit
+
+```bash
+npx @supersoniks/create-concorde-ts-starter my-app
+```
+
+Interactive routes mirror these patterns (`/concepts/*`, `/demo/*`).
+
+## Derived data (`derive` / `sonic-jsonata`)
+
+Use when you need **client-side aggregations** (groupby, top N, chart shapes) from existing DataProviders — without inline app JS in SDUI.
+
+- Primitive: `derive({ inputs, compute, output, variables? })` from `@supersoniks/concorde/utils` (read-only output, debounce, generation, cycle detection, `{output}/_state_`).
+- SDUI adapter: [`sonic-jsonata`](/core/components/functional/jsonata) (`inputProvider` → `expression` → `outputProvider`, optional `formDataProvider`).
+- vs [`sonic-mix`](/core/components/functional/mix): mix composes bidirectionally; jsonata **computes** unidirectionally.
+
+## Legacy integration
+
+| Topic | Page |
+|-------|------|
+| `data-bind` HTML (plain HTML hosts) | [HTML integration](/docs/misc/html-integration) — doc demos use Lit in `src/docs/example/` |
+| `@onAssign` | [@onAssign](/docs/decorators/on-assign) (prefer `@handle`) |
+| `sonic-fetch` alone | [Fetch](/core/components/functional/fetch) |