npm - pantsdown - Versions diffs - 2.2.8 → 2.3.0 - Mend

pantsdown 2.2.8 → 2.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (8) hide show

package/README.md CHANGED Viewed

@@ -148,13 +148,47 @@ const config: PartialPantsdownConfig = {
        * false
        */
       detailsTagDefaultOpen: boolean;
+      /**
+       * Interactive controls added to rendered mermaid diagrams.
+       */
+      mermaid: {
+         /**
+          * Control buttons overlaid on the diagram.
+          * Set individual buttons to `false` to hide them.
+          *
+          * @default
+          * { zoom: true, reset: true, arrows: true, popover: true }
+          */
+         buttons: {
+            /** Zoom in & zoom out buttons */
+            zoom: boolean;
+            /** Reset zoom & pan to the initial position */
+            reset: boolean;
+            /** Directional pan arrows */
+            arrows: boolean;
+            /** Open the diagram in a fullscreen popover */
+            popover: boolean;
+         };
+         /**
+          * Enable cmd/ctrl + drag to pan and cmd/ctrl + scroll to zoom.
+          * Plain click & scroll are never captured, so text selection
+          * and page scrolling keep working. Inside the popover, plain
+          * drag pans and plain scroll zooms regardless of this setting.
+          *
+          * @default
+          * true
+          */
+         mouseActions: boolean;
+      };
    };
 };
 const pantsdown = new Pantsdown(config);
