react-cheminfo 0.34.0 → 0.36.0

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

package/src/download/ui/useFigureDownload.tsx

@@ -0,0 +1,191 @@
+import type { ReactElement, ReactNode } from 'react';
+import { useCallback, useState } from 'react';
+
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import type { FigureFormat } 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 { useFigureActions } from './useFigureActions.ts';
+import type { FigureRenderer } from './useFigureRedraw.tsx';
+import { useFigureRedraw } from './useFigureRedraw.tsx';
+
+/** What the "Save figure" panel is set up with. */
+export interface FigureDownloadOptions {
+  /**
+   * 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;
+  /**
+   * What the panel is called.
+   * @default the chrome's own line, in the language of the page
+   */
+  title?: 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;
+}
+
+/** What {@link useFigureDownload} hands back. */
+export interface FigureDownloadState {
+  /** Whether the panel is showing. */
+  isOpen: boolean;
+  /**
+   * Show or hide the panel. Showing it measures the figure, so hand this to
+   * the popover's `onInteraction` rather than a setter of your own.
+   */
+  setOpen: (open: boolean) => void;
+  /** The panel, for the popover's `content`. */
+  panel: ReactElement;
+  /** The format picked, for a trigger that shows it. */
+  format: FigureFormat;
+  /**
+   * The copy drawn off the page while a figure is saved at another size, to
+   * be rendered anywhere in the caller's tree.
+   */
+  portal: ReactNode;
+}
+
+/**
+ * The "Save figure" panel — save as PNG or SVG, or copy as PNG — for a caller
+ * that brings its own trigger, such as a button in an editor's toolbar.
+ * `FigureDownload` is the same panel behind the family's own glyph.
+ * @param options - See {@link FigureDownloadOptions}.
+ * @returns See {@link FigureDownloadState}.
+ */
+export function useFigureDownload(
+  options: FigureDownloadOptions,
+): FigureDownloadState {
+  const { targetId, fileName, background, scales = FIGURE_SCALES } = options;
+  const { defaultFormat = 'png', defaultScale = DEFAULT_FIGURE_SCALE } =
+    options;
+  const { title, renderFigure } = options;
+
+  const t = useChromeT();
+  const [isOpen, setIsOpen] = 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 [layout, setLayout] = useState<FigureLayout>('screen');
+  const [custom, setCustom] = useState<FigurePixels | null>(null);
+  const { redraw, portal } = useFigureRedraw(renderFigure);
+  const redrawAt =
+    renderFigure !== undefined &&
+    size !== null &&
+    figureLayoutRedraws(layout, size, custom ?? size)
+      ? figureLayoutSize(layout, size, custom ?? size)
+      : null;
+  const { save, copy, busy, failure, notice, clear } = useFigureActions({
+    targetId,
+    format,
+    scale,
+    fileName,
+    background,
+    redrawAt,
+    redraw,
+  });
+
+  // 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.
+  const setOpen = useCallback(
+    (next: boolean) => {
+      setIsOpen(next);
+      if (!next) return;
+      setSize(figureSize(targetId));
+      clear();
+    },
+    [targetId, clear],
+  );
+
+  // What the last copy came to only describes the choices it was made with.
+  function changed<T>(apply: (value: T) => void): (value: T) => void {
+    return (value) => {
+      clear();
+      apply(value);
+    };
+  }
+
+  const panel = (
+    <FigureDownloadPanel
+      title={title ?? t('download.saveFigure')}
+      format={format}
+      scale={scale}
+      scales={scales}
+      size={size}
+      failure={failure}
+      notice={notice}
+      saving={busy}
+      onFormatChange={changed(setFormat)}
+      onScaleChange={changed((next: number) =>
+        setPicked((current) => ({ ...current, [format]: next })),
+      )}
+      onSave={save}
+      onCopy={copy}
+      sizing={
+        renderFigure === undefined
+          ? undefined
+          : {
+              layout,
+              custom,
+              onLayoutChange: changed(setLayout),
+              onCustomChange: changed(setCustom),
+            }
+      }
+    />
+  );
+
+  return { isOpen, setOpen, panel, format, portal };
+}