react-cheminfo 0.27.0 → 0.29.0

package/src/chart/core/chartDomain.ts

@@ -0,0 +1,185 @@
+/**
+ * The window a chart is showing, which is the one thing every viewer built on
+ * this package holds in common.
+ *
+ * Two numbers on each axis and nothing else — no units, no labels, no notion of
+ * what is being measured. That absence is the point: a mass spectrum reads its
+ * x axis as m/z and an infrared spectrum reads the same two numbers as
+ * wavenumbers, so a window that named either would need converting at every
+ * boundary, and a zoom gesture would have to be written twice to do the same
+ * arithmetic.
+ *
+ * The y axis is called nothing more specific than y for the same reason. It
+ * carries intensity in one viewer, absorbance or percent transmittance in
+ * another, and the arithmetic that maps it to pixels cares only that it is a
+ * range of numbers.
+ */
+
+/** The window a chart is showing, in data units. */
+export interface ChartDomain {
+  /** `[min, max]` on the horizontal axis. */
+  x: [number, number];
+  /** `[min, max]` on the vertical axis, the lower bound negative in mirror mode. */
+  y: [number, number];
+}
+
+/**
+ * How the vertical axis behaves under a gesture, where the two viewers differ.
+ *
+ * A mass spectrum is drawn as sticks standing on zero, so zero has to stay in
+ * the window however it is zoomed — a window starting at a tenth of the base
+ * peak cuts every stick off at the ankles. A continuous trace has no feet: an
+ * infrared band dragged out at 20 to 60 percent transmittance is asked about at
+ * 20 to 60 percent, and forcing 100 into the window would undo the zoom that was
+ * just asked for.
+ *
+ * The baseline is also what the wheel scales about, which is not always zero:
+ * percent transmittance runs *down* from 100, and scaling it about zero would
+ * walk the whole trace off the top of the plot instead of stretching it.
+ */
+export interface YAxisRules {
+  /**
+   * The value the wheel scales about, and the line a drag is judged against.
+   * @default 0
+   */
+  baseline?: number;
+  /**
+   * Whether the baseline must stay inside the window a drag asks for — true for
+   * a stick spectrum standing on it, false for a continuous trace.
+   * @default true
+   */
+  keepBaseline?: boolean;
+  /**
+   * Whether the features hang **down** from the baseline rather than standing up
+   * out of it.
+   *
+   * This is which side of the baseline the data is on, and it decides which way
+   * "released past the baseline" points. A mass peak and an absorbance band both
+   * stand up out of a baseline at the foot of the plot, so the gesture is a drag
+   * released *below* it. Percent transmittance hangs down from 100, which sits
+   * near the *top* — so there the gesture is a drag released above it, and asking
+   * the mass question instead would make almost every drag in the plot take the
+   * value axis with it.
+   * @default false
+   */
+  pointsDown?: boolean;
+}
+
+/** What the rules come to when a viewer states none of them. */
+export const DEFAULT_Y_AXIS_RULES: Required<YAxisRules> = {
+  baseline: 0,
+  keepBaseline: true,
+  pointsDown: false,
+};
+
+/**
+ * What a drag across the plot zooms to.
+ *
+ * `xAxis` is the reading gesture and the default: the question a chemist asks of
+ * a spectrum is nearly always "what is between 1650 and 1750", never "what is
+ * between forty and sixty percent", so a drag narrows the horizontal axis and
+ * leaves the height alone unless it is released past the baseline.
+ *
+ * `box` is the tool: while it is chosen, the rectangle dragged out is the window,
+ * both axes at once. It is a mode rather than a modifier because it is used in
+ * runs — a baseline being examined is examined several times over — and a
+ * modifier held down through each of them is a worse gesture than a tool pressed
+ * once.
+ *
+ * The two are named apart from the whole of `DragMode` so that a chart offering
+ * nothing but zoom tools can say so in its own signature — which is what stops
+ * `select`, the one drag that moves no axis, from reaching a chart with no
+ * handler for it.
+ */
+export type ZoomDragMode = 'xAxis' | 'box';
+
+/**
+ * What a drag across the plot asks for.
+ *
+ * `select` is the third and it is not a zoom at all: the rectangle swept out is
+ * handed back as a range and the window is left exactly where it was. A
+ * chromatographic peak is integrated between two retention times a chemist
+ * chose, and choosing them by dragging over them is the gesture — so the answer
+ * to it is two numbers on the horizontal axis rather than a new window, and a
+ * chart that zoomed to them as well would take the neighbouring peaks off the
+ * screen the moment the boundaries were set.
+ *
+ * It is a mode rather than a modifier for the reason `ZoomDragMode` already
+ * gives — integration is done in runs — and it is kept out of `ZoomDragMode` so
+ * that a chart offering only zoom tools, which is what the infrared toolbar
+ * hands to its `zoomGestures`, cannot be handed it by a widening nobody noticed.
+ * Handed one, that chart would sweep out a rectangle and then do nothing at all.
+ */
+export type DragMode = ZoomDragMode | 'select';
+
+/** How the y axis behaves, and what a drag is taken to mean. */
+export interface ZoomRules extends YAxisRules {
+  /**
+   * What a drag asks for.
+   * @default 'xAxis'
+   */
+  drag?: DragMode;
+}
+
+/**
+ * Which gestures a chart answers, for a viewer that offers fewer than all of
+ * them.
+ *
+ * A gesture is worth having only where the axis it moves has somewhere to go,
+ * and that is a property of what is being measured rather than of the chart. An
+ * axis running between two ends the data fills — percent transmittance from 0 to
+ * 100 — has nothing for the wheel to scale: stretching it about its baseline
+ * pushes the trace off the plot and leaves an axis that no longer reads as
+ * percent. An axis open at one end — intensity, absorbance — has weak features
+ * lying against the baseline, and bringing those up is what the wheel is for.
+ *
+ * Saying it here, once, is what keeps a viewer from answering a gesture in one
+ * mode and quietly ignoring it in another: the whole set travels as one object
+ * from whatever knows the measurement into `useChartZoom`.
+ */
+export interface ZoomGestures {
+  /**
+   * What a drag across the plot asks for.
+   * @default 'xAxis'
+   */
+  drag?: DragMode;
+  /**
+   * Whether the wheel scales the value axis about its baseline.
+   *
+   * Turned off, the wheel is left entirely alone — the page scrolls under the
+   * pointer as it does anywhere else, which is what a reader expects of a chart
+   * that does not answer the gesture.
+   * @default true
+   */
+  wheel?: boolean;
+}
+
+/** What the gestures come to when a viewer states none of them. */
+export const DEFAULT_ZOOM_GESTURES: Required<ZoomGestures> = {
+  drag: 'xAxis',
+  wheel: true,
+};
+
+/**
+ * Whether two windows show the same thing, compared by their four numbers.
+ *
+ * By value and never by identity, because the fitted window is rebuilt from the
+ * spectra whenever anything about them changes — a colour, a name, a visibility
+ * — and only some of those changes move an axis. A chart that told the two
+ * apart by identity would throw the user's zoom away every time they touched
+ * the list beside it.
+ * @param current - The window in force.
+ * @param next - The window just worked out.
+ * @returns Whether both axes already run between the same bounds.
+ */
+export function sameChartDomain(
+  current: ChartDomain,
+  next: ChartDomain,
+): boolean {
+  return (
+    current.x[0] === next.x[0] &&
+    current.x[1] === next.x[1] &&
+    current.y[0] === next.y[0] &&
+    current.y[1] === next.y[1]
+  );
+}

