@supersoniks/concorde 4.7.3 → 4.8.0

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

@@ -1,163 +0,0 @@
-# @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

@@ -1,91 +0,0 @@
-# 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

@@ -1,56 +0,0 @@
-# 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

@@ -1,133 +0,0 @@
-# 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,33 +0,0 @@
-# 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 following command creates a new Vite project in TypeScript mode with Tailwind and an example component to get started.
-
-<sonic-code language="shell">
-  <template>
-npx @supersoniks/create-concorde-ts-starter "project_name"
-  </template>
-</sonic-code>
-
-Then, from the project folder:
-
-<sonic-code language="shell">
-  <template>
-yarn install
-yarn dev --host
-  </template>
-</sonic-code>
-
-## Next steps
-
-| 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,139 +0,0 @@
-# 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>
-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 `Subscriber`, see:
-
-- [🔔 Subscriber](#docs/_core-concept/subscriber.md/subscriber)
-- [🥨 Sharing Data](#docs/_getting-started/pubsub.md/pubsub)
-
-### 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 [Subscriber](#docs/_core-concept/subscriber.md/subscriber).
-
-#### 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>