react-cheminfo 0.27.0 → 0.29.0

package/src/chart/ui/useChartZoom.ts

@@ -0,0 +1,255 @@
+/**
+ * The gestures that move the window a chart is showing.
+ *
+ * A drag zooms the x axis, because that is the axis a chemist reads: the
+ * question is nearly always "what is between 366 and 372", never "what is
+ * between forty and sixty percent". The y axis comes along only when the drag is
+ * released past the baseline, a gesture that cannot be made by accident and one
+ * the preview rectangle announces before the button is let go. The wheel scales
+ * the y axis on its own, bringing up the small features being asked about far
+ * more often than any box around them, and a double click puts the window back.
+ *
+ * Which of them a chart answers is `ZoomGestures`, and a viewer is free to offer
+ * fewer: a drag can be the rectangle it sweeps out, and the wheel can be left to
+ * the page. Neither is a preference to be toggled — it is what the measurement
+ * makes worth doing, and `chartDomain.ts` says why.
+ *
+ * Not every gesture moves the window. A drag can be asked to report the range it
+ * swept out, a press that went nowhere is a click, and a host can refuse a press
+ * outright so that a handle drawn on the chart keeps the gesture aimed at it;
+ * `chartGestures.ts` holds all three, and `zoomDomain.ts` holds what a gesture
+ * does to a window. Neither knows anything of React, which is what lets the
+ * answer to a gesture be read without a chart on screen.
+ *
+ * What the window is fitted *to* is handed in rather than worked out here, and
+ * that is what makes one hook serve every kind of spectrum: fitting reads the
+ * traces, and a mass spectrum's are two per spectrum where an infrared
+ * spectrum's are one in either of two units. `useChartWindow` then holds the
+ * answer each viewer hands over.
+ */
+
+import type { PointerEvent as ReactPointerEvent, RefObject } from 'react';
+import { useCallback, useMemo, useState } from 'react';
+
+import type {
+  ChartDomain,
+  YAxisRules,
+  ZoomGestures,
+  ZoomRules,
+} from '../core/chartDomain.ts';
+import { DEFAULT_ZOOM_GESTURES } from '../core/chartDomain.ts';
+import type { ChartScale } from '../core/chartScale.ts';
+import { chartWheelFactor } from '../core/chartViewport.ts';
+import type { ZoomSelection } from '../core/zoomDomain.ts';
+import { scaledYAxis, zoomSelection } from '../core/zoomDomain.ts';
+
+import type {
+  ChartGestureReports,
+  ChartZoomHandlers,
+  Drag,
+} from './chartGestures.ts';
+import {
+  answeredRelease,
+  draggedTo,
+  releaseDrag,
+  startedDrag,
+} from './chartGestures.ts';
+import type { ChartWindowOptions } from './useChartWindow.ts';
+import { useChartWindow } from './useChartWindow.ts';
+import { useWheelListener } from './useWheelListener.ts';
+
+/** The chart, what it is fitted to, and which gestures it answers. */
+export interface ChartZoomOptions
+  extends ChartWindowOptions, ChartGestureReports {
+  /** The SVG the gestures are made on, as it was handed to its `ref`. */
+  svgRef: RefObject<SVGSVGElement | null>;
+  /**
+   * How the y axis behaves under a gesture — where its baseline is, and whether
+   * that baseline is held in the window.
+   * @default a stick spectrum's: a baseline of zero, always kept
+   */
+  yAxis?: YAxisRules;
+  /**
+   * Which gestures the chart answers: what a drag asks for, and whether the
+   * wheel scales the value axis at all.
+   *
+   * Both together rather than one at a time, because they are one decision. A
+   * viewer that reads its data in more than one way — an infrared spectrum is
+   * read as absorbance or as percent transmittance — settles the whole set from
+   * whatever it is currently reading, and hands it over as it stands.
+   * @default every gesture: a drag along the horizontal axis, and the wheel
+   */
+  gestures?: ZoomGestures;
+}
+
+/** The window, the drag being made in it, and how to work both. */
+export interface ChartZoom {
+  /** What the chart is showing. */
+  domain: ChartDomain;
+  /**
+   * The horizontal axis, as every gesture was measured against it: **draw with
+   * this rather than building one**, since a second scale beside it is a second
+   * chance to get a reversed axis the wrong way round.
+   */
+  xScale: ChartScale;
+  /** The vertical axis, likewise. */
+  yScale: ChartScale;
+  /** The drag being made, `null` when none is. */
+  selection: ZoomSelection | null;
+  /** Put the window back to everything that is drawn. */
+  reset: () => void;
+  /** Put on the SVG. */
+  handlers: ChartZoomHandlers;
+}
+
+/**
+ * Zoom a chart by dragging it, by the wheel and by double clicking it.
+ *
+ * Which window is on screen — the fit, the one a gesture arrived at, or the one
+ * a host imposes — is `useChartWindow`. What is here is what a gesture *is*: the
+ * drag as it is made, the rules it is read under, and the answer it comes to.
+ * @param options - The chart, the fit and how its y axis behaves.
+ * @returns The window and the gestures that move it.
+ */
+export function useChartZoom(options: ChartZoomOptions): ChartZoom {
+  const {
+    fitted,
+    fitKey,
+    yFitKey,
+    svgRef,
+    plot,
+    yAxis,
+    gestures,
+    reverseX = false,
+    domain: imposed = null,
+    onSelectRange,
+    onClick,
+    shouldStartDrag,
+  } = options;
+
+  const { domain, xScale, yScale, show, reset } = useChartWindow({
+    fitted,
+    fitKey,
+    ...(yFitKey === undefined ? {} : { yFitKey }),
+    plot,
+    domain: imposed,
+    reverseX,
+  });
+
+  // Taken apart field by field rather than depending on the object, so a viewer
+  // rebuilding an equal `yAxis` or `gestures` on every render does not rebuild
+  // the rules and every callback hanging off them. Every field has to be listed
+  // here: one left out silently falls back to its default, which is how a
+  // transmittance chart came to answer a mass spectrum's question about its own
+  // baseline.
+  const baseline = yAxis?.baseline;
+  const keepBaseline = yAxis?.keepBaseline;
+  const pointsDown = yAxis?.pointsDown;
+  const dragMode = gestures?.drag ?? DEFAULT_ZOOM_GESTURES.drag;
+  const wheel = gestures?.wheel ?? DEFAULT_ZOOM_GESTURES.wheel;
+  const rules = useMemo<ZoomRules>(
+    () => ({ baseline, keepBaseline, pointsDown, drag: dragMode }),
+    [baseline, keepBaseline, pointsDown, dragMode],
+  );
+
+  const [drag, setDrag] = useState<Drag | null>(null);
+
+  const onWheel = useCallback(
+    (event: WheelEvent) => {
+      // Refused before the event is touched, so a chart that does not answer the
+      // wheel scrolls the page under the pointer exactly as the rest of it does.
+      // Swallowing the gesture and doing nothing with it would be the one
+      // outcome nobody asked for.
+      if (!wheel) return;
+      const factor = chartWheelFactor(event.deltaY, event.deltaMode);
+      if (factor === 1) return;
+      // Heard non-passively for exactly this: without the refusal the chart
+      // zooms and the page scrolls out from under it at the same time.
+      event.preventDefault();
+      show(scaledYAxis(domain, factor, rules.baseline));
+    },
+    [domain, rules.baseline, wheel, show],
+  );
+  useWheelListener(svgRef, onWheel);
+
+  const onPointerDown = useCallback(
+    (event: ReactPointerEvent<SVGSVGElement>) => {
+      const started = startedDrag(event, svgRef.current, shouldStartDrag);
+      if (started !== null) setDrag(started);
+    },
+    [svgRef, shouldStartDrag],
+  );
+
+  const onPointerMove = useCallback(
+    (event: ReactPointerEvent<SVGSVGElement>) => {
+      const moved = draggedTo(drag, event, svgRef.current);
+      if (moved !== null) setDrag(moved);
+    },
+    [drag, svgRef],
+  );
+
+  const onPointerUp = useCallback(
+    (event: ReactPointerEvent<SVGSVGElement>) => {
+      if (drag?.pointerId !== event.pointerId) return;
+      releaseDrag(event);
+      setDrag(null);
+      const released = draggedTo(drag, event, svgRef.current) ?? drag;
+      const next = answeredRelease(
+        domain,
+        released,
+        plot,
+        xScale,
+        yScale,
+        rules,
+        { onSelectRange, onClick },
+        // Read off the release rather than off the press, because that is where
+        // the reader was looking and what `reportClick` already inverts.
+        { shift: event.shiftKey, alt: event.altKey },
+      );
+      if (next !== null) show(next);
+    },
+    [
+      drag,
+      domain,
+      plot,
+      xScale,
+      yScale,
+      svgRef,
+      rules,
+      onSelectRange,
+      onClick,
+      show,
+    ],
+  );
+
+  const onPointerCancel = useCallback(
+    (event: ReactPointerEvent<SVGSVGElement>) => {
+      if (drag?.pointerId !== event.pointerId) return;
+      releaseDrag(event);
+      setDrag(null);
+    },
+    [drag],
+  );
+
+  const selection = useMemo(
+    () => zoomSelection(drag, yScale, rules),
+    [drag, yScale, rules],
+  );
+
+  return {
+    domain,
+    xScale,
+    yScale,
+    selection,
+    reset,
+    handlers: {
+      onPointerDown,
+      onPointerMove,
+      onPointerUp,
+      onPointerCancel,
+      onDoubleClick: reset,
+    },
+  };
+}
+
+export { type ChartZoomHandlers } from './chartGestures.ts';

