react-cheminfo 0.9.0 → 0.10.0

package/lib/download/core/downloadFigure.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Saving a figure that is on the page, named by the box it is mounted in.
+ *
+ * Which of the two formats a reader wants is not a question the figure can
+ * answer for them: an SVG is the one to put in a paper, where it stays sharp
+ * at any size and can still be edited, and a PNG is the one every chat window,
+ * slide deck and issue tracker actually accepts. So both are offered, and the
+ * resolution goes with the second.
+ */
+import type { FigureSvgOptions } from './figureSvg.ts';
+/** Which file a figure is saved as. */
+export type FigureFormat = 'svg' | 'png';
+/** How a figure is saved. */
+export interface DownloadFigureOptions extends FigureSvgOptions {
+    /**
+     * Which file to write.
+     * @default 'png'
+     */
+    format?: FigureFormat;
+    /**
+     * How many pixels are painted per pixel on screen. An SVG ignores it: it
+     * carries no resolution of its own.
+     * @default 2
+     */
+    scale?: number;
+    /**
+     * What the saved file is called, without its extension.
+     * @default 'figure'
+     */
+    fileName?: string;
+}
+/**
+ * Save the figure mounted in that box.
+ * @param target - The `id` of the box, or the element itself.
+ * @param options - See {@link DownloadFigureOptions}.
+ * @throws {Error} When the box holds no figure, or the browser cannot paint it.
+ */
+export declare function downloadFigure(target: string | Element, options?: DownloadFigureOptions): Promise<void>;
+//# sourceMappingURL=downloadFigure.d.ts.map

package/lib/download/core/downloadFigure.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"downloadFigure.d.ts","sourceRoot":"","sources":["../../../src/download/core/downloadFigure.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAKH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAIvD,uCAAuC;AACvC,MAAM,MAAM,YAAY,GAAG,KAAK,GAAG,KAAK,CAAC;AAEzC,6BAA6B;AAC7B,MAAM,WAAW,qBAAsB,SAAQ,gBAAgB;IAC7D;;;OAGG;IACH,MAAM,CAAC,EAAE,YAAY,CAAC;IACtB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAKD;;;;;GAKG;AACH,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,GAAG,OAAO,EACxB,OAAO,GAAE,qBAA0B,GAClC,OAAO,CAAC,IAAI,CAAC,CAaf"}

package/lib/download/core/downloadFigure.js

@@ -0,0 +1,35 @@
+/**
+ * Saving a figure that is on the page, named by the box it is mounted in.
+ *
+ * Which of the two formats a reader wants is not a question the figure can
+ * answer for them: an SVG is the one to put in a paper, where it stays sharp
+ * at any size and can still be edited, and a PNG is the one every chat window,
+ * slide deck and issue tracker actually accepts. So both are offered, and the
+ * resolution goes with the second.
+ */
+import { downloadBlob } from "./downloadBlob.js";
+import { figurePng } from "./figurePng.js";
+import { DEFAULT_FIGURE_SCALE } from "./figureScale.js";
+import { FIGURE_SVG_TYPE, figureSvg } from "./figureSvg.js";
+import { sanitizeFileName } from "./sanitizeFileName.js";
+/** What a figure is called when the caller does not say. */
+const DEFAULT_FILE_NAME = 'figure';
+/**
+ * Save the figure mounted in that box.
+ * @param target - The `id` of the box, or the element itself.
+ * @param options - See {@link DownloadFigureOptions}.
+ * @throws {Error} When the box holds no figure, or the browser cannot paint it.
+ */
+export async function downloadFigure(target, options = {}) {
+    const { format = 'png', scale = DEFAULT_FIGURE_SCALE } = options;
+    const { fileName = DEFAULT_FILE_NAME, background } = options;
+    const figure = figureSvg(target, { background });
+    const name = sanitizeFileName(fileName, DEFAULT_FILE_NAME);
+    if (format === 'svg') {
+        const blob = new Blob([figure.markup], { type: FIGURE_SVG_TYPE });
+        downloadBlob(blob, `${name}.svg`);
+        return;
+    }
+    downloadBlob(await figurePng(figure, scale), `${name}.png`);
+}
+//# sourceMappingURL=downloadFigure.js.map

