@supersoniks/concorde 5.1.1 → 5.1.2

package/docs/src/docs/directives/sub.md

@@ -0,0 +1,75 @@
+# sub()
+
+`sub(path)` is a Lit directive that renders the current value of a store path and updates in place on every assignment. Use it inside `html` templates for read-only display; in a decorator, the same path goes to [@subscribe](/docs/decorators/subscribe). See [Data flow](/docs/getting-started/dataFlow) for the overall model.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { sub } from "@supersoniks/concorde/directives";
+
+render() {
+  return html`&lt;p&gt;Altitude: ${sub("cockpit.altitude")} ft&lt;/p&gt;`;
+}
+  </template>
+</sonic-code>
+
+## DataProviderKey
+
+Pass a [DataProviderKey](/docs/misc/dataProviderKey) instead of a string to get a typo-safe path. Until the publisher holds a value, nothing is rendered.
+
+<sonic-code language="typescript">
+  <template>
+import { DataProviderKey } from "@supersoniks/concorde/dataProviderKey";
+
+const flightKey = new DataProviderKey&lt;{ code: string; gate: string }&gt;("flight");
+
+render() {
+  return html`&lt;p&gt;${sub(flightKey.code)} · gate ${sub(flightKey.gate)}&lt;/p&gt;`;
+}
+  </template>
+</sonic-code>
+
+## Dynamic path
+
+`${prop}` placeholders resolve from properties of the component that renders the template; the directive re-subscribes when they change. While a placeholder is `null` or `undefined`, nothing is rendered. Rules: [Dynamic paths](/docs/misc/dynamic-path). `skipEmptyPlaceholder` is not available on `sub()`.
+
+<sonic-code language="typescript">
+  <template>
+const personKey = new DataProviderKey&lt;OnBoard, { seatIndex: number }&gt;(
+  "demoOnBoard.${seatIndex}",
+);
+
+@property({ type: Number }) seatIndex = 0;
+
+render() {
+  return html`&lt;strong&gt;${sub(personKey.name)}&lt;/strong&gt; · ${sub(personKey.role)}`;
+}
+  </template>
+</sonic-code>
+
+<sonic-code>
+  <template>
+    <docs-demo-sources for="demo-sub-template"></docs-demo-sources>
+    <demo-sub-template></demo-sub-template>
+  </template>
+</sonic-code>
+
+## sub() or get()
+
+`get(path)` from `@supersoniks/concorde/utils` returns a one-time snapshot: in a template it never updates. Use `sub()` in templates and `get` / `set` / `dp` in imperative code.
+
+<sonic-code language="typescript">
+  <template>
+html`${sub(flightKey.gate)}`; // updates on gate change
+html`${get(flightKey.gate)}`; // frozen at first render
+  </template>
+</sonic-code>
+
+## API reference
+
+| Argument | Type | Description |
+|----------|------|-------------|
+| `path` | `string` or `DataProviderKey<T, U>` | Path to read. Placeholders resolve on the template host |
+
+The directive subscribes when its part connects and unsubscribes when it disconnects.

package/docs/src/docs/directives/t.md

@@ -0,0 +1,73 @@
+# t()
+
+Lit directive that renders a translated label by key. Keys are batched into one GET to the endpoint set by the nearest `wordingProvider` ancestor attribute, and results are cached in `localStorage`.
+
+## Import
+
+<sonic-code language="typescript">
+  <template>
+import { t } from "@supersoniks/concorde/directives/Wording";
+  </template>
+</sonic-code>
+
+`wording` and `w` are aliases of `t`. In plain HTML, use the [`sonic-t`](/core/components/functional/translation) element.
+
+## Usage
+
+Set `serviceURL` and `wordingProvider` on the host component or one of its ancestors, then call `t(key)` in a template. Attributes on elements **inside** the component's own template are not read. Click the button to bump the version and reload the labels.
+
+<docs-lit-demo for="docs-api-config-wording-demo"></docs-lit-demo>
+
+## Endpoint contract
+
+All keys requested in the same tick are sent in one request, appended to `wordingProvider` as `labels[]`:
+
+<sonic-code language="shell">
+  <template>
+GET {serviceURL}/wording/labels?lang=fr&labels[]=greeting&labels[]=farewell
+  </template>
+</sonic-code>
+
+The response is a flat map of key to label:
+
+<sonic-code language="json">
+  <template>
+{ "greeting": "Bonjour", "farewell": "Au revoir" }
+  </template>
+</sonic-code>
+
+Until the label arrives, `t()` renders an empty string.
+
+## HTML labels
+
+`t()` escapes the label. Use `unsafeWording(key)` for labels that contain trusted HTML.
+
+<sonic-code language="typescript">
+  <template>
+import { unsafeWording } from "@supersoniks/concorde/directives/Wording";
+
+html`&lt;p&gt;${unsafeWording("terms.notice")}&lt;/p&gt;`;
+  </template>
+</sonic-code>
+
+## Reloading labels
+
+Labels are fetched again when:
+
+- the `lang` attribute of `<html>` changes
+- the number stored at `wordingVersionProvider` changes — bump it after publishing new labels to invalidate the `localStorage` cache
+
+## API reference
+
+| Function | Description |
+|----------|-------------|
+| `t(key)` · `wording(key)` · `w(key)` | Renders the escaped label for `key` |
+| `unsafeWording(key)` | Renders the label as HTML |
+| `isWordingReady(key)` | `true` once the label for `key` is loaded |
+
+| Ancestor attribute | Description |
+|--------------------|-------------|
+| `wordingProvider` | Endpoint path and query, relative to `serviceURL` |
+| `wordingVersionProvider` | DataProvider path holding a version number |
+
+Other ancestor attributes (`serviceURL`, `token`, …) apply as for any request: see [API configuration](/docs/misc/api-configuration).

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

