react-cheminfo 0.8.0 → 0.10.0

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,130 @@
+/**
+ * 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 { FigurePiece } from './figureSvgDocument.ts';
+import { figureSvgDocument } from './figureSvgDocument.ts';
+import { figureBounds, figureDrawings, figureElement } 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,
+    });
+  }
+
+  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: 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,129 @@
+/**
+ * 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;
+}
+
+/** 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) {
+    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: 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,130 @@
+/**
+ * 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 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 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;
+}

package/src/download/core/index.ts

@@ -1,3 +1,31 @@
+export { cssTokenNames, resolveCssTokens } from './cssTokens.ts';
 export { downloadBlob } from './downloadBlob.ts';
+export type { DownloadFigureOptions, FigureFormat } from './downloadFigure.ts';
+export { downloadFigure } from './downloadFigure.ts';
 export { downloadText } from './downloadText.ts';
+export { FIGURE_PNG_TYPE, figurePng } from './figurePng.ts';
+export type { FigurePixels } from './figureScale.ts';
+export {
+  DEFAULT_FIGURE_SCALE,
+  FIGURE_MAX_PIXELS,
+  FIGURE_SCALES,
+  figurePixels,
+  figureScaleFits,
+  figureScaleLabel,
+  formatFigurePixels,
+} from './figureScale.ts';
+export type { FigureSvg, FigureSvgOptions } from './figureSvg.ts';
+export { FIGURE_SVG_TYPE, figureSvg } from './figureSvg.ts';
+export type {
+  FigurePiece,
+  FigureSvgDocumentOptions,
+} from './figureSvgDocument.ts';
+export { figureSvgDocument } from './figureSvgDocument.ts';
+export type { FigureBounds } from './figureTarget.ts';
+export {
+  figureBounds,
+  figureDrawings,
+  figureElement,
+  figureSize,
+} from './figureTarget.ts';
 export { sanitizeFileName } from './sanitizeFileName.ts';

package/src/download/ui/FigureDownload.tsx

@@ -0,0 +1,158 @@
+import type { IconName } from '@blueprintjs/core';
+import { PopoverNext } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+import { useState } from 'react';
+
+import { OverlayIconButton } from '../../overlay/ui/OverlayIconButton.tsx';
+import type { FigureFormat } from '../core/downloadFigure.ts';
+import { downloadFigure } from '../core/downloadFigure.ts';
+import type { FigurePixels } from '../core/figureScale.ts';
+import { DEFAULT_FIGURE_SCALE, FIGURE_SCALES } from '../core/figureScale.ts';
+import { figureSize } from '../core/figureTarget.ts';
+
+import { FigureDownloadPanel } from './FigureDownloadPanel.tsx';
+
+/** What {@link FigureDownload} needs. */
+export interface FigureDownloadProps {
+  /**
+   * The `id` of the box the figure is mounted in. Everything drawn inside it
+   * is saved — sixteen charts of a pair grid as readily as one scatter plot —
+   * and the controls floating over it are left behind.
+   */
+  targetId: string;
+  /**
+   * What the saved file is called, without its extension. Name it after the
+   * data rather than after the tool: a reader with four of these in a
+   * downloads folder cannot tell four `figure.png` apart.
+   * @default 'figure'
+   */
+  fileName?: string;
+  /**
+   * The format it opens on.
+   * @default 'png'
+   */
+  defaultFormat?: FigureFormat;
+  /**
+   * The resolution it opens on, as a multiple of the figure on screen.
+   * @default 2
+   */
+  defaultScale?: number;
+  /**
+   * The resolutions offered.
+   * @default [1, 2, 3, 4]
+   */
+  scales?: readonly number[];
+  /**
+   * What is painted under the figure. `transparent` leaves it unpainted, for a
+   * figure going onto a coloured slide.
+   * @default the surface the figure is drawn on
+   */
+  background?: string;
+  /**
+   * What the glyph is called, for the pointer and for a screen reader.
+   * @default 'Save this figure'
+   */
+  label?: string;
+  /**
+   * What the panel behind it is called.
+   * @default 'Save figure'
+   */
+  title?: string;
+  /**
+   * Its glyph.
+   * @default 'download'
+   */
+  icon?: IconName;
+  /**
+   * Value of the `data-testid` attribute of the glyph.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * The glyph that takes the figure off the page as a file.
+ *
+ * It works from the `id` of the box the figure is mounted in rather than from
+ * the figure itself, so the control is free to sit in the bar above the
+ * picture — or anywhere else on the page — without the component that drew the
+ * figure having to hand anything over. That is also what lets one control save
+ * a view that is really several charts: whatever is inside the box is what is
+ * saved.
+ *
+ * Both formats are offered because they answer different questions. An SVG is
+ * the figure itself, sharp at any size and still editable, which is what a
+ * paper wants; a PNG is a picture of it, which is what every chat window and
+ * slide deck accepts. The resolution belongs to the second alone, and the
+ * panel writes out the pixels it is about to produce so nobody has to guess
+ * what `3×` means for the figure in front of them.
+ * @param props - See {@link FigureDownloadProps}.
+ * @returns The glyph and its panel.
+ */
+export function FigureDownload(props: FigureDownloadProps): ReactElement {
+  const { targetId, fileName, background, scales = FIGURE_SCALES } = props;
+  const { defaultFormat = 'png', defaultScale = DEFAULT_FIGURE_SCALE } = props;
+  const { label = 'Save this figure', title = 'Save figure' } = props;
+  const { icon = 'download', testId } = props;
+
+  const [open, setOpen] = useState(false);
+  const [format, setFormat] = useState<FigureFormat>(defaultFormat);
+  const [scale, setScale] = useState(defaultScale);
+  const [size, setSize] = useState<FigurePixels | null>(null);
+  const [failure, setFailure] = useState<string | null>(null);
+  const [saving, setSaving] = useState(false);
+
+  // The panel is held open from here rather than left to itself, because the
+  // figure has to be measured at the moment it opens: its size is what the
+  // panel writes out, and reading a bounding box on every render would cost a
+  // layout pass on a bar that is re-rendered on every pointer move.
+  function interact(next: boolean): void {
+    setOpen(next);
+    if (!next) return;
+    setSize(figureSize(targetId));
+    setFailure(null);
+  }
+
+  async function save(): Promise<void> {
+    setSaving(true);
+    try {
+      await downloadFigure(targetId, { format, scale, fileName, background });
+      setFailure(null);
+    } catch (error) {
+      setFailure(error instanceof Error ? error.message : String(error));
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  return (
+    <PopoverNext
+      isOpen={open}
+      placement="bottom-end"
+      onInteraction={interact}
+      content={
+        <FigureDownloadPanel
+          title={title}
+          format={format}
+          scale={scale}
+          scales={scales}
+          size={size}
+          failure={failure}
+          saving={saving}
+          onFormatChange={setFormat}
+          onScaleChange={setScale}
+          onSave={() => void save()}
+        />
+      }
+    >
+      <OverlayIconButton
+        icon={icon}
+        label={label}
+        value={format.toUpperCase()}
+        active={open}
+        testId={testId}
+        opensMenu
+      />
+    </PopoverNext>
+  );
+}