@supersoniks/concorde 5.0.5 → 5.1.1

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

@@ -1,120 +0,0 @@
-# Legacy: My first subscriber component
-
-> **New projects:** use [My first component](#docs/_getting-started/my-first-component.md/my-first-component) (`@ancestorAttribute`, `@subscribe` + `DataProviderKey`, `.items` on lists) and [Data flow](#docs/_core-concept/dataFlow.md/dataFlow). This page documents the **Subscriber mixin** used by older apps and core components.
-
-Learn how to build a component with the **Subscriber** mixin, styled with Tailwind, filled from a DataProvider via automatic property mapping.
-
-## Create a classic lit component
-
-<sonic-code language="javascript" >
-  <template>
-  import { html, LitElement, nothing } from "lit";
-  import { customElement, property } from "lit/decorators.js";
-  @customElement("docs-user")
-  export class user extends LitElement {
-    @property({ type: String }) first_name = "";
-    @property({ type: String }) last_name = "";
-    @property({ type: String }) avatar = "";
-    @property({ type: String }) email = "";
-    render() {
-      return html`
-        &lt;img src="${this.avatar}" /&gt; &lt;br&gt;
-        ${this.first_name} ${this.last_name} &lt;br&gt;
-        ${this.email}`;
-    }
-  }
-  </template>
-</sonic-code>
-
-### Style with tailwind and ui components
-
-<sonic-code language="javascript">
-  <template>
-  import { css, unsafeCSS } from "lit";
-  import tailwindImport from "./css/tailwind.css?inline";
-  export const tailwind = css`${unsafeCSS(tailwindImport)}`;
-  </template>
-</sonic-code>
-
-<sonic-code language="javascript">
-  <template>
-    import { html, LitElement } from "lit";
-    import { customElement, property } from "lit/decorators.js";
-    import { tailwind } from "../tailwind";
-    import '@supersoniks/concode/ui/image'
-    import '@supersoniks/concode/ui/button'
-    import '@supersoniks/concode/ui/icon'
-    @customElement("docs-user")
-    export class user extends LitElement {
-      static styles = [tailwind];
-      @property({ type: String }) first_name = "";
-      @property({ type: String }) last_name = "";
-      @property({ type: String }) avatar = "";
-      @property({ type: String }) email = "";
-      render() {
-        return html`&lt;div class="flex items-center gap-3 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;${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;`;
-      }
-    }
-  </template>
-</sonic-code>
-
-## Add Subscriber mixin
-
-<sonic-code language="javascript">
-  <template>
-    import Subscriber from "@supersoniks/concorde/core/mixins/Subscriber";
-    @customElement("docs-user")
-    export class user extends Subscriber(LitElement) {
-      // properties auto-filled from DataProvider when names match
-    }
-  </template>
-</sonic-code>
-
-See [Legacy: Subscriber mixin](#docs/_core-concept/subscriber.md/subscriber).
-
-## Autofill from a dataProvider
-
-<sonic-code >
-<template>
-<docs-demo-sources for="list-users-fetch"></docs-demo-sources>
-<div serviceURL="/docs-mock-api">
-<sonic-fetch 
-    serviceURL="/docs-mock-api"
-    dataProvider="api/users/3" 
-    key="data">
-     <docs-user></docs-user>
-</sonic-fetch>
-</div>
-</template>
-</sonic-code>
-
-<sonic-code >
-<template>
-<sonic-fetch 
-    serviceURL="/docs-mock-api"
-    dataProvider="api/users/2" 
-    key="data"></sonic-fetch>
-<docs-user dataProvider="api/users/2" ></docs-user>
-</template>
-</sonic-code>
-
-<sonic-code >
-<template>
-<div class="grid grid-cols-1 gap-4">
-<form formDataProvider="userPreview" class="grid grid-cols-4 gap-3" >
-  <sonic-input label="First name" type="text" name="first_name" value="Paul" size="sm"></sonic-input>
-  <sonic-input label="Last name" type="text" name="last_name" value="Metrand" size="sm"></sonic-input>
-  <sonic-input class="col-span-2" label="email" type="text" name="email" value="paul@example.com" size="sm"></sonic-input>
-  <sonic-input label="Image url" type="text" name="avatar" value="https://i.pravatar.cc/150?u=paul" size="sm"></sonic-input>
-</form>
-<sonic-divider align="left">Preview before submit</sonic-divider>
-<div dataProvider="userPreview">
-  <docs-user></docs-user>
-</div>
-</div>
-</template>
-</sonic-code>

package/docs/src/docs/_getting-started/pubsub.md

@@ -1,37 +0,0 @@
-# Legacy: Sharing data
-
-> **New apps:** [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) (`get` / `set` / `DataProviderKey`, decorators). This page documents the historical **Publisher** proxy API (`PublisherManager`, `publisher.set`, `onAssign`, …).
-
-This section describes how data is shared between graphical and non-graphical components.
-
-Graphical components should not reference each other directly — they stay decoupled via a **publish/subscribe** store.
-
-## The Publisher
-
-### Principle
-
-* The **publisher** is a [JavaScript proxy](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Proxy) that holds data.<br>
-  Example: `{foo:{hello:["world"]}, bar:"baz"}`
-
-* Accessing a property (`myPublisher.foo.hello`) returns another **publisher** for that segment.
-
-* Missing properties create a publisher with internal data `null`, filled later.
-
-* **Subscribers** listen via `onAssign`, `onInternalMutation`, template filling on the **Subscriber mixin**, etc.
-
-* Updates use `publisher.set(...)` or nested assignment; changes propagate to subscribers.
-
-❇️ Order of creation vs subscription theoretically does not matter.
-
-### Methods
-
-* **set** — replace internal value  
-  <sonic-code language="javascript"><template>publisher.set({foo:{hello:["world"]}, bar:"baz"});</template></sonic-code>
-
-* **get** — read internal value  
-  <sonic-code language="javascript"><template>publisher.get()</template></sonic-code>
-
-* **onAssign / offAssign** — react to `set`  
-  <sonic-code language="javascript"><template>publisher.a.b.onAssign(console.log);</template></sonic-code>
-
-Modern equivalent: `get` / `set` / `@handle` — see [Data flow](#docs/_core-concept/dataFlow.md/dataFlow).

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

@@ -1,47 +0,0 @@
-# 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
-
-## Learn Concorde
-
-| Step | Page |
-|------|------|
-| 1 | [My first component](#docs/_getting-started/my-first-component.md/my-first-component) — Lit card, `@ancestorAttribute`, `@bind`, mock API |
-| 2 | [Data flow](#docs/_core-concept/dataFlow.md/dataFlow) — Core concepts: decorators and APIs |
-| 3 | [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) — offline `serviceURL` for this site (Misc) |
-| 4 | [create-concorde-ts-starter](https://www.npmjs.com/package/@supersoniks/create-concorde-ts-starter) — **recommended** project kit (Vite, Tailwind, `yarn ai:sync`) |
-| 5 | [AI agents (skills)](#docs/_getting-started/ai-agents.md/ai-agents) — `AGENTS.md`, Cursor / JetBrains rules |
-
-Legacy (Subscriber mixin, Publisher API): **Legacy** section at the bottom of the sidebar.
-
-## 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.md/ai-agents). Manual Vite setup: [Legacy: Manual installation](#docs/_getting-started/concorde-manual-install.md/concorde-manual-install).

package/docs/src/docs/_getting-started/theming.md

@@ -1,253 +0,0 @@
-# Customization
-
-## Theme-first customization
-
-Concorde components ship with **default styles** (fallback values in each component and in `<sonic-theme>`).  
-You do not need to define any CSS variables to get a usable UI.
-
-To align the kit with your brand, override **only the essential theme tokens** on `<sonic-theme>`, on `:root`, or in a project stylesheet.  
-Concorde derives radius steps, button/input rounding, shadows, and most per-component layout from these primitives—**do not copy long lists of derived variables** unless you have a specific need.
-
-<sonic-code language="html">
-  <template>
-<sonic-theme color font class="block bg-base min-h-screen">
-  <!-- your app -->
-</sonic-theme>
-  </template>
-</sonic-code>
-
-<sonic-code language="javascript">
-  <template>
-import "@supersoniks/concorde/theme";
-  </template>
-</sonic-code>
-
-| Attribute | Effect |
-|-----------|--------|
-| *(omit)* \| `theme="custom"` | Default: core tokens + your `--sc-*`; no built-in light/dark palette |
-| `theme="light"` \| `"dark"` \| `"auto"` | Opt-in presets; `auto` follows `prefers-color-scheme` |
-| `class="bg-base block"` (Tailwind) | Page/surface background (`--sc-base`) |
-| `color` | Text color (`--sc-base-content`) |
-| `font` | Base font family/weight (`--sc-font-family-base`, etc.) |
-
-Popovers, modals, and toasts mount under the nearest `<sonic-theme>`.
-
-## Customization example
-
-Example (full brand override on `<sonic-theme>` or `:root`). Set every essential token below; derived radii and shadows still come from the theme engine—only `--sc-rounded` is listed here.
-
-<sonic-code language="css">
-  <template>
-sonic-theme {
-  /* Semantic fills */
-  --sc-primary: #353429;
-  --sc-secondary: #f43f5e;
-  --sc-info: #7c3aed;
-  --sc-danger: #d71839;
-  --sc-warning: #f97316;
-  --sc-success: #10b981;
-  --sc-contrast: #111;
-
-  /* Text/icons on semantic fills */
-  --sc-primary-content: #fff;
-  --sc-secondary-content: #fff;
-  --sc-info-content: #fff;
-  --sc-danger-content: #fff;
-  --sc-warning-content: #fff;
-  --sc-success-content: #fff;
-  --sc-contrast-content: #fff;
-
-  /* Neutral fills */
-  --sc-base: #fff;
-  --sc-base-50: #f6f6f5;
-  --sc-base-100: #ededec;
-  --sc-base-200: #d7d7d4;
-  --sc-base-300: #c8c7c4;
-  --sc-base-400: #a8a7a2;
-  --sc-base-500: #94938c;
-  --sc-base-600: #76756c;
-  --sc-base-700: #59584e;
-  --sc-base-800: #47463b;
-  --sc-base-900: #353429;
-
-  /* Text/icons on neutral surfaces */
-  --sc-base-content: var(--sc-base-900);
-
-  /* Typography */
-  --sc-font-family-base: "Oswald", system-ui, -apple-system, "Segoe UI", Roboto,
-    "Helvetica Neue", Arial, sans-serif;
-  --sc-headings-font-family: "alternate-gothic-compressed", system-ui, sans-serif;
-  --sc-headings-line-height: 1.1;
-  --sc-headings-font-weight: bold;
-  --sc-headings-text-transform: none;
-
-  /* Shape (primitive only) */
-  --sc-rounded: 0;
-
-  /* Forms */
-  --sc-border-width: 0.2rem;
-  --sc-form-height: 2em;
-  --sc-input-bg: var(--sc-base);
-  --sc-input-color: var(--sc-base-content);
-  --sc-input-border-color: var(--sc-input-color);
-  --sc-input-active-bg: var(--sc-primary);
-  --sc-input-active-color: var(--sc-primary-content);
-  --sc-input-active-border-color: var(--sc-primary);
-}
-  </template>
-</sonic-code>
-
-<sonic-button href="https://delanfranchi.github.io/concordecolors/"> Palette generator: concordecolors</sonic-button>
-
-
-**Without these overrides**, components keep Concorde’s per-component fallbacks. Built-in light/dark palettes apply only when you set `theme="light"`, `theme="dark"`, or `theme="auto"`.
-
-**What we intentionally avoid:** large public `--sc-alert-*` / `--sc-badge-*` APIs or `::part()` styling hooks on most components. Prefer attributes (`type`, `status`, `size`, …) and the theme tokens above.
-
-
-## Only essential CSS variables (public theme API)
-
-These are the **smallest set** we recommend customizing. Everything else should stay internal to the theme or to components (`--sc_*` private variables, attributes like `type`, `size`, `variant`).
-
-### Surfaces and foreground
-
-Tokens **without** a `-content` suffix are **fill / background** colors.  
-Tokens **with** `-content` are **text and icons** on top of the matching fill (solid buttons, badges, alerts, etc.).
-
-#### Neutral fills
-
-| Variable | Role |
-|----------|------|
-| `--sc-base` | Main surface / page background |
-| `--sc-base-50` … `--sc-base-900` | Neutral scale (borders, subtle backgrounds, muted UI) |
-
-#### Neutral foreground
-
-| Variable | Role |
-|----------|------|
-| `--sc-base-content` | Default body text and icons on neutral surfaces |
-
-#### Semantic fills
-
-| Variable | Role |
-|----------|------|
-| `--sc-primary` | Primary actions, links, emphasis |
-| `--sc-secondary` | Secondary brand accent (when used) |
-| `--sc-info`, `--sc-success`, `--sc-warning`, `--sc-danger` | Status and feedback |
-| `--sc-contrast` | High-contrast fills (e.g. on media) |
-
-#### Semantic foreground
-
-| Variable | Role |
-|----------|------|
-| `--sc-primary-content`, `--sc-secondary-content`, … | Text/icons on the matching semantic **fill** (`--sc-primary`, etc.) |
-
-### Shape
-
-| Variable | Role |
-|----------|------|
-| `--sc-rounded` | **Single primitive** corner radius; the theme computes `--sc-rounded-sm`, `--sc-btn-rounded`, `--sc-input-rounded`, etc. |
-
-### Typography
-
-| Variable | Role |
-|----------|------|
-| `--sc-font-family-base` | Body UI text |
-| `--sc-font-weight-base`, `--sc-font-style-base` | Optional |
-| `--sc-headings-font-family`, `--sc-headings-line-height`, `--sc-headings-font-weight`, `--sc-headings-text-transform` | Headings (modal titles, etc.) |
-
-### Forms (only if you customize inputs globally)
-
-Interactive controls expose a few extra **theme-level** tokens; prefer these over styling individual inputs from outside.
-
-| Variable | Role |
-|----------|------|
-| `--sc-border-width` | Default border thickness |
-| `--sc-form-height` | Control height |
-| `--sc-input-bg`, `--sc-input-color`, `--sc-input-border-color` | Default field chrome |
-| `--sc-input-active-bg`, `--sc-input-active-color`, `--sc-input-active-border-color` | Focus/active state |
-
----
-
-## Tailwind in new components ?
-
-Set <code>tailwind.config.js</code> to match concorde style token in your custom component.
-
-<sonic-code language="js">
-  <template>
-...
-theme: {
-  borderRadius: {
-    DEFAULT: "var(--sc-rounded)",
-    none: "0",
-    sm: "var(--sc-rounded-sm)",
-    md: "var(--sc-rounded-md)",
-    lg: "var(--sc-rounded-lg)",
-    xl: "var(--sc-rounded-xl)",
-    full: "9999px",
-  },
-  boxShadow: {
-    DEFAULT: "var(--sc-shadow)",
-    none: "none",
-    sm: "var(--sc-shadow-sm)",
-    md: "var(--sc-shadow-md)",
-    lg: "var(--sc-shadow-lg)",
-    xl: "var(--sc-shadow-xl)",
-  },
-  colors: {
-    transparent: "transparent",
-    current: "currentColor",
-    content: "var(--sc-base-content)",
-    base: "var(--sc-base)",
-    neutral: {
-      0: "var(--sc-base)",
-      50: "var(--sc-base-50)",
-      100: "var(--sc-base-100)",
-      200: "var(--sc-base-200)",
-      300: "var(--sc-base-300)",
-      400: "var(--sc-base-400)",
-      500: "var(--sc-base-500)",
-      600: "var(--sc-base-600)",
-      700: "var(--sc-base-700)",
-      800: "var(--sc-base-800)",
-      900: "var(--sc-base-900)",
-      content: "var(--sc-base)",
-    },
-    primary: {
-      DEFAULT: "var(--sc-primary)",
-      content: "var(--sc-primary-content)",
-    },
-    success: {
-      DEFAULT: "var(--sc-success)",
-      content: "var(--sc-success-content)",
-    },
-    danger: {
-      DEFAULT: "var(--sc-danger)",
-      content: "var(--sc-danger-content)",
-    },
-    warning: {
-      DEFAULT: "var(--sc-warning)",
-      content: "var(--sc-warning-content)",
-    },
-    info: {
-      DEFAULT: "var(--sc-info)",
-      content: "var(--sc-info-content)",
-    },
-    contrast: {
-      DEFAULT: "var(--sc-contrast)",
-      content: "var(--sc-contrast-content)",
-    },
-  },
-  extend: {
-    borderWidth: {
-      DEFAULT: "var(--sc-border-width)",
-    },
-    fontFamily: {
-      headings: ["var(--sc-headings-font-family, var(--sc-font-family-base, sans-serif))"],
-      body: ["var(--sc-font-family-base)"],
-      monospace: ["var(--sc-font-family-monospace, monospace)"],
-    }
-  }
-  </template>
-</sonic-code>
-

package/docs/src/docs/_misc/api-configuration.md

@@ -1,81 +0,0 @@
-# API configuration
-
-`APIConfiguration` is the object built by [`HTML.getApiConfiguration`](../../core/utils/HTML.ts) from **ancestor attributes** on the DOM (or from a typed publisher — see [@get](#docs/_decorators/get.md/get) / [@post](#docs/_decorators/post.md/post) configuration key). It is passed to [`API`](../../core/utils/api.ts) by fetchers, **sonic-submit**, the **`wording()`** directive, **`@get`**, **`@post`**, **`@put`**, and **`@patch`**.
-
-> **Mock service:** same [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) Service Worker / Vite middleware. Routes used on this page are listed in the [API config routes](#api-config-routes) section below.
-
-## Attribute map
-
-| Attribute (ancestor) | `APIConfiguration` field | Role |
-|---------------------|---------------------------|------|
-| `serviceURL` | `serviceURL` | Base URL (e.g. `/docs-mock-api`) |
-| `token` | `token` | Static Bearer sent on REST calls |
-| `userName` / `password` | `userName` / `password` | Basic auth for **tokenProvider** fetch only |
-| `eventsApiToken` | `authToken` | Bearer for **tokenProvider** when no Basic |
-| `tokenProvider` | `tokenProvider` | Path to GET a new token (`{ token }` JSON) |
-| `wordingProvider` | — (read by `wording()`) | Base path + query for label batch GET |
-| `wordingVersionProvider` | — | Publisher id; bump version → reload wordings |
-| `credentials` | `credentials` | `fetch` credentials mode |
-| `addHTTPResponse` | `addHTTPResponse` | Attach `_sonic_http_response_` on result |
-| `cache` | `cache` | `fetch` cache mode |
-| `blockUntilDone` | `blockUntilDone` | Serialize calls per `serviceURL` |
-| `keepAlive` | `keepAlive` | `fetch` keepalive |
-
-**Lit / TypeScript:** store the same shape in a publisher and pass `DataProviderKey<APIConfiguration>` as the second argument of `@get` (see [DataProviderKey](#docs/_misc/dataProviderKey.md/dataProviderKey)).
-
-## Bearer token (static)
-
-Publisher `docsApiConfBearerKey` (`set(docsApiConfBearerKey, { token: "docs-mock-valid-token", … })`) — mock returns the protected payload.
-
-<docs-lit-demo for="docs-api-config-bearer-demo"></docs-lit-demo>
-
-## tokenProvider + Basic auth
-
-No static `token`: `API.auth()` calls `GET /docs-mock-api/auth/token` with Basic **demo** / **secret**, stores `token`, then calls the protected route.
-
-<docs-lit-demo for="docs-api-config-token-provider-demo"></docs-lit-demo>
-
-## HTTP 498 — stale token refresh
-
-Initial `token="docs-mock-stale-token"` → mock responds **498** → Concorde invalidates the token, runs `auth()` again (same `tokenProvider` + Basic), retries with `docs-mock-fresh-token`.
-
-<docs-lit-demo for="docs-api-config-stale-token-demo"></docs-lit-demo>
-
-## eventsApiToken
-
-Attribute **`eventsApiToken`** on an ancestor maps to **`authToken`** in config (used as Bearer when calling `tokenProvider`, instead of Basic).
-
-<docs-lit-demo for="docs-api-config-events-token-demo"></docs-lit-demo>
-
-## Wording API
-
-`wordingProvider="wording/labels?lang=fr"` + `wording('api-config.greeting')` in Lit. Mock returns label map from `labels[]` query params.
-
-<docs-lit-demo for="docs-api-config-wording-demo"></docs-lit-demo>
-
-## Scoped attributes (HTML / sonic-scope)
-
-Attributes on **`sonic-scope`** (or any ancestor) are visible to descendants via `getAncestorAttributeValue`.
-
-<docs-lit-demo for="docs-api-config-scoped-attrs-demo"></docs-lit-demo>
-
-## API config routes
-
-| Route | Demo |
-|-------|------|
-| `GET /docs-mock-api/auth/token` | tokenProvider, eventsApiToken |
-| `GET /docs-mock-api/api/config/protected` | Bearer / Basic / 498 |
-| `GET /docs-mock-api/wording/labels?labels[]=…&lang=fr` | `wording()` |
-
-Mock tokens (doc only): `docs-mock-valid-token`, `docs-mock-stale-token` (498), `docs-mock-fresh-token` (after refresh). Basic: **demo** / **secret**. Events token: `docs-mock-events-token`.
-
-Implementation: `src/docs/mock-api/api-config-mock.ts` (bundled in the Service Worker with `router.ts`).
-
-## See also
-
-- [@get](#docs/_decorators/get.md/get) — `APIConfiguration` + `Endpoint`
-- [@post](#docs/_decorators/post.md/post) — same configuration model for POST
-- [@put](#docs/_decorators/put.md/put) · [@patch](#docs/_decorators/patch.md/patch) — PUT / PATCH
-- [Endpoint](#docs/_misc/endpoint.md/endpoint) — typed path
-- [Local API demos](#docs/_misc/docs-mock-api.md/docs-mock-api) — offline `serviceURL`
-- [Fetch](#core/components/functional/fetch/fetch.md/fetch) — attribute table (legacy sonic-fetch)