react-cheminfo 0.30.0 → 0.31.0

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';

package/src/download/ui/useFigureRedraw.tsx

@@ -0,0 +1,115 @@
+import type { ReactNode } from 'react';
+import { useEffect, useRef, useState } from 'react';
+import { createPortal } from 'react-dom';
+
+import type { FigurePixels } from '../core/figureScale.ts';
+import { whenFigureSettles } from '../core/figureSettle.ts';
+import { figureElement } from '../core/figureTarget.ts';
+
+/** Draws a figure at the size asked for, for a file. */
+export type FigureRenderer = (size: FigurePixels) => ReactNode;
+
+/** What {@link useFigureRedraw} hands back. */
+export interface FigureRedraw {
+  /**
+   * Draw the figure off the page at a size, wait for it to settle, and hand
+   * the box it was drawn in to `save`.
+   */
+  redraw: (
+    targetId: string,
+    size: FigurePixels,
+    save: (box: Element) => Promise<void>,
+  ) => Promise<void>;
+  /** The copy being drawn, to be rendered anywhere in the caller's tree. */
+  portal: ReactNode;
+}
+
+interface RedrawJob {
+  /** The box off the page the copy is drawn in. */
+  box: HTMLElement;
+  /** The size it is drawn at. */
+  size: FigurePixels;
+}
+
+/**
+ * A second copy of a figure, drawn at another size for as long as it takes to
+ * save it.
+ *
+ * The copy is rendered through a portal, so it sees every provider the figure
+ * on the page sees, and the portal's box is placed next to the figure's own,
+ * so it inherits the same tokens and the same type. It sits far to the left of
+ * the page, out of sight, and is taken away once the file is written.
+ * @param render - Draws the figure at a size.
+ * @returns See {@link FigureRedraw}.
+ */
+export function useFigureRedraw(render?: FigureRenderer): FigureRedraw {
+  const [job, setJob] = useState<RedrawJob | null>(null);
+  const controllerRef = useRef<AbortController | null>(null);
+
+  useEffect(() => () => controllerRef.current?.abort(), []);
+
+  async function redraw(
+    targetId: string,
+    size: FigurePixels,
+    save: (box: Element) => Promise<void>,
+  ): Promise<void> {
+    const box = mountRedrawBox(figureElement(targetId), size);
+    const controller = new AbortController();
+    controllerRef.current = controller;
+    setJob({ box, size });
+    try {
+      await whenFigureSettles(box, { signal: controller.signal });
+      await save(box);
+    } finally {
+      controllerRef.current = null;
+      setJob(null);
+      box.remove();
+    }
+  }
+
+  const portal =
+    job === null || render === undefined
+      ? null
+      : createPortal(render(job.size), job.box);
+
+  return { redraw, portal };
+}
+
+/**
+ * The box the copy is drawn in, beside the figure it copies.
+ *
+ * Its type is copied from the figure's box, since a chart inherits its labels'
+ * size from wherever it is mounted and the copy is mounted one level up.
+ * @param target - The box the figure on the page is mounted in.
+ * @param size - The size the copy is drawn at.
+ * @returns The box, already in the document.
+ */
+function mountRedrawBox(target: Element, size: FigurePixels): HTMLElement {
+  const box = document.createElement('div');
+  box.setAttribute('aria-hidden', 'true');
+  box.inert = true;
+  const type = window.getComputedStyle(target);
+  Object.assign(box.style, {
+    position: 'absolute',
+    top: '0',
+    left: '-100000px',
+    width: `${size.width}px`,
+    height: `${size.height}px`,
+    pointerEvents: 'none',
+    fontFamily: type.fontFamily,
+    fontSize: type.fontSize,
+    lineHeight: type.lineHeight,
+    color: type.color,
+  });
+
+  if (target instanceof HTMLElement) {
+    target.after(box);
+    return box;
+  }
+  // A figure named by its `<svg>` gets the box beside the nearest element
+  // that may hold a `<div>`.
+  let host: Element | null = target;
+  while (host instanceof SVGElement) host = host.parentElement;
+  (host ?? document.body).append(box);
+  return box;
+}

package/src/locales/de.json

@@ -183,12 +183,20 @@
   "download.format": "Format",
   "download.formatHelp": "Ein PNG ist ein Bild der Abbildung, und das ist es, was eine Folie, ein Chatfenster oder ein Ticket annimmt. Ein SVG ist die Abbildung selbst: jede Linie bleibt scharf, wie weit man sie auch vergrößert, und sie lässt sich nachträglich bearbeiten.",
   "download.resolution": "Auflösung",
