react-cheminfo 0.27.0 → 0.29.0

package/src/chart/core/viewTransform.ts

@@ -0,0 +1,287 @@
+/**
+ * How much of a drawing surface is shown, and where.
+ *
+ * Everything here is arithmetic on a `viewBox`: zooming narrows the window and
+ * panning slides it, so what is inside is re-rendered at the new scale rather
+ * than magnified as pixels. None of it knows what is being drawn — it is the
+ * pan-and-zoom half of a canvas, and it is shared because a glycan drawing and
+ * an ion image ask the same questions of it and would otherwise answer them
+ * twice.
+ *
+ * What they do not share is how a surface is fitted before it is touched, which
+ * is why `baseViewBox` takes `maximumScale`: a glycan is centred at its own
+ * size up to a readable maximum, while an image is fitted to its frame.
+ */
+export interface ViewState {
+  /** How far in, `1` being the base view. */
+  zoom: number;
+  /** Left edge of the window, from the left edge of the base view. */
+  panX: number;
+  /** Top edge of the window, from the top edge of the base view. */
+  panY: number;
+}
+
+/** A rectangle of the drawing, shaped the way the `viewBox` wants it. */
+export interface ViewBox {
+  x: number;
+  y: number;
+  width: number;
+  height: number;
+}
+
+/** Closest and furthest the canvas will go. */
+export const MINIMUM_ZOOM = 0.25;
+export const MAXIMUM_ZOOM = 8;
+
+/**
+ * Biggest a drawing unit is ever drawn at, in pixels, unless a caller says
+ * otherwise.
+ *
+ * Chosen against the glycan canvas, where a symbol is 34 units across and a
+ * bond 60 long, so a drawing at this scale reads about the size it does in a
+ * paper — which is as big as it is worth drawing. Without the cap a
+ * disaccharide on a wide screen is blown up until three residues fill a metre
+ * of pixels. A surface with its own idea of how big is big enough passes its
+ * own maximum instead.
+ */
+export const MAXIMUM_CONTENT_SCALE = 1.5;
+
+/** The base view, seen as it comes: no zoom, no pan. */
+export const INITIAL_VIEW: ViewState = { zoom: 1, panX: 0, panY: 0 };
+
+/**
+ * What the canvas shows before it is zoomed or panned.
+ *
+ * A drawing too big for the canvas is fitted to it, as anything drawn to be
+ * looked at whole must be. A drawing smaller than that is *not* stretched to
+ * fill it: it is drawn at its own size, up to `maximumScale`, in the middle of
+ * a window opened around it — so a disaccharide reads like a disaccharide
+ * however wide the screen it is on, and the empty canvas around it is still
+ * canvas, there to be clicked and drawn on.
+ * @param content - Size of the whole drawing, in canvas units.
+ * @param content.width - How wide the drawing is.
+ * @param content.height - How tall the drawing is.
+ * @param viewport - Size of the canvas on screen, in pixels.
+ * @param viewport.width - How wide the canvas is.
+ * @param viewport.height - How tall the canvas is.
+ * @param maximumScale - Biggest a canvas unit may be drawn, in pixels.
+ * @returns The rectangle of the drawing seen at zoom `1`.
+ */
+export function baseViewBox(
+  content: { width: number; height: number },
+  viewport: { width: number; height: number },
+  maximumScale = MAXIMUM_CONTENT_SCALE,
+): ViewBox {
+  // Before the canvas has been measured there is nothing to fit the drawing
+  // to; showing it whole is what the `viewBox` does on its own anyway.
+  if (
+    content.width <= 0 ||
+    content.height <= 0 ||
+    viewport.width <= 0 ||
+    viewport.height <= 0
+  ) {
+    return { x: 0, y: 0, width: content.width, height: content.height };
+  }
+
+  const fitted = Math.min(
+    viewport.width / content.width,
+    viewport.height / content.height,
+  );
+  const scale = Math.min(fitted, maximumScale);
+  const width = viewport.width / scale;
+  const height = viewport.height / scale;
+
+  return {
+    x: (content.width - width) / 2,
+    y: (content.height - height) / 2,
+    width,
+    height,
+  };
+}
+
+/**
+ * How far in and out a particular surface may go.
+ *
+ * Carried as an argument rather than fixed, because the two surfaces that use
+ * this disagree about it and both are right: a drawing may be zoomed out below
+ * its fitted size to see where it sits on the canvas, while an ion image has
+ * nothing outside itself to see — zooming out past the fit would only add
+ * emptiness — so its floor is the fit and its ceiling is far higher, since a
+ * twenty-micrometre pixel is worth magnifying.
+ */
+export interface ZoomBounds {
+  /**
+   * Furthest out.
+   * @default MINIMUM_ZOOM
+   */
+  minimum?: number;
+  /**
+   * Furthest in.
+   * @default MAXIMUM_ZOOM
+   */
+  maximum?: number;
+}
+
+/**
+ * The magnification a window factor asks for.
+ *
+ * There are two ways to say "zoom" and this package uses both, so the
+ * conversion is named rather than written as a stray reciprocal. A chart zooms
+ * by resizing the **window** it shows — `chartWheelFactor` returns that, and a
+ * factor above one means a wider window and therefore less magnification. A
+ * drawing surface zooms by scaling the picture, so `zoomAbout` takes a
+ * **magnification**, where above one means larger.
+ *
+ * Feeding one to the other reverses the wheel: the gesture still works, it
+ * simply does the opposite of what the hand meant, which is the kind of defect
+ * that survives review because nothing throws and the picture still moves.
+ * @param windowFactor - How much the window is being multiplied by.
+ * @returns The magnification that corresponds to it.
+ */
+export function magnificationOf(windowFactor: number): number {
+  if (!Number.isFinite(windowFactor) || windowFactor === 0) return 1;
+  return 1 / windowFactor;
+}
+
+/**
+ * Hold a zoom inside what the surface allows.
+ * @param zoom - The wanted zoom.
+ * @param bounds - How far in and out this surface goes.
+ * @returns The zoom it will actually use.
+ */
+export function clampZoom(zoom: number, bounds: ZoomBounds = {}): number {
+  const { minimum = MINIMUM_ZOOM, maximum = MAXIMUM_ZOOM } = bounds;
+  // A zoom that is not a number at all is a lost view rather than a small one,
+  // so it comes back to the base rather than to the floor — held inside the
+  // bounds all the same, since a surface whose floor is the fit has no base
+  // below it.
+  const wanted = Number.isFinite(zoom) ? zoom : 1;
+  return Math.min(maximum, Math.max(minimum, wanted));
+}
+
+/**
+ * Zoom while keeping one point of the drawing under the pointer.
+ *
+ * Without the anchor the drawing would drift away from the cursor as it grows,
+ * which is what makes a wheel zoom feel wrong.
+ * @param view - Where the canvas is now.
+ * @param base - What the canvas shows at zoom `1`.
+ * @param factor - How much to multiply the zoom by.
+ * @param anchor - The surface point to keep still, usually the pointer.
+ * @param anchor.x - Its horizontal position, in drawing units.
+ * @param anchor.y - Its vertical position, in drawing units.
+ * @param bounds - How far in and out this surface goes.
+ * @returns Where the canvas goes.
+ */
+export function zoomAbout(
+  view: ViewState,
+  base: ViewBox,
+  factor: number,
+  anchor: { x: number; y: number },
+  bounds: ZoomBounds = {},
+): ViewState {
+  const zoom = clampZoom(view.zoom * factor, bounds);
+  if (zoom === view.zoom) return view;
+
+  const beforeWidth = base.width / view.zoom;
+  const beforeHeight = base.height / view.zoom;
+  const afterWidth = base.width / zoom;
+  const afterHeight = base.height / zoom;
+
+  // The pan is measured from the base view, so the anchor is read from there
+  // too: a window written that way keeps its place over the drawing when the
+  // canvas is resized and the base view moves under it.
+  const anchorX = anchor.x - base.x;
+  const anchorY = anchor.y - base.y;
+
+  const fractionX = beforeWidth === 0 ? 0 : (anchorX - view.panX) / beforeWidth;
+  const fractionY =
+    beforeHeight === 0 ? 0 : (anchorY - view.panY) / beforeHeight;
+
+  return {
+    zoom,
+    panX: anchorX - fractionX * afterWidth,
+    panY: anchorY - fractionY * afterHeight,
+  };
+}
+
+/**
+ * Slide the window, in canvas units.
+ * @param view - Where the canvas is now.
+ * @param deltaX - How far to move it horizontally.
+ * @param deltaY - How far to move it vertically.
+ * @returns Where the canvas goes.
+ */
+export function panBy(
+  view: ViewState,
+  deltaX: number,
+  deltaY: number,
+): ViewState {
+  return {
+    zoom: view.zoom,
+    panX: view.panX - deltaX,
+    panY: view.panY - deltaY,
+  };
+}
+
+/**
+ * Set the zoom about the middle of what is on screen, which is what the
+ * toolbar buttons want — they have no pointer to zoom around.
+ * @param view - Where the canvas is now.
+ * @param base - What the canvas shows at zoom `1`.
+ * @param zoom - The wanted zoom.
+ * @param bounds - How far in and out this surface goes.
+ * @returns Where the canvas goes.
+ */
+export function zoomToAboutCentre(
+  view: ViewState,
+  base: ViewBox,
+  zoom: number,
+  bounds: ZoomBounds = {},
+): ViewState {
+  const centre = {
+    x: base.x + view.panX + base.width / view.zoom / 2,
+    y: base.y + view.panY + base.height / view.zoom / 2,
+  };
+  return zoomAbout(
+    view,
+    base,
+    clampZoom(zoom, bounds) / view.zoom,
+    centre,
+    bounds,
+  );
+}
+
+/**
+ * The rectangle of the drawing the canvas is showing.
+ * @param view - Where the canvas is.
+ * @param base - What the canvas shows at zoom `1`.
+ * @returns The rectangle.
+ */
+export function viewBoxOf(view: ViewState, base: ViewBox): ViewBox {
+  return {
+    x: base.x + view.panX,
+    y: base.y + view.panY,
+    width: base.width / view.zoom,
+    height: base.height / view.zoom,
+  };
+}
+
+/**
+ * The rectangle, written the way the `viewBox` attribute wants it.
+ * @param box - The rectangle.
+ * @returns The attribute.
+ */
+export function viewBoxAttribute(box: ViewBox): string {
+  return `${round(box.x)} ${round(box.y)} ${round(box.width)} ${round(box.height)}`;
+}
+
+/**
+ * A coordinate, short enough not to bloat an attribute rewritten on every
+ * frame of a drag.
+ * @param value - The coordinate.
+ * @returns It, to two decimals.
+ */
+function round(value: number): number {
+  return Math.round(value * 100) / 100;
+}

