tosijs-ui 1.6.12 → 1.6.14

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # Changelog
 
+## 1.6.14
+
+Lighter live-example transpilation. Additive; affects only how the live-example
+runner loads its (optional, lazy) transpiler.
+
+### Changed
+
+- **Live examples now use tjs-lang 0.8.5's self-contained browser bundles**
+  (`tjs-lang/browser` + `tjs-lang/browser/from-ts`). The transpiler is a single
+  self-contained chunk, and the TypeScript compiler is **lazy-loaded from a CDN at
+  runtime** only when a `ts` example actually transpiles — so `typescript` (~MB)
+  and the transpiler's own deps are never in a consumer's dependency graph. This
+  also fixes the `ts` example path, which previously tried to load the TypeScript
+  compiler through a CDN transform that timed out on its size.
+- `tjs-lang` optional peer bumped to `^0.8.6`.
+
+### Fixed
+
+- A garbled character in the first `example` doc snippet that made it throw.
+
+## 1.6.13
+
+The documentation system becomes a real publishing pipeline: every doc site can
+now emit an **ePub** of the whole corpus, **print to PDF** from the browser, and
+**deep-link every example from the book back to the live site**. All changes are
+**additive — no breaking changes** — and concern the doc-site tooling
+(`tosijs-ui/site`) and doc browser, not the components.
+
+### Added
+
+- **ePub of the whole doc site** (`tosijs-ui/site`). Set `epub: true` (or an
+  options object) in the site config and the build emits a valid EPUB 3 of the
+  corpus alongside the static pages, regenerated on every build:
+  - one chapter per doc in nav-tree order, a readable **Contents page** in the
+    reading flow plus the reader's Contents drawer (EPUB3 `nav.xhtml` + EPUB2
+    `toc.ncx`), and a customizable stylesheet (`epub.css` / default force-wraps
+    code listings)
+  - an **auto-generated cover** from the title + favicon (`epub.cover` /
+    `epub.coverColor` to override); needs the optional `@resvg/resvg-js`, and is
+    omitted gracefully if it's absent
+- **Print to PDF** from the doc browser — a "Print as PDF" item in the settings
+  menu assembles the whole corpus into a print-styled window and opens the print
+  dialog. No server, no headless browser. (A headless `buildPdf` is also available
+  for CI via `bun run book:pdf`, not deployed.)
+- **"Download ePub"** item in the settings menu (alongside Print), linking the
+  built book.
+- **Example anchors + book deep links.** Every live example gets a stable anchor
+  (`/{slug}/#example-1`, or a custom `id` via a ` ```js#my-id ` fence on any block
+  of the group). Arriving at such a URL scrolls the example into view with a brief
+  highlight. Each example in the ePub/PDF links back to its anchor on the live
+  site — a reader is one tap from the real, interactive, editable version.
+
+### Removed
+
+- The broken **bundlejs** size badge (bundlejs errors computing the bundle).
+
+### Notes
+
+- The ePub needs `happy-dom` (dev dep) + the `zip` CLI; the generated cover needs
+  the optional `@resvg/resvg-js`.
+
 ## 1.6.12
 
 Packaging improvements for independent, tree-shakeable consumption. All changes

package/README.md

