react-cheminfo 0.28.0 → 0.29.0

package/src/chart/core/stackCapacity.ts

@@ -0,0 +1,162 @@
+/**
+ * How many charts a column of a given height can stack, and how tall each stands.
+ *
+ * A viewer that draws one pane per selected spectrum has to answer a question
+ * the stack itself never asks. A reader who ticks a dozen spectra has not asked
+ * for twelve panes of fifty pixels, and a stack handed them draws twelve stubs
+ * with a full set of axes over each — the failure `ChartStack.tsx`'s header
+ * describes, arrived at from above instead of through a splitter. So the number
+ * of panes is settled from the height actually available, against the stack's
+ * own floors rather than a number somebody hoped for, and whatever a reader
+ * selects past that number is overlaid together into the last pane rather than
+ * dropped, which is the one outcome a reader cannot see happening.
+ *
+ * All of it is arithmetic over `chartStackLevel.tsx`'s floors and
+ * `chartGeometry.ts`'s margins; nothing here renders, measures or reads a
+ * spectrum.
+ */
+
+import { MARGIN, SHARED_AXIS_MARGIN } from './chartGeometry.ts';
+
+/**
+ * The shortest a pane that is *not* at the foot of the stack may stand, in
+ * pixels.
+ *
+ * Ninety, and ninety exactly, because it is not a judgement about how short a
+ * chart may be: `chartStackLevel.tsx` hands `SplitPane` a `closeThreshold` of 90
+ * at every non-foot split, and a split measuring under that closes its pane
+ * outright — before a splitter has ever been touched, so a stack built on a
+ * floor of 80 would come up with panes already shut and no gesture that made
+ * them so. The threshold is applied as `>=`, which is why standing exactly on it
+ * is allowed. That constant is module-private over there, so its value is
+ * restated here and the two have to move together.
+ *
+ * A caller must state this as each pane's own `minimumHeight`. Left unsaid,
+ * `paneHeight` clamps the pane up to the 120 pixels it defaults to, and five
+ * panes would then demand 688 pixels where 538 draws them.
+ */
+export const STACKED_MINIMUM = 90;
+
+/**
+ * What the pane at the foot pays for its axis beyond what every pane pays, in
+ * pixels.
+ *
+ * Only the foot of a stack writes the tick row and the axis title under its
+ * plot, and that is `MARGIN.bottom` less the `SHARED_AXIS_MARGIN` a pane keeps
+ * even when it writes no axis — 26 of them, not 34. The *difference* is what
+ * matters and the whole bottom margin is not it: a stacked pane still leaves a
+ * little room under its trace, and charging the foot for all 34 draws its plot
+ * eight pixels taller than the others, so a peak of one intensity comes out
+ * taller at the bottom of the stack than at the top. Every other side of the margin
+ * is paid alike by every pane, the room kept above the plot for the tallest
+ * peak's label as much as the gutter the value labels are written in, so it
+ * cancels out of the difference between two panes and does not appear here.
+ * This one asymmetry is the whole of why an equal split of the *boxes* is not an
+ * equal split of the *plots*.
+ */
+export const FOOT_FURNITURE = MARGIN.bottom - SHARED_AXIS_MARGIN;
+
+/**
+ * The shortest the pane at the foot may stand, in pixels.
+ *
+ * The ordinary floor plus the tick row and axis title only it writes, so that
+ * the plot left inside it is the same plot `STACKED_MINIMUM` leaves inside a
+ * pane above it. Deriving it rather than picking 116 is what makes the tightest
+ * stack land exactly on both floors at once: at a height of
+ * `FOOT_MINIMUM + (n - 1) * STACKED_MINIMUM`, `stackShares` gives every pane
+ * above the foot exactly `STACKED_MINIMUM` and the foot exactly this.
+ */
+export const FOOT_MINIMUM = STACKED_MINIMUM + FOOT_FURNITURE;
+
+/**
+ * How much room the splitter between two panes takes, in pixels.
+ *
+ * `react-science` draws a vertical splitter as a ten-pixel bar, and there is one
+ * between each *pair* of panes rather than one per pane — five of them under six
+ * panes. Small enough to be forgotten and large enough that forgetting it costs
+ * a pane: the fifty it comes to across a full stack is more than half a stacked
+ * minimum.
+ */
+export const SPLITTER = 10;
+
+/**
+ * The most panes worth stacking at all, however tall the column.
+ *
+ * Six, and the height is not what settles it. A 1080-pixel screen with the side
+ * panels open leaves the stack something near 900 pixels; six panes take 50 of
+ * those in splitters and share the rest, which is a box of 133 pixels each and a
+ * plot inside it of barely a hundred — about the height of the label stack a
+ * mass spectrum draws over its tallest sticks, so a seventh pane makes the
+ * labels taller than the trace they belong to. And the reader stacked the panes
+ * in order to compare them: past six the first and the last are most of a page
+ * apart, and an eye travelling that far is no longer comparing anything.
+ * Whatever is selected beyond this is overlaid into the last pane, where traces
+ * drawn over one another are compared the way they always were.
+ */
+export const STACK_LIMIT = 6;
+
+/**
+ * How many panes a column of a given height can hold and still draw spectra.
+ *
+ * The arithmetic is the stack as it will actually be built: one pane at the foot
+ * carrying the horizontal axis, every other pane at the stacked floor, and a
+ * splitter between each pair. Nothing here rounds in the caller's favour — a
+ * height one pixel short of the fourth pane holds three.
+ * @param height - The whole column the stack fills, in pixels, with the
+ * splitters counted in: it is the box `ChartStack` is handed, not the room its
+ * panes are left with.
+ * @returns At least one, because a lone pane squeezed short is still the
+ * measurement and the stack draws it rather than nothing — that is why the foot
+ * pane is given no close threshold — and never more than `STACK_LIMIT`.
+ */
+export function stackCapacity(height: number): number {
+  const beyondTheFoot = height - FOOT_MINIMUM;
+  const fits = 1 + Math.floor(beyondTheFoot / (STACKED_MINIMUM + SPLITTER));
+  return Math.min(STACK_LIMIT, Math.max(1, fits));
+}
+
+/**
+ * How tall each pane of the stack stands, top to bottom.
+ *
+ * The split equalises the **plot** rather than the box. An equal share of the
+ * box hands the foot pane 34 pixels of tick row and axis title that the panes
+ * above it do not draw, so its trace comes out visibly shorter than theirs while
+ * every box measures the same — the one thing a reader comparing two spectra
+ * side by side must not be shown. So `FOOT_FURNITURE` is taken off the top, what
+ * is left is divided evenly, and the foot is given its share back with the
+ * furniture on it.
+ *
+ * The division is floored, so the panes above the foot are whole pixels and the
+ * remainder — never more than `count - 1` of them — lands on the foot, which is
+ * the tallest pane and the one where two pixels are least visible. That keeps
+ * the sum exact, and it is also why the foot's share is *at least*
+ * `FOOT_FURNITURE` above a stacked one rather than exactly it.
+ * @param height - The room the panes themselves share, in pixels. A caller
+ * holding the whole column subtracts the splitters first — `height -
+ * (count - 1) * SPLITTER` — because `SplitPane` takes those out of the panes,
+ * not out of the column.
+ * @param count - How many panes to stack, normally whatever `stackCapacity`
+ * answered.
+ * @returns One height per pane, summing exactly to `height`, each at or above
+ * its own floor. The two cannot both hold for a height short of what `count`
+ * panes need, and there the floors win and the sum overshoots: a pane under its
+ * floor is the stub with a full set of axes over it, which is the worse of the
+ * two pictures. A lone pane is the exception and takes the whole height floor
+ * and all, since there is nothing to redistribute to and nothing to compare it
+ * against.
+ */
+export function stackShares(height: number, count: number): readonly number[] {
+  if (!Number.isInteger(count) || count < 1) return [];
+  if (count === 1) return [height];
+
+  const stacked = Math.max(
+    STACKED_MINIMUM,
+    Math.floor((height - FOOT_FURNITURE) / count),
+  );
+  const shares = new Array<number>(count);
+  for (let index = 0; index < count - 1; index++) {
+    shares[index] = stacked;
+  }
+  shares[count - 1] = Math.max(FOOT_MINIMUM, height - stacked * (count - 1));
+  return shares;
+}

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