@supersoniks/concorde 4.6.0 → 4.7.3

package/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/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/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/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>

package/src/docs/_getting-started/my-first-component.md

@@ -0,0 +1,236 @@
+# My first component
+
+Build a **Lit** user card with Tailwind and Concorde UI, then connect it to the **DataProvider** store: declare the **data configuration** (type, key, scope), and let **`@subscribe`** keep the card in sync.
+
+> Legacy approach with the **Subscriber mixin**: [Legacy: My first subscriber](#docs/_getting-started/my-first-subscriber.md/my-first-subscriber).
+
+## 1. Lit component + Tailwind
+
+Export Tailwind once (e.g. `src/docs/tailwind.ts` in this repo):
+
+<sonic-code language="typescript">
+  <template>
+import { css, unsafeCSS } from "lit";
+import tailwindImport from "./css/tailwind.css?inline";
+
+export const tailwind = css`${unsafeCSS(tailwindImport)}`;
+  </template>
+</sonic-code>
+
+User card — plain Lit properties and UI components (no store yet):
+
+<sonic-code language="typescript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement, property } from "lit/decorators.js";
+import { tailwind } from "../tailwind";
+
+@customElement("docs-user")
+export class DocsUser extends LitElement {
+  static styles = [tailwind];
+
+  @property({ type: String }) first_name = "";
+  @property({ type: String }) last_name = "";
+  @property({ type: String }) email = "";
+  @property({ type: String }) avatar = "";
+
+  render() {
+    return html`&lt;div class="flex items-center gap-3 rounded-md p-2"&gt;
+      &lt;sonic-image src=${this.avatar} rounded="md" ratio="1/1" class="w-16"&gt;&lt;/sonic-image&gt;
+      &lt;div&gt;
+        &lt;div&gt;${this.first_name} &lt;span class="font-bold"&gt;${this.last_name}&lt;/span&gt;&lt;/div&gt;
+        &lt;div class="text-sm text-neutral-400"&gt;${this.email}&lt;/div&gt;
+      &lt;/div&gt;
+    &lt;/div&gt;`;
+  }
+}
+  </template>
+</sonic-code>
+
+## 2. Data configuration
+
+The card does not hard-code user fields anymore. You declare **what** is stored, **where** it lives, and **which ancestor scope** applies — then `@subscribe` mirrors that object on the component.
+
+### Type — shape of the data
+
+`DocsUserData` documents the fields you expect at this scope (first name, email, avatar, …). TypeScript checks that `user` matches that shape.
+
+<sonic-code language="typescript">
+  <template>
+export type DocsUserData = {
+  first_name: string;
+  last_name: string;
+  email: string;
+  avatar: string;
+};
+  </template>
+</sonic-code>
+
+### Key — path in the DataProvider
+
+`docsUserRowKey` points at the store segment to read. The path `"${dataProvider}"` is resolved at runtime from a property on the component (see scope below).
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/core/utils/dataProviderKey";
+
+export const docsUserRowKey = new DataProviderKey&lt;
+  DocsUserData,
+  { dataProvider: string | null }
+&gt;("${dataProvider}");
+  </template>
+</sonic-code>
+
+The second generic (`{ dataProvider: string | null }`) lists what the host must expose so `"${dataProvider}"` can be resolved. See [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey).
+
+### Scope — which store segment applies
+
+A parent sets `dataProvider=${docsUserScopeAKey.path}` (or a list row sets `…/list-item/0`). [`@ancestorAttribute`](#docs/_decorators/ancestor-attribute.md/ancestor-attribute) copies that attribute onto `this.dataProvider`, so the key resolves to the correct branch.
+
+<sonic-code language="typescript">
+  <template>
+@ancestorAttribute("dataProvider")
+dataProvider: string | null = null;
+  </template>
+</sonic-code>
+
+### Subscribe — keep the card in sync
+
+[`@subscribe`](#docs/_decorators/subscribe.md/subscribe) watches `docsUserRowKey` and updates `user` when the store changes. Use `@state()` so Lit re-renders. The template reads `this.user` like any other property.
+
+<sonic-code language="typescript">
+  <template>
+import { html, LitElement, nothing } from "lit";
+import { customElement, state } from "lit/decorators.js";
+import {
+  ancestorAttribute,
+  subscribe,
+} from "@supersoniks/concorde/core/decorators/Subscriber";
+import { docsUserRowKey, type DocsUserData } from "./users";
+import { tailwind } from "../tailwind";
+
+@customElement("docs-user")
+export class DocsUser extends LitElement {
+  static styles = [tailwind];
+
+  @ancestorAttribute("dataProvider")
+  dataProvider: string | null = null;
+
+  @subscribe(docsUserRowKey)
+  @state()
+  user: DocsUserData | null = null;
+
+  render() {
+    const u = this.user;
+    if (!u) return nothing;
+    return html`&lt;div class="flex items-center gap-3 rounded-md p-2"&gt;
+      &lt;sonic-image src=${u.avatar} rounded="md" ratio="1/1" class="w-16"&gt;&lt;/sonic-image&gt;
+      &lt;div&gt;
+        &lt;div&gt;${u.first_name} &lt;span class="font-bold"&gt;${u.last_name}&lt;/span&gt;&lt;/div&gt;
+        &lt;div class="text-sm text-neutral-400"&gt;${u.email}&lt;/div&gt;
+      &lt;/div&gt;
+    &lt;/div&gt;`;
+  }
+}
+  </template>
+</sonic-code>
+
+Live code: `src/docs/example/users.ts`. In this repo, imports use **`core/…` paths** (short `@supersoniks/concorde/…` exports apply in **consumer apps** only).
+
+### Two scopes, one component
+
+The same `docs-user` is mounted twice. Each copy inherits a **different** nearest `dataProvider` — that is the row/list **scope**:
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="docs-user-two-scopes"></docs-demo-sources>
+    <docs-user-two-scopes></docs-user-two-scopes>
+  </template>
+</sonic-code>
+
+Markup (two isolated stores; keys from `docs-provider-keys.ts`):
+
+<sonic-code language="markup">
+  <template>
+    &lt;div class="grid md:grid-cols-2 gap-6"&gt;
+      &lt;div dataProvider="${docsUserScopeAKey.path}"&gt;
+        &lt;docs-user&gt;&lt;/docs-user&gt;
+      &lt;/div&gt;
+      &lt;div dataProvider="${docsUserScopeBKey.path}"&gt;
+        &lt;docs-user&gt;&lt;/docs-user&gt;
+      &lt;/div&gt;
+    &lt;/div&gt;
+  </template>
+</sonic-code>
+
+Seeded in `docs-provider-keys.ts` (`set(docsUserScopeAKey, …)`): **Paul** / **Marie**. Without `@ancestorAttribute`, both cards would not know which store to read.
+
+## 3. Fetch users — `sonic-list` with `.items`
+
+Use a Lit parent and the **`items`** renderer (not HTML `<template>` children). The callback receives each row object from fetch — render fields directly (`${item.first_name}`, …), like porting a template that used `data-bind` / `<sonic-value>`.
+
+<sonic-code>
+  <template>
+      <docs-lit-demo for="docs-users-list"></docs-lit-demo>
+  </template>
+</sonic-code>
+
+Wrapper (`docs-users-list.ts`):
+
+<sonic-code language="typescript">
+  <template>
+import { html, LitElement } from "lit";
+import { customElement } from "lit/decorators.js";
+import "../../core/components/functional/list/list";
+import "./users";
+
+@customElement("docs-users-list")
+export class DocsUsersList extends LitElement {
+  private items = ({ first_name, last_name, email, avatar }) => html`
+    &lt;div class="flex gap-3"&gt;
+      &lt;sonic-image src=${avatar} ...&gt;&lt;/sonic-image&gt;
+      &lt;div&gt;${first_name} &lt;b&gt;${last_name}&lt;/b&gt;&lt;/div&gt;
+      &lt;div class="text-sm text-neutral-400"&gt;${email}&lt;/div&gt;
+    &lt;/div&gt;
+  `;
+
+  render() {
+    return html`
+      &lt;sonic-list fetch dataProvider=${usersListEndpoint.path} key="data" .items=${this.items}&gt;&lt;/sonic-list&gt;
+    `;
+  }
+}
+  </template>
+</sonic-code>
+
+See [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) for `serviceURL="/docs-mock-api"`.
+
+## 4. Form preview with `formDataProvider`
+
+Edit fields in a form; the card follows the same `docsUserRowKey` when the preview host sets `dataProvider="userPreview"`.
+
+<sonic-code>
+  <template>
+    <div class="grid grid-cols-1 gap-4 max-w-xl">
+      <form formDataProvider="${docsUserPreviewKey.path}" class="grid grid-cols-2 gap-3">
+        <sonic-input label="First name" name="first_name" value="Paul" size="sm"></sonic-input>
+        <sonic-input label="Last name" name="last_name" value="Metrand" size="sm"></sonic-input>
+        <sonic-input class="col-span-2" label="Email" name="email" value="paul@example.com" size="sm"></sonic-input>
+        <sonic-input class="col-span-2" label="Avatar URL" name="avatar" value="https://i.pravatar.cc/150?u=paul" size="sm"></sonic-input>
+      </form>
+      <sonic-divider align="left">Preview</sonic-divider>
+      <div dataProvider="${docsUserPreviewKey.path}">
+        <docs-user></docs-user>
+      </div>
+    </div>
+  </template>
+</sonic-code>
+
+Use `formDataProvider` + `name` on inputs — no manual `@input` handlers ([Data flow](#docs/_core-concept/dataFlow.md/dataFlow)).
+
+## Next steps
+
+- [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) — full map
+- [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey) — typed paths and host constraints
+- [@subscribe](#docs/_decorators/subscribe.md/subscribe) / [sub()](#docs/_directives/sub.md/sub) — read-only in templates
+- [List](#core/components/functional/list/list.md/list) — `.items`, `.noItems`, `.skeleton`