@supersoniks/concorde 5.1.0 → 5.1.2

package/src/docs/home/catalog.ts

@@ -0,0 +1,44 @@
+/** One-line notes for the home index, keyed by sidebar label (taken from each component page). */
+export const COMPONENT_NOTES: Record<string, { tag: string; note: string }> = {
+  Alert: { tag: "sonic-alert", note: "Inline feedback: errors, confirmations, contextual help." },
+  Badge: { tag: "sonic-badge", note: "Compact label for a status, a count or a category." },
+  Button: { tag: "sonic-button", note: "Action or link, with types, variants, sizes and loading." },
+  Captcha: { tag: "sonic-captcha", note: "ALTCHA widget wired to the surrounding form data." },
+  Card: { tag: "sonic-card", note: "Groups related content on a padded, themed surface." },
+  Checkbox: { tag: "sonic-checkbox", note: "Boolean or multi-value field that publishes to a form." },
+  Divider: { tag: "sonic-divider", note: "Horizontal or vertical separator, with an optional label." },
+  Fieldset: { tag: "sonic-fieldset", note: "Groups related controls under a legend." },
+  "Form actions": { tag: "sonic-form-actions", note: "Lays out submit, cancel and other form footer controls." },
+  "Form layout": { tag: "sonic-form-layout", note: "Responsive grid for form fields with steady spacing." },
+  Group: { tag: "sonic-group", note: "Joins buttons, inputs and selects into one row." },
+  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." },
+  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." },
+  Modal: { tag: "sonic-modal", note: "Dialog overlay with title, content and actions." },
+  Pop: { tag: "sonic-pop", note: "Floating panel anchored to a trigger." },
+  Progress: { tag: "sonic-progress", note: "Completion bar on a value and max scale, or indeterminate." },
+  Radio: { tag: "sonic-radio", note: "One choice among several, published to a form." },
+  Select: { tag: "sonic-select", note: "Drop-down choice that publishes to a form." },
+  Switch: { tag: "sonic-switch", note: "On and off toggle that publishes to a form." },
+  Table: { tag: "sonic-table", note: "Tabular data from composable rows and cells." },
+  Textarea: { tag: "sonic-textarea", note: "Multi-line text field for forms." },
+  Theme: { tag: "sonic-theme", note: "Registers the design tokens and wraps the app." },
+  Toast: { tag: "sonic-toast", note: "Short-lived feedback in a fixed stack." },
+  Tooltip: { tag: "sonic-tooltip", note: "Short label on hover and focus." },
+  Date: { tag: "sonic-date", note: "Formats dates and durations, localised." },
+  Fetch: { tag: "sonic-fetch", note: "Loads an endpoint into a data provider." },
+  If: { tag: "sonic-if", note: "Shows its content while a condition holds." },
+  List: { tag: "sonic-list", note: "Renders a fetched collection with a template." },
+  Mix: { tag: "sonic-mix", note: "Merges several data providers into one." },
+  Jsonata: { tag: "sonic-jsonata", note: "Transforms data with a JSONata expression." },
+  Queue: { tag: "sonic-queue", note: "Paginated, lazy-loaded lists, page after page." },
+  Router: { tag: "sonic-router", note: "Renders the view that matches the location." },
+  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." },
+};

package/src/docs/home/home.ts