package/lib/download/core/downloadFigure.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"downloadFigure.js","sourceRoot":"","sources":["../../../src/download/core/downloadFigure.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC3C,OAAO,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAExD,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAC5D,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC;AAyBzD,4DAA4D;AAC5D,MAAM,iBAAiB,GAAG,QAAQ,CAAC;AAEnC;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,MAAwB,EACxB,UAAiC,EAAE;IAEnC,MAAM,EAAE,MAAM,GAAG,KAAK,EAAE,KAAK,GAAG,oBAAoB,EAAE,GAAG,OAAO,CAAC;IACjE,MAAM,EAAE,QAAQ,GAAG,iBAAiB,EAAE,UAAU,EAAE,GAAG,OAAO,CAAC;IAE7D,MAAM,MAAM,GAAG,SAAS,CAAC,MAAM,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;IACjD,MAAM,IAAI,GAAG,gBAAgB,CAAC,QAAQ,EAAE,iBAAiB,CAAC,CAAC;IAE3D,IAAI,MAAM,KAAK,KAAK,EAAE,CAAC;QACrB,MAAM,IAAI,GAAG,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC,CAAC;QAClE,YAAY,CAAC,IAAI,EAAE,GAAG,IAAI,MAAM,CAAC,CAAC;QAClC,OAAO;IACT,CAAC;IACD,YAAY,CAAC,MAAM,SAAS,CAAC,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,IAAI,MAAM,CAAC,CAAC;AAC9D,CAAC"}

package/lib/download/core/figurePng.d.ts

@@ -0,0 +1,21 @@
+/**
+ * A figure painted into pixels, at whatever resolution the reader asked for.
+ *
+ * The picture is drawn once as an SVG and then rasterized from it, rather than
+ * being drawn a second time into a canvas: a figure that is saved has to be
+ * the figure that was read, and two drawing paths are two things to keep in
+ * step. Scaling is the browser's own, so a figure saved at three times is
+ * genuinely three times the detail rather than a stretched screenshot.
+ */
+import type { FigureSvg } from './figureSvg.ts';
+/** What a saved raster figure is. */
+export declare const FIGURE_PNG_TYPE = "image/png";
+/**
+ * The figure as a PNG.
+ * @param figure - The figure, already copied off the page.
+ * @param scale - How many pixels are painted per pixel on screen.
+ * @returns The image.
+ * @throws {Error} When the browser cannot paint or encode it.
+ */
+export declare function figurePng(figure: FigureSvg, scale?: number): Promise<Blob>;
+//# sourceMappingURL=figurePng.d.ts.map

package/lib/download/core/figurePng.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figurePng.d.ts","sourceRoot":"","sources":["../../../src/download/core/figurePng.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC;AAGhD,qCAAqC;AACrC,eAAO,MAAM,eAAe,cAAc,CAAC;AAE3C;;;;;;GAMG;AACH,wBAAsB,SAAS,CAC7B,MAAM,EAAE,SAAS,EACjB,KAAK,GAAE,MAA6B,GACnC,OAAO,CAAC,IAAI,CAAC,CAcf"}

package/lib/download/core/figurePng.js

@@ -0,0 +1,76 @@
+/**
+ * A figure painted into pixels, at whatever resolution the reader asked for.
+ *
+ * The picture is drawn once as an SVG and then rasterized from it, rather than
+ * being drawn a second time into a canvas: a figure that is saved has to be
+ * the figure that was read, and two drawing paths are two things to keep in
+ * step. Scaling is the browser's own, so a figure saved at three times is
+ * genuinely three times the detail rather than a stretched screenshot.
+ */
+import { DEFAULT_FIGURE_SCALE, figurePixels } from "./figureScale.js";
+import { FIGURE_SVG_TYPE } from "./figureSvg.js";
+/** What a saved raster figure is. */
+export const FIGURE_PNG_TYPE = 'image/png';
+/**
+ * The figure as a PNG.
+ * @param figure - The figure, already copied off the page.
+ * @param scale - How many pixels are painted per pixel on screen.
+ * @returns The image.
+ * @throws {Error} When the browser cannot paint or encode it.
+ */
+export async function figurePng(figure, scale = DEFAULT_FIGURE_SCALE) {
+    const pixels = figurePixels(figure, scale);
+    const drawing = await loadFigure(figure);
+    const canvas = document.createElement('canvas');
+    canvas.width = pixels.width;
+    canvas.height = pixels.height;
+    const context = canvas.getContext('2d');
+    if (context === null) {
+        throw new Error('This browser cannot paint the figure into an image.');
+    }
+    context.drawImage(drawing, 0, 0, pixels.width, pixels.height);
+    return encode(canvas);
+}
+/**
+ * The SVG document, decoded and ready to be painted.
+ *
+ * It goes through an object URL rather than a `data:` one because a figure of
+ * a few thousand dots runs to hundreds of kilobytes, and a `data:` URL that
+ * long is refused outright by some browsers.
+ * @param figure - The figure, already copied off the page.
+ * @returns The decoded image.
+ */
+async function loadFigure(figure) {
+    const url = URL.createObjectURL(new Blob([figure.markup], { type: FIGURE_SVG_TYPE }));
+    try {
+        const image = new Image(figure.width, figure.height);
+        await new Promise((resolve, reject) => {
+            image.addEventListener('load', () => resolve());
+            image.addEventListener('error', () => {
+                reject(new Error('The figure could not be read back as an image.'));
+            });
+            image.src = url;
+        });
+        return image;
+    }
+    finally {
+        URL.revokeObjectURL(url);
+    }
+}
+/**
+ * The painted canvas, as a file.
+ * @param canvas - The canvas the figure was painted into.
+ * @returns The image.
+ */
+function encode(canvas) {
+    return new Promise((resolve, reject) => {
+        canvas.toBlob((blob) => {
+            if (blob === null) {
+                reject(new Error('The figure could not be encoded as a PNG.'));
+                return;
+            }
+            resolve(blob);
+        }, FIGURE_PNG_TYPE);
+    });
+}
+//# sourceMappingURL=figurePng.js.map