-  "download.resolutionHelp": "Wie viele Pixel für jedes Pixel der Abbildung auf dem Bildschirm gemalt werden. Zwei passt für eine Folie, drei oder vier für den Druck. Ein SVG hat keine eigene Auflösung und wird daher in jeder Größe scharf gespeichert.",
+  "download.resolutionHelp": "Wie viele Male größer als die Abbildung auf dem Bildschirm die Datei ist. Ein PNG bekommt entsprechend mehr Pixel: zwei passt für eine Folie, drei oder vier für den Druck. Ein SVG bleibt in jeder Größe scharf und öffnet sich entsprechend größer.",
   "download.resolutionExample": "Eine auf dem Bildschirm 640 Pixel breite Abbildung wird 1280 Pixel breit gespeichert.",
   "download.noFigure": "Auf der Seite gibt es noch keine Abbildung zum Speichern.",
   "download.hintRasterSvg": "Ein SVG, das ein Bild von {pixels} enthält: eine 3D-Szene hat keine Vektorform.",
-  "download.hintSvg": "Ein SVG bleibt in jeder Größe scharf, die Auflösung gilt also nicht. Gezeichnet {pixels}.",
+  "download.hintSvg": "Öffnet sich mit {pixels} und bleibt in jeder Größe scharf.",
   "download.hintPng": "Gespeichert {pixels}.",
+  "download.size": "Größe",
+  "download.sizeHelp": "Die Form, in der die Abbildung für die Datei gezeichnet wird. Sie wird neu gesetzt, sodass Achsen und Beschriftungen in diese Form passen, statt hineingedehnt zu werden. Eine Zeitschriftenspalte ist 8,5 cm breit, und ihr Text wird in der Größe gedruckt, in der er auf dem Bildschirm steht.",
+  "download.sizeScreen": "Wie angezeigt",
+  "download.sizeColumn": "Zeitschriftenspalte",
+  "download.sizeCustom": "Eigene",
+  "download.customSize": "Breite × Höhe",
+  "download.width": "Breite",
+  "download.height": "Höhe",
   "pedagogy.check": "Prüfen",
   "pedagogy.revealHint": "Hinweis zeigen",
   "pedagogy.revealHintCount": "Hinweis zeigen ({revealed}/{total})",

package/src/locales/en.json

@@ -183,12 +183,20 @@
   "download.format": "Format",
   "download.formatHelp": "A PNG is a picture of the figure, which is what a slide, a chat window or an issue accepts. An SVG is the figure itself: every line stays sharp however far it is enlarged, and it can still be edited afterwards.",
   "download.resolution": "Resolution",
-  "download.resolutionHelp": "How many pixels are painted for each pixel of the figure on screen. Two is right for a slide, three or four for print. An SVG carries no resolution of its own, so it is saved sharp at every size.",
+  "download.resolutionHelp": "How many times the figure on screen the file is. A PNG gets that many more pixels: two is right for a slide, three or four for print. An SVG stays sharp at any size, and opens that many times larger.",
   "download.resolutionExample": "A figure 640 pixels wide on screen is saved 1280 pixels wide.",
   "download.noFigure": "There is no figure on the page to save yet.",
   "download.hintRasterSvg": "An SVG holding a picture of {pixels}: a 3D scene has no vector form.",
-  "download.hintSvg": "An SVG stays sharp at any size, so the resolution does not apply. Drawn {pixels}.",
+  "download.hintSvg": "Opens at {pixels}, and stays sharp at any size.",
   "download.hintPng": "Saved {pixels}.",
+  "download.size": "Size",
+  "download.sizeHelp": "The shape the figure is drawn at for the file. It is laid out again, so the axes and labels fit that shape instead of being stretched into it. A journal column is 8.5 cm wide, and its text prints at the size it reads on screen.",
+  "download.sizeScreen": "As shown",
+  "download.sizeColumn": "Journal column",
+  "download.sizeCustom": "Custom",
+  "download.customSize": "Width × height",
+  "download.width": "Width",
+  "download.height": "Height",
   "pedagogy.check": "Check",
   "pedagogy.revealHint": "Reveal hint",
   "pedagogy.revealHintCount": "Reveal hint ({revealed}/{total})",

package/src/locales/es.json

@@ -183,12 +183,20 @@
   "download.format": "Formato",
   "download.formatHelp": "Un PNG es una imagen de la figura, que es lo que aceptan una diapositiva, una ventana de chat o una incidencia. Un SVG es la figura misma: cada línea sigue nítida por mucho que se amplíe, y todavía puede editarse después.",
   "download.resolution": "Resolución",
