react-cheminfo 0.27.0 → 0.29.0

package/src/chart/ui/useChartPointer.ts

@@ -0,0 +1,223 @@
+/**
+ * Where the pointer is over a chart, and what that place means.
+ *
+ * What it *means* is the one thing this hook does not decide. A mass spectrum
+ * reads an m/z, an intensity and the peak within reach; an infrared spectrum
+ * reads a wavenumber, an absorbance and the band it falls in. Both are the same
+ * mechanism — place the pointer in user units, refuse the margins, and report
+ * only when the answer changed — so the mechanism is here and the reading is
+ * handed in.
+ *
+ * Every value is compared before it is stored or reported. A pointer resting on
+ * one feature fires `pointermove` on every sub-pixel tremor of a hand, and a
+ * fresh answer each time would re-render the panel beside the chart — and, where
+ * that panel is a linked viewer that reports its own hovers back, would
+ * ping-pong between the two until the tab stops answering.
+ */
+
+import type { RefObject } from 'react';
+import { useEffect, useLayoutEffect, useRef, useState } from 'react';
+
+import type { PlotRect } from '../core/chartGeometry.ts';
+import type { ChartPoint } from '../core/svgPoint.ts';
+import { svgPointAt } from '../core/svgPoint.ts';
+
+/** Where the pointer is, and what that place means. */
+export interface ChartPointer<TReadout> {
+  /** Its position in user units, `null` whenever it is off the plot. */
+  position: ChartPoint | null;
+  /** What the chart reads under it, `null` whenever it is off the plot. */
+  readout: TReadout | null;
+}
+
+export interface ChartPointerOptions<TReadout> {
+  /** The SVG the chart is drawn on, as it was handed to its `ref`. */
+  svgRef: RefObject<SVGSVGElement | null>;
+  /**
+   * Where the plot sits inside that SVG. The pointer is only followed inside
+   * it: the margins carry the axis labels, and a crosshair drawn across them
+   * claims to read a value off a place where none is drawn.
+   */
+  plot: PlotRect;
+  /**
+   * What the chart reads at a point. Called on every move the pointer makes
+   * inside the plot, and read live rather than closed over, so it may capture
+   * the scales as they are currently zoomed.
+   */
+  read: (point: ChartPoint) => TReadout;
+  /**
+   * Whether two readings say the same thing, which is what suppresses the
+   * report of a hand resting still.
+   *
+   * A viewer normally compares less than the whole reading: the pointer's own
+   * position has already been compared by the time this is asked, so what is
+   * left is whichever *feature* the reading is about — the peak, the band — and
+   * not the fractional value under the crosshair, which changes on every pixel.
+   */
+  sameReadout: (current: TReadout, next: TReadout) => boolean;
+  /**
+   * Told what the chart reads under the pointer, and told `null` when it leaves
+   * the plot — called only when `sameReadout` says the answer changed, so it is
+   * safe to hang a highlight that redraws half the page on it.
+   * @default undefined
+   */
+  onReadout?: (readout: TReadout | null) => void;
+}
+
+/**
+ * Follow the pointer over a chart.
+ *
+ * The listeners are attached to the element rather than returned as props, so
+ * that a chart already spreading another hook's `onPointerMove` onto its SVG
+ * does not have to merge two handlers into one — and so that the options are
+ * read live, at the moment the pointer moves, rather than closed over when the
+ * listener was attached.
+ *
+ * The pointer leaving is heard as `pointerout` and not as the `pointerleave`
+ * that reads so much more naturally, because a chart with a control laid over
+ * it — a legend whose rows answer a hover — has two writers of one highlight
+ * and they must be sequenced. React synthesises the overlay's `pointerenter`
+ * from the *earlier* `pointerout` and dispatches it at the root, so a browser
+ * fires `pointerout` on the SVG, then React's `onPointerEnter` on the row, then
+ * `pointerleave` on the SVG: listening for the leave puts this hook's "nothing
+ * is under the pointer" **after** the row's "this trace is being read", and
+ * wipes it. Heard as `pointerout`, the report lands first and the row has the
+ * last word. The containment test is what `pointerleave` was giving for free.
+ * @param options - The chart, and how to read a point on it.
+ * @returns Where the pointer is and what it reads, both `null` while it is
+ * anywhere but over the plot.
+ */
+export function useChartPointer<TReadout>(
+  options: ChartPointerOptions<TReadout>,
+): ChartPointer<TReadout> {
+  const { svgRef } = options;
+  const [pointer, setPointer] = useState<ChartPointer<TReadout>>(POINTER_AWAY);
+  const latest = useRef(options);
+  const reported = useRef<TReadout | null>(null);
+
+  useLayoutEffect(() => {
+    latest.current = options;
+  });
+
+  useEffect(() => {
+    const svg = svgRef.current;
+    if (svg === null) return;
+
+    function show(next: ChartPointer<TReadout>): void {
+      const { sameReadout, onReadout } = latest.current;
+      setPointer((current) => nextChartPointer(current, next, sameReadout));
+      if (sameReading(reported.current, next.readout, sameReadout)) return;
+      reported.current = next.readout;
+      onReadout?.(next.readout);
+    }
+
+    function move(event: PointerEvent): void {
+      const { plot, read } = latest.current;
+      const point = svgPointAt(svg, event.clientX, event.clientY);
+      show(
+        point === null || !isInsidePlot(plot, point)
+          ? POINTER_AWAY
+          : { position: point, readout: read(point) },
+      );
+    }
+
+    function out(event: PointerEvent): void {
+      if (leftChart(svg, event.relatedTarget)) show(POINTER_AWAY);
+    }
+
+    svg.addEventListener('pointermove', move);
+    svg.addEventListener('pointerout', out);
+    return () => {
+      svg.removeEventListener('pointermove', move);
+      svg.removeEventListener('pointerout', out);
+    };
+  }, [svgRef]);
+
+  return pointer;
+}
+
+/**
+ * Whether a `pointerout` means the pointer has left the chart.
+ *
+ * It also fires on the way *into* a child of the SVG — a trace, a label, the
+ * rectangle behind a legend — which is not leaving the chart at all, and is the
+ * one thing `pointerleave` was giving for free.
+ * @param svg - The chart, `null` before it is on screen.
+ * @param related - What the pointer moved onto, `null` when it left the window
+ * altogether.
+ * @returns Whether the chart no longer has the pointer.
+ */
+export function leftChart(
+  svg: Element | null,
+  related: EventTarget | null,
+): boolean {
+  if (svg === null) return true;
+  return !(related instanceof Node) || !svg.contains(related);
+}
+
+/**
+ * Whether two readings — either of which may be absent — say the same thing.
+ * @param current - What was last read, `null` while the pointer was away.
+ * @param next - What has just been read, `null` when it has left the plot.
+ * @param sameReadout - The viewer's own comparison.
+ * @returns Whether the report can be skipped.
+ */
+export function sameReading<TReadout>(
+  current: TReadout | null,
+  next: TReadout | null,
+  sameReadout: (current: TReadout, next: TReadout) => boolean,
+): boolean {
+  if (current === next) return true;
+  if (current === null || next === null) return false;
+  return sameReadout(current, next);
+}
+
+/**
+ * What to hold, given where the pointer has just been seen.
+ *
+ * The answer already held comes back whenever it still stands, so the whole
+ * chart is left alone while a hand rests on a feature — `pointermove` fires on
+ * every tremor, and several of those land on the very same user-unit position.
+ * @param current - What is held.
+ * @param next - What has just been read.
+ * @param sameReadout - The viewer's own comparison, asked only once the pointer
+ * turns out not to have moved.
+ * @returns `current` itself when it already says it, `next` otherwise.
+ */
+export function nextChartPointer<TReadout>(
+  current: ChartPointer<TReadout>,
+  next: ChartPointer<TReadout>,
+  sameReadout: (current: TReadout, next: TReadout) => boolean,
+): ChartPointer<TReadout> {
+  if (current === next) return current;
+  if (current.position === null || next.position === null) {
+    return current.position === next.position ? current : next;
+  }
+  if (
+    current.position.x !== next.position.x ||
+    current.position.y !== next.position.y
+  ) {
+    return next;
+  }
+  return sameReading(current.readout, next.readout, sameReadout)
+    ? current
+    : next;
+}
+
+/**
+ * Whether a point is over the data rather than over an axis.
+ * @param plot - Where the plot sits inside the SVG.
+ * @param point - The point to test, in user units.
+ * @returns Whether it is inside the plot, edges included.
+ */
+export function isInsidePlot(plot: PlotRect, point: ChartPoint): boolean {
+  return (
+    point.x >= plot.left &&
+    point.x <= plot.right &&
+    point.y >= plot.top &&
+    point.y <= plot.bottom
+  );
+}
+
+/** What is held while the pointer is anywhere but over the plot. */
+const POINTER_AWAY: ChartPointer<never> = { position: null, readout: null };

