@apisurf/canonui 0.1.1

package/package.json

@@ -0,0 +1,67 @@
+{
+  "name": "@apisurf/canonui",
+  "version": "0.1.1",
+  "description": "canonui — build and preview the documents that canon holds: render one into static HTML, or serve it locally.",
+  "keywords": [
+    "astro",
+    "canon",
+    "cli",
+    "docs",
+    "preview",
+    "static-site",
+    "theme"
+  ],
+  "homepage": "https://github.com/apisurf/canon/tree/main/packages/ui#readme",
+  "bugs": {
+    "url": "https://github.com/apisurf/canon/issues"
+  },
+  "license": "ISC",
+  "author": "Luka Vidakovic (https://github.com/apisurfer)",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/apisurf/canon.git",
+    "directory": "packages/ui"
+  },
+  "bin": {
+    "canonui": "./dist/bin.js"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "theme",
+    "astro.config.mjs",
+    "tsconfig.json"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "dependencies": {
+    "astro": "7.2.0",
+    "better-sqlite3": "11.7.0",
+    "marked": "18.0.9",
+    "mermaid": "11.16.1"
+  },
+  "devDependencies": {
+    "@astrojs/check": "0.9.10",
+    "@types/better-sqlite3": "7.6.12",
+    "@types/node": "22.14.0",
+    "tsup": "8.3.5",
+    "typescript": "5.6.3",
+    "vitest": "4.1.8",
+    "@canon/core": "0.0.0",
+    "@canon/db": "0.0.0"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc -p tsconfig.cli.json --noEmit && astro sync && astro check --minimumSeverity error",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "lint": "oxlint --deny-warnings"
+  }
+}

package/theme/components/Block.astro

@@ -0,0 +1,76 @@
+---
+/**
+ * One content block, drawn according to its type.
+ *
+ * Five types, five renderings, and no fallthrough: an unknown type is drawn as
+ * a visible notice rather than silently skipped. A block that does not appear
+ * in the output looks exactly like a block that was never written, and that is
+ * the wrong thing to be ambiguous about.
+ */
+import type { SnapshotBlock } from "@canon/db";
+import { renderBlock } from "../lib/markdown";
+
+interface Props {
+  block: SnapshotBlock;
+}
+
+const { block } = Astro.props;
+const attrs = block.attrs ?? {};
+const anchor = `b${block.seq}`;
+---
+
+<section class:list={["block", `block-${block.type}`]} id={anchor}>
+  {
+    block.title && (
+      <h2 class="block-title">
+        <a class="anchor" href={`#${anchor}`}>
+          {block.title}
+        </a>
+      </h2>
+    )
+  }
+
+  {
+    block.type === "markdown" && (
+      <div class="prose" set:html={renderBlock(block).html} />
+    )
+  }
+
+  {
+    block.type === "text" && (
+      <div class="prose">
+        {block.content.split(/\n{2,}/).map((paragraph) => (
+          <p>{paragraph}</p>
+        ))}
+      </div>
+    )
+  }
+
+  {block.type === "html" && <div class="prose" set:html={block.content} />}
+
+  {
+    block.type === "img" && (
+      <figure>
+        <img
+          src={block.content}
+          alt={typeof attrs.alt === "string" ? attrs.alt : ""}
+          width={attrs.width as number | string | undefined}
+          height={attrs.height as number | string | undefined}
+          loading="lazy"
+          decoding="async"
+        />
+        {typeof attrs.caption === "string" && <figcaption>{attrs.caption}</figcaption>}
+      </figure>
+    )
+  }
+
+  {block.type === "mermaid" && <pre class="mermaid">{block.content}</pre>}
+
+  {
+    !["markdown", "text", "html", "img", "mermaid"].includes(block.type) && (
+      <p class="block-unknown">
+        Block {block.seq} has type <code>{block.type}</code>, which this theme cannot draw.
+      </p>
+    )
+  }
+</section>

package/theme/components/Blocks.astro

@@ -0,0 +1,26 @@
+---
+/**
+ * A document's blocks, in order, plus whatever they need at the page level.
+ *
+ * The mermaid runtime is the one thing a block cannot pull in for itself: three
+ * diagrams in a document need one initialization, not three.
+ */
+import type { SnapshotBlock } from "@canon/db";
+import Block from "./Block.astro";
+import Mermaid from "./Mermaid.astro";
+
+interface Props {
+  blocks: SnapshotBlock[];
+}
+
+const { blocks } = Astro.props;
+const hasMermaid = blocks.some((block) => block.type === "mermaid");
+---
+
+{blocks.map((block) => <Block block={block} />)}
+{
+  blocks.length === 0 && (
+    <p class="empty">This document has no blocks yet. Add one with <code>canon new block</code>.</p>
+  )
+}
+{hasMermaid && <Mermaid />}