-  "download.resolutionHelp": "Cuántos píxeles se pintan por cada píxel de la figura en pantalla. Dos va bien para una diapositiva, tres o cuatro para imprimir. Un SVG no tiene resolución propia, así que se guarda nítido a cualquier tamaño.",
+  "download.resolutionHelp": "Cuántas veces la figura en pantalla mide el archivo. Un PNG recibe tantos píxeles más: dos sirve para una diapositiva, tres o cuatro para imprimir. Un SVG se mantiene nítido a cualquier tamaño, y se abre tantas veces más grande.",
   "download.resolutionExample": "Una figura de 640 píxeles de ancho en pantalla se guarda con 1280 píxeles de ancho.",
   "download.noFigure": "Todavía no hay ninguna figura en la página que guardar.",
   "download.hintRasterSvg": "Un SVG que contiene una imagen de {pixels}: una escena 3D no tiene forma vectorial.",
-  "download.hintSvg": "Un SVG sigue nítido a cualquier tamaño, de modo que la resolución no se aplica. Dibujado {pixels}.",
+  "download.hintSvg": "Se abre a {pixels}, y se mantiene nítido a cualquier tamaño.",
   "download.hintPng": "Guardado {pixels}.",
+  "download.size": "Tamaño",
+  "download.sizeHelp": "La forma con la que se dibuja la figura para el archivo. Se vuelve a maquetar, de modo que los ejes y las etiquetas se ajustan a esa forma en lugar de estirarse. Una columna de revista mide 8,5 cm, y su texto se imprime al tamaño con que se lee en pantalla.",
+  "download.sizeScreen": "Como se muestra",
+  "download.sizeColumn": "Columna de revista",
+  "download.sizeCustom": "Personalizado",
+  "download.customSize": "Ancho × alto",
+  "download.width": "Ancho",
+  "download.height": "Alto",
   "pedagogy.check": "Comprobar",
   "pedagogy.revealHint": "Mostrar una pista",
   "pedagogy.revealHintCount": "Mostrar una pista ({revealed}/{total})",

package/src/locales/fr.json

@@ -183,12 +183,20 @@
   "download.format": "Format",
   "download.formatHelp": "Un PNG est une image de la figure, ce qu'acceptent une diapositive, une fenêtre de discussion ou un ticket. Un SVG est la figure elle-même : chaque trait reste net quel que soit l'agrandissement, et il reste modifiable ensuite.",
   "download.resolution": "Résolution",
-  "download.resolutionHelp": "Combien de pixels sont peints pour chaque pixel de la figure à l'écran. Deux convient pour une diapositive, trois ou quatre pour l'impression. Un SVG n'a pas de résolution propre : il est enregistré net à toute taille.",
+  "download.resolutionHelp": "Combien de fois la figure à l'écran mesure le fichier. Un PNG reçoit d'autant plus de pixels : deux convient pour une diapositive, trois ou quatre pour l'impression. Un SVG reste net à toute taille, et s'ouvre d'autant plus grand.",
   "download.resolutionExample": "Une figure large de 640 pixels à l'écran est enregistrée large de 1280 pixels.",
   "download.noFigure": "Il n'y a encore aucune figure à enregistrer sur la page.",
   "download.hintRasterSvg": "Un SVG contenant une image de {pixels} : une scène 3D n'a pas de forme vectorielle.",
-  "download.hintSvg": "Un SVG reste net à toute taille, la résolution ne s'applique donc pas. Dessiné {pixels}.",
+  "download.hintSvg": "S'ouvre à {pixels}, et reste net à toute taille.",
   "download.hintPng": "Enregistré {pixels}.",
+  "download.size": "Taille",
+  "download.sizeHelp": "La forme à laquelle la figure est dessinée pour le fichier. Elle est remise en page, si bien que les axes et les étiquettes s'ajustent à cette forme au lieu d'y être étirés. Une colonne de revue mesure 8,5 cm, et son texte s'imprime à la taille où il se lit à l'écran.",
+  "download.sizeScreen": "Comme affichée",
+  "download.sizeColumn": "Colonne de revue",
+  "download.sizeCustom": "Personnalisée",
+  "download.customSize": "Largeur × hauteur",
+  "download.width": "Largeur",
+  "download.height": "Hauteur",
   "pedagogy.check": "Vérifier",
   "pedagogy.revealHint": "Révéler un indice",
   "pedagogy.revealHintCount": "Révéler un indice ({revealed}/{total})",

package/src/overlay/ui/OverlayValueMenu.tsx

@@ -108,7 +108,13 @@ export function OverlayValueMenu<TValue extends string = string>(
               text={option.label}
               htmlTitle={option.title}
               disabled={option.disabled}
-              onClick={() => onChange(option.value)}
+              // A menu opened from inside a panel would otherwise dismiss the
+              // panel too, taking the reader's other settings away mid-choice.
+              shouldDismissPopover={false}
+              onClick={() => {
+                onChange(option.value);
+                setOpen(false);
+              }}
             />
           ))}
         </Menu>