react-cheminfo 0.28.0 → 0.30.0

package/src/chart/core/svgPoint.ts

@@ -0,0 +1,77 @@
+/**
+ * Turning a pointer on the screen into a point on the chart.
+ *
+ * Asked by everything that reads a gesture — the crosshair, the box zoom, the
+ * click that pins a label — so it is answered once, here, and all of them place
+ * the pointer in the same place.
+ *
+ * The SVG's own screen matrix is the only correct answer once the chart carries
+ * a `viewBox`: the element then draws in user units of its own, and a pointer
+ * 300 CSS pixels from the left edge of an 800-pixel-wide chart showing 600 user
+ * units is at 225 of them, not at 300. The matrix carries that scaling, the
+ * device pixel ratio and any transform an ancestor applies, all at once, so
+ * nothing downstream has to know that any of them happened.
+ */
+
+/** A point on the chart, in the user units its `viewBox` is written in. */
+export interface ChartPoint {
+  /** Distance from the left edge of the SVG. */
+  x: number;
+  /** Distance from its top edge. */
+  y: number;
+}
+
+/** The little of an SVG matrix a pointer position is worked out from. */
+export interface ScreenMatrix {
+  /** Horizontal scaling. */
+  a: number;
+  /** Vertical shear. */
+  b: number;
+  /** Horizontal shear. */
+  c: number;
+  /** Vertical scaling. */
+  d: number;
+  /** Horizontal translation. */
+  e: number;
+  /** Vertical translation. */
+  f: number;
+  /** The matrix that undoes this one. */
+  inverse: () => ScreenMatrix;
+}
+
+/** The little of an SVG element a pointer position is asked of. */
+export interface PointerSurface {
+  /** How the SVG's user units are laid over the screen. */
+  getScreenCTM: () => ScreenMatrix | null;
+}
+
+/**
+ * Where a pointer is, in the user units the SVG draws in.
+ *
+ * The matrix maps user units onto the screen, so it is inverted to go the other
+ * way. It is applied here rather than through a `DOMPoint` so that the
+ * arithmetic can be read — and tested — without a browser standing by.
+ *
+ * A surface that is not laid out has no matrix to give: an SVG inside a folded
+ * panel, or one whose `viewBox` has collapsed to nothing, answers `null` rather
+ * than a matrix of zeros, and the caller is then told there is no position
+ * instead of being handed an infinity that lands every gesture at the same
+ * impossible place.
+ * @param surface - The SVG, `null` before it is on screen.
+ * @param clientX - Where the pointer is on the screen, horizontally.
+ * @param clientY - Where it is vertically.
+ * @returns The point, `null` when the surface cannot place it.
+ */
+export function svgPointAt(
+  surface: PointerSurface | null,
+  clientX: number,
+  clientY: number,
+): ChartPoint | null {
+  const screen = surface?.getScreenCTM();
+  if (!screen) return null;
+  const inverse = screen.inverse();
+  const x = clientX * inverse.a + clientY * inverse.c + inverse.e;
+  const y = clientX * inverse.b + clientY * inverse.d + inverse.f;
+  if (!Number.isFinite(x) || !Number.isFinite(y)) return null;
+  return { x, y };
+}

package/src/chart/core/tracePath.ts

