react-cheminfo 0.30.0 → 0.32.0

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

package/src/download/ui/FigureSizeField.tsx

@@ -0,0 +1,153 @@
+import type { CSSProperties, KeyboardEvent, ReactElement } from 'react';
+import { useState } from 'react';
+
+import type { OverlayMetrics } from '../../overlay/core/overlayMetrics.ts';
+import { OverlayRow } from '../../overlay/ui/OverlayRow.tsx';
+import { useOverlaySurface } from '../../overlay/ui/overlaySurface.ts';
+import { overlayFocusRing } from '../../overlay/ui/overlayValueStyles.ts';
+import { figureLayoutSide } from '../core/figureLayout.ts';
+import type { FigurePixels } from '../core/figureScale.ts';
+
+/** What {@link FigureSizeField} needs. */
+export interface FigureSizeFieldProps {
+  /** What the row is called. */
+  label: string;
+  /** What the first box is called, for a screen reader. */
+  widthLabel: string;
+  /** What the second box is called. */
+  heightLabel: string;
+  /** The size typed so far. */
+  value: FigurePixels;
+  /** Called with the size, each side already held to the range. */
+  onChange: (size: FigurePixels) => void;
+}
+
+/**
+ * The two sides of a figure, typed in pixels.
+ *
+ * These are typed rather than stepped: a reader asking for 1920 × 1080 knows
+ * the numbers, and a stepper would take a hundred presses to reach them. A side
+ * is taken when the reader leaves its box or presses Enter, never on each key,
+ * since the `1` of a `1200` on its way in is not a width anybody asked for.
+ * @param props - See {@link FigureSizeFieldProps}.
+ * @returns The row.
+ */
+export function FigureSizeField(props: FigureSizeFieldProps): ReactElement {
+  const { label, widthLabel, heightLabel, value, onChange } = props;
+  const { metrics } = useOverlaySurface();
+
+  return (
+    <OverlayRow label={label}>
+      <span style={{ ...FIELD_STYLE, fontSize: metrics.fontSize }}>
+        <SideInput
+          label={widthLabel}
+          value={value.width}
+          metrics={metrics}
+          onCommit={(width) => onChange({ ...value, width })}
+        />
+        <span aria-hidden="true">×</span>
+        <SideInput
+          label={heightLabel}
+          value={value.height}
+          metrics={metrics}
+          onCommit={(height) => onChange({ ...value, height })}
+        />
+        <span style={UNIT_STYLE}>px</span>
+      </span>
+    </OverlayRow>
+  );
+}
+
+interface SideInputProps {
+  /** What the box is called. */
+  label: string;
+  /** The side as last taken. */
+  value: number;
+  /** The measurements the panel is drawn from. */
+  metrics: OverlayMetrics;
+  /** Called with the side once it is taken. */
+  onCommit: (side: number) => void;
+}
+
+/**
+ * One side, typed.
+ * @param props - See {@link SideInputProps}.
+ * @returns The box.
+ */
+function SideInput(props: SideInputProps): ReactElement {
+  const { label, value, metrics, onCommit } = props;
+  const [draft, setDraft] = useState(String(value));
+  const [taken, setTaken] = useState(value);
+  const [focused, setFocused] = useState(false);
+
+  // A side changed from outside — another shape picked, a clamp — replaces
+  // whatever was being typed.
+  if (taken !== value) {
+    setTaken(value);
+    setDraft(String(value));
+  }
+
+  function commit(): void {
+    const typed = Number.parseFloat(draft);
+    const side = Number.isFinite(typed) ? figureLayoutSide(typed) : value;
+    setDraft(String(side));
+    if (side !== value) onCommit(side);
+  }
+
+  function onKeyDown(event: KeyboardEvent<HTMLInputElement>): void {
+    if (event.key !== 'Enter') return;
+    event.preventDefault();
+    commit();
+  }
+
+  return (
+    <input
+      type="text"
+      inputMode="numeric"
+      aria-label={label}
+      value={draft}
+      style={{ ...sideStyle(metrics), ...overlayFocusRing(focused) }}
+      onChange={(event) => setDraft(event.currentTarget.value)}
+      onFocus={() => setFocused(true)}
+      onBlur={() => {
+        setFocused(false);
+        commit();
+      }}
+      onKeyDown={onKeyDown}
+    />
+  );
+}
+
+/**
+ * A box as tall as every other control of the panel, and wide enough for four
+ * digits.
+ * @param metrics - The measurements the panel is drawn from.
+ * @returns The box's rules.
+ */
+function sideStyle(metrics: OverlayMetrics): CSSProperties {
+  return {
+    boxSizing: 'border-box',
+    width: '5em',
+    height: metrics.controlHeight,
+    padding: '0 6px',
+    border: '1px solid var(--border)',
+    borderRadius: metrics.controlRadius,
+    background: 'var(--surface)',
+    color: 'var(--text)',
+    font: 'inherit',
+    fontSize: metrics.fontSize,
+    fontVariantNumeric: 'tabular-nums',
+    textAlign: 'right',
+  };
+}
+
+const FIELD_STYLE = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  gap: 6,
+  color: 'var(--text-muted)',
+} as const satisfies CSSProperties;
+
+const UNIT_STYLE = {
+  color: 'var(--text-faint)',
+} as const satisfies CSSProperties;