package/lib/download/core/figurePng.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"figurePng.js","sourceRoot":"","sources":["../../../src/download/core/figurePng.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAEtE,OAAO,EAAE,eAAe,EAAE,MAAM,gBAAgB,CAAC;AAEjD,qCAAqC;AACrC,MAAM,CAAC,MAAM,eAAe,GAAG,WAAW,CAAC;AAE3C;;;;;;GAMG;AACH,MAAM,CAAC,KAAK,UAAU,SAAS,CAC7B,MAAiB,EACjB,QAAgB,oBAAoB;IAEpC,MAAM,MAAM,GAAG,YAAY,CAAC,MAAM,EAAE,KAAK,CAAC,CAAC;IAC3C,MAAM,OAAO,GAAG,MAAM,UAAU,CAAC,MAAM,CAAC,CAAC;IAEzC,MAAM,MAAM,GAAG,QAAQ,CAAC,aAAa,CAAC,QAAQ,CAAC,CAAC;IAChD,MAAM,CAAC,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC;IAC5B,MAAM,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;IAC9B,MAAM,OAAO,GAAG,MAAM,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC;IACxC,IAAI,OAAO,KAAK,IAAI,EAAE,CAAC;QACrB,MAAM,IAAI,KAAK,CAAC,qDAAqD,CAAC,CAAC;IACzE,CAAC;IACD,OAAO,CAAC,SAAS,CAAC,OAAO,EAAE,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;IAE9D,OAAO,MAAM,CAAC,MAAM,CAAC,CAAC;AACxB,CAAC;AAED;;;;;;;;GAQG;AACH,KAAK,UAAU,UAAU,CAAC,MAAiB;IACzC,MAAM,GAAG,GAAG,GAAG,CAAC,eAAe,CAC7B,IAAI,IAAI,CAAC,CAAC,MAAM,CAAC,MAAM,CAAC,EAAE,EAAE,IAAI,EAAE,eAAe,EAAE,CAAC,CACrD,CAAC;IACF,IAAI,CAAC;QACH,MAAM,KAAK,GAAG,IAAI,KAAK,CAAC,MAAM,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,CAAC,CAAC;QACrD,MAAM,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;YAC1C,KAAK,CAAC,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,OAAO,EAAE,CAAC,CAAC;YAChD,KAAK,CAAC,gBAAgB,CAAC,OAAO,EAAE,GAAG,EAAE;gBACnC,MAAM,CAAC,IAAI,KAAK,CAAC,gDAAgD,CAAC,CAAC,CAAC;YACtE,CAAC,CAAC,CAAC;YACH,KAAK,CAAC,GAAG,GAAG,GAAG,CAAC;QAClB,CAAC,CAAC,CAAC;QACH,OAAO,KAAK,CAAC;IACf,CAAC;YAAS,CAAC;QACT,GAAG,CAAC,eAAe,CAAC,GAAG,CAAC,CAAC;IAC3B,CAAC;AACH,CAAC;AAED;;;;GAIG;AACH,SAAS,MAAM,CAAC,MAAyB;IACvC,OAAO,IAAI,OAAO,CAAO,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;QAC3C,MAAM,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE;YACrB,IAAI,IAAI,KAAK,IAAI,EAAE,CAAC;gBAClB,MAAM,CAAC,IAAI,KAAK,CAAC,2CAA2C,CAAC,CAAC,CAAC;gBAC/D,OAAO;YACT,CAAC;YACD,OAAO,CAAC,IAAI,CAAC,CAAC;QAChB,CAAC,EAAE,eAAe,CAAC,CAAC;IACtB,CAAC,CAAC,CAAC;AACL,CAAC"}