@@ -0,0 +1,228 @@
+/**
+ * The one string a trace becomes, and why it is only ever one.
+ *
+ * A profile scan is a few hundred thousand samples and a peak table a few
+ * thousand sticks. Drawn as an element each, the browser holds a hundred
+ * thousand nodes for a picture that is a single stroke, and every pointer move
+ * across the chart then costs a walk of all of them. Both traces are therefore
+ * one `<path>` built here, and the only thing that ever changes is its `d`.
+ *
+ * Coordinates are rounded to a hundredth of a pixel. No display resolves more
+ * than that, while the full precision of a double writes `312.40000000000003`
+ * where `312.4` was meant — six times the string for a distance nobody can see.
+ */
+
+import type { NumberArray } from 'cheminfo-types';
+
+import type { ChartScale } from './chartScale.ts';
+import { chartPixel } from './chartScale.ts';
+
+/**
+ * The path of a continuous trace: every sample joined to the next.
+ *
+ * A sample that maps to nothing finite — a `NaN` intensity a reader let
+ * through, a mass a degenerate scale sent to infinity — breaks the line in two
+ * rather than being passed over, because joining the two sound samples either
+ * side of it draws a straight run across a stretch the instrument never
+ * reported. Writing the `NaN` into the string instead would void the whole
+ * path, and the trace would then silently not be drawn at all.
+ * @param x - Where each sample was taken, ascending.
+ * @param y - What was measured there, one per sample.
+ * @param xScale - The x axis as it is currently zoomed.
+ * @param yScale - The y axis as it is currently zoomed.
+ * @returns The `d` of one path; empty when there is nothing to draw, and a bare
+ * `M` for a trace of a single sample, which is a point and not a line.
+ */
+export function profilePath(
+  x: NumberArray,
+  y: NumberArray,
+  xScale: ChartScale,
+  yScale: ChartScale,
+): string {
+  // The two scales are read out here and the multiply-add written inline, as
+  // `chartScale` asks a loop over points to: a trace is tens of thousands of
+  // samples, and a helper call per sample per axis is the one cost this file
+  // can avoid without changing what it draws.
+  const { offset: xOffset, factor: xFactor } = xScale;
+  const { offset: yOffset, factor: yFactor } = yScale;
+  const count = Math.min(x.length, y.length);
+  let path = '';
+  let drawnInRun = 0;
+  for (let index = 0; index < count; index++) {
+    const pixelX = xOffset + (x[index] as number) * xFactor;
+    const pixelY = yOffset + (y[index] as number) * yFactor;
+    if (!Number.isFinite(pixelX) || !Number.isFinite(pixelY)) {
+      drawnInRun = 0;
+      continue;
+    }
+    const point = `${roundPixel(pixelX)} ${roundPixel(pixelY)}`;
+    if (drawnInRun === 0) path += `M${point}`;
+    else if (drawnInRun === 1) path += `L${point}`;
+    else path += ` ${point}`;
+    drawnInRun++;
+  }
+  return path;
+}
+
+/**
+ * The path of a centroid: one stick per peak, standing on zero.
+ *
+ * The foot of every stick is where the intensity axis reads zero rather than
+ * the bottom of the plot, which is the same pixel until the chart is mirrored
+ * and then is not — a stick of the inverted half hangs from the rule the pair
+ * is reflected in. Nothing is clipped here: a peak taller than the window still
+ * gets its full stick, and the clip path over the data band is what stops it at
+ * the edge, so a zoom into the baseline shows the tall peak leaving the top
+ * rather than a gap where it stood.
+ * @param x - Where each peak sits, ascending.
+ * @param y - How tall each one is, one per peak.
+ * @param xScale - The x axis as it is currently zoomed.
+ * @param yScale - The y axis as it is currently zoomed, which the foot of the
+ * sticks is read off.
+ * @returns The `d` of one path, empty when there is nothing to draw.
+ */
+export function stickPath(
+  x: NumberArray,
+  y: NumberArray,
+  xScale: ChartScale,
+  yScale: ChartScale,
+): string {
+  const count = Math.min(x.length, y.length);
+  const foot = chartPixel(yScale, 0);
+  if (!Number.isFinite(foot)) return '';
+  const baseline = roundPixel(foot);
+  // The two scales are read out here and the multiply-add written inline, as
+  // `chartScale` asks a loop over points to: a trace is tens of thousands of
+  // samples, and a helper call per sample per axis is the one cost this file
+  // can avoid without changing what it draws.
+  const { offset: xOffset, factor: xFactor } = xScale;
+  const { offset: yOffset, factor: yFactor } = yScale;
+  let path = '';
+  for (let index = 0; index < count; index++) {
+    const pixelX = xOffset + (x[index] as number) * xFactor;
+    const pixelY = yOffset + (y[index] as number) * yFactor;
+    if (!Number.isFinite(pixelX) || !Number.isFinite(pixelY)) continue;
+    path += `M${roundPixel(pixelX)} ${baseline}V${roundPixel(pixelY)}`;
+  }
+  return path;
+}
+
+/** What an area is closed at, when the ground it stands on is not zero. */
+export interface AreaPathOptions {
+  /**
+   * The value the area is closed down onto, in the units of the y axis.
+   *
+   * A chromatographic baseline is neither at zero nor horizontal — a gradient
+   * run drifts a few thousand counts between the first peak and the last — so
+   * shading a peak down to the axis shades the column of baseline under it as
+   * well, which at a weak peak is most of what the eye then reads as the peak.
+   * Given the value the integration was corrected against, the shading and the
+   * number in the table are about the same region.
+   * @default 0
+   */
+  baseline?: number;
+}
+
+/**
+ * The path of the region under a trace: its top edge, closed onto a baseline.
+ *
+ * `profilePath` draws where a trace went and stops there, so nothing built on
+ * it can shade a region — and an integrated chromatographic peak, a UV band
+ * and an NMR integral are all that same picture, a stretch of one trace filled
+ * in to say how much of it was counted. The top edge is written exactly as
+ * `profilePath` writes it, so an area drawn under a trace lies along it to the
+ * hundredth of a pixel rather than a rounding apart from it.
+ *
+ * Each unbroken run of samples is closed on its own: down to the baseline
+ * where it ended, back along the baseline to where it began, and shut. A run
+ * of one sample encloses nothing and is left out altogether, which is what
+ * stops a break in the data from shading a spike of zero width.
+ *
+ * Nothing is clipped here, exactly as in `profilePath` and `stickPath` — a
+ * peak taller than the window keeps its whole area and the clip path over the
+ * data band is what stops it at the edge.
+ * @param x - Where each sample was taken, ascending.
+ * @param y - What was measured there, one per sample.
+ * @param xScale - The x axis as it is currently zoomed.
+ * @param yScale - The y axis as it is currently zoomed, which the baseline is
+ * read off.
+ * @param options - Where the ground under the area is.
+ * @returns The `d` of one path, holding one closed shape per unbroken run;
+ * empty when there is nothing wide enough to enclose anything.
+ */
+export function areaPath(
+  x: NumberArray,
+  y: NumberArray,
+  xScale: ChartScale,
+  yScale: ChartScale,
+  options: AreaPathOptions = {},
+): string {
+  const { baseline = 0 } = options;
+  const ground = chartPixel(yScale, baseline);
+  if (!Number.isFinite(ground)) return '';
+  const foot = roundPixel(ground);
+  const count = Math.min(x.length, y.length);
+  // The two scales are read out here and the multiply-add written inline, as
+  // `chartScale` asks a loop over points to: a trace is tens of thousands of
+  // samples, and a helper call per sample per axis is the one cost this file
+  // can avoid without changing what it draws.
+  const { offset: xOffset, factor: xFactor } = xScale;
+  const { offset: yOffset, factor: yFactor } = yScale;
+  let path = '';
+  let edge = '';
+  let drawnInRun = 0;
+  let runStart = 0;
+  for (let index = 0; index < count; index++) {
+    const pixelX = xOffset + (x[index] as number) * xFactor;
+    const pixelY = yOffset + (y[index] as number) * yFactor;
+    if (!Number.isFinite(pixelX) || !Number.isFinite(pixelY)) {
+      path += closedRun(edge, drawnInRun, runStart, foot);
+      edge = '';
+      drawnInRun = 0;
+      continue;
+    }
+    const left = roundPixel(pixelX);
+    const point = `${left} ${roundPixel(pixelY)}`;
+    if (drawnInRun === 0) {
+      edge = `M${point}`;
+      runStart = left;
+    } else if (drawnInRun === 1) {
+      edge += `L${point}`;
+    } else {
+      edge += ` ${point}`;
+    }
+    drawnInRun++;
+  }
+  return path + closedRun(edge, drawnInRun, runStart, foot);
+}
+
+/**
+ * Shut one run of samples down onto the baseline.
+ * @param edge - The top edge of the run, as `profilePath` would have written it.
+ * @param drawnInRun - How many samples that edge was drawn from.
+ * @param runStart - Where the run began, in pixels.
+ * @param foot - Where the baseline falls, in pixels.
+ * @returns The closed shape, empty for a run of fewer than two samples, which
+ * has no width and so encloses nothing.
+ */
+function closedRun(
+  edge: string,
+  drawnInRun: number,
+  runStart: number,
+  foot: number,
+): string {
+  if (drawnInRun < 2) return '';
+  return `${edge}V${foot}H${runStart}Z`;
+}
+
+/** How many parts of a pixel a coordinate is written to. */
+const PIXEL_PRECISION = 100;
+
+/**
+ * A coordinate as the path writes it.
+ * @param value - Where the point falls, in pixels.
+ * @returns The same place, to a hundredth of a pixel.
+ */
+function roundPixel(value: number): number {
+  return Math.round(value * PIXEL_PRECISION) / PIXEL_PRECISION;
+}