package/theme/components/Copy.astro

@@ -0,0 +1,167 @@
+---
+/**
+ * The control that puts a document on the clipboard as markdown.
+ *
+ * What it copies is fetched rather than embedded, so the page does not carry
+ * the whole document a second time for a button most readers never press. The
+ * cost is a request on first click.
+ *
+ * Both labels ship in the markup and CSS picks the one that matches the state,
+ * the way the wide toggle does, so the button never reads wrongly between paint
+ * and hydration.
+ */
+interface Props {
+  /** The .md the button copies. */
+  href: string;
+  /** What it copies, for the resting label — "document". */
+  what: string;
+}
+
+const { href, what } = Astro.props;
+---
+
+<button
+  type="button"
+  class="copy"
+  data-copy={href}
+  data-state="idle"
+  aria-label={`Copy this ${what} as markdown`}
+>
+  <svg
+    class="copy-icon copy-icon-idle"
+    viewBox="0 0 16 16"
+    width="12"
+    height="12"
+    aria-hidden="true"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="1.6"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  >
+    <rect x="5.5" y="5.5" width="8" height="8" rx="1.5"></rect>
+    <path d="M10.5 2.5h-8v8"></path>
+  </svg>
+  <svg
+    class="copy-icon copy-icon-done"
+    viewBox="0 0 16 16"
+    width="12"
+    height="12"
+    aria-hidden="true"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="1.8"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  >
+    <path d="M3 8.5l3.5 3.5L13 5"></path>
+  </svg>
+  {/* Announced rather than only drawn: the icon swap is the whole feedback. */}
+  <span class="copy-label" aria-live="polite">
+    <span class="copy-text copy-text-idle">Copy {what}</span>
+    <span class="copy-text copy-text-done">Copied</span>
+    <span class="copy-text copy-text-failed">Copy failed</span>
+  </span>
+</button>
+
+<script>
+  /*
+   * Astro bundles this once per page however many buttons are on it, so the
+   * listener is bound by query rather than by the component instance.
+   */
+  const RESET_MS = 1600;
+
+  /*
+   * Fetched once per document per page load. A reader who copies twice is
+   * checking they got it, not asking for a fresh render of a static file.
+   */
+  const cache = new Map<string, Promise<string>>();
+
+  function markdown(url: string): Promise<string> {
+    let pending = cache.get(url);
+    if (!pending) {
+      pending = fetch(url).then((response) => {
+        if (!response.ok) throw new Error(`${url}: ${response.status}`);
+        return response.text();
+      });
+      // A failed fetch must not be the answer to every later click.
+      pending.catch(() => cache.delete(url));
+      cache.set(url, pending);
+    }
+    return pending;
+  }
+
+  /**
+   * The clipboard API needs a secure context, which `canonui serve --host` on a
+   * LAN address is not. The fallback is the old selection trick: deprecated,
+   * and still working everywhere the modern one does not.
+   */
+  function legacyCopy(text: string): boolean {
+    const field = document.createElement("textarea");
+    field.value = text;
+    field.setAttribute("readonly", "");
+    // Off-screen rather than hidden: the selection has to be real to be copied.
+    field.style.cssText = "position:fixed;top:0;left:-9999px;opacity:0";
+    document.body.appendChild(field);
+    field.select();
+    try {
+      return document.execCommand("copy");
+    } catch {
+      return false;
+    } finally {
+      field.remove();
+    }
+  }
+
+  async function copy(url: string): Promise<boolean> {
+    /*
+     * Handing the clipboard the pending fetch rather than awaiting it first is
+     * what keeps this working in Safari, which grants the write only while the
+     * click that asked for it is still the task in hand.
+     */
+    if (typeof ClipboardItem !== "undefined" && navigator.clipboard?.write) {
+      try {
+        const blob = markdown(url).then((text) => new Blob([text], { type: "text/plain" }));
+        await navigator.clipboard.write([new ClipboardItem({ "text/plain": blob })]);
+        return true;
+      } catch {
+        // Older Chrome and Firefox reject a promise here. They take the text.
+      }
+    }
+
+    const text = await markdown(url);
+    try {
+      await navigator.clipboard.writeText(text);
+      return true;
+    } catch {
+      return legacyCopy(text);
+    }
+  }
+
+  for (const button of document.querySelectorAll<HTMLButtonElement>("[data-copy]")) {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const url = button.dataset.copy as string;
+
+    // Intent, a moment before the click. By the time it lands the document is
+    // usually already here, which is the difference between copying instantly
+    // and copying after a round trip.
+    const warm = () => void markdown(url).catch(() => {});
+    button.addEventListener("pointerenter", warm);
+    button.addEventListener("focus", warm);
+
+    button.addEventListener("click", async () => {
+      clearTimeout(timer);
+      let ok = false;
+      try {
+        ok = await copy(url);
+      } catch {
+        ok = false;
+      }
+
+      button.dataset.state = ok ? "done" : "failed";
+      timer = setTimeout(() => {
+        button.dataset.state = "idle";
+      }, RESET_MS);
+    });
+  }
+</script>

