@supersoniks/concorde 5.1.1 → 5.1.3-immutable.1

package/scripts/site-pages.mjs

@@ -0,0 +1,212 @@
+/**
+ * Homepage JSON-LD and the root site pages (/about, /privacy).
+ *
+ * Page content lives in site-pages/*.md: the SPA renders it at /about, and
+ * the build publishes `slug.md` + `slug.html` (SPA shell with the page
+ * inlined for crawlers and link previews).
+ */
+import fs from "fs";
+import { fileURLToPath } from "url";
+
+export const SITE_ORIGIN = "https://concorde.supersoniks.org";
+export const NPM_URL = "https://www.npmjs.com/package/@supersoniks/concorde";
+
+/** Publisher details, from https://supersoniks.com/mentions-legales */
+export const ORGANIZATION = {
+  name: "Supersoniks",
+  legalName: "SUPERSONIKS",
+  url: "https://supersoniks.com/",
+  contactUrl: "https://supersoniks.com/un-projet",
+  telephone: "+33 2 47 68 93 25",
+  streetAddress: "22 rue du Docteur Bretonneau",
+  postalCode: "37000",
+  addressLocality: "Tours",
+  addressCountry: "FR",
+  sameAs: [
+    "https://www.linkedin.com/company/supersoniks/",
+    "https://www.facebook.com/supersoniks",
+    "https://www.instagram.com/agencesupersoniks/",
+  ],
+};
+
+function escapeHtml(text) {
+  return String(text)
+    .replace(/&/g, "&")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/* -------------------------------------------------------------------------- */
+/* JSON-LD                                                                    */
+/* -------------------------------------------------------------------------- */
+
+export function organizationJsonLd() {
+  return {
+    "@type": "Organization",
+    "@id": `${ORGANIZATION.url}#organization`,
+    name: ORGANIZATION.name,
+    legalName: ORGANIZATION.legalName,
+    url: ORGANIZATION.url,
+    telephone: ORGANIZATION.telephone,
+    address: {
+      "@type": "PostalAddress",
+      streetAddress: ORGANIZATION.streetAddress,
+      postalCode: ORGANIZATION.postalCode,
+      addressLocality: ORGANIZATION.addressLocality,
+      addressCountry: ORGANIZATION.addressCountry,
+    },
+    contactPoint: {
+      "@type": "ContactPoint",
+      contactType: "customer service",
+      telephone: ORGANIZATION.telephone,
+      url: ORGANIZATION.contactUrl,
+      availableLanguage: ["fr", "en"],
+    },
+    sameAs: ORGANIZATION.sameAs,
+  };
+}
+
+/** Homepage graph: WebSite + SoftwareApplication + Organization. */
+export function homepageJsonLd() {
+  const org = { "@id": `${ORGANIZATION.url}#organization` };
+  return {
+    "@context": "https://schema.org",
+    "@graph": [
+      {
+        "@type": "WebSite",
+        "@id": `${SITE_ORIGIN}/#website`,
+        name: "Concorde",
+        alternateName: "Concorde by Supersoniks",
+        url: `${SITE_ORIGIN}/`,
+        inLanguage: "en",
+        publisher: org,
+      },
+      {
+        "@type": "SoftwareApplication",
+        "@id": `${SITE_ORIGIN}/#software`,
+        name: "Concorde",
+        alternateName: "@supersoniks/concorde",
+        description:
+          "Concorde is an open-source web components framework built on Lit: UI components, data binding, forms, routing helpers and theming that work in React, Vue, PHP or plain HTML.",
+        url: `${SITE_ORIGIN}/`,
+        applicationCategory: "DeveloperApplication",
+        applicationSubCategory: "Web components framework",
+        operatingSystem: "Any (web browser)",
+        programmingLanguage: "TypeScript",
+        license: "https://opensource.org/licenses/MIT",
+        downloadUrl: NPM_URL,
+        softwareHelp: `${SITE_ORIGIN}/docs/getting-started/start`,
+        image: `${SITE_ORIGIN}/img/og-concorde.jpg`,
+        offers: { "@type": "Offer", price: "0", priceCurrency: "EUR" },
+        author: org,
+        publisher: org,
+        sameAs: [NPM_URL],
+      },
+      organizationJsonLd(),
+    ],
+  };
+}
+
+/* -------------------------------------------------------------------------- */
+/* Site pages: /about, /privacy                                               */
+/* -------------------------------------------------------------------------- */
+
+const SITE_PAGES_DIR = fileURLToPath(new URL("../site-pages/", import.meta.url));
+
+export const STATIC_PAGES = [
+  {
+    slug: "about",
+    title: "About Concorde — web components framework by Supersoniks",
+    description:
+      "Concorde is an open-source Lit web components framework designed and maintained by Supersoniks, Tours, France.",
+  },
+  {
+    slug: "privacy",
+    title: "Privacy notice — Concorde by Supersoniks",
+    description:
+      "Privacy notice of the Concorde documentation site: no cookies, no analytics, third-party hosts and your GDPR rights.",
+  },
+].map((page) => ({
+  ...page,
+  markdown: fs.readFileSync(`${SITE_PAGES_DIR}${page.slug}.md`, "utf8"),
+}));
+
+function pageJsonLd(page) {
+  return {
+    "@context": "https://schema.org",
+    "@type": page.slug === "about" ? "AboutPage" : "WebPage",
+    name: page.title,
+    description: page.description,
+    url: `${SITE_ORIGIN}/${page.slug}`,
+    isPartOf: { "@type": "WebSite", name: "Concorde", url: `${SITE_ORIGIN}/` },
+    publisher: organizationJsonLd(),
+  };
+}
+
+function replaceOnce(html, re, replacement, what) {
+  if (!re.test(html)) throw new Error(`site page shell: ${what} not found`);
+  return html.replace(re, () => replacement);
+}
+
+/**
+ * `slug.html`: the SPA shell (built docs/index.html) with the page's
+ * metadata and its rendered content in the no-JS section. Browsers boot the
+ * SPA, which renders the same Markdown; crawlers read the inline copy.
+ */
+export function renderSitePage(page, bodyHtml, shellHtml) {
+  const url = `${SITE_ORIGIN}/${page.slug}`;
+  const title = escapeHtml(page.title);
+  const description = escapeHtml(page.description);
+  let html = shellHtml;
+  html = replaceOnce(html, /<title>[\s\S]*?<\/title>/, `<title>${title}</title>`, "title");
+  html = replaceOnce(
+    html,
+    /<meta\s+name="description"\s+content="[^"]*"\s*\/?>/,
+    `<meta name="description" content="${description}" />`,
+    "description",
+  );
+  html = replaceOnce(
+    html,
+    /<link rel="canonical" href="[^"]*"\s*\/?>/,
+    `<link rel="canonical" href="${url}" />`,
+    "canonical",
+  );
+  html = replaceOnce(
+    html,
+    /<link rel="alternate" type="text\/markdown" href="[^"]*"/,
+    `<link rel="alternate" type="text/markdown" href="/${page.slug}.md"`,
+    "markdown alternate",
+  );
+  html = replaceOnce(
+    html,
+    /<meta property="og:title" content="[^"]*"/,
+    `<meta property="og:title" content="${title}"`,
+    "og:title",
+  );
+  html = replaceOnce(
+    html,
+    /<meta property="og:description" content="[^"]*"/,
+    `<meta property="og:description" content="${description}"`,
+    "og:description",
+  );
+  html = replaceOnce(
+    html,
+    /<meta property="og:url" content="[^"]*"/,
+    `<meta property="og:url" content="${url}"`,
+    "og:url",
+  );
+  html = replaceOnce(
+    html,
+    /<script type="application\/ld\+json">[\s\S]*?<\/script>/,
+    `<script type="application/ld+json">${JSON.stringify(pageJsonLd(page))}</script>`,
+    "JSON-LD",
+  );
+  html = replaceOnce(
+    html,
+    /<section id="docs-agent-content"([^>]*)>[\s\S]*?<\/section>/,
+    `<section id="docs-agent-content" aria-hidden="true">\n${bodyHtml}\n    </section>`,
+    "page section",
+  );
+  return html;
+}