package/src/chart/ui/useWheelListener.ts

@@ -0,0 +1,62 @@
+/**
+ * The wheel over an element, heard loudly enough to refuse the page its
+ * scroll.
+ *
+ * React's `onWheel` is registered passively — the browser is told in advance
+ * that the page may scroll before the handler has had its say — so calling
+ * `preventDefault` inside it does nothing at all: the chart zooms and the page
+ * scrolls out from under it at the same time. The only way to be heard is to
+ * register the listener on the element directly with `{ passive: false }`,
+ * which is what this hook exists to do; nothing else about the gesture belongs
+ * here.
+ *
+ * The listener is attached once and reads the handler through a ref refreshed
+ * on every commit. Both halves are needed: attaching once is what keeps a
+ * pointer resting over the chart from re-registering a listener sixty times a
+ * second, and reading the handler live is what stops that one listener from
+ * zooming the window as it stood when the chart was mounted.
+ */
+
+import type { RefObject } from 'react';
+import { useEffect, useLayoutEffect, useRef } from 'react';
+
+/**
+ * Hear the wheel over an element.
+ * @param ref - The element, as it was handed to its `ref`.
+ * @param handler - What to do with the wheel; free to be an inline arrow, since
+ * it is read at the moment the wheel turns rather than closed over when the
+ * listener is attached. It is the handler's own business to call
+ * `preventDefault` — the listener is registered so that the call is honoured,
+ * not so that it is made.
+ */
+export function useWheelListener<T extends Element>(
+  ref: RefObject<T | null>,
+  handler: (event: WheelEvent) => void,
+): void {
+  const latest = useRef(handler);
+  useLayoutEffect(() => {
+    latest.current = handler;
+  });
+
+  useEffect(() => {
+    const element = ref.current;
+    if (element === null) return;
+    // Typed as the plain `Event` the element's own listener map hands it: an
+    // `Element` is not known to carry a wheel, so the narrowing is done here.
+    function onWheel(event: Event) {
+      if (event instanceof WheelEvent) latest.current(event);
+    }
+    element.addEventListener('wheel', onWheel, WHEEL_LISTENER);
+    return () => {
+      element.removeEventListener('wheel', onWheel);
+    };
+  }, [ref]);
+}
+
+/**
+ * Registered non-passively, which is the whole reason this hook exists. Nothing
+ * is passed back on removal: a listener is matched on its type, its function
+ * and its capture flag alone, and passing the options object there is a type
+ * error rather than a courtesy.
+ */
+const WHEEL_LISTENER = { passive: false } as const;

