react-cheminfo 0.28.0 → 0.30.0

package/src/chart/ui/AxisGuide.tsx

@@ -0,0 +1,187 @@
+import type { ReactElement } from 'react';
+import { useMemo } from 'react';
+
+import type { PlotRect } from '../core/chartGeometry.ts';
+import type { ChartScale } from '../core/chartScale.ts';
+import { CHART_COLORS, CHART_FONT, LABEL_HALO } from '../core/chartTheme.ts';
+import type { GuidePlacement } from '../core/guidePlacement.ts';
+import { guidePlacement } from '../core/guidePlacement.ts';
+
+/** What the rule is drawn at, and what it says about itself. */
+export interface AxisGuideProps {
+  /**
+   * The place on the horizontal axis being pointed at, in whatever that axis
+   * measures, and `null` when nothing is being looked at.
+   */
+  value: number | null;
+  /** Where the plot sits inside the SVG. */
+  plot: PlotRect;
+  /** The horizontal axis as it is currently zoomed. */
+  xScale: ChartScale;
+  /**
+   * What the guide is drawn in.
+   * @default the theme's highlight colour
+   */
+  color?: string;
+  /**
+   * A few words written beside the rule, for a chart carrying more than one of
+   * them — `MS2 456.7`, `scan 314`. Nothing is written when it is absent, which
+   * is right for a chart whose single guide answers a hover the reader is
+   * already making.
+   * @default nothing is written
+   */
+  label?: string;
+}
+
+/**
+ * The vertical rule marking the place on the horizontal axis being looked at.
+ *
+ * A peak hovered in a table, a fragment hovered on a structure beside the chart,
+ * a search result rested on, the retention time whose scan is drawn in the pane
+ * below: each of them asks the chart the same question, and this is its whole
+ * answer. It sits below the viewers rather than inside one of them because a
+ * mass viewer's precursor rule and a chromatogram's time cursor are not two
+ * pictures that resemble each other — they are one picture, drawn from a value
+ * and a scale, and neither half of it can tell what it is measuring.
+ *
+ * When the value is inside the window the rule stands on it, solid. When it is
+ * not, the rule is parked on the edge the value went out of, dashed, and
+ * carries an arrow pointing that way. That is the case the component exists
+ * for: a chart zoomed onto one isotopologue cluster has almost everything a
+ * panel can point at outside its window, and answering with nothing drawn
+ * leaves a fragment the spectrum does not carry looking exactly like one that
+ * is two hundred mass units to the left. Dashed says *not here*, and the arrow
+ * says where to go.
+ *
+ * The arrow is a triangle rather than a `◀` glyph, because whether that
+ * character has one is the host's font's business and a missing one draws a
+ * hollow box in the middle of the chart. It sits just under the top edge, the
+ * strip of the plot a trace is least often in.
+ *
+ * Nothing here takes a pointer event: the guide is an answer, never a target.
+ * @param props - Component props.
+ * @returns The guide, or nothing when there is no value to point at and when
+ * the scale maps it nowhere.
+ */
+export function AxisGuide(props: AxisGuideProps): ReactElement | null {
+  const { value, plot, xScale, color = CHART_COLORS.highlight, label } = props;
+
+  const placement = value === null ? null : guidePlacement(value, plot, xScale);
+  const lineStyle = useMemo(() => ({ stroke: color }), [color]);
+  const arrowStyle = useMemo(() => ({ fill: color }), [color]);
+  const labelStyle = useMemo(
+    () => ({ fill: color, fontSize: CHART_FONT.label, ...LABEL_HALO }),
+    [color],
+  );
+
+  if (placement === null) return null;
+  const { x, direction } = placement;
+  const labelPlace = labelPlacement(placement, plot);
+
+  return (
+    <g pointerEvents="none">
+      <line
+        x1={x}
+        y1={plot.top}
+        x2={x}
+        y2={plot.bottom}
+        strokeWidth={GUIDE_WIDTH}
+        strokeDasharray={direction === null ? undefined : PARKED_DASH}
+        style={lineStyle}
+      />
+      {direction === null ? null : (
+        <path d={arrowPath({ x, direction }, plot)} style={arrowStyle} />
+      )}
+      {label === undefined ? null : (
+        <text
+          x={labelPlace.x}
+          y={plot.top + ARROW_TOP_INSET}
+          textAnchor={labelPlace.anchor}
+          dominantBaseline="central"
+          style={labelStyle}
+        >
+          {label}
+        </text>
+      )}
+    </g>
+  );
+}
+
+/** How thick the rule is: thin enough to read a peak beside, not through. */
+const GUIDE_WIDTH = 1.5;
+
+/** What a parked guide is dashed with. */
+const PARKED_DASH = '4 3';
+
+/** How far the arrow reaches back into the plot from its point. */
+const ARROW_LENGTH = 7;
+
+/** Half the width of its base. */
+const ARROW_HALF_HEIGHT = 5;
+
+/** How far below the top of the plot it sits. */
+const ARROW_TOP_INSET = 8;
+
+/** The clear space between the rule, or its arrow, and the label beside it. */
+const LABEL_GAP = 4;
+
+/**
+ * How much room a label is assumed to want.
+ *
+ * Measuring the text would mean rendering it first, which is a whole layout
+ * pass for a decision that only has to be right at the edges. Sixty pixels is
+ * about eight characters at the label size — `MS2 456.7` — and a label longer
+ * than that is one written for a panel rather than for a plot.
+ */
+const LABEL_ROOM = 60;
+
+/**
+ * The triangle a parked guide carries, pointing off the edge it is parked on.
+ *
+ * Only a parked guide has one, and the parameter says so rather than a guard
+ * inside: a guide standing on its own value has no edge to point at, and the
+ * caller has already told the two apart to decide whether to draw a path at all.
+ * @param placement - Where the guide is parked, and which edge its value lies past.
+ * @param plot - The plotting area, whose top the arrow hangs under.
+ * @returns The `d` of the triangle.
+ */
+function arrowPath(
+  placement: GuidePlacement & { direction: 'left' | 'right' },
+  plot: PlotRect,
+): string {
+  const { x, direction } = placement;
+  const back = direction === 'left' ? x + ARROW_LENGTH : x - ARROW_LENGTH;
+  const y = plot.top + ARROW_TOP_INSET;
+  return `M${x} ${y}L${back} ${y - ARROW_HALF_HEIGHT}L${back} ${y + ARROW_HALF_HEIGHT}Z`;
+}
+
+/**
+ * Which side of the rule the label is written on.
+ *
+ * It runs to the right and flips to the left as soon as it would otherwise
+ * cross the right edge — flipping rather than sliding, for the reason the
+ * pointer readout flips: a label pinned to the edge drifts away from the rule
+ * it belongs to and the pair stops reading as one thing. A guide parked on an
+ * edge has only one side that is inside the plot at all, so there the flip is
+ * forced, and the gap clears the arrow rather than the rule.
+ * @param placement - Where the guide ended up, and which way its value lies.
+ * @param plot - The plotting area the label has to stay inside.
+ * @returns The anchor, and which way the text runs from it.
+ */
+function labelPlacement(
+  placement: GuidePlacement,
+  plot: PlotRect,
+): { x: number; anchor: 'start' | 'end' } {
+  const { x, direction } = placement;
+  if (direction === 'left') {
+    return { x: x + ARROW_LENGTH + LABEL_GAP, anchor: 'start' };
+  }
+  if (direction === 'right') {
+    return { x: x - ARROW_LENGTH - LABEL_GAP, anchor: 'end' };
+  }
+  const runsRight = x + LABEL_GAP + LABEL_ROOM <= plot.right;
+  return {
+    x: runsRight ? x + LABEL_GAP : x - LABEL_GAP,
+    anchor: runsRight ? 'start' : 'end',
+  };
+}