package/scripts/site-pages.test.mjs

@@ -0,0 +1,116 @@
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
+import path from "path";
+import test from "node:test";
+import { STATIC_PAGES, homepageJsonLd } from "./site-pages.mjs";
+import {
+  generateHomepageMarkdown,
+  generateHtaccess,
+  generateSitemap,
+  writeAgentSiteArtifacts,
+} from "./generate-crawl-docs.mjs";
+
+function stripTags(html) {
+  return html
+    .replace(/<[^>]+>/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+}
+
+test("homepage JSON-LD has SoftwareApplication and complete Organization", () => {
+  const ld = homepageJsonLd();
+  assert.equal(ld["@context"], "https://schema.org");
+  const byType = Object.fromEntries(ld["@graph"].map((n) => [n["@type"], n]));
+  const app = byType.SoftwareApplication;
+  assert.ok(app.name && app.description && app.url && app.offers);
+  assert.equal(app.publisher["@id"], byType.Organization["@id"]);
+  const org = byType.Organization;
+  assert.equal(org.url, "https://supersoniks.com/");
+  assert.equal(org.address["@type"], "PostalAddress");
+  assert.equal(org.address.addressLocality, "Tours");
+  assert.equal(org.contactPoint["@type"], "ContactPoint");
+  assert.ok(org.contactPoint.contactType && org.contactPoint.telephone);
+  assert.ok(org.sameAs.every((u) => u.startsWith("https://")));
+});
+
+test("source index.html embeds the generated JSON-LD and Open Graph tags", () => {
+  const html = fs.readFileSync(path.resolve("index.html"), "utf8");
+  const block = html.match(
+    /<script type="application\/ld\+json">([\s\S]*?)<\/script>/,
+  );
+  assert.ok(block, "JSON-LD script missing");
+  assert.deepEqual(JSON.parse(block[1]), homepageJsonLd());
+  for (const prop of ["og:type", "og:title", "og:description", "og:url", "og:image"]) {
+    assert.match(html, new RegExp(`<meta property="${prop}" content="[^"]+"`), prop);
+  }
+  assert.match(
+    html,
+    /<meta property="og:image" content="https:\/\/concorde\.supersoniks\.org\/img\/og-concorde\.jpg"/,
+  );
+  assert.ok(fs.existsSync(path.resolve("public/img/og-concorde.jpg")));
+  assert.match(html, /<meta name="twitter:card" content="summary_large_image"/);
+  assert.match(html, /href="\/about"/);
+  assert.match(html, /href="\/privacy"/);
+});
+
+test("site page Markdown is read from site-pages/", () => {
+  assert.deepEqual(
+    STATIC_PAGES.map((p) => p.slug),
+    ["about", "privacy"],
+  );
+  for (const { slug, markdown } of STATIC_PAGES) {
+    assert.equal(
+      markdown,
+      fs.readFileSync(path.resolve(`site-pages/${slug}.md`), "utf8"),
+    );
+    assert.match(markdown, /^# /);
+  }
+});
+
+test("site pages are SPA shells with their own metadata and inline content", () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), "concorde-pages-"));
+  try {
+    writeAgentSiteArtifacts(dir);
+    for (const { slug } of STATIC_PAGES) {
+      const md = fs.readFileSync(path.join(dir, `${slug}.md`), "utf8");
+      const html = fs.readFileSync(path.join(dir, `${slug}.html`), "utf8");
+      assert.ok(md.length >= 500, `${slug}.md too short (${md.length})`);
+      const section = html.match(
+        /<section id="docs-agent-content"[^>]*>([\s\S]*?)<\/section>/,
+      );
+      assert.ok(section, `${slug}.html page section missing`);
+      assert.ok(stripTags(section[1]).length >= 500, `${slug}.html too short`);
+      assert.match(section[1], /<h1/);
+      assert.doesNotMatch(section[1], /<h1>Concorde by Supersoniks<\/h1>/);
+      assert.match(html, /<sonic-router>/, "SPA shell expected");
+      const url = `https://concorde\\.supersoniks\\.org/${slug}`;
+      assert.match(html, new RegExp(`<link rel="canonical" href="${url}" />`));
+      assert.match(html, new RegExp(`<meta property="og:url" content="${url}"`));
+      assert.match(html, new RegExp(`href="/${slug}\\.md"`));
+      assert.equal((html.match(/<title>/g) || []).length, 1);
+      const ld = JSON.parse(
+        html.match(/<script type="application\/ld\+json">([\s\S]*?)<\/script>/)[1],
+      );
+      assert.equal(ld.url, `https://concorde.supersoniks.org/${slug}`);
+      assert.equal(ld.publisher.address.addressLocality, "Tours");
+    }
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("sitemap and homepage Markdown link the site pages", () => {
+  const xml = generateSitemap([], []);
+  const md = generateHomepageMarkdown();
+  for (const slug of ["about", "privacy"]) {
+    assert.match(xml, new RegExp(`<loc>https://concorde\\.supersoniks\\.org/${slug}</loc>`));
+    assert.match(md, new RegExp(`https://concorde\\.supersoniks\\.org/${slug}\\)`));
+  }
+});
+
+test("htaccess serves site pages as HTML or Markdown", () => {
+  const conf = generateHtaccess();
+  assert.match(conf, /\^\(about\|privacy\)\$ \/\$1\.md \[END\]/);
+  assert.match(conf, /\^\(about\|privacy\)\$ \/\$1\.html \[END\]/);
+});

package/site-pages/about.md

@@ -0,0 +1,22 @@
+# About Concorde
+
+Concorde is an open-source web components framework built on [Lit](https://lit.dev). It is designed, written and maintained by [Supersoniks](https://supersoniks.com/), a company based in Tours, France, which uses it in production.
+
+## Why it exists
+
+Supersoniks works on many stacks: PHP back offices, static pages, React and Vue front ends. Rewriting the same buttons, forms and data lists for each stack was slow and led to inconsistent interfaces. Concorde solves this with standard custom elements (`sonic-*`) that work the same way in any host page, plus a small data layer (DataProvider, decorators) that connects components to each other and to REST APIs without a framework.
+
+## What it includes
+
+- UI components: buttons, inputs, selects, checkboxes, modals, toasts, cards, menus, tooltips and more.
+- Data components: lists, queues, fetch, submit, router, states and server-driven UI from JSON.
+- Lit decorators such as `@get`, `@post`, `@subscribe` and `@bind`.
+- Theming through CSS custom properties, with light and dark modes.
+
+## Licence and distribution
+
+Concorde is published on npm as [`@supersoniks/concorde`](https://www.npmjs.com/package/@supersoniks/concorde) under the MIT licence. This site (https://concorde.supersoniks.org) is its official documentation.
+
+## Publisher
+
+Supersoniks, 22 rue du Docteur Bretonneau, 37000 Tours, France · +33 2 47 68 93 25 · [contact Supersoniks](https://supersoniks.com/un-projet). See also the [privacy notice](/privacy).

package/site-pages/privacy.md

@@ -0,0 +1,32 @@
+# Privacy notice
+
+This notice covers the Concorde documentation site, https://concorde.supersoniks.org, published by [Supersoniks](https://supersoniks.com/), 22 rue du Docteur Bretonneau, 37000 Tours, France.
+
+## What this site does not do
+
+- It has no user accounts, sign-up or login.
+- It sets no cookies and runs no analytics, advertising or tracking scripts.
+- It has no forms that send personal data to Supersoniks.
+
+## What is stored in your browser
+
+- `sonicTheme` in localStorage remembers your light or dark theme choice. It never leaves your browser.
+- A service worker serves the mock API used by live examples (`/docs-mock-api/…`). It runs locally in your browser.
+- Some examples demonstrate features that store values in localStorage (for example dismissed alerts or cached labels). They only run when you open those pages.
+
+## Third-party services
+
+To display pages, your browser loads files from these providers, which receive your IP address and browser details as part of any web request:
+
+- Google Fonts (fonts.googleapis.com, fonts.gstatic.com) for the Schibsted Grotesk font.
+- jsDelivr (cdn.jsdelivr.net) for the search and Markdown libraries.
+- cdn.supersoniks.com for icons.
+- A few live examples call public demo APIs (geo.api.gouv.fr, reqres.in, i.pravatar.cc) when you open them.
+
+## Server logs
+
+Like any web server, the host records technical request data (IP address, URL, date, user agent) to operate and secure the site.
+
+## Your rights
+
+Under the GDPR you can ask for access to, correction or deletion of data about you. Contact Supersoniks through [supersoniks.com/un-projet](https://supersoniks.com/un-projet), by phone at +33 2 47 68 93 25, or by mail at 22 rue du Docteur Bretonneau, 37000 Tours, France. See also the [Supersoniks privacy policy](https://supersoniks.com/politique-de-confidentialite) and [legal notice](https://supersoniks.com/mentions-legales).