package/lib/download/core/figureScale.d.ts

@@ -0,0 +1,61 @@
+/**
+ * How large a figure is saved.
+ *
+ * The resolution is offered as a multiple of the figure on screen rather than
+ * as a pixel width, because the multiple is the part a reader has an opinion
+ * about — one for a note, two for a slide, three or four for print — while the
+ * pixel count is the consequence, and is written out beside it so nobody has
+ * to work it out.
+ */
+/** The size of a saved figure, in pixels. */
+export interface FigurePixels {
+    /** Its width. */
+    width: number;
+    /** Its height. */
+    height: number;
+}
+/** The multiples offered, from the figure as drawn to print resolution. */
+export declare const FIGURE_SCALES: readonly number[];
+/**
+ * The multiple a figure is saved at unless the reader says otherwise.
+ *
+ * Two rather than one: a figure saved at the size it was drawn looks soft on
+ * every screen that is not the one it was drawn on, and a slide is where most
+ * of these files end up.
+ */
+export declare const DEFAULT_FIGURE_SCALE = 2;
+/**
+ * The longest side a browser will paint into one canvas.
+ *
+ * Past it the canvas is silently blank rather than refused, which is the worst
+ * of both — so a multiple that would cross it is offered greyed rather than
+ * left to fail after the reader has pressed save.
+ */
+export declare const FIGURE_MAX_PIXELS = 16384;
+/**
+ * How big the saved file is, at this multiple.
+ * @param size - The figure as it is drawn on the page.
+ * @param scale - The multiple it is saved at.
+ * @returns The size in pixels, whole numbers.
+ */
+export declare function figurePixels(size: FigurePixels, scale: number): FigurePixels;
+/**
+ * Whether a browser can actually paint the figure at this multiple.
+ * @param size - The figure as it is drawn on the page.
+ * @param scale - The multiple it would be saved at.
+ * @returns Whether the file would come out.
+ */
+export declare function figureScaleFits(size: FigurePixels, scale: number): boolean;
+/**
+ * What a multiple reads on a button: `2×`.
+ * @param scale - The multiple.
+ * @returns Its label.
+ */
+export declare function figureScaleLabel(scale: number): string;
+/**
+ * What a size reads in a sentence: `1280 × 920 pixels`.
+ * @param pixels - The size of the saved file.
+ * @returns The measurement, written out.
+ */
+export declare function formatFigurePixels(pixels: FigurePixels): string;
+//# sourceMappingURL=figureScale.d.ts.map

package/lib/download/core/figureScale.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figureScale.d.ts","sourceRoot":"","sources":["../../../src/download/core/figureScale.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,6CAA6C;AAC7C,MAAM,WAAW,YAAY;IAC3B,iBAAiB;IACjB,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,2EAA2E;AAC3E,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAAiB,CAAC;AAE7D;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC;;;;;;GAMG;AACH,eAAO,MAAM,iBAAiB,QAAQ,CAAC;AAEvC;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,YAAY,CAM5E;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAK1E;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,YAAY,GAAG,MAAM,CAE/D"}

package/lib/download/core/figureScale.js

@@ -0,0 +1,67 @@
+/**
+ * How large a figure is saved.
+ *
+ * The resolution is offered as a multiple of the figure on screen rather than
+ * as a pixel width, because the multiple is the part a reader has an opinion
+ * about — one for a note, two for a slide, three or four for print — while the
+ * pixel count is the consequence, and is written out beside it so nobody has
+ * to work it out.
+ */
+/** The multiples offered, from the figure as drawn to print resolution. */
+export const FIGURE_SCALES = [1, 2, 3, 4];
+/**
+ * The multiple a figure is saved at unless the reader says otherwise.
+ *
+ * Two rather than one: a figure saved at the size it was drawn looks soft on
+ * every screen that is not the one it was drawn on, and a slide is where most
+ * of these files end up.
+ */
+export const DEFAULT_FIGURE_SCALE = 2;
+/**
+ * The longest side a browser will paint into one canvas.
+ *
+ * Past it the canvas is silently blank rather than refused, which is the worst
+ * of both — so a multiple that would cross it is offered greyed rather than
+ * left to fail after the reader has pressed save.
+ */
+export const FIGURE_MAX_PIXELS = 16384;
+/**
+ * How big the saved file is, at this multiple.
+ * @param size - The figure as it is drawn on the page.
+ * @param scale - The multiple it is saved at.
+ * @returns The size in pixels, whole numbers.
+ */
+export function figurePixels(size, scale) {
+    const factor = Number.isFinite(scale) && scale > 0 ? scale : 1;
+    return {
+        width: Math.max(1, Math.round(size.width * factor)),
+        height: Math.max(1, Math.round(size.height * factor)),
+    };
+}
+/**
+ * Whether a browser can actually paint the figure at this multiple.
+ * @param size - The figure as it is drawn on the page.
+ * @param scale - The multiple it would be saved at.
+ * @returns Whether the file would come out.
+ */
+export function figureScaleFits(size, scale) {
+    const pixels = figurePixels(size, scale);
+    return (pixels.width <= FIGURE_MAX_PIXELS && pixels.height <= FIGURE_MAX_PIXELS);
+}
+/**
+ * What a multiple reads on a button: `2×`.
+ * @param scale - The multiple.
+ * @returns Its label.
+ */
+export function figureScaleLabel(scale) {
+    return `${scale}×`;
+}
+/**
+ * What a size reads in a sentence: `1280 × 920 pixels`.
+ * @param pixels - The size of the saved file.
+ * @returns The measurement, written out.
+ */
+export function formatFigurePixels(pixels) {
+    return `${pixels.width} × ${pixels.height} pixels`;
+}
+//# sourceMappingURL=figureScale.js.map