package/src/chart/ui/ChartStack.tsx

@@ -0,0 +1,130 @@
+/**
+ * Charts stacked one above another, each resized by the splitter under it.
+ *
+ * One measurement is often read on more than one chart at once — the separation
+ * a sample was run through, the spectrum taken where the cursor stands, and what
+ * that spectrum broke into — and those are windows over different axes rather
+ * than traces on one. Stacking them is layout and nothing else, which is the
+ * whole of what this component knows: N panes, one above another, sharing the
+ * gutter their value axes are drawn in, the one at the foot writing the
+ * horizontal axis under all of them. Which pane holds what, and what makes one
+ * appear at all, is a fact about the measurement and stays in the viewer.
+ *
+ * How N panes become N nested splits is in `chartStackLevel.tsx`; what is held
+ * here is the one thing that outlives a render, which is how tall each of them
+ * was last left.
+ *
+ * Two things `SplitPane` does not do, and both of them draw a plausible wrong
+ * picture rather than failing outright:
+ *
+ * - **It has no minimum.** `useSplitPaneSize` clamps a drag to
+ *   `{ min: 0, max: parentDimension }`, so a splitter dragged to the top of the
+ *   stack leaves the pane above it at nothing at all; `plotRect` then holds the
+ *   plot at `MINIMUM_PLOT_SIDE` and what is left is a ten-pixel stub with a full
+ *   set of axes over it. Every height is held above the pane's own minimum —
+ *   the default it starts at as much as the one a drag arrives at — because
+ *   nothing underneath will do it.
+ * - **Its controlled side gets no `min-height: 0`.** `getItemStyle` resets that
+ *   on the *other* side only, and a chart is an `<svg>` carrying a real `height`
+ *   attribute, so the controlled pane's min-content height is whatever the
+ *   chart was last measured at: the pane grows and then refuses to shrink back.
+ *   Every pane is wrapped in a box that carries the reset itself.
+ *
+ * A pane keeps its children mounted whether it is open or shut — `unmountChildren`
+ * stays false — so a closed pane measures 0 × 0 behind a `display: none`, its
+ * `ResizeObserver` fires again the moment it is revealed, and it comes back
+ * through the window it was being looked at through. A remounted chart is empty.
+ */
+
+import type { ReactElement } from 'react';
+import { useCallback, useMemo, useState } from 'react';
+import type { SplitPaneSize } from 'react-science/ui';
+
+import type { ChartStackPane, StackLevel } from './chartStackLevel.tsx';
+import { keptHeight, paneHeight, stackFrom } from './chartStackLevel.tsx';
+
+export type { ChartStackPane } from './chartStackLevel.tsx';
+
+/** What the stack is drawn from. */
+export interface ChartStackProps {
+  /**
+   * The panes, in the order they are stacked, top to bottom.
+   *
+   * A pane with nothing to draw is left out of this array rather than handed in
+   * empty — that is what makes its splitter go away with it. Appending a pane,
+   * and dropping the one at the foot, cost nothing: every pane is a split
+   * whether or not anything follows it, so no chart already stacked is stood up
+   * again. Taking one out of the *middle* still is expensive — every split
+   * below it takes on the identity of the one that was under it, and the charts
+   * in them are all remounted, coming back fitted to what they draw rather than
+   * through the window they were left at. So a pane is still better dropped
+   * from the foot of the stack than out of its middle.
+   */
+  panes: readonly ChartStackPane[];
+  /**
+   * Told when a splitter is let go, with the height the pane came to rest at.
+   *
+   * On release rather than on every pixel of the drag, because a viewer that
+   * hears this puts it in its own state, and a store per pointer move renders
+   * every pane of the stack again on each one. The height reported is the one
+   * that was kept, minimum already applied.
+   * @default the height is remembered inside the stack and nowhere else
+   * @param id - Which pane was resized.
+   * @param height - How tall it now stands, in pixels.
+   */
+  onHeightChange?: (id: string, height: number) => void;
+}
+
+/**
+ * Stack charts vertically, with a splitter between each pair.
+ *
+ * Everything a level of the nesting is handed is memoised, and for the reason
+ * the release is told apart from the drag: `resize` fires on every pointer move,
+ * and a `StackLevel` rebuilt there would recurse through every `SplitPane` of
+ * the stack on each one, taking every chart in it with them.
+ * @param props - Component props.
+ * @returns The stack, filling the box it is given.
+ */
+export function ChartStack(props: ChartStackProps): ReactElement {
+  const { panes, onHeightChange } = props;
+  const [heights, setHeights] = useState<Readonly<Record<string, number>>>({});
+
+  const heightOf = useCallback(
+    (pane: ChartStackPane) => paneHeight(pane, heights[pane.id]),
+    [heights],
+  );
+
+  const resize = useCallback((pane: ChartStackPane, asked: SplitPaneSize) => {
+    const height = keptHeight(asked, pane);
+    if (height === null) return;
+    setHeights((current) =>
+      current[pane.id] === height ? current : { ...current, [pane.id]: height },
+    );
+  }, []);
+
+  const rest = useCallback(
+    (pane: ChartStackPane, asked: SplitPaneSize) => {
+      const height = keptHeight(asked, pane);
+      if (height !== null) onHeightChange?.(pane.id, height);
+    },
+    [onHeightChange],
+  );
+
+  const level = useMemo<StackLevel>(
+    () => ({ panes, heightOf, resize, rest }),
+    [panes, heightOf, resize, rest],
+  );
+
+  return <div style={stackStyle}>{stackFrom(level, 0)}</div>;
+}
+
+/** The box the whole stack fills, whatever it was given by way of a parent. */
+const stackStyle = {
+  display: 'flex',
+  flexDirection: 'column',
+  width: '100%',
+  height: '100%',
+  minWidth: 0,
+  minHeight: 0,
+  overflow: 'hidden',
+} as const;