package/src/chart/core/zoomDomain.ts

@@ -0,0 +1,235 @@
+/**
+ * The window a gesture asks for, where each viewer's own fitting holds the one
+ * the data asks for.
+ *
+ * Nothing here touches React or the DOM: a drag arrives as two corners in the
+ * user units of the SVG, a wheel as a factor, and each leaves as a window — so
+ * what a gesture does to a chart can be read, and tested, without one being on
+ * screen.
+ */
+
+import { clamp } from '../../format/core/clamp.ts';
+
+import type { ChartDomain, ZoomRules } from './chartDomain.ts';
+import { DEFAULT_Y_AXIS_RULES } from './chartDomain.ts';
+import type { PlotRect } from './chartGeometry.ts';
+import type { ChartScale } from './chartScale.ts';
+import { chartPixel, chartValue } from './chartScale.ts';
+
+/**
+ * How far the pointer has to travel before a press counts as a gesture rather
+ * than as a click, in user units of the SVG.
+ *
+ * Across the x axis it is what decides whether there is a window at all: below
+ * this the gesture is a click that happened to wobble — which is most clicks
+ * made on a trackpad — and zooming to it would leave a window a fraction of a
+ * data unit wide, from which the only way back is the double click nobody knows
+ * about yet. `chartGestures.ts` asks the same question of the vertical travel
+ * before it calls a release a click, since a drag of one pixel across and three
+ * hundred down went somewhere.
+ */
+export const MINIMUM_DRAG = 4;
+
+/** The two corners of a drag, in the user units of the SVG. */
+export interface DragBox {
+  /** Where the press landed, horizontally. */
+  fromX: number;
+  /** Where it landed vertically. */
+  fromY: number;
+  /** Where the pointer is now, horizontally. */
+  toX: number;
+  /** Where it is vertically. */
+  toY: number;
+}
+
+/** The drag as it is being made, for the preview rectangle to be drawn from. */
+export interface ZoomSelection extends DragBox {
+  /**
+   * Whether letting go here would take the y axis with it, which is what the
+   * rectangle changes shape to say.
+   */
+  zoomsYAxis: boolean;
+}
+
+/**
+ * The drag as the preview rectangle needs it.
+ *
+ * The answer the rectangle changes shape on is worked out once, here, rather
+ * than by the rectangle itself — so what the preview promises and what letting
+ * go actually does are the same test rather than two that have to agree.
+ *
+ * A `select` drag is therefore always a band, however far past the baseline it
+ * strays: its answer is two numbers on one axis, so a preview that grew into a
+ * rectangle would promise a height nobody is ever told about.
+ * @param drag - The drag being made, `null` when none is.
+ * @param yScale - The y axis as it is currently zoomed.
+ * @param rules - How the y axis behaves and what a drag means, defaulting to a
+ * stick spectrum read by dragging its horizontal axis.
+ * @returns The selection to draw, `null` when there is no drag.
+ */
+export function zoomSelection(
+  drag: DragBox | null,
+  yScale: ChartScale,
+  rules: ZoomRules = {},
+): ZoomSelection | null {
+  if (drag === null) return null;
+  const {
+    baseline = DEFAULT_Y_AXIS_RULES.baseline,
+    pointsDown = DEFAULT_Y_AXIS_RULES.pointsDown,
+    drag: mode = 'xAxis',
+  } = rules;
+  return {
+    fromX: drag.fromX,
+    fromY: drag.fromY,
+    toX: drag.toX,
+    toY: drag.toY,
+    // The box tool takes the height always, so the preview is a rectangle from
+    // the first pixel of the gesture rather than a full-height band that
+    // suddenly becomes one; a select drag never takes it at all.
+    zoomsYAxis:
+      mode === 'box' ||
+      (mode !== 'select' &&
+        releasedBeyondBaseline(drag.toY, yScale, baseline, pointsDown)),
+  };
+}
+
+/**
+ * Whether a drag let go here asks for the y axis as well.
+ *
+ * The baseline, not the bottom of the plot: on a mirrored chart zero runs across
+ * the middle, so a drag that dips into the reflected half has crossed it, and on
+ * an ordinary chart the same test means the pointer went below the axis and out
+ * into the margin. One rule, two gestures that both read as "and take the height
+ * with you".
+ *
+ * **Which way "past" points depends on which side of the baseline the data is
+ * on**, which is what `pointsDown` says. Features that stand up out of a
+ * baseline at the foot of the plot — mass sticks, absorbance bands — are passed
+ * by going below it. Percent transmittance hangs down from 100, which sits near
+ * the top of the plot, so there the gesture is a drag released *above* the
+ * baseline; asking the other question would answer yes almost everywhere in the
+ * plot and make every ordinary drag take the value axis with it.
+ * @param pointerY - Where the pointer is, in user units of the SVG.
+ * @param yScale - The y axis as it is currently zoomed.
+ * @param baseline - The value the gesture is judged against. Defaults to `0`.
+ * @param pointsDown - Whether the data hangs below the baseline. Defaults to
+ * `false`.
+ * @returns Whether the y axis comes along.
+ */
+export function releasedBeyondBaseline(
+  pointerY: number,
+  yScale: ChartScale,
+  baseline = DEFAULT_Y_AXIS_RULES.baseline,
+  pointsDown = DEFAULT_Y_AXIS_RULES.pointsDown,
+): boolean {
+  const atBaseline = chartPixel(yScale, baseline);
+  // SVG counts pixels downwards, so "above the baseline" is the smaller pixel.
+  return pointsDown ? pointerY < atBaseline : pointerY > atBaseline;
+}
+
+/**
+ * The window a drag asks for, or `null` when it asks for nothing.
+ *
+ * Both corners are pulled back inside the plot before they are read, so a drag
+ * that ran out over the axis labels — which is how the y axis is asked for in
+ * the first place — zooms to the edge of the data rather than to whatever lies
+ * under the margin.
+ *
+ * Whether the baseline is kept in the window is the one thing that differs
+ * between viewers, and `YAxisRules` is where they say so. A stick spectrum keeps
+ * it: sticks are drawn from it, and a window starting at a tenth of the base
+ * peak would cut every one of them off at the ankles. A continuous trace does
+ * not: a band dragged out between two absorbances is asked about between those
+ * two absorbances.
+ * @param current - The window in force, kept on the axis that is not asked for.
+ * @param drag - The two corners, in user units of the SVG.
+ * @param plot - Where the plot sits inside the SVG.
+ * @param xScale - The x axis as it is currently zoomed.
+ * @param yScale - The y axis as it is currently zoomed.
+ * @param rules - How the y axis behaves and what a drag means, defaulting to a
+ * stick spectrum read by dragging its horizontal axis.
+ * @returns The window to show, `null` when the drag was too short to be one.
+ */
+export function zoomedDomain(
+  current: ChartDomain,
+  drag: DragBox,
+  plot: PlotRect,
+  xScale: ChartScale,
+  yScale: ChartScale,
+  rules: ZoomRules = {},
+): ChartDomain | null {
+  const {
+    baseline = DEFAULT_Y_AXIS_RULES.baseline,
+    keepBaseline = DEFAULT_Y_AXIS_RULES.keepBaseline,
+    pointsDown = DEFAULT_Y_AXIS_RULES.pointsDown,
+    drag: mode = 'xAxis',
+  } = rules;
+  const fromX = clamp(drag.fromX, plot.left, plot.right);
+  const toX = clamp(drag.toX, plot.left, plot.right);
+  if (Math.abs(toX - fromX) < MINIMUM_DRAG) return null;
+  // Sorted after inverting, not before: an axis drawn right to left — an
+  // infrared spectrum runs from 4000 down to 400 — maps the leftmost pixel to
+  // the *highest* value, so taking the left edge as the lower bound would hand
+  // back a window whose ends are the wrong way round, and every scale built
+  // from it would draw the trace mirrored.
+  const firstX = chartValue(xScale, fromX);
+  const secondX = chartValue(xScale, toX);
+  const x: [number, number] = [
+    Math.min(firstX, secondX),
+    Math.max(firstX, secondX),
+  ];
+  // The box tool is asked for the rectangle it was given, wherever it was let
+  // go; the reading gesture takes the height only when it crossed the baseline.
+  if (
+    mode !== 'box' &&
+    !releasedBeyondBaseline(drag.toY, yScale, baseline, pointsDown)
+  ) {
+    return { x, y: current.y };
+  }
+
+  const fromY = chartValue(yScale, clamp(drag.fromY, plot.top, plot.bottom));
+  const toY = chartValue(yScale, clamp(drag.toY, plot.top, plot.bottom));
+  // Both ends, so a baseline the data runs *down* from — 100 percent
+  // transmittance — is kept as surely as one it stands on. The box tool holds no
+  // baseline at all: a rectangle dragged round a feature is a promise about
+  // exactly that rectangle, and a viewer whose axis rules keep its baseline
+  // would otherwise see the tool quietly return a taller window than the one
+  // drawn.
+  const holdBaseline = keepBaseline && mode !== 'box';
+  const bottom = holdBaseline
+    ? Math.min(baseline, fromY, toY)
+    : Math.min(fromY, toY);
+  const top = holdBaseline
+    ? Math.max(baseline, fromY, toY)
+    : Math.max(fromY, toY);
+  return top > bottom ? { x, y: [bottom, top] } : { x, y: current.y };
+}
+
+/**
+ * The window one turn of the wheel asks for.
+ *
+ * Both bounds are scaled about the baseline rather than about the middle of the
+ * window. On a stick spectrum that keeps the foot the sticks are drawn from on
+ * the axis, and keeps a mirrored chart symmetric — scaling about the middle
+ * would send the two halves apart at different rates, so a peak of one height
+ * would mean two different intensities. On an axis running downwards from a
+ * baseline, such as percent transmittance from 100, it is what stretches the
+ * bands instead of walking the whole trace off the plot.
+ * @param current - The window in force.
+ * @param factor - What one wheel event is worth, above one to zoom out.
+ * @param baseline - The value to scale about. Defaults to `0`.
+ * @returns The window to show, `current` itself when the factor is not one a
+ * window survives.
+ */
+export function scaledYAxis(
+  current: ChartDomain,
+  factor: number,
+  baseline = DEFAULT_Y_AXIS_RULES.baseline,
+): ChartDomain {
+  if (!Number.isFinite(factor) || factor <= 0) return current;
+  const y: [number, number] = [
+    baseline + (current.y[0] - baseline) * factor,
+    baseline + (current.y[1] - baseline) * factor,
+  ];
+  return y[1] > y[0] ? { x: current.x, y } : current;
+}