react-cheminfo 0.34.0 → 0.35.0

package/src/download/core/index.ts

@@ -51,31 +51,6 @@ export {
 } from './figureTarget.ts';
 export { sanitizeFileName } from './sanitizeFileName.ts';
 
-export {
-  exportButtonsStyle,
-  exportNoteStyle,
-  exportSectionStyle,
-} from './exportStyles.ts';
-export type {
-  ImageResolution,
-  ImageResolutionId,
-  ImageSize,
-} from './imageResolution.ts';
-export {
-  DEFAULT_IMAGE_RESOLUTION,
-  IMAGE_RESOLUTIONS,
-  formatImageSize,
-  imageResolution,
-  imageSize,
-} from './imageResolution.ts';
-export type { PictureFrame, PictureOptions } from './pictureExport.ts';
-export {
-  PICTURE_PADDING,
-  copyPicture,
-  pictureSize,
-  savePngPicture,
-  saveSvgPicture,
-} from './pictureExport.ts';
 export { drawingIn, stackDrawings } from './stackedDrawing.ts';
 export type { SvgBox } from './svgBounds.ts';
 export { CONTENT_ATTRIBUTE, contentBox, elementBox } from './svgBounds.ts';

package/src/download/ui/FigureDownload.tsx

@@ -1,74 +1,20 @@
 import type { IconName } from '@blueprintjs/core';
 import { PopoverNext } from '@blueprintjs/core';
 import type { ReactElement } from 'react';
-import { useState } from 'react';
 
 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,
-  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';
+import type { FigureDownloadOptions } from './useFigureDownload.tsx';
+import { useFigureDownload } from './useFigureDownload.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 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;
-  /**
-   * 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;
+export interface FigureDownloadProps extends FigureDownloadOptions {
   /**
    * What the glyph is called, for the pointer and for a screen reader.
    * @default the chrome's own line, in the language of the page
    */
   label?: string;