package/src/clipboard/core/copyPng.ts

@@ -0,0 +1,20 @@
+/**
+ * Put a PNG on the clipboard.
+ *
+ * The image is handed over as a promise rather than as a blob on purpose:
+ * Safari only allows a clipboard write that the click itself started, so the
+ * item has to be built while the handler is still running and the
+ * rasterization awaited by the clipboard rather than before it.
+ * @param png - The image being rasterized.
+ * @returns Whether it was copied. `false` outside a secure context, and in a
+ *   browser whose clipboard takes text only.
+ */
+export async function writeImageToClipboard(
+  png: Promise<Blob>,
+): Promise<boolean> {
+  if (typeof ClipboardItem === 'undefined' || !navigator.clipboard?.write) {
+    return false;
+  }
+  await navigator.clipboard.write([new ClipboardItem({ 'image/png': png })]);
+  return true;
+}

package/src/clipboard/core/index.ts

@@ -1,3 +1,4 @@
+export { writeImageToClipboard } from './copyPng.ts';
 export type { WriteBlobToClipboardOptions } from './writeBlobToClipboard.ts';
 export { writeBlobToClipboard } from './writeBlobToClipboard.ts';
 export type { ClipboardContent, ClipboardText } from './writeToClipboard.ts';

package/src/clipboard/ui/CopyableValue.tsx

