@casoon/pages-theme 0.0.0-stage → 0.12.8

package/lib/i18n.ts

@@ -0,0 +1,136 @@
+/** UI strings the theme emits itself. Project-supplied props and content stay untranslated. */
+
+export type Lang = 'en' | 'de';
+
+const en = {
+  dateLocale: 'en-GB',
+  skipLink: 'Skip to content',
+  mainNav: 'Main',
+  docs: 'Docs',
+  showcase: 'Showcase',
+  changelog: 'Changelog',
+  darkTheme: 'Dark theme',
+  copy: 'Copy',
+  copied: 'Copied',
+  footerProject: 'Project',
+  documentation: 'Documentation',
+  footerPackages: 'Packages',
+  website: (name: string) => `${name} website`,
+  catalogEntry: (name: string) => `${name} on casoon.dev`,
+  allProjects: 'All open-source projects by CASOON',
+  footerBy: 'A CASOON project',
+  imprint: 'Imprint',
+  privacyPolicy: 'Privacy Policy',
+  license: (id: string) => `${id} License`,
+  docsNav: 'Documentation',
+  breadcrumb: 'Breadcrumb',
+  pagerDocs: 'Previous and next page',
+  pagerShowcase: 'Previous and next example',
+  previous: 'Previous',
+  next: 'Next',
+  editPage: 'Edit this page on GitHub',
+  docsFor: (version: string) => `Docs for v${version}`,
+  onThisPage: 'On this page',
+  heroEyebrow: 'CASOON Open Source',
+  installLabel: 'Package manager',
+  callout: { note: 'Note', tip: 'Tip', caution: 'Caution', deprecated: 'Deprecated' },
+  buildOutputHeading: 'Generated at build time',
+  allExamples: 'All examples',
+  featuresHeading: 'What it does',
+  overview: 'Overview',
+  quickstartTitle: 'Quickstart',
+  quickstartLead:
+    'From install to a first result. The full walkthrough lives in the documentation.',
+  readDocs: 'Read the documentation',
+  parameters: 'Parameters',
+  detail: 'Detail',
+  input: 'Input',
+  output: 'Output',
+  keyFacts: 'Key facts',
+  themeDependent: 'theme-dependent',
+  tabsLabel: 'Variants',
+  filesLabel: 'Generated files',
+  notFoundTitle: 'Page not found',
+  notFoundHeading: 'This page does not exist.',
+  notFoundBody: 'The address may be outdated, or the page moved when the docs were restructured.',
+  backToStart: 'Back to the start page',
+  openDocs: 'Open the documentation',
+  changelogDescription: (name: string) => `Release history of ${name}.`,
+  changelogLeadBefore: 'Generated from',
+  changelogLeadAfter: 'in the project repository. Never maintained twice.',
+  showcaseDescription: (name: string) => `Real input and output of ${name}.`,
+  showcaseLead: (name: string) =>
+    `Each example shows real output produced by ${name} itself, from files in the project repository. Input on the left, output on the right.`,
+  faqHeading: 'Frequently asked questions',
+  newIn: (version: string) => `New in v${version}`,
+};
+
+export type Strings = typeof en;
+
+const de: Strings = {
+  dateLocale: 'de-DE',
+  skipLink: 'Zum Inhalt springen',
+  mainNav: 'Hauptnavigation',
+  docs: 'Doku',
+  showcase: 'Beispiele',
+  changelog: 'Änderungen',
+  darkTheme: 'Dunkles Design',
+  copy: 'Kopieren',
+  copied: 'Kopiert',
+  footerProject: 'Projekt',
+  documentation: 'Dokumentation',
+  footerPackages: 'Pakete',
+  website: (name) => `Website von ${name}`,
+  catalogEntry: (name) => `${name} auf casoon.dev`,
+  allProjects: 'Alle Open-Source-Projekte von CASOON',
+  footerBy: 'Ein Projekt von CASOON',
+  imprint: 'Impressum',
+  privacyPolicy: 'Datenschutz',
+  license: (id) => `${id}-Lizenz`,
+  docsNav: 'Dokumentation',
+  breadcrumb: 'Navigationspfad',
+  pagerDocs: 'Vorherige und nächste Seite',
+  pagerShowcase: 'Vorheriges und nächstes Beispiel',
+  previous: 'Zurück',
+  next: 'Weiter',
+  editPage: 'Diese Seite auf GitHub bearbeiten',
+  docsFor: (version) => `Doku für v${version}`,
+  onThisPage: 'Auf dieser Seite',
+  heroEyebrow: 'CASOON Open Source',
+  installLabel: 'Paketmanager',
+  callout: { note: 'Hinweis', tip: 'Tipp', caution: 'Achtung', deprecated: 'Veraltet' },
+  buildOutputHeading: 'Beim Build erzeugt',
+  allExamples: 'Alle Beispiele',
+  featuresHeading: 'Was es kann',
+  overview: 'Überblick',
+  quickstartTitle: 'Schnellstart',
+  quickstartLead:
+    'Von der Installation zum ersten Ergebnis. Die ausführliche Anleitung steht in der Dokumentation.',
+  readDocs: 'Zur Dokumentation',
+  parameters: 'Parameter',
+  detail: 'Details',
+  input: 'Eingabe',
+  output: 'Ausgabe',
+  keyFacts: 'Eckdaten',
+  themeDependent: 'je nach Farbschema',
+  tabsLabel: 'Varianten',
+  filesLabel: 'Erzeugte Dateien',
+  notFoundTitle: 'Seite nicht gefunden',
+  notFoundHeading: 'Diese Seite gibt es nicht.',
+  notFoundBody:
+    'Die Adresse ist vielleicht veraltet, oder die Seite ist beim Umbau der Doku umgezogen.',
+  backToStart: 'Zur Startseite',
+  openDocs: 'Zur Dokumentation',
+  changelogDescription: (name) => `Versionsgeschichte von ${name}.`,
+  changelogLeadBefore: 'Erzeugt aus',
+  changelogLeadAfter: 'im Projekt-Repository. Wird nie doppelt gepflegt.',
+  showcaseDescription: (name) => `Echte Ein- und Ausgaben von ${name}.`,
+  showcaseLead: (name) =>
+    `Jedes Beispiel zeigt echte Ausgabe, die ${name} selbst erzeugt hat, aus Dateien im Projekt-Repository. Links die Eingabe, rechts die Ausgabe.`,
+  faqHeading: 'Häufige Fragen',
+  newIn: (version) => `Neu in v${version}`,
+};
+
+export const strings: Record<Lang, Strings> = { en, de };
+
+export const t = (lang: Lang): Strings => strings[lang];