-const html = pantsdown.parse(markdown);
+const { html, javascript } = pantsdown.parse(markdown);
-console.log(html);
+console.log(html, javascript);
 ```
 ## 🤝 Acknowledgements

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "pantsdown",
-  "version": "2.2.8",
+  "version": "2.3.0",
   "description": "Markdown to 'GitHub HTML' parser",
   "license": "MIT",
   "author": "wallpants",
@@ -38,21 +38,21 @@
   "dependencies": {
     "github-slugger": "^2.0.0",
     "highlight.js": "^11.11.1",
-    "katex": "^0.18.0"
+    "katex": "^0.18.1"
   },
   "devDependencies": {
     "@commitlint/cli": "^21.2.1",
     "@commitlint/config-conventional": "^21.2.0",
     "@commitlint/cz-commitlint": "^21.2.0",
-    "@happy-dom/global-registrator": "^20.11.0",
+    "@happy-dom/global-registrator": "^20.11.1",
     "@types/bun": "^1.3.14",
     "@types/katex": "^0.16.8",
     "commitizen": "^4.3.2",
     "husky": "^9.1.7",
     "inquirer": "^12.11.1",
-    "oxfmt": "^0.59.0",
-    "oxlint": "^1.73.0",
-    "oxlint-tsgolint": "^0.25.0",
+    "oxfmt": "^0.62.0",
+    "oxlint": "^1.77.0",
+    "oxlint-tsgolint": "^7.0.2001",
     "semantic-release": "^25.0.8",
     "typescript": "7.0.2"
   },

package/src/css/styles.css CHANGED Viewed

@@ -203,6 +203,85 @@
    margin-bottom: 16px;
 }
+.pantsdown .mermaid-viewport {
+   overflow: hidden;
+}
+/* swallow the pre's padding and restore it as the viewport's own: the resting
+   layout is unchanged, but overflow clips at the padding box, so panned
+   content reaches the container edge (like github) instead of dying 16px short */
+.pantsdown pre .mermaid-viewport {
+   margin: -16px;
+   padding: 16px;
+}
+.pantsdown .mermaid-canvas {
+   transform-origin: 0 0;
+}
+/* second selector covers consumers where <html> itself is the .pantsdown root */
+html.pantsdown-mermaid-mod .pantsdown .mermaid-viewport,
+html.pantsdown-mermaid-mod.pantsdown .mermaid-viewport {
+   cursor: grab;
+}
+.pantsdown .mermaid-viewport.dragging {
+   cursor: grabbing;
+   user-select: none;
+}
+.pantsdown .mermaid-button {
+   cursor: pointer;
+   height: 30px;
+   width: 30px;
+   padding: 0;
+   color: var(--color-fg-default);
+   background: var(--color-btn-bg);
+   border: 1px solid var(--color-btn-border);
+   border-radius: 4px;
+   display: flex;
+   align-items: center;
+   justify-content: center;
+}
+.pantsdown .mermaid-button:hover {
+   background: var(--color-btn-hover-bg);
+}
+.pantsdown .mermaid-controls {
+   position: absolute;
+   right: 8px;
+   bottom: 8px;
+   display: grid;
+   gap: 4px;
+}
+.pantsdown .mermaid-popover-button {
+   position: absolute;
+   right: 8px;
+   top: 8px;
+}
+.pantsdown.mermaid-overlay {
+   position: fixed;
+   inset: 0;
+   z-index: 100;
+   background: rgba(0, 0, 0, 0.5);
+   padding: 24px;
+}
+.pantsdown.mermaid-overlay .mermaid-panel {
+   position: relative;
+   width: 100%;
+   height: 100%;
+   background: var(--color-canvas-default);
+   border: 1px solid var(--color-border-default);
+   border-radius: 6px;
+   overflow: hidden;
+}
+.pantsdown.mermaid-overlay .mermaid-viewport {
+   width: 100%;
+   height: 100%;
+   cursor: grab;
+}
+.pantsdown.mermaid-overlay .mermaid-viewport.dragging {
+   cursor: grabbing;
+}
 .pantsdown .octicon {
    display: inline-block;
    fill: currentColor;

package/src/javascript.ts CHANGED Viewed

@@ -1,4 +1,6 @@
-export const javascript = `
+import { type PantsdownConfig } from "./types.ts";
+const copyButtonScript = `
     /** code copy button */
     document.querySelectorAll("pre").forEach((pre) => {
         const firstElement = pre.firstElementChild;
@@ -33,3 +35,356 @@ export const javascript = `
         });
     });
 `;
+function mermaidScript(config: PantsdownConfig["renderer"]["mermaid"]): string {
+   return `
+    /** mermaid pan & zoom controls */
+    (() => {
+        const config = ${JSON.stringify(config)};
+        const MIN_SCALE = 0.2;
+        const MAX_SCALE = 10;
+        const PAN_STEP = 60;
+        // pan/zoom state per diagram, keyed by data-mermaid-key. Lives on
+        // window so it survives consumers replacing the whole DOM on every
+        // update. Pruning to the keys present in the current document resets
+        // views on navigation and evicts stale entries.
+        const transforms = (window.pantsdownMermaidTransforms ??= new Map());
+        {
+            const presentKeys = new Set();
+            document.querySelectorAll(".mermaid[data-mermaid-key]").forEach((el) => {
+                presentKeys.add(el.getAttribute("data-mermaid-key"));
+            });
+            transforms.forEach((_, key) => {
+                if (!presentKeys.has(key)) transforms.delete(key);
+            });
+        }
+        const icon = (paths) =>
+            '<svg xmlns="http://www.w3.org/2000/svg" width="16" height="16" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">' +
+            paths +
+            "</svg>";
+        const icons = {
+            up: icon('<path d="m18 15-6-6-6 6"/>'),
+            down: icon('<path d="m6 9 6 6 6-6"/>'),
+            left: icon('<path d="m15 18-6-6 6-6"/>'),
+            right: icon('<path d="m9 18 6-6-6-6"/>'),
+            zoomIn: icon('<circle cx="11" cy="11" r="8"/><line x1="21" x2="16.65" y1="21" y2="16.65"/><line x1="11" x2="11" y1="8" y2="14"/><line x1="8" x2="14" y1="11" y2="11"/>'),
+            zoomOut: icon('<circle cx="11" cy="11" r="8"/><line x1="21" x2="16.65" y1="21" y2="16.65"/><line x1="8" x2="14" y1="11" y2="11"/>'),
+            reset: icon('<path d="M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8"/><path d="M21 3v5h-5"/><path d="M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16"/><path d="M8 16H3v5"/>'),
+            popover: icon('<polyline points="15 3 21 3 21 9"/><polyline points="9 21 3 21 3 15"/><line x1="21" x2="14" y1="3" y2="10"/><line x1="3" x2="10" y1="21" y2="14"/>'),
+            close: icon('<path d="M18 6 6 18"/><path d="m6 6 12 12"/>'),
+        };
+        function makeButton(name, title, onClick) {
+            const btn = document.createElement("button");
+            btn.type = "button";
+            btn.className = "mermaid-button";
+            btn.innerHTML = icons[name];
+            btn.title = title;
+            btn.setAttribute("aria-label", title);
+            btn.addEventListener("click", onClick);
+            return btn;
+        }
+        function attachGestures(viewport, canvas, opts) {
+            const state = { x: 0, y: 0, scale: 1 };
+            // "reset" returns to this state; the popover overrides it with a
+            // fitted & centered transform via setHome
+            const home = { x: 0, y: 0, scale: 1 };
+            function apply() {
+                canvas.style.transform =
+                    "translate(" + state.x + "px, " + state.y + "px) scale(" + state.scale + ")";
+                if (opts.storeKey) {
+                    transforms.set(opts.storeKey, {
+                        x: state.x,
+                        y: state.y,
+                        scale: state.scale,
+                    });
+                }
+            }
+            function panBy(dx, dy) {
+                state.x += dx;
+                state.y += dy;
+                apply();
+            }
+            function zoomAt(factor, originX, originY) {
+                const scale = Math.min(MAX_SCALE, Math.max(MIN_SCALE, state.scale * factor));
+                factor = scale / state.scale;
+                state.x = originX - (originX - state.x) * factor;
+                state.y = originY - (originY - state.y) * factor;
+                state.scale = scale;
+                apply();
+            }
+            // canvas coordinates are relative to the viewport's content box;
+            // the inline viewport carries the pre's padding, so gesture
+            // coordinates (relative to the border box) must be shifted by it
+            function contentOrigin() {
+                const style = window.getComputedStyle(viewport);
+                return {
+                    x: parseFloat(style.paddingLeft) || 0,
+                    y: parseFloat(style.paddingTop) || 0,
+                };
+            }
+            function zoomBy(factor) {
+                const rect = viewport.getBoundingClientRect();
+                const origin = contentOrigin();
+                zoomAt(factor, rect.width / 2 - origin.x, rect.height / 2 - origin.y);
+            }
+            function reset() {
+                state.x = home.x;
+                state.y = home.y;
+                state.scale = home.scale;
+                apply();
+            }
+            function setHome(x, y, scale) {
+                home.x = x;
+                home.y = y;
+                home.scale = scale;
+                reset();
+            }
+            // inline diagrams require cmd/ctrl (and can be disabled via config)
+            // so plain click & scroll keep selecting text / scrolling the page;
+            // the popover captures plain gestures
+            const enabled = opts.requireMod ? config.mouseActions : true;
+            const modOk = (e) => !opts.requireMod || e.metaKey || e.ctrlKey;
+            if (enabled) {
+                viewport.addEventListener(
+                    "wheel",
+                    (e) => {
+                        if (!modOk(e)) return;
+                        e.preventDefault();
+                        const rect = viewport.getBoundingClientRect();
+                        const origin = contentOrigin();
+                        const delta = e.deltaY * (e.deltaMode === 1 ? 16 : 1);
+                        zoomAt(
+                            Math.exp(-delta * 0.002),
+                            e.clientX - rect.left - origin.x,
+                            e.clientY - rect.top - origin.y,
+                        );
+                    },
+                    { passive: false },
+                );
+                viewport.addEventListener("pointerdown", (e) => {
+                    if (e.button !== 0 || !modOk(e)) return;
+                    e.preventDefault();
+                    viewport.setPointerCapture(e.pointerId);
+                    viewport.classList.add("dragging");
+                    let lastX = e.clientX;
+                    let lastY = e.clientY;
+                    const onMove = (ev) => {
+                        panBy(ev.clientX - lastX, ev.clientY - lastY);
+                        lastX = ev.clientX;
+                        lastY = ev.clientY;
+                    };
+                    const onUp = () => {
+                        viewport.classList.remove("dragging");
+                        viewport.removeEventListener("pointermove", onMove);
+                        viewport.removeEventListener("pointerup", onUp);
+                        viewport.removeEventListener("pointercancel", onUp);
+                    };
+                    viewport.addEventListener("pointermove", onMove);
+                    viewport.addEventListener("pointerup", onUp);
+                    viewport.addEventListener("pointercancel", onUp);
+                });
+            }
+            // restore the stashed transform so re-renders don't visually
+            // move the diagram; home stays identity, so reset still returns
+            // to the natural view
+            const stored = opts.storeKey ? transforms.get(opts.storeKey) : undefined;
+            if (stored) {
+                state.x = stored.x;
+                state.y = stored.y;
+                state.scale = stored.scale;
+                apply();
+            }
+            return { panBy, zoomBy, reset, setHome };
+        }
+        function buildCluster(controller) {
+            const b = config.buttons;
+            if (!b.arrows && !b.zoom && !b.reset) return null;
+            const cluster = document.createElement("div");
+            cluster.className = "mermaid-controls";
+            cluster.style.gridTemplateAreas = b.arrows
+                ? '". up zin" "left reset right" ". down zout"'
+                : '"zin" "reset" "zout"';
+            const place = (btn, area) => {
+                btn.style.gridArea = area;
+                cluster.appendChild(btn);
+            };
+            if (b.arrows) {
+                place(makeButton("up", "Pan up", () => controller.panBy(0, PAN_STEP)), "up");
+                place(makeButton("down", "Pan down", () => controller.panBy(0, -PAN_STEP)), "down");
+                place(makeButton("left", "Pan left", () => controller.panBy(PAN_STEP, 0)), "left");
+                place(makeButton("right", "Pan right", () => controller.panBy(-PAN_STEP, 0)), "right");
+            }
+            if (b.zoom) {
+                place(makeButton("zoomIn", "Zoom in", () => controller.zoomBy(1.25)), "zin");
+                place(makeButton("zoomOut", "Zoom out", () => controller.zoomBy(0.8)), "zout");
+            }
+            if (b.reset) place(makeButton("reset", "Reset view", () => controller.reset()), "reset");
+            return cluster;
+        }
+        function openPopover(el, svg) {
+            const root = el.closest(".pantsdown");
+            const overlay = document.createElement("div");
+            overlay.className = (root ? root.className : "pantsdown") + " mermaid-overlay";
+            const panel = document.createElement("div");
+            panel.className = "mermaid-panel";
+            const viewport = document.createElement("div");
+            viewport.className = "mermaid-viewport";
+            const canvas = document.createElement("div");
+            canvas.className = "mermaid-canvas";
+            const clone = svg.cloneNode(true);
+            canvas.appendChild(clone);
+            viewport.appendChild(canvas);
+            panel.appendChild(viewport);
+            overlay.appendChild(panel);
+            const controller = attachGestures(viewport, canvas, { requireMod: false });
+            const cluster = buildCluster(controller);
+            if (cluster) panel.appendChild(cluster);
+            function onKeydown(e) {
+                if (e.key === "Escape") close();
+            }
+            function close() {
+                overlay.remove();
+                window.removeEventListener("keydown", onKeydown);
+            }
+            const closeButton = makeButton("close", "Close", close);
+            closeButton.classList.add("mermaid-popover-button");
+            panel.appendChild(closeButton);
+            window.addEventListener("keydown", onKeydown);
+            overlay.addEventListener("pointerdown", (e) => {
+                if (e.target === overlay) close();
+            });
+            document.body.appendChild(overlay);
+            // fit the whole diagram inside the viewport (never upscaling past
+            // its natural size) and center it; reset returns to this state
+            const vp = viewport.getBoundingClientRect();
+            const content = clone.getBoundingClientRect();
+            if (vp.width > 0 && content.width > 0 && content.height > 0) {
+                const pad = 32;
+                const scale = Math.max(
+                    MIN_SCALE,
+                    Math.min(
+                        1,
+                        (vp.width - pad) / content.width,
+                        (vp.height - pad) / content.height,
+                    ),
+                );
+                const x = (vp.width - content.width * scale) / 2 - (content.left - vp.left) * scale;
+                const y = (vp.height - content.height * scale) / 2 - (content.top - vp.top) * scale;
+                controller.setHome(x, y, scale);
+            }
+        }
+        function setup(el) {
+            // prefer the canvas svg: if a consumer re-injects html that was
+            // serialized after a previous setup, the diagram svg sits inside
+            // the old wrapper and stale button icons are svgs too
+            const svg = el.querySelector(".mermaid-canvas svg") ?? el.querySelector("svg");
+            if (!svg) return;
+            // serialized html loses event listeners, so stale wrappers and
+            // controls would be dead and duplicated — remove them and rebuild
+            el.querySelectorAll(
+                ".mermaid-viewport, .mermaid-controls, .mermaid-popover-button",
+            ).forEach((stale) => {
+                stale.remove();
+            });
+            const viewport = document.createElement("div");
+            viewport.className = "mermaid-viewport";
+            const canvas = document.createElement("div");
+            canvas.className = "mermaid-canvas";
+            canvas.appendChild(svg);
+            viewport.appendChild(canvas);
+            el.appendChild(viewport);
+            const controller = attachGestures(viewport, canvas, {
+                requireMod: true,
+                storeKey: el.getAttribute("data-mermaid-key"),
+            });
+            const cluster = buildCluster(controller);
+            if (cluster) el.appendChild(cluster);
+            if (config.buttons.popover) {
+                const btn = makeButton("popover", "Open in popover", () => openPopover(el, svg));
+                btn.classList.add("mermaid-popover-button");
+                el.appendChild(btn);
+            }
+        }
+        // mermaid renders asynchronously (the page loads mermaid.js separately),
+        // so wait for the svg to replace the diagram source
+        function whenRendered(el, cb) {
+            if (el.querySelector("svg")) {
+                cb();
+                return;
+            }
+            const observer = new MutationObserver(() => {
+                if (el.querySelector("svg")) {
+                    observer.disconnect();
+                    cb();
+                }
+            });
+            observer.observe(el, { childList: true, subtree: true });
+        }
+        document.querySelectorAll(".mermaid").forEach((el) => {
+            if (el.hasAttribute("data-pantsdown-mermaid")) return;
+            el.setAttribute("data-pantsdown-mermaid", "");
+            whenRendered(el, () => {
+                setup(el);
+            });
+        });
+        // grab cursor hint while cmd/ctrl is held over a diagram
+        if (config.mouseActions && !window.pantsdownMermaidModListener) {
+            window.pantsdownMermaidModListener = true;
+            const setMod = (on) => {
+                document.documentElement.classList.toggle("pantsdown-mermaid-mod", on);
+            };
+            window.addEventListener("keydown", (e) => {
+                if (e.key === "Meta" || e.key === "Control") setMod(true);
+            });
+            window.addEventListener("keyup", (e) => {
+                if (e.key === "Meta" || e.key === "Control") setMod(false);
+            });
+            window.addEventListener("blur", () => {
+                setMod(false);
+            });
+        }
+    })();
+`;
+}
+export function getJavascript(config: PantsdownConfig): string {
+   return copyButtonScript + mermaidScript(config.renderer.mermaid);
+}

package/src/pantsdown.ts CHANGED Viewed

@@ -1,5 +1,5 @@
 import GithubSlugger from "github-slugger";
-import { javascript } from "./javascript.ts";
+import { getJavascript } from "./javascript.ts";
 import { Lexer } from "./lexer.ts";
 import { Parser } from "./parser.ts";
 import { type PantsdownConfig, type PartialPantsdownConfig } from "./types.ts";
@@ -9,6 +9,15 @@ const defaultConfig: PantsdownConfig = {
       relativeImageUrlPrefix: "",
       absoluteImageUrlPrefix: undefined,
       detailsTagDefaultOpen: false,
+      mermaid: {
+         buttons: {
+            zoom: true,
+            reset: true,
+            arrows: true,
+            popover: true,
+         },
+         mouseActions: true,
+      },
    },
 };
@@ -28,10 +37,19 @@ export class Pantsdown {
     * The object you provide will be deeply merged into current config.
     */
    setConfig(config: PartialPantsdownConfig) {
+      const { mermaid, ...renderer } = config.renderer ?? {};
       this.config = {
          renderer: {
             ...this.config.renderer,
-            ...config.renderer,
+            ...renderer,
+            mermaid: {
+               ...this.config.renderer.mermaid,
+               ...mermaid,
+               buttons: {
+                  ...this.config.renderer.mermaid.buttons,
+                  ...mermaid?.buttons,
+               },
+            },
          },
       };
    }
@@ -43,12 +61,13 @@ export class Pantsdown {
       // re-init slugger to avoid slug count from incorrectly incrementing
       // from previosly slugged headings
       this.parser.renderer.slugger = new GithubSlugger();
+      this.parser.renderer.mermaidCounts = new Map();
       const tokens = this.lexer.lex(src);
       const html = this.parser.parse(tokens);
       return {
          html,
-         javascript,
+         javascript: getJavascript(this.config),
       };
    }
 }

package/src/renderer.ts CHANGED Viewed

@@ -13,6 +13,7 @@ import {
    fixHtmlLocalImageHref,
    fixLocalImageHref,
    getHtmlElementText,
+   hashString,
    injectHtmlAttributes,
 } from "./utils.ts";
@@ -23,6 +24,7 @@ export class Renderer {
    private pantsdown: Pantsdown;
    parser!: Parser; // set by the parser
    slugger = new GithubSlugger();
+   mermaidCounts = new Map<string, number>();
    constructor(pantsdown: Pantsdown) {
       this.pantsdown = pantsdown;
@@ -40,6 +42,13 @@ export class Renderer {
       if (lang === "mermaid") {
          attrs.push(["class", "mermaid-container mermaid"]);
+         // stable identity across re-renders — the pan/zoom script keys
+         // stashed transforms on it; the occurrence index disambiguates
+         // byte-identical diagrams in the same document
+         const hash = hashString(code);
+         const count = this.mermaidCounts.get(hash) ?? 0;
+         this.mermaidCounts.set(hash, count + 1);
+         attrs.push(["data-mermaid-key", `${hash}-${count}`]);
          // escape so diagram source can't be parsed as HTML;
          // mermaid reads textContent, which undoes the escaping
          const result = `<pre style="position: relative;">` + escape(code, true) + "\n" + `</pre>`;

package/src/types.ts CHANGED Viewed

@@ -285,6 +285,40 @@ export type PantsdownConfig = {
        * false
        */
       detailsTagDefaultOpen: boolean;
+      /**
+       * Interactive controls added to rendered mermaid diagrams.
+       */
+      mermaid: {
+         /**
+          * Control buttons overlaid on the diagram.
+          * Set individual buttons to `false` to hide them.
+          *
+          * @default
+          * { zoom: true, reset: true, arrows: true, popover: true }
+          */
+         buttons: {
+            /** Zoom in & zoom out buttons */
+            zoom: boolean;
+            /** Reset zoom & pan to the initial position */
+            reset: boolean;
+            /** Directional pan arrows */
+            arrows: boolean;
+            /** Open the diagram in a fullscreen popover */
+            popover: boolean;
+         };
+         /**
+          * Enable cmd/ctrl + drag to pan and cmd/ctrl + scroll to zoom.
+          * Plain click & scroll are never captured, so text selection
+          * and page scrolling keep working. Inside the popover, plain
+          * drag pans and plain scroll zooms regardless of this setting.
+          *
+          * @default
+          * true
+          */
+         mouseActions: boolean;
+      };
    };
 };

package/src/utils.ts CHANGED Viewed

@@ -30,6 +30,15 @@ export function escape(html: string, encode?: boolean) {
    return html;
 }
+/** djb2 — stable, collision-tolerant key for identifying content across parses */
+export function hashString(str: string): string {
+   let hash = 5381;
+   for (let i = 0; i < str.length; i++) {
+      hash = ((hash << 5) + hash + str.charCodeAt(i)) | 0;
+   }
+   return (hash >>> 0).toString(36);
+}
 export function getHtmlElementText(html: string) {
    try {
       const parser = new DOMParser();