@@ -0,0 +1,76 @@
+# 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/installation) project, run `yarn ai:sync` after install. On an existing 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 |
+|------|--------|
+| `--skip-agents` | Never write `AGENTS.md` (skills / rules only) |
+| `--merge-agents` | Opt-in: keep the project preamble and append / refresh the Concorde block |
+| `--force-agents` | Opt-in: **replace** the whole `AGENTS.md` (destructive) |
+| `--overlay <dir>` | Extra rules/skills + optional `AGENTS.concorde.md` for project-only Concorde agent notes |
+| `--cursor-only` | Install only `.cursor/skills` and `.cursor/rules` |
+| `--jetbrains-only` | Install only `.aiassistant/rules/` |
+
+## `AGENTS.md` policy (non-invasive)
+
+| Situation | Default |
+|-----------|---------|
+| No `AGENTS.md` | Create the Concorde guide |
+| File with `<!-- concorde-ai -->` | Refresh the managed zone only |
+| File **without** marker (project notes) | **Left untouched** — skills / rules are enough |
+| `--merge-agents` / `--force-agents` / `--skip-agents` | See flags above |
+
+```text
+[optional project preamble — short, project-only]
+<!-- concorde-ai -->
+<package ai/AGENTS.md>
+[--- + overlay AGENTS.concorde.md]
+```
+
+Everything **after** `<!-- concorde-ai -->` is replaced on each `ai-init` run (idempotent). Do not paste a full copy of the Concorde guide above the marker — put project-specific notes in `AGENTS.concorde.md` (overlay). If the preamble duplicates package `AGENTS.md`, `ai-init` slims or drops it and prints a warning. Legacy filenames `AGENTS.overlay.md` / `AGENTS.starter.md` are still accepted with a deprecation warning.
+
+## What gets installed
+
+| Path | Role |
+|------|------|
+| `AGENTS.md` | Created only if missing; existing project-owned files are left alone unless `--merge-agents` / `--force-agents` |
+| `.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/installation) — `yarn ai:sync` is wired in the kit.
+2. **Existing project:** run **`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`).
+
+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/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/docs/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/docs/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) |
+
+Skill: `concorde-get-set-dp` in the package `ai/` folder.
+
+## 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) |

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

@@ -0,0 +1,36 @@
+# Installation
+
+Start a new project from the official starter. It sets up Vite, TypeScript, Lit, Tailwind and Concorde in one command.
+
+## Use the starter
+
+<sonic-code language="shell">
+  <template>
+npx @supersoniks/create-concorde-ts-starter my-app
+cd my-app
+yarn install
+yarn dev --host
+  </template>
+</sonic-code>
+
+The project includes:
+
+- an example component to copy from
+- `npx concorde enable-short-paths` for short import paths
+- `yarn ai:sync` for [AI agent skills](/docs/getting-started/ai-agents)
+
+Package: [create-concorde-ts-starter](https://www.npmjs.com/package/@supersoniks/create-concorde-ts-starter).
+
+## Stack
+
+| Tool | Role |
+|------|------|
+| [Lit](https://lit.dev) | Base class, templates and reactive properties for web components |
+| [TypeScript](https://www.typescriptlang.org) | Decorators and typed store paths |
+| [Vite](https://vite.dev) | Dev server and build |
+| [Tailwind](https://tailwindcss.com) | Optional, layout in your components. Concorde components ship their own styles, driven by [theme](/docs/getting-started/theming) variables |
+
+## Gotchas
+
+- `yarn dev` does not type-check. Run `tsc --noEmit` or a production build to catch type errors.
+- Scripts that query the global document (`document.querySelector`, jQuery plugins, icon replacers) cannot see inside a shadow root. Query from the component's `renderRoot`, or pass the element as slotted content.