package/src/chart/ui/ChartTracker.tsx

@@ -0,0 +1,101 @@
+/**
+ * The crosshair a chart follows the pointer with, and the lines it reads out.
+ *
+ * Every viewer draws the same two dashed rules and writes the same stack of
+ * short lines beside them; what differs is the words, which are the one thing
+ * only the viewer knows — an m/z and a height here, a retention time and a
+ * summed current there. So the geometry, the dashes and the placement live
+ * here, and the caller hands over the lines already written.
+ *
+ * The first line is the one being pointed at and is written plainly; the rest
+ * are quieter, because they answer the question the first one raises rather
+ * than being asked for in their own right.
+ */
+
+import type { ReactElement } from 'react';
+
+import type { PlotRect } from '../core/chartGeometry.ts';
+import {
+  CHART_COLORS,
+  CHART_FONT,
+  LABEL_HALO,
+  LABEL_QUIET,
+  PEAK_LABEL,
+} from '../core/chartTheme.ts';
+import type { ChartPoint } from '../core/svgPoint.ts';
+import { readoutPlacement } from '../core/trackerReadout.ts';
+
+/** What the tracker is given. */
+export interface ChartTrackerProps {
+  /** Where the pointer is, `null` whenever it is off the plot. */
+  position: ChartPoint | null;
+  /** Where the plot sits inside the SVG. */
+  plot: PlotRect;
+  /**
+   * What to write beside the crosshair, most important first, `null` where the
+   * axes read nothing under the pointer.
+   * @default null
+   */
+  lines?: readonly string[] | null;
+}
+
+/**
+ * Draw the crosshair and its readout.
+ * @param props - The pointer, the plot and the lines to write.
+ * @returns The crosshair, or nothing while the pointer is off the plot.
+ */
+export function ChartTracker(props: ChartTrackerProps): ReactElement | null {
+  const { position, plot, lines = null } = props;
+  if (position === null) return null;
+
+  const place = readoutPlacement(position, plot);
+
+  return (
+    <g pointerEvents="none">
+      <line
+        x1={position.x}
+        y1={plot.top}
+        x2={position.x}
+        y2={plot.bottom}
+        strokeDasharray={TRACKER_DASH}
+        style={crosshairStyle}
+      />
+      <line
+        x1={plot.left}
+        y1={position.y}
+        x2={plot.right}
+        y2={position.y}
+        strokeDasharray={TRACKER_DASH}
+        style={crosshairStyle}
+      />
+      {lines === null || lines.length === 0 ? null : (
+        <text textAnchor={place.anchor} style={readoutStyle}>
+          {lines.map((line, at) => (
+            <tspan
+              key={line}
+              x={place.x}
+              y={place.y + at * PEAK_LABEL.lineHeight}
+              fillOpacity={at === 0 ? undefined : LABEL_QUIET}
+            >
+              {line}
+            </tspan>
+          ))}
+        </text>
+      )}
+    </g>
+  );
+}
+
+/** What the crosshair is dashed with, so it is never read as a trace. */
+const TRACKER_DASH = '3 3';
+
+const crosshairStyle = { stroke: CHART_COLORS.tracker } as const;
+
+const readoutStyle = {
+  fill: CHART_COLORS.trackerText,
+  fontSize: CHART_FONT.readout,
+  // Haloed like every other label written onto the plot, and it needs it more
+  // than any of them: the pointer is put wherever the question is, which is over
+  // the trace rather than beside it.
+  ...LABEL_HALO,
+} as const;