-  /**
-   * What the panel behind it is called.
-   * @default the chrome's own line, in the language of the page
-   */
-  title?: string;
   /**
    * Its glyph.
    * @default 'download'
@@ -79,20 +25,11 @@ 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;
 }
 
 /**
- * The glyph that takes the figure off the page as a file.
+ * The glyph that takes the figure off the page, as a file or onto the
+ * clipboard.
  *
  * 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
@@ -112,97 +49,23 @@ export interface 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, title } = props;
-  const { icon = 'download', testId, renderFigure } = props;
-
+  const { label, icon = 'download', testId, ...options } = props;
   const t = useChromeT();
-  const [open, setOpen] = useState(false);
-  const [format, setFormat] = useState<FigureFormat>(defaultFormat);
-  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
-  // 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 {
-      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));
-    } finally {
-      setSaving(false);
-    }
-  }
+  const { isOpen, setOpen, panel, format, portal } = useFigureDownload(options);
 
   return (
     <>
       <PopoverNext
-        isOpen={open}
+        isOpen={isOpen}
         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,
-                  }
-            }
-          />
-        }
+        onInteraction={setOpen}
+        content={panel}
       >
         <OverlayIconButton
           icon={icon}
           label={label ?? t('download.saveThisFigure')}
           value={format.toUpperCase()}
-          active={open}
+          active={isOpen}
           testId={testId}
           opensMenu
         />

package/src/download/ui/FigureDownloadPanel.tsx

@@ -1,7 +1,5 @@
 import type { ReactElement } from 'react';
 
-import type { ChromeKey } from '../../i18n/core/chromeCatalog.ts';
-import type { Translate } from '../../i18n/ui/useT.ts';
 import { useChromeT } from '../../i18n/ui/useT.ts';
 import { OverlayAction } from '../../overlay/ui/OverlayAction.tsx';
 import { OverlayPanel } from '../../overlay/ui/OverlayPanel.tsx';
@@ -19,6 +17,8 @@ import {
 
 import type { FigureSizing } from './FigureSizeRows.tsx';
 import { FigureSizeRows } from './FigureSizeRows.tsx';
+import { hintOf } from './figureDownloadHint.ts';
+import type { FigureNotice } from './useFigureActions.ts';
 
 /** What {@link FigureDownloadPanel} is drawn from. */
 export interface FigureDownloadPanelProps {
@@ -34,7 +34,13 @@ export interface FigureDownloadPanelProps {
   size: FigurePixels | null;
   /** What went wrong the last time save was pressed, if anything. */
   failure: string | null;
-  /** Whether a file is being written right now. */
+  /**
+   * What the last copy came to, while the choices it was made with still
+   * stand.
+   * @default null
+   */
+  notice?: FigureNotice | null;
+  /** Whether a file or a copy is being written right now. */
   saving: boolean;
   /** Called with the format the reader picked. */
   onFormatChange: (format: FigureFormat) => void;
@@ -42,6 +48,12 @@ export interface FigureDownloadPanelProps {
   onScaleChange: (scale: number) => void;
   /** Called when they press save. */
   onSave: () => void;
+  /**
+   * Called when they press copy, which puts a PNG at the resolution picked on
+   * the clipboard.
+   * @default undefined — no copy is offered
+   */
+  onCopy?: () => void;
   /**
    * Whether the SVG holds a rendered picture rather than vector drawings, as
    * for a WebGL scene: its resolution is then the pixels of that picture, it
@@ -59,7 +71,8 @@ export interface FigureDownloadPanelProps {
 }
 
 /**
- * The choices behind the save glyph, and the button that writes the file.
+ * The choices behind the save glyph, and the buttons that write the file and
+ * copy the picture.
  *
  * 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,
@@ -81,7 +94,7 @@ export function FigureDownloadPanel(
 ): ReactElement {
   const { title, format, scale, scales, size, failure, saving } = props;
   const { onFormatChange, onScaleChange, onSave, rasterSvg = false } = props;
-  const { sizing } = props;
+  const { sizing, onCopy, notice = null } = props;
   const t = useChromeT();
 
   // What the file is drawn at: the figure on screen, or the shape picked.
@@ -95,15 +108,29 @@ export function FigureDownloadPanel(
   return (
     <OverlayPanel
       title={title}
-      hint={hintOf(format, drawn, scale, failure, rasterSvg, t)}
+      width={PANEL_WIDTH}
+      hint={hintOf(
+        { format, size: drawn, scale, failure, notice, rasterSvg },
+        t,
+      )}
       actions={
-        <OverlayAction
-          text={t('download.save')}
-          icon="download"
-          intent="primary"
-          disabled={saving || size === null}
-          onClick={onSave}
-        />
+        <>
+          <OverlayAction
+            text={t('download.save')}
+            icon="download"
+            intent="primary"
+            disabled={saving || size === null}
+            onClick={onSave}
+          />
+          {onCopy === undefined ? null : (
+            <OverlayAction
+              text={t('clipboard.copy')}
+              icon="clipboard"
+              disabled={saving || size === null}
+              onClick={onCopy}
+            />
+          )}
+        </>
       }
     >
       <OverlaySegmented<FigureFormat>
@@ -137,6 +164,12 @@ export function FigureDownloadPanel(
   );
 }
 
+/**
+ * Wide enough for the longest hint on one line in English, so switching
+ * between PNG and SVG — whose hints differ in length — never resizes the panel.
+ */
+const PANEL_WIDTH = '27em';
+
 /** The two files a figure can leave the page as. */
 const FORMAT_CHOICES: ReadonlyArray<OverlayOption<FigureFormat>> = [
   { value: 'png', label: 'PNG' },
@@ -171,35 +204,3 @@ function scaleChoices(
   }
   return choices;
 }
-
-/**
- * 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 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
- * the page.
- * @returns The sentence.
- */
-function hintOf(
-  format: FigureFormat,
-  size: FigurePixels | null,
-  scale: number,
-  failure: string | null,
-  rasterSvg: boolean,
-  t: Translate<ChromeKey>,
-): string {
-  if (failure !== null) return failure;
-  if (size === null) return t('download.noFigure');
-  if (format === 'svg' && rasterSvg) {
-    return t('download.hintRasterSvg', {
-      pixels: formatFigurePixels(figurePixels(size, scale)),
-    });
-  }
-  const pixels = formatFigurePixels(figurePixels(size, scale));
-  return format === 'svg'
-    ? t('download.hintSvg', { pixels })
-    : t('download.hintPng', { pixels });
-}

package/src/download/ui/figureDownloadHint.ts

@@ -0,0 +1,52 @@
+import type { ChromeKey } from '../../i18n/core/chromeCatalog.ts';
+import type { Translate } from '../../i18n/ui/useT.ts';
+import type { FigureFormat } from '../core/downloadFigure.ts';
+import type { FigurePixels } from '../core/figureScale.ts';
+import { figurePixels, formatFigurePixels } from '../core/figureScale.ts';
+
+import type { FigureNotice } from './useFigureActions.ts';
+
+/** What the line at the foot of the panel is written from. */
+export interface HintState {
+  /** Which file the reader is about to write. */
+  format: FigureFormat;
+  /** How big the figure is drawn for the file. */
+  size: FigurePixels | null;
+  /** The multiple it is saved at. */
+  scale: number;
+  /** What went wrong last time, if anything. */
+  failure: string | null;
+  /** What the last copy came to, if anything. */
+  notice: FigureNotice | null;
+  /** Whether the SVG embeds a rendered picture. */
+  rasterSvg: boolean;
+}
+
+/**
+ * The line at the foot of the panel: what pressing save is about to do, or
+ * what the last copy did.
+ * @param state - See {@link HintState}.
+ * @param t - The chrome's formatter, so the sentence is in the language of
+ * the page.
+ * @returns The sentence.
+ */
+export function hintOf(state: HintState, t: Translate<ChromeKey>): string {
+  const { format, size, scale, failure, notice, rasterSvg } = state;
+  if (failure !== null) return failure;
+  if (size === null) return t('download.noFigure');
+  if (notice === 'copyUnsupported') return t('download.copyUnsupported');
+  if (notice === 'copied') {
+    return t('download.hintCopied', {
+      pixels: formatFigurePixels(figurePixels(size, scale)),
+    });
+  }
+  if (format === 'svg' && rasterSvg) {
+    return t('download.hintRasterSvg', {
+      pixels: formatFigurePixels(figurePixels(size, scale)),
+    });
+  }
+  const pixels = formatFigurePixels(figurePixels(size, scale));
+  return format === 'svg'
+    ? t('download.hintSvg', { pixels })
+    : t('download.hintPng', { pixels });
+}

package/src/download/ui/index.ts

@@ -14,13 +14,9 @@ export { FigureDownloadPanel } from './FigureDownloadPanel.tsx';
 export type { FigureSizing } from './FigureSizeRows.tsx';
 export type { FigureRenderer } from './useFigureRedraw.tsx';
 
-export type { ExportDialogFrameProps } from './ExportDialogFrame.tsx';
-export { ExportDialogFrame } from './ExportDialogFrame.tsx';
-export type { ExportImageDialogProps } from './ExportImageDialog.tsx';
-export { ExportImageDialog } from './ExportImageDialog.tsx';
-export type { ExportNameFieldProps } from './ExportNameField.tsx';
-export { ExportNameField } from './ExportNameField.tsx';
-export type { ExportPictureSectionProps } from './ExportPictureSection.tsx';
-export { ExportPictureSection } from './ExportPictureSection.tsx';
-export type { DrawingBox } from './useDrawingBox.ts';
-export { useDrawingBox } from './useDrawingBox.ts';
+export type {
+  FigureDownloadOptions,
+  FigureDownloadState,
+} from './useFigureDownload.tsx';
+export { useFigureDownload } from './useFigureDownload.tsx';
+export type { FigureNotice } from './useFigureActions.ts';

package/src/download/ui/useFigureActions.ts

@@ -0,0 +1,113 @@
+import { useCallback, useState } from 'react';
+
+import { writeImageToClipboard } from '../../clipboard/core/copyPng.ts';
+import type { FigureFormat } from '../core/downloadFigure.ts';
+import { downloadFigure } from '../core/downloadFigure.ts';
+import { figurePng } from '../core/figurePng.ts';
+import type { FigurePixels } from '../core/figureScale.ts';
+import { figureSvg } from '../core/figureSvg.ts';
+
+import type { FigureRedraw } from './useFigureRedraw.tsx';
+
+/** What the last copy came to, when it is worth a line of its own. */
+export type FigureNotice = 'copied' | 'copyUnsupported';
+
+/** What {@link useFigureActions} works from. */
+export interface FigureActionsOptions {
+  /** The `id` of the box the figure is mounted in. */
+  targetId: string;
+  /** Which file save writes. */
+  format: FigureFormat;
+  /** The multiple of the figure on screen it is painted at. */
+  scale: number;
+  /** What the saved file is called, without its extension. */
+  fileName?: string;
+  /** What is painted under the figure. */
+  background?: string;
+  /**
+   * The size the figure is drawn again at, off the page, or `null` to take
+   * the figure as it is on screen.
+   */
+  redrawAt: FigurePixels | null;
+  /** Draws the figure again, from {@link FigureRedraw}. */
+  redraw: FigureRedraw['redraw'];
+}
+
+/** What {@link useFigureActions} hands back. */
+export interface FigureActions {
+  /** Write the figure to a file, in the format picked. */
+  save: () => void;
+  /** Put the figure on the clipboard, as a PNG at the resolution picked. */
+  copy: () => void;
+  /** Whether a file or a copy is being written right now. */
+  busy: boolean;
+  /** What went wrong the last time, if anything. */
+  failure: string | null;
+  /** What the last copy came to, if it is still what the panel describes. */
+  notice: FigureNotice | null;
+  /** Forget the last outcome, once the choices it answered have changed. */
+  clear: () => void;
+}
+
+/**
+ * The two things the figure panel does: save the figure, and copy it.
+ *
+ * A copy is always a PNG, whatever format save is set to: a clipboard carries
+ * a picture, and the one every slide, chat window and issue accepts is a PNG.
+ * @param options - See {@link FigureActionsOptions}.
+ * @returns See {@link FigureActions}.
+ */
+export function useFigureActions(options: FigureActionsOptions): FigureActions {
+  const { targetId, format, scale, fileName, background } = options;
+  const { redrawAt, redraw } = options;
+  const [busy, setBusy] = useState(false);
+  const [failure, setFailure] = useState<string | null>(null);
+  const [notice, setNotice] = useState<FigureNotice | null>(null);
+
+  function withFigure(write: (box: string | Element) => Promise<void>) {
+    return redrawAt === null
+      ? write(targetId)
+      : redraw(targetId, redrawAt, write);
+  }
+
+  function run(task: Promise<FigureNotice | null>): void {
+    setBusy(true);
+    setFailure(null);
+    setNotice(null);
+    void task
+      .then(setNotice, (error: unknown) => {
+        setFailure(error instanceof Error ? error.message : String(error));
+      })
+      .finally(() => setBusy(false));
+  }
+
+  function save(): void {
+    const options = { format, scale, fileName, background };
+    run(withFigure((box) => downloadFigure(box, options)).then(() => null));
+  }
+
+  function copy(): void {
+    // The clipboard is written before anything is awaited, with the picture
+    // still being painted: Safari only allows a write the click itself started.
+    const png = new Promise<Blob>((resolve, reject) => {
+      withFigure(async (box) => {
+        resolve(await figurePng(figureSvg(box, { background }), scale));
+      }).catch(reject);
+    });
+    // A browser whose clipboard takes text only never reads the picture, so
+    // its failure would otherwise go unhandled.
+    png.catch(() => undefined);
+    run(
+      writeImageToClipboard(png).then((copied) =>
+        copied ? 'copied' : 'copyUnsupported',
+      ),
+    );
+  }
+
+  const clear = useCallback(() => {
+    setFailure(null);
+    setNotice(null);
+  }, []);
+
+  return { save, copy, busy, failure, notice, clear };
+}