package/src/chart/core/chartGeometry.ts

@@ -0,0 +1,159 @@
+/**
+ * Where the plot sits inside the SVG, and in what order its bands are painted.
+ *
+ * The margins are deliberately not symmetric, because the two axes ask for very
+ * different room: a value label runs to `1.2e6` and needs the width on the
+ * left, while the horizontal axis carries its ticks and its title stacked under the
+ * plot. Nothing here is responsive — whatever lays the chart out decides how big
+ * it is, and this module only says what is left over for the data.
+ */
+
+/** The box a chart was given, in CSS pixels. */
+export interface ChartSize {
+  /** How wide the SVG is. */
+  width: number;
+  /** How tall the SVG is. */
+  height: number;
+}
+
+/**
+ * The plotting area inside the margins, in SVG user units.
+ *
+ * `right` and `bottom` are carried rather than recomputed at each use: a clip
+ * path, the brush rectangle and both axes all need the far edge, and three
+ * copies of `left + width` are three chances for one of them to drift.
+ */
+export interface PlotRect {
+  /** Distance from the left edge of the SVG to the plot. */
+  left: number;
+  /** Distance from the top edge of the SVG to the plot. */
+  top: number;
+  /** How wide the plot is, never below `MINIMUM_PLOT_SIDE`. */
+  width: number;
+  /** How tall the plot is, never below `MINIMUM_PLOT_SIDE`. */
+  height: number;
+  /** `left + width`, where the horizontal axis ends. */
+  right: number;
+  /** `top + height`, the baseline the horizontal axis is drawn on. */
+  bottom: number;
+}
+
+/**
+ * The four sides of the room kept around a plot, in CSS pixels.
+ *
+ * Named as a type of its own because `MARGIN` is frozen at literal values, so a
+ * caller asking for `{ bottom: 4 }` would be told that 4 is not 34 — the
+ * defaults are constants, but a margin is four numbers.
+ */
+export interface ChartMargin {
+  /** Room above the plot. */
+  top: number;
+  /** Room to the right of the plot. */
+  right: number;
+  /** Room below the plot, where the horizontal axis is written. */
+  bottom: number;
+  /** Room to the left of the plot, where the value axis is written. */
+  left: number;
+}
+
+/**
+ * The room kept around the plot for the axes and their titles.
+ *
+ * `left` is the widest because it has to hold a value label; `bottom` is
+ * deeper than `top` because it stacks the tick labels and the axis title under
+ * the plot, where `top` only keeps the topmost value label off the edge.
+ *
+ * Each of them is the furniture and no more than the furniture. `Axes` writes
+ * its tick row five pixels under the plot and its title thirteen under that,
+ * which puts the deepest ink of a `(min)` some thirty pixels down; what is left
+ * is slack. A stack pays these four numbers once per pane — a column of three
+ * chromatograms over a spectrum pays `bottom` four times — and a pixel of slack
+ * in here is a pixel the measurement was not drawn in, over and over.
+ */
+export const MARGIN = { top: 10, right: 16, bottom: 34, left: 60 } as const;
+
+/**
+ * How much room a chart leaves under its plot when it writes no horizontal axis
+ * of its own.
+ *
+ * A pane of a stack above the foot draws no tick row and no axis title — the
+ * panes share one window, so one axis under the last of them says everything —
+ * and this is what it keeps instead: enough that the trace does not run into
+ * the splitter under it, and no more. It lives here beside `MARGIN` rather than
+ * in the viewer that uses it, because the arithmetic that shares a stack's
+ * height between its panes has to subtract exactly the difference between the
+ * two, and a second copy of either number is a stack whose plots do not line up.
+ */
+export const SHARED_AXIS_MARGIN = 8;
+
+/**
+ * The smallest plot the arithmetic is allowed to describe.
+ *
+ * A chart is briefly laid out at nothing — a panel opening, a splitter dragged
+ * shut, the first render before the container has been measured — and the naive
+ * subtraction then gives a negative width, which every scale built from it turns
+ * into an infinity and the DOM refuses outright. Ten pixels is small enough to
+ * be invisible and large enough to keep every number finite until the real size
+ * arrives.
+ */
+export const MINIMUM_PLOT_SIDE = 10;
+
+/**
+ * The six bands of the chart, bottom to top, in the order they are painted.
+ *
+ * The order is the whole interaction design in one array. `defs` holds the clip
+ * paths and markers and is never painted itself. `axes` sits under the data so a
+ * grid line can never be mistaken for a peak. `data` is the only clipped band,
+ * so a zoomed trace stops at the plot edge instead of running out over the
+ * labels — which is also why `guide` is separate: an annotation's label sits
+ * above the tallest peak and must be allowed out of the clip. `selection` covers
+ * the data so a drag stays visible over it, and `tracker` is last so the
+ * crosshair and its readout are never occluded by anything.
+ */
+export const CHART_LAYERS = [
+  'defs',
+  'axes',
+  'data',
+  'guide',
+  'selection',
+  'tracker',
+] as const;
+
+/** One band of the chart. */
+export type ChartLayer = (typeof CHART_LAYERS)[number];
+
+/**
+ * Work out the plotting area for a chart of a given size.
+ * @param size - The box the chart was given.
+ * @param margin - Room to keep around the plot instead of the module default.
+ * Whatever side it names is used and every side it omits keeps `MARGIN`, because
+ * a chart that only wants its foot back should not have to restate the 60 px its
+ * value labels need. A chart standing alone wants all four sides, but panes
+ * stacked one above another do not: only the pane at the foot of the stack draws
+ * a tick row, and only the topmost has anything above it to be kept clear of.
+ * Three panes sharing a 400 px column each pay 48 px at the bottom and 16 px at
+ * the top, which is 192 px of axis furniture where 64 px is all that can be seen
+ * — the other 128 px is blank room taken out of the traces, and the middle pane
+ * is left drawing in barely half of its third. Passing `{ top: 4, bottom: 4 }`
+ * to every pane but the two that need the room hands it back.
+ * @returns The plot inside the margins, clamped so it is never degenerate.
+ */
+export function plotRect(
+  size: ChartSize,
+  margin?: Partial<ChartMargin>,
+): PlotRect {
+  const top = margin?.top ?? MARGIN.top;
+  const right = margin?.right ?? MARGIN.right;
+  const bottom = margin?.bottom ?? MARGIN.bottom;
+  const left = margin?.left ?? MARGIN.left;
+  const width = Math.max(MINIMUM_PLOT_SIDE, size.width - left - right);
+  const height = Math.max(MINIMUM_PLOT_SIDE, size.height - top - bottom);
+  return {
+    left,
+    top,
+    width,
+    height,
+    right: left + width,
+    bottom: top + height,
+  };
+}