@@ -5,7 +5,6 @@
 [ui.tosijs.net live demo](https://ui.tosijs.net) | [tosijs](https://tosijs.net) | [discord](https://discord.gg/ramJ9rgky5) | [github](https://github.com/tonioloewald/tosijs-ui#readme) | [npm](https://www.npmjs.com/package/tosijs-ui)
 
 [![tosijs is on NPM](https://badge.fury.io/js/tosijs-ui.svg)](https://www.npmjs.com/package/tosijs-ui)
-[![tosijs is about 10kB gzipped](https://deno.bundlejs.com/?q=tosijs-ui&badge=)](https://bundlejs.com/?q=tosijs-ui&badge=)
 [![tosijs on jsdelivr](https://data.jsdelivr.com/v1/package/npm/tosijs-ui/badge)](https://www.jsdelivr.com/package/npm/tosijs-ui)
 
 <center>

package/dist/doc-browser.js

@@ -241,6 +241,15 @@ const testIndicatorStyleSpec = {
         justifyContent: 'center',
         fontWeight: 'bold',
     },
+    // Deep-linked example (e.g. arriving at /slug/#example-2): brief highlight pulse
+    '@keyframes example-target-pulse': {
+        from: { boxShadow: `0 0 0 3px ${varDefault.accent('#007aff')}` },
+        to: { boxShadow: '0 0 0 3px transparent' },
+    },
+    '.example-target': {
+        animation: 'example-target-pulse 1.5s ease-out',
+        borderRadius: vars.roundedRadius,
+    },
 };
 export function createDocBrowser(options) {
     const { docs, context = {}, projectName = '', projectLinks = {}, navSize = 200, minSize = 600, routing = 'query', initialRoute, onRouteChange, navbarLinks, contentElement, } = options;
@@ -560,6 +569,31 @@ export function createDocBrowser(options) {
             }
         }
     };
+    // Deep-link to a specific live example: arriving at /slug/#example-2 (or a
+    // custom ```js#my-id anchor) scrolls it into view with a brief highlight. The
+    // example ids are set by insertExamples, so this runs after it. Skipped in
+    // memory routing (which must never touch window.location).
+    const scrollToHashExample = () => {
+        if (memoryRouting)
+            return;
+        const hash = location.hash.replace(/^#/, '');
+        if (!hash)
+            return;
+        requestAnimationFrame(() => {
+            let el = null;
+            try {
+                el = docContent.querySelector(`#${CSS.escape(hash)}`);
+            }
+            catch {
+                el = null;
+            }
+            if (!el)
+                return;
+            el.scrollIntoView({ block: 'center', behavior: 'smooth' });
+            el.classList.add('example-target');
+            setTimeout(() => el && el.classList.remove('example-target'), 1600);
+        });
+    };
     let adoptInitialContent = contentElement !== undefined && !memoryRouting;
     const showDoc = (doc) => {
         if (adoptInitialContent) {
@@ -572,6 +606,7 @@ export function createDocBrowser(options) {
         // Stamp each example with its source file (for the source↔doc map). doc.path
         // is the extracted file (.md, or a source file with doc comments).
         LiveExample.insertExamples(docContent, context, doc.path || undefined);
+        scrollToHashExample();
         if (routing === 'path') {
             document.title = projectName
                 ? `${doc.title} — ${projectName}`

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

@@ -0,0 +1,26 @@
+import { NavNode, NavDoc } from './nav-tree';
+export interface BookDoc {
+    filename: string;
+    title: string;
+    text: string;
+    parent?: string;
+    hidden?: boolean;
+}
+export declare const DEFAULT_BOOK_CSS = "/* doc-system book stylesheet */\nhtml { font-size: 100%; }\nbody {\n  font-family: Georgia, 'Times New Roman', serif;\n  line-height: 1.5;\n  margin: 0 1em;\n  color: #1a1a1a;\n}\nh1, h2, h3, h4, h5, h6 {\n  font-family: -apple-system, 'Helvetica Neue', Arial, sans-serif;\n  line-height: 1.2;\n  margin: 1.4em 0 0.5em;\n}\nh1 { font-size: 1.8em; }\nh2 { font-size: 1.4em; }\nh3 { font-size: 1.2em; }\np { margin: 0.6em 0; }\na { color: #08c; text-decoration: none; }\nul, ol { margin: 0.6em 0; padding-left: 1.4em; }\nblockquote {\n  margin: 0.8em 0;\n  padding: 0 0 0 1em;\n  border-left: 3px solid #ccc;\n  color: #555;\n}\nimg { max-width: 100%; height: auto; }\ntable { border-collapse: collapse; margin: 0.8em 0; font-size: 0.85em; }\nth, td { border: 1px solid #ccc; padding: 0.3em 0.6em; text-align: left; }\ncode, pre {\n  font-family: 'SF Mono', Menlo, Consolas, monospace;\n  font-size: 0.8em;\n}\n:not(pre) > code {\n  background: #f3f3f3;\n  padding: 0.1em 0.3em;\n  border-radius: 3px;\n}\npre {\n  background: #f6f8fa;\n  border: 1px solid #e1e4e8;\n  border-radius: 4px;\n  padding: 0.7em 0.9em;\n  margin: 0.8em 0;\n  white-space: pre-wrap;\n  word-break: break-word;\n  overflow-wrap: anywhere;\n}\npre code { background: none; padding: 0; }\n/* the in-flow Contents page (ePub spine TOC) */\n.toc-title { text-align: center; }\nol.toc, ol.toc ol { list-style: none; padding-left: 0; }\nol.toc ol { padding-left: 1.2em; }\nol.toc li { margin: 0.3em 0; }\nol.toc > li > a { font-weight: bold; }\n/* per-example \"run this live\" deep link */\n.example-live-link { margin: 0.6em 0 0; font-size: 0.85em; }\n.example-live-link a { color: #08c; font-weight: bold; }\n";
+export declare const PRINT_CSS = "\n@page { margin: 18mm 16mm; }\n.book-title { text-align: center; margin: 30vh 0 1em; }\n.book-toc { page-break-after: always; }\n.book-toc h2 { page-break-before: avoid; }\n.book-toc ol { list-style: none; padding-left: 0; }\n.book-toc ol ol { padding-left: 1.2em; }\n.book-toc a { color: inherit; }\n.chapter { page-break-before: always; }\n";
+export declare function escapeHtml(s: string): string;
+export declare function slugify(s: string): string;
+/** Drop the `<!--{ … }-->` metadata directives the extractor leaves in the text. */
+export declare function stripDocMeta(text: string): string;
+/** Flatten a nav-tree depth-first into reading order. */
+export declare function flatten<T extends NavDoc>(nodes: NavNode<T>[]): NavNode<T>[];
+export interface BookHtmlOptions {
+    title: string;
+    /** full stylesheet (defaults to DEFAULT_BOOK_CSS + PRINT_CSS) */
+    css?: string;
+    lang?: string;
+    /** inject a script that opens the print dialog once the page has loaded */
+    autoPrint?: boolean;
+}
+/** Assemble the whole corpus into one self-contained printable HTML document. */
+export declare function buildBookHtml(docs: BookDoc[], opts: BookHtmlOptions): string;

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

@@ -0,0 +1,129 @@
+/*
+Shared, browser-safe assembly of the whole doc corpus into one printable HTML
+"book": a title page, a generated table of contents, then every doc as a chapter
+that starts on a new page. Used by the client-side **Print** button in the
+doc-browser (the user's browser prints it to PDF) and by the headless PDF builder
+(site/pdf.ts). Pure rendering — no fs, no Node-only APIs — so it bundles into the
+iife. Live examples are pretty-printed, force-wrapped code listings, not executed.
+*/
+import { renderDocMarkdown } from './render';
+import { buildSlugMap } from './routing';
+import { buildNavTree } from './nav-tree';
+// Clean book typography; force-wraps code so listings never overflow a page.
+export const DEFAULT_BOOK_CSS = `/* doc-system book stylesheet */
+html { font-size: 100%; }
+body {
+  font-family: Georgia, 'Times New Roman', serif;
+  line-height: 1.5;
+  margin: 0 1em;
+  color: #1a1a1a;
+}
+h1, h2, h3, h4, h5, h6 {
+  font-family: -apple-system, 'Helvetica Neue', Arial, sans-serif;
+  line-height: 1.2;
+  margin: 1.4em 0 0.5em;
+}
+h1 { font-size: 1.8em; }
+h2 { font-size: 1.4em; }
+h3 { font-size: 1.2em; }
+p { margin: 0.6em 0; }
+a { color: #08c; text-decoration: none; }
+ul, ol { margin: 0.6em 0; padding-left: 1.4em; }
+blockquote {
+  margin: 0.8em 0;
+  padding: 0 0 0 1em;
+  border-left: 3px solid #ccc;
+  color: #555;
+}
+img { max-width: 100%; height: auto; }
+table { border-collapse: collapse; margin: 0.8em 0; font-size: 0.85em; }
+th, td { border: 1px solid #ccc; padding: 0.3em 0.6em; text-align: left; }
+code, pre {
+  font-family: 'SF Mono', Menlo, Consolas, monospace;
+  font-size: 0.8em;
+}
+:not(pre) > code {
+  background: #f3f3f3;
+  padding: 0.1em 0.3em;
+  border-radius: 3px;
+}
+pre {
+  background: #f6f8fa;
+  border: 1px solid #e1e4e8;
+  border-radius: 4px;
+  padding: 0.7em 0.9em;
+  margin: 0.8em 0;
+  white-space: pre-wrap;
+  word-break: break-word;
+  overflow-wrap: anywhere;
+}
+pre code { background: none; padding: 0; }
+/* the in-flow Contents page (ePub spine TOC) */
+.toc-title { text-align: center; }
+ol.toc, ol.toc ol { list-style: none; padding-left: 0; }
+ol.toc ol { padding-left: 1.2em; }
+ol.toc li { margin: 0.3em 0; }
+ol.toc > li > a { font-weight: bold; }
+/* per-example "run this live" deep link */
+.example-live-link { margin: 0.6em 0 0; font-size: 0.85em; }
+.example-live-link a { color: #08c; font-weight: bold; }
+`;
+// Print-only layout: page margins, a chapter per page, an avoid-break TOC.
+export const PRINT_CSS = `
+@page { margin: 18mm 16mm; }
+.book-title { text-align: center; margin: 30vh 0 1em; }
+.book-toc { page-break-after: always; }
+.book-toc h2 { page-break-before: avoid; }
+.book-toc ol { list-style: none; padding-left: 0; }
+.book-toc ol ol { padding-left: 1.2em; }
+.book-toc a { color: inherit; }
+.chapter { page-break-before: always; }
+`;
+export function escapeHtml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+export function slugify(s) {
+    return s.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
+}
+/** Drop the `<!--{ … }-->` metadata directives the extractor leaves in the text. */
+export function stripDocMeta(text) {
+    return text.replace(/<!--\{[\s\S]*?\}-->\s*/g, '');
+}
+/** Flatten a nav-tree depth-first into reading order. */
+export function flatten(nodes) {
+    const out = [];
+    for (const node of nodes) {
+        out.push(node);
+        out.push(...flatten(node.children));
+    }
+    return out;
+}
+function tocHtml(nodes) {
+    return nodes
+        .map((node) => `<li><a href="#${slugify(node.doc.filename)}">${escapeHtml(node.doc.title)}</a>${node.children.length ? `<ol>${tocHtml(node.children)}</ol>` : ''}</li>`)
+        .join('');
+}
+/** Assemble the whole corpus into one self-contained printable HTML document. */
+export function buildBookHtml(docs, opts) {
+    const visible = docs.filter((d) => !d.hidden);
+    const slugMap = buildSlugMap(visible);
+    const roots = buildNavTree(visible, slugMap);
+    const css = opts.css ?? `${DEFAULT_BOOK_CSS}\n${PRINT_CSS}`;
+    const chapters = flatten(roots)
+        .map((node) => `<section class="chapter" id="${slugify(node.doc.filename)}">\n${renderDocMarkdown(stripDocMeta(node.doc.text))}\n</section>`)
+        .join('\n');
+    return `<!DOCTYPE html>
+<html lang="${opts.lang ?? 'en'}">
+<head>
+<meta charset="utf-8"/>
+<title>${escapeHtml(opts.title)}</title>
+<style>${css}</style>
+</head>
+<body>
+<h1 class="book-title">${escapeHtml(opts.title)}</h1>
+<nav class="book-toc"><h2>Contents</h2><ol>${tocHtml(roots)}</ol></nav>
+${chapters}
+${opts.autoPrint ? '<script>addEventListener("load",function(){setTimeout(function(){print()},300)})</script>' : ''}
+</body>
+</html>`;
+}

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

@@ -59,6 +59,7 @@ A self-contained, controllable embed (e.g. docs in a floating panel):
 import { Component, StyleSheet, elements, tosi, vars } from 'tosijs';
 import { createDocBrowser } from '../doc-browser';
 import { buildSlugMap, legacyQueryPath } from './routing';
+import { buildBookHtml, slugify } from './book-html';
 import { docSystemStyleSpec } from './doc-system-styles';
 import { icons } from '../icons';
 import { popMenu } from '../menu';
@@ -204,6 +205,43 @@ export class TosiDocSystem extends Component {
             title: 'settings',
             onClick: (event) => {
                 const menuItems = [];
+                // Print / ePub of the whole corpus, before a separator + the prefs.
+                let projectName = '';
+                try {
+                    projectName = JSON.parse(this.config || '{}').projectName || '';
+                }
+                catch {
+                    // ignore — fall through to document.title
+                }
+                const bookTitle = projectName || document.title || 'Documentation';
+                menuItems.push({
+                    caption: 'Print as PDF',
+                    icon: 'printer',
+                    action: () => {
+                        const win = window.open('', '_blank');
+                        if (!win) {
+                            window.alert('Allow pop-ups to print the documentation as a book.');
+                            return;
+                        }
+                        win.document.open();
+                        win.document.write(buildBookHtml(this.corpus, {
+                            title: bookTitle,
+                            autoPrint: true,
+                        }));
+                        win.document.close();
+                    },
+                });
+                menuItems.push({
+                    caption: 'Download ePub',
+                    icon: 'book',
+                    action: () => {
+                        const link = document.createElement('a');
+                        link.href = `/${slugify(bookTitle)}.epub`;
+                        link.download = '';
+                        link.click();
+                    },
+                });
+                menuItems.push(null);
                 const localeOptions = i18n.localeOptions.value || [];
                 if (localeOptions.length > 1) {
                     menuItems.push({

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

@@ -1,5 +1,3 @@
-import { MarkedOptions } from 'marked';
-export declare const docMarkedOptions: MarkedOptions;
 /** Render a doc's markdown text to HTML (synchronous, default marked options). */
 export declare function renderDocMarkdown(text: string): string;
 /**

package/dist/doc-system/render.js

@@ -1,18 +1,40 @@
 /*
 Shared markdown rendering for the static doc system.
 
-`renderDocMarkdown` MUST stay in lockstep with how <tosi-md> renders doc text
-(see src/markdown-viewer.ts: `marked(source, this.options)` with default options),
-so the build-time pre-render is byte-identical to what the component would produce
-on the client. Fenced code blocks are left as <pre><code class="language-*"> so the
-static page shows readable, indexable code AND the component can later upgrade
-consecutive blocks into <live-example> widgets via insertExamples().
+Both the build-time pre-render and the client (doc-browser) call THIS function, so
+the static page hydrates byte-identically. Fenced code blocks are left as
+<pre><code class="language-*"> so the static page shows readable, indexable code
+AND the component can later upgrade consecutive blocks into <live-example> widgets
+via insertExamples(). A fence info string may carry a `#id` (```js#my-example) to
+give that example a stable anchor — see the docMarked renderer below.
 */
-import { marked } from 'marked';
-export const docMarkedOptions = {};
+import { Marked, Renderer } from 'marked';
+const baseRenderer = new Renderer();
+// A doc-scoped marked instance. Its ONLY customization: a fenced code block whose
+// info string carries a `#id` suffix — e.g. ```js#my-example — renders the lang
+// clean (`language-js`, so all existing grouping/highlighting is unaffected) but
+// stamps `data-example-id="my-example"` on the <pre>. insertExamples (client) and
+// the book builders both read that to give the live example a stable anchor for
+// deep-linking. A block with no `#id` is byte-identical to default marked output.
+const docMarked = new Marked();
+docMarked.use({
+    renderer: {
+        code(token) {
+            const info = String(token.lang || '');
+            const hash = info.indexOf('#');
+            if (hash === -1)
+                return false; // default rendering
+            const id = info.slice(hash + 1).match(/^[A-Za-z0-9_-]+/)?.[0];
+            if (!id)
+                return false;
+            const html = baseRenderer.code({ ...token, lang: info.slice(0, hash) });
+            return html.replace(/^<pre>/, `<pre data-example-id="${id}">`);
+        },
+    },
+});
 /** Render a doc's markdown text to HTML (synchronous, default marked options). */
 export function renderDocMarkdown(text) {
-    return marked(text, docMarkedOptions);
+    return docMarked.parse(text);
 }
 /**
  * Derive a clean <meta name="description"> from a doc's first prose paragraph.

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

@@ -0,0 +1,50 @@
+import type { SiteConfig } from './site-config';
+import { DEFAULT_BOOK_CSS, stripDocMeta } from '../book-html';
+export { DEFAULT_BOOK_CSS, stripDocMeta };
+declare global {
+    var Bun: any;
+}
+export interface BookMeta {
+    title: string;
+    author: string;
+    language: string;
+    /** unique identifier (a URL or urn:) */
+    identifier: string;
+    /** dcterms:modified timestamp, e.g. 2026-06-28T00:00:00Z */
+    modified: string;
+}
+export interface BuildEpubOptions {
+    /** corpus path; default config.docsJson ?? 'demo/docs.json' */
+    docsJson?: string;
+    /** output .epub path; default `${outputDir}/${slug(name)}.epub` */
+    output?: string;
+    /** book title; default config.name */
+    title?: string;
+    /** author / publisher line */
+    author?: string;
+    /** BCP-47 language; default 'en' */
+    language?: string;
+    /** override the whole book stylesheet */
+    css?: string;
+    /** extra CSS appended to the default stylesheet (ignored if `css` is set) */
+    extraCss?: string;
+    /** ISO timestamp for dcterms:modified; default now (seconds precision) */
+    modified?: string;
+    /**
+     * Cover image path (png/jpeg/gif). If omitted, a cover is generated from the
+     * book title + the site favicon (rasterized to PNG via @resvg/resvg-js).
+     */
+    cover?: string;
+    /** background color for the generated cover, default '#1f2933' */
+    coverColor?: string;
+}
+export declare function escapeXml(s: string): string;
+/**
+ * Best-effort normalize marked's HTML output to well-formed XHTML: self-close
+ * void elements and escape bare `&` that isn't already part of an entity.
+ */
+export declare function toXhtml(html: string): string;
+/**
+ * Build an EPUB 3 book from the extracted corpus. Returns the output path.
+ */
+export declare function buildEpub(config: SiteConfig, opts?: BuildEpubOptions): Promise<string>;