package/lib/download/core/figureScale.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"figureScale.js","sourceRoot":"","sources":["../../../src/download/core/figureScale.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAUH,2EAA2E;AAC3E,MAAM,CAAC,MAAM,aAAa,GAAsB,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,oBAAoB,GAAG,CAAC,CAAC;AAEtC;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG,KAAK,CAAC;AAEvC;;;;;GAKG;AACH,MAAM,UAAU,YAAY,CAAC,IAAkB,EAAE,KAAa;IAC5D,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC;IAC/D,OAAO;QACL,KAAK,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,GAAG,MAAM,CAAC,CAAC;QACnD,MAAM,EAAE,IAAI,CAAC,GAAG,CAAC,CAAC,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,CAAC;KACtD,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,IAAkB,EAAE,KAAa;IAC/D,MAAM,MAAM,GAAG,YAAY,CAAC,IAAI,EAAE,KAAK,CAAC,CAAC;IACzC,OAAO,CACL,MAAM,CAAC,KAAK,IAAI,iBAAiB,IAAI,MAAM,CAAC,MAAM,IAAI,iBAAiB,CACxE,CAAC;AACJ,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,gBAAgB,CAAC,KAAa;IAC5C,OAAO,GAAG,KAAK,GAAG,CAAC;AACrB,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAoB;IACrD,OAAO,GAAG,MAAM,CAAC,KAAK,MAAM,MAAM,CAAC,MAAM,SAAS,CAAC;AACrD,CAAC"}

package/lib/download/core/figureSvg.d.ts

@@ -0,0 +1,37 @@
+/**
+ * A figure on the page, copied into a file that stands on its own.
+ *
+ * Two things have to travel with it. The tokens it is drawn from, which are
+ * declared by the site and not by the figure, so a `var()` that leaves the
+ * page resolves to nothing. And the type, which a chart inherits from the page
+ * around it and would otherwise be reset to whatever opens the file.
+ */
+/** How the figure is copied. */
+export interface FigureSvgOptions {
+    /**
+     * What is painted under it. `transparent` leaves it unpainted, which is what
+     * a figure being dropped onto a coloured slide wants.
+     * @default the surface the figure is drawn on, which is the page's own
+     */
+    background?: string;
+}
+/** A figure, as the file that leaves the page. */
+export interface FigureSvg {
+    /** The whole SVG document, tokens resolved. */
+    markup: string;
+    /** Its width in pixels, at the size the figure was drawn. */
+    width: number;
+    /** Its height. */
+    height: number;
+}
+/** What a saved SVG figure is, for the file and for the renderer reading it. */
+export declare const FIGURE_SVG_TYPE = "image/svg+xml;charset=utf-8";
+/**
+ * The figure as a standalone SVG document.
+ * @param target - The `id` of the box the figure is mounted in, or the element.
+ * @param options - See {@link FigureSvgOptions}.
+ * @returns See {@link FigureSvg}.
+ * @throws {Error} When the box holds no drawing to save.
+ */
+export declare function figureSvg(target: string | Element, options?: FigureSvgOptions): FigureSvg;
+//# sourceMappingURL=figureSvg.d.ts.map

package/lib/download/core/figureSvg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figureSvg.d.ts","sourceRoot":"","sources":["../../../src/download/core/figureSvg.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAOH,gCAAgC;AAChC,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,kDAAkD;AAClD,MAAM,WAAW,SAAS;IACxB,+CAA+C;IAC/C,MAAM,EAAE,MAAM,CAAC;IACf,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,gFAAgF;AAChF,eAAO,MAAM,eAAe,gCAAgC,CAAC;AAQ7D;;;;;;GAMG;AACH,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,GAAG,OAAO,EACxB,OAAO,GAAE,gBAAqB,GAC7B,SAAS,CAgCX"}