package/src/chart/core/chartPane.ts

@@ -0,0 +1,10 @@
+/**
+ * Marks the box one pane of a chart stack is drawn in.
+ *
+ * A stack is laid out in `chartStackLevel.tsx` and read again, from the outside,
+ * by whatever takes a picture of the editor the stack sits in — `drawingIn` has
+ * to know that a box holding a chromatogram over a spectrum holds two drawings
+ * rather than one, and this mark is how it tells. It sits in a file of its own
+ * so that neither of them has to import the other's React.
+ */
+export const CHART_PANE_ATTRIBUTE = 'data-chart-pane';

package/src/chart/core/chartScale.ts

@@ -27,7 +27,10 @@ export interface ChartScale {
  * @param rangeMax - The pixel `domainMax` maps to.
  * @returns The mapping. A zero-width or non-finite domain gives a `factor` of
  * zero, which pins every value to the middle of the range so that a constant
- * column still draws instead of vanishing.
+ * column still draws instead of vanishing. A range that is not a range — a
+ * plot measured before it was laid out — gives an `offset` of `NaN` instead,
+ * because there is no pixel a value could honestly be put at, and every mark
+ * already declines to draw what does not map.
  */
 export function chartScale(
   domainMin: number,
@@ -37,9 +40,9 @@ export function chartScale(
 ): ChartScale {
   const span = domainMax - domainMin;
   const reach = rangeMax - rangeMin;
-  if (span === 0 || !Number.isFinite(span) || !Number.isFinite(reach)) {
-    const middle = (rangeMin + rangeMax) / 2;
-    return { offset: Number.isFinite(middle) ? middle : 0, factor: 0 };
+  if (!Number.isFinite(reach)) return { offset: Number.NaN, factor: 0 };
+  if (span === 0 || !Number.isFinite(span)) {
+    return { offset: (rangeMin + rangeMax) / 2, factor: 0 };
   }
   const factor = reach / span;
   return { offset: rangeMin - domainMin * factor, factor };

package/src/chart/core/chartTheme.ts

@@ -0,0 +1,161 @@
+/**
+ * Every colour and every measurement the chart is drawn with.
+ *
+ * Each colour is a custom property with a literal fallback baked in, and is
+ * applied through the `style` prop rather than through the matching SVG
+ * attribute — `fill="var(--spectrum-axis, #64748b)"` is not a colour any browser
+ * resolves, because `var()` is a CSS value and a presentation attribute is not
+ * parsed as one. `style={{ fill: CHART_COLORS.axis }}` is.
+ *
+ * One set of tokens for every viewer built on this package, rather than one per
+ * viewer: a page showing a mass spectrum beside an infrared one is showing two
+ * charts that have to look like the same instrument, and two token families
+ * would let them drift apart at the first theme change.
+ *
+ * The fallbacks are what make the package usable on its own: a host that sets
+ * none of these tokens still gets a chart that reads correctly, and a host with
+ * a dark theme or a house palette overrides whichever it cares about by setting
+ * the properties on any ancestor. Nothing here is a prop, because a colour
+ * threaded through props is a colour that ends up hard-coded in one component
+ * that forgot to accept it.
+ */
+
+/** The colours of everything the chart draws that is not a spectrum. */
+export const CHART_COLORS = {
+  /** The two axis lines and their ticks. */
+  axis: 'var(--spectrum-axis, #64748b)',
+  /** The numbers along both axes. */
+  tick: 'var(--spectrum-tick, #475569)',
+  /** The axis titles, whatever the viewer calls its two axes. */
+  title: 'var(--spectrum-title, #334155)',
+  /** The rules across the plot, behind the data. */
+  grid: 'var(--spectrum-grid, #e2e8f0)',
+  /** The rule at zero, which a mirrored pair is reflected in. */
+  zeroRule: 'var(--spectrum-zero-rule, #cbd5e1)',
+  /** A mark on a feature an annotation explained. */
+  annotation: 'var(--spectrum-annotation, #2563eb)',
+  /**
+   * A mark where an annotation nothing answered would fall, drawn dashed. Grey
+   * rather than red: a fragment the spectrum does not carry is an answer, and
+   * colouring it as a failure would say the opposite.
+   */
+  annotationUnmatched: 'var(--spectrum-annotation-unmatched, #cbd5e1)',
+  /**
+   * A mark on a place the measurement drawn below was cut from — the peaks a
+   * survey scan was fragmented at.
+   *
+   * Its own token rather than the annotation blue, because the two are claims
+   * of different kinds laid over the same peaks: an annotation says *this is
+   * what I think that peak is*, and a precursor mark says *this is what the
+   * instrument did with it*. A spectrum can carry both at once, and a reader
+   * has to be able to tell one row of marks from the other.
+   */
+  precursor: 'var(--spectrum-precursor, #7c3aed)',
+  /** The line from a label back down to the peak it belongs to. */
+  leader: 'var(--spectrum-leader, #94a3b8)',
+  /** The fill of a label box, opaque enough to read over a dense trace. */
+  labelBackground:
+    'var(--spectrum-label-background, rgba(255, 255, 255, 0.88))',
+  /** Its border. */
+  labelBorder: 'var(--spectrum-label-border, #cbd5e1)',
+  /** The text inside it. */
+  labelText: 'var(--spectrum-label-text, #1e293b)',
+  /**
+   * The paper a label written straight onto the plot is set on, laid behind its
+   * glyphs rather than in a box around them — the colour of the chart itself,
+   * which is why a host with a dark theme has to override it along with the rest.
+   */
+  labelHalo: 'var(--spectrum-label-halo, #ffffff)',
+  /** Whatever the pointer has come to rest on, wherever it was hovered. */
+  highlight: 'var(--spectrum-highlight, #f97316)',
+  /** The rectangle a drag is sweeping out. */
+  selection: 'var(--spectrum-selection, rgba(37, 99, 235, 0.12))',
+  /** Its edge. */
+  selectionBorder: 'var(--spectrum-selection-border, #2563eb)',
+  /** The crosshair following the pointer. */
+  tracker: 'var(--spectrum-tracker, #94a3b8)',
+  /** What it reads out. */
+  trackerText: 'var(--spectrum-tracker-text, #0f172a)',
+} as const;
+
+/**
+ * The type sizes, in pixels.
+ *
+ * Small and fixed rather than inherited: the chart is a drawing, and a host
+ * whose base font is 18px would push its tick labels into one another. The
+ * family is deliberately not set here, so the chart still looks like the
+ * application it is embedded in.
+ */
+export const CHART_FONT = {
+  /** The numbers along both axes. */
+  tick: 10,
+  /** The axis titles. */
+  title: 12,
+  /** The labels pinned above the peaks. */
+  label: 11,
+  /** The readout the crosshair carries. */
+  readout: 11,
+} as const;
+
+/**
+ * The geometry of a label pinned above a feature.
+ *
+ * A label is two lines often enough — an m/z over a formula, a wavenumber over
+ * the group it is assigned to — that the spacing has to be a constant both the
+ * drawing and the declutter sweep agree on, or the boxes are spaced for one
+ * height and drawn at another.
+ */
+export const PEAK_LABEL = {
+  /** The baseline-to-baseline distance between two stacked lines. */
+  lineHeight: 11,
+  /** The clear space between the top of a stick and its first line. */
+  topPad: 10,
+  /**
+   * How far the mark on a named peak reaches from the tip of its stick.
+   *
+   * It reaches *away* from the stack, down into the peak, because the clear
+   * space above the tip is where the numbers are written and the mark is there
+   * to say which peak they are about. Short on purpose: what is drawn is the
+   * **top of the centroid stick**, enough to put a picked peak exactly on the
+   * profile it was picked from — a rule carried all the way to the baseline is
+   * the centroid trace itself, which is the other thing the row toggles.
+   */
+  topMark: 10,
+  /**
+   * Half the width a label claims while the pointer is on it, which is what the
+   * declutter sweep keeps its neighbours out of.
+   */
+  hoverHalfWidth: 26,
+} as const;
+
+/**
+ * The halo a label written straight onto the plot carries.
+ *
+ * A number over a peak is written over whatever the plot has there — a grid
+ * line, a dense trace, the crosshair following the pointer, the tail of the
+ * label beside it — and a glyph crossed by a line is a glyph read twice before
+ * it is read at all. So the glyphs are stroked in the colour of the paper and
+ * that stroke is painted *first*, which clears a hairline of chart from around
+ * every letter without a box, a border or a fill hiding the data underneath.
+ *
+ * `paintOrder` is the whole of it and is easy to leave out: the default order
+ * paints the stroke over the fill, so the same three properties without it draw
+ * every label in white on white.
+ */
+export const LABEL_HALO = {
+  paintOrder: 'stroke',
+  stroke: CHART_COLORS.labelHalo,
+  strokeWidth: 3,
+  strokeLinejoin: 'round',
+} as const;
+
+/**
+ * How far the supporting line of a label is let back towards the paper.
+ *
+ * A label is rarely one thing: a mass peak carries what it is *and* how tall it
+ * stood, and the crosshair reads a place on both axes at once. Written in one
+ * ink they are read together, which means the line somebody wants has to be
+ * found among the ones they do not. Six tenths is enough to grade them apart at
+ * eleven pixels and not so far as to make the quiet line look disabled.
+ */
+export const LABEL_QUIET = 0.6;

package/src/chart/core/chartViewport.ts

@@ -33,8 +33,20 @@ export const CHART_WHEEL_LINE = 16;
 /** Pixels it is worth where the browser reports pages. */
 export const CHART_WHEEL_PAGE = 400;
 
-/** The most one wheel event may zoom by, so a stray burst cannot jump. */
-export const CHART_WHEEL_LARGEST = 4;
+/**
+ * The most travel one wheel event is read as, in pixels.
+ *
+ * A trackpad flick arrives as a handful of events carrying several hundred
+ * pixels each, and an inertial one keeps arriving after the fingers have left
+ * the glass. Uncapped, a single flick takes an axis through several orders of
+ * magnitude and the data is gone; capped, the gesture stays fast and is always
+ * recoverable by flicking the other way.
+ *
+ * The cap is written in travel rather than as a largest factor because travel
+ * is what the browser reports and what varies between them — so a chart that
+ * zooms at its own pace is held to the same burst as every other.
+ */
+export const CHART_WHEEL_TRAVEL = 240;
 
 /**
  * The viewport a zoom about one point leaves behind.
@@ -130,9 +142,13 @@ export function chartZoomDomain(
  * The travel is normalised first, because the same notch of the same wheel
  * arrives as pixels in one browser and as lines in another, and a zoom that
  * moves three times as fast in Firefox is a fault the reader blames on the
- * figure. One event is capped: a trackpad flick can deliver a whole page of
- * travel at once, and landing four hundred times out is not recoverable by
- * feel.
+ * figure. Then it is capped at {@link CHART_WHEEL_TRAVEL}, so one burst can
+ * only ever be worth one flick.
+ *
+ * The factor is `exp(pixels x rate)`, so the gesture is multiplicative: two
+ * notches in and two notches out land back where they started, whichever way
+ * round they were made, and a zoom deep into one small feature comes back out
+ * at the pace it went in.
  * @param delta - The event's `deltaY`; positive scrolls away and zooms out.
  * @param mode - Its `deltaMode`: 0 pixels, 1 lines, 2 pages. Defaults to `0`.
  * @param speed - Share zoomed per pixel of travel. Defaults to {@link CHART_WHEEL_SPEED}.
@@ -143,15 +159,26 @@ export function chartWheelFactor(
   mode = 0,
   speed = CHART_WHEEL_SPEED,
 ): number {
-  if (!Number.isFinite(delta) || delta === 0) return 1;
-  const pixels = delta * wheelPixels(mode);
+  const travel = chartWheelTravel(delta, mode);
+  if (travel === 0) return 1;
   const rate = Number.isFinite(speed) && speed > 0 ? speed : CHART_WHEEL_SPEED;
-  const factor = Math.exp(pixels * rate);
-  if (!Number.isFinite(factor)) return delta > 0 ? CHART_WHEEL_LARGEST : 1;
-  return Math.min(
-    CHART_WHEEL_LARGEST,
-    Math.max(1 / CHART_WHEEL_LARGEST, factor),
-  );
+  return Math.exp(travel * rate);
+}
+
+/**
+ * The travel one wheel event carries, in pixels, capped.
+ *
+ * Separate from the factor because a gesture that is not a zoom — a wheel that
+ * scales a value axis about its baseline — needs the same normalisation and
+ * the same cap while computing something else entirely.
+ * @param delta - The event's `deltaY`.
+ * @param mode - Its `deltaMode`: 0 pixels, 1 lines, 2 pages. Defaults to `0`.
+ * @returns The travel, `0` for an event that says nothing.
+ */
+export function chartWheelTravel(delta: number, mode = 0): number {
+  if (!Number.isFinite(delta) || delta === 0) return 0;
+  const pixels = delta * wheelPixels(mode);
+  return Math.min(CHART_WHEEL_TRAVEL, Math.max(-CHART_WHEEL_TRAVEL, pixels));
 }
 
 function wheelPixels(mode: number): number {