tosijs-ui 1.16.10 → 1.16.11

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # Changelog
 
+## 1.16.11
+
+In-page links work, teaching examples show their test result, and "Download ePub" stops
+offering a book that was never built. `dist/iife.js` grows by 1.2 kB gzip.
+
+- **Headings have ids.** Every heading rendered from markdown now carries an `id`, so
+  `[text](#that-heading)` and `/page/#that-heading` go somewhere. Before this they were
+  links that did nothing, with no error anywhere. The id is the GitHub slug of the heading
+  text, with `-1`, `-2` for a repeat on the same page. Arriving at a heading scrolls it to
+  the top of the page.
+- **The build warns about an in-page link that matches nothing** on its page, naming the
+  page and the anchor. Under `strict: true` it fails the build.
+- **An inset's `#anchor` is matched as the heading's id**, the one the page carries:
+  `install.md#whats-new` now matches "What's new", and `#usage-1` names the second "Usage".
+  The 1.16.9 spelling still matches (`#what-s-new`).
+- **Inline views show the test result** (#219). An example opened with `{"view": "code"}` or
+  `{"view": "console"}` has one line under its preview: the count when its tests pass, the
+  first failure in red when they do not. It covers the `test` block and a `tjs` example's
+  inline tests, and clicking it opens the tab with the detail.
+- **An example in an inline view always runs its tests**, whatever the page's tests switch says (it is off
+  by default away from localhost). A `tjs` example with inline tests therefore transpiles in
+  the page when it is in an inline view on a deployed site, where it used to run from the
+  copy the build transpiled. Examples without a `view` option are unchanged.
+- **Inline views hide empty tabs.** `html`, `css` and `DOM tests` appear only when the
+  example has that block. The full-screen code view still shows them all.
+- **A long section title keeps its arrow.** In the sidebar, a section title that wraps no
+  longer leaves the disclosure triangle alone on a line above it.
+- **"Download ePub" follows the build** (#218). The settings menu links to the ePub at the
+  URL the build wrote, shows a submenu for a site with several volumes, and has no entry on
+  a site that builds none. It used to appear on every site and 404 on those. A hand-written
+  `<tosi-doc-system config>` without the new `ebooks` key keeps the old derived link.
+
 ## 1.16.10
 
 Print now opens with the book cover.

package/dist/doc-browser.js

@@ -978,9 +978,16 @@ export function createDocBrowser(options) {
     const scrollToHashExample = () => {
         if (memoryRouting)
             return;
-        const hash = location.hash.replace(/^#/, '');
+        let hash = location.hash.replace(/^#/, '');
         if (!hash)
             return;
+        try {
+            // A heading id can hold non-ASCII letters, which arrive percent-encoded.
+            hash = decodeURIComponent(hash);
+        }
+        catch {
+            // a stray % — look it up as written
+        }
         requestAnimationFrame(() => {
             let el = null;
             try {
@@ -991,6 +998,12 @@ export function createDocBrowser(options) {
             }
             if (!el)
                 return;
+            // A heading (they have ids as of 1.16.11) goes to the top, where a reader expects a
+            // section to start; an example is centred and flashed.
+            if (/^H[1-6]$/.test(el.tagName)) {
+                el.scrollIntoView({ block: 'start' });
+                return;
+            }
             el.scrollIntoView({ block: 'center', behavior: 'smooth' });
             el.classList.add('example-target');
             setTimeout(() => el && el.classList.remove('example-target'), 1600);

package/dist/doc-system/doc-system-styles.js

@@ -632,6 +632,15 @@ export function docSystemStyleSpec(theme = {}) {
             display: 'inline-block',
             // push the summary text in a bit less than a normal doc-link
             paddingLeft: 'calc(var(--spacing) * 0.5)',
+            /*
+            Room for the disclosure triangle on the same line (#219). An inline-block as wide as
+            its text does not fit beside the marker once the title is long, so the whole link
+            dropped to the next line and left the triangle alone on a row of its own, which reads
+            as an empty nav entry. Capped, it stays beside the triangle and wraps inside itself.
+            */
+            boxSizing: 'border-box',
+            maxWidth: 'calc(100% - 1.5em)',
+            verticalAlign: 'top',
         },
         // Declarative header link list — shown for no-JS, removed on hydration.
         '.doc-navbar': {

package/dist/doc-system/doc-system.d.ts

@@ -2,6 +2,23 @@ import { ElementCreator } from 'tosijs';
 import * as tosijsModule from 'tosijs';
 import { Doc } from '../doc-browser.js';
 import './css-var-editor.js';
+export interface Ebook {
+    title: string;
+    url: string;
+}
+/**
+ * The settings menu's "Download ePub" entry, or `null` for none.
+ *
+ * The item used to be unconditional and its URL derived from the project name, so a site
+ * that built no ePub (the default) shipped a menu item that 404s, and a multi-volume site
+ * or one with `basePath` or `epub.title` linked to a file nothing wrote (#218). The site
+ * build now bakes the list of volumes it makes into the page config:
+ *
+ *   - a list   → one item (or, for several volumes, a submenu), at the build's own URLs
+ *   - `[]`     → the site makes no ePub: no item
+ *   - no key   → a hand-written `config` that predates this: the old derived link, unchanged
+ */
+export declare function epubMenuItem(ebooks: Ebook[] | undefined, legacyUrl: string): Record<string, unknown> | null;
 export declare const CORPUS_ATTEMPTS = 3;
 export declare function fetchCorpus(url: string): Promise<Doc[]>;
 declare const TosiDocSystem_base: tosijsModule.WithAttributes<{

package/dist/doc-system/doc-system.js

@@ -71,6 +71,48 @@ import { i18n, setLocale, initLocalization } from '../localize.js';
 // tweaker under an example. Part of the doc-system, NOT re-exported from tosijs-ui.
 import './css-var-editor.js';
 const { button, div } = elements;
+const download = (url) => () => {
+    const link = document.createElement('a');
+    link.href = url;
+    link.download = '';
+    link.click();
+};
+/**
+ * The settings menu's "Download ePub" entry, or `null` for none.
+ *
+ * The item used to be unconditional and its URL derived from the project name, so a site
+ * that built no ePub (the default) shipped a menu item that 404s, and a multi-volume site
+ * or one with `basePath` or `epub.title` linked to a file nothing wrote (#218). The site
+ * build now bakes the list of volumes it makes into the page config:
+ *
+ *   - a list   → one item (or, for several volumes, a submenu), at the build's own URLs
+ *   - `[]`     → the site makes no ePub: no item
+ *   - no key   → a hand-written `config` that predates this: the old derived link, unchanged
+ */
+export function epubMenuItem(ebooks, legacyUrl) {
+    if (!Array.isArray(ebooks))
+        return {
+            caption: 'Download ePub',
+            icon: 'book',
+            action: download(legacyUrl),
+        };
+    if (ebooks.length === 0)
+        return null;
+    if (ebooks.length === 1)
+        return {
+            caption: 'Download ePub',
+            icon: 'book',
+            action: download(ebooks[0].url),
+        };
+    return {
+        caption: 'Download ePub',
+        icon: 'book',
+        menuItems: ebooks.map((book) => ({
+            caption: book.title,
+            action: download(book.url),
+        })),
+    };
+}
 const PREFS_KEY = 'tosi-doc-system-prefs';
 /*
 Fetch the corpus, retrying a TRANSIENT failure — without becoming the reason it stays down.
@@ -289,10 +331,12 @@ export class TosiDocSystem extends withAttributes({
                 // Print / ePub of the whole corpus, before a separator + the prefs.
                 let projectName = '';
                 let bookVolumes;
+                let ebooks;
                 try {
                     const parsed = JSON.parse(this.config || '{}');
                     projectName = parsed.projectName || '';
                     bookVolumes = parsed.bookVolumes || undefined;
+                    ebooks = parsed.ebooks;
                 }
                 catch {
                     // ignore — fall through to document.title
@@ -345,16 +389,9 @@ export class TosiDocSystem extends withAttributes({
                         void printWhenReady(win, () => highlightBlocks(win.document, { policy: 'none' }));
                     },
                 });
-                menuItems.push({
-                    caption: 'Download ePub',
-                    icon: 'book',
-                    action: () => {
-                        const link = document.createElement('a');
-                        link.href = `/${slugify(bookTitle)}.epub`;
-                        link.download = '';
-                        link.click();
-                    },
-                });
+                const epubItem = epubMenuItem(ebooks, `/${slugify(bookTitle)}.epub`);
+                if (epubItem)
+                    menuItems.push(epubItem);
                 menuItems.push(null);
                 const localeOptions = i18n.localeOptions.value || [];
                 if (localeOptions.length > 1) {

package/dist/doc-system/heading-id.d.ts

@@ -0,0 +1,21 @@
+/** The text a reader sees in a heading: marked's inline tokens with the markup dropped. */
+export declare function headingText(token: any): string;
+/** GitHub-flavoured slug of some heading text. May be empty (a heading of punctuation). */
+export declare function slugOfHeadingText(text: string): string;
+/** The slug of a marked heading token, before any `-1` de-duplication. */
+export declare const headingSlug: (token: any) => string;
+/**
+ * Hands out ids for one page, suffixing a repeat the way GitHub does.
+ *
+ * It knows about headings and nothing else. In particular it does NOT keep headings out of
+ * `example-N`, the ids live examples get in the browser: a reservation here was tried for
+ * 1.16.11 and made `next('example')` loop forever on its second call, because every suffix
+ * of `example` is `example-N`. A heading "Example 2" is `example-2`, as on GitHub. On a page
+ * that also has a second live example the two share that id, and a link reaches whichever
+ * comes first in the document (a known overlap, not checked by the build).
+ */
+export declare class HeadingIds {
+    private seen;
+    /** The id for the next heading with this slug, or '' when the slug is empty. */
+    next(slug: string): string;
+}

package/dist/doc-system/heading-id.js

@@ -0,0 +1,62 @@
+/*
+THE rule for a heading's id, build and client alike.
+
+Headings rendered with no `id`, so `[text](#some-heading)` was a live-looking link that did
+nothing, with no error anywhere (board #3178). The slug is the GitHub-flavoured one, because
+that is what an author writing an in-page link expects and what the same file gets when it is
+read on GitHub: lowercase, every character that is not a letter, a number, a space, `-` or
+`_` dropped, spaces to `-`. A repeat on one page gets `-1`, `-2`, ….
+
+The renderer stamps ids with it and an inset's `#anchor` (single-source.ts) is matched with
+it. Do not write a second copy: an anchor that the build accepts and the page does not carry
+is exactly the silent failure this exists to end.
+*/
+/** The text a reader sees in a heading: marked's inline tokens with the markup dropped. */
+export function headingText(token) {
+    if (Array.isArray(token.tokens) && token.type !== 'codespan')
+        return token.tokens.map(headingText).join('');
+    if (token.type === 'html')
+        return '';
+    if (token.type === 'br')
+        return ' ';
+    return String(token.text ?? '');
+}
+/** GitHub-flavoured slug of some heading text. May be empty (a heading of punctuation). */
+export function slugOfHeadingText(text) {
+    return text
+        .replace(/&(?:#\d+|#x[\da-f]+|[a-z][a-z\d]*);/gi, '') // an entity is not its name
+        .trim()
+        .toLowerCase()
+        .replace(/[^\p{L}\p{N}\p{M}\s_-]/gu, '')
+        .replace(/\s/g, '-');
+}
+/** The slug of a marked heading token, before any `-1` de-duplication. */
+export const headingSlug = (token) => slugOfHeadingText(headingText(token));
+/**
+ * Hands out ids for one page, suffixing a repeat the way GitHub does.
+ *
+ * It knows about headings and nothing else. In particular it does NOT keep headings out of
+ * `example-N`, the ids live examples get in the browser: a reservation here was tried for
+ * 1.16.11 and made `next('example')` loop forever on its second call, because every suffix
+ * of `example` is `example-N`. A heading "Example 2" is `example-2`, as on GitHub. On a page
+ * that also has a second live example the two share that id, and a link reaches whichever
+ * comes first in the document (a known overlap, not checked by the build).
+ */
+export class HeadingIds {
+    seen = new Map();
+    /** The id for the next heading with this slug, or '' when the slug is empty. */
+    next(slug) {
+        if (!slug)
+            return '';
+        let id = slug;
+        // A suffixed id can itself collide with an earlier literal heading ("Usage 1"). Each
+        // pass raises the counter, and `seen` is finite, so this ends.
+        while (this.seen.has(id)) {
+            const n = (this.seen.get(slug) ?? 0) + 1;
+            this.seen.set(slug, n);
+            id = `${slug}-${n}`;
+        }
+        this.seen.set(id, this.seen.get(id) ?? 0);
+        return id;
+    }
+}

package/dist/doc-system/render.js

@@ -10,11 +10,20 @@ give that example a stable anchor — see the docMarked renderer below.
 */
 import { Marked, Renderer } from 'marked';
 import { parseFenceInfo } from './example-policy.js';
+import { HeadingIds, headingSlug } from './heading-id.js';
 const baseRenderer = new Renderer();
 let currentBakes;
+// Per-parse, reset in `preprocess` below (same pattern as the footnote state).
+let headingIds = new HeadingIds();
 const docMarked = new Marked();
 docMarked.use({
     renderer: {
+        // Every heading gets an id, so `[text](#that-heading)` resolves — see heading-id.ts.
+        heading(token) {
+            const id = headingIds.next(headingSlug(token));
+            const inner = this.parser.parseInline(token.tokens);
+            return `<h${token.depth}${id ? ` id="${escapeAttr(id)}"` : ''}>${inner}</h${token.depth}>\n`;
+        },
         code(token) {
             // Fence info grammar: `<lang>` optionally with a `:<mode>` and/or `#<id>` in
             // EITHER order — `js`, `css#anchor`, `js:iframe`, `ts:ide#demo`, `ts#demo:ide`.
@@ -84,6 +93,7 @@ docMarked.use({
         preprocess(markdown) {
             footnoteDefs = new Map();
             footnoteOrder = [];
+            headingIds = new HeadingIds();
             return markdown;
         },
         postprocess(html) {

package/dist/doc-system/site/build-warnings.d.ts

@@ -21,3 +21,4 @@ export declare function misconfigured(strict: boolean | undefined, message: stri
 export declare function liveFenceLanguages(docs: Array<{
     text?: string;
 }>, policy?: ExamplePolicy): Set<string>;
+export declare function deadInPageAnchors(html: string): string[];

package/dist/doc-system/site/build-warnings.js

@@ -43,3 +43,64 @@ export function liveFenceLanguages(docs, policy = 'auto') {
     }
     return langs;
 }
+const unescapeAttr = (s) => s
+    .replace(/"/g, '"')
+    .replace(/'/g, "'")
+    .replace(/&lt;/g, '<')
+    .replace(/&gt;/g, '>')
+    .replace(/&amp;/g, '&');
+/**
+ * The in-page links (`href="#…"`) in a RENDERED page that point at no id on it.
+ *
+ * A dead in-page anchor is the one broken link a reader cannot tell from a working one: it
+ * is styled as a link, it does nothing, and nothing reports it (board #3178). Asked of the
+ * rendered HTML and not of the markdown, so the ids are the ones the page really carries
+ * (`renderDocMarkdown`, THE renderer) and no second copy of the heading-id rule exists here.
+ *
+ * Not reported, because they are not in-page anchors or resolve only in the browser:
+ * `#/route` and `#!…` (hash routers), a bare `#`, `#top`, and `#example-N` (live examples
+ * are numbered when the page hydrates). A fence's own `#id` is on the rendered page and is
+ * checked like any other id.
+ *
+ * Tags are read with their attributes in any order and any quoting. What it cannot see is
+ * an id that only exists once a script has run; such a link is reported.
+ */
+// One HTML start tag, attributes and all. Quoted values may hold `>`, which is why this is
+// not `<[^>]*>`.
+const START_TAG = /<([a-z][a-z0-9-]*)((?:\s+[^\s"'<>/=]+(?:\s*=\s*(?:"[^"]*"|'[^']*'|[^\s"'=<>`]+))?)*)\s*\/?>/gi;
+const ATTRIBUTE = /([^\s"'<>/=]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'=<>`]+)))?/g;
+export function deadInPageAnchors(html) {
+    const ids = new Set();
+    const links = [];
+    for (const tag of html.matchAll(START_TAG)) {
+        const name = tag[1].toLowerCase();
+        for (const attr of tag[2].matchAll(ATTRIBUTE)) {
+            const key = attr[1].toLowerCase();
+            const value = unescapeAttr(attr[2] ?? attr[3] ?? attr[4] ?? '');
+            if (key === 'id' || key === 'data-example-id')
+                ids.add(value);
+            // `name` is an anchor target on <a> only; on a form field it is a field name.
+            else if (key === 'name' && name === 'a')
+                ids.add(value);
+            else if (key === 'href' && name === 'a' && value.startsWith('#'))
+                links.push(value.slice(1));
+        }
+    }
+    const dead = new Set();
+    for (let target of links) {
+        try {
+            target = decodeURIComponent(target);
+        }
+        catch {
+            // a stray % — compare it as written
+        }
+        if (!target ||
+            target === 'top' ||
+            /^[/!]/.test(target) ||
+            /^example-\d+$/.test(target) ||
+            ids.has(target))
+            continue;
+        dead.add(target);
+    }
+    return [...dead];
+}

package/dist/doc-system/site/generate-site.d.ts

@@ -14,12 +14,23 @@ export interface GenerateSiteConfig {
     liveExamples?: 'auto' | 'opt-in';
     /** directory to write pages into (the served web root, e.g. ./docs) */
     outputDir: string;
+    /** `SiteConfig.strict`: a build warning raised here fails the build */
+    strict?: boolean;
     projectName?: string;
     /**
      * URL of the volume manifest (`/epub-volumes.json`). Print reads the default volume's
      * cover from it; omitted when the site has no ePub or opted out with `printCover: false`.
      */
     bookVolumes?: string;
+    /**
+     * The ePubs this build makes (`listEpubVolumes`), for the "Download ePub" menu entry.
+     * `[]` says the site makes none, which removes the entry; leave it unset only if you do
+     * not know (the entry then links to the name derived from `projectName`, as it used to).
+     */
+    ebooks?: Array<{
+        title: string;
+        url: string;
+    }>;
     /** site-level description, used as a fallback when a doc has none */
     description?: string;
     /** <html lang>, default 'en' */

package/dist/doc-system/site/generate-site.js

@@ -15,6 +15,7 @@ import { highlightHtml } from '../highlight.js';
 import { buildSlugMap, pathForSlug, rewriteDocLinks, withBase, } from '../routing.js';
 import { buildNavTree, navOpenPath } from '../nav-tree.js';
 import { renderDocMarkdown, docDescription, } from '../render.js';
+import { deadInPageAnchors, misconfigured } from './build-warnings.js';
 const escapeAttr = (s) => s
     .replace(/&/g, '&')
     .replace(/</g, '&lt;')
@@ -304,13 +305,20 @@ export async function generateSite(config) {
         projectLinks: config.projectLinks,
         logo: config.logo,
         bookVolumes: config.bookVolumes,
+        ebooks: config.ebooks,
     }));
     // The theme stylesheet (config.stylesUrl) is written separately by
     // ./generate-css.ts; pages here just <link> to it.
     let count = 0;
+    const deadAnchors = [];
     for (const doc of docs) {
         const slug = slugMap[doc.filename];
         const dir = slug === '' ? outputDir : `${outputDir}/${slug}`;
+        const dead = deadInPageAnchors(renderDocMarkdown(doc.text));
+        if (dead.length)
+            deadAnchors.push(`    ${doc.path || doc.filename}: ${dead
+                .map((d) => `#${d}`)
+                .join(', ')}`);
         await Bun.write(`${dir}/index.html`, await pageHtml(doc, config, slugMap, configAttr));
         // The page's own source, for readers that want text rather than a page.
         if (hasMarkdownPage(doc, config)) {
@@ -318,6 +326,11 @@ export async function generateSite(config) {
         }
         count += 1;
     }
+    if (deadAnchors.length) {
+        misconfigured(config.strict, `\n⚠️  In-page links that point at nothing on their page. A heading's id is its text,\n` +
+            `    lowercased, punctuation dropped, spaces as "-" (a repeat gets -1, -2, …):\n` +
+            `${deadAnchors.join('\n')}\n`);
+    }
     // The corpus the component fetches for nav + client-side rendering of other pages.
     // Attach each doc's tjs bakes so client-side SPA navigation renders the same hidden
     // <script type="application/tosi-transpiled"> the pre-rendered page has, and runs

package/dist/doc-system/site/orchestrator.js

@@ -1480,6 +1480,13 @@ export async function buildSite(config, opts = {}) {
                 outputDir: PUBLIC,
                 projectName: config.name,
                 bookVolumes: printCoverManifestUrl(config),
+                ebooks: config.epub
+                    ? listEpubVolumes(docs, config).map(({ title, url }) => ({
+                        title,
+                        url,
+                    }))
+                    : [],
+                strict: config.strict,
                 description: config.description,
                 baseUrl: config.baseUrl,
                 lang: config.lang,

package/dist/doc-system/site/single-source.js

@@ -23,6 +23,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { marked } from 'marked';
 import { buildSlugMap, resolveParent, slugify } from '../routing.js';
+import { HeadingIds, headingSlug, slugOfHeadingText } from '../heading-id.js';
 import { mayHaveSingleSourceDirective } from '../book-target.js';
 export class SingleSourceError extends Error {
     constructor(message) {
@@ -110,7 +111,14 @@ export function isSingleSourceDirective(json) {
     }
 }
 const mayHaveDirective = mayHaveSingleSourceDirective;
-const headingSlug = (token) => slugify(String(token.text ?? '').replace(/`/g, ''));
+/*
+An inset's `#anchor` names a heading by the id the page gives it (`headingSlug`, THE rule).
+The spelling insets shipped with in 1.16.9 is still accepted: it differs only where a heading
+has punctuation ("What's new" was `what-s-new`, and is `whats-new` on the page).
+*/
+const legacyHeadingSlug = (token) => slugify(String(token.text ?? '').replace(/`/g, ''));
+const headingMatches = (token, anchor) => headingSlug(token) === slugOfHeadingText(anchor) ||
+    legacyHeadingSlug(token) === slugify(anchor);
 /*
 What an inset contributes: the passage, not its place in some other page's outline.
 
@@ -143,8 +151,16 @@ function bodyOf(text, anchor, ref) {
             .join('')
             .trim();
     }
-    const want = slugify(anchor);
-    const start = tokens.findIndex((t) => t.type === 'heading' && headingSlug(t) === want);
+    // By the id the page gives it first (so `#usage-1` names the second "Usage"), then by slug.
+    const ids = new HeadingIds();
+    const pageIds = tokens.map((t) => t.type === 'heading' ? ids.next(headingSlug(t)) : '');
+    // An anchor with nothing sluggable in it ("#???") names no heading; '' is also what every
+    // non-heading token has in `pageIds`, so it must not be looked up there.
+    const wanted = slugOfHeadingText(anchor);
+    const byId = wanted ? pageIds.indexOf(wanted) : -1;
+    const start = byId > -1
+        ? byId
+        : tokens.findIndex((t) => t.type === 'heading' && headingMatches(t, anchor));
     if (start < 0) {
         const have = tokens
             .filter((t) => t.type === 'heading')