react-cheminfo 0.30.0 → 0.31.0

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}
+    </>
   );
 }

package/src/download/ui/FigureDownloadPanel.tsx

@@ -8,6 +8,7 @@ import { OverlayPanel } from '../../overlay/ui/OverlayPanel.tsx';
 import type { OverlayOption } from '../../overlay/ui/OverlayRow.tsx';
 import { OverlaySegmented } from '../../overlay/ui/OverlaySegmented.tsx';
 import type { FigureFormat } from '../core/downloadFigure.ts';
+import { figureLayoutSize } from '../core/figureLayout.ts';
 import type { FigurePixels } from '../core/figureScale.ts';
 import {
   figurePixels,
@@ -16,6 +17,9 @@ import {
   formatFigurePixels,
 } from '../core/figureScale.ts';
 
+import type { FigureSizing } from './FigureSizeRows.tsx';
+import { FigureSizeRows } from './FigureSizeRows.tsx';
+
 /** What {@link FigureDownloadPanel} is drawn from. */
 export interface FigureDownloadPanelProps {
   /** What the panel is called. */
@@ -40,21 +44,30 @@ export interface FigureDownloadPanelProps {
   onSave: () => void;
   /**
    * Whether the SVG holds a rendered picture rather than vector drawings, as
-   * for a WebGL scene: its resolution then applies, and the hint says so.
+   * for a WebGL scene: its resolution is then the pixels of that picture, it
+   * meets the same ceiling as a PNG, and the hint says so.
    * @default false
    */
   rasterSvg?: boolean;
+  /**
+   * The shape the figure is drawn at, for a figure that can be drawn again at
+   * another size. Without it the figure is saved at the size it has on screen,
+   * and no size is offered.
+   * @default undefined
+   */
+  sizing?: FigureSizing;
 }
 
 /**
- * The two choices behind the save glyph, and the button that writes the file.
+ * The choices behind the save glyph, and the button that writes the file.
  *
- * The resolution stays in place and greyed while an SVG is selected rather
- * than disappearing, because a control that vanishes is a control the reader
- * concludes the figure does not have — and the sentence at the foot says why
- * it is greyed, which is that an SVG has no resolution to choose.
+ * The resolution applies to both formats, and means what the reader needs it
+ * to: a PNG is painted with that many more pixels, and an SVG, drawn the same,
+ * opens that many times larger in the slide or the document it is dropped
+ * into. Only a PNG meets the ceiling of what a browser can paint, so only its
+ * choices past that ceiling are greyed.
  *
- * That sentence is the panel's own hint line rather than a row of its own: it
+ * The sentence at the foot is the panel's own hint line rather than a row of its own: it
  * is not a setting, it is what the two settings above it currently amount to,
  * and it is the only thing here that answers the question a reader actually
  * has, which is how big the file is going to be. Saving itself is a command
@@ -68,14 +81,21 @@ export function FigureDownloadPanel(
 ): ReactElement {
   const { title, format, scale, scales, size, failure, saving } = props;
   const { onFormatChange, onScaleChange, onSave, rasterSvg = false } = props;
+  const { sizing } = props;
   const t = useChromeT();
 
-  const vector = format === 'svg' && !rasterSvg;
+  // What the file is drawn at: the figure on screen, or the shape picked.
+  const drawn =
+    size === null || sizing === undefined
+      ? size
+      : figureLayoutSize(sizing.layout, size, sizing.custom ?? size);
+
+  const painted = format === 'png' || rasterSvg;
 
   return (
     <OverlayPanel
       title={title}
-      hint={hintOf(format, size, scale, failure, rasterSvg, t)}
+      hint={hintOf(format, drawn, scale, failure, rasterSvg, t)}
       actions={
         <OverlayAction
           text={t('download.save')}
@@ -96,6 +116,9 @@ export function FigureDownloadPanel(
         options={FORMAT_CHOICES}
         onChange={onFormatChange}
       />
+      {sizing === undefined ? null : (
+        <FigureSizeRows sizing={sizing} size={size} />
+      )}
       <OverlaySegmented
         label={t('download.resolution')}
         help={{
@@ -107,8 +130,7 @@ export function FigureDownloadPanel(
           },
         }}
         value={String(scale)}
-        options={scaleChoices(scales, size)}
-        disabled={vector}
+        options={scaleChoices(scales, drawn, painted)}
         onChange={(picked) => onScaleChange(Number(picked))}
       />
     </OverlayPanel>
@@ -125,14 +147,17 @@ const FORMAT_CHOICES: ReadonlyArray<OverlayOption<FigureFormat>> = [
  * The multiples offered, each saying what it would actually produce.
  *
  * One too large for the browser to paint is greyed rather than dropped, so the
- * reader learns the ceiling exists before they meet it as a blank file.
+ * reader learns the ceiling exists before they meet it as a blank file. An SVG
+ * is not painted, so it has no such ceiling.
  * @param scales - The multiples the caller offers.
- * @param size - How big the figure is on the page.
+ * @param size - How big the figure is drawn for the file.
+ * @param painted - Whether the file is painted into pixels.
  * @returns The choices, in the order offered.
  */
 function scaleChoices(
   scales: readonly number[],
   size: FigurePixels | null,
+  painted: boolean,
 ): readonly OverlayOption[] {
   const choices: OverlayOption[] = [];
   for (const scale of scales) {
@@ -141,7 +166,7 @@ function scaleChoices(
       value: String(scale),
       label: figureScaleLabel(scale),
       title: pixels === null ? undefined : formatFigurePixels(pixels),
-      disabled: size !== null && !figureScaleFits(size, scale),
+      disabled: painted && size !== null && !figureScaleFits(size, scale),
     });
   }
   return choices;
@@ -150,8 +175,8 @@ function scaleChoices(
 /**
  * The line at the foot of the panel: what pressing save is about to do.
  * @param format - Which file the reader is about to write.
- * @param size - How big the figure is on the page.
- * @param scale - The multiple it is painted at.
+ * @param size - How big the figure is drawn for the file.
+ * @param scale - The multiple it is saved at.
  * @param failure - What went wrong last time, if anything.
  * @param rasterSvg - Whether the SVG embeds a rendered picture.
  * @param t - The chrome's formatter, so the sentence is in the language of
@@ -173,10 +198,8 @@ function hintOf(
       pixels: formatFigurePixels(figurePixels(size, scale)),
     });
   }
-  if (format === 'svg') {
-    return t('download.hintSvg', { pixels: formatFigurePixels(size) });
-  }
-  return t('download.hintPng', {
-    pixels: formatFigurePixels(figurePixels(size, scale)),
-  });
+  const pixels = formatFigurePixels(figurePixels(size, scale));
+  return format === 'svg'
+    ? t('download.hintSvg', { pixels })
+    : t('download.hintPng', { pixels });
 }