package/lib/download/core/figureSvg.js

@@ -0,0 +1,94 @@
+/**
+ * A figure on the page, copied into a file that stands on its own.
+ *
+ * Two things have to travel with it. The tokens it is drawn from, which are
+ * declared by the site and not by the figure, so a `var()` that leaves the
+ * page resolves to nothing. And the type, which a chart inherits from the page
+ * around it and would otherwise be reset to whatever opens the file.
+ */
+import { cssTokenNames, resolveCssTokens } from "./cssTokens.js";
+import { figureSvgDocument } from "./figureSvgDocument.js";
+import { figureBounds, figureDrawings, figureElement } from "./figureTarget.js";
+/** What a saved SVG figure is, for the file and for the renderer reading it. */
+export const FIGURE_SVG_TYPE = 'image/svg+xml;charset=utf-8';
+/** The token a figure's own ground is named by. */
+const SURFACE_TOKEN = '--surface';
+/** What a figure is painted on where the site has declared nothing. */
+const FALLBACK_SURFACE = '#ffffff';
+/**
+ * The figure as a standalone SVG document.
+ * @param target - The `id` of the box the figure is mounted in, or the element.
+ * @param options - See {@link FigureSvgOptions}.
+ * @returns See {@link FigureSvg}.
+ * @throws {Error} When the box holds no drawing to save.
+ */
+export function figureSvg(target, options = {}) {
+    const element = figureElement(target);
+    const drawings = figureDrawings(element);
+    if (drawings.length === 0) {
+        throw new Error('That part of the page holds no figure to save.');
+    }
+    const bounds = figureBounds(drawings);
+    const pieces = [];
+    for (const drawing of drawings) {
+        const box = drawing.getBoundingClientRect();
+        pieces.push({
+            markup: drawingMarkup(drawing),
+            x: box.left - bounds.left,
+            y: box.top - bounds.top,
+        });
+    }
+    const styles = window.getComputedStyle(element);
+    const markup = figureSvgDocument(pieces, {
+        width: bounds.width,
+        height: bounds.height,
+        background: options.background ?? surfaceOf(styles),
+        fontFamily: styles.fontFamily,
+        fontSize: Number.parseFloat(styles.fontSize),
+    });
+    return {
+        markup,
+        width: Math.round(bounds.width),
+        height: Math.round(bounds.height),
+    };
+}
+/**
+ * One drawing, serialized with every token it names written out.
+ *
+ * The copy is taken first and read from the original, because the values are a
+ * property of where the figure sits on the page: a detached clone inherits
+ * nothing and would resolve every token to an empty string.
+ * @param drawing - The drawing, as it sits on the page.
+ * @returns Its markup.
+ */
+function drawingMarkup(drawing) {
+    const clone = drawing.cloneNode(true);
+    const markup = new XMLSerializer().serializeToString(clone);
+    return resolveCssTokens(markup, tokenValues(drawing, cssTokenNames(markup)));
+}
+/**
+ * What each token the markup names is worth where the figure is drawn.
+ * @param drawing - The drawing, as it sits on the page.
+ * @param names - The tokens it asks for.
+ * @returns The values, keyed by token name.
+ */
+function tokenValues(drawing, names) {
+    const values = {};
+    if (names.length === 0)
+        return values;
+    const styles = window.getComputedStyle(drawing);
+    for (const name of names) {
+        values[name] = styles.getPropertyValue(name);
+    }
+    return values;
+}
+/**
+ * The ground the figure is standing on.
+ * @param styles - The computed style of the box it is mounted in.
+ * @returns The colour to paint under it.
+ */
+function surfaceOf(styles) {
+    const surface = styles.getPropertyValue(SURFACE_TOKEN).trim();
+    return surface === '' ? FALLBACK_SURFACE : surface;
+}
+//# sourceMappingURL=figureSvg.js.map

package/lib/download/core/figureSvg.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"figureSvg.js","sourceRoot":"","sources":["../../../src/download/core/figureSvg.ts"],"names":[],"mappings":"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"}

package/lib/download/core/figureSvgDocument.d.ts

