@imontene/mdrender 2.0.0 → 2.2.0

package/dist/render/mermaid-fit.js

@@ -0,0 +1,135 @@
+/**
+ * Autofit for Mermaid flowcharts: pick, among several layouts of the same diagram, the one whose
+ * text prints largest once the diagram is scaled to the text column and the page height.
+ *
+ * Mermaid wraps label lines at `flowchart.wrappingWidth`, and a flowchart laid out along one axis
+ * can be far wider (or taller) than the page; the theme then shrinks the whole drawing, text
+ * included. Wider wrapping makes tall diagrams shorter; turning a long left-to-right chain
+ * top-to-bottom makes it fit the column. Neither has one value that suits every diagram, so each
+ * flowchart is rendered a few times and measured. Everything here is pure; the rendering loop is
+ * in render/mermaid.ts.
+ */
+export const FLOW_DIRECTIONS = ["TB", "TD", "BT", "LR", "RL"];
+/** Label wrapping widths tried, in px; undefined is Mermaid's own default (the layout as today). */
+export const WRAPPING_WIDTHS = [
+    undefined,
+    200,
+    300,
+    400,
+    600,
+    900,
+];
+/** Candidates within this scale of the best one read the same; the shorter one wins. */
+export const SCALE_TOLERANCE = 0.05;
+/** Only turn a diagram whose best scale in its own direction is below this (text under ~10 px)… */
+export const FLIP_BELOW = 0.75;
+/** …and only when turning it raises the scale by at least this much. */
+export const FLIP_GAIN = 0.15;
+/** Below this scale the diagram is reported: no layout makes it readable, its content must change. */
+export const SMALL_SCALE = 0.5;
+/** The axis-swapped direction: horizontal flowcharts go top-to-bottom, vertical ones left-to-right. */
+const FLIPPED = {
+    LR: "TB",
+    RL: "TB",
+    TB: "LR",
+    TD: "LR",
+    BT: "LR",
+};
+const HEADER = /^(\s*(?:flowchart|graph))(?:[ \t]+(TB|TD|BT|LR|RL))?(?=\s|;|$)/i;
+/** Lines of the diagram after Mermaid's optional front matter (`---` … `---`). */
+function bodyStart(lines) {
+    if (lines[0]?.trim() !== "---")
+        return 0;
+    const end = lines.findIndex((line, i) => i > 0 && line.trim() === "---");
+    return end === -1 ? 0 : end + 1;
+}
+/**
+ * The flowchart's header line and main direction, or undefined when the source is another kind
+ * of diagram. Blank lines and `%%` comments before the header are skipped.
+ */
+export function flowchartHeader(source) {
+    const lines = source.split("\n");
+    for (let i = bodyStart(lines); i < lines.length; i++) {
+        const text = lines[i].trim();
+        if (text === "" || text.startsWith("%%"))
+            continue;
+        const match = HEADER.exec(lines[i]);
+        if (!match)
+            return undefined;
+        const direction = (match[2]?.toUpperCase() ?? "TB");
+        return { line: i, direction };
+    }
+    return undefined;
+}
+/** The source with its main direction replaced; subgraph directions are left alone. */
+export function withDirection(source, header, direction) {
+    const lines = source.split("\n");
+    lines[header.line] = lines[header.line].replace(HEADER, (_m, keyword) => `${keyword} ${direction}`);
+    return lines.join("\n");
+}
+export function flippedDirection(direction) {
+    return FLIPPED[direction];
+}
+/**
+ * The diagram sets its own Mermaid configuration (an `%%{init: …}%%` directive or `config:` in
+ * its front matter): it is drawn exactly as written.
+ */
+export function authorConfigured(source) {
+    if (/%%\{\s*(?:init|initialize)\b/i.test(source))
+        return true;
+    const lines = source.split("\n");
+    const start = bodyStart(lines);
+    return start > 0 && lines.slice(1, start - 1).some((line) => /^\s*config\s*:/.test(line));
+}
+/** Width and height of an SVG from its viewBox. */
+export function measureSvg(svg) {
+    const match = /viewBox="\s*[-\d.e]+[\s,]+[-\d.e]+[\s,]+([\d.e]+)[\s,]+([\d.e]+)\s*"/.exec(svg);
+    if (!match)
+        return undefined;
+    const width = Number(match[1]);
+    const height = Number(match[2]);
+    return width > 0 && height > 0 ? { width, height } : undefined;
+}
+/** How much the diagram is shrunk when printed: 1 is its natural size. */
+export function printScale(size, fit) {
+    return Math.min(1, fit.width / size.width, fit.height / size.height);
+}
+export function candidate(svg, wrap, flipped, fit) {
+    const size = measureSvg(svg);
+    return size && { svg, wrap, flipped, ...size, scale: printScale(size, fit) };
+}
+const printedHeight = (c) => Math.round(c.height * c.scale);
+/**
+ * Best of one direction's candidates: those within SCALE_TOLERANCE of the top scale and never
+ * below the layout as written (`base`), then the shortest printed, then the largest scale.
+ */
+function bestOf(candidates, base) {
+    const top = Math.max(...candidates.map((c) => c.scale));
+    return candidates
+        .filter((c) => c.scale >= top - SCALE_TOLERANCE && c.scale >= base.scale - 1e-9)
+        .sort((a, b) => printedHeight(a) - printedHeight(b) || b.scale - a.scale)[0];
+}
+/** Whether a turned layout is worth trying, given the best layout in the written direction. */
+export const flipWorthTrying = (best) => best.scale < FLIP_BELOW - 1e-9;
+/**
+ * The chosen layout. `base` is the diagram as written (Mermaid's default wrapping, its own
+ * direction); the result is never smaller than it. A turned layout wins only when the written
+ * direction stays below FLIP_BELOW and turning gains at least FLIP_GAIN.
+ */
+export function chooseCandidate(candidates, base) {
+    const written = bestOf(candidates.filter((c) => !c.flipped), base);
+    const best = written ?? base;
+    const turned = candidates.filter((c) => c.flipped);
+    if (turned.length === 0 || !flipWorthTrying(best))
+        return best;
+    const flipped = bestOf(turned, base);
+    return flipped && flipped.scale >= best.scale + FLIP_GAIN - 1e-9 ? flipped : best;
+}
+/**
+ * Whether wider wrapping in this direction can still help: once the diagram is wider than the
+ * column and its scale went down, wider labels only make it wider.
+ */
+export function wrapsExhausted(current, previous, fit) {
+    return previous !== undefined && current.width > fit.width && current.scale < previous.scale;
+}
+//# sourceMappingURL=mermaid-fit.js.map

package/dist/render/mermaid.d.ts

@@ -1,20 +1,54 @@
 import type { Diagnostic } from "../diagnostics.js";
 import type { MermaidBlock } from "../markdown/env.js";
-import type { MermaidTheme } from "../options.js";
+import type { MermaidFlip, MermaidTheme } from "../options.js";
 import type { BrowserSession } from "./browser.js";
 export { MERMAID_THEMES, type MermaidTheme } from "../options.js";
-type DiagramResult = {
+/** How autofit laid out a flowchart (see render/mermaid-fit.ts). */
+export interface DiagramLayout {
+    /** Label wrapping width in px; undefined is Mermaid's default. */
+    wrap: number | undefined;
+    /** Main direction turned to the other axis, e.g. "LR→TB"; undefined when kept. */
+    turned?: string;
+    /** Printed scale and height (CSS px) as written and as chosen. */
+    baseScale: number;
+    scale: number;
+    baseHeight: number;
+    height: number;
+    /** Layouts rendered to choose this one. */
+    tried: number;
+}
+export type DiagramResult = {
     svg: string;
+    /** Printed scale (1 = natural size), when the SVG could be measured. */
+    scale?: number;
+    /** Set for flowcharts considered by autofit. */
+    layout?: DiagramLayout;
 } | {
     error: string;
 };
+export interface MermaidRenderOptions {
+    theme?: MermaidTheme;
+    /** Width of the text column, so diagrams are laid out at their printed size. */
+    widthPx?: number;
+    /** Text size of the document in CSS pixels, so diagram labels match the body text. */
+    fontPx?: number;
+    /** Tallest a diagram may print (the page's text height), in CSS px; Infinity for HTML. */
+    pageHeightPx?: number;
+    /** Search label wrapping widths (and, with `flip`, the other axis) for each flowchart. */
+    autofit?: boolean;
+    flip?: MermaidFlip;
+}
+/**
+ * Room kept for a heading printed together with the diagram below it (see keep-with-heading in
+ * theme.css, where the same allowance is subtracted), in multiples of the text size.
+ */
+export declare const HEADING_ALLOWANCE_EM = 5;
 /**
  * Render Mermaid diagrams to SVG in a blank page that holds no user content: only the diagram
- * sources are passed in, as data. Mermaid runs with `securityLevel: "strict"`.
+ * sources are passed in, as data. Mermaid runs with `securityLevel: "strict"`. With `autofit`,
+ * flowcharts are rendered in several layouts and the one whose text prints largest is kept.
  */
-export declare function renderMermaid(session: BrowserSession, blocks: MermaidBlock[], theme?: MermaidTheme, 
-/** Width of the text column, so diagrams are laid out at their printed size. */
-widthPx?: number): Promise<DiagramResult[]>;
+export declare function renderMermaid(session: BrowserSession, blocks: MermaidBlock[], options?: MermaidRenderOptions): Promise<DiagramResult[]>;
 /**
  * Replace the Mermaid placeholders in `html` with rendered SVGs, or with a visible error box.
  * Returns the new HTML and one error diagnostic per failed diagram.

package/dist/render/mermaid.js

@@ -2,17 +2,40 @@ import { MERMAID_JS, readTextAsset } from "../assets.js";
 import { mermaidPlaceholder } from "../markdown/mermaid.js";
 import { fontFaceCss } from "./fonts.js";
 import { escapeHtml } from "../html.js";
+import { authorConfigured, candidate, chooseCandidate, flipWorthTrying, flippedDirection, flowchartHeader, withDirection, WRAPPING_WIDTHS, wrapsExhausted, } from "./mermaid-fit.js";
 export { MERMAID_THEMES } from "../options.js";
 /** Width of the text column on A4 with 20 mm margins. */
 const DEFAULT_WIDTH_PX = 642;
+/** 10.5pt, the built-in themes' text size (Mermaid's own default is 16px). */
+const DEFAULT_FONT_PX = 14;
+/**
+ * Room kept for a heading printed together with the diagram below it (see keep-with-heading in
+ * theme.css, where the same allowance is subtracted), in multiples of the text size.
+ */
+export const HEADING_ALLOWANCE_EM = 5;
 let mermaidJs;
+function mermaidConfig(theme, fontPx, wrap) {
+    return {
+        startOnLoad: false,
+        securityLevel: "strict",
+        theme,
+        fontFamily: "Inter, sans-serif",
+        // Sequence diagrams take their text sizes from here, the others from themeVariables.
+        fontSize: fontPx,
+        themeVariables: { fontFamily: "Inter, sans-serif", fontSize: `${fontPx}px` },
+        htmlLabels: true,
+        // Actors only at the top of sequence diagrams: repeating them below costs height.
+        sequence: { mirrorActors: false },
+        ...(wrap === undefined ? {} : { flowchart: { wrappingWidth: wrap } }),
+    };
+}
 /**
  * Render Mermaid diagrams to SVG in a blank page that holds no user content: only the diagram
- * sources are passed in, as data. Mermaid runs with `securityLevel: "strict"`.
+ * sources are passed in, as data. Mermaid runs with `securityLevel: "strict"`. With `autofit`,
+ * flowcharts are rendered in several layouts and the one whose text prints largest is kept.
  */
-export async function renderMermaid(session, blocks, theme = "neutral", 
-/** Width of the text column, so diagrams are laid out at their printed size. */
-widthPx = DEFAULT_WIDTH_PX) {
+export async function renderMermaid(session, blocks, options = {}) {
+    const { theme = "neutral", widthPx = DEFAULT_WIDTH_PX, fontPx = DEFAULT_FONT_PX, pageHeightPx = Infinity, autofit = true, flip = "auto", } = options;
     mermaidJs ??= readTextAsset(MERMAID_JS);
     const page = await session.newPage();
     try {
@@ -20,31 +43,85 @@ widthPx = DEFAULT_WIDTH_PX) {
 body { margin: 0; width: ${widthPx}px; font-family: "Inter", sans-serif; }</style>
 </head><body></body></html>`);
         await page.evaluate(mermaidJs);
-        return await page.evaluate(async (sources, theme) => {
+        await page.evaluate(async () => {
             // Runs in the browser. The project is compiled without DOM types, hence PageGlobals.
-            const { document, mermaid } = globalThis;
+            const { document } = globalThis;
             // Load the font weights Mermaid uses before it measures any text.
             await Promise.all(["400", "600", "700"].map((w) => document.fonts.load(`${w} 16px Inter`)));
-            mermaid.initialize({
-                startOnLoad: false,
-                securityLevel: "strict",
-                theme,
-                fontFamily: "Inter, sans-serif",
-                themeVariables: { fontFamily: "Inter, sans-serif" },
-                htmlLabels: true,
-            });
-            const results = [];
-            for (const [i, source] of sources.entries()) {
-                try {
-                    const { svg } = await mermaid.render(`mermaid-${i + 1}`, source);
-                    results.push({ svg });
-                }
-                catch (error) {
-                    results.push({ error: String(error?.message ?? error) });
+        });
+        const render = (source, id, wrap) => page.evaluate(async (source, id, config) => {
+            const { mermaid } = globalThis;
+            // Each render sets the whole configuration, so one layout never leaks into the next.
+            mermaid.initialize(config);
+            try {
+                return { svg: (await mermaid.render(id, source)).svg };
+            }
+            catch (error) {
+                return { error: String(error?.message ?? error) };
+            }
+        }, source, id, mermaidConfig(theme, fontPx, wrap));
+        const results = [];
+        for (const [i, block] of blocks.entries()) {
+            const id = `mermaid-${i + 1}`;
+            const fit = {
+                width: widthPx,
+                height: block.afterHeading ? pageHeightPx - HEADING_ALLOWANCE_EM * fontPx : pageHeightPx,
+            };
+            const written = await render(block.source, id, undefined);
+            if ("error" in written) {
+                results.push(written);
+                continue;
+            }
+            const base = candidate(written.svg, undefined, false, fit);
+            const header = flowchartHeader(block.source);
+            if (!autofit || !base || !header || authorConfigured(block.source)) {
+                results.push({ svg: written.svg, scale: base?.scale });
+                continue;
+            }
+            let tried = 1;
+            const candidates = [base];
+            const tryWraps = async (source, flipped) => {
+                let previous = flipped ? undefined : base;
+                for (const wrap of WRAPPING_WIDTHS) {
+                    if (!flipped && wrap === undefined)
+                        continue; // that is `base`
+                    const rendered = await render(source, `${id}-${tried}`, wrap);
+                    tried++;
+                    if ("error" in rendered)
+                        continue;
+                    const next = candidate(rendered.svg, wrap, flipped, fit);
+                    if (!next)
+                        continue;
+                    candidates.push(next);
+                    if (wrapsExhausted(next, previous, fit))
+                        break;
+                    previous = next;
                 }
+            };
+            await tryWraps(block.source, false);
+            let chosen = chooseCandidate(candidates, base);
+            const turnedTo = flippedDirection(header.direction);
+            if (flip === "auto" && flipWorthTrying(chosen)) {
+                await tryWraps(withDirection(block.source, header, turnedTo), true);
+                chosen = chooseCandidate(candidates, base);
             }
-            return results;
-        }, blocks.map((b) => b.source), theme);
+            // Candidate ids ("mermaid-2-3") stay unique in the document, and its styles are scoped
+            // to that id, so the chosen SVG is used as rendered.
+            results.push({
+                svg: chosen.svg,
+                scale: chosen.scale,
+                layout: {
+                    wrap: chosen.wrap,
+                    turned: chosen.flipped ? `${header.direction}→${turnedTo}` : undefined,
+                    baseScale: base.scale,
+                    scale: chosen.scale,
+                    baseHeight: Math.round(base.height * base.scale),
+                    height: Math.round(chosen.height * chosen.scale),
+                    tried,
+                },
+            });
+        }
+        return results;
     }
     finally {
         await page.close();

package/dist/render/page.d.ts

@@ -5,3 +5,8 @@ export declare function contentWidthPx(pageSize: PageSize, landscape: boolean, m
     left: string;
     right: string;
 }): number;
+/** Height of the text area in CSS pixels: the paper minus the top and bottom margins. */
+export declare function contentHeightPx(pageSize: PageSize, landscape: boolean, margin: {
+    top: string;
+    bottom: string;
+}): number;

package/dist/render/page.js

@@ -20,4 +20,10 @@ export function contentWidthPx(pageSize, landscape, margin) {
     const paperPx = ((landscape ? height : width) * 96) / 25.4;
     return Math.round(paperPx - lengthToPx(margin.left) - lengthToPx(margin.right));
 }
+/** Height of the text area in CSS pixels: the paper minus the top and bottom margins. */
+export function contentHeightPx(pageSize, landscape, margin) {
+    const [width, height] = PAPER_MM[pageSize];
+    const paperPx = ((landscape ? width : height) * 96) / 25.4;
+    return Math.round(paperPx - lengthToPx(margin.top) - lengthToPx(margin.bottom));
+}
 //# sourceMappingURL=page.js.map

package/dist/render/template.d.ts

@@ -2,6 +2,8 @@ import { escapeHtml } from "../html.js";
 export { escapeHtml };
 /** Stylesheets of a built-in theme ("light" or "dark"). */
 export declare function builtinThemeCss(theme: "light" | "dark"): string[];
+/** Stylesheet for a density other than "normal", applied after the theme. */
+export declare function densityCss(density: "normal" | "compact"): string[];
 export interface DocumentParts {
     title: string;
     body: string;
@@ -15,7 +17,9 @@ export interface DocumentParts {
     showTitle?: boolean;
     /** Theme stylesheet contents. Defaults to the built-in light theme. */
     themeCss?: string[];
-    /** Extra stylesheet contents, applied after the theme. */
+    /** Layout stylesheets (density, font size, page height), applied after the theme. */
+    layoutCss?: string[];
+    /** Extra stylesheet contents, applied after the theme and layout. */
     extraCss?: string[];
 }
 /** Wrap a rendered Markdown fragment in a complete, self-contained HTML document. */

package/dist/render/template.js

@@ -17,6 +17,10 @@ function asset(name) {
 export function builtinThemeCss(theme) {
     return theme === "dark" ? [asset("theme.css"), asset("theme-dark.css")] : [asset("theme.css")];
 }
+/** Stylesheet for a density other than "normal", applied after the theme. */
+export function densityCss(density) {
+    return density === "compact" ? [asset("density-compact.css")] : [];
+}
 function titleBlock({ title, subtitle, author, date }) {
     const meta = [author, date].filter(Boolean).map((part) => escapeHtml(part));
     return [
@@ -31,9 +35,15 @@ function titleBlock({ title, subtitle, author, date }) {
 }
 /** Wrap a rendered Markdown fragment in a complete, self-contained HTML document. */
 export function buildHtmlDocument(parts) {
-    const { title, body, math = false, lang, author, extraCss = [] } = parts;
+    const { title, body, math = false, lang, author, layoutCss = [], extraCss = [] } = parts;
     const themeCss = parts.themeCss ?? builtinThemeCss("light");
-    const styles = [fontFaceCss(), ...(math ? [katexCss()] : []), ...themeCss, ...extraCss];
+    const styles = [
+        fontFaceCss(),
+        ...(math ? [katexCss()] : []),
+        ...themeCss,
+        ...layoutCss,
+        ...extraCss,
+    ];
     return `<!doctype html>
 <html${lang ? ` lang="${escapeHtml(lang)}"` : ""}>
 <head>

package/dist/run.js

@@ -26,6 +26,12 @@ export async function runJob(job, format, settings, browsers, io) {
         }
         if (io.verbose && result.configFile)
             io.err(`config: ${result.configFile}\n`);
+        if (io.verbose) {
+            for (const note of result.notes) {
+                const location = [displayPath(job.input), note.line].filter((p) => p !== undefined);
+                io.err(`${location.join(":")}: ${note.message}\n`);
+            }
+        }
         if (!io.quiet)
             io.out(`${result.output}\n`);
         if (io.verbose)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@imontene/mdrender",
-  "version": "2.0.0",
+  "version": "2.2.0",
   "description": "Command-line app for Windows and Linux that renders Markdown — with LaTeX equations and Mermaid diagrams — to PDF and HTML using the Inter typeface",
   "keywords": [
     "markdown",
@@ -60,7 +60,8 @@
     "check": "npm run format:check && npm run lint && npm run typecheck && npm test",
     "build:exe": "npm run build && node scripts/build-sea.mjs",
     "prepublishOnly": "npm run check && npm run build",
-    "test:coverage": "vitest run --coverage"
+    "test:coverage": "vitest run --coverage",
+    "bench:mermaid": "tsx tests/bench/mermaid-autofit.ts"
   },
   "dependencies": {
     "@fontsource/jetbrains-mono": "^5.3.0",