react-cheminfo 0.76.0 → 0.78.0

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

package/src/download/ui/useFigureDownload.tsx

@@ -1,8 +1,13 @@
 import type { ReactElement, ReactNode } from 'react';
-import { useCallback, useState } from 'react';
+import { useCallback, useRef, useState } from 'react';
 
 import { useChromeT } from '../../i18n/ui/useT.ts';
 import type { FigureFormat } from '../core/downloadFigure.ts';
+import {
+  DEFAULT_FIGURE_DPI,
+  FIGURE_DPIS,
+  dpiScale,
+} from '../core/figureDpi.ts';
 import type { FigureLayout } from '../core/figureLayout.ts';
 import { figureLayoutRedraws, figureLayoutSize } from '../core/figureLayout.ts';
 import type { FigurePixels } from '../core/figureScale.ts';
@@ -14,64 +19,11 @@ import {
 import { figureSize } from '../core/figureTarget.ts';
 
 import { FigureDownloadPanel } from './FigureDownloadPanel.tsx';
+import type { FigureDownloadOptions } from './figureDownloadOptions.ts';
 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;
-}
+export type { FigureDownloadOptions } from './figureDownloadOptions.ts';
 
 /** What {@link useFigureDownload} hands back. */
 export interface FigureDownloadState {
@@ -93,6 +45,9 @@ export interface FigureDownloadState {
   portal: ReactNode;
 }
 
+/** The dots per inch offered, as the multiples the figure is painted at. */
+const DPI_SCALES = FIGURE_DPIS.map(dpiScale);
+
 /**
  * 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.
@@ -103,10 +58,18 @@ export interface 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 { targetId, writeFigure, fileName, background } = options;
+  const { unit = 'multiple', defaultFormat = 'png' } = options;
+  const { title, renderFigure, onScaleChange } = options;
+  const dpi = unit === 'dpi';
+  const scales = options.scales ?? (dpi ? DPI_SCALES : FIGURE_SCALES);
+  const defaultScale =
+    options.defaultScale ??
+    (dpi ? dpiScale(DEFAULT_FIGURE_DPI) : DEFAULT_FIGURE_SCALE);
+  // A figure with a printed size, or one its page wrote, keeps the size its
+  // SVG states: the resolution is then the PNG's alone.
+  const svgAtOwnSize = dpi || writeFigure !== undefined;
+  const redraws = renderFigure !== undefined && writeFigure === undefined;
 
   const t = useChromeT();
   const [isOpen, setIsOpen] = useState(false);
@@ -115,19 +78,23 @@ export function useFigureDownload(
     png: defaultScale,
     svg: defaultFigureScale('svg'),
   }));
-  const scale = picked[format];
+  const scale = format === 'svg' && svgAtOwnSize ? 1 : picked[format];
   const [size, setSize] = useState<FigurePixels | null>(null);
+  const opening = useRef(0);
   const [layout, setLayout] = useState<FigureLayout>('screen');
   const [custom, setCustom] = useState<FigurePixels | null>(null);
-  const { redraw, portal } = useFigureRedraw(renderFigure);
+  const { redraw, portal } = useFigureRedraw(
+    redraws ? renderFigure : undefined,
+  );
   const redrawAt =
-    renderFigure !== undefined &&
+    redraws &&
     size !== null &&
     figureLayoutRedraws(layout, size, custom ?? size)
       ? figureLayoutSize(layout, size, custom ?? size)
       : null;
   const { save, copy, busy, failure, notice, clear } = useFigureActions({
     targetId,
+    writeFigure,
     format,
     scale,
     fileName,
@@ -144,10 +111,26 @@ export function useFigureDownload(
     (next: boolean) => {
       setIsOpen(next);
       if (!next) return;
-      setSize(figureSize(targetId));
       clear();
+      if (writeFigure === undefined) {
+        setSize(targetId === undefined ? null : figureSize(targetId));
+        return;
+      }
+      // A written figure is measured once it is written; only the last
+      // opening is answered.
+      opening.current += 1;
+      const ticket = opening.current;
+      writeFigure().then(
+        (figure) => {
+          if (ticket !== opening.current) return;
+          setSize({ width: figure.width, height: figure.height });
+        },
+        () => {
+          if (ticket === opening.current) setSize(null);
+        },
+      );
     },
-    [targetId, clear],
+    [targetId, writeFigure, clear],
   );
 
   // What the last copy came to only describes the choices it was made with.
@@ -164,25 +147,28 @@ export function useFigureDownload(
       format={format}
       scale={scale}
       scales={scales}
+      unit={unit}
+      svgAtOwnSize={svgAtOwnSize}
       size={size}
       failure={failure}
       notice={notice}
       saving={busy}
       onFormatChange={changed(setFormat)}
-      onScaleChange={changed((next: number) =>
-        setPicked((current) => ({ ...current, [format]: next })),
-      )}
+      onScaleChange={changed((next: number) => {
+        setPicked((current) => ({ ...current, [format]: next }));
+        if (format === 'png') onScaleChange?.(next);
+      })}
       onSave={save}
       onCopy={copy}
       sizing={
-        renderFigure === undefined
-          ? undefined
-          : {
+        redraws
+          ? {
               layout,
               custom,
               onLayoutChange: changed(setLayout),
               onCustomChange: changed(setCustom),
             }
+          : undefined
       }
     />
   );

package/src/ecosystem/core/sites.ts

@@ -350,6 +350,20 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     brandAlt: '#a16207',
     mark: { plate: '#0072b2', accent: '#e69f00' },
   },
+  {
+    id: 'draw',
+    name: { lead: 'draw', alt: 'cheminfo', dot: true },
+    host: 'draw.cheminfo.org',
+    tagline: 'Journal-grade structures, in an SVG that keeps the chemistry.',
+    group: 'computing',
+    // The ink a structure is printed in.
+    brand: '#1f2a44',
+    // The red curly arrows are taught in, at 5.9:1 on white.
+    brandAlt: '#c0261d',
+    // Ink and red on paper: a red nib on the navy stays under 4:1, where on
+    // white it reads at 5.9:1.
+    mark: { plate: '#ffffff', accent: '#c0261d', edge: '#dfe3e8' },
+  },
 ];
 
 /** How a link to a site is written, beyond the site itself. */

package/src/ecosystem/core/types.ts

@@ -35,7 +35,8 @@ export type SiteId =
   | 'chembio'
   | 'wikidata'
   | 'mz'
-  | 'vibrations';
+  | 'vibrations'
+  | 'draw';
 
 /** A site's name, split the way its own wordmark splits it. */
 export interface SiteName {

package/src/ecosystem/ui/glyphs.tsx

@@ -602,4 +602,24 @@ export const GLYPHS: Record<SiteId, (alt: string) => ReactNode> = {
       />
     </>
   ),
+  // A ring in ink, with a pen nib drawing its last bond in the answering
+  // colour: a structure being drawn by hand.
+  draw: (alt) => (
+    <>
+      <path
+        d="M19 15.25 19 22.75 12.5 26.5 6 22.75 6 15.25 12.5 11.5 15.3 13.1"
+        fill="none"
+        stroke="#1f2a44"
+        strokeWidth="2.4"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      />
+      <path
+        d="M15.6 13 22.32 11.94 26.35 6.78 21.82 2.25 16.66 6.28Z"
+        fill={alt}
+      />
+      <path d="M16.59 12.01 20.13 8.47" stroke="#ffffff" strokeWidth="1.1" />
+      <circle cx="20.55" cy="8.05" r="1.25" fill="#ffffff" />
+    </>
+  ),
 };

package/src/host/core/connectHost.ts

@@ -109,7 +109,7 @@ export function connectHost(options: HostConnectionOptions): () => void {
         const result =
           request.type === 'load'
             ? await applyLoad(request)
-            : answerGet(request, tool, outputs);
+            : await answerGet(request, tool, outputs);
         port?.postMessage(result);
       })
       // A request that failed must not stop the ones after it being served,