@supersoniks/concorde 5.1.1 → 5.1.3

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

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

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

package/src/docs/header/header.ts

@@ -120,11 +120,13 @@ export class SonicComponent extends Subscriber(LitElement) {
       }
     });
 
-    // on hash change, hide search and mobile navigation
-    window.addEventListener("hashchange", () => {
+    // on navigation, hide search and mobile navigation
+    const onNav = () => {
       this.hideSearch();
       this.closeNavigation();
-    });
+    };
+    window.addEventListener("hashchange", onNav);
+    window.addEventListener("popstate", onNav);
   }
 
   handleColorScheme() {
@@ -181,7 +183,7 @@ export class SonicComponent extends Subscriber(LitElement) {
           <sonic-icon name="menu" library="iconoir"></sonic-icon>
         </sonic-button>
         <div class="min-w-0">
-          <sonic-link href="/" class="logo flex items-end gap-x-1">
+          <sonic-link pushState href="/" class="logo flex items-end gap-x-1">
             <svg
               class="size-8 sm:size-[2.4rem] inline-block rotate-[55deg]"
               viewBox="0 0 66 66"
@@ -217,14 +219,16 @@ export class SonicComponent extends Subscriber(LitElement) {
             class="hidden md:block"
             variant="ghost"
             size="sm"
-            href="#docs/_getting-started/start.md/start"
+            pushState
+            href="/docs/getting-started/start"
             >Docs</sonic-button
           >
           <sonic-button
             class="hidden md:block"
             variant="ghost"
             size="sm"
-            href="#docs/_getting-started/components.md/components"
+            pushState
+            href="/docs/getting-started/components"
             >Components</sonic-button
           >
           <sonic-button
@@ -375,6 +379,7 @@ export class SonicComponent extends Subscriber(LitElement) {
                   <docs-search
                     setFocus
                     class="max-w-[30rem] lg:max-w-[35rem] w-full block"
+                    @docs-search-close=${() => this.hideSearch()}
                   >
                   </docs-search>
                 </div>

package/src/docs/home/catalog.ts

@@ -14,7 +14,6 @@ export const COMPONENT_NOTES: Record<string, { tag: string; note: string }> = {
   Icon: { tag: "sonic-icon", note: "Inline SVG icons from the core set or a CDN library." },
   Image: { tag: "sonic-image", note: "Responsive image with ratio, cover fit and load transition." },
   Input: { tag: "sonic-input", note: "Text field that publishes its value to a form provider." },
-  "Input autocomplete": { tag: "sonic-input-autocomplete", note: "Field with suggestions fed by a queue." },
   Link: { tag: "sonic-link", note: "Navigation for routes, anchors and external URLs." },
   Loader: { tag: "sonic-loader", note: "Loading animation, inline or as an overlay." },
   Menu: { tag: "sonic-menu", note: "Row or column of menu items for navigation or actions." },
@@ -40,5 +39,6 @@ export const COMPONENT_NOTES: Record<string, { tag: string; note: string }> = {
   SDUI: { tag: "sonic-sdui", note: "Builds an interface from a JSON descriptor." },
   States: { tag: "sonic-states", note: "Switches content on a data value or a pattern." },
   Submit: { tag: "sonic-submit", note: "Sends a form provider to an API endpoint." },
+  Translation: { tag: "sonic-t", note: "Renders a translated label in plain HTML, by key." },
   Value: { tag: "sonic-value", note: "Prints a live value from a data provider." },
 };