@supersoniks/concorde 5.1.2 → 5.1.3-immutable.2

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

@@ -1,227 +0,0 @@
-# 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/docs/docs/getting-started/start.html

@@ -1,47 +0,0 @@
-<!DOCTYPE html>
-<html lang="en" data-doc-url="https://concorde.supersoniks.org/docs/getting-started/start" data-doc-id="docs/getting-started/start">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Introduction — Concorde by Supersoniks</title>
-  <meta name="description" content="Based on lit.dev, Concorde is a collection of web components for shared apps and websites.">
-  <meta name="keywords" content="Concorde, supersoniks, docs/getting-started/start, start, Introduction, guide, get, set, formDataProvider, yarn ai:sync">
-  <meta name="concorde-doc-id" content="docs/getting-started/start">
-  <link rel="canonical" href="https://concorde.supersoniks.org/docs/getting-started/start">
-  <link rel="alternate" type="text/markdown" href="https://concorde.supersoniks.org/docs/getting-started/start.md">
-</head>
-<body>
-  <header>
-    <p><a href="/docs/index.html">Concorde documentation</a> · <a href="https://concorde.supersoniks.org/docs/getting-started/start">same URL (interactive)</a> · <a href="/llms.txt">llms.txt</a></p>
-  </header>
-  <main>
-    <article>
-      <p class="doc-lead" id="doc-summary"><strong>Concorde guide — Introduction</strong>. Based on lit.dev, Concorde is a collection of web components for shared apps and websites. <span>Doc ID: <code>docs/getting-started/start</code>. Keywords: Concorde, supersoniks, docs/getting-started/start, start, Introduction, guide, get, set, formDataProvider, yarn ai:sync. URL: <a href="https://concorde.supersoniks.org/docs/getting-started/start">https://concorde.supersoniks.org/docs/getting-started/start</a>.</span></p>
-      <h1 id="introduction">Introduction</h1>
-<h2 id="what-is-concorde">What is Concorde?</h2>
-<p>Based on <strong><a href="https://lit.dev">lit.dev</a></strong>, Concorde is a collection of web components for shared apps and websites.<br>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.</p>
-<h2 id="why-and-use-case">Why and use case</h2>
-<p>In 2022, Supersoniks needed a new ticketing stack for nearly 100 sites — mobile apps, modern sites, and legacy PHP without bundlers.<br>One composable web-component library replaced many one-off apps. Lit was chosen for broad runtime compatibility.</p>
-<h3 id="stack">Stack</h3>
-<ul>
-<li>Lit</li>
-<li>TypeScript</li>
-<li>Vite</li>
-<li>Tailwind (starter kit, not required in the core package)</li>
-</ul>
-<h3 id="functional-features">Functional features</h3>
-<ul>
-<li><strong>DataProvider</strong> store (decorators, <code>get</code> / <code>set</code>)</li>
-<li>Forms (<code>formDataProvider</code>)</li>
-<li>Lists, queues, lazy loading</li>
-<li>Router, states, UI kit with status variants</li>
-</ul>
-<h2 id="start-a-new-project">Start a new project</h2>
-<pre><code class="language-bash">npx @supersoniks/create-concorde-ts-starter &quot;project_name&quot;
-</code></pre>
-<p>The starter runs <strong><code>yarn ai:sync</code></strong> for you. Details: <a href="/docs/getting-started/ai-agents">AI agents (skills)</a>.</p>
-
-    </article>
-  </main>
-</body>
-</html>

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

@@ -1,35 +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
-
-## 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).

package/docs/docs/getting-started/theming.md

@@ -1,253 +0,0 @@
-# Theming 
-
-## 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 >
-  <!-- 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>
-