package/theme/components/Mermaid.astro

@@ -0,0 +1,31 @@
+---
+/**
+ * Mermaid, rendered in the browser.
+ *
+ * Included only when the document actually holds a mermaid block, so a plain
+ * document never ships the library. The import is bundled by Astro rather than
+ * fetched from a CDN: the output has to work from a file server with no network
+ * behind it.
+ */
+---
+
+<script>
+  import mermaid from "mermaid";
+
+  /* Light, like the rest of the theme, and told the page's ground so the
+     diagram sits on paper rather than on a white card. */
+  mermaid.initialize({
+    startOnLoad: true,
+    securityLevel: "strict",
+    theme: "default",
+    fontFamily: "inherit",
+    themeVariables: {
+      background: "#fbfaf7",
+      primaryColor: "#f2f0ea",
+      primaryTextColor: "#24231f",
+      primaryBorderColor: "#d6d2c6",
+      lineColor: "#8a867d",
+      textColor: "#24231f",
+    },
+  });
+</script>

package/theme/components/Toc.astro

@@ -0,0 +1,75 @@
+---
+/**
+ * What is on this page, in the rail beside it.
+ *
+ * Drawn only when there is something to navigate: a page with two sections is
+ * already visible in one screen, and a contents list for it is furniture. The
+ * highlight follows the reader down the page, which is the whole reason the
+ * rail is worth its column — a list of links they have to match against their
+ * own scroll position is one they stop reading.
+ */
+import type { OutlineEntry } from "../lib/outline";
+
+interface Props {
+  entries: OutlineEntry[];
+}
+
+const { entries } = Astro.props;
+---
+
+{
+  entries.length > 2 && (
+    <nav class="toc" aria-label="On this page">
+      <p class="toc-title">On this page</p>
+      <ul class="toc-list">
+        {entries.map((entry) => (
+          <li class:list={["toc-item", `toc-depth-${entry.depth}`]}>
+            <a href={`#${entry.id}`}>{entry.text}</a>
+          </li>
+        ))}
+      </ul>
+    </nav>
+  )
+}
+
+<script>
+  /*
+   * Mark the heading the reader is at.
+   *
+   * The observer fires on every heading crossing the viewport; the one to mark
+   * is the last one that has crossed the top, which is not what any single
+   * entry's own visibility tells you. So the entries are kept and the whole set
+   * is re-read on each batch.
+   */
+  const links = new Map<string, HTMLAnchorElement>();
+  for (const link of document.querySelectorAll<HTMLAnchorElement>(".toc-list a")) {
+    links.set(decodeURIComponent(link.hash.slice(1)), link);
+  }
+
+  if (links.size > 0) {
+    const headings = [...links.keys()]
+      .map((id) => document.getElementById(id))
+      .filter((el): el is HTMLElement => el !== null);
+
+    let current: HTMLAnchorElement | null = null;
+
+    const mark = () => {
+      // The last heading whose top is above the reading line, or the first.
+      const line = 96;
+      let found = headings[0];
+      for (const heading of headings) {
+        if (heading.getBoundingClientRect().top <= line) found = heading;
+      }
+
+      const link = found ? (links.get(found.id) ?? null) : null;
+      if (link === current) return;
+      current?.removeAttribute("aria-current");
+      link?.setAttribute("aria-current", "true");
+      current = link;
+    };
+
+    const observer = new IntersectionObserver(mark, { rootMargin: "-80px 0px 0px 0px" });
+    for (const heading of headings) observer.observe(heading);
+    mark();
+  }
+</script>

package/theme/components/Wide.astro