package/src/chart/core/trackerReadout.ts

@@ -0,0 +1,78 @@
+/**
+ * Where the crosshair writes what the axes say under it.
+ *
+ * The readout is the one thing on the chart that must never be clipped: it is
+ * what the pointer was put there to read, and the places it is most often put
+ * are exactly the awkward ones — on the tallest peak, hard against the top of
+ * the plot, or out at the far right where a label written rightwards runs off
+ * the edge. So the side it is written on and the line it starts on are both
+ * decided from the room there is, and neither is a fixed offset.
+ */
+
+import type { PlotRect } from './chartGeometry.ts';
+import { CHART_FONT, PEAK_LABEL } from './chartTheme.ts';
+import type { ChartPoint } from './svgPoint.ts';
+
+/** The clear space between the crosshair and what is written beside it. */
+export const READOUT_GAP = 6;
+
+/**
+ * The room the readout claims, in pixels.
+ *
+ * A value at a deep zoom is `1234.5678` and the one under it is shorter, so this
+ * is the width of the longest line either can be — measured from the font rather
+ * than from the text, because the text is not on screen yet when the side it goes
+ * on has to be chosen.
+ */
+export const READOUT_WIDTH = 88;
+
+/** How many lines the readout is written on: one for each axis. */
+export const READOUT_LINES = 2;
+
+/** Where the readout is written, and which way it runs from there. */
+export interface ReadoutPlacement {
+  /** The edge the lines are anchored on. */
+  x: number;
+  /** The baseline of the first line. */
+  y: number;
+  /** Which way the text runs from `x`. */
+  anchor: 'start' | 'end';
+}
+
+/**
+ * Work out where the readout beside the pointer goes.
+ *
+ * It is written to the right of the crosshair and above the pointer, which is
+ * where a hand holding a mouse is not covering it, and flips to the left as soon
+ * as it would otherwise cross the right edge of the plot. Flipping rather than
+ * sliding: a readout pinned to the edge would drift away from the crosshair it
+ * belongs to as the pointer went further right, and the pair would stop reading
+ * as one thing.
+ *
+ * Both bounds are honoured rather than only the near one, so the last line never
+ * runs off the bottom of a short plot. In a plot too short to hold every line
+ * the top edge wins: the first line is the one worth keeping, because every
+ * viewer writes what its horizontal axis reads there first.
+ * @param point - Where the pointer is, in user units.
+ * @param plot - Where the plot sits inside the SVG.
+ * @param lines - How many lines are written. Defaults to `READOUT_LINES`.
+ * @returns The anchor, the first baseline, and which way the text runs.
+ */
+export function readoutPlacement(
+  point: ChartPoint,
+  plot: PlotRect,
+  lines = READOUT_LINES,
+): ReadoutPlacement {
+  const runsRight = point.x + READOUT_GAP + READOUT_WIDTH <= plot.right;
+  const x = runsRight ? point.x + READOUT_GAP : point.x - READOUT_GAP;
+
+  const written = Math.max(1, lines);
+  const highest = plot.top + CHART_FONT.readout;
+  const lowest = plot.bottom - (written - 1) * PEAK_LABEL.lineHeight;
+  const y = Math.min(
+    Math.max(point.y - READOUT_GAP, highest),
+    Math.max(highest, lowest),
+  );
+
+  return { x, y, anchor: runsRight ? 'start' : 'end' };
+}

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;
+}