package/lib/og.ts

@@ -0,0 +1,91 @@
+import { readFile } from 'node:fs/promises';
+import { fileURLToPath } from 'node:url';
+import sharp from 'sharp';
+import type { ResolvedConfig } from '../index';
+
+/** Dark theme tokens (styles/tokens.css): the card looks like the site at night. */
+const BG = '#101010';
+const HEADING = '#f4f4f4';
+const TEXT = '#c3c7c7';
+const MUTED = '#8c9090';
+const ACCENT = 'rgb(58 206 222)';
+
+const WIDTH = 1200;
+const HEIGHT = 630;
+const X = 88;
+
+const asset = (path: string) => fileURLToPath(new URL(path, import.meta.url));
+const SANS = asset('../fonts/onest-latin-wght-normal.woff2');
+const MONO = asset('../fonts/jetbrains-mono-latin-400-normal.woff2');
+
+const escapeMarkup = (text: string) => text.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+
+/** Cut at a word boundary so the text keeps to about three lines on the card. */
+const clip = (text: string, max: number) =>
+  text.length <= max ? text : `${text.slice(0, text.lastIndexOf(' ', max - 1))} …`;
+
+/** One text block via Pango, in a font file of the theme: no system fonts involved. */
+const text = (markup: string, font: string, fontfile: string, width: number) =>
+  sharp({ text: { text: markup, font, fontfile, width, wrap: 'word', rgba: true } })
+    .png()
+    .toBuffer();
+
+/** Largest name size whose single line fits the card, so a long name shrinks instead of wrapping. */
+async function nameBlock(name: string, width: number): Promise<Buffer> {
+  const markup = `<span foreground="${HEADING}" weight="600">${escapeMarkup(name)}</span>`;
+  const sizes = [96, 80, 68, 58, 50];
+  for (const size of sizes) {
+    const block = await text(markup, `Onest ${size}`, SANS, width * 4);
+    if (((await sharp(block).metadata()).width ?? 0) <= width) return block;
+  }
+  return text(markup, `Onest ${sizes[sizes.length - 1]}`, SANS, width);
+}
+
+/** The project's 1200×630 Open Graph image: name, tagline and description, address. */
+export async function renderOgImage(config: ResolvedConfig, site: URL): Promise<Buffer> {
+  const accent = config.accent?.dark ?? ACCENT;
+  const background = Buffer.from(
+    `<svg xmlns="http://www.w3.org/2000/svg" width="${WIDTH}" height="${HEIGHT}">` +
+      `<rect width="100%" height="100%" fill="${BG}"/>` +
+      `<rect width="12" height="100%" fill="${accent}"/>` +
+      `<rect x="${X}" y="${HEIGHT - 128}" width="${WIDTH - 2 * X}" height="1" fill="${MUTED}" opacity="0.4"/>` +
+      '</svg>'
+  );
+  const logo = await sharp(await readFile(asset('../assets/casoon-logo-dark.svg')), {
+    density: 300,
+  })
+    .resize({ width: 176 })
+    .png()
+    .toBuffer();
+  const address = `${site.host}${site.pathname}`.replace(/\/$/, '');
+  const span = (color: string, content: string) =>
+    `<span foreground="${color}">${escapeMarkup(content)}</span>`;
+
+  const [eyebrow, name, tagline, description, host] = await Promise.all([
+    text(span(MUTED, 'CASOON Open Source'), 'JetBrains Mono 26', MONO, 1000),
+    nameBlock(config.name, WIDTH - 2 * X),
+    config.tagline && text(span(HEADING, config.tagline), 'Onest 44', SANS, WIDTH - 2 * X),
+    text(
+      span(TEXT, clip(config.description, config.tagline ? 150 : 140)),
+      config.tagline ? 'Onest 30' : 'Onest 40',
+      SANS,
+      WIDTH - 2 * X
+    ),
+    text(span(MUTED, address), 'JetBrains Mono 24', MONO, 640),
+  ]);
+  const size = async (image: Buffer) => sharp(image).metadata();
+  const nameBottom = 128 + ((await size(name)).height ?? 0) + 16;
+  const taglineHeight = tagline ? ((await size(tagline)).height ?? 0) + 24 : 0;
+
+  return sharp(background)
+    .composite([
+      { input: eyebrow, left: X, top: 76 },
+      { input: name, left: X, top: 128 },
+      ...(tagline ? [{ input: tagline, left: X, top: nameBottom }] : []),
+      { input: description, left: X, top: nameBottom + taglineHeight },
+      { input: logo, left: X, top: HEIGHT - 92 },
+      { input: host, left: WIDTH - X - ((await size(host)).width ?? 0), top: HEIGHT - 80 },
+    ])
+    .png()
+    .toBuffer();
+}