package/src/chart/ui/useChartSize.ts

@@ -0,0 +1,115 @@
+/**
+ * How big the box a chart was handed is, followed for as long as it is on
+ * screen.
+ *
+ * The element is measured from the `ref` rather than from an effect, so the
+ * observer is re-attached every time the element goes away and comes back —
+ * which is the whole point of doing it here. A chart living in a folded
+ * accordion panel is unmounted while the panel is shut; an observer bound once
+ * at mount would be watching an element nobody kept, so the chart returns
+ * measuring nothing, builds its scales on a plot of `MINIMUM_PLOT_SIDE`, and
+ * stays that way until the window itself happens to be resized. Measuring in
+ * the callback also means the size is known in the same commit the element
+ * appears in, so nothing is ever painted at a size that is about to change.
+ */
+
+import type { Dispatch, SetStateAction } from 'react';
+import { useCallback, useRef, useState } from 'react';
+
+import type { ChartSize } from '../core/chartGeometry.ts';
+
+/** The `ref` to put on the wrapper, and how big that wrapper is. */
+export type ChartSizeHandle<T extends Element> = [
+  ref: (element: T | null) => void,
+  size: ChartSize,
+];
+
+/**
+ * Follow the size of the element a chart is drawn in.
+ *
+ * The `ref` never changes between renders, so React attaches it once per
+ * element rather than detaching and re-attaching it — and a detach here is not
+ * free, since it is what tears the observer down.
+ * @returns The `ref`, and the size — `0 × 0` until the element is on screen,
+ * which every first render sees.
+ */
+export function useChartSize<
+  T extends Element = HTMLDivElement,
+>(): ChartSizeHandle<T> {
+  const observer = useRef<ResizeObserver | null>(null);
+  const [size, setSize] = useState<ChartSize>(NO_SIZE);
+
+  const measure = useCallback((element: T | null) => {
+    // Torn down here rather than from a cleanup returned to React: only React
+    // 19 runs one, where React 18 calls the ref with `null` instead — so
+    // detaching on `null` is what disconnects the observer under both.
+    observer.current?.disconnect();
+    observer.current = null;
+    if (element === null) return;
+
+    read(element, setSize);
+    // Absent outside a browser, where nothing is on screen to be resized.
+    if (typeof ResizeObserver === 'undefined') return;
+    observer.current = new ResizeObserver(() => {
+      read(element, setSize);
+    });
+    observer.current.observe(element);
+  }, []);
+
+  return [measure, size];
+}
+
+/**
+ * The size to hold, given what the element has just been measured at.
+ *
+ * The one already held comes back when the numbers have not moved, so a
+ * resize that changes nothing — a splitter dragged and let go where it was, a
+ * panel folded and unfolded at the same width — costs a comparison rather than
+ * a render of the whole chart, which rebuilds every scale and re-lays every
+ * label out.
+ *
+ * A measurement that is not a size is read as nothing at all: a negative width
+ * is impossible, and a `NaN` one is what an element that is not laid out gives.
+ * Either would travel into `plotRect` and out the far side as an infinity.
+ * @param current - The size held so far.
+ * @param width - What the element has just been measured at, horizontally.
+ * @param height - What it has just been measured at, vertically.
+ * @returns `current` itself when nothing moved, the new size otherwise.
+ */
+export function nextChartSize(
+  current: ChartSize,
+  width: number,
+  height: number,
+): ChartSize {
+  const nextWidth = usableSide(width);
+  const nextHeight = usableSide(height);
+  if (current.width === nextWidth && current.height === nextHeight) {
+    return current;
+  }
+  return { width: nextWidth, height: nextHeight };
+}
+
+/** What a chart is given before its element has ever been laid out. */
+const NO_SIZE: ChartSize = { width: 0, height: 0 };
+
+/**
+ * Measure an element and hold what it says.
+ * @param element - The wrapper the chart is drawn in.
+ * @param setSize - Where the measurement goes.
+ */
+function read(
+  element: Element,
+  setSize: Dispatch<SetStateAction<ChartSize>>,
+): void {
+  const { width, height } = element.getBoundingClientRect();
+  setSize((current) => nextChartSize(current, width, height));
+}
+
+/**
+ * One side of a measurement, as a size rather than as a number.
+ * @param value - What the element was measured at.
+ * @returns The side, `0` for anything that is not a length.
+ */
+function usableSide(value: number): number {
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}

