react-cheminfo 0.29.0 → 0.31.0

package/src/download/core/downloadFigure.ts

@@ -4,13 +4,13 @@
  * 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.
+ * slide deck and issue tracker actually accepts. So both are offered. The
+ * resolution paints a PNG with more pixels, and makes an SVG open larger.
  */
 
 import { downloadBlob } from './downloadBlob.ts';
 import { figurePng } from './figurePng.ts';
-import { DEFAULT_FIGURE_SCALE } from './figureScale.ts';
+import { defaultFigureScale } from './figureScale.ts';
 import type { FigureSvgOptions } from './figureSvg.ts';
 import { FIGURE_SVG_TYPE, figureSvg } from './figureSvg.ts';
 import { sanitizeFileName } from './sanitizeFileName.ts';
@@ -26,9 +26,11 @@ export interface DownloadFigureOptions extends FigureSvgOptions {
    */
   format?: FigureFormat;
   /**
-   * How many pixels are painted per pixel on screen. An SVG ignores it: it
-   * carries no resolution of its own.
-   * @default 2
+   * How many pixels are painted per pixel on screen. An SVG is drawn the same
+   * and opens this many times larger, which is the size a slide or a word
+   * processor places it at.
+   * @default 2 for a PNG, 1 for an SVG — which then opens at the size it has
+   * on screen
    */
   scale?: number;
   /**
@@ -51,16 +53,17 @@ export async function downloadFigure(
   target: string | Element,
   options: DownloadFigureOptions = {},
 ): Promise<void> {
-  const { format = 'png', scale = DEFAULT_FIGURE_SCALE } = options;
-  const { fileName = DEFAULT_FILE_NAME, background } = options;
+  const { format = 'png', fileName = DEFAULT_FILE_NAME, background } = options;
+  const scale = options.scale ?? defaultFigureScale(format);
 
-  const figure = figureSvg(target, { background });
   const name = sanitizeFileName(fileName, DEFAULT_FILE_NAME);
 
   if (format === 'svg') {
+    const figure = figureSvg(target, { background, scale });
     const blob = new Blob([figure.markup], { type: FIGURE_SVG_TYPE });
     downloadBlob(blob, `${name}.svg`);
     return;
   }
+  const figure = figureSvg(target, { background });
   downloadBlob(await figurePng(figure, scale), `${name}.png`);
 }

package/src/download/core/figureLayout.ts

@@ -0,0 +1,114 @@
+/**
+ * The shape a figure is drawn at before it is saved.
+ *
+ * A saved figure is the drawing the reader is looking at, so its proportions
+ * are the proportions of the box it sits in. The resolution scales that
+ * drawing — more pixels for a PNG, a larger page for an SVG — but leaves its
+ * shape, and the size of its words against its axes, exactly as they were. A
+ * figure for a slide or for a journal column wants another shape, and the only
+ * way to give it one is to draw it again at that size, so its axes and labels
+ * are laid out for the new box rather than stretched into it.
+ */
+
+import type { FigurePixels } from './figureScale.ts';
+
+/** The shapes a figure can be drawn at for a file. */
+export type FigureLayout = 'screen' | 'standard' | 'wide' | 'column' | 'custom';
+
+/** The shapes, in the order they are offered. */
+export const FIGURE_LAYOUTS = [
+  'screen',
+  'standard',
+  'wide',
+  'column',
+  'custom',
+] as const satisfies readonly FigureLayout[];
+
+/**
+ * How wide a journal's single column is, in CSS pixels: 8.5 cm at 96 pixels
+ * per inch. A figure laid out at that width prints its text at the size it is
+ * read at on screen, a 12 px label becoming a 9 pt one.
+ */
+export const FIGURE_COLUMN_WIDTH = 321;
+
+/** The narrowest side a figure is drawn at, below which no chart has room for its axes. */
+export const FIGURE_LAYOUT_MIN = 120;
+
+/** The widest side a figure is drawn at: past it the page would be laying out a poster. */
+export const FIGURE_LAYOUT_MAX = 4096;
+
+/**
+ * The size a figure is drawn at, in the shape the reader picked.
+ *
+ * The two slide shapes keep the width of the figure on screen and change its
+ * height, since the width is what a page already gave it. The journal column
+ * does the reverse: its width is fixed by the journal, and the figure keeps
+ * the proportions it has on screen.
+ * @param layout - The shape picked.
+ * @param screen - The figure as it is drawn on the page.
+ * @param custom - The size typed in, read only for `custom`. Defaults to the
+ *   figure on screen.
+ * @returns The size to draw it at, in whole pixels.
+ */
+export function figureLayoutSize(
+  layout: FigureLayout,
+  screen: FigurePixels,
+  custom: FigurePixels = screen,
+): FigurePixels {
+  switch (layout) {
+    case 'standard':
+      return sized(screen.width, (screen.width * 3) / 4);
+    case 'wide':
+      return sized(screen.width, (screen.width * 9) / 16);
+    case 'column':
+      return sized(
+        FIGURE_COLUMN_WIDTH,
+        (FIGURE_COLUMN_WIDTH * screen.height) / Math.max(screen.width, 1),
+      );
+    case 'custom':
+      return sized(custom.width, custom.height);
+    case 'screen':
+      return { width: screen.width, height: screen.height };
+    default:
+      throw new Error(`unknown figure layout: ${String(layout)}`);
+  }
+}
+
+/**
+ * One side, held to the range a figure can be drawn at.
+ * @param value - What was asked for, typed or computed.
+ * @returns A whole number of pixels, inside the range.
+ */
+export function figureLayoutSide(value: number): number {
+  if (!Number.isFinite(value)) return FIGURE_LAYOUT_MIN;
+  return Math.min(
+    FIGURE_LAYOUT_MAX,
+    Math.max(FIGURE_LAYOUT_MIN, Math.round(value)),
+  );
+}
+
+/**
+ * Whether a figure is drawn again for the file, rather than copied as it is.
+ * @param layout - The shape picked.
+ * @param screen - The figure as it is drawn on the page.
+ * @param custom - The size typed in.
+ * @returns Whether the size differs from the one on screen.
+ */
+export function figureLayoutRedraws(
+  layout: FigureLayout,
+  screen: FigurePixels,
+  custom?: FigurePixels,
+): boolean {
+  const drawn = figureLayoutSize(layout, screen, custom);
+  return drawn.width !== screen.width || drawn.height !== screen.height;
+}
+
+/**
+ * A size, both sides held to the range.
+ * @param width - The width asked for.
+ * @param height - The height asked for.
+ * @returns The size.
+ */
+function sized(width: number, height: number): FigurePixels {
+  return { width: figureLayoutSide(width), height: figureLayoutSide(height) };
+}

package/src/download/core/figureScale.ts

@@ -8,6 +8,8 @@
  * to work it out.
  */
 
+import type { FigureFormat } from './downloadFigure.ts';
+
 /** The size of a saved figure, in pixels. */
 export interface FigurePixels {
   /** Its width. */
@@ -28,6 +30,17 @@ export const FIGURE_SCALES: readonly number[] = [1, 2, 3, 4];
  */
 export const DEFAULT_FIGURE_SCALE = 2;
 
+/**
+ * The multiple a figure is saved at in this format unless the reader says
+ * otherwise. An SVG stays sharp however large it is shown, so it opens at the
+ * size it has on screen; a PNG is painted twice over, for a slide.
+ * @param format - The file being written.
+ * @returns The multiple.
+ */
+export function defaultFigureScale(format: FigureFormat): number {
+  return format === 'svg' ? 1 : DEFAULT_FIGURE_SCALE;
+}
+
 /**
  * The longest side a browser will paint into one canvas.
  *

package/src/download/core/figureSettle.ts

@@ -0,0 +1,112 @@
+/**
+ * Knowing when a figure drawn for a file has finished drawing.
+ *
+ * A chart mounted off the page to be saved at another size does not arrive in
+ * one piece: it may render once at a guessed size, measure its box, and render
+ * again, and a chart behind a lazy import arrives whenever its chunk does. So
+ * nothing here waits a fixed time. The figure is watched frame by frame, and
+ * it is taken the moment it has stood still for two frames running.
+ */
+
+import { figureSize } from './figureTarget.ts';
+
+/** How the wait is run. */
+export interface FigureSettleOptions {
+  /**
+   * Stops the wait, for a panel closed or a page left while the figure is
+   * still drawing.
+   * @default undefined — the wait runs to its end
+   */
+  signal?: AbortSignal;
+  /**
+   * How many frames the figure is given to settle before the save is given
+   * up, about ten seconds at sixty frames a second. It is how a figure that
+   * never draws is reported, not how long a slow one is expected to take.
+   * @default 600
+   */
+  maxFrames?: number;
+  /**
+   * Resolves at the next frame.
+   * @default the browser's `requestAnimationFrame`
+   */
+  nextFrame?: () => Promise<void>;
+}
+
+/** How many frames in a row the figure has to hold still. */
+const STILL_FRAMES = 2;
+
+/** What {@link FigureSettleOptions.maxFrames} is unless the caller says. */
+const DEFAULT_MAX_FRAMES = 600;
+
+/**
+ * Wait until the figure mounted in a box has finished drawing.
+ * @param element - The box the figure is being drawn in.
+ * @param options - See {@link FigureSettleOptions}.
+ * @returns Resolves once the figure has stood still.
+ * @throws {Error} When the wait is stopped, or the figure never settles.
+ */
+export async function whenFigureSettles(
+  element: Element,
+  options: FigureSettleOptions = {},
+): Promise<void> {
+  let changes = 0;
+  const observer = new MutationObserver(() => {
+    changes++;
+  });
+  observer.observe(element, {
+    subtree: true,
+    childList: true,
+    attributes: true,
+    characterData: true,
+  });
+  try {
+    await settle(() => {
+      const size = figureSize(element);
+      return size === null ? null : `${changes}:${size.width}×${size.height}`;
+    }, options);
+  } finally {
+    observer.disconnect();
+  }
+}
+
+/**
+ * Wait until a reading of the figure comes back the same frames in a row.
+ *
+ * The reading is whatever says the figure has changed — for a drawing on the
+ * page, how many times it was touched and the size it came out at — and
+ * `null` while there is nothing drawn yet.
+ * @param read - Takes the reading.
+ * @param options - See {@link FigureSettleOptions}.
+ * @returns Resolves once the reading has held.
+ * @throws {Error} When the wait is stopped, or the reading never holds.
+ */
+export async function settle(
+  read: () => string | null,
+  options: FigureSettleOptions = {},
+): Promise<void> {
+  const { signal, maxFrames = DEFAULT_MAX_FRAMES } = options;
+  const { nextFrame = animationFrame } = options;
+
+  let last: string | null = null;
+  let still = 0;
+  for (let frame = 0; frame < maxFrames; frame++) {
+    // eslint-disable-next-line no-await-in-loop -- each frame is compared with the one before it
+    await nextFrame();
+    if (signal?.aborted) throw new Error('The figure was not saved.');
+    const reading = read();
+    still = reading !== null && reading === last ? still + 1 : 0;
+    if (still >= STILL_FRAMES) return;
+    last = reading;
+  }
+  throw new Error('The figure did not finish drawing, so nothing was saved.');
+}
+
+/**
+ * The next frame the browser paints.
+ * @returns Resolves at that frame.
+ */
+function animationFrame(): Promise<void> {
+  return new Promise((resolve) => {
+    requestAnimationFrame(() => resolve());
+  });
+}

package/src/download/core/figureSvg.ts

@@ -27,13 +27,19 @@ export interface FigureSvgOptions {
    * @default the surface the figure is drawn on, which is the page's own
    */
   background?: string;
+  /**
+   * How many times the figure on screen the document says it is. The drawing
+   * is unchanged; only the size the file opens at grows.
+   * @default 1
+   */
+  scale?: number;
 }
 
 /** 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. */
+  /** Its width in pixels, at the size the figure was drawn on screen. */
   width: number;
   /** Its height. */
   height: number;
@@ -94,6 +100,7 @@ export function figureSvg(
     background: options.background ?? surfaceOf(styles),
     fontFamily: styles.fontFamily,
     fontSize: Number.parseFloat(styles.fontSize),
+    scale: options.scale,
   });
 
   return {

package/src/download/core/figureSvgDocument.ts

@@ -53,6 +53,13 @@ export interface FigureSvgDocumentOptions {
    * @default undefined — the reader's own default
    */
   fontSize?: number;
+  /**
+   * How many times the figure on screen the document says it is. Only the
+   * size it opens at changes — the drawing keeps its own coordinates, so every
+   * line and every word grows together and stays as sharp as before.
+   * @default 1
+   */
+  scale?: number;
 }
 
 /** Where an SVG document says it belongs. */
@@ -69,7 +76,8 @@ export function figureSvgDocument(
   pieces: readonly FigurePiece[],
   options: FigureSvgDocumentOptions,
 ): string {
-  const { width, height, background, fontFamily, fontSize } = options;
+  const { width, height, background, fontFamily, fontSize, scale } = options;
+  const factor = positiveOrOne(scale);
   const box = `0 0 ${round(width)} ${round(height)}`;
   const style = documentStyle(fontFamily, fontSize);
 
@@ -86,7 +94,7 @@ export function figureSvgDocument(
 
   return (
     `<?xml version="1.0" encoding="UTF-8"?>` +
-    `<svg xmlns="${SVG_NAMESPACE}" width="${round(width)}" height="${round(height)}" viewBox="${box}"${style}>` +
+    `<svg xmlns="${SVG_NAMESPACE}" width="${round(width * factor)}" height="${round(height * factor)}" viewBox="${box}"${style}>` +
     `${inside}</svg>`
   );
 }
@@ -113,6 +121,15 @@ function documentStyle(
     : ` style="${escapeAttribute(rules.join(';'))}"`;
 }
 
+/**
+ * A multiple that makes sense, or one.
+ * @param value - The multiple asked for.
+ * @returns It, where it is a positive number; one otherwise.
+ */
+function positiveOrOne(value: number | undefined): number {
+  return value !== undefined && Number.isFinite(value) && value > 0 ? value : 1;
+}
+
 /**
  * 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

package/src/download/core/index.ts

@@ -3,12 +3,25 @@ export { downloadBlob } from './downloadBlob.ts';
 export type { DownloadFigureOptions, FigureFormat } from './downloadFigure.ts';
 export { downloadFigure } from './downloadFigure.ts';
 export { downloadText } from './downloadText.ts';
+export type { FigureLayout } from './figureLayout.ts';
+export {
+  FIGURE_COLUMN_WIDTH,
+  FIGURE_LAYOUTS,
+  FIGURE_LAYOUT_MAX,
+  FIGURE_LAYOUT_MIN,
+  figureLayoutRedraws,
+  figureLayoutSide,
+  figureLayoutSize,
+} from './figureLayout.ts';
 export { FIGURE_PNG_TYPE, figurePng } from './figurePng.ts';
+export type { FigureSettleOptions } from './figureSettle.ts';
+export { whenFigureSettles } from './figureSettle.ts';
 export type { FigurePixels } from './figureScale.ts';
 export {
   DEFAULT_FIGURE_SCALE,
   FIGURE_MAX_PIXELS,
   FIGURE_SCALES,
+  defaultFigureScale,
   figurePixels,
   figureScaleFits,
   figureScaleLabel,

package/src/download/ui/FigureDownload.tsx

@@ -7,11 +7,19 @@ import { useChromeT } from '../../i18n/ui/useT.ts';
 import { OverlayIconButton } from '../../overlay/ui/OverlayIconButton.tsx';
 import type { FigureFormat } from '../core/downloadFigure.ts';
 import { downloadFigure } from '../core/downloadFigure.ts';
+import type { FigureLayout } from '../core/figureLayout.ts';
+import { figureLayoutRedraws, figureLayoutSize } from '../core/figureLayout.ts';
 import type { FigurePixels } from '../core/figureScale.ts';
-import { DEFAULT_FIGURE_SCALE, FIGURE_SCALES } from '../core/figureScale.ts';
+import {
+  DEFAULT_FIGURE_SCALE,
+  FIGURE_SCALES,
+  defaultFigureScale,
+} from '../core/figureScale.ts';
 import { figureSize } from '../core/figureTarget.ts';
 
 import { FigureDownloadPanel } from './FigureDownloadPanel.tsx';
+import type { FigureRenderer } from './useFigureRedraw.tsx';
+import { useFigureRedraw } from './useFigureRedraw.tsx';
 
 /** What {@link FigureDownload} needs. */
 export interface FigureDownloadProps {
@@ -34,7 +42,9 @@ export interface FigureDownloadProps {
    */
   defaultFormat?: FigureFormat;
   /**
-   * The resolution it opens on, as a multiple of the figure on screen.
+   * The resolution a PNG opens on, as a multiple of the figure on screen. An
+   * SVG opens at 1×, the size it has on screen, and each format keeps the
+   * multiple the reader last picked for it.
    * @default 2
    */
   defaultScale?: number;
@@ -69,6 +79,16 @@ export interface FigureDownloadProps {
    * @default undefined
    */
   testId?: string;
+  /**
+   * Draws the figure at a size, for a file. When it is given the panel offers
+   * a size — as shown, 4:3, 16:9, a journal column, or typed — and a figure
+   * saved at a size other than its own is drawn again at that size, off the
+   * page, so its axes and labels are laid out for the new shape rather than
+   * stretched into it. Draw exactly what is on screen, with the same data,
+   * zoom and colours; only the box changes.
+   * @default undefined — the figure is saved at the size it has on screen
+   */
+  renderFigure?: FigureRenderer;
 }
 
 /**
@@ -84,9 +104,10 @@ export interface FigureDownloadProps {
  * 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.
+ * slide deck accepts. The resolution paints a PNG with more pixels and makes
+ * an SVG open larger, and the panel writes out the size 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.
  */
@@ -94,15 +115,22 @@ export function FigureDownload(props: FigureDownloadProps): ReactElement {
   const { targetId, fileName, background, scales = FIGURE_SCALES } = props;
   const { defaultFormat = 'png', defaultScale = DEFAULT_FIGURE_SCALE } = props;
   const { label, title } = props;
-  const { icon = 'download', testId } = props;
+  const { icon = 'download', testId, renderFigure } = props;
 
   const t = useChromeT();
   const [open, setOpen] = useState(false);
   const [format, setFormat] = useState<FigureFormat>(defaultFormat);
-  const [scale, setScale] = useState(defaultScale);
+  const [picked, setPicked] = useState<Record<FigureFormat, number>>(() => ({
+    png: defaultScale,
+    svg: defaultFigureScale('svg'),
+  }));
+  const scale = picked[format];
   const [size, setSize] = useState<FigurePixels | null>(null);
   const [failure, setFailure] = useState<string | null>(null);
   const [saving, setSaving] = useState(false);
+  const [layout, setLayout] = useState<FigureLayout>('screen');
+  const [custom, setCustom] = useState<FigurePixels | null>(null);
+  const { redraw, portal } = useFigureRedraw(renderFigure);
 
   // 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
@@ -118,7 +146,17 @@ export function FigureDownload(props: FigureDownloadProps): ReactElement {
   async function save(): Promise<void> {
     setSaving(true);
     try {
-      await downloadFigure(targetId, { format, scale, fileName, background });
+      const options = { format, scale, fileName, background };
+      if (
+        renderFigure !== undefined &&
+        size !== null &&
+        figureLayoutRedraws(layout, size, custom ?? size)
+      ) {
+        const drawn = figureLayoutSize(layout, size, custom ?? size);
+        await redraw(targetId, drawn, (box) => downloadFigure(box, options));
+      } else {
+        await downloadFigure(targetId, options);
+      }
       setFailure(null);
     } catch (error) {
       setFailure(error instanceof Error ? error.message : String(error));
@@ -128,33 +166,48 @@ export function FigureDownload(props: FigureDownloadProps): ReactElement {
   }
 
   return (
-    <PopoverNext
-      isOpen={open}
-      placement="bottom-end"
-      onInteraction={interact}
-      content={
-        <FigureDownloadPanel
-          title={title ?? t('download.saveFigure')}
-          format={format}
-          scale={scale}
-          scales={scales}
-          size={size}
-          failure={failure}
-          saving={saving}
-          onFormatChange={setFormat}
-          onScaleChange={setScale}
-          onSave={() => void save()}
+    <>
+      <PopoverNext
+        isOpen={open}
+        placement="bottom-end"
+        onInteraction={interact}
+        content={
+          <FigureDownloadPanel
+            title={title ?? t('download.saveFigure')}
+            format={format}
+            scale={scale}
+            scales={scales}
+            size={size}
+            failure={failure}
+            saving={saving}
+            onFormatChange={setFormat}
+            onScaleChange={(next) =>
+              setPicked((current) => ({ ...current, [format]: next }))
+            }
+            onSave={() => void save()}
+            sizing={
+              renderFigure === undefined
+                ? undefined
+                : {
+                    layout,
+                    custom,
+                    onLayoutChange: setLayout,
+                    onCustomChange: setCustom,
+                  }
+            }
+          />
+        }
+      >
+        <OverlayIconButton
+          icon={icon}
+          label={label ?? t('download.saveThisFigure')}
+          value={format.toUpperCase()}
+          active={open}
+          testId={testId}
+          opensMenu
         />
-      }
-    >
-      <OverlayIconButton
-        icon={icon}
-        label={label ?? t('download.saveThisFigure')}
-        value={format.toUpperCase()}
-        active={open}
-        testId={testId}
-        opensMenu
-      />
-    </PopoverNext>
+      </PopoverNext>
+      {portal}
+    </>
   );
 }