react-cheminfo 0.27.0 → 0.29.0

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;

package/src/chart/ui/TraceLegend.tsx

@@ -0,0 +1,193 @@
+import type { ReactElement } from 'react';
+
+import { TOKEN } from '../../tokens/core/familyTokens.ts';
+import type { PlotRect } from '../core/chartGeometry.ts';
+import {
+  CLOSE_COLUMN,
+  FONT_SIZE,
+  GAP,
+  PADDING,
+  ROW_HEIGHT,
+  SWATCH,
+  hiddenLabel,
+  legendBox,
+  legendLabel,
+  legendNames,
+} from '../core/legendBox.ts';
+
+/** One trace the legend names. */
+export interface LegendEntry {
+  /** Identity, which is what the list is keyed on. */
+  id: string;
+  /** What it is called. */
+  name: string;
+  /** The colour it is drawn in. */
+  color: string;
+  /**
+   * Whether it is drawn solid or faint — a trace that is present but not the
+   * one being read.
+   * @default false
+   */
+  dimmed?: boolean;
+  /**
+   * A 1-based number written before the name.
+   *
+   * The palette hands out six hues and `nextSpectrumColor` deliberately falls
+   * back to the least-used one rather than reaching for a colour only some
+   * readers can place, so the seventh trace legitimately repeats a colour and
+   * the legend stops being able to tell two rows apart by swatch alone. A
+   * number tells them apart at twelve traces and at thirty, survives a
+   * monochrome print, and survives a trace too short to show its colour
+   * clearly — the row then reads `3 · x 132, y 88`.
+   * @default undefined
+   */
+  index?: number;
+  /**
+   * A short remark written at the right of the row, in grey.
+   * @default undefined
+   */
+  note?: string;
+}
+
+export interface TraceLegendProps {
+  /** The traces, in the order they are drawn. */
+  entries: readonly LegendEntry[];
+  /** The plot the legend sits inside. */
+  plot: PlotRect;
+  /**
+   * How many entries are named before the rest are counted instead.
+   *
+   * A legend taller than the plot is a legend that hides the measurement it is
+   * explaining, which is the failure a scrollbar in a legend admits to. Past
+   * this many the last line reads `+ 4 more`.
+   * @default 8
+   */
+  limit?: number;
+  /**
+   * How few named traces are still worth a legend.
+   *
+   * Two is right for a chart standing on its own: the axis title already says
+   * what the single curve is, so a box naming the only trace is furniture. It
+   * is wrong for a pane of a stack, where the panes share their axes and the
+   * legend is the only thing saying which measurement this one is of — there a
+   * single name is the whole point, and the pane passes 1.
+   * @default 2
+   */
+  minimumEntries?: number;
+  /**
+   * Whether a column is left at the right of every row for a control.
+   *
+   * The picture never draws that control — a cross drawn here would be cloned
+   * into every exported figure as a dead glyph, and a press on the SVG root is
+   * read as the start of a chart gesture — but it has to leave the room for it,
+   * or the box painted behind the rows comes out narrower than the rows an HTML
+   * layer places over it and every cross hangs off the end of the legend.
+   * @default false
+   */
+  closable?: boolean;
+}
+
+/**
+ * What each curve on a chart is, written in the top right of the plot.
+ *
+ * Drawn **inside the SVG** and never as HTML beside it, which is not a style
+ * choice: `stackDrawings` exports a picture by cloning the chart's own
+ * `SVGSVGElement`, so a legend living in a `<div>` would be missing from every
+ * exported figure while looking perfectly correct on screen — a picture that is
+ * wrong only once it leaves the application is the worst kind to ship.
+ *
+ * Top right because that is where a chromatogram has room: a trace rises from
+ * the baseline and the tallest peak is rarely at the right-hand edge. It is
+ * drawn over the plot rather than in a gutter beside it so that adding a legend
+ * does not narrow the measurement.
+ *
+ * Where it sits and how tall it is comes from `legendBox` rather than from
+ * arithmetic of its own, because a legend whose rows carry an interactive
+ * control is drawn a second time in HTML over this one, and two owners of a row
+ * position is a cross that drifts off the name it closes.
+ *
+ * A trace with no name is not given one here. An unnamed curve in a legend is a
+ * row of colour and nothing else, which is worse than being left out, and the
+ * caller knows what it drew.
+ * @param props - Component props.
+ * @returns The legend, or nothing when there are too few traces to name.
+ */
+export function TraceLegend(props: TraceLegendProps): ReactElement | null {
+  const {
+    entries,
+    plot,
+    limit = 8,
+    minimumEntries = 2,
+    closable = false,
+  } = props;
+  const named = legendNames(entries, minimumEntries);
+  if (named.length === 0) return null;
+
+  // The very options the control layer measures with, or the two disagree by
+  // exactly the width of the column a cross stands in.
+  const box = legendBox(named, plot, { limit, closable });
+  const noteX = box.left + box.width - PADDING - (closable ? CLOSE_COLUMN : 0);
+
+  return (
+    <g aria-hidden="true" pointerEvents="none">
+      <rect
+        x={box.left}
+        y={box.top}
+        width={box.width}
+        height={box.height}
+        rx={3}
+        fill="rgb(255 255 255 / 82%)"
+        stroke="rgb(217 223 230)"
+        strokeWidth={0.5}
+      />
+      {box.rows.map((row, index) => {
+        const entry = named[index];
+        if (entry === undefined) return null;
+        return (
+          <g key={row.id} opacity={entry.dimmed === true ? 0.45 : 1}>
+            <line
+              x1={box.left + PADDING}
+              x2={box.left + PADDING + SWATCH}
+              y1={row.middle}
+              y2={row.middle}
+              stroke={entry.color}
+              strokeWidth={2}
+            />
+            <text
+              x={box.left + PADDING + SWATCH + GAP}
+              y={row.middle}
+              fontSize={FONT_SIZE}
+              dominantBaseline="middle"
+              fill="rgb(28 33 39)"
+            >
+              {legendLabel(entry)}
+            </text>
+            {entry.note !== undefined && (
+              <text
+                x={noteX}
+                y={row.middle}
+                fontSize={FONT_SIZE}
+                dominantBaseline="middle"
+                textAnchor="end"
+                fill={TOKEN.textMuted}
+              >
+                {entry.note}
+              </text>
+            )}
+          </g>
+        );
+      })}
+      {box.hidden > 0 && (
+        <text
+          x={box.left + PADDING + SWATCH + GAP}
+          y={box.top + box.height - PADDING - ROW_HEIGHT / 2}
+          fontSize={FONT_SIZE}
+          dominantBaseline="middle"
+          fill={TOKEN.textMuted}
+        >
+          {hiddenLabel(box.hidden)}
+        </text>
+      )}
+    </g>
+  );
+}