@@ -0,0 +1,77 @@
+---
+/**
+ * The control that trades the rail for reading width.
+ *
+ * The measure is right for prose and wrong for the things a page carries
+ * alongside it — a wide table, a diagram, a screenshot. Rather than give each
+ * of those its own escape hatch, the whole page has one mode: the rail steps
+ * aside, the gutters tighten and the content takes the room. The reader turns
+ * it on, and the same control turns it off, from wherever they have scrolled
+ * to — which is why it is pinned to the window rather than left at the top of
+ * the page they have just read past.
+ *
+ * Both labels ship in the markup and CSS picks the one that matches the mode.
+ * The alternative is a script correcting the label after the fact, and the
+ * page would be restored wide while its own button still read "Expand".
+ */
+---
+
+<button type="button" class="wide-toggle" data-wide>
+  <svg
+    class="wide-icon wide-icon-out"
+    viewBox="0 0 16 16"
+    width="12"
+    height="12"
+    aria-hidden="true"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="1.6"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  >
+    <path d="M6 2H2v4M14 6V2h-4M2 10v4h4M10 14h4v-4"></path>
+  </svg>
+  <svg
+    class="wide-icon wide-icon-in"
+    viewBox="0 0 16 16"
+    width="12"
+    height="12"
+    aria-hidden="true"
+    fill="none"
+    stroke="currentColor"
+    stroke-width="1.6"
+    stroke-linecap="round"
+    stroke-linejoin="round"
+  >
+    <path d="M2 6h4V2M14 6h-4V2M2 10h4v4M14 10h-4v4"></path>
+  </svg>
+  <span class="wide-label wide-label-out">Expand</span>
+  <span class="wide-label wide-label-in">Collapse</span>
+</button>
+
+<script>
+  /*
+   * The mode outlives the page. Every link here is a full navigation, so a
+   * reader who widened the page to read a table would land back in the measure
+   * on the next page and have to say so again. The class itself is set by an
+   * inline script in the head — by the time this module runs the page has
+   * already been painted, and restoring the mode from here would show the
+   * narrow layout first.
+   */
+  const KEY = "canon:wide";
+
+  const remember = (wide: boolean) => {
+    try {
+      localStorage.setItem(KEY, wide ? "1" : "0");
+    } catch {
+      // Private browsing, a file:// origin with storage off — the mode still
+      // works for this page, it just does not follow the reader to the next.
+    }
+  };
+
+  for (const button of document.querySelectorAll("[data-wide]")) {
+    button.addEventListener("click", () => {
+      remember(document.documentElement.classList.toggle("wide"));
+    });
+  }
+</script>

package/theme/layouts/Site.astro

@@ -0,0 +1,74 @@
+---
+/**
+ * The default theme: one shell, three slots.
+ *
+ * Everything a different theme would want to replace is a named slot with a
+ * default behind it — `aside`, `footer`, and `head` for anything that belongs
+ * in the document head. A page that passes nothing gets the defaults.
+ *
+ * The shell is two columns: the document, and the rail beside it listing what
+ * is in it. The rail is the column the reader can do without: `Wide` drops it
+ * and lifts the measure, so a document holding a wide table or a diagram can be
+ * read at the width of the window and put back afterwards.
+ */
+import { snapshot, document, isoDate } from "../lib/snapshot";
+import Wide from "../components/Wide.astro";
+import "../styles/theme.css";
+
+interface Props {
+  title: string;
+  description?: string | null;
+}
+
+const { title, description } = Astro.props;
+---
+
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>{title}</title>
+    {description && <meta name="description" content={description} />}
+    <meta name="generator" content="canon" />
+    {/* Before the first paint, so a reader who left the page wide does not
+        watch it start narrow. Inline and blocking for the same reason. */}
+    <script is:inline>
+      try {
+        if (localStorage.getItem("canon:wide") === "1")
+          document.documentElement.classList.add("wide");
+      } catch {}
+    </script>
+    <slot name="head" />
+  </head>
+  <body>
+    <a class="skip" href="#content">Skip to content</a>
+
+    <Wide />
+
+    <div class="shell">
+      <main id="content" class="site-main">
+        <slot />
+
+        <footer class="site-footer">
+          <slot name="footer">
+            <p>
+              Updated{" "}
+              <time datetime={new Date(document.updatedAt).toISOString()}>
+                {isoDate(document.updatedAt)}
+              </time>
+              {" · "}Built{" "}
+              <time datetime={new Date(snapshot.generatedAt).toISOString()}>
+                {isoDate(snapshot.generatedAt)}
+              </time>
+            </p>
+          </slot>
+        </footer>
+      </main>
+
+      <div class="site-rail">
+        <slot name="aside" />
+      </div>
+    </div>
+  </body>
+</html>