react-cheminfo 0.28.0 → 0.30.0

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 {

package/src/chart/core/guidePlacement.ts

@@ -0,0 +1,66 @@
+/**
+ * Where the guide for one value is drawn when that value is not on screen.
+ *
+ * A chart zoomed onto a single feature is the normal way of reading a spectrum
+ * — one isotopologue cluster two millimass units wide, one chromatographic peak
+ * four seconds wide — and most of what a panel beside it can point at then lies
+ * outside the window. Drawing nothing in that case answers the only question
+ * the guide exists for — where is it? — with silence, and the reader is left
+ * unable to tell a fragment the spectrum does not carry from one that is simply
+ * off to the left. So the guide is parked on the edge it went out of instead,
+ * dashed and carrying an arrow, which says both that it is elsewhere and which
+ * way.
+ *
+ * Nothing here reads the domain: the value is put through the scale, and the
+ * pixel that comes back is compared against the two pixel edges of the plot.
+ * That is what lets `left` and `right` mean what they say on an axis that runs
+ * backwards, as an infrared chart's wavenumbers do — they are the edges of the
+ * screen, not the ends of the window, and a descending axis parks a value below
+ * its window on the right, which is exactly where the reader must look for it.
+ */
+
+import type { PlotRect } from './chartGeometry.ts';
+import type { ChartScale } from './chartScale.ts';
+import { chartPixel, chartRoundPixel } from './chartScale.ts';
+
+/** Where a guide ended up, and whether that is where its value actually is. */
+export interface GuidePlacement {
+  /** Where the guide is drawn, in pixels. */
+  x: number;
+  /**
+   * Which side of the window the value lies on, `null` when it is inside it and
+   * the guide is therefore standing on the value itself.
+   */
+  direction: 'left' | 'right' | null;
+}
+
+/**
+ * Work out where the guide for a value goes.
+ *
+ * The test is made in pixels rather than against the domain, so the guide can
+ * never disagree with the axis it is drawn over: both are read off the same
+ * scale, and a rounding that puts a value a hundredth of a unit inside the
+ * window puts the guide a hundredth of a pixel inside the plot rather than
+ * parking it on an edge it is standing beside.
+ * @param value - The place on the horizontal axis being pointed at, in whatever
+ * that axis measures — an m/z, a retention time, a wavenumber.
+ * @param plot - The plotting area the guide is confined to.
+ * @param xScale - The horizontal axis as it is currently zoomed.
+ * The pixel is rounded for the markup, to the hundredth: that is under a tenth
+ * of a device pixel at any zoom a browser offers, and it keeps the last digits
+ * of a multiply-add out of the `d` a reader has to look at in a failing test.
+ * @returns Where to draw it, or `null` for a value no scale maps anywhere — an
+ * empty chart's degenerate axis, or a `NaN` out of an unparsed field.
+ */
+export function guidePlacement(
+  value: number,
+  plot: PlotRect,
+  xScale: ChartScale,
+): GuidePlacement | null {
+  if (!Number.isFinite(value)) return null;
+  const pixel = chartPixel(xScale, value);
+  if (!Number.isFinite(pixel)) return null;
+  if (pixel < plot.left) return { x: plot.left, direction: 'left' };
+  if (pixel > plot.right) return { x: plot.right, direction: 'right' };
+  return { x: chartRoundPixel(pixel), direction: null };
+}

package/src/chart/core/index.ts

@@ -41,18 +41,137 @@ export { chartAxisTitle, chartShare } from './chartLabels.ts';
 export type { ChartColorRole } from './chartPalette.ts';
 export { CHART_SERIES_COLORS, chartSeriesColor } from './chartPalette.ts';
 export type { ChartScale } from './chartScale.ts';
-export { chartPixel, chartScale, chartValue } from './chartScale.ts';
+export {
+  chartPixel,
+  chartRoundPixel,
+  chartScale,
+  chartValue,
+} from './chartScale.ts';
 export type { ChartViewport } from './chartViewport.ts';
 export {
   CHART_SMALLEST_ZOOM,
-  CHART_WHEEL_LARGEST,
   CHART_WHEEL_LINE,
   CHART_WHEEL_PAGE,
   CHART_WHEEL_SPEED,
+  CHART_WHEEL_TRAVEL,
   chartClampViewport,
   chartWheelFactor,
+  chartWheelTravel,
   chartZoomDomain,
   chartZoomViewport,
 } from './chartViewport.ts';
 export type { MatrixLike } from './matrix.ts';
 export { mappedMatrix, rowMatrix, stackedMatrix } from './matrix.ts';
+
+export {
+  SCIENTIFIC_ABOVE,
+  SCIENTIFIC_BELOW,
+  axisLabeller,
+  formatNumber,
+  formatScientific,
+} from './axisLabels.ts';
+export { MAXIMUM_DRIFT_STEPS, layoutAnnotationBoxes } from './boxLayout.ts';
+export type {
+  ChartDomain,
+  DragMode,
+  YAxisRules,
+  ZoomDragMode,
+  ZoomGestures,
+  ZoomRules,
+} from './chartDomain.ts';
+export {
+  DEFAULT_Y_AXIS_RULES,
+  DEFAULT_ZOOM_GESTURES,
+  sameChartDomain,
+} from './chartDomain.ts';
+export type {
+  ChartLayer,
+  ChartMargin,
+  ChartSize,
+  PlotRect,
+} from './chartGeometry.ts';
+export {
+  CHART_LAYERS,
+  MARGIN,
+  MINIMUM_PLOT_SIDE,
+  SHARED_AXIS_MARGIN,
+  plotRect,
+} from './chartGeometry.ts';
+export { CHART_PANE_ATTRIBUTE } from './chartPane.ts';
+export {
+  CHART_COLORS,
+  CHART_FONT,
+  LABEL_HALO,
+  LABEL_QUIET,
+  PEAK_LABEL,
+} from './chartTheme.ts';
+export type { GuidePlacement } from './guidePlacement.ts';
+export { guidePlacement } from './guidePlacement.ts';
+export { labelStackBaselines } from './labelStack.ts';
+export type {
+  LegendBox,
+  LegendBoxEntry,
+  LegendBoxOptions,
+  LegendRow,
+} from './legendBox.ts';
+export {
+  CLOSE_COLUMN,
+  MAXIMUM_CHARACTERS,
+  PADDING,
+  ROW_HEIGHT,
+  SWATCH,
+  hiddenLabel,
+  legendBox,
+  legendLabel,
+  legendNames,
+} from './legendBox.ts';
+export type { SelectionRectangle } from './selectionGeometry.ts';
+export { selectionRectangle } from './selectionGeometry.ts';
+export {
+  ALL_SPECTRUM_COLORS,
+  EXTRA_SPECTRUM_COLORS,
+  SPECTRUM_COLORS,
+  nextSpectrumColor,
+} from './spectrumColor.ts';
+export {
+  FOOT_FURNITURE,
+  FOOT_MINIMUM,
+  STACKED_MINIMUM,
+  STACK_LIMIT,
+  stackCapacity,
+  stackShares,
+} from './stackCapacity.ts';
+export type { ChartPoint, PointerSurface, ScreenMatrix } from './svgPoint.ts';
+export { svgPointAt } from './svgPoint.ts';
+export type { AreaPathOptions } from './tracePath.ts';
+export { areaPath, profilePath, stickPath } from './tracePath.ts';
+export type { ReadoutPlacement } from './trackerReadout.ts';
+export {
+  READOUT_GAP,
+  READOUT_LINES,
+  READOUT_WIDTH,
+  readoutPlacement,
+} from './trackerReadout.ts';
+export type { ViewBox, ViewState, ZoomBounds } from './viewTransform.ts';
+export {
+  INITIAL_VIEW,
+  MAXIMUM_CONTENT_SCALE,
+  MAXIMUM_ZOOM,
+  MINIMUM_ZOOM,
+  baseViewBox,
+  clampZoom,
+  magnificationOf,
+  panBy,
+  viewBoxAttribute,
+  viewBoxOf,
+  zoomAbout,
+  zoomToAboutCentre,
+} from './viewTransform.ts';
+export type { DragBox, ZoomSelection } from './zoomDomain.ts';
+export {
+  MINIMUM_DRAG,
+  releasedBeyondBaseline,
+  scaledYAxis,
+  zoomSelection,
+  zoomedDomain,
+} from './zoomDomain.ts';

package/src/chart/core/labelStack.ts

@@ -0,0 +1,72 @@
+/**
+ * Where each line of a stack of labels above a feature is written.
+ *
+ * The arithmetic only, and none of the wording: what a stack *says* is the one
+ * thing every viewer answers differently — a mass peak carries its intensity,
+ * its m/z and its charge, an infrared band carries its wavenumber and the group
+ * it is assigned to — while where the lines go is the same sum in both, and the
+ * same sum again for the reflected half of a mirrored chart.
+ */
+
+import { PEAK_LABEL } from './chartTheme.ts';
+
+/**
+ * Where each line of a stack is written, in pixels down the SVG.
+ *
+ * A stack that would run off the top of the plot is **pushed back down** rather
+ * than clipped: the tallest peak of a spectrum is the one most worth naming, its
+ * tip is by construction near the top of the window, and a label cut in half by
+ * the plot edge names nothing. Sliding it down puts it over the feature instead,
+ * which is the one place a reader already knows to look.
+ * @param tip - Where the top of the feature is, in pixels down the SVG.
+ * @param lineCount - How many lines the stack has.
+ * @param bounds - `[top, bottom]` of the plot in pixels, which no line may pass.
+ * @param below - Whether the stack hangs under the feature, which is what the
+ *   mirrored half of a chart wants — above its sticks is the other spectrum.
+ *   Defaults to `false`.
+ * @returns The baseline of each line, in the order the lines were given.
+ */
+export function labelStackBaselines(
+  tip: number,
+  lineCount: number,
+  bounds: readonly [number, number],
+  below = false,
+): Float64Array {
+  const count = Number.isFinite(lineCount)
+    ? Math.max(0, Math.floor(lineCount))
+    : 0;
+  const baselines = new Float64Array(count);
+  if (count === 0) return baselines;
+
+  const { lineHeight, topPad } = PEAK_LABEL;
+  if (below) {
+    for (let line = 0; line < count; line++) {
+      baselines[line] = tip + topPad + (count - line) * lineHeight;
+    }
+    shift(baselines, Math.min(0, bounds[1] - (baselines[0] as number)));
+    return baselines;
+  }
+
+  for (let line = 0; line < count; line++) {
+    baselines[line] = tip - topPad - (count - 1 - line) * lineHeight;
+  }
+  // A baseline one line height below the top edge is what keeps the glyphs of
+  // the topmost line inside the plot rather than half over it.
+  shift(
+    baselines,
+    Math.max(0, bounds[0] + lineHeight - (baselines[0] as number)),
+  );
+  return baselines;
+}
+
+/**
+ * Move every baseline of a stack by the same amount.
+ * @param baselines - The baselines, written into.
+ * @param delta - How far down to move them; zero leaves them alone.
+ */
+function shift(baselines: Float64Array, delta: number): void {
+  if (delta === 0) return;
+  for (let line = 0; line < baselines.length; line++) {
+    baselines[line] = (baselines[line] as number) + delta;
+  }
+}