@apisurf/canonui 0.1.1 → 0.1.2

package/README.md

@@ -56,19 +56,20 @@ one stylesheet of plain CSS with tokens on `:root`.
 The page is two columns: the document — title, description, a copy button, then
 every block in order — and a rail listing its titled blocks and the headings
 inside markdown blocks. There is no framework, and the client-side runtime is
-four small scripts: the wide toggle, the copy button, the rail's scroll
-tracking, and mermaid when the document holds a diagram — bundled into the site
+five small scripts: the wide toggle, the copy button, the one that puts it on
+each section's heading, the rail's scroll tracking, and mermaid when the document holds a diagram — bundled into the site
 rather than fetched from a CDN, so it works offline.
 
-| File                           | What it is                                      |
-| ------------------------------ | ----------------------------------------------- |
-| `theme/layouts/Site.astro`     | The shell, and every slot a theme would replace |
-| `theme/components/Block.astro` | One block, drawn according to its type          |
-| `theme/components/Toc.astro`   | The contents rail                               |
-| `theme/components/Copy.astro`  | The button that copies the document as markdown |
-| `theme/pages/index.astro`      | The document, at `/`                            |
-| `theme/styles/theme.css`       | The whole of the styling                        |
-| `theme/lib/snapshot.ts`        | The snapshot, read once at build time           |
+| File                                 | What it is                                      |
+| ------------------------------------ | ----------------------------------------------- |
+| `theme/layouts/Site.astro`           | The shell, and every slot a theme would replace |
+| `theme/components/Block.astro`       | One block, drawn according to its type          |
+| `theme/components/Toc.astro`         | The contents rail                               |
+| `theme/components/Copy.astro`        | The button that copies the document as markdown |
+| `theme/components/SectionCopy.astro` | The same button, on each section's heading      |
+| `theme/pages/index.astro`            | The document, at `/`                            |
+| `theme/styles/theme.css`             | The whole of the styling                        |
+| `theme/lib/snapshot.ts`              | The snapshot, read once at build time           |
 
 ### The markdown twin
 
@@ -81,6 +82,11 @@ copy button fetches it rather than embedding it, so the button wants the site
 served rather than opened off the disk, where `fetch` has no origin to work
 from; everything else on the page works either way.
 
+Each top-level section is written the same way, to `/sections/<anchor>.md`,
+with `bundleSection`. Where the sections fall is `theme/lib/sections.ts`, which
+the command imports so that the files it writes and the headings the page puts
+buttons on are cut by the same parse.
+
 The theme sits under `theme/` rather than Astro's default `src/`, which this
 package uses for the command itself. `astro.config.mjs` points `srcDir` at it.
 

package/dist/bin.js

@@ -32,6 +32,11 @@ function bundleDocument(snapshot, options = {}) {
   return `${parts.join("\n\n")}
 `;
 }
+function bundleSection(blocks) {
+  const level = blocks[0]?.title ? 2 : 1;
+  return `${blocks.map((block) => renderBlock(block, block.title ? 2 : level)).join("\n\n")}
+`;
+}
 function frontMatter(snapshot) {
   const d = snapshot.document;
   const lines = [
@@ -629,6 +634,99 @@ function run(bin, env, verbose) {
   });
 }
 
