react-cheminfo 0.9.0 → 0.11.0

package/src/download/core/figurePng.ts

@@ -0,0 +1,87 @@
+/**
+ * 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.ts';
+import type { FigureSvg } from './figureSvg.ts';
+import { FIGURE_SVG_TYPE } from './figureSvg.ts';
+
+/** 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: FigureSvg,
+  scale: number = DEFAULT_FIGURE_SCALE,
+): Promise<Blob> {
+  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: FigureSvg): Promise<HTMLImageElement> {
+  const url = URL.createObjectURL(
+    new Blob([figure.markup], { type: FIGURE_SVG_TYPE }),
+  );
+  try {
+    const image = new Image(figure.width, figure.height);
+    await new Promise<void>((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: HTMLCanvasElement): Promise<Blob> {
+  return new Promise<Blob>((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);
+  });
+}

package/src/download/core/figureScale.ts

@@ -0,0 +1,83 @@
+/**
+ * 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 const FIGURE_SCALES: readonly number[] = [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: FigurePixels, scale: number): FigurePixels {
+  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: FigurePixels, scale: number): boolean {
+  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: number): string {
+  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: FigurePixels): string {
+  return `${pixels.width} × ${pixels.height} pixels`;
+}

package/src/download/core/figureSvg.ts

@@ -0,0 +1,210 @@
+/**
+ * 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.ts';
+import type { FigureLegendMark, FigureLegendText } from './figureLegend.ts';
+import { figureLegendMarkup } from './figureLegend.ts';
+import type { FigurePiece } from './figureSvgDocument.ts';
+import { figureSvgDocument } from './figureSvgDocument.ts';
+import {
+  figureBounds,
+  figureDrawings,
+  figureElement,
+  figureLegends,
+} from './figureTarget.ts';
+
+/** 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 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: string | Element,
+  options: FigureSvgOptions = {},
+): FigureSvg {
+  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: FigurePiece[] = [];
+  for (const drawing of drawings) {
+    const box = drawing.getBoundingClientRect();
+    pieces.push({
+      markup: drawingMarkup(drawing),
+      x: box.left - bounds.left,
+      y: box.top - bounds.top,
+    });
+  }
+
+  for (const legend of figureLegends(element)) {
+    const box = legend.getBoundingClientRect();
+    if (box.width <= 0 || box.height <= 0) continue;
+    pieces.push({
+      markup: legendMarkup(legend, box),
+      x: box.left - bounds.left,
+      y: box.top - bounds.top,
+      kind: 'legend',
+    });
+  }
+
+  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 key, measured off the page and painted as SVG.
+ *
+ * Everything is read from where the browser put it — the card's own ground and
+ * corner, each mark's box, each run of words and the type it is set in — so
+ * the copy in the file is the card the reader was looking at, folding and all.
+ * The ground is painted at full strength however faint the card had gone on
+ * screen: a key that fades when the pointer leaves the figure is a property of
+ * pointing at it, not of the figure.
+ * @param legend - The card, as it sits on the page.
+ * @param box - Its box, so the pieces inside it can be placed against it.
+ * @returns Its markup, in the card's own coordinates.
+ */
+function legendMarkup(legend: Element, box: DOMRect): string {
+  const ground = legend.firstElementChild;
+  const styles = ground === null ? undefined : window.getComputedStyle(ground);
+
+  const marks: FigureLegendMark[] = [];
+  for (const mark of legend.querySelectorAll('svg')) {
+    const at = mark.getBoundingClientRect();
+    marks.push({
+      markup: drawingMarkup(mark),
+      x: at.left - box.left,
+      y: at.top - box.top,
+    });
+  }
+
+  const texts: FigureLegendText[] = [];
+  for (const run of legend.querySelectorAll('*')) {
+    if (run.firstElementChild !== null) continue;
+    const words = run.textContent?.trim() ?? '';
+    if (words === '') continue;
+    const at = run.getBoundingClientRect();
+    const type = window.getComputedStyle(run);
+    texts.push({
+      text: words,
+      x: at.left - box.left,
+      y: at.top - box.top + at.height / 2,
+      color: type.color,
+      fontSize: Number.parseFloat(type.fontSize),
+      fontWeight: type.fontWeight,
+    });
+  }
+
+  return figureLegendMarkup({
+    card: {
+      width: box.width,
+      height: box.height,
+      radius:
+        styles === undefined
+          ? 0
+          : Number.parseFloat(styles.borderTopLeftRadius),
+      background: styles?.backgroundColor,
+      border: styles?.borderTopColor,
+      borderWidth:
+        styles === undefined ? 1 : Number.parseFloat(styles.borderTopWidth),
+    },
+    marks,
+    texts,
+  });
+}
+
+/**
+ * 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: SVGSVGElement): string {
+  const clone = drawing.cloneNode(true) as SVGSVGElement;
+  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: SVGSVGElement,
+  names: readonly string[],
+): Record<string, string> {
+  const values: Record<string, string> = {};
+  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: CSSStyleDeclaration): string {
+  const surface = styles.getPropertyValue(SURFACE_TOKEN).trim();
+  return surface === '' ? FALLBACK_SURFACE : surface;
+}

package/src/download/core/figureSvgDocument.ts

@@ -0,0 +1,139 @@
+/**
+ * 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 piece of the page, and where it sits inside the saved figure. */
+export interface FigurePiece {
+  /** The markup, 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;
+  /**
+   * What it is. Written into the file, so a reader — a test, or somebody
+   * editing the figure afterwards — can tell the drawings from the key that
+   * was painted over them.
+   * @default 'drawing'
+   */
+  kind?: 'drawing' | 'legend';
+}
+
+/** 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;
+}
+
+/** 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: readonly FigurePiece[],
+  options: FigureSvgDocumentOptions,
+): string {
+  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) {
+    const kind = piece.kind ?? 'drawing';
+    inside +=
+      `<g data-figure="${kind}" 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: string | undefined,
+  fontSize: number | undefined,
+): string {
+  const rules: string[] = [];
+  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: number): number {
+  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: string): string {
+  return value
+    .replaceAll('&', '&amp;')
+    .replaceAll('<', '&lt;')
+    .replaceAll('"', '&quot;');
+}

package/src/download/core/figureTarget.ts

@@ -0,0 +1,151 @@
+/**
+ * Finding the drawings inside whatever the caller pointed at.
+ *
+ * A caller names a figure by the `id` of the box it is mounted in — never by
+ * handing over an element it had to hold a ref to — because the box is
+ * something a page already has a name for, and because the thing that saves
+ * the figure is then free to sit anywhere on the page rather than inside the
+ * component that drew it.
+ */
+
+import type { FigurePixels } from './figureScale.ts';
+
+/** Chrome floating over a figure, which is not part of the picture. */
+const CHROME = '[data-figure="chrome"]';
+
+/** A key floating over a figure, which is. */
+const LEGEND = '[data-figure="legend"]';
+
+/** A figure's box on the page, in the coordinates a bounding box reports. */
+export interface FigureBounds {
+  /** Its left edge. */
+  left: number;
+  /** Its top edge. */
+  top: number;
+  /** Its width. */
+  width: number;
+  /** Its height. */
+  height: number;
+}
+
+/**
+ * The element a caller named.
+ * @param target - The `id` of the box the figure is mounted in, or the element
+ *   itself.
+ * @returns The element.
+ * @throws {Error} When no element on the page carries that `id`.
+ */
+export function figureElement(target: string | Element): Element {
+  if (typeof target !== 'string') return target;
+  // Escaped, because the ids React generates are not bare identifiers: a raw
+  // `#«r3»-panel` is not a selector any browser will parse.
+  const element = document.querySelector(`#${CSS.escape(target)}`);
+  if (element === null) {
+    throw new Error(`No element with the id ${target} to save.`);
+  }
+  return element;
+}
+
+/**
+ * The drawings inside it, in the order they are painted.
+ *
+ * What is collected is every `<svg>` that is part of the picture: one for a
+ * plain chart, sixteen for a pair grid. The glyphs of the controls floating
+ * over a figure are `<svg>` too, so anything inside an element marked as
+ * chrome is left behind — a cog saved into the middle of a scatter plot is the
+ * bug this exists to prevent. A drawing with no area is left behind as well,
+ * because a tab that is not showing is still in the document.
+ * @param element - The box the figure is mounted in.
+ * @returns The drawings.
+ */
+export function figureDrawings(element: Element): readonly SVGSVGElement[] {
+  if (element.tagName.toLowerCase() === 'svg') {
+    return [element as SVGSVGElement];
+  }
+  const drawings: SVGSVGElement[] = [];
+  for (const drawing of element.querySelectorAll('svg')) {
+    if (drawing.closest(CHROME) !== null) continue;
+    if (isNested(drawings, drawing)) continue;
+    const box = drawing.getBoundingClientRect();
+    if (box.width <= 0 || box.height <= 0) continue;
+    drawings.push(drawing);
+  }
+  return drawings;
+}
+
+/**
+ * The keys inside it.
+ *
+ * A key is chrome — it is a filter the reader presses — and is therefore not
+ * among the drawings, but it is still part of the picture: a saved figure
+ * whose colours stand for nothing is not a figure. So it is collected
+ * separately, to be redrawn over the drawings rather than copied with them.
+ * @param element - The box the figure is mounted in.
+ * @returns The keys, in the order they are painted.
+ */
+export function figureLegends(element: Element): readonly Element[] {
+  const legends: Element[] = [];
+  for (const legend of element.querySelectorAll(LEGEND)) {
+    legends.push(legend);
+  }
+  return legends;
+}
+
+/**
+ * The box every drawing of a figure fits in.
+ * @param drawings - The drawings, as they sit on the page.
+ * @returns The box, or one with no area where there are no drawings.
+ */
+export function figureBounds(drawings: readonly SVGSVGElement[]): FigureBounds {
+  let left = Number.POSITIVE_INFINITY;
+  let top = Number.POSITIVE_INFINITY;
+  let right = Number.NEGATIVE_INFINITY;
+  let bottom = Number.NEGATIVE_INFINITY;
+  for (const drawing of drawings) {
+    const box = drawing.getBoundingClientRect();
+    if (box.left < left) left = box.left;
+    if (box.top < top) top = box.top;
+    if (box.right > right) right = box.right;
+    if (box.bottom > bottom) bottom = box.bottom;
+  }
+  if (!Number.isFinite(left) || !Number.isFinite(top)) {
+    return { left: 0, top: 0, width: 0, height: 0 };
+  }
+  return { left, top, width: right - left, height: bottom - top };
+}
+
+/**
+ * How big the saved figure would be at its own size, for a control that has to
+ * write the resulting file size before anybody presses save.
+ * @param target - The `id` of the box the figure is mounted in, or the element.
+ * @returns The size in pixels, or `null` where there is nothing to save.
+ */
+export function figureSize(target: string | Element): FigurePixels | null {
+  let bounds: FigureBounds;
+  try {
+    bounds = figureBounds(figureDrawings(figureElement(target)));
+  } catch {
+    return null;
+  }
+  if (bounds.width <= 0 || bounds.height <= 0) return null;
+  return {
+    width: Math.round(bounds.width),
+    height: Math.round(bounds.height),
+  };
+}
+
+/**
+ * Whether a drawing already sits inside one that was taken.
+ * @param taken - The drawings collected so far.
+ * @param drawing - The one being considered.
+ * @returns Whether it is already part of the figure.
+ */
+function isNested(
+  taken: readonly SVGSVGElement[],
+  drawing: SVGSVGElement,
+): boolean {
+  for (const other of taken) {
+    if (other.contains(drawing)) return true;
+  }
+  return false;
+}