@@ -4,7 +4,6 @@ import { MISSING_VALUE } from '../../format/core/missing.ts';
 import { TOKEN } from '../../tokens/core/familyTokens.ts';
 
 import { ClickToCopy } from './ClickToCopy.tsx';
-import { CopyButton } from './CopyButton.tsx';
 
 const DEFAULT_BLOCK_HEIGHT = 160;
 
@@ -12,7 +11,7 @@ const DEFAULT_BLOCK_HEIGHT = 160;
 export interface CopyableValueProps {
   /** What the value is, written above it, e.g. `InChIKey`. */
   label: string;
-  /** The value itself, which is also what the button copies. */
+  /** The value itself, which is what a click on it copies. */
   value: string;
   /**
    * A longer explanation of the label, shown on hover.
@@ -31,8 +30,9 @@ export interface CopyableValueProps {
    */
   maxHeight?: number | string;
   /**
-   * What the pointer and a screen reader are told the button does.
-   * @default `Copy the ${label}`
+   * What the pointer and a screen reader are told, replacing the title built
+   * from the label and the value.
+   * @default undefined — `Copy the ${label} (${value})`
    */
   copyTitle?: string;
   /**
@@ -48,14 +48,16 @@ export interface CopyableValueProps {
 }
 
 /**
- * One read-only value, named, with the button that copies it.
+ * One read-only value, named, copied by clicking it.
  *
- * A derived notation — a SMILES, an InChIKey, an accession — is only useful
- * somewhere else, so a click on the value or on its button puts it on the
- * clipboard. An empty value reads as the missing marker and offers nothing to
- * copy.
+ * A derived notation — a SMILES, an InChIKey, an accession, a computed energy
+ * — is only useful somewhere else, so the value is the button that copies it:
+ * the cursor carries a clipboard over it, a click or `Enter` puts it on the
+ * clipboard, and a tick confirms. Nothing is drawn beside the label, which
+ * names the value and no more. An empty value reads as the missing marker and
+ * offers nothing to copy.
  * @param props - See {@link CopyableValueProps}.
- * @returns The labelled value and its copy button.
+ * @returns The labelled value.
  */
 export function CopyableValue(props: CopyableValueProps): ReactElement {
   const {
@@ -64,7 +66,7 @@ export function CopyableValue(props: CopyableValueProps): ReactElement {
     hint,
     block = false,
     maxHeight = DEFAULT_BLOCK_HEIGHT,
-    copyTitle = `Copy the ${label}`,
+    copyTitle,
     children,
     className,
   } = props;
@@ -78,27 +80,18 @@ export function CopyableValue(props: CopyableValueProps): ReactElement {
           : `copyable-value ${className}`
       }
     >
-      <div style={HEADER_STYLE}>
-        <span
-          className="copyable-value__label"
-          style={hint === undefined ? LABEL_STYLE : HINTED_LABEL_STYLE}
-          title={hint}
-        >
-          {label}
-        </span>
-        <CopyButton
-          content={value}
-          title={copyTitle}
-          disabled={isEmpty}
-          minimal
-          small
-        />
-      </div>
+      <span
+        className="copyable-value__label"
+        style={hint === undefined ? LABEL_STYLE : HINTED_LABEL_STYLE}
+        title={hint}
+      >
+        {label}
+      </span>
       <ClickToCopy
         as="code"
         value={value}
         label={label}
-        focusable={false}
+        title={copyTitle}
         disabled={isEmpty}
         className="copyable-value__value"
         style={block ? { ...BLOCK_VALUE_STYLE, maxHeight } : VALUE_STYLE}
@@ -110,14 +103,8 @@ export function CopyableValue(props: CopyableValueProps): ReactElement {
   );
 }
 
-const HEADER_STYLE = {
-  display: 'flex',
-  alignItems: 'center',
-  justifyContent: 'space-between',
-  gap: 8,
-} as const satisfies CSSProperties;
-
 const LABEL_STYLE = {
+  display: 'block',
   color: TOKEN.textMuted,
   fontSize: 12,
   fontWeight: 600,

package/src/core.ts

@@ -14,6 +14,7 @@ export * from './i18n/core/index.ts';
 export * from './language/core/index.ts';
 export * from './orbital/core/index.ts';
 export * from './overlay/core/index.ts';
+export * from './panel/core/index.ts';
 export * from './parallel/core/index.ts';
 export * from './pedagogy/core/index.ts';
 export * from './periodic/core/index.ts';

package/src/download/core/exportStyles.ts

@@ -0,0 +1,20 @@
+/**
+ * A row of buttons with the name box among them, wrapping when the dialog is
+ * too narrow for them.
+ */
+export const exportButtonsStyle = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  alignItems: 'center',
+  gap: 6,
+} as const;
+
+/** One group of an export dialog: what it offers, in a column. */
+export const exportSectionStyle = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 8,
+} as const;
+
+/** Text that says something about a control rather than being one. */
+export const exportNoteStyle = { fontSize: 12, opacity: 0.7 } as const;

package/src/download/core/imageResolution.ts

@@ -0,0 +1,118 @@
+/** How big a picture is written out, as a multiple of the size it is drawn at. */
+export interface ImageResolution {
+  /** Identifies the resolution in a picker. */
+  id: string;
+  /** What the option reads. */
+  label: string;
+  /** How many pixels each drawing unit becomes. */
+  scale: number;
+}
+
+/**
+ * The sizes a picture leaves the editor at.
+ *
+ * A drawing unit is about a screen pixel, so the multipliers read as what the
+ * picture is for rather than as numbers: what is on screen, the same again on a
+ * retina display, and the two steps up a figure needs to survive being printed
+ * or thrown on a wall.
+ */
+export const IMAGE_RESOLUTIONS = [
+  { id: 'screen', label: 'Screen (1×)', scale: 1 },
+  { id: 'retina', label: 'Retina (2×)', scale: 2 },
+  { id: 'print', label: 'Print (4×)', scale: 4 },
+  { id: 'poster', label: 'Poster (8×)', scale: 8 },
+] as const satisfies readonly ImageResolution[];
+
+/** One of the resolutions offered. */
+export type ImageResolutionId = (typeof IMAGE_RESOLUTIONS)[number]['id'];
+
+/**
+ * The resolution a picture is written out at unless another is picked: what is
+ * on screen, doubled, which is what a picture pasted into a document wants.
+ */
+export const DEFAULT_IMAGE_RESOLUTION = IMAGE_RESOLUTIONS[1];
+
+/**
+ * Longest side a browser rasterizes reliably.
+ *
+ * Above roughly this, Safari and Chrome quietly hand back an empty canvas
+ * instead of refusing, so the picture would be saved blank.
+ */
+const MAXIMUM_SIDE = 8192;
+
+/** Most pixels a rasterized picture is allowed to hold. */
+const MAXIMUM_PIXELS = 32 * 1024 * 1024;
+
+/** How big a picture comes out, in pixels. */
+export interface ImageSize {
+  /** Width of the picture, in pixels. */
+  width: number;
+  /** Height of the picture, in pixels. */
+  height: number;
+  /**
+   * What each drawing unit was actually worth. Below the resolution that was
+   * asked for when it would have made a picture too big to rasterize.
+   */
+  scale: number;
+}
+
+/**
+ * How big a rectangle of the drawing comes out at a given resolution.
+ *
+ * The resolution is a wish rather than an instruction: a wide glycan asked for
+ * at 8× would run past what a browser can rasterize and come back blank, so the
+ * scale is brought down until the picture fits instead. The scale it settled on
+ * comes back with the size, so what will actually be written can be shown
+ * before it is.
+ * @param box - The rectangle being written out.
+ * @param box.width - How wide it is, in drawing units.
+ * @param box.height - How tall it is, in drawing units.
+ * @param scale - How many pixels each drawing unit should become.
+ * @returns The size, and the scale it was reached at.
+ */
+export function imageSize(
+  box: { width: number; height: number },
+  scale: number,
+): ImageSize {
+  const wanted = Number.isFinite(scale) && scale > 0 ? scale : 1;
+  const width = Math.max(box.width, 1);
+  const height = Math.max(box.height, 1);
+
+  const limit = Math.min(
+    MAXIMUM_SIDE / width,
+    MAXIMUM_SIDE / height,
+    Math.sqrt(MAXIMUM_PIXELS / (width * height)),
+  );
+  const used = Math.min(wanted, limit);
+  // A picture held back by the limit is rounded down rather than to the nearest
+  // pixel, so rounding cannot put it back over what it was held to.
+  const toPixels = used < wanted ? Math.floor : Math.round;
+
+  return {
+    width: Math.max(1, toPixels(width * used)),
+    height: Math.max(1, toPixels(height * used)),
+    scale: used,
+  };
+}
+
+/**
+ * The resolution an identifier stands for.
+ * @param id - What was picked.
+ * @returns The resolution, falling back to the default one.
+ */
+export function imageResolution(id: string): ImageResolution {
+  return (
+    IMAGE_RESOLUTIONS.find((resolution) => resolution.id === id) ??
+    DEFAULT_IMAGE_RESOLUTION
+  );
+}
+
+/**
+ * A size, written the way it is shown next to the resolution it comes from.
+ * @param size - The size to write, `null` when nothing is drawn.
+ * @returns The text, e.g. `1440 × 620 px`.
+ */
+export function formatImageSize(size: ImageSize | null): string {
+  if (!size) return 'nothing to export';
+  return `${size.width} × ${size.height} px`;
+}

package/src/download/core/index.ts

@@ -37,3 +37,37 @@ export {
   figureSize,
 } from './figureTarget.ts';
 export { sanitizeFileName } from './sanitizeFileName.ts';
+
+export {
+  exportButtonsStyle,
+  exportNoteStyle,
+  exportSectionStyle,
+} from './exportStyles.ts';
+export type {
+  ImageResolution,
+  ImageResolutionId,
+  ImageSize,
+} from './imageResolution.ts';
+export {
+  DEFAULT_IMAGE_RESOLUTION,
+  IMAGE_RESOLUTIONS,
+  formatImageSize,
+  imageResolution,
+  imageSize,
+} from './imageResolution.ts';
+export type { PictureFrame, PictureOptions } from './pictureExport.ts';
+export {
+  PICTURE_PADDING,
+  copyPicture,
+  pictureSize,
+  savePngPicture,
+  saveSvgPicture,
+} from './pictureExport.ts';
+export { drawingIn, stackDrawings } from './stackedDrawing.ts';
+export type { SvgBox } from './svgBounds.ts';
+export { CONTENT_ATTRIBUTE, contentBox, elementBox } from './svgBounds.ts';
+export { SVG_NAMESPACE } from './svgNamespace.ts';
+export type { PngOptions } from './svgToPng.ts';
+export { svgToPng } from './svgToPng.ts';
+export type { SvgDocumentOptions } from './svgToString.ts';
+export { svgToString } from './svgToString.ts';