+// theme/lib/markdown.ts
+import { Marked } from "marked";
+var sink = null;
+var slugs = null;
+var anchors = null;
+var prefix = "";
+var marked = new Marked({ gfm: true, breaks: false });
+marked.use({
+  renderer: {
+    /**
+     * Headings carry an id so a section can be linked, and are recorded on the
+     * way past so the page can draw its own contents.
+     */
+    heading(token) {
+      const text = this.parser.parseInline(token.tokens);
+      const id = slug(stripTags(text));
+      anchors?.set(token, id);
+      if (sink && (token.depth === 2 || token.depth === 3)) {
+        sink.push({ id, text: stripTags(text), depth: token.depth });
+      }
+      return `<h${token.depth} id="${id}"><a class="anchor" href="#${id}">${text}</a></h${token.depth}>
+`;
+    }
+  }
+});
+var cache = /* @__PURE__ */ new Map();
+function renderBlock2(block) {
+  const hit = cache.get(block.uid);
+  if (hit) return hit;
+  sink = [];
+  slugs = /* @__PURE__ */ new Map();
+  anchors = /* @__PURE__ */ new Map();
+  prefix = `b${block.seq}`;
+  const tokens = marked.lexer(block.content);
+  const html = marked.parser(tokens);
+  const rendered = { html, headings: sink, parts: split(tokens, anchors) };
+  sink = null;
+  slugs = null;
+  anchors = null;
+  cache.set(block.uid, rendered);
+  return rendered;
+}
+function split(tokens, ids) {
+  const parts = [{ id: null, depth: null, content: "" }];
+  for (const token of tokens) {
+    const depth = token.type === "heading" && token.depth <= 2 ? token.depth : null;
+    const id = depth ? ids.get(token) : void 0;
+    if (depth && id) parts.push({ id, depth, content: "" });
+    parts[parts.length - 1].content += token.raw;
+  }
+  return parts;
+}
+function slug(text) {
+  const base = text.toLowerCase().replace(/[^\p{L}\p{N}]+/gu, "-").replace(/^-+|-+$/g, "");
+  const stem = `${prefix}-${base || "section"}`;
+  const seen = slugs?.get(stem) ?? 0;
+  slugs?.set(stem, seen + 1);
+  return seen === 0 ? stem : `${stem}-${seen + 1}`;
+}
+function stripTags(html) {
+  return html.replace(/<[^>]*>/g, "");
+}
+
+// theme/lib/sections.ts
+function sections(blocks) {
+  const found = [];
+  let open2 = [];
+  const start = (id, depth, block) => {
+    open2 = open2.filter((section2) => section2.depth < depth);
+    const section = { id, depth, blocks: [] };
+    found.push(section);
+    open2.push(section);
+    add(block);
+  };
+  const add = (block) => {
+    for (const section of open2) section.blocks.push(block);
+  };
+  for (const block of blocks) {
+    if (block.title) {
+      start(`b${block.seq}`, 2, block);
+    } else if (block.type !== "markdown") {
+      add(block);
+    } else {
+      for (const part of renderBlock2(block).parts) {
+        const piece = { ...block, content: part.content };
+        if (part.id && part.depth) start(part.id, part.depth, piece);
+        else if (part.content.trim()) add(piece);
+      }
+    }
+  }
+  return found;
+}
+
 // src/build.ts
 var BUILDS_DIR = "builds";
 async function build(options) {
@@ -669,6 +767,12 @@ function writeMarkdown(snapshot, out) {
     bundleDocument(snapshot, { toc: true, meta: false }),
     "utf8"
   );
+  const dir = join(out, "sections");
+  rmSync(dir, { recursive: true, force: true });
+  mkdirSync2(dir, { recursive: true });
+  for (const section of sections(snapshot.blocks)) {
+    writeFileSync(join(dir, `${section.id}.md`), bundleSection(section.blocks), "utf8");
+  }
 }
 function prepare(options) {
   const db = openRead(options);
@@ -714,15 +818,15 @@ function report(options, result) {
     return;
   }
   const what = result.rendered ? "built" : "wrote snapshot for";
-  const slug = result.snapshot.document.slug;
+  const slug2 = result.snapshot.document.slug;
   process.stdout.write(
     `
-  ${what} ${slug}
+  ${what} ${slug2}
 
   blocks  ${result.blocks}
   output  ${result.out}
 
-` + (result.rendered && !options.serving ? `  Serve it:  canonui serve ${slug}
+` + (result.rendered && !options.serving ? `  Serve it:  canonui serve ${slug2}
 
 ` : "\n")
   );
@@ -1132,6 +1236,7 @@ var SITES_HELP = `canonui sites \u2014 what a built site is, and what it needs.
 The folder
   index.html          the document: its title, description and every block
   index.md            the same document as markdown
+  sections/           each top-level section as markdown, named for its anchor
   404.html            served for anything else
   _astro/             the stylesheet, and scripts only where a block needs one
 
@@ -1169,6 +1274,11 @@ The markdown twin
   without the front matter. It is what the copy button under the title puts
   on the clipboard, and what curl gets you without one.
 
+  Each top-level section \u2014 a titled block, or an h1 or h2 at the top of an
+  untitled markdown block, up to the next heading of its rank \u2014 has its own
+  under /sections/, copied by the button that appears when its heading is
+  hovered. An h1 runs on past the h2s under it, so it copies all of them.
+
   The button fetches what it copies, so it wants the site served rather than
   opened off the disk \u2014 canonui open is enough, and so is any host. Everything
   else on the page works either way.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@apisurf/canonui",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "canonui — build and preview the documents that canon holds: render one into static HTML, or serve it locally.",
   "keywords": [
     "astro",

package/theme/components/Copy.astro

@@ -11,9 +11,9 @@
  * and hydration.
  */
 interface Props {
-  /** The .md the button copies. */
-  href: string;
-  /** What it copies, for the resting label — "document". */
+  /** The .md the button copies. Left out when a script fills it in. */
+  href?: string;
+  /** What it copies, for the resting label — "document", "section". */
   what: string;
 }
 
@@ -65,10 +65,6 @@ const { href, what } = Astro.props;
 </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;
 
   /*
@@ -138,30 +134,47 @@ const { href, what } = Astro.props;
     }
   }
 
-  for (const button of document.querySelectorAll<HTMLButtonElement>("[data-copy]")) {
-    let timer: ReturnType<typeof setTimeout> | undefined;
-    const url = button.dataset.copy as string;
+  /*
+   * Bound once on the document rather than on each button: the section buttons
+   * are put on their headings after this runs, and a handler per button would
+   * miss them.
+   */
+  const timers = new WeakMap<HTMLButtonElement, ReturnType<typeof setTimeout>>();
 
-    // 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);
+  const buttonOf = (event: Event) =>
+    event.target instanceof Element
+      ? event.target.closest<HTMLButtonElement>("button[data-copy]")
+      : null;
 
-    button.addEventListener("click", async () => {
-      clearTimeout(timer);
-      let ok = false;
-      try {
-        ok = await copy(url);
-      } catch {
-        ok = false;
-      }
+  // 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 = (event: Event) => {
+    const url = buttonOf(event)?.dataset.copy;
+    if (url) void markdown(url).catch(() => {});
+  };
+  document.addEventListener("pointerover", warm);
+  document.addEventListener("focusin", warm);
 
-      button.dataset.state = ok ? "done" : "failed";
-      timer = setTimeout(() => {
+  document.addEventListener("click", async (event) => {
+    const button = buttonOf(event);
+    const url = button?.dataset.copy;
+    if (!button || !url) return;
+
+    clearTimeout(timers.get(button));
+    let ok = false;
+    try {
+      ok = await copy(url);
+    } catch {
+      ok = false;
+    }
+
+    button.dataset.state = ok ? "done" : "failed";
+    timers.set(
+      button,
+      setTimeout(() => {
         button.dataset.state = "idle";
-      }, RESET_MS);
-    });
-  }
+      }, RESET_MS),
+    );
+  });
 </script>

package/theme/components/SectionCopy.astro

@@ -0,0 +1,51 @@
+---
+/**
+ * A copy button on each top-level section's heading, shown when it is hovered.
+ *
+ * The headings come from two places — a block's title, drawn here, and an h2
+ * inside a markdown block, drawn by marked as a string — so the button is put
+ * on them in the browser, from one template, rather than written twice. It is
+ * `Copy` either way, so it looks and behaves like the document's own.
+ */
+import Copy from "./Copy.astro";
+
+interface Props {
+  /** Each section's anchor, and the .md its button copies. */
+  sections: { id: string; href: string }[];
+}
+
+const { sections } = Astro.props;
+---
+
+{
+  sections.length > 0 && (
+    <template data-section-copy={JSON.stringify(sections)}>
+      <Copy what="section" />
+    </template>
+  )
+}
+
+<script>
+  const template = document.querySelector<HTMLTemplateElement>("template[data-section-copy]");
+  const sections = JSON.parse(template?.dataset.sectionCopy ?? "[]") as {
+    id: string;
+    href: string;
+  }[];
+
+  for (const { id, href } of sections) {
+    // A titled block's anchor is on the block, and its heading is the title.
+    const target = document.getElementById(id);
+    const heading = target?.matches("h1, h2") ? target : target?.querySelector(":scope > h2");
+    const button = template?.content.firstElementChild?.cloneNode(true);
+    if (!heading || !(button instanceof HTMLButtonElement)) continue;
+
+    const title = heading.textContent?.trim() ?? "";
+    button.dataset.copy = href;
+    button.classList.add("section-copy");
+    button.setAttribute("aria-label", `Copy the section “${title}” as markdown`);
+    // Named for its own text, not the button that now sits inside it.
+    heading.setAttribute("aria-label", title);
+    heading.classList.add("section-heading");
+    heading.append(button);
+  }
+</script>

package/theme/lib/markdown.ts

@@ -10,7 +10,7 @@
  * would break the `html` block type, which exists precisely to pass markup
  * through. Do not point a build at a database you did not write.
  */
-import { Marked } from "marked";
+import { Marked, type Token } from "marked";
 import type { SnapshotBlock } from "@canon/db";
 
 /** One entry in a page's outline: a heading, and the anchor that reaches it. */
@@ -20,10 +20,21 @@ export interface Heading {
   depth: 2 | 3;
 }
 
+/**
+ * A block's source, cut where it opens a section: the text before its first
+ * top-level h1 or h2, then one part per such heading, with its anchor and rank.
+ */
+export interface BlockPart {
+  id: string | null;
+  depth: 1 | 2 | null;
+  content: string;
+}
+
 /** A rendered block: its markup, and the headings a table of contents can link. */
 export interface RenderedBlock {
   html: string;
   headings: Heading[];
+  parts: BlockPart[];
 }
 
 /**
@@ -36,6 +47,8 @@ export interface RenderedBlock {
  */
 let sink: Heading[] | null = null;
 let slugs: Map<string, number> | null = null;
+/** The anchor each heading was given, keyed by the token it was drawn from. */
+let anchors: Map<Token, string> | null = null;
 let prefix = "";
 
 const marked = new Marked({ gfm: true, breaks: false });
@@ -49,6 +62,7 @@ marked.use({
     heading(token) {
       const text = this.parser.parseInline(token.tokens);
       const id = slug(stripTags(text));
+      anchors?.set(token, id);
       if (sink && (token.depth === 2 || token.depth === 3)) {
         sink.push({ id, text: stripTags(text), depth: token.depth });
       }
@@ -72,11 +86,16 @@ export function renderBlock(block: SnapshotBlock): RenderedBlock {
 
   sink = [];
   slugs = new Map();
+  anchors = new Map();
   prefix = `b${block.seq}`;
-  const html = marked.parse(block.content, { async: false });
-  const rendered: RenderedBlock = { html, headings: sink };
+  // Lexed and parsed as two steps so the top-level tokens are in hand to cut
+  // the source at. Their raw text, end to end, is the source.
+  const tokens = marked.lexer(block.content);
+  const html = marked.parser(tokens);
+  const rendered: RenderedBlock = { html, headings: sink, parts: split(tokens, anchors) };
   sink = null;
   slugs = null;
+  anchors = null;
 
   cache.set(block.uid, rendered);
   return rendered;
@@ -92,6 +111,21 @@ export function headingsOf(block: SnapshotBlock): Heading[] {
   return block.type === "markdown" ? renderBlock(block).headings : [];
 }
 
+/**
+ * Cut at the h1s and h2s that stand at the top of the block. One inside a
+ * blockquote or a list is part of what surrounds it, not the start of a section.
+ */
+function split(tokens: Token[], ids: Map<Token, string>): BlockPart[] {
+  const parts: BlockPart[] = [{ id: null, depth: null, content: "" }];
+  for (const token of tokens) {
+    const depth = token.type === "heading" && token.depth <= 2 ? (token.depth as 1 | 2) : null;
+    const id = depth ? ids.get(token) : undefined;
+    if (depth && id) parts.push({ id, depth, content: "" });
+    (parts[parts.length - 1] as BlockPart).content += token.raw;
+  }
+  return parts;
+}
+
 /**
  * `b2-when-a-retry-fires` — stable across builds, unique within the document.
  *

package/theme/lib/sections.ts

@@ -0,0 +1,64 @@
+/**
+ * A document's top-level sections: each heading at the top of the content,
+ * and everything under it up to the next heading of the same rank or higher.
+ *
+ * Three things open one — a titled block, whose title is drawn as an h2, and an
+ * h1 or an h2 standing at the top of an untitled markdown block. Sections nest
+ * the way markdown's do: an h1 runs on past the h2s under it, so the h1 copies
+ * all of them and each h2 copies itself. Headings inside a titled block are
+ * subsections of its title, as the outline and the markdown twin both have it.
+ *
+ * Shared by the page, which puts a copy button on each section's heading, and
+ * by `canonui build`, which writes the markdown that button copies. Both cut
+ * where the renderer cut, so a button cannot end up pointing at the wrong
+ * stretch of the document.
+ */
+import type { SnapshotBlock } from "@canon/db";
+import { renderBlock } from "./markdown";
+
+export interface Section {
+  /** The heading's anchor, which also names the section's markdown file. */
+  id: string;
+  /** 1 for an h1, 2 for an h2 or a block title. */
+  depth: 1 | 2;
+  /** Its blocks, the first and last cut down to the part inside the section. */
+  blocks: SnapshotBlock[];
+}
+
+export function sections(blocks: readonly SnapshotBlock[]): Section[] {
+  const found: Section[] = [];
+  // The sections still running, outermost first.
+  let open: Section[] = [];
+
+  const start = (id: string, depth: 1 | 2, block: SnapshotBlock) => {
+    open = open.filter((section) => section.depth < depth);
+    const section = { id, depth, blocks: [] };
+    found.push(section);
+    open.push(section);
+    add(block);
+  };
+  const add = (block: SnapshotBlock) => {
+    for (const section of open) section.blocks.push(block);
+  };
+
+  for (const block of blocks) {
+    if (block.title) {
+      start(`b${block.seq}`, 2, block);
+    } else if (block.type !== "markdown") {
+      add(block);
+    } else {
+      for (const part of renderBlock(block).parts) {
+        const piece = { ...block, content: part.content };
+        if (part.id && part.depth) start(part.id, part.depth, piece);
+        else if (part.content.trim()) add(piece);
+      }
+    }
+  }
+
+  return found;
+}
+
+/** Href for a section's markdown, honouring the configured base path. */
+export function sectionHref(base: string, id: string): string {
+  return `${base.endsWith("/") ? base : `${base}/`}sections/${encodeURIComponent(id)}.md`;
+}

package/theme/pages/index.astro

@@ -8,11 +8,14 @@
 import Site from "../layouts/Site.astro";
 import Blocks from "../components/Blocks.astro";
 import Copy from "../components/Copy.astro";
+import SectionCopy from "../components/SectionCopy.astro";
 import Toc from "../components/Toc.astro";
 import { outline } from "../lib/outline";
+import { sectionHref, sections } from "../lib/sections";
 import { blocks, document, mdHref } from "../lib/snapshot";
 
 const base = import.meta.env.BASE_URL;
+const copyable = sections(blocks).map(({ id }) => ({ id, href: sectionHref(base, id) }));
 ---
 
 <Site title={document.title} description={document.description}>
@@ -29,4 +32,6 @@ const base = import.meta.env.BASE_URL;
 
     <Blocks blocks={blocks} />
   </article>
+
+  <SectionCopy sections={copyable} />
 </Site>

package/theme/styles/theme.css

@@ -436,6 +436,56 @@ pre.mermaid[data-processed="true"] {
   margin: 0;
 }
 
+/*
+ * The same button on each section's heading, kept out of sight until the
+ * heading is hovered. Pinned to the right edge rather than set after the title,
+ * so turning it on does not rewrap the heading.
+ */
+.section-heading {
+  position: relative;
+  /* One line of the heading — 1.35rem at a leading of 1.3 — so the button can
+     centre on the first line rather than on all of them when the title wraps. */
+  --section-line: 1.755rem;
+}
+
+/* 2rem at 1.25. */
+h1.section-heading {
+  --section-line: 2.5rem;
+}
+
+.section-copy {
+  position: absolute;
+  right: 0;
+  top: calc(var(--section-line) / 2);
+  transform: translateY(-50%);
+  background: var(--bg);
+  font-weight: 400;
+  letter-spacing: normal;
+  opacity: 0;
+  transition:
+    opacity 120ms ease,
+    color 120ms ease,
+    border-color 120ms ease,
+    background-color 120ms ease;
+}
+
+.section-heading:hover > .section-copy,
+.section-copy:focus-visible,
+.section-copy:not([data-state="idle"]) {
+  opacity: 1;
+}
+
+/* Nothing to hover on a touchscreen, so there it sits after the title instead. */
+@media (hover: none) {
+  .section-copy {
+    position: static;
+    transform: none;
+    margin-left: 0.6rem;
+    vertical-align: middle;
+    opacity: 1;
+  }
+}
+
 /* -----------------------------------------------------------------------------
  * Narrower screens
  *