@peter.prib/renderengine 0.0.0-stage → 0.2.0

package/src/exportImage.js

@@ -0,0 +1,233 @@
+/**
+ * exportImage — get a diagram out of the page: onto the clipboard, or into a
+ * file.
+ *
+ * A diagram is an `<svg>` (SVGRenderer) or a `<canvas>` (CanvasRenderer). A
+ * canvas is already an image; an SVG is not, and turning one into a bitmap has
+ * three failure modes that are invisible until someone pastes the result into a
+ * document and finds it wrong:
+ *
+ *  - **No intrinsic size.** An SVG sized by CSS (`width: 100%`) has no `width`
+ *    attribute, and an `Image` loading that markup gets 0×0 — a blank paste.
+ *  - **Transparent background.** Diagrams draw no background, so a PNG pasted
+ *    into anything dark shows dark-on-dark labels. Paper is white; the default
+ *    here is too.
+ *  - **Namespace loss.** Markup serialized without `xmlns` will not load as an
+ *    image at all, and `xlink:href` (markers, patterns) needs its own.
+ *
+ * The decisions above are made by pure functions over strings and numbers so
+ * they can be tested without a browser; everything that touches `document`,
+ * `Image` or `navigator` is a thin wrapper over them and is named `...Async`
+ * or documented as DOM-only. Nothing here runs at import time, so this module
+ * loads under node.
+ */
+
+const SVG_NS = 'http://www.w3.org/2000/svg';
+const XLINK_NS = 'http://www.w3.org/1999/xlink';
+
+/** Anything bigger than this is a browser tab crash, not a diagram. */
+export const MAX_IMAGE_PIXELS = 32_000_000;
+
+/**
+ * Work out the bitmap size to rasterize at.
+ *
+ * `scale` is what the caller asked for (2 = retina-sharp). It is reduced, never
+ * the diagram's own dimensions, when the result would be too large: halving the
+ * scale of a huge diagram still shows all of it, whereas cropping or shrinking
+ * the diagram loses content or legibility.
+ *
+ * @returns {{width:number, height:number, scale:number, clamped:boolean}}
+ */
+export function imageSize({ width, height, scale = 2, maxPixels = MAX_IMAGE_PIXELS } = {}) {
+    const w = Math.max(1, Math.round(Number(width) || 0));
+    const h = Math.max(1, Math.round(Number(height) || 0));
+    let s = Number(scale);
+    if (!Number.isFinite(s) || s <= 0) s = 1;
+
+    let clamped = false;
+    if (w * h * s * s > maxPixels) {
+        s = Math.sqrt(maxPixels / (w * h));
+        clamped = true;
+    }
+    // A scale below 1:1 would be a downscale the caller never asked for, but a
+    // diagram that is itself over the budget leaves no choice.
+    if (s < 1 && w * h <= maxPixels) s = 1;
+
+    return { width: Math.max(1, Math.round(w * s)), height: Math.max(1, Math.round(h * s)), scale: s, clamped };
+}
+
+/**
+ * Make serialized SVG markup loadable as an image.
+ *
+ * Adds the namespaces, pins explicit pixel dimensions, and paints a background
+ * behind the drawing. See the class doc for why each is needed.
+ *
+ * @param {string} markup     the output of XMLSerializer on an <svg> element
+ * @param {object} [options]
+ * @param {number} [options.width]       pixels; omitted leaves what is there
+ * @param {number} [options.height]
+ * @param {string|null} [options.background='#ffffff']  null for transparent
+ */
+export function prepareSvgMarkup(markup, { width, height, background = '#ffffff' } = {}) {
+    let out = String(markup ?? '').trim();
+    const open = out.match(/^<svg\b[^>]*>/i);
+    if (!open) return out;          // not an <svg> — hand it back untouched
+    let tag = open[0];
+
+    if (!/\sxmlns\s*=/.test(tag)) tag = tag.replace(/^<svg/i, `<svg xmlns="${SVG_NS}"`);
+    // Only when something actually uses it: an unused namespace declaration is
+    // noise in a file someone may open in an editor.
+    if (/xlink:/.test(out) && !/\sxmlns:xlink\s*=/.test(tag)) {
+        tag = tag.replace(/^<svg/i, `<svg xmlns:xlink="${XLINK_NS}"`);
+    }
+
+    const setAttr = (name, value) => {
+        const re = new RegExp(`\\s${name}\\s*=\\s*("[^"]*"|'[^']*')`, 'i');
+        tag = re.test(tag) ? tag.replace(re, ` ${name}="${value}"`) : tag.replace(/^<svg/i, `<svg ${name}="${value}"`);
+    };
+    if (Number.isFinite(width) && width > 0) setAttr('width', Math.round(width));
+    if (Number.isFinite(height) && height > 0) setAttr('height', Math.round(height));
+
+    out = tag + out.slice(open[0].length);
+
+    if (background) {
+        // First child, so it sits behind everything. Percentages rather than
+        // pixels so it still covers the drawing if a viewBox rescales it.
+        out = out.replace(tag, `${tag}<rect x="0" y="0" width="100%" height="100%" fill="${background}"/>`);
+    }
+    return out;
+}
+
+/** A filename-safe stem: `My Diagram (v2)` → `my-diagram-v2`. */
+export function imageFileName(name, ext = 'png') {
+    const stem = String(name ?? 'diagram')
+        .trim().toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '') || 'diagram';
+    return `${stem}.${ext}`;
+}
+
+/* ── DOM side ────────────────────────────────────────────────────────────── */
+
+/**
+ * The drawable inside `host` — `host` itself if it is already one. DOM only.
+ * @returns {SVGElement|HTMLCanvasElement|null}
+ */
+export function findDrawable(host) {
+    if (!host) return null;
+    const tag = host.tagName?.toLowerCase?.();
+    if (tag === 'svg' || tag === 'canvas') return host;
+    return host.querySelector?.('svg, canvas') ?? null;
+}
+
+/**
+ * Serialize an `<svg>` element to standalone markup. DOM only.
+ *
+ * Size is taken from the element's laid-out box rather than its attributes,
+ * because that is what the user is actually looking at.
+ */
+export function serializeSvg(svgEl, { background = '#ffffff', width, height } = {}) {
+    const box = svgEl.getBoundingClientRect?.() ?? {};
+    const w = width ?? svgEl.width?.baseVal?.value ?? box.width;
+    const h = height ?? svgEl.height?.baseVal?.value ?? box.height;
+    const markup = new XMLSerializer().serializeToString(svgEl);
+    return prepareSvgMarkup(markup, { width: w, height: h, background });
+}
+
+/**
+ * Rasterize a diagram to a PNG Blob. DOM only.
+ *
+ * @param {Element} host  the diagram, or an element containing one
+ */
+export async function toPngBlob(host, { scale = 2, background = '#ffffff', maxPixels = MAX_IMAGE_PIXELS } = {}) {
+    const drawable = findDrawable(host);
+    if (!drawable) throw new Error('No <svg> or <canvas> to export');
+
+    if (drawable.tagName.toLowerCase() === 'canvas') {
+        return await new Promise((resolve, reject) => {
+            drawable.toBlob(b => (b ? resolve(b) : reject(new Error('Canvas produced no image'))), 'image/png');
+        });
+    }
+
+    const box = drawable.getBoundingClientRect();
+    const size = imageSize({ width: box.width, height: box.height, scale, maxPixels });
+    const markup = serializeSvg(drawable, { background, width: box.width, height: box.height });
+
+    // A data: URL rather than a blob: URL — a blob: URL taints nothing either,
+    // but Safari has historically refused to draw SVG from one.
+    const url = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(markup)}`;
+    const img = await new Promise((resolve, reject) => {
+        const i = new Image();
+        i.onload = () => resolve(i);
+        i.onerror = () => reject(new Error('The diagram could not be rendered as an image'));
+        i.src = url;
+    });
+
+    const canvas = document.createElement('canvas');
+    canvas.width = size.width;
+    canvas.height = size.height;
+    const ctx = canvas.getContext('2d');
+    if (background) { ctx.fillStyle = background; ctx.fillRect(0, 0, canvas.width, canvas.height); }
+    ctx.drawImage(img, 0, 0, canvas.width, canvas.height);
+
+    return await new Promise((resolve, reject) => {
+        canvas.toBlob(b => (b ? resolve(b) : reject(new Error('The image could not be encoded'))), 'image/png');
+    });
+}
+
+/** Trigger a download of `blob` as `filename`. DOM only. */
+export function downloadBlob(blob, filename) {
+    const url = URL.createObjectURL(blob);
+    const a = document.createElement('a');
+    a.href = url;
+    a.download = filename;
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    // Revoked on a later turn: revoking synchronously can beat the download in
+    // some browsers, leaving an empty file.
+    setTimeout(() => URL.revokeObjectURL(url), 10_000);
+}
+
+/**
+ * Put a diagram on the clipboard as a PNG. DOM only.
+ *
+ * Falls back to downloading the file where writing images to the clipboard is
+ * unavailable — Firefox, and any page not served over a secure context — so the
+ * action always does something rather than silently failing. The result says
+ * which happened, so a caller can tell the user the truth.
+ *
+ * @returns {Promise<{via:'clipboard'|'download', filename?:string}>}
+ */
+export async function copyImage(host, { scale = 2, background = '#ffffff', name = 'diagram' } = {}) {
+    const blob = await toPngBlob(host, { scale, background });
+    const canWrite = typeof ClipboardItem !== 'undefined'
+        && typeof navigator !== 'undefined'
+        && navigator.clipboard?.write;
+
+    if (canWrite) {
+        try {
+            await navigator.clipboard.write([new ClipboardItem({ 'image/png': blob })]);
+            return { via: 'clipboard' };
+        } catch {
+            // Denied permission, or a browser that advertises write() but
+            // refuses images — fall through rather than lose the user's click.
+        }
+    }
+    const filename = imageFileName(name, 'png');
+    downloadBlob(blob, filename);
+    return { via: 'download', filename };
+}
+
+/** Save a diagram as an SVG file. DOM only. */
+export function downloadSvg(host, { background = '#ffffff', name = 'diagram' } = {}) {
+    const drawable = findDrawable(host);
+    if (!drawable || drawable.tagName.toLowerCase() !== 'svg') throw new Error('No <svg> to export');
+    const markup = serializeSvg(drawable, { background });
+    downloadBlob(new Blob([markup], { type: 'image/svg+xml;charset=utf-8' }), imageFileName(name, 'svg'));
+}
+
+/** Save a diagram as a PNG file. DOM only. */
+export async function downloadPng(host, { scale = 2, background = '#ffffff', name = 'diagram' } = {}) {
+    downloadBlob(await toPngBlob(host, { scale, background }), imageFileName(name, 'png'));
+}