package/src/download/ui/FigureSizeRows.tsx

@@ -0,0 +1,108 @@
+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 type { OverlayOption } from '../../overlay/ui/OverlayRow.tsx';
+import { OverlaySelect } from '../../overlay/ui/OverlaySelect.tsx';
+import type { FigureLayout } from '../core/figureLayout.ts';
+import { FIGURE_LAYOUTS, figureLayoutSize } from '../core/figureLayout.ts';
+import type { FigurePixels } from '../core/figureScale.ts';
+import { formatFigurePixels } from '../core/figureScale.ts';
+
+import { FigureSizeField } from './FigureSizeField.tsx';
+
+/** The shape a figure is saved at, and what changes it. */
+export interface FigureSizing {
+  /** The shape picked. */
+  layout: FigureLayout;
+  /**
+   * The size typed for `custom`, or `null` before anything was typed, when it
+   * starts from the figure on screen.
+   */
+  custom: FigurePixels | null;
+  /** Called with the shape picked. */
+  onLayoutChange: (layout: FigureLayout) => void;
+  /** Called with the size typed. */
+  onCustomChange: (size: FigurePixels) => void;
+}
+
+/** What {@link FigureSizeRows} needs. */
+export interface FigureSizeRowsProps {
+  /** The shape and what changes it. */
+  sizing: FigureSizing;
+  /** How big the figure is on the page, or `null` where there is none. */
+  size: FigurePixels | null;
+}
+
+/**
+ * The shape the figure is drawn at, and the two sides of a custom one.
+ *
+ * Each shape says the pixels it would produce, so choosing `16:9` for a figure
+ * already close to it is visibly a choice that changes little.
+ * @param props - See {@link FigureSizeRowsProps}.
+ * @returns The rows.
+ */
+export function FigureSizeRows(props: FigureSizeRowsProps): ReactElement {
+  const { sizing, size } = props;
+  const { layout, custom, onLayoutChange, onCustomChange } = sizing;
+  const t = useChromeT();
+
+  const options: Array<OverlayOption<FigureLayout>> = [];
+  for (const shape of FIGURE_LAYOUTS) {
+    options.push({
+      value: shape,
+      label: layoutLabel(shape, t),
+      title:
+        size === null
+          ? undefined
+          : formatFigurePixels(figureLayoutSize(shape, size, custom ?? size)),
+    });
+  }
+
+  return (
+    <>
+      <OverlaySelect<FigureLayout>
+        label={t('download.size')}
+        help={{ title: t('download.size'), body: t('download.sizeHelp') }}
+        value={layout}
+        options={options}
+        disabled={size === null}
+        onChange={onLayoutChange}
+      />
+      {layout === 'custom' && size !== null ? (
+        <FigureSizeField
+          label={t('download.customSize')}
+          widthLabel={t('download.width')}
+          heightLabel={t('download.height')}
+          value={figureLayoutSize('custom', size, custom ?? size)}
+          onChange={onCustomChange}
+        />
+      ) : null}
+    </>
+  );
+}
+
+/**
+ * What a shape reads in the picker. A ratio is written as a ratio in every
+ * language.
+ * @param layout - The shape.
+ * @param t - The chrome's formatter.
+ * @returns Its label.
+ */
+function layoutLabel(layout: FigureLayout, t: Translate<ChromeKey>): string {
+  switch (layout) {
+    case 'standard':
+      return '4:3';
+    case 'wide':
+      return '16:9';
+    case 'column':
+      return t('download.sizeColumn');
+    case 'custom':
+      return t('download.sizeCustom');
+    case 'screen':
+      return t('download.sizeScreen');
+    default:
+      throw new Error(`unknown figure layout: ${String(layout)}`);
+  }
+}

package/src/download/ui/index.ts

@@ -11,6 +11,8 @@ export type { FigureDownloadProps } from './FigureDownload.tsx';
 export { FigureDownload } from './FigureDownload.tsx';
 export type { FigureDownloadPanelProps } from './FigureDownloadPanel.tsx';
 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';