@casoon/pages-theme 0.0.0-stage → 0.12.6

package/layouts/Docs.astro

@@ -0,0 +1,286 @@
+---
+import config from 'virtual:casoon-pages/config';
+import type { MarkdownHeading } from 'astro';
+import type { DocsNavGroup } from '../lib/docs';
+import { t } from '../lib/i18n';
+import Base from './Base.astro';
+
+interface Props {
+  id: string;
+  title: string;
+  description?: string;
+  /** Path of the source file relative to the repository root, for the edit link. */
+  sourcePath: string;
+  groups: DocsNavGroup[];
+  headings: MarkdownHeading[];
+}
+
+const { id, title, description, sourcePath, groups, headings } = Astro.props;
+const flat = groups.flatMap((g) => g.items);
+const index = flat.findIndex((item) => item.id === id);
+const prev = index > 0 ? flat[index - 1] : undefined;
+const next = index >= 0 && index < flat.length - 1 ? flat[index + 1] : undefined;
+const group = groups.find((g) => g.items.some((item) => item.id === id));
+const toc = headings.filter((h) => h.depth === 2);
+const s = t(config.lang);
+const editUrl = config.repo
+  ? `https://github.com/${config.repo}/edit/${config.branch}/${sourcePath}`
+  : '';
+---
+
+<Base title={title} description={description}>
+  <div class="docs">
+    <aside class="sidebar">
+      <nav aria-label={s.docsNav}>
+        {
+          groups.map((g) => (
+            <div class="group">
+              <p class="group-title">{g.label}</p>
+              <ul>
+                {g.items.map((item) => (
+                  <li>
+                    <a href={item.href} aria-current={item.id === id ? 'page' : undefined}>
+                      {item.label}
+                    </a>
+                  </li>
+                ))}
+              </ul>
+            </div>
+          ))
+        }
+      </nav>
+    </aside>
+
+    <article class="content">
+      <nav class="crumb" aria-label={s.breadcrumb}>
+        <ol>
+          <li>{s.docs}</li>
+          {group && <li>{group.label}</li>}
+          <li aria-current="page">{title}</li>
+        </ol>
+      </nav>
+      <h1>{title}</h1>
+      {description && <p class="lead">{description}</p>}
+      <div class="cp-prose"><slot /></div>
+
+      {
+        (prev || next) && (
+          <nav class="pager" aria-label={s.pagerDocs}>
+            {prev ? (
+              <a href={prev.href}>
+                <span class="dir">{s.previous}</span>
+                <span class="label">{prev.label}</span>
+              </a>
+            ) : (
+              <span />
+            )}
+            {next && (
+              <a class="next" href={next.href}>
+                <span class="dir">{s.next}</span>
+                <span class="label">{next.label}</span>
+              </a>
+            )}
+          </nav>
+        )
+      }
+      <p class="meta">
+        {editUrl && <a href={editUrl}>{s.editPage}</a>}
+        {config.version && <span>{editUrl && ' · '}{s.docsFor(config.version)}</span>}
+      </p>
+    </article>
+
+    {
+      toc.length > 0 && (
+        <aside class="toc">
+          <nav aria-labelledby="toc-title">
+            <p class="group-title" id="toc-title">
+              {s.onThisPage}
+            </p>
+            <ul>
+              {toc.map((h) => (
+                <li>
+                  <a href={`#${h.slug}`}>{h.text}</a>
+                </li>
+              ))}
+            </ul>
+          </nav>
+        </aside>
+      )
+    }
+  </div>
+</Base>
+
+<style>
+  .docs {
+    display: flex;
+    align-items: flex-start;
+    gap: 48px;
+    max-width: 1320px;
+    margin: 0 auto;
+    padding: 0 24px;
+  }
+  /* The sidebar scrolls with the page: as a sticky box with its own scroll area, a long menu
+     was cut off at the footer on short pages. The table of contents stays in view. */
+  .toc {
+    position: sticky;
+    top: var(--header-h);
+    max-height: calc(100vh - var(--header-h));
+    overflow: auto;
+  }
+  .sidebar {
+    flex: 0 0 220px;
+    padding: 40px 0 60px;
+  }
+  .toc {
+    flex: 0 0 180px;
+    padding: 40px 0;
+    font-size: 13.5px;
+  }
+  .content {
+    flex: 1 1 auto;
+    min-width: 0;
+    max-width: 760px;
+    padding: 40px 0 96px;
+  }
+  .group {
+    margin-bottom: 26px;
+  }
+  .group-title {
+    margin: 0 0 10px;
+    color: var(--muted);
+    font-family: var(--font-mono);
+    font-size: 12px;
+    letter-spacing: 0.09em;
+    text-transform: uppercase;
+  }
+  ul {
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  .sidebar li + li {
+    margin-top: 1px;
+  }
+  .sidebar a {
+    display: block;
+    padding: 6px 10px;
+    border-left: 2px solid transparent;
+    border-radius: 0 7px 7px 0;
+    color: var(--muted);
+    font-size: 14px;
+  }
+  .sidebar a:hover {
+    color: var(--heading);
+  }
+  .sidebar a[aria-current='page'] {
+    border-left-color: var(--accent);
+    background: var(--accent-soft);
+    color: var(--heading);
+  }
+  .toc ul {
+    display: flex;
+    flex-direction: column;
+    gap: 7px;
+    padding-left: 14px;
+    border-left: 1px solid var(--border);
+  }
+  .toc a {
+    color: var(--muted);
+  }
+  .toc a:hover {
+    color: var(--heading);
+  }
+  .crumb ol {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 8px;
+    margin: 0 0 14px;
+    padding: 0;
+    list-style: none;
+    color: var(--muted);
+    font-size: 13px;
+  }
+  .crumb li + li::before {
+    content: '/';
+    margin-right: 8px;
+  }
+  .crumb [aria-current] {
+    color: var(--text);
+  }
+  h1 {
+    margin: 0 0 12px;
+    color: var(--heading);
+    font-size: clamp(28px, 3.4vw, 38px);
+    font-weight: 600;
+    letter-spacing: -0.025em;
+    line-height: 1.15;
+  }
+  .lead {
+    margin: 0 0 36px;
+    font-size: 17.5px;
+  }
+  .pager {
+    display: grid;
+    grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
+    gap: 14px;
+    margin-top: 56px;
+  }
+  .pager a {
+    display: block;
+    padding: 14px 18px;
+    border: 1px solid var(--border);
+    border-radius: 12px;
+    background: var(--surface);
+  }
+  .pager a:hover {
+    border-color: var(--border-strong);
+  }
+  .pager .next {
+    text-align: right;
+  }
+  .dir {
+    display: block;
+    margin-bottom: 3px;
+    color: var(--muted);
+    font-size: 12px;
+  }
+  .label {
+    color: var(--heading);
+    font-size: 15px;
+    font-weight: 500;
+  }
+  .meta {
+    margin: 28px 0 0;
+    color: var(--muted);
+    font-size: 13.5px;
+  }
+  /* Next to muted text the accent alone is not distinguishable enough (WCAG 1.4.1). */
+  .meta a {
+    text-decoration: underline;
+    text-underline-offset: 2px;
+    text-decoration-thickness: 1px;
+  }
+  @media (max-width: 1100px) {
+    .toc {
+      display: none;
+    }
+  }
+  @media (max-width: 800px) {
+    .docs {
+      flex-direction: column;
+      align-items: stretch;
+      gap: 0;
+    }
+    .sidebar {
+      flex: none;
+      width: 100%;
+      padding: 24px 0 0;
+      border-bottom: 1px solid var(--border);
+    }
+    .sidebar nav {
+      display: grid;
+      grid-template-columns: repeat(auto-fill, minmax(160px, 1fr));
+      gap: 0 24px;
+    }
+  }
+</style>

package/lib/ansi.ts

@@ -0,0 +1,168 @@
+/**
+ * Minimal ANSI → HTML conversion for the Terminal component: SGR colours
+ * (16-colour palette as classes, 256-colour and 24-bit colour as inline
+ * styles), bold, dim, italic, underline and carriage-return overwrites. Other
+ * escape sequences are dropped. Projects with their own renderer (e.g.
+ * runemark) pass its HTML to <Terminal> instead.
+ */
+
+interface Style {
+  fg: number | null;
+  /** A 256-colour or 24-bit foreground, as a CSS colour; wins over `fg`. */
+  fgColor: string | null;
+  /** A 256-colour or 24-bit background, as a CSS colour. */
+  bgColor: string | null;
+  bold: boolean;
+  dim: boolean;
+  italic: boolean;
+  underline: boolean;
+}
+
+interface Cell {
+  ch: string;
+  cls: string;
+  css: string;
+}
+
+// biome-ignore lint/suspicious/noControlCharactersInRegex: matching ANSI control sequences is the point
+const TOKEN = /\x1b\[([0-9;]*)([A-Za-z])|\x1b\][^\x07]*(?:\x07|\x1b\\)|\r|[^\x1b\r]+/g;
+
+const plain = (): Style => ({
+  fg: null,
+  fgColor: null,
+  bgColor: null,
+  bold: false,
+  dim: false,
+  italic: false,
+  underline: false,
+});
+
+const hex = (r: number, g: number, b: number) =>
+  `#${[r, g, b].map((v) => Math.max(0, Math.min(255, v)).toString(16).padStart(2, '0')).join('')}`;
+
+/** The xterm 256-colour cube and grey ramp; 0–15 are the theme's palette. */
+function color256(index: number): string | number {
+  if (index < 16) return index;
+  if (index < 232) {
+    const i = index - 16;
+    const level = (n: number) => (n === 0 ? 0 : 55 + n * 40);
+    return hex(level(Math.floor(i / 36)), level(Math.floor(i / 6) % 6), level(i % 6));
+  }
+  const grey = 8 + (index - 232) * 10;
+  return hex(grey, grey, grey);
+}
+
+/**
+ * `38;5;n` / `38;2;r;g;b` (and 48 for the background) starting at `codes[i]`.
+ * Returns how many codes it consumed after the 38/48 itself.
+ */
+function extendedColour(style: Style, codes: number[], i: number): number {
+  const background = codes[i] === 48;
+  let value: string | number | null = null;
+  let used = 0;
+  if (codes[i + 1] === 5) {
+    value = color256(codes[i + 2] ?? 0);
+    used = 2;
+  } else if (codes[i + 1] === 2) {
+    value = hex(codes[i + 2] ?? 0, codes[i + 3] ?? 0, codes[i + 4] ?? 0);
+    used = 4;
+  }
+  if (value === null) return used;
+  if (background) {
+    // Palette backgrounds (40–47) are not rendered either; keep the two consistent.
+    style.bgColor = typeof value === 'string' ? value : null;
+  } else if (typeof value === 'number') {
+    paletteForeground(style, value);
+  } else {
+    style.fgColor = value;
+  }
+  return used;
+}
+
+/** A palette foreground (or none) replaces any 256/24-bit one. */
+function paletteForeground(style: Style, index: number | null): void {
+  style.fg = index;
+  style.fgColor = null;
+}
+
+function applySgr(style: Style, params: string): void {
+  const codes = params === '' ? [0] : params.split(';').map(Number);
+  for (let i = 0; i < codes.length; i++) {
+    const c = codes[i];
+    if (c === 0) Object.assign(style, plain());
+    else if (c === 1) style.bold = true;
+    else if (c === 2) style.dim = true;
+    else if (c === 3) style.italic = true;
+    else if (c === 4) style.underline = true;
+    else if (c === 22) style.bold = style.dim = false;
+    else if (c === 23) style.italic = false;
+    else if (c === 24) style.underline = false;
+    else if (c >= 30 && c <= 37) paletteForeground(style, c - 30);
+    else if (c >= 90 && c <= 97) paletteForeground(style, c - 90 + 8);
+    else if (c === 39) paletteForeground(style, null);
+    else if (c === 49) style.bgColor = null;
+    else if (c === 38 || c === 48) i += extendedColour(style, codes, i);
+  }
+}
+
+function className(style: Style): string {
+  const cls: string[] = [];
+  if (style.bold) cls.push('ansi-bold');
+  if (style.dim) cls.push('ansi-dim');
+  if (style.italic) cls.push('ansi-italic');
+  if (style.underline) cls.push('ansi-underline');
+  if (style.fg !== null && style.fgColor === null) cls.push(`ansi-fg-${style.fg}`);
+  return cls.join(' ');
+}
+
+function inlineStyle(style: Style): string {
+  const css: string[] = [];
+  if (style.fgColor !== null) css.push(`color:${style.fgColor}`);
+  if (style.bgColor !== null) css.push(`background-color:${style.bgColor}`);
+  return css.join(';');
+}
+
+const escapeHtml = (s: string) =>
+  s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+function renderLine(cells: Cell[]): string {
+  let html = '';
+  let i = 0;
+  while (i < cells.length) {
+    const { cls, css } = cells[i];
+    let text = '';
+    while (i < cells.length && cells[i].cls === cls && cells[i].css === css) text += cells[i++].ch;
+    const attrs = (cls ? ` class="${cls}"` : '') + (css ? ` style="${css}"` : '');
+    html += attrs ? `<span${attrs}>${escapeHtml(text)}</span>` : escapeHtml(text);
+  }
+  return html;
+}
+
+export function ansiToHtml(input: string): string {
+  const style = plain();
+  return input
+    .replace(/\r\n/g, '\n')
+    .replace(/\n$/, '')
+    .split('\n')
+    .map((line) => {
+      const cells: Cell[] = [];
+      let col = 0;
+      for (const [token, params, command] of line.matchAll(TOKEN)) {
+        if (token === '\r') col = 0;
+        else if (command === 'm') applySgr(style, params);
+        else if (token[0] !== '\x1b') {
+          const cls = className(style);
+          const css = inlineStyle(style);
+          for (const ch of token) cells[col++] = { ch, cls, css };
+        }
+      }
+      return renderLine(cells);
+    })
+    .join('\n');
+}
+
+/** Show escape sequences literally, for displaying ANSI source files. */
+export function escapeAnsi(input: string): string {
+  // biome-ignore lint/suspicious/noControlCharactersInRegex: ESC is replaced by its literal notation
+  return input.replace(/\x1b/g, '\\x1b').replace(/\r/g, '\\r').replace(/\n$/, '');
+}

package/lib/changelog.ts

@@ -0,0 +1,85 @@
+/**
+ * Parses a Keep-a-Changelog style CHANGELOG.md:
+ *
+ *   ## [0.4.0] - 2026-02-11
+ *   ### Added
+ *   - Item with `code` and [links](https://…)
+ */
+
+export interface Change {
+  kind: string;
+  html: string;
+}
+
+export interface Release {
+  version: string;
+  date: string | null;
+  changes: Change[];
+}
+
+const RELEASE = /^##\s+\[?([^\]\s]+)\]?(?:\s*[-–—]\s*(\S+))?/;
+const SECTION = /^###\s+(.+)/;
+const ITEM = /^\s*[-*]\s+(.*)/;
+
+const escapeHtml = (s: string) =>
+  s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+
+/** Inline Markdown subset: `code`, **bold**, [text](url). */
+export function inlineMarkdown(md: string): string {
+  return md
+    .split('`')
+    .map((part, i) =>
+      i % 2 === 1
+        ? `<code>${escapeHtml(part)}</code>`
+        : escapeHtml(part)
+            .replace(/\*\*(.+?)\*\*/g, '<strong>$1</strong>')
+            .replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, '<a href="$2">$1</a>')
+    )
+    .join('');
+}
+
+export function parseChangelog(md: string): Release[] {
+  const releases: Release[] = [];
+  let kind = 'changed';
+  let item: string | null = null;
+
+  const flush = () => {
+    if (item !== null && releases.length > 0) {
+      releases[releases.length - 1].changes.push({ kind, html: inlineMarkdown(item.trim()) });
+    }
+    item = null;
+  };
+
+  for (const line of md.split('\n')) {
+    const release = RELEASE.exec(line);
+    const section = SECTION.exec(line);
+    const listItem = ITEM.exec(line);
+    if (release) {
+      flush();
+      releases.push({ version: release[1], date: release[2] ?? null, changes: [] });
+    } else if (section) {
+      flush();
+      kind = section[1].trim().toLowerCase();
+    } else if (listItem) {
+      flush();
+      item = listItem[1];
+    } else if (item !== null && line.trim() !== '') {
+      item += ` ${line.trim()}`;
+    } else {
+      flush();
+    }
+  }
+  flush();
+  return releases.filter((r) => r.changes.length > 0);
+}
+
+export function formatDate(iso: string, locale = 'en-GB'): string {
+  const date = new Date(`${iso}T00:00:00Z`);
+  if (Number.isNaN(date.getTime())) return iso;
+  return date.toLocaleDateString(locale, {
+    day: 'numeric',
+    month: 'long',
+    year: 'numeric',
+    timeZone: 'UTC',
+  });
+}