package/src/chart/ui/PlotCaption.tsx

@@ -0,0 +1,108 @@
+import type { ReactElement } from 'react';
+
+import type { PlotRect } from '../core/chartGeometry.ts';
+import { CHART_COLORS, LABEL_HALO } from '../core/chartTheme.ts';
+import {
+  CHARACTER_WIDTH,
+  FONT_SIZE,
+  GAP,
+  MARGIN,
+  ROW_HEIGHT,
+} from '../core/legendBox.ts';
+
+/** What the caption says, and how much of the plot it may say it across. */
+export interface PlotCaptionProps {
+  /** What the plot is a picture of, in one line. */
+  text: string;
+  /** The plot it is written on. */
+  plot: PlotRect;
+  /**
+   * The x it must stop short of, in the plot's own pixels.
+   *
+   * The left edge of a legend sharing the top of the plot, which `legendBox`
+   * answers for whoever is drawing one. Nothing here works that out on its own:
+   * a caption is written wherever a caller asks and only the caller knows what
+   * else it put up there.
+   * @default the plot's right edge
+   */
+  until?: number;
+}
+
+/**
+ * What a plot is a picture of, written in its top left corner.
+ *
+ * The opposite corner from the legend, and it says the opposite kind of thing:
+ * a legend names the curves against each other, while a caption says which
+ * measurement the whole pane is of — which file, which acquisition of it, when
+ * it was measured. A stack of panes is where that matters, since three charts
+ * one above another are three pictures of three different scans and the axes
+ * say nothing about which.
+ *
+ * Drawn **inside the SVG**, for the reason `TraceLegend` states: a picture is
+ * exported by cloning the chart's own `SVGSVGElement`, so a caption living in a
+ * `<div>` beside it would be missing from every figure while looking perfectly
+ * right on screen — and a figure that does not say what it is a picture of is
+ * the one thing a caption exists to prevent.
+ *
+ * It is written on the plot rather than above it. The room over a plot belongs
+ * to the tallest peak's label, and taking it for a caption would either push
+ * the measurement down or have the two collide on whichever spectrum happens to
+ * peak at the left.
+ * @param props - Component props.
+ * @returns The caption, or nothing where there is no room to write it.
+ */
+export function PlotCaption(props: PlotCaptionProps): ReactElement | null {
+  const { text, plot, until } = props;
+
+  const said = elide(text, (until ?? plot.right) - GAP - plot.left - MARGIN);
+  if (said === '') return null;
+
+  return (
+    <text
+      x={plot.left + MARGIN}
+      y={plot.top + MARGIN + ROW_HEIGHT / 2}
+      fontSize={FONT_SIZE}
+      dominantBaseline="middle"
+      style={captionStyle}
+      pointerEvents="none"
+      aria-hidden="true"
+    >
+      {said}
+    </text>
+  );
+}
+
+/**
+ * The caption cut to the room it has, with an ellipsis where it was cut.
+ *
+ * Measured from character counts rather than from the DOM, for the reason
+ * `legendBox` gives: the text is decided during render, where a
+ * `getComputedTextLength` would need a layout pass that has not happened, and
+ * the clone an export takes gets no layout at all — so a caption that measured
+ * itself would come out one length on screen and another in the figure.
+ * @param text - What the pane would say.
+ * @param room - How wide it may be, in pixels.
+ * @returns What it says, or nothing where a caption would be a stub.
+ */
+function elide(text: string, room: number): string {
+  const fits = Math.floor(room / CHARACTER_WIDTH);
+  if (fits >= text.length) return text;
+  // A caption cut to three characters is not a caption, and a reader has to
+  // guess at what it was — better a pane that says nothing than one that
+  // appears to answer and does not.
+  if (fits < MINIMUM_CHARACTERS) return '';
+  return `${text.slice(0, fits - 1).trimEnd()}…`;
+}
+
+/** The shortest caption still worth writing, in characters. */
+const MINIMUM_CHARACTERS = 8;
+
+/**
+ * The face it is set in: the axis titles' ink, haloed like a peak label.
+ *
+ * The halo is what lets it be written straight onto the plot rather than in a
+ * box: a box in the top left would hide the very trace the pane is a picture
+ * of, while a hairline of paper around each glyph clears the letters and
+ * nothing else.
+ */
+const captionStyle = { fill: CHART_COLORS.title, ...LABEL_HALO } as const;

