@supersoniks/concorde 4.5.2 → 4.7.0

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

@@ -1,8 +1,17 @@
 # @subscribe
 
-Read-only binding: **only** `DataProviderKey<T>` (no legacy string path). No `reflect` option — the publisher updates the property, not the other way around.
+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.
 
-For bidirectional binding or string paths, use [@bind](#docs/_decorators/bind.md/bind).
+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
 
@@ -10,27 +19,79 @@ For bidirectional binding or string paths, use [@bind](#docs/_decorators/bind.md
   <template>
 import { subscribe } from "@supersoniks/concorde/decorators";
 import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
-//
+
 type Data = { count: number };
-const dataKey = new DataProviderKey<Data>("data");
-//
+const dataKey = new DataProviderKey&lt;Data&gt;("data");
+
 @subscribe(dataKey.count)
 @state()
 count = 0;
   </template>
 </sonic-code>
 
-## Highlights
+## Static path
 
-- Strict typing: the property type must match `T`.
-- Dynamic paths: placeholders in `DataProviderKey`, resolved from the host component’s properties.
+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**. Declare them 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 [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey).
+## See also
+
+- [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) — overview
+- [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) — paths and host generics
+- [sub()](#docs/_directives/sub.md/sub) — same paths inside `html` templates

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

@@ -30,7 +30,7 @@ The parent is registered via `customElements.define()` (vanilla JS) rather than
   <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 {
@@ -38,21 +38,21 @@ export class DemoWaitAncestorContainer extends LitElement {
     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>
@@ -60,7 +60,7 @@ export class DemoWaitAncestorValue extends LitElement {
     `;
   }
 }
-//
+
 // Demo section: register parent via customElements.define() when user clicks
 @customElement("demo-wait-ancestors-section")
 export class DemoWaitAncestorsSection extends LitElement {
@@ -83,7 +83,8 @@ export class DemoWaitAncestorsSection extends LitElement {
 
 <sonic-code>
   <template>
-<demo-wait-ancestors-section></demo-wait-ancestors-section>
+    <docs-demo-sources for="demo-wait-ancestors-section"></docs-demo-sources>
+    <demo-wait-ancestors-section></demo-wait-ancestors-section>
   </template>
 </sonic-code>
 
@@ -105,7 +106,8 @@ When the parent is defined at load and already in the DOM, the child initializes
 
 <sonic-code>
   <template>
-<demo-wait-ancestors-static-section></demo-wait-ancestors-static-section>
+    <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>
 
@@ -113,7 +115,8 @@ When the parent is defined at load and already in the DOM, the child initializes
 
 <sonic-code>
   <template>
-<demo-wait-ancestors-ready-section></demo-wait-ancestors-ready-section>
+    <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>
 
@@ -145,7 +148,7 @@ 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);
 });

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.
+
+<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/ai-agents.md

@@ -0,0 +1,56 @@
+# AI agents (skills & AGENTS.md)
+
+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/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
+
+| 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` |
+
+<sonic-code language="shell">
+  <template>
+# Starter (from project root)
+yarn ai:sync
+
+# Manual / existing project
+node node_modules/@supersoniks/concorde/scripts/ai-init.mjs
+  </template>
+</sonic-code>
+
+## Useful flags
+
+| Flag | Effect |
+|------|--------|
+| `--merge-agents` | Append to an existing `AGENTS.md` instead of replacing it |
+| `--overlay <dir>` | Copy extra rules/skills from another layer (e.g. starter kit) |
+| `--cursor-only` | Install only `.cursor/skills` and `.cursor/rules` |
+| `--jetbrains-only` | Install only `.aiassistant/rules/` |
+
+## What gets installed
+
+| Path | Role |
+|------|------|
+| `AGENTS.md` | Project-level guide for agents (Concorde conventions) |
+| `.cursor/skills/concorde/` | Core Lit + DataProvider patterns |
+| `.cursor/skills/concorde-imports/` | Short `@supersoniks/concorde/…` import paths |
+| `.cursor/skills/concorde-scope/` | `serviceURL`, `formDataProvider`, API configuration |
+| `.cursor/skills/concorde-theme/` | `sonic-theme` and `--sc-*` tokens |
+| `.cursor/skills/concorde-menu/` | `sonic-menu` navigation |
+| `.cursor/skills/concorde-get-set-dp/` | `get` / `set` / `dp` and `DataProviderKey` migration |
+| `.cursor/rules/concorde.mdc` | Cursor rules (always-on patterns) |
+| `.aiassistant/rules/concorde.md` | JetBrains AI Assistant rules |
+
+## Workflow
+
+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 `AGENTS.md`, `.cursor/`, and `.aiassistant/` 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`).
+
+Source files in the npm package: `node_modules/@supersoniks/concorde/ai/` (see also `ai/README.md` in the [Concorde repository](https://github.com/supersoniks/concorde)).

package/docs/src/docs/_getting-started/concorde-manual-install.md

@@ -0,0 +1,133 @@
+# Manual installation (Vite)
+
+> **Legacy** — for brownfield apps or custom stacks. New projects should use the [starter](#docs/_getting-started/concorde-outside.md/concorde-outside).
+
+## Brand New Vite Project
+
+Tailwind configuration is not covered here yet.
+
+### Creating the Project
+
+<sonic-code language="shell">
+  <template>
+# Pure JavaScript project
+yarn create vite --template vanilla-js
+# TypeScript project
+# (it is recommended to use this approach, which installs Lit separately if needed, via "yarn add lit")
+yarn create vite --template vanilla-ts
+# TypeScript + Lit project
+# (creating new web components, for example, to extend the fetch or subscriber mixins)
+yarn create vite --template lit-ts
+  </template>
+</sonic-code>
+
+Using Lit with TypeScript requires the following configuration in the "compilerOptions" section of the `tsconfig.json` file:
+
+<sonic-code language="json">
+  <template>
+"experimentalDecorators": true,
+"useDefineForClassFields": false
+  </template>
+</sonic-code>
+
+### Installing Concorde
+
+Navigate to the project folder created and perform the installation:
+
+<sonic-code language="shell">
+  <template>
+yarn add @supersoniks/concorde
+  </template>
+</sonic-code>
+
+Agent skills (`AGENTS.md`, Cursor / JetBrains): see [AI agents](#docs/_getting-started/ai-agents.md/ai-agents) — run `node node_modules/@supersoniks/concorde/scripts/ai-init.mjs` after install.
+
+### Development / Build
+
+<sonic-code language="shell">
+  <template>
+# Development (you can add `--host` after the command chain in package.json's dev script instead of typing it each time as shown below)
+yarn dev --host
+# Build
+yarn build
+  </template>
+</sonic-code>
+
+## Shortcut Imports
+
+Shortcut imports work by default in JavaScript, but in TypeScript, they are activated by choice as they inject data into *tsconfig.json*. Here is the command:
+
+<sonic-code language="shell">
+  <template>
+npx concorde enable-short-paths
+  </template>
+</sonic-code>
+
+Shortcut imports replace the actual paths with aliases as follows:
+
+* `@supersoniks/concorde/core/components/functional_or_ui/component/component` becomes `@supersoniks/concorde/functional_or_ui/component`
+* `@supersoniks/concorde/core/mixins_or_utils/class_name` becomes `@supersoniks/concorde/mixins_or_utils/class_name`
+
+The original paths remain accessible. Shortcut imports are used for the examples later in this documentation.
+
+## Usage
+
+### Simple Integration in HTML
+
+Import needed component in `main.ts` or wherever you want to use it:
+
+<sonic-code language="typescript">
+  <template>
+import "@supersoniks/concorde/ui/button";
+  </template>
+</sonic-code>
+
+Then in the render function ofyour component or in the HTML of the web page that includes the compiled JS, use the component as follows:
+
+<sonic-code>
+  <template>
+<sonic-button variant="outline">My button</sonic-button>
+  </template>
+</sonic-code>
+
+### Using a Mixin to Create a New Lit Component
+
+For example, create a file `my-element.ts` at the root:
+
+<sonic-code language="typescript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement, property } from "lit/decorators.js";
+import Fetcher from "@supersoniks/concorde/mixins/Fetcher";
+import Subscriber from "@supersoniks/concorde/mixins/Subscriber";
+
+@customElement("my-element")
+export class SonicComponent extends Fetcher(Subscriber(LitElement)) {
+  @property() email = "";
+  @property() first_name = "";
+  @property() last_name = "";
+
+  render() {
+    return html`<div>
+      ${this.first_name} ${this.last_name} : ${this.email}
+    </div>`;
+  }
+}
+  </template>
+</sonic-code>
+
+Import component `main.ts` or `main.js` or any other component that uses it to be compiled
+
+<sonic-code language="typescript">
+  <template>
+import "./my-element";
+  </template>
+</sonic-code>
+
+In the HTML of a JS or TS component or in the HTML of the web page containing the compiled JS:
+
+<sonic-code language="html">
+  <template>
+<my-element serviceURL="/docs-mock-api" dataProvider="api/users/2" key="data"></my-element>
+  </template>
+</sonic-code>

package/docs/src/docs/_getting-started/concorde-outside.md

@@ -1,8 +1,12 @@
 # Installation
 
+<sonic-alert status="success" label="Recommended — use the starter" size="xl" background>
+  <p><strong>For almost all new projects, use <a href="https://www.npmjs.com/package/@supersoniks/create-concorde-ts-starter">create-concorde-ts-starter</a>.</strong></p>
+  <p>You get Vite + TypeScript + Lit + Tailwind, an example component, <code>npx concorde enable-short-paths</code> ready to run, and <code>yarn ai:sync</code> for <a href="#docs/_getting-started/ai-agents.md/ai-agents">AI agent skills</a> (<code>AGENTS.md</code>, Cursor / JetBrains rules) without extra setup.</p>
+</sonic-alert>
+
 ## Starter
 
-The easiest way to use Concorde is by using the Concorde starter.  
 The following command creates a new Vite project in TypeScript mode with Tailwind and an example component to get started.
 
 <sonic-code language="shell">
@@ -11,133 +15,19 @@ npx @supersoniks/create-concorde-ts-starter "project_name"
   </template>
 </sonic-code>
 
-## Brand New Vite Project
-
-
-For a more manual configuration, you can refer to the following sections. <br/>
-However, the Tailwind configuration is not mentioned at the moment.
-
-
-### Creating the Project
+Then, from the project folder:
 
 <sonic-code language="shell">
   <template>
-# Pure JavaScript project
-yarn create vite --template vanilla-js
-# TypeScript project
-# (it is recommended to use this approach, which installs Lit separately if needed, via "yarn add lit")
-yarn create vite --template vanilla-ts
-# TypeScript + Lit project
-# (creating new web components, for example, to extend the fetch or subscriber mixins)
-yarn create vite --template lit-ts
-  </template>
-</sonic-code>
-
-Using Lit with TypeScript requires the following configuration in the "compilerOptions" section of the `tsconfig.json` file:
-
-<sonic-code language="json">
-  <template>
-"experimentalDecorators": true,
-"useDefineForClassFields": false
-  </template>
-</sonic-code>
-
-### Installing Concorde
-
-Navigate to the project folder created and perform the installation:
-
-<sonic-code language="shell">
-  <template>
-yarn add @supersoniks/concorde
-  </template>
-</sonic-code>
-
-### Development / Build
-
-<sonic-code language="shell">
-  <template>
-# Development (you can add `--host` after the command chain in package.json's dev script instead of typing it each time as shown below)
+yarn install
 yarn dev --host
-# Build
-yarn build
   </template>
 </sonic-code>
 
-## Shortcut Imports
-
-Shortcut imports work by default in JavaScript, but in TypeScript, they are activated by choice as they inject data into *tsconfig.json*. Here is the command:
-
-<sonic-code language="shell">
-  <template>
-npx concorde enable-short-paths
-  </template>
-</sonic-code>
-
-Shortcut imports replace the actual paths with aliases as follows:
-
-* `@supersoniks/concorde/core/components/functional_or_ui/component/component` becomes `@supersoniks/concorde/functional_or_ui/component`
-* `@supersoniks/concorde/core/mixins_or_utils/class_name` becomes `@supersoniks/concorde/mixins_or_utils/class_name`
+## Next steps
 
-The original paths remain accessible. Shortcut imports are used for the examples later in this documentation.
-
-## Usage
-
-### Simple Integration in HTML
-
-Import needed component in `main.ts` or wherever you want to use it:
-
-<sonic-code language="typescript">
-  <template>
-import "@supersoniks/concorde/ui/button";
-  </template>
-</sonic-code>
-
-Then in the render function ofyour component or in the HTML of the web page that includes the compiled JS, use the component as follows:
-
-<sonic-code>
-  <template>
-<sonic-button variant="outline">My button</sonic-button>
-  </template>
-</sonic-code>
-
-### Using a Mixin to Create a New Lit Component
-
-For example, create a file `my-element.ts` at the root:
-
-<sonic-code language="typescript">
-  <template>
-import { html, LitElement } from "lit";
-import { customElement, property } from "lit/decorators.js";
-import Fetcher from "@supersoniks/concorde/mixins/Fetcher";
-import Subscriber from "@supersoniks/concorde/mixins/Subscriber";
-
-@customElement("my-element")
-export class SonicComponent extends Fetcher(Subscriber(LitElement)) {
-  @property() email = "";
-  @property() first_name = "";
-  @property() last_name = "";
-
-  render() {
-    return html`<div>
-      ${this.first_name} ${this.last_name} : ${this.email}
-    </div>`;
-  }
-}
-  </template>
-</sonic-code>
-
-Import component `main.ts` or `main.js` or any other component that uses it to be compiled
-
-<sonic-code language="typescript">
-  <template>
-import "./my-element";
-  </template>
-</sonic-code>
-
-In the HTML of a JS or TS component or in the HTML of the web page containing the compiled JS:
-
-<sonic-code language="html">
-  <template>
-<my-element serviceURL="https://reqres.in" dataProvider="api/users/2" key="data"></my-element>
-  </template>
-</sonic-code>
+| Step | Page |
+|------|------|
+| Learn patterns | [My first component](#docs/_getting-started/my-first-component.md/my-first-component) |
+| Agent skills | [AI agents (skills)](#docs/_getting-started/ai-agents.md/ai-agents) — `yarn ai:sync` on the starter |
+| Brownfield / manual Vite | [Legacy: Manual installation](#docs/_getting-started/concorde-manual-install.md/concorde-manual-install) |

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

@@ -1,5 +1,7 @@
 # Creating components
 
+> **New app components:** start with [My first component](#docs/_getting-started/my-first-component.md/my-first-component) and [Data flow](#docs/_core-concept/dataFlow.md/dataFlow). The `Subscriber` mixin below is [legacy](#docs/_core-concept/subscriber.md/subscriber).
+
 ## Where to put it?
 
 In this document, we consider the src directory of the project as the root.<br>