react-cheminfo 0.28.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/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';