package/src/chart/ui/SelectionRect.tsx

@@ -0,0 +1,52 @@
+import type { ReactElement } from 'react';
+
+import type { PlotRect } from '../core/chartGeometry.ts';
+import { CHART_COLORS } from '../core/chartTheme.ts';
+import { selectionRectangle } from '../core/selectionGeometry.ts';
+import type { ZoomSelection } from '../core/zoomDomain.ts';
+
+export interface SelectionRectProps {
+  /** The drag being made, `null` when none is. */
+  selection: ZoomSelection | null;
+  /** Where the plot sits inside the SVG, which the drag is confined to. */
+  plot: PlotRect;
+}
+
+/**
+ * What the drag being made promises, drawn before the button is let go.
+ *
+ * It is painted over the data rather than under it, which is the one place a
+ * preview may cover a trace: a rectangle drawn behind a dense spectrum is a
+ * rectangle nobody sees, and the whole point of it is to be seen while the hand
+ * is still moving. The fill is faint enough for the peaks inside it to be read
+ * through, so the window being asked for can be judged against what is in it.
+ *
+ * Nothing here takes a pointer event: the drag is already captured on the SVG,
+ * and a rectangle that swallowed the pointer would end the very gesture it is
+ * drawing.
+ * @param props - Component props.
+ * @returns The rectangle, or nothing when no drag is being made and when the one
+ * being made is too short to zoom.
+ */
+export function SelectionRect(props: SelectionRectProps): ReactElement | null {
+  const { selection, plot } = props;
+
+  const rectangle = selectionRectangle(selection, plot);
+  if (rectangle === null) return null;
+
+  return (
+    <rect
+      x={rectangle.x}
+      y={rectangle.y}
+      width={rectangle.width}
+      height={rectangle.height}
+      pointerEvents="none"
+      style={selectionStyle}
+    />
+  );
+}
+
+const selectionStyle = {
+  fill: CHART_COLORS.selection,
+  stroke: CHART_COLORS.selectionBorder,
+} as const;