react-cheminfo 0.76.0 → 0.77.0

package/src/download/core/pngDpi.ts

@@ -0,0 +1,84 @@
+/**
+ * The resolution a PNG states, in its `pHYs` chunk.
+ *
+ * A browser writes none, and a word processor or a slide then places the
+ * picture as if it were 72 or 96 dpi — a figure painted for print arrives
+ * several times too large. Stated, it arrives at the size it was drawn.
+ */
+
+import CRC32 from 'crc-32';
+
+const SIGNATURE = [0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a];
+
+/** Metres in an inch: `pHYs` counts pixels per metre. */
+const METRES_PER_INCH = 0.0254;
+
+/**
+ * A PNG stating a resolution, any resolution it stated before dropped.
+ * @param png - The PNG file's bytes.
+ * @param dpi - Dots per inch.
+ * @returns A new PNG file.
+ * @throws {Error} When the bytes are not a PNG.
+ */
+export function withPngDpi(
+  png: Uint8Array,
+  dpi: number,
+): Uint8Array<ArrayBuffer> {
+  for (let index = 0; index < SIGNATURE.length; index++) {
+    if (png[index] !== SIGNATURE[index]) throw new Error('Not a PNG file.');
+  }
+  const view = new DataView(png.buffer, png.byteOffset, png.byteLength);
+  const chunks: Uint8Array[] = [png.subarray(0, SIGNATURE.length)];
+  let offset = SIGNATURE.length;
+  while (offset + 8 <= png.length) {
+    const end = offset + 12 + view.getUint32(offset);
+    const type = chunkType(png, offset);
+    if (type !== 'pHYs') chunks.push(png.subarray(offset, end));
+    if (type === 'IHDR') chunks.push(physChunk(dpi));
+    offset = end;
+  }
+  let total = 0;
+  for (const chunk of chunks) total += chunk.length;
+  const result = new Uint8Array(total);
+  let position = 0;
+  for (const chunk of chunks) {
+    result.set(chunk, position);
+    position += chunk.length;
+  }
+  return result;
+}
+
+/**
+ * The resolution a PNG states.
+ * @param png - The PNG file's bytes.
+ * @returns Whole dots per inch, or `undefined` when it states none.
+ */
+export function pngDpi(png: Uint8Array): number | undefined {
+  const view = new DataView(png.buffer, png.byteOffset, png.byteLength);
+  let offset = SIGNATURE.length;
+  while (offset + 8 <= png.length) {
+    if (chunkType(png, offset) === 'pHYs' && png[offset + 16] === 1) {
+      return Math.round(view.getUint32(offset + 8) * METRES_PER_INCH);
+    }
+    offset += 12 + view.getUint32(offset);
+  }
+  return undefined;
+}
+
+function chunkType(png: Uint8Array, offset: number): string {
+  return String.fromCodePoint(...png.subarray(offset + 4, offset + 8));
+}
+
+function physChunk(dpi: number): Uint8Array {
+  const chunk = new Uint8Array(21);
+  const view = new DataView(chunk.buffer);
+  view.setUint32(0, 9);
+  chunk.set([0x70, 0x48, 0x59, 0x73], 4);
+  const perMetre = Math.round(dpi / METRES_PER_INCH);
+  view.setUint32(8, perMetre);
+  view.setUint32(12, perMetre);
+  // The unit: 1 is the metre, 0 an aspect ratio with no size.
+  chunk[16] = 1;
+  view.setInt32(17, CRC32.buf(chunk.subarray(4, 17)));
+  return chunk;
+}

package/src/download/ui/FigureDownloadPanel.tsx

@@ -1,5 +1,6 @@
 import type { ReactElement, ReactNode } from 'react';
 
+import { useLanguage } from '../../i18n/ui/useLanguage.ts';
 import { useChromeT } from '../../i18n/ui/useT.ts';
 import { OverlayAction } from '../../overlay/ui/OverlayAction.tsx';
 import { OverlayPanel } from '../../overlay/ui/OverlayPanel.tsx';
@@ -7,18 +8,14 @@ import type { OverlayOption } from '../../overlay/ui/OverlayRow.tsx';
 import { OverlaySegmented } from '../../overlay/ui/OverlaySegmented.tsx';
 import type { FigureNotice } from '../core/copyFigure.ts';
 import type { FigureFormat } from '../core/downloadFigure.ts';
+import type { FigureResolutionUnit } from '../core/figureDpi.ts';
 import { figureLayoutSize } from '../core/figureLayout.ts';
 import type { FigurePixels } from '../core/figureScale.ts';