package/lib/showcase.ts

@@ -0,0 +1,48 @@
+export interface ShowcaseExample {
+  /** URL segment of the detail page. */
+  slug: string;
+  title: string;
+  description?: string;
+  /** Source file in the project repository, e.g. "examples/report.ansi". */
+  file: string;
+  tags?: string[];
+  /** What goes in: source, fixture, configuration. */
+  input: { code: string; lang?: string };
+  /**
+   * What comes out: HTML produced at build time by the project's own package.
+   * "terminal" renders on the dark terminal surface, "panel" on the page surface (SVG, tables …).
+   */
+  output: { html: string; kind?: 'terminal' | 'panel' };
+  /**
+   * Heading the example is listed under on the overview. Examples sharing a group appear together,
+   * groups in the order of their first example, with a jump list above them.
+   */
+  group?: string;
+  /**
+   * A small preview for the overview, typically a lazily loaded image. With it the overview shows
+   * a compact card (title, description, preview, link); input and output stay on the detail page.
+   * Suits showcases with many examples.
+   */
+  preview?: { html: string };
+}
+
+const escapeHtml = (text: string) =>
+  text.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+/**
+ * A description as HTML: text escaped, `backtick spans` as `<code>`, no other markup.
+ * Text without backticks comes out as the escaped text alone.
+ */
+export function descriptionHtml(text: string): string {
+  return text
+    .split(/(`[^`]+`)/)
+    .map((part, i) =>
+      i % 2 === 1 ? `<code>${escapeHtml(part.slice(1, -1))}</code>` : escapeHtml(part)
+    )
+    .join('');
+}
+
+/** A description as plain text (meta description and other text-only places): backticks of code spans removed. */
+export function descriptionText(text: string): string {
+  return text.replace(/`([^`]+)`/g, '$1');
+}

package/lib/url.ts

@@ -0,0 +1,16 @@
+import type { Lang } from './i18n';
+
+const base = import.meta.env.BASE_URL.replace(/\/?$/, '/');
+
+/** Prefix a site-internal path with the Pages base path ("/<repo>/"). */
+export function url(path = ''): string {
+  return base + path.replace(/^\//, '');
+}
+
+/** casoon.de, canonical host. */
+export const CASOON_URL = 'https://www.casoon.de/';
+
+/** The project catalog on casoon.dev (canonical host), or one project's entry in it. */
+export function catalogUrl(lang: Lang, slug = ''): string {
+  return `https://casoon.dev/${lang === 'en' ? 'en/' : ''}${slug && `#projekt-${slug}`}`;
+}

package/lib/version.ts

@@ -0,0 +1,50 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/**
+ * The project's current release, read from the manifest next to site/ so it is never
+ * maintained twice. npm projects keep it in package.json, Rust projects in Cargo.toml
+ * (also as `[workspace.package]`, which a crate inherits with `version.workspace = true`).
+ *
+ * A wrong number on the page is worse than none: anything this cannot read with certainty
+ * yields '', and the project passes `version` itself.
+ */
+export function projectVersion(repoRoot: string): string {
+  return fromPackageJson(repoRoot) || fromCargoToml(repoRoot) || '';
+}
+
+function read(path: string): string | null {
+  try {
+    return readFileSync(path, 'utf8');
+  } catch {
+    return null;
+  }
+}
+
+function fromPackageJson(repoRoot: string): string {
+  const raw = read(join(repoRoot, 'package.json'));
+  if (raw === null) return '';
+  try {
+    const { version } = JSON.parse(raw) as { version?: unknown };
+    return typeof version === 'string' ? version : '';
+  } catch {
+    return '';
+  }
+}
+
+function fromCargoToml(repoRoot: string): string {
+  const raw = read(join(repoRoot, 'Cargo.toml'));
+  if (raw === null) return '';
+  return section(raw, 'package') || section(raw, 'workspace.package');
+}
+
+/** First `version = "…"` inside [<name>], stopping at the next table header. */
+function section(toml: string, name: string): string {
+  const start = toml.search(new RegExp(`^\\[${name.replaceAll('.', '\\.')}\\]\\s*$`, 'm'));
+  if (start === -1) return '';
+  const rest = toml.slice(start);
+  const next = rest.indexOf('\n[', 1);
+  const body = next === -1 ? rest : rest.slice(0, next);
+  const match = body.match(/^version\s*=\s*"([^"]+)"/m);
+  return match ? match[1] : '';
+}

package/package.json

@@ -1,6 +1,73 @@
 {
   "name": "@casoon/pages-theme",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.12.8",
+  "description": "Shared Astro theme for the GitHub Pages sites of CASOON open-source projects",
+  "type": "module",
+  "license": "MIT",
+  "author": "Jörn Seidel <joern.seidel@casoon.de> (https://www.casoon.de)",
+  "homepage": "https://github.com/casoon/pages-theme#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/casoon/pages-theme.git"
+  },
+  "bugs": {
+    "url": "https://github.com/casoon/pages-theme/issues"
+  },
+  "exports": {
+    ".": "./index.ts",
+    "./content": "./content.ts",
+    "./components": "./components/index.ts",
+    "./components/*": "./components/*",
+    "./ansi": "./lib/ansi.ts",
+    "./url": "./lib/url.ts",
+    "./showcase": "./lib/showcase.ts",
+    "./layouts/*": "./layouts/*",
+    "./lib/*": "./lib/*.ts",
+    "./routes/*": "./routes/*",
+    "./styles/*": "./styles/*"
+  },
+  "files": [
+    "index.ts",
+    "content.ts",
+    "virtual.d.ts",
+    "assets",
+    "components",
+    "fonts",
+    "layouts",
+    "lib",
+    "routes",
+    "styles"
+  ],
+  "keywords": [
+    "astro-integration",
+    "astro-theme",
+    "withastro",
+    "casoon"
+  ],
+  "scripts": {
+    "dev": "pnpm --filter starter-site dev",
+    "build": "pnpm --filter starter-site build",
+    "preview": "pnpm --filter starter-site preview",
+    "check": "biome check .",
+    "check:fix": "biome check --write .",
+    "type-check": "pnpm --filter starter-site type-check",
+    "test:accent": "node scripts/test-accent.mjs"
+  },
+  "peerDependencies": {
+    "astro": "^7.3.2"
+  },
+  "dependencies": {
+    "@astrojs/mdx": "^8.1.2",
+    "sharp": "^0.35.5"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "devDependencies": {
+    "@axe-core/playwright": "^4.14.0",
+    "@biomejs/biome": "^2.6.4",
+    "@playwright/test": "^1.64.1"
+  },
+  "packageManager": "pnpm@10.26.0"
+}

package/routes/404.astro

@@ -0,0 +1,49 @@
+---
+import config from 'virtual:casoon-pages/config';
+import Button from '../components/Button.astro';
+import Base from '../layouts/Base.astro';
+import { t } from '../lib/i18n';
+import { url } from '../lib/url';
+
+const s = t(config.lang);
+---
+
+<Base title={s.notFoundTitle}>
+  <div class="page">
+    <p class="code">404</p>
+    <h1>{s.notFoundHeading}</h1>
+    <p>{s.notFoundBody}</p>
+    <div class="actions">
+      <Button href={url()}>{s.backToStart}</Button>
+      <Button href={url('docs/')} variant="secondary">{s.openDocs}</Button>
+    </div>
+  </div>
+</Base>
+
+<style>
+  .page {
+    max-width: 640px;
+    margin: 0 auto;
+    padding: 96px 24px;
+  }
+  .code {
+    margin: 0 0 12px;
+    color: var(--brand);
+    font-family: var(--font-mono);
+    font-size: 14px;
+  }
+  h1 {
+    margin: 0 0 14px;
+    color: var(--heading);
+    font-size: 38px;
+    font-weight: 600;
+    letter-spacing: -0.025em;
+    line-height: 1.15;
+  }
+  .actions {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 12px;
+    margin-top: 28px;
+  }
+</style>

package/routes/changelog.astro

@@ -0,0 +1,129 @@
+---
+import { readFile } from 'node:fs/promises';
+import config from 'virtual:casoon-pages/config';
+import Base from '../layouts/Base.astro';
+import { formatDate, parseChangelog } from '../lib/changelog';
+import { t } from '../lib/i18n';
+
+const s = t(config.lang);
+
+const releases = parseChangelog(await readFile(config.changelog as string, 'utf8'));
+const tone = (kind: string) =>
+  ['breaking', 'removed', 'security'].includes(kind)
+    ? 'brand'
+    : kind === 'fixed'
+      ? 'accent'
+      : 'plain';
+---
+
+<Base title={s.changelog} description={s.changelogDescription(config.name)}>
+  <div class="page">
+    <h1>{s.changelog}</h1>
+    <p class="lead">
+      {s.changelogLeadBefore} <code>CHANGELOG.md</code> {s.changelogLeadAfter}
+    </p>
+    {
+      releases.map((release) => (
+        <section>
+          <div>
+            <h2>{release.version}</h2>
+            {release.date && <p class="date">{formatDate(release.date, s.dateLocale)}</p>}
+          </div>
+          <ul>
+            {release.changes.map((change) => (
+              <li>
+                <span class:list={['kind', tone(change.kind)]}>{change.kind}</span>
+                <span set:html={change.html} />
+              </li>
+            ))}
+          </ul>
+        </section>
+      ))
+    }
+  </div>
+</Base>
+
+<style>
+  .page {
+    max-width: 820px;
+    margin: 0 auto;
+    padding: 56px 24px 96px;
+  }
+  h1 {
+    margin: 0 0 12px;
+    color: var(--heading);
+    font-size: 38px;
+    font-weight: 600;
+    letter-spacing: -0.025em;
+  }
+  .lead {
+    margin: 0 0 44px;
+    font-size: 17.5px;
+  }
+  .lead code,
+  li :global(code) {
+    padding: 1px 6px;
+    border-radius: 5px;
+    background: var(--code-bg);
+    font-size: 0.86em;
+  }
+  li :global(a) {
+    text-decoration: underline;
+    text-underline-offset: 2px;
+    text-decoration-thickness: 1px;
+  }
+  section {
+    display: grid;
+    grid-template-columns: 150px 1fr;
+    gap: 24px;
+    padding: 26px 0;
+    border-top: 1px solid var(--border);
+  }
+  h2 {
+    margin: 0;
+    color: var(--heading);
+    font-family: var(--font-mono);
+    font-size: 15px;
+    font-weight: 500;
+  }
+  .date {
+    margin: 0;
+    color: var(--muted);
+    font-size: 13px;
+  }
+  ul {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  li {
+    display: flex;
+    align-items: baseline;
+    gap: 12px;
+    margin-bottom: 8px;
+    font-size: 14.5px;
+  }
+  .kind {
+    flex-shrink: 0;
+    min-width: 76px;
+    font-family: var(--font-mono);
+    font-size: 12px;
+    letter-spacing: 0.05em;
+    text-transform: uppercase;
+  }
+  .plain {
+    color: var(--heading);
+  }
+  .accent {
+    color: var(--accent);
+  }
+  .brand {
+    color: var(--brand);
+  }
+  @media (max-width: 560px) {
+    section {
+      grid-template-columns: 1fr;
+      gap: 12px;
+    }
+  }
+</style>

package/routes/docs/[...slug].astro

@@ -0,0 +1,39 @@
+---
+import { type CollectionEntry, getCollection, render } from 'astro:content';
+import config from 'virtual:casoon-pages/config';
+import { components as projectComponents } from 'virtual:casoon-pages/mdx-components';
+import * as components from '../../components/index';
+import Docs from '../../layouts/Docs.astro';
+import { buildDocsNav, docSlug } from '../../lib/docs';
+
+export async function getStaticPaths() {
+  const entries = await getCollection('docs');
+  const paths = entries.map((entry) => ({ params: { slug: docSlug(entry.id) }, props: { entry } }));
+  // Without docs/index.md, /docs/ shows the first page of the sidebar.
+  if (entries.length > 0 && !entries.some((entry) => entry.id === 'index')) {
+    const first = buildDocsNav(entries, config.docsGroups)[0].items[0];
+    const entry = entries.find((e) => e.id === first.id) as CollectionEntry<'docs'>;
+    paths.push({ params: { slug: undefined }, props: { entry } });
+  }
+  return paths;
+}
+
+const { entry } = Astro.props;
+const { Content, headings } = await render(entry);
+const groups = buildDocsNav(await getCollection('docs'), config.docsGroups);
+// filePath is relative to site/; the repository root is one level up.
+const sourcePath = (entry.filePath ?? '').replace(/^(\.\.\/)+/, '');
+---
+
+<Docs
+  id={entry.id}
+  title={entry.data.title}
+  description={entry.data.description}
+  sourcePath={sourcePath}
+  groups={groups}
+  headings={headings}
+>
+  {/* docs/ sits outside site/ and cannot import packages; theme components are provided
+      here, and the project's own (option `mdxComponents`) on top of them. */}
+  <Content components={{ ...components, ...projectComponents }} />
+</Docs>