@supersoniks/concorde 5.1.0 → 5.1.2

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) |
+
+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/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.

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

@@ -0,0 +1,227 @@
+# 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.
+
+## 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) and [Dynamic path placeholders](/docs/misc/dynamic-path).
+
+### Scope — which store segment applies
+
+A parent sets `dataProvider=${docsUserScopeAKey.path}` (or a list row sets `…/list-item/0`). [`@ancestorAttribute`](/docs/decorators/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) 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) 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/getting-started/dataFlow)).

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

@@ -0,0 +1,35 @@
+# Introduction
+
+## What is Concorde?
+
+Based on **[lit.dev](https://lit.dev)**, Concorde is a collection of web components for shared apps and websites.  
+Build UIs without tying components to a specific host stack, while keeping visual consistency through the smallest set of CSS variables needed to define a theme.
+
+## Why and use case
+
+In 2022, Supersoniks needed a new ticketing stack for nearly 100 sites — mobile apps, modern sites, and legacy PHP without bundlers.  
+One composable web-component library replaced many one-off apps. Lit was chosen for broad runtime compatibility.
+
+### Stack
+
+* Lit
+* TypeScript
+* Vite
+* Tailwind (starter kit, not required in the core package)
+
+### Functional features
+
+* **DataProvider** store (decorators, `get` / `set`)
+* Forms (`formDataProvider`)
+* Lists, queues, lazy loading
+* Router, states, UI kit with status variants
+
+## Start a new project
+
+<sonic-code language="bash">
+  <template>
+npx @supersoniks/create-concorde-ts-starter "project_name"
+  </template>
+</sonic-code>
+
+The starter runs **`yarn ai:sync`** for you. Details: [AI agents (skills)](/docs/getting-started/ai-agents).