@@ -0,0 +1,520 @@
+import { html, LitElement } from "lit";
+import { customElement, state } from "lit/decorators.js";
+import { unsafeHTML } from "lit/directives/unsafe-html.js";
+import { sectionPages } from "../navigation/components-index";
+import { COMPONENT_NOTES } from "./catalog";
+import "./mach-stage";
+
+const GET_STARTED = "/docs/getting-started/start";
+const COMPONENTS_PAGE = "/docs/getting-started/components";
+
+/**
+ * Presets for the theming instrument: palette, typeface and radius all come from tokens.
+ * `--sc-btn-rounded` is derived once on <sonic-theme>, so it is set explicitly.
+ */
+const themes = [
+  { name: "Manual", vars: "" },
+  {
+    name: "Dracula",
+    vars: [
+      "--sc-base:#282a36;--sc-base-content:#f8f8f2",
+      "--sc-base-50:#343746;--sc-base-100:#44475a;--sc-base-200:#6272a4",
+      "--sc-primary:#bd93f9;--sc-primary-content:#282a36",
+      "--sc-info:#8be9fd;--sc-info-content:#282a36",
+      "--sc-success:#50fa7b;--sc-success-content:#282a36",
+      "--sc-warning:#ffb86c;--sc-danger:#ff5555",
+      "--sc-rounded:1rem;--sc-btn-rounded:9999px",
+    ].join(";"),
+  },
+  {
+    name: "Classic",
+    vars: [
+      "--sc-base:#fbf5e6;--sc-base-content:#3b2f2f",
+      "--sc-base-50:#f3e9d2;--sc-base-100:#e9dcbd;--sc-base-200:#d6c49a",
+      "--sc-primary:#7f1d1d;--sc-primary-content:#fbf5e6",
+      "--sc-info:#1e3a8a;--sc-success:#166534;--sc-warning:#b45309",
+      '--sc-font-family-base:Georgia,"Times New Roman",serif',
+      '--sc-headings-font-family:Georgia,"Times New Roman",serif',
+      "--sc-rounded:0;--sc-btn-rounded:0",
+    ].join(";"),
+  },
+  {
+    name: "Terminal",
+    vars: [
+      "--sc-base:#0b0f0b;--sc-base-content:#b8f7c4",
+      "--sc-base-50:#111a12;--sc-base-100:#16231a;--sc-base-200:#1f3a26",
+      "--sc-primary:#22c55e;--sc-primary-content:#0b0f0b",
+      "--sc-info:#22d3ee;--sc-info-content:#0b0f0b",
+      "--sc-success:#4ade80;--sc-success-content:#0b0f0b",
+      // the Terminal preset only ever restyles the data-ui fragment
+      "--sc-font-family-base:ui-monospace,SFMono-Regular,Menlo,monospace", // taste-skill-ignore
+      "--sc-headings-font-family:ui-monospace,SFMono-Regular,Menlo,monospace", // taste-skill-ignore
+      "--sc-rounded:2px;--sc-btn-rounded:2px",
+    ].join(";"),
+  },
+];
+
+/** The same <sonic-button>, dropped in different stacks (strings: formatters leave them alone). */
+const hosts = [
+  {
+    name: "HTML",
+    language: "html",
+    code: `<script type="module" src="concorde.js"></script>
+
+<sonic-button type="primary">Book</sonic-button>`,
+  },
+  {
+    name: "React",
+    language: "javascript",
+    code: `import "@supersoniks/concorde/button";
+
+export const Book = () => (
+  <sonic-button type="primary">Book</sonic-button>
+);`,
+  },
+  {
+    name: "Vue",
+    language: "html",
+    code: `<script setup>
+import "@supersoniks/concorde/button";
+</script>
+<template><sonic-button type="primary">Book</sonic-button></template>`,
+  },
+  {
+    name: "PHP",
+    language: "html",
+    code: `<?php foreach ($flights as $f): ?>
+  <sonic-button type="primary"><?= $f->label ?></sonic-button>
+<?php endforeach ?>`,
+  },
+];
+
+const bindSnippet = `<div formDataProvider="flight">
+  <sonic-input name="captain"></sonic-input>
+</div>
+<sonic-value dataProvider="flight" key="captain"></sonic-value>`;
+
+/** What the server pushes when the gate changes (rendered by the real <sonic-sdui>). */
+const gateJson = `{
+  "nodes": [
+    {
+      "tagName": "sonic-alert",
+      "attributes": {
+        "status": "warning",
+        "background": "",
+        "label": "Gate change: AF 002 now boards at C4"
+      }
+    }
+  ]
+}`;
+const gateChange = JSON.parse(gateJson);
+
+const INSTALL = `npx @supersoniks/create-concorde-ts-starter "MyProject"`;
+
+const escapeCode = (code: string) =>
+  code.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+
+/** A read-only code block built from a string, so whitespace survives formatters. */
+const codeBlock = (code: string, language: string, className = "") =>
+  unsafeHTML(
+    `<sonic-code language="${language}" noEdit noPreview class="${className}"><template>${escapeCode(code)}</template></sonic-code>`,
+  );
+
+const INDEX_TABS = [
+  { title: "UI components", label: "Interface" },
+  { title: "Functional components", label: "Functional" },
+];
+
+/** Components listed in the sidebar, so the count follows the menu (hidden pages excluded). */
+const COMPONENT_COUNT = INDEX_TABS.reduce(
+  (total, tab) => total + sectionPages(tab.title).length,
+  0,
+);
+
+const ARCHIVE = "./img/archive/";
+
+/** Credit lines for the archive pictures (CC BY / CC BY-SA, from assets.mjs --credits). */
+const CREDITS = `Film: <a href="https://commons.wikimedia.org/wiki/File:Concorde_%26_Red_Arrows_2002.webm">“Concorde &amp; Red Arrows 2002”</a> by Steve Elliott, <a href="https://creativecommons.org/licenses/by-sa/2.0/">CC BY-SA 2.0</a>, via Wikimedia Commons.`;
+
+const tagName = "docs-home";
+/**
+ * Landing page of the documentation, set like an old technical manual.
+ * Light DOM so the global sheet and the docs helpers (sonic-code) apply.
+ */
+@customElement(tagName)
+export class DocsHome extends LitElement {
+  private observer?: IntersectionObserver;
+  private settleObserver?: IntersectionObserver;
+
+  @state() private theme = 0;
+  @state() private host = 0;
+  @state() private gate = false;
+  @state() private families = new Set([0, 1]);
+  @state() private focus = "Button";
+
+  createRenderRoot() {
+    return this;
+  }
+
+  firstUpdated() {
+    this.observer = new IntersectionObserver(
+      (records) => {
+        records.forEach((r) => {
+          if (!r.isIntersecting) return;
+          r.target.classList.add("is-visible");
+          this.observer?.unobserve(r.target);
+        });
+      },
+      { threshold: 0.12 },
+    );
+this.querySelectorAll("[data-reveal]").forEach((el) =>
+      this.observer?.observe(el),
+    );
+    // the archive photograph settles from a slight zoom as it comes in (always visible)
+    this.settleObserver = new IntersectionObserver(
+      (records) => {
+        records.forEach((r) => {
+          if (!r.isIntersecting) return;
+          r.target.classList.add("is-visible");
+          this.settleObserver?.unobserve(r.target);
+        });
+      },
+      { rootMargin: "0px 0px 25% 0px" },
+    );
+    this.querySelectorAll(".settle").forEach((el) =>
+      this.settleObserver?.observe(el),
+    );
+  }
+
+  disconnectedCallback() {
+    this.observer?.disconnect();
+    this.settleObserver?.disconnect();
+    super.disconnectedCallback();
+  }
+
+  /** The departures shown on the board; the gate switch reroutes the passenger's flight. */
+  private get flights() {
+    return [
+      { time: "10:30", flight: "AF 002", to: "New York", gate: this.gate ? "C4" : "B12", status: this.gate ? "Gate change" : "Boarding", type: this.gate ? "warning" : "success", mine: true },
+      { time: "11:15", flight: "BA 001", to: "London", gate: "A7", status: "On time", type: "default", mine: false },
+      { time: "13:40", flight: "AF 054", to: "Rio", gate: "D2", status: "Delayed", type: "danger", mine: false },
+    ];
+  }
+
+  /** Reads the switch after its own toggle (a label click fires two click events). */
+  private syncGate(e: Event) {
+    const sw = e.currentTarget as HTMLElement & { checked?: boolean };
+    window.setTimeout(() => (this.gate = !!sw.checked));
+  }
+
+
+  private renderHero() {
+    return html`<section class="hero" aria-labelledby="home-title">
+      <div class="hero-copy">
+        <h1 id="home-title" class="hero-title hero-in">
+          Web components<br />for every stack.
+        </h1>
+        <div class="hero-actions hero-in" style="--d:180ms">
+          <sonic-button size="lg" type="primary" class="signal-button" pushState href=${GET_STARTED}
+            >Open the manual</sonic-button
+          >
+          <sonic-link pushState href=${COMPONENTS_PAGE} class="text-link"
+            >Browse the components</sonic-link
+          >
+        </div>
+        <div class="hero-install hero-in" style="--d:270ms">
+          ${codeBlock(INSTALL, "bash", "hero-install-code")}
+        </div>
+      </div>
+      <div class="hero-stage">
+        <docs-mach-stage class="hero-mach"></docs-mach-stage>
+      </div>
+    </section>`;
+  }
+
+  private renderManifesto() {
+    return html`<section class="manifesto" aria-label="What Concorde is">
+      <p class="manifesto-text" data-reveal>
+        Concorde is a Lit library of ${COMPONENT_COUNT} web components. They bind data, call
+        APIs and theme themselves from plain HTML, in React, Vue, PHP or a
+        static page.
+      </p>
+    </section>`;
+  }
+
+  /** Families shown in the wall; at least one stays on. */
+  private toggleFamily(i: number) {
+    const next = new Set(this.families);
+    if (next.has(i) && next.size > 1) next.delete(i);
+    else next.add(i);
+    this.families = next;
+  }
+
+  private renderIndex() {
+    const pages = INDEX_TABS.flatMap((t, i) =>
+      this.families.has(i) ? sectionPages(t.title) : [],
+    );
+    const focus = COMPONENT_NOTES[this.focus] ?? COMPONENT_NOTES[pages[0]?.label];
+    return html`<section class="index" aria-labelledby="index-title">
+      <div class="index-head" data-reveal>
+        <h2 id="index-title" class="section-title">${COMPONENT_COUNT} components,<br />one tag each.</h2>
+        <div class="index-filters" role="group" aria-label="Component families" data-ui>
+          ${INDEX_TABS.map((t, i) => {
+            const on = this.families.has(i);
+            return html`<sonic-button
+              variant="unstyled"
+              size="lg"
+              class="index-filter"
+              aria-pressed=${on ? "true" : "false"}
+              @click=${() => this.toggleFamily(i)}
+              >[<span class="index-filter-mark">×</span>] ${t.label}
+              (${sectionPages(t.title).length})</sonic-button
+            >`;
+          })}
+        </div>
+      </div>
+      <p class="index-wall">
+          ${pages.map(
+          (page) => html`<span class="wall-item"
+              ><sonic-link
+                pushState
+                href=${page.href}
+                class="wall-name ${page.label === this.focus ? "is-focus" : ""}"
+                @mouseenter=${() => (this.focus = page.label)}
+                @focusin=${() => (this.focus = page.label)}
+                >${page.label}</sonic-link
+              ></span
+            > `,
+        )}
+      </p>
+      <div class="index-caption" aria-live="polite">
+        <code class="index-caption-tag">&lt;${focus?.tag ?? ""}&gt;</code>
+        <span class="index-caption-note">${focus?.note ?? ""}</span>
+        <sonic-link pushState href=${COMPONENTS_PAGE} class="text-link index-caption-all"
+          >All components</sonic-link
+        >
+      </div>
+    </section>`;
+  }
+
+  private renderInstruments() {
+    return html`<section class="instruments" aria-labelledby="instruments-title">
+      <h2 id="instruments-title" class="section-title instr-title" data-reveal>
+        Plumbing in attributes.
+      </h2>
+      <div class="instr-field">
+        <div class="instr-output board" data-ui style=${themes[this.theme].vars}>
+          <div class="board-head">
+            <span class="board-title">Departures</span>
+            <span class="board-airport">Paris CDG</span>
+          </div>
+          <div class="board-passenger">
+            <span class="board-label">Captain</span>
+            <span class="board-name"
+              ><sonic-value dataProvider="homeFlight" key="captain"></sonic-value
+            ></span>
+          </div>
+          <sonic-table class="board-table">
+            <sonic-thead>
+              <sonic-tr>
+                <sonic-th>Time</sonic-th>
+                <sonic-th>Flight</sonic-th>
+                <sonic-th>To</sonic-th>
+                <sonic-th>Gate</sonic-th>
+                <sonic-th>Status</sonic-th>
+              </sonic-tr>
+            </sonic-thead>
+            <sonic-tbody>
+              ${this.flights.map(
+                (f) => html`<sonic-tr class=${f.mine ? "board-mine" : ""}>
+                  <sonic-td>${f.time}</sonic-td>
+                  <sonic-td>${f.flight}</sonic-td>
+                  <sonic-td>${f.to}</sonic-td>
+                  <sonic-td>${f.gate}</sonic-td>
+                  <sonic-td
+                    ><sonic-badge size="sm" type=${f.type}>${f.status}</sonic-badge></sonic-td
+                  >
+                </sonic-tr>`,
+              )}
+            </sonic-tbody>
+          </sonic-table>
+          ${this.gate
+            ? html`<sonic-sdui dataProvider="homeGate" .props=${gateChange}></sonic-sdui>`
+            : ""}
+          <div class="board-foot">
+            <sonic-button type="primary">
+              <sonic-icon slot="prefix" name="airplane" library="iconoir"></sonic-icon>
+              Board AF 002
+            </sonic-button>
+            <span class="board-note">Rendered in ${hosts[this.host].name}</span>
+          </div>
+        </div>
+      </div>
+      <div class="instr-blocks">
+        <div class="instr-block" data-reveal>
+          <p class="instr-claim">Bind state without glue.</p>
+          <p class="instr-text">
+            The field publishes into a formDataProvider and the panel
+            subscribes. No store to set up, no event to wire.
+          </p>
+          <div formDataProvider="homeFlight">
+            <sonic-input name="captain" label="Captain" value="André Turcat"></sonic-input>
+          </div>
+          ${codeBlock(bindSnippet, "html", "instr-code")}
+        </div>
+        <div class="instr-block" data-reveal>
+          <p class="instr-claim">Restyle with a handful of tokens.</p>
+          <p class="instr-text">
+            Palette, typeface and radius are CSS custom properties. Swap them
+            and every component in the panel follows.
+          </p>
+          <sonic-group size="sm">
+            ${themes.map(
+              (t, i) => html`<sonic-button
+                type=${i === this.theme ? "primary" : "default"}
+                aria-pressed=${i === this.theme ? "true" : "false"}
+                @click=${() => (this.theme = i)}
+                >${t.name}</sonic-button
+              >`,
+            )}
+          </sonic-group>
+        </div>
+        <div class="instr-block" data-reveal>
+          <p class="instr-claim">Render screens from JSON.</p>
+          <p class="instr-text">
+            The server sends the JSON below; sonic-sdui draws it with the same components. Flip the switch to push it to the board.
+          </p>
+          <sonic-switch @click=${this.syncGate}
+            >Push a gate change from the server</sonic-switch
+          >
+          ${codeBlock(gateJson, "json", "instr-code")}
+        </div>
+        <div class="instr-block" data-reveal>
+          <p class="instr-claim">Drop the same tag in any stack.</p>
+          <p class="instr-text">
+            Standard custom elements: no wrapper per framework, no bundler
+            required on a legacy page.
+          </p>
+          <sonic-group size="sm">
+            ${hosts.map(
+              (h, i) => html`<sonic-button
+                type=${i === this.host ? "primary" : "default"}
+                aria-pressed=${i === this.host ? "true" : "false"}
+                @click=${() => (this.host = i)}
+                >${h.name}</sonic-button
+              >`,
+            )}
+          </sonic-group>
+          <div class="host-snippets">
+            ${hosts.map(
+              (h, i) => html`<div
+                class="host-snippet ${i === this.host ? "is-active" : ""}"
+                ?inert=${i !== this.host}
+              >
+                ${codeBlock(h.code, h.language, "instr-code")}
+              </div>`,
+            )}
+          </div>
+        </div>
+      </div>
+    </section>`;
+  }
+
+  private renderStory() {
+    return html`<section class="story" aria-labelledby="story-title">
+      <div class="letter">
+<h2 id="story-title" class="section-title" data-reveal>Why we built it.</h2>
+        <div class="letter-body" data-reveal style="--d:90ms">
+          <p>
+            In 2022 we needed one ticketing stack for nearly a hundred sites:
+            mobile apps, modern front ends, and PHP pages that will never see a
+            bundler.
+          </p>
+          <p>
+            Writing the same booking form five times was not an option. We
+            wanted components that any of those pages could load and that
+            would still share their data with each other.
+          </p>
+          <p>
+            We chose Lit for its reach and web components for their
+            longevity, then moved the plumbing into attributes: data
+            providers, fetchers, forms and themes.
+          </p>
+          <p>
+            We named it after the aircraft that flew Paris to New York in
+            three and a half hours. Concorde is the library we run in
+            production every day, now open to you.
+          </p>
+          <p class="letter-sign">The Supersoniks team</p>
+        </div>
+      </div>
+      <figure class="story-figure settle">
+        <img
+          src="${ARCHIVE}concorde-001-2cv.webp"
+          width="3000"
+          height="1934"
+          alt="Concorde 001 on the apron, a yellow 2CV parked under its wing, photographers walking past"
+          loading="lazy"
+          decoding="async"
+        />
+      </figure>
+    </section>`;
+  }
+
+  private renderTakeoff() {
+    return html`<section class="takeoff" aria-labelledby="takeoff-title">
+      <div class="takeoff-copy">
+        <h2 id="takeoff-title" class="takeoff-title" data-reveal>
+          Take your project<br />supersonic.
+        </h2>
+        <p class="takeoff-lead" data-reveal style="--d:60ms">
+          One command scaffolds a Vite project with Concorde, Tailwind and
+          the agent skills, ready to build.
+        </p>
+        <div class="takeoff-code" data-reveal style="--d:120ms">
+          ${codeBlock(INSTALL, "bash", "takeoff-command")}
+        </div>
+      </div>
+      <figure class="takeoff-figure">
+        <video
+          src="${ARCHIVE}concorde-red-arrows-2002.webm"
+          poster="${ARCHIVE}concorde-red-arrows-2002-poster.jpg"
+          width="640"
+          height="360"
+          autoplay
+          muted
+          loop
+          playsinline
+          aria-label="Concorde flying in formation with the Red Arrows, 2002"
+        ></video>
+      </figure>
+    </section>`;
+  }
+
+  private renderFooter() {
+    return html`<footer class="home-footer">
+      <div class="footer-line">
+        <span>Concorde, web components by Supersoniks</span>
+        <nav class="footer-links" aria-label="Footer">
+          <sonic-link pushState href=${GET_STARTED}>Docs</sonic-link>
+          <sonic-link pushState href=${COMPONENTS_PAGE}>Components</sonic-link>
+          <sonic-link href="https://www.npmjs.com/package/@supersoniks/concorde" target="_blank"
+            >npm</sonic-link
+          >
+        </nav>
+        <span class="footer-end">MIT licence · ${new Date().getFullYear()}</span>
+      </div>
+      <p class="credits">${unsafeHTML(CREDITS)}</p>
+    </footer>`;
+  }
+
+  render() {
+    return html`<div class="docs-home">
+      ${this.renderHero()} ${this.renderManifesto()} ${this.renderIndex()}
+      ${this.renderInstruments()}
+      ${this.renderStory()} ${this.renderTakeoff()}
+      ${this.renderFooter()}
+    </div>`;
+  }
+}
+