@supersoniks/concorde 5.1.2 → 5.1.3-immutable.2

package/docs/docs/directives/sub.md

@@ -1,75 +0,0 @@
-# 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/docs/directives/t.html

@@ -1,91 +0,0 @@
-<!DOCTYPE html>
-<html lang="en" data-doc-url="https://concorde.supersoniks.org/docs/directives/t" data-doc-id="docs/directives/t">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>t() — Concorde by Supersoniks</title>
-  <meta name="description" content="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.">
-  <meta name="keywords" content="Concorde, supersoniks, docs/directives/t, t, t(), directive, wordingProvider, localStorage, wording,  are aliases of , . In plain HTML, use the [, serviceURL, t(key), labels[]">
-  <meta name="concorde-doc-id" content="docs/directives/t">
-  <link rel="canonical" href="https://concorde.supersoniks.org/docs/directives/t">
-  <link rel="alternate" type="text/markdown" href="https://concorde.supersoniks.org/docs/directives/t.md">
-</head>
-<body>
-  <header>
-    <p><a href="/docs/index.html">Concorde documentation</a> · <a href="https://concorde.supersoniks.org/docs/directives/t">same URL (interactive)</a> · <a href="/llms.txt">llms.txt</a></p>
-  </header>
-  <main>
-    <article>
-      <p class="doc-lead" id="doc-summary"><strong>Concorde directive — t()</strong>. 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. <span>Doc ID: <code>docs/directives/t</code>. Keywords: Concorde, supersoniks, docs/directives/t, t, t(), directive, wordingProvider, localStorage, wording,  are aliases of , . In plain HTML, use the [, serviceURL, t(key), labels[]. URL: <a href="https://concorde.supersoniks.org/docs/directives/t">https://concorde.supersoniks.org/docs/directives/t</a>.</span></p>
-      <h1 id="t">t()</h1>
-<p>Lit directive that renders a translated label by key. Keys are batched into one GET to the endpoint set by the nearest <code>wordingProvider</code> ancestor attribute, and results are cached in <code>localStorage</code>.</p>
-<h2 id="import">Import</h2>
-<pre><code class="language-typescript">import { t } from &quot;@supersoniks/concorde/directives/Wording&quot;;
-</code></pre>
-<p><code>wording</code> and <code>w</code> are aliases of <code>t</code>. In plain HTML, use the <a href="/core/components/functional/translation"><code>sonic-t</code></a> element.</p>
-<h2 id="usage">Usage</h2>
-<p>Set <code>serviceURL</code> and <code>wordingProvider</code> on the host component or one of its ancestors, then call <code>t(key)</code> in a template. Attributes on elements <strong>inside</strong> the component&#39;s own template are not read. Click the button to bump the version and reload the labels.</p>
-<p><docs-lit-demo for="docs-api-config-wording-demo"></docs-lit-demo></p>
-<h2 id="endpoint-contract">Endpoint contract</h2>
-<p>All keys requested in the same tick are sent in one request, appended to <code>wordingProvider</code> as <code>labels[]</code>:</p>
-<pre><code class="language-shell">GET {serviceURL}/wording/labels?lang=fr&amp;labels[]=greeting&amp;labels[]=farewell
-</code></pre>
-<p>The response is a flat map of key to label:</p>
-<pre><code class="language-json">{ &quot;greeting&quot;: &quot;Bonjour&quot;, &quot;farewell&quot;: &quot;Au revoir&quot; }
-</code></pre>
-<p>Until the label arrives, <code>t()</code> renders an empty string.</p>
-<h2 id="html-labels">HTML labels</h2>
-<p><code>t()</code> escapes the label. Use <code>unsafeWording(key)</code> for labels that contain trusted HTML.</p>
-<pre><code class="language-typescript">import { unsafeWording } from &quot;@supersoniks/concorde/directives/Wording&quot;;
-
-html`&amp;lt;p&amp;gt;${unsafeWording(&quot;terms.notice&quot;)}&amp;lt;/p&amp;gt;`;
-</code></pre>
-<h2 id="reloading-labels">Reloading labels</h2>
-<p>Labels are fetched again when:</p>
-<ul>
-<li>the <code>lang</code> attribute of <code>&lt;html&gt;</code> changes</li>
-<li>the number stored at <code>wordingVersionProvider</code> changes — bump it after publishing new labels to invalidate the <code>localStorage</code> cache</li>
-</ul>
-<h2 id="api-reference">API reference</h2>
-<table>
-<thead>
-<tr>
-<th>Function</th>
-<th>Description</th>
-</tr>
-</thead>
-<tbody><tr>
-<td><code>t(key)</code> · <code>wording(key)</code> · <code>w(key)</code></td>
-<td>Renders the escaped label for <code>key</code></td>
-</tr>
-<tr>
-<td><code>unsafeWording(key)</code></td>
-<td>Renders the label as HTML</td>
-</tr>
-<tr>
-<td><code>isWordingReady(key)</code></td>
-<td><code>true</code> once the label for <code>key</code> is loaded</td>
-</tr>
-</tbody></table>
-<table>
-<thead>
-<tr>
-<th>Ancestor attribute</th>
-<th>Description</th>
-</tr>
-</thead>
-<tbody><tr>
-<td><code>wordingProvider</code></td>
-<td>Endpoint path and query, relative to <code>serviceURL</code></td>
-</tr>
-<tr>
-<td><code>wordingVersionProvider</code></td>
-<td>DataProvider path holding a version number</td>
-</tr>
-</tbody></table>
-<p>Other ancestor attributes (<code>serviceURL</code>, <code>token</code>, …) apply as for any request: see <a href="/docs/misc/api-configuration">API configuration</a>.</p>
-
-    </article>
-  </main>
-</body>
-</html>

package/docs/docs/directives/t.md

@@ -1,73 +0,0 @@
-# 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/docs/getting-started/ai-agents.md

@@ -1,76 +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/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/docs/getting-started/components.html

@@ -1,27 +0,0 @@
-<!DOCTYPE html>
-<html lang="en" data-doc-url="https://concorde.supersoniks.org/docs/getting-started/components" data-doc-id="docs/getting-started/components">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Components — Concorde by Supersoniks</title>
-  <meta name="description" content="Every Concorde web component, grouped like the sidebar. Pick one to see its live demos, attributes and import path.">
-  <meta name="keywords" content="Concorde, supersoniks, docs/getting-started/components, components, Components, guide">
-  <meta name="concorde-doc-id" content="docs/getting-started/components">
-  <link rel="canonical" href="https://concorde.supersoniks.org/docs/getting-started/components">
-  <link rel="alternate" type="text/markdown" href="https://concorde.supersoniks.org/docs/getting-started/components.md">
-</head>
-<body>
-  <header>
-    <p><a href="/docs/index.html">Concorde documentation</a> · <a href="https://concorde.supersoniks.org/docs/getting-started/components">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 — Components</strong>. Every Concorde web component, grouped like the sidebar. Pick one to see its live demos, attributes and import path. <span>Doc ID: <code>docs/getting-started/components</code>. Keywords: Concorde, supersoniks, docs/getting-started/components, components, Components, guide. URL: <a href="https://concorde.supersoniks.org/docs/getting-started/components">https://concorde.supersoniks.org/docs/getting-started/components</a>.</span></p>
-      <h1 id="components">Components</h1>
-<p>Every Concorde web component, grouped like the sidebar. Pick one to see its live demos, attributes and import path.</p>
-<p><docs-components-index></docs-components-index></p>
-
-    </article>
-  </main>
-</body>
-</html>

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

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

@@ -1,69 +0,0 @@
-<!DOCTYPE html>
-<html lang="en" data-doc-url="https://concorde.supersoniks.org/docs/getting-started/installation" data-doc-id="docs/getting-started/installation">
-<head>
-  <meta charset="UTF-8">
-  <meta name="viewport" content="width=device-width, initial-scale=1.0">
-  <title>Installation — Concorde by Supersoniks</title>
-  <meta name="description" content="Start a new project from the official starter. It sets up Vite, TypeScript, Lit, Tailwind and Concorde in one command.">
-  <meta name="keywords" content="Concorde, supersoniks, docs/getting-started/installation, installation, Installation, guide, npx concorde enable-short-paths, yarn ai:sync, yarn dev, tsc --noEmit, document.querySelector, renderRoot">
-  <meta name="concorde-doc-id" content="docs/getting-started/installation">
-  <link rel="canonical" href="https://concorde.supersoniks.org/docs/getting-started/installation">
-  <link rel="alternate" type="text/markdown" href="https://concorde.supersoniks.org/docs/getting-started/installation.md">
-</head>
-<body>
-  <header>
-    <p><a href="/docs/index.html">Concorde documentation</a> · <a href="https://concorde.supersoniks.org/docs/getting-started/installation">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 — Installation</strong>. Start a new project from the official starter. It sets up Vite, TypeScript, Lit, Tailwind and Concorde in one command. <span>Doc ID: <code>docs/getting-started/installation</code>. Keywords: Concorde, supersoniks, docs/getting-started/installation, installation, Installation, guide, npx concorde enable-short-paths, yarn ai:sync, yarn dev, tsc --noEmit, document.querySelector, renderRoot. URL: <a href="https://concorde.supersoniks.org/docs/getting-started/installation">https://concorde.supersoniks.org/docs/getting-started/installation</a>.</span></p>
-      <h1 id="installation">Installation</h1>
-<p>Start a new project from the official starter. It sets up Vite, TypeScript, Lit, Tailwind and Concorde in one command.</p>
-<h2 id="use-the-starter">Use the starter</h2>
-<pre><code class="language-shell">npx @supersoniks/create-concorde-ts-starter my-app
-cd my-app
-yarn install
-yarn dev --host
-</code></pre>
-<p>The project includes:</p>
-<ul>
-<li>an example component to copy from</li>
-<li><code>npx concorde enable-short-paths</code> for short import paths</li>
-<li><code>yarn ai:sync</code> for <a href="/docs/getting-started/ai-agents">AI agent skills</a></li>
-</ul>
-<p>Package: <a href="https://www.npmjs.com/package/@supersoniks/create-concorde-ts-starter">create-concorde-ts-starter</a>.</p>
-<h2 id="stack">Stack</h2>
-<table>
-<thead>
-<tr>
-<th>Tool</th>
-<th>Role</th>
-</tr>
-</thead>
-<tbody><tr>
-<td><a href="https://lit.dev">Lit</a></td>
-<td>Base class, templates and reactive properties for web components</td>
-</tr>
-<tr>
-<td><a href="https://www.typescriptlang.org">TypeScript</a></td>
-<td>Decorators and typed store paths</td>
-</tr>
-<tr>
-<td><a href="https://vite.dev">Vite</a></td>
-<td>Dev server and build</td>
-</tr>
-<tr>
-<td><a href="https://tailwindcss.com">Tailwind</a></td>
-<td>Optional, layout in your components. Concorde components ship their own styles, driven by <a href="/docs/getting-started/theming">theme</a> variables</td>
-</tr>
-</tbody></table>
-<h2 id="gotchas">Gotchas</h2>
-<ul>
-<li><code>yarn dev</code> does not type-check. Run <code>tsc --noEmit</code> or a production build to catch type errors.</li>
-<li>Scripts that query the global document (<code>document.querySelector</code>, jQuery plugins, icon replacers) cannot see inside a shadow root. Query from the component&#39;s <code>renderRoot</code>, or pass the element as slotted content.</li>
-</ul>
-
-    </article>
-  </main>
-</body>
-</html>

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

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