package/src/chart/ui/useChartWindow.ts

@@ -0,0 +1,240 @@
+/**
+ * The window a chart is looking through, and the two scales it is read by.
+ *
+ * Three things can decide what is on screen — the fit the data asks for, the
+ * window a gesture arrived at, and a window a host imposes — and the whole of
+ * the policy that settles between them is here, away from the gestures, because
+ * it is the half that has nothing to do with a pointer. A chart put back to its
+ * fit by a toolbar button and one put back by a double click are the same event
+ * to this hook.
+ *
+ * The scales come out of the same place for a reason that shipped broken once:
+ * every gesture is measured by inverting a pixel, so a chart drawing a reversed
+ * axis while the gestures were measured through an ascending one zoomed to the
+ * mirror image of whatever was dragged over. Held here, beside the window they
+ * are built from, there is only ever one mapping to disagree with.
+ */
+
+import { useCallback, useMemo, useState } from 'react';
+
+import type { ChartDomain } from '../core/chartDomain.ts';
+import { sameChartDomain } from '../core/chartDomain.ts';
+import type { PlotRect } from '../core/chartGeometry.ts';
+import type { ChartScale } from '../core/chartScale.ts';
+import { chartScale } from '../core/chartScale.ts';
+
+/** The fit, the window a host imposes, and the box both are drawn into. */
+export interface ChartWindowOptions {
+  /**
+   * The window that shows everything currently drawn, as the viewer fits it.
+   * This is what a double click goes back to.
+   */
+  fitted: ChartDomain;
+  /**
+   * What that fit was made *to*, as one string two renders can compare.
+   *
+   * The window is put back to the fit whenever this changes and never otherwise,
+   * so it must name the data and not its extents: a spectrum switched from one
+   * unit to another, or from its profile to its sticks, moves the fitted extents
+   * by a hair, and refitting on a hair throws away the zoom somebody set.
+   */
+  fitKey: string;
+  /**
+   * What the **value axis alone** was fitted to, for a chart whose height is
+   * fitted to something that changes under a window the reader is keeping.
+   *
+   * A loading spectrum is the case it was written for. The reader zooms onto a
+   * few masses and then steps through the components, and the m/z window is
+   * where they are looking rather than a fact about the component being read —
+   * so it stays. The loading axis is fitted to the component's own scale, and
+   * cannot: drawn through the last component's window, a diffuse component is a
+   * flat line along the middle and a concentrated one is cut off at the top.
+   * @default `fitKey`, so the value axis moves only when the whole fit does
+   */
+  yFitKey?: string;
+  /** Where the plot sits inside the SVG, which the axes are laid over. */
+  plot: PlotRect;
+  /**
+   * The window a host is imposing, `null` while it imposes none.
+   *
+   * It is handed *in* rather than merely shown beside the chart's own, so that
+   * every gesture is measured against what is actually on screen. A peak table
+   * that frames a value, a handle that zooms to one: both put a window on the
+   * chart that the chart did not arrive at, and a drag worked out against the
+   * window the chart last held instead would zoom to somewhere else entirely.
+   * It is taken up when it *changes*, not held over the chart's own — see the
+   * hook itself for why that distinction is the difference between a chart that
+   * zooms and one that zooms once.
+   * @default null
+   */
+  domain?: ChartDomain | null;
+  /**
+   * Whether the horizontal axis is drawn right to left, as an infrared
+   * spectrum's wavenumbers are.
+   *
+   * It has to be said **here**, and this is the one option a viewer cannot get
+   * away with handling on its own: a chart that drew a reversed axis while the
+   * gestures were measured through an ascending one would zoom to the mirror
+   * image of whatever was dragged over. The scales are handed back for exactly
+   * that reason — draw with those and the two cannot disagree.
+   * @default false
+   */
+  reverseX?: boolean;
+}
+
+/** The window, how it maps to pixels, and the two ways it moves. */
+export interface ChartWindow {
+  /** What the chart is showing. */
+  domain: ChartDomain;
+  /** The horizontal axis, already accounting for a reversed one. */
+  xScale: ChartScale;
+  /** The vertical axis, which runs backwards because SVG counts downwards. */
+  yScale: ChartScale;
+  /** Show a window a gesture arrived at. */
+  show: (domain: ChartDomain) => void;
+  /** Put the window back to everything that is drawn. */
+  reset: () => void;
+}
+
+/**
+ * Hold the window a chart shows, and map it to the plot.
+ *
+ * The window is put back to what fits whenever the chart is handed **different
+ * data** — a spectrum loaded, one closed, the chart reflected about zero — and
+ * is otherwise left exactly where it was. That distinction is the whole of the
+ * behaviour, and `fitKey` is where it is drawn: the same spectra drawn
+ * differently is the same data, and a chart that refitted on it would throw away
+ * the window somebody had zoomed to for a change of a fraction of a percent in
+ * the extents.
+ *
+ * The value axis can be refitted on its own, by `yFitKey`, for the one chart
+ * where the two halves of the window answer to different things: a component's
+ * loadings are drawn on the component's own scale, while the masses on screen
+ * are where the reader chose to look and have nothing to do with which
+ * component is being read. Everywhere else it is the whole fit that moves, so
+ * it defaults to `fitKey` and nothing has to be said.
+ *
+ * A window a host imposes is **taken up as it changes**, and is not held over
+ * the window kept here. A host is told every window the chart arrives at and is
+ * expected to hand that same window back, so what it imposes is, in the ordinary
+ * case, the answer to the *last* gesture. Held over the top, that answer would
+ * be the answer to the next one as well — the chart would zoom once, report it,
+ * and then stand still, with every later drag and turn of the wheel worked out
+ * and thrown away.
+ *
+ * Handing back `null` where a window was is how a host asks for the fit again —
+ * the only thing it is ever told is a window, so that is the one way it has of
+ * saying it. That is what "zoom to fit" pressed on a toolbar beside the chart
+ * comes down to.
+ *
+ * New data refits the **value axis** of whatever a host is imposing, and leaves
+ * the horizontal half of it alone. A host that stores every window it is told
+ * and hands the same one back is imposing one at every moment after the first
+ * gesture, so a refit that waited for it to stop would never happen at all: a
+ * chart reflected about zero would draw its mirrored half below the foot of the
+ * plot, where the clip path swallows it. But the horizontal axis is where the
+ * reader chose to look, and by the time data arrives with a window still
+ * imposed the host has already decided the two belong together — every route in
+ * gives its own window up when what arrived does not belong in it, and there is
+ * then nothing imposed here to keep. What is left is another scan of the run
+ * being stepped through, or another pixel of the section being compared, and
+ * refitting those out of the window they are being compared in is the one thing
+ * the gesture that added them was not asking for. A host imposing a *different*
+ * window in the same render still wins outright, since it is asking for that
+ * window of the data just handed over.
+ *
+ * The imposed window is compared by value rather than by identity, so a host
+ * that rebuilds an equal window on every render neither fights the gestures nor
+ * renders forever. Both comparisons are made while rendering rather than in an
+ * effect: an effect would draw the stale window for one frame, and setting state
+ * from one is what `react-hooks/set-state-in-effect` forbids.
+ * @param options - The fit, the plot, and the window a host imposes.
+ * @returns The window, its two scales, and the two ways it is moved.
+ */
+export function useChartWindow(options: ChartWindowOptions): ChartWindow {
+  const {
+    fitted,
+    fitKey,
+    yFitKey = fitKey,
+    plot,
+    domain: imposed = null,
+    reverseX = false,
+  } = options;
+
+  // What the chart shows, and the one thing every gesture moves.
+  const [held, setHeld] = useState<ChartDomain>(imposed ?? fitted);
+
+  const [fittedFor, setFittedFor] = useState(fitKey);
+  if (fittedFor !== fitKey) {
+    setFittedFor(fitKey);
+    // The horizontal half of a window a host is still imposing survives the
+    // refit; only the value axis is refitted. A host that wanted the whole
+    // window given up has already given it up — every route in clears its own
+    // window when the data that arrived does not belong in it, and then there
+    // is nothing imposed here to keep. What is left is the case where it does
+    // belong: another scan of the run being stepped through, another pixel of
+    // the section being compared. Refitting x there throws away the very
+    // window the reader is comparing *in*, which is the whole point of the
+    // gesture that added it.
+    //
+    // The value axis is refitted all the same, and must be: a chart reflected
+    // about zero, or one a brighter trace has just joined, is drawn against a
+    // height that has genuinely changed, and keeping the old one hides the new
+    // data below the foot of the plot or off the top of it.
+    setHeld((current) =>
+      imposed === null ? fitted : { x: current.x, y: fitted.y },
+    );
+  }
+
+  const [yFittedFor, setYFittedFor] = useState(yFitKey);
+  if (yFittedFor !== yFitKey) {
+    setYFittedFor(yFitKey);
+    // Mapped over whatever the refit above may just have set, rather than over
+    // the window this render read, so that both keys changing at once is the
+    // whole fit and not the last window's x with a new height on it.
+    setHeld((current) => ({ x: current.x, y: fitted.y }));
+  }
+
+  const [imposedShown, setImposedShown] = useState(imposed);
+  if (!sameImposedDomain(imposedShown, imposed)) {
+    setImposedShown(imposed);
+    setHeld(imposed ?? fitted);
+  }
+
+  const domain = held;
+
+  // Reversed by handing the range over backwards, which is the whole of drawing
+  // an axis right to left.
+  const xScale = useMemo(
+    () =>
+      reverseX
+        ? chartScale(domain.x[0], domain.x[1], plot.right, plot.left)
+        : chartScale(domain.x[0], domain.x[1], plot.left, plot.right),
+    [domain.x, plot.left, plot.right, reverseX],
+  );
+  // Backwards, since SVG counts pixels downwards while a value counts up.
+  const yScale = useMemo(
+    () => chartScale(domain.y[0], domain.y[1], plot.bottom, plot.top),
+    [domain.y, plot.bottom, plot.top],
+  );
+
+  const reset = useCallback(() => {
+    setHeld(fitted);
+  }, [fitted]);
+
+  return { domain, xScale, yScale, show: setHeld, reset };
+}
+
+/**
+ * Whether a host is imposing the same window it was imposing before.
+ * @param current - The window it imposed last, `null` when it imposed none.
+ * @param next - The window it imposes now, `null` for none.
+ * @returns Whether both say the same thing.
+ */
+function sameImposedDomain(
+  current: ChartDomain | null,
+  next: ChartDomain | null,
+): boolean {
+  if (current === null || next === null) return current === next;
+  return sameChartDomain(current, next);
+}