-import {
-  figurePixels,
-  figureScaleFits,
-  figureScaleLabel,
-  formatFigurePixels,
-} from '../core/figureScale.ts';
 
 import type { FigureSizing } from './FigureSizeRows.tsx';
 import { FigureSizeRows } from './FigureSizeRows.tsx';
 import { hintOf } from './figureDownloadHint.ts';
+import { resolutionHelp, scaleChoices } from './resolutionChoices.ts';
 
 /** What {@link FigureDownloadPanel} is drawn from. */
 export interface FigureDownloadPanelProps {
@@ -30,6 +27,18 @@ export interface FigureDownloadPanelProps {
   scale: number;
   /** The multiples offered. */
   scales: readonly number[];
+  /**
+   * How the resolution reads: multiples of the figure on screen, or the dots
+   * per inch it has printed at its size on the page — 1× is 96 dpi.
+   * @default 'multiple'
+   */
+  unit?: FigureResolutionUnit;
+  /**
+   * Whether an SVG is saved at the size it states, whatever the resolution:
+   * the resolution then paints the PNG alone, and is not offered for the SVG.
+   * @default false
+   */
+  svgAtOwnSize?: boolean;
   /** How big the figure is on the page, or `null` where there is none. */
   size: FigurePixels | null;
   /** What went wrong the last time save was pressed, if anything. */
@@ -100,7 +109,9 @@ export function FigureDownloadPanel(
   const { title, format, scale, scales, size, failure, saving } = props;
   const { onFormatChange, onScaleChange, onSave, rasterSvg = false } = props;
   const { sizing, onCopy, notice = null, children } = props;
+  const { unit = 'multiple', svgAtOwnSize = false } = props;
   const t = useChromeT();
+  const language = useLanguage();
 
   // What the file is drawn at: the figure on screen, or the shape picked.
   const drawn =
@@ -109,13 +120,23 @@ export function FigureDownloadPanel(
       : figureLayoutSize(sizing.layout, size, sizing.custom ?? size);
 
   const painted = format === 'png' || rasterSvg;
+  const offerResolution = format === 'png' || !svgAtOwnSize;
 
   return (
     <OverlayPanel
       title={title}
-      width={PANEL_WIDTH}
+      width={unit === 'dpi' ? DPI_PANEL_WIDTH : PANEL_WIDTH}
       hint={hintOf(
-        { format, size: drawn, scale, failure, notice, rasterSvg },
+        {
+          format,
+          size: drawn,
+          scale,
+          failure,
+          notice,
+          rasterSvg,
+          unit,
+          language,
+        },
         t,
       )}
       actions={
@@ -152,20 +173,15 @@ export function FigureDownloadPanel(
       {sizing === undefined ? null : (
         <FigureSizeRows sizing={sizing} size={size} />
       )}
-      <OverlaySegmented
-        label={t('download.resolution')}
-        help={{
-          title: t('download.resolution'),
-          body: t('download.resolutionHelp'),
-          example: {
-            code: '2×',
-            note: t('download.resolutionExample'),
-          },
-        }}
-        value={String(scale)}
-        options={scaleChoices(scales, drawn, painted)}
-        onChange={(picked) => onScaleChange(Number(picked))}
-      />
+      {offerResolution ? (
+        <OverlaySegmented
+          label={t('download.resolution')}
+          help={resolutionHelp(unit, t)}
+          value={String(scale)}
+          options={scaleChoices(scales, drawn, painted, unit)}
+          onChange={(picked) => onScaleChange(Number(picked))}
+        />
+      ) : null}
     </OverlayPanel>
   );
 }
@@ -176,37 +192,11 @@ export function FigureDownloadPanel(
  */
 const PANEL_WIDTH = '27em';
 
+/** Wide enough for the four dots per inch on one row, `1200 dpi` last. */
+const DPI_PANEL_WIDTH = '33em';
+
 /** The two files a figure can leave the page as. */
 const FORMAT_CHOICES: ReadonlyArray<OverlayOption<FigureFormat>> = [
   { value: 'png', label: 'PNG' },
   { value: 'svg', label: 'SVG' },
 ];
-
-/**
- * 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. 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 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) {
-    const pixels = size === null ? null : figurePixels(size, scale);
-    choices.push({
-      value: String(scale),
-      label: figureScaleLabel(scale),
-      title: pixels === null ? undefined : formatFigurePixels(pixels),
-      disabled: painted && size !== null && !figureScaleFits(size, scale),
-    });
-  }
-  return choices;
-}

package/src/download/ui/figureDownloadHint.ts

@@ -2,6 +2,8 @@ import type { ChromeKey } from '../../i18n/core/chromeCatalog.ts';
 import type { Translate } from '../../i18n/ui/useT.ts';
 import type { FigureNotice } from '../core/copyFigure.ts';
 import type { FigureFormat } from '../core/downloadFigure.ts';
+import type { FigureResolutionUnit } from '../core/figureDpi.ts';
+import { formatFigureCentimetres } from '../core/figureDpi.ts';
 import type { FigurePixels } from '../core/figureScale.ts';
 import { figurePixels, formatFigurePixels } from '../core/figureScale.ts';
 
@@ -19,6 +21,10 @@ export interface HintState {
   notice: FigureNotice | null;
   /** Whether the SVG embeds a rendered picture. */
   rasterSvg: boolean;
+  /** How the resolution is offered; in dpi, the printed size is written out. */
+  unit: FigureResolutionUnit;
+  /** The language of the page, which the printed size is written in. */
+  language: string;
 }
 
 /**
@@ -31,6 +37,7 @@ export interface HintState {
  */
 export function hintOf(state: HintState, t: Translate<ChromeKey>): string {
   const { format, size, scale, failure, notice, rasterSvg } = state;
+  const { unit, language } = state;
   if (failure !== null) return failure;
   if (size === null) return t('download.noFigure');
   if (notice === 'copyUnsupported') return t('download.copyUnsupported');
@@ -45,6 +52,12 @@ export function hintOf(state: HintState, t: Translate<ChromeKey>): string {
     });
   }
   const pixels = formatFigurePixels(figurePixels(size, scale));
+  if (unit === 'dpi') {
+    const printed = formatFigureCentimetres(size, language);
+    return format === 'svg'
+      ? t('download.hintSvgDpi', printed)
+      : t('download.hintPngDpi', { pixels, ...printed });
+  }
   return format === 'svg'
     ? t('download.hintSvg', { pixels })
     : t('download.hintPng', { pixels });

package/src/download/ui/figureDownloadOptions.ts

@@ -0,0 +1,85 @@
+import type { FigureFormat } from '../core/downloadFigure.ts';
+import type { FigureResolutionUnit } from '../core/figureDpi.ts';
+import type { FigureSvg } from '../core/figureSvg.ts';
+
+import type { FigureRenderer } 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. Give this or
+   * `writeFigure`.
+   * @default undefined
+   */
+  targetId?: string;
+  /**
+   * Writes the figure as an SVG document, in place of reading it off the
+   * page: for a drawing whose file carries more than its picture, such as the
+   * chemistry behind a structure. It is called when the panel opens, to
+   * measure the figure, and again for every save and copy. The SVG is saved as
+   * written, at the size it states; the resolution paints the PNG alone.
+   * @default undefined
+   */
+  writeFigure?: () => Promise<FigureSvg>;
+  /**
+   * 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;
+  /**
+   * How the resolution is offered: as multiples of the figure on screen, or —
+   * for a figure drawn to the size it prints at — in dots per inch. In dots
+   * per inch an SVG keeps the size it states, and 1× is 96 dpi.
+   * @default 'multiple'
+   */
+  unit?: FigureResolutionUnit;
+  /**
+   * The resolution a PNG opens on, as a multiple of the figure on screen:
+   * `dpiScale(600)` opens on 600 dpi. 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, or 300 dpi
+   */
+  defaultScale?: number;
+  /**
+   * The resolutions offered, as multiples of the figure on screen.
+   * @default [1, 2, 3, 4], or 150, 300, 600 and 1200 dpi
+   */
+  scales?: readonly number[];
+  /**
+   * Called with the multiple a PNG is set to, for a page that keeps the
+   * reader's choice — to paint its own PNGs at it, or to open on it next time.
+   * @default undefined
+   */
+  onScaleChange?: (scale: number) => void;
+  /**
+   * What is painted under the figure. `transparent` leaves it unpainted, for a
+   * figure going onto a coloured slide. A written figure paints its own.
+   * @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. A written figure has the size it
+   * states, and is offered none.
+   * @default undefined — the figure is saved at the size it has on screen
+   */
+  renderFigure?: FigureRenderer;
+}

package/src/download/ui/resolutionChoices.ts

@@ -0,0 +1,67 @@
+import type { HelpContent } from '../../help/ui/HelpBody.tsx';
+import type { ChromeKey } from '../../i18n/core/chromeCatalog.ts';
+import type { Translate } from '../../i18n/ui/useT.ts';
+import type { OverlayOption } from '../../overlay/ui/OverlayRow.tsx';
+import type { FigureResolutionUnit } from '../core/figureDpi.ts';
+import { figureResolutionLabel } from '../core/figureDpi.ts';
+import type { FigurePixels } from '../core/figureScale.ts';
+import {
+  figurePixels,
+  figureScaleFits,
+  formatFigurePixels,
+} from '../core/figureScale.ts';
+
+/**
+ * The resolutions 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. 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 drawn for the file.
+ * @param painted - Whether the file is painted into pixels.
+ * @param unit - How the resolution reads.
+ * @returns The choices, in the order offered.
+ */
+export function scaleChoices(
+  scales: readonly number[],
+  size: FigurePixels | null,
+  painted: boolean,
+  unit: FigureResolutionUnit,
+): readonly OverlayOption[] {
+  const choices: OverlayOption[] = [];
+  for (const scale of scales) {
+    const pixels = size === null ? null : figurePixels(size, scale);
+    choices.push({
+      value: String(scale),
+      label: figureResolutionLabel(scale, unit),
+      title: pixels === null ? undefined : formatFigurePixels(pixels),
+      disabled: painted && size !== null && !figureScaleFits(size, scale),
+    });
+  }
+  return choices;
+}
+
+/**
+ * What the resolution means, in the unit it is offered in.
+ * @param unit - How the resolution reads.
+ * @param t - The chrome's formatter.
+ * @returns The help of the row.
+ */
+export function resolutionHelp(
+  unit: FigureResolutionUnit,
+  t: Translate<ChromeKey>,
+): HelpContent {
+  const title = t('download.resolution');
+  return unit === 'dpi'
+    ? {
+        title,
+        body: t('download.resolutionDpiHelp'),
+        example: { code: '300 dpi', note: t('download.resolutionDpiExample') },
+      }
+    : {
+        title,
+        body: t('download.resolutionHelp'),
+        example: { code: '2×', note: t('download.resolutionExample') },
+      };
+}

package/src/download/ui/useFigureActions.ts

@@ -1,8 +1,9 @@
 import { copyFigure } from '../core/copyFigure.ts';
 import type { FigureFormat } from '../core/downloadFigure.ts';
-import { downloadFigure } from '../core/downloadFigure.ts';
+import { downloadFigure, downloadFigureSvg } from '../core/downloadFigure.ts';
 import { figurePng } from '../core/figurePng.ts';
 import type { FigurePixels } from '../core/figureScale.ts';
+import type { FigureSvg } from '../core/figureSvg.ts';
 import { figureSvg } from '../core/figureSvg.ts';
 
 import type { FigureRedraw } from './useFigureRedraw.tsx';
@@ -12,7 +13,9 @@ import { useFigureTask } from './useFigureTask.ts';
 /** What {@link useFigureActions} works from. */
 export interface FigureActionsOptions {
   /** The `id` of the box the figure is mounted in. */
-  targetId: string;
+  targetId?: string;
+  /** Writes the figure, in place of reading it off the page. */
+  writeFigure?: () => Promise<FigureSvg>;
   /** Which file save writes. */
   format: FigureFormat;
   /** The multiple of the figure on screen it is painted at. */
@@ -47,17 +50,26 @@ export interface FigureActions extends Omit<FigureTask, 'run'> {
  * @returns See {@link FigureActions}.
  */
 export function useFigureActions(options: FigureActionsOptions): FigureActions {
-  const { targetId, format, scale, fileName, background } = options;
+  const { targetId, writeFigure, format, scale, fileName, background } =
+    options;
   const { redrawAt, redraw } = options;
   const { run, busy, failure, notice, clear } = useFigureTask();
 
-  function withFigure(write: (box: string | Element) => Promise<void>) {
+  async function withFigure(write: (box: string | Element) => Promise<void>) {
+    if (targetId === undefined) throw new Error('There is no figure to save.');
     return redrawAt === null
       ? write(targetId)
       : redraw(targetId, redrawAt, write);
   }
 
   function save(): void {
+    if (writeFigure !== undefined) {
+      const written = writeFigure().then((figure) =>
+        downloadFigureSvg(figure, { format, scale, fileName }),
+      );
+      run(written.then(() => null));
+      return;
+    }
     const options = { format, scale, fileName, background };
     run(withFigure((box) => downloadFigure(box, options)).then(() => null));
   }
@@ -65,11 +77,14 @@ export function useFigureActions(options: FigureActionsOptions): FigureActions {
   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);
-    });
+    const png =
+      writeFigure === undefined
+        ? new Promise<Blob>((resolve, reject) => {
+            withFigure(async (box) => {
+              resolve(await figurePng(figureSvg(box, { background }), scale));
+            }).catch(reject);
+          })
+        : writeFigure().then((figure) => figurePng(figure, scale));
     run(copyFigure(png));
   }