@supersoniks/concorde 5.1.2 → 5.1.3-immutable.2

package/docs/src/docs/_decorators/post.md

@@ -0,0 +1,146 @@
+# @post
+
+`@post` sends the contents of a publisher and stores the response in an
+optional `ApiResult<T>` property. The property is `undefined` until a result
+is available.
+
+## Minimal usage
+
+Pass an `Endpoint<T>` and a `DataProviderKey<B>` for the request body.
+
+```typescript
+const userBodyKey = new DataProviderKey<CreateUser>("users.form");
+const createUser = post(new Endpoint<User>("users"), userBodyKey);
+
+@createUser
+@state()
+payload?: ApiResult<User>;
+```
+
+The same decorator adapts to a method and receives the complete payload:
+
+```typescript
+@post(new Endpoint<User>("users"), userBodyKey)
+handleCreate(payload?: ApiResult<User>) {
+  if (payload?.response?.ok) console.log(payload.result);
+}
+```
+
+The current body is read from `userBodyKey`. By default, the POST is sent when
+the component connects and after each body mutation. Mutations in the same
+frame are coalesced into one request.
+
+API configuration is read from the HTML scope, as with
+[@get](#docs/_decorators/get.md/get).
+
+## Sending the POST again
+
+### From the component
+
+Keep the decorator to access `send(component)`. The body is read again when the
+operation runs.
+
+```typescript
+async saveAgain() {
+  const payload = await createUser.send(this);
+  console.log(payload?.result);
+}
+```
+
+`send()` returns a `Promise<ApiResult<T> | undefined>` that resolves after the
+operation completes. It is useful for “Save” or “Retry” buttons and can repeat
+an operation with side effects.
+
+### From a method decorator
+
+The send action can decorate a local method. It runs after the method by
+default, waits for an eventual Promise to resolve, and the decorated method
+call waits for the send to complete:
+
+```typescript
+import { send } from "@supersoniks/concorde/decorators";
+
+@send(createUser)
+async save() {
+  // Prepare local state or validate the form.
+}
+```
+
+Use `{ when: "before" }` when the send must complete before the method runs:
+
+```typescript
+@send(createUser, { when: "before" })
+saveBefore() {
+  // The POST has completed before this method runs.
+}
+```
+
+The method decorator adds an explicit send. If the method also mutates the body
+publisher, set `autoPostOnBodyMutation: false` when the decorated method must
+be the only trigger.
+
+## Options (`PostOptions`)
+
+Options are the third argument, or the fourth argument when a configuration key
+is provided.
+
+- `autoPostOnBodyMutation`: send after a body mutation (default: `true`). Set
+  it to `false` to use `send()`.
+- `skipIfBodyMissing`: skip when the body is `null` or `undefined` (default:
+  `true`).
+- `refetchEveryMs`: repeat the POST at this interval. Use it only when
+  repeating the operation is intended.
+- `skipEmptyPlaceholder`: block the request when a `${...}` placeholder is
+  `""`.
+- `triggerKey`: a publisher whose `invalidate()` sends the POST again.
+
+With a configuration key:
+
+```typescript
+@post(endpoint, userBodyKey, apiConfigurationKey)
+```
+
+See [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) for
+dynamic path details.
+
+## When the POST is sent
+
+- when the component connects and the body and configuration are available;
+- after a body mutation, unless `autoPostOnBodyMutation: false`;
+- when a property used in `${...}` changes;
+- when a configuration publisher changes;
+- when the `triggerKey` publisher is invalidated;
+- when `send()` is called;
+- after each response when `refetchEveryMs` is set.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { post, type ApiResult } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
+  </template>
+</sonic-code>
+
+## Demos
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-api-post"></docs-demo-sources>
+    <demo-api-post></demo-api-post>
+    <docs-demo-sources for="demo-api-post-method"></docs-demo-sources>
+    <demo-api-post-method></demo-api-post-method>
+    <docs-demo-sources for="demo-api-post-dynamic"></docs-demo-sources>
+    <demo-api-post-dynamic></demo-api-post-dynamic>
+  </template>
+</sonic-code>
+
+See [@put](#docs/_decorators/put.md/put) and
+[@patch](#docs/_decorators/patch.md/patch): they use the same model with a
+different HTTP method.
+
+## Advanced
+
+External invalidation is currently available through `triggerKey`; it is kept
+out of the main usage examples.

package/docs/src/docs/_decorators/publish.md

@@ -0,0 +1,55 @@
+# @publish
+
+Write-only binding: assigning to the property publishes to the `DataProviderKey` path. No read subscription (inverse of [@subscribe](#docs/_decorators/subscribe.md/subscribe)).
+
+Similar to the “reflect” half of [@bind](#docs/_decorators/bind.md/bind) without listening to the publisher.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { publish } from "@supersoniks/concorde/decorators";
+import { sub } from "@supersoniks/concorde/directives";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+  </template>
+</sonic-code>
+
+## Example
+
+<sonic-code language="typescript">
+  <template>
+type PublishDemoData = { email: string; message: string };
+const publishDemoKey = new DataProviderKey<PublishDemoData>("publishDemo");
+//
+@customElement("demo-publish")
+export class DemoPublish extends LitElement {
+  @publish(publishDemoKey.email)
+  @state()
+  email = "";
+  //
+  @publish(publishDemoKey.message)
+  @state()
+  message = "";
+  //
+  render() {
+    return html`
+      <sonic-input
+        .value=${this.email}
+        @input=${(e) => (this.email = (e.target as HTMLInputElement).value)}
+        label="Email"
+      ></sonic-input>
+      <p>${sub(publishDemoKey.email)}</p>
+    `;
+  }
+}
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-publish"></docs-demo-sources>
+    <demo-publish></demo-publish>
+  </template>
+</sonic-code>
+
+Dynamic paths use the same placeholder rules as `@bind` / `@subscribe`. Resolution and `skipEmptyPlaceholder`: [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).

package/docs/src/docs/_decorators/put.md

@@ -0,0 +1,70 @@
+# @put
+
+`@put` replaces a resource with the body from a publisher. It uses exactly the
+same model as [@post](#docs/_decorators/post.md/post):
+`Endpoint<T>`, `DataProviderKey<B>`, `ApiResult<T>`, options, and the
+`send(component)` handle.
+
+## Minimal usage
+
+```typescript
+const bodyKey = new DataProviderKey<UpdateUser>("users.form");
+const updateUser = put(new Endpoint<User>("users/42"), bodyKey);
+
+@updateUser
+@state()
+payload?: ApiResult<User>;
+```
+
+The same decorator adapts to a method:
+
+```typescript
+@put(new Endpoint<User>("users/42"), bodyKey)
+handleUpdate(payload?: ApiResult<User>) {
+  if (payload?.response?.ok) console.log(payload.result);
+}
+```
+
+To run the operation again from the component:
+
+```typescript
+async update() {
+  await updateUser.send(this);
+}
+```
+
+`send(component)` returns a Promise resolved after the PUT completes. See
+[@post](#docs/_decorators/post.md/post) for the method-decorator form and the
+`when: "before"` option.
+
+The PUT is also sent automatically when the body mutates, unless
+`autoPostOnBodyMutation: false` is set. See
+[@post](#docs/_decorators/post.md/post) for the option details:
+
+- `autoPostOnBodyMutation`
+- `skipIfBodyMissing`
+- `refetchEveryMs`
+- `skipEmptyPlaceholder`
+- `triggerKey`
+
+Pass explicit API configuration as the third argument:
+
+```typescript
+@put(endpoint, bodyKey, apiConfigurationKey)
+```
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { put, type ApiResult } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { Endpoint } from "@supersoniks/concorde/utils/endpoint";
+  </template>
+</sonic-code>
+
+## See also
+
+- [@post](#docs/_decorators/post.md/post) — options and triggers
+- [@patch](#docs/_decorators/patch.md/patch) — partial update
+- [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path)

package/docs/src/docs/_decorators/subscribe.md

@@ -0,0 +1,100 @@
+# @subscribe
+
+Keeps a **Lit property** in sync with a **read-only** slice of the DataProvider store. You pass a [`DataProviderKey`](#docs/_misc/dataProviderKey.md/dataProviderKey); when that path changes, the property updates and the component re-renders.
+
+Typical setup (same idea as [My first component](#docs/_getting-started/my-first-component.md/my-first-component)):
+
+| Piece | Role |
+|-------|------|
+| **Type** `T` | Shape of the object at that path (`DocsUserData`, `{ count: number }`, …) |
+| **Key** | `DataProviderKey<T, U>` — static path (`"cart"`) or dynamic (`"users.${userIndex}"`, `"${dataProvider}"`) |
+| **Scope on the host** | Properties listed in `U` (e.g. `dataProvider`, `userIndex`) — often filled via [`@ancestorAttribute`](#docs/_decorators/ancestor-attribute.md/ancestor-attribute) |
+| **`@subscribe(key)`** | Mirrors the store into `@state()` (or another property); read-only from the component side |
+
+For **writing** back to the store from component state, use [@publish](#docs/_decorators/publish.md/publish). In templates, the same paths work with [sub()](#docs/_directives/sub.md/sub).
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { subscribe } from "@supersoniks/concorde/decorators";
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+
+type Data = { count: number };
+const dataKey = new DataProviderKey&lt;Data&gt;("data");
+
+@subscribe(dataKey.count)
+@state()
+count = 0;
+  </template>
+</sonic-code>
+
+## Static path
+
+The key path is fixed. The property type must match `T` at that segment.
+
+<sonic-code language="typescript">
+  <template>
+const cartKey = new DataProviderKey&lt;{ items: string[] }&gt;("cart");
+
+@subscribe(cartKey)
+@state()
+cart: { items: string[] } | null = null;
+  </template>
+</sonic-code>
+
+## Dynamic path and scope
+
+Placeholders `${prop}` in the key string are resolved from **properties on the same component**. While a value is `null`/`undefined`, the subscription is inactive; optional `{ skipEmptyPlaceholder: true }` also waits on `""`. Full rules: [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path).
+
+Declare dynamic props in the key’s second generic so TypeScript expects them on the host:
+
+<sonic-code language="typescript">
+  <template>
+type User = { firstName: string; lastName: string; email: string };
+
+@subscribe(new DataProviderKey&lt;User, { userIndex: number }&gt;("demoUsers.${userIndex}"))
+@state()
+user: User | null = null;
+
+@property({ type: Number }) userIndex = 0;
+  </template>
+</sonic-code>
+
+When `userIndex` changes, `@subscribe` re-resolves the path and refreshes `user`.
+
+## Row / ancestor scope
+
+List items (and wrappers like `<div dataProvider="…">`) set which branch the child reads. Pattern from the tutorial:
+
+<sonic-code language="typescript">
+  <template>
+export const rowKey = new DataProviderKey&lt;
+  User,
+  { dataProvider: string | null }
+&gt;("${dataProvider}");
+
+@ancestorAttribute("dataProvider")
+dataProvider: string | null = null;
+
+@subscribe(rowKey)
+@state()
+user: User | null = null;
+  </template>
+</sonic-code>
+
+## Demo
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-subscribe-dynamic"></docs-demo-sources>
+    <demo-subscribe-dynamic></demo-subscribe-dynamic>
+  </template>
+</sonic-code>
+
+## See also
+
+- [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) — overview
+- [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) — paths and host generics
+- [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) — `${prop}` resolution and `skipEmptyPlaceholder`
+- [sub()](#docs/_directives/sub.md/sub) — same paths inside `html` templates

package/docs/src/docs/_decorators/wait-for-ancestors.md

@@ -0,0 +1,163 @@
+# @awaitConnectedAncestors and @dispatchConnectedEvent
+
+The `@awaitConnectedAncestors` and `@dispatchConnectedEvent` decorators delay a web component's initialization until its matching ancestors have executed their `connectedCallback`. This is when contextual elements (publisher, dataProvider, etc.) are configured.
+
+## Principle
+
+When a child component attaches to the DOM, its ancestors may not yet be initialized (especially if custom element definitions are loaded asynchronously). The `@awaitConnectedAncestors` decorator delays the component's `connectedCallback` until all ancestors matching the provided CSS selectors have executed their `connectedCallback`.
+
+The `@dispatchConnectedEvent` decorator allows ancestors to signal they are ready by dispatching the `sonic-connected` event at the end of their `connectedCallback`. The event bubbles, so it can be listened to from anywhere (e.g. `document.addEventListener(CONNECTED, handler)`).
+
+Ancestors that are not web components (no hyphen in tag name) are considered connected by default and do not need to emit the event.
+
+## Usage
+
+### Import
+
+<sonic-code language="typescript">
+  <template>
+import { awaitConnectedAncestors, dispatchConnectedEvent, ancestorAttribute } from "@supersoniks/concorde/decorators";
+  </template>
+</sonic-code>
+
+### Basic example
+
+An ancestor container decorated with `@dispatchConnectedEvent()` signals when it is ready. A child component decorated with `@awaitConnectedAncestors("demo-wait-ancestor-container[dataProvider]")` waits for this container to be initialized before initializing itself. Parameters are CSS selectors (`element.matches()`).
+
+The parent is registered via `customElements.define()` (vanilla JS) rather than `@customElement`, so it can be defined later—e.g. when the user clicks a button. This demonstrates the child waiting until the parent exists.
+
+<sonic-code language="typescript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement, state } from "lit/decorators.js";
+
+// Parent: registered later via customElements.define(), not @customElement
+@dispatchConnectedEvent()
+export class DemoWaitAncestorContainer extends LitElement {
+  render() {
+    return html`<slot></slot>`;
+  }
+}
+
+// Child: waits for parent before initializing
+@customElement("demo-wait-ancestor-value")
+@awaitConnectedAncestors("demo-wait-ancestor-container[dataProvider]")
+export class DemoWaitAncestorValue extends LitElement {
+  @ancestorAttribute("dataProvider")
+  dataProvider: string | null = null;
+
+  @state() initializedAt: string = "";
+
+  connectedCallback() {
+    super.connectedCallback();
+    this.initializedAt = new Date().toISOString();
+  }
+
+  render() {
+    return html`
+      <p>DataProvider from ancestor: <strong>${this.dataProvider || "—"}</strong></p>
+      <p>Initialized at: ${this.initializedAt || "(waiting for parent…)"}</p>
+    `;
+  }
+}
+
+// Demo section: register parent via customElements.define() when user clicks
+@customElement("demo-wait-ancestors-section")
+export class DemoWaitAncestorsSection extends LitElement {
+  registerParent() {
+    if (!customElements.get("demo-wait-ancestor-container")) {
+      customElements.define("demo-wait-ancestor-container", DemoWaitAncestorContainer);
+    }
+  }
+  render() {
+    return html`
+      <sonic-button @click=${this.registerParent}>Register parent component</sonic-button>
+      <demo-wait-ancestor-container dataProvider="waitAncestorDemo">
+        <demo-wait-ancestor-value></demo-wait-ancestor-value>
+      </demo-wait-ancestor-container>
+    `;
+  }
+}
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-wait-ancestors-section"></docs-demo-sources>
+    <demo-wait-ancestors-section></demo-wait-ancestors-section>
+  </template>
+</sonic-code>
+
+### Multiple ancestors
+
+The child waits for all specified ancestors. Register outer first, then inner — the child initializes only when both are ready.
+
+<sonic-code>
+  <template>
+<demo-wait-ancestors-multi-section></demo-wait-ancestors-multi-section>
+  </template>
+</sonic-code>
+
+### Ancestors already connected
+
+When the parent is defined at load and already in the DOM, the child initializes immediately (no delay).
+
+**Static (both in DOM from start):**
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-wait-ancestors-static-section"></docs-demo-sources>
+    <demo-wait-ancestors-static-section></demo-wait-ancestors-static-section>
+  </template>
+</sonic-code>
+
+**Dynamic (child added on button click):**
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-wait-ancestors-ready-section"></docs-demo-sources>
+    <demo-wait-ancestors-ready-section></demo-wait-ancestors-ready-section>
+  </template>
+</sonic-code>
+
+## CSS selector support
+
+Parameters are CSS selectors matched via `element.matches()` — e.g. `"sonic-subscriber"`, `"sonic-subscriber[dataProvider]"`, `".my-container"`, or multiple: `"sonic-subscriber", "sonic-sdui"`.
+
+## Behavior
+
+- Ancestor search uses CSS selectors (`element.matches(selector)`) — supports tag names, classes, attributes, combinators, etc.
+- Traversal includes shadow roots (parentNode / host)
+- Non-web components (no hyphen in tag name) are considered connected by default
+- For web component ancestors, it waits for `customElements.whenDefined(tagName)` and the `sonic-connected` event (or a timeout as fallback)
+- If no matching ancestor is found, the original `connectedCallback` is called immediately
+- Ancestors that do not emit `sonic-connected` trigger the fallback after the timeout (compatibility with existing components)
+
+## Use cases
+
+These decorators are particularly useful for:
+
+- **sonic-value** inside a **sonic-subscriber**: the value waits for the subscriber to configure its publisher
+- **Components inside sonic-sdui**: wait for the SDUI to load and configure its context
+- **Any component** depending on context provided by an ancestor custom element
+
+## Listening to the connected event
+
+The `sonic-connected` event bubbles, so you can listen to it from anywhere:
+
+<sonic-code language="typescript">
+  <template>
+import { CONNECTED } from "@supersoniks/concorde/decorators";
+
+someConnectable.addEventListener(CONNECTED, (e) => {
+  console.log("Component connected:", e.target);
+});
+  </template>
+</sonic-code>
+
+## Notes
+
+- These decorators apply only to web components (classes extending `HTMLElement`)
+- The fallback timeout ensures compatibility with components that do not yet use `@dispatchConnectedEvent`
+- Traversal includes shadow roots
+- For a guarantee without relying on the timeout, decorate ancestors (Subscriber, Fetcher, etc.) with `@dispatchConnectedEvent`

package/docs/src/docs/_directives/sub.md

@@ -0,0 +1,91 @@
+# sub()
+
+Read-only Lit directive: displays the current **DataProvider** value and updates whenever it is assigned.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { sub } from "@supersoniks/concorde/directives";
+  </template>
+</sonic-code>
+
+## String path
+
+<sonic-code language="typescript">
+  <template>
+render() {
+  return html`&lt;p&gt;Count: ${sub("myCounter.count")}&lt;/p&gt;`;
+}
+  </template>
+</sonic-code>
+
+## DataProviderKey (static)
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { sub } from "@supersoniks/concorde/directives";
+
+const counterKey = new DataProviderKey&lt;{ count: number }&gt;("myCounter");
+
+render() {
+  return html`&lt;p&gt;${sub(counterKey.count)}&lt;/p&gt;`;
+}
+  </template>
+</sonic-code>
+
+## Dynamic DataProviderKey (`${prop}`)
+
+Like `@subscribe`: the path is resolved on the template **host component**; the directive re-subscribes when observed props change. Placeholder values (`null`, `""`, `0`, …): [Dynamic path placeholders](#docs/_misc/dynamic-path.md/dynamic-path) (`skipEmptyPlaceholder` not available on `sub()` yet).
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+import { sub } from "@supersoniks/concorde/directives";
+
+type User = { firstName: string; lastName: string; email: string };
+const userKey = new DataProviderKey&lt;User, { userIndex: number }&gt;(
+  "demoUsers.${userIndex}",
+);
+
+@customElement("demo-sub-dynamic")
+export class DemoSubDynamic extends LitElement {
+  @property({ type: Number }) userIndex = 0;
+
+  render() {
+    return html`
+      &lt;p&gt;${sub(userKey.email)}&lt;/p&gt;
+    `;
+  }
+}
+  </template>
+</sonic-code>
+
+## Demo
+
+<sonic-code toggleCode>
+  <template>
+    <docs-demo-sources for="demo-sub-template"></docs-demo-sources>
+    <demo-sub-template></demo-sub-template>
+  </template>
+</sonic-code>
+
+## Concatenation (forms)
+
+<sonic-code language="typescript">
+  <template>
+html`&lt;span&gt;${sub(this.formDataProvider + ".email")}&lt;/span&gt;`
+  </template>
+</sonic-code>
+
+## sub() vs get() / set() / dp()
+
+| API | Context | Dynamic `${…}` |
+|-----|----------|------------------|
+| `sub()` | Lit template, reactive | Yes |
+| `get` / `set` / `dp` | Imperative code | No |
+
+Do not replace `sub(path)` with `get(path)` in a template: `get` returns a one-time snapshot.
+
+See [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey), [@subscribe](#docs/_decorators/subscribe.md/subscribe), and the `concorde-get-set-dp` migration skill.

package/docs/src/docs/{getting-started → _getting-started}/ai-agents.md

@@ -2,7 +2,7 @@
 
 Concorde ships **skills**, **rules**, and a root **`AGENTS.md`** so Cursor, JetBrains AI Assistant, and other coding agents follow framework patterns (DataProvider, decorators, short imports, scope, theme, migrations).
 
-On a [starter](/docs/getting-started/installation) project, run `yarn ai:sync` after install. On an existing project, install Concorde first, then use `ai-init` below.
+On a [starter](#docs/_getting-started/concorde-outside.md/concorde-outside) project, run `yarn ai:sync` after install. On a [manual / brownfield](#docs/_getting-started/concorde-manual-install.md/concorde-manual-install) project, install Concorde first, then use `ai-init` below.
 
 ## Dedicated commands
 
@@ -67,8 +67,8 @@ Everything **after** `<!-- concorde-ai -->` is replaced on each `ai-init` run (i
 
 ## Workflow
 
-1. **Starter project:** [Installation](/docs/getting-started/installation) — `yarn ai:sync` is wired in the kit.
-2. **Existing project:** run **`ai-init`** after `yarn add @supersoniks/concorde`.
+1. **Starter project:** [Installation](#docs/_getting-started/concorde-outside.md/concorde-outside) — `yarn ai:sync` is wired in the kit.
+2. **Existing / manual Vite project:** [Manual installation](#docs/_getting-started/concorde-manual-install.md/concorde-manual-install), then **`ai-init`** after `yarn add @supersoniks/concorde`.
 3. Commit `.cursor/` and `.aiassistant/` (and `AGENTS.md` only if you opted in / it was created) if your team shares agent settings.
 4. Re-run the same command when you bump `@supersoniks/concorde` to refresh skills from `node_modules/@supersoniks/concorde/ai/`.
 5. In Cursor, skills under `.cursor/skills/` are picked up automatically; mention a skill in chat for focused tasks (e.g. migration → `concorde-get-set-dp`).