package/lib/docs.ts

@@ -0,0 +1,54 @@
+import type { CollectionEntry } from 'astro:content';
+import { url } from './url';
+
+export interface DocsNavItem {
+  id: string;
+  label: string;
+  href: string;
+}
+
+export interface DocsNavGroup {
+  label: string;
+  items: DocsNavItem[];
+}
+
+const humanize = (dir: string) => dir.replace(/[-_]/g, ' ').replace(/^\w/, (c) => c.toUpperCase());
+
+/** The docs page at docs/index.md is served at /docs/. */
+export const docSlug = (id: string) => (id === 'index' ? undefined : id);
+
+export const docHref = (id: string) => url(id === 'index' ? 'docs/' : `docs/${id}/`);
+
+/**
+ * Sidebar groups come from the folders in docs/. Group order and labels follow
+ * the `docsGroups` option; unlisted folders follow alphabetically. Root-level
+ * pages join the first group.
+ */
+export function buildDocsNav(
+  entries: CollectionEntry<'docs'>[],
+  groups: Record<string, string>
+): DocsNavGroup[] {
+  const configured = Object.keys(groups);
+  const byGroup = new Map<string, CollectionEntry<'docs'>[]>();
+
+  for (const entry of entries) {
+    const dir = entry.id.includes('/') ? entry.id.split('/')[0] : (configured[0] ?? '');
+    byGroup.set(dir, [...(byGroup.get(dir) ?? []), entry]);
+  }
+
+  const order = [
+    ...configured.filter((dir) => byGroup.has(dir)),
+    ...[...byGroup.keys()].filter((dir) => !configured.includes(dir)).sort(),
+  ];
+
+  return order.map((dir) => ({
+    label: groups[dir] ?? humanize(dir),
+    items: (byGroup.get(dir) ?? [])
+      .sort((a, b) => a.data.order - b.data.order || a.data.title.localeCompare(b.data.title))
+      .map((entry) => ({
+        id: entry.id,
+        label: entry.data.sidebarLabel ?? entry.data.title,
+        href: docHref(entry.id),
+      })),
+  }));
+}