@@ -0,0 +1,55 @@
+/**
+ * The one file a figure leaves the page as.
+ *
+ * A figure on the page is not always one drawing: a pair grid is sixteen
+ * charts laid out by the browser, each an `<svg>` of its own that knows
+ * nothing about where the others sit. So the saved file is a frame with each
+ * of them placed back where the reader saw it, rather than whichever one
+ * happened to be first in the document.
+ *
+ * It is assembled as text rather than as elements, so the same document comes
+ * out of a browser, a test and a server, and so the one part of the export
+ * that decides what the file *is* can be read without a DOM to run it in.
+ */
+/** One drawing on the page, and where it sits inside the saved figure. */
+export interface FigurePiece {
+    /** The `<svg>` element as it was serialized, tokens already resolved. */
+    markup: string;
+    /** Its left edge, in pixels from the left of the saved figure. */
+    x: number;
+    /** Its top edge, in pixels from the top of the saved figure. */
+    y: number;
+}
+/** How the file around the drawings is written. */
+export interface FigureSvgDocumentOptions {
+    /** Width of the whole figure, in pixels. */
+    width: number;
+    /** Its height. */
+    height: number;
+    /**
+     * What is painted under it. A figure saved with nothing behind it is a
+     * figure whose axes vanish the moment it is dropped on a dark slide, so a
+     * ground is the default and `transparent` is the deliberate choice.
+     * @default undefined — nothing is painted
+     */
+    background?: string;
+    /**
+     * The type the words are set in. A file that has left the page inherits no
+     * font from it, so the stack the figure was read in travels with it.
+     * @default undefined — the reader's own default
+     */
+    fontFamily?: string;
+    /**
+     * The size those words are set at, in pixels.
+     * @default undefined — the reader's own default
+     */
+    fontSize?: number;
+}
+/**
+ * Every drawing of a figure, in one standalone SVG document.
+ * @param pieces - The drawings, in the order they are painted.
+ * @param options - See {@link FigureSvgDocumentOptions}.
+ * @returns The document, ready to be saved or rendered.
+ */
+export declare function figureSvgDocument(pieces: readonly FigurePiece[], options: FigureSvgDocumentOptions): string;
+//# sourceMappingURL=figureSvgDocument.d.ts.map

package/lib/download/core/figureSvgDocument.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"figureSvgDocument.d.ts","sourceRoot":"","sources":["../../../src/download/core/figureSvgDocument.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,0EAA0E;AAC1E,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,CAAC,EAAE,MAAM,CAAC;IACV,gEAAgE;IAChE,CAAC,EAAE,MAAM,CAAC;CACX;AAED,mDAAmD;AACnD,MAAM,WAAW,wBAAwB;IACvC,4CAA4C;IAC5C,KAAK,EAAE,MAAM,CAAC;IACd,kBAAkB;IAClB,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB;;;OAGG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAMD;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,OAAO,EAAE,wBAAwB,GAChC,MAAM,CAkBR"}

package/lib/download/core/figureSvgDocument.js

@@ -0,0 +1,79 @@
+/**
+ * The one file a figure leaves the page as.
+ *
+ * A figure on the page is not always one drawing: a pair grid is sixteen
+ * charts laid out by the browser, each an `<svg>` of its own that knows
+ * nothing about where the others sit. So the saved file is a frame with each
+ * of them placed back where the reader saw it, rather than whichever one
+ * happened to be first in the document.
+ *
+ * It is assembled as text rather than as elements, so the same document comes
+ * out of a browser, a test and a server, and so the one part of the export
+ * that decides what the file *is* can be read without a DOM to run it in.
+ */
+/** Where an SVG document says it belongs. */
+// eslint-disable-next-line unicorn/prefer-https -- an XML namespace is a name fixed by the SVG specification, not an address anything is fetched from.
+const SVG_NAMESPACE = 'http://www.w3.org/2000/svg';
+/**
+ * Every drawing of a figure, in one standalone SVG document.
+ * @param pieces - The drawings, in the order they are painted.
+ * @param options - See {@link FigureSvgDocumentOptions}.
+ * @returns The document, ready to be saved or rendered.
+ */
+export function figureSvgDocument(pieces, options) {
+    const { width, height, background, fontFamily, fontSize } = options;
+    const box = `0 0 ${round(width)} ${round(height)}`;
+    const style = documentStyle(fontFamily, fontSize);
+    let inside = background === undefined || background === ''
+        ? ''
+        : `<rect width="100%" height="100%" fill="${escapeAttribute(background)}"/>`;
+    for (const piece of pieces) {
+        inside += `<g transform="translate(${round(piece.x)} ${round(piece.y)})">${piece.markup}</g>`;
+    }
+    return (`<?xml version="1.0" encoding="UTF-8"?>` +
+        `<svg xmlns="${SVG_NAMESPACE}" width="${round(width)}" height="${round(height)}" viewBox="${box}"${style}>` +
+        `${inside}</svg>`);
+}
+/**
+ * The type the document is set in, as an attribute or as nothing at all.
+ * @param fontFamily - The stack the figure was read in.
+ * @param fontSize - The size it was read at, in pixels.
+ * @returns The `style` attribute, with the space in front of it.
+ */
+function documentStyle(fontFamily, fontSize) {
+    const rules = [];
+    if (fontFamily !== undefined && fontFamily !== '') {
+        rules.push(`font-family:${fontFamily}`);
+    }
+    if (fontSize !== undefined && Number.isFinite(fontSize)) {
+        rules.push(`font-size:${round(fontSize)}px`);
+    }
+    return rules.length === 0
+        ? ''
+        : ` style="${escapeAttribute(rules.join(';'))}"`;
+}
+/**
+ * A number as an attribute reads it: whole pixels where it is one, and two
+ * decimals otherwise, because a serialized figure carrying sixteen digits per
+ * offset is a file twice the size for no visible difference.
+ * @param value - The measurement.
+ * @returns How it is written.
+ */
+function round(value) {
+    if (!Number.isFinite(value))
+        return 0;
+    return Math.round(value * 100) / 100;
+}
+/**
+ * A value written inside double quotes, with the three characters that would
+ * end the attribute or the tag spelled out.
+ * @param value - The value.
+ * @returns The value, safe to quote.
+ */
+function escapeAttribute(value) {
+    return value
+        .replaceAll('&', '&amp;')
+        .replaceAll('<', '&lt;')
+        .replaceAll('"', '&quot;');
+}
+//# sourceMappingURL=figureSvgDocument.js.map

package/lib/download/core/figureSvgDocument.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"figureSvgDocument.js","sourceRoot":"","sources":["../../../src/download/core/figureSvgDocument.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAsCH,6CAA6C;AAC7C,uJAAuJ;AACvJ,MAAM,aAAa,GAAG,4BAA4B,CAAC;AAEnD;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAC/B,MAA8B,EAC9B,OAAiC;IAEjC,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,UAAU,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IACpE,MAAM,GAAG,GAAG,OAAO,KAAK,CAAC,KAAK,CAAC,IAAI,KAAK,CAAC,MAAM,CAAC,EAAE,CAAC;IACnD,MAAM,KAAK,GAAG,aAAa,CAAC,UAAU,EAAE,QAAQ,CAAC,CAAC;IAElD,IAAI,MAAM,GACR,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,EAAE;QAC3C,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,0CAA0C,eAAe,CAAC,UAAU,CAAC,KAAK,CAAC;IACjF,KAAK,MAAM,KAAK,IAAI,MAAM,EAAE,CAAC;QAC3B,MAAM,IAAI,2BAA2B,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,IAAI,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,KAAK,CAAC,MAAM,MAAM,CAAC;IAChG,CAAC;IAED,OAAO,CACL,wCAAwC;QACxC,eAAe,aAAa,YAAY,KAAK,CAAC,KAAK,CAAC,aAAa,KAAK,CAAC,MAAM,CAAC,cAAc,GAAG,IAAI,KAAK,GAAG;QAC3G,GAAG,MAAM,QAAQ,CAClB,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,SAAS,aAAa,CACpB,UAA8B,EAC9B,QAA4B;IAE5B,MAAM,KAAK,GAAa,EAAE,CAAC;IAC3B,IAAI,UAAU,KAAK,SAAS,IAAI,UAAU,KAAK,EAAE,EAAE,CAAC;QAClD,KAAK,CAAC,IAAI,CAAC,eAAe,UAAU,EAAE,CAAC,CAAC;IAC1C,CAAC;IACD,IAAI,QAAQ,KAAK,SAAS,IAAI,MAAM,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE,CAAC;QACxD,KAAK,CAAC,IAAI,CAAC,aAAa,KAAK,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;IAC/C,CAAC;IACD,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC;QACvB,CAAC,CAAC,EAAE;QACJ,CAAC,CAAC,WAAW,eAAe,CAAC,KAAK,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,GAAG,CAAC;AACrD,CAAC;AAED;;;;;;GAMG;AACH,SAAS,KAAK,CAAC,KAAa;IAC1B,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC,KAAK,CAAC;QAAE,OAAO,CAAC,CAAC;IACtC,OAAO,IAAI,CAAC,KAAK,CAAC,KAAK,GAAG,GAAG,CAAC,GAAG,GAAG,CAAC;AACvC,CAAC;AAED;;;;;GAKG;AACH,SAAS,eAAe,CAAC,KAAa;IACpC,OAAO,KAAK;SACT,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC;SACxB,UAAU,CAAC,GAAG,EAAE,MAAM,CAAC;SACvB,UAAU,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;AAC/B,CAAC"}