react-cheminfo 0.9.0 → 0.11.0

package/src/chart/ui/ChartTrackingLayer.tsx

@@ -0,0 +1,192 @@
+/**
+ * What a band chart draws: the series, the names under the slots, and the
+ * crosshair saying which slot is under the pointer. The names sit in an
+ * overlay because a frame clips its children to the plot, and a name goes
+ * under it.
+ */
+
+import type { CSSProperties, MouseEvent, ReactElement } from 'react';
+import { useRef } from 'react';
+
+import type { ChartAxisScale } from '../core/chartAxisScale.ts';
+import type { ChartBand } from '../core/chartBand.ts';
+import { chartBandCenter, chartBandIndexAt } from '../core/chartBand.ts';
+import type { ChartScale } from '../core/chartScale.ts';
+
+import { ChartAxis } from './ChartAxis.tsx';
+import type { ChartPlotArea } from './ChartFrame.tsx';
+import type { ChartSeries, ChartTrackEvent } from './TrackedLineChart.tsx';
+
+/** What {@link ChartTrackingLayer} needs. */
+export interface ChartTrackingLayerProps {
+  /** The rectangle the data is drawn in. */
+  plot: ChartPlotArea;
+  /** The slots the pointer is resolved against. */
+  band: ChartBand;
+  /** Data to pixels, vertically, which is where a marker sits. */
+  y: ChartScale;
+  /** One label per slot, in the slots' order. */
+  categories: readonly string[];
+  /** The visible series, in the order they are drawn. */
+  series: readonly ChartSeries[];
+  /** The slots that are named, thinned so the names cannot overlap. */
+  slotAxis: ChartAxisScale;
+  /** The slot the crosshair sits on, or `null` when nothing is tracked. */
+  index: number | null;
+  /** Called with the slot the pointer entered, and with nothing when it leaves. */
+  onTrack: (index: number | null, event: ChartTrackEvent | null) => void;
+  /**
+   * Called when a slot is clicked or committed with Enter.
+   * @default undefined
+   */
+  onSelect?: (index: number) => void;
+  /**
+   * What the horizontal axis measures, written under the names.
+   * @default undefined — the axis carries no title
+   */
+  title?: string;
+}
+
+/**
+ * The names of the slots, the crosshair, and the transparent rectangle that
+ * takes the pointer.
+ *
+ * The rectangle covers the whole plot rather than a hit area per point, which
+ * is what lets a finger track a spectrum: a two-pixel band cannot be aimed at,
+ * and the nearest slot to where the finger landed is what the reader meant. It
+ * lets every event through but its own, so a floating card stays clickable.
+ * @param props - See {@link ChartTrackingLayerProps}.
+ * @returns The layer.
+ */
+export function ChartTrackingLayer(
+  props: ChartTrackingLayerProps,
+): ReactElement {
+  const { plot, band, y, categories, series, index, onTrack, onSelect } = props;
+  const { slotAxis, title } = props;
+  const entered = useRef<number | null>(null);
+  const slot = index ?? -1;
+  const tracked = slot >= 0 && slot < band.count;
+  const at = tracked ? chartBandCenter(band, slot) : 0;
+  const crosshair = `M${at} ${plot.top}V${plot.bottom}`;
+
+  function report(found: number, x: number, pointer: number): void {
+    entered.current = found;
+    onTrack(found, {
+      index: found,
+      label: categories[found] ?? '',
+      x,
+      y: pointer,
+      values: series.map((item) => ({
+        id: item.id,
+        label: item.label,
+        value: item.values[found] ?? Number.NaN,
+        color: item.color,
+      })),
+    });
+  }
+
+  function move(event: MouseEvent<SVGRectElement>): void {
+    const box = event.currentTarget.getBoundingClientRect();
+    const across = box.width === 0 ? 1 : plot.width / box.width;
+    const down = box.height === 0 ? 1 : plot.height / box.height;
+    const x = plot.left + (event.clientX - box.left) * across;
+    const found = chartBandIndexAt(band, x);
+    if (found === -1 || found === entered.current) return;
+    const height = plot.top + (event.clientY - box.top) * down;
+    report(found, chartBandCenter(band, found), height);
+  }
+
+  function leave(): void {
+    if (entered.current === null) return;
+    entered.current = null;
+    onTrack(null, null);
+  }
+
+  function commit(): void {
+    if (entered.current !== null) onSelect?.(entered.current);
+  }
+
+  function keys(event: { key: string; preventDefault: () => void }): void {
+    if (event.key !== 'Enter' && event.key !== ' ') return;
+    event.preventDefault();
+    if (tracked) onSelect?.(slot);
+  }
+
+  return (
+    <svg width="100%" height="100%" style={LAYER_STYLE}>
+      <ChartAxis
+        orientation="bottom"
+        scale={slotAxis}
+        pixels={{ offset: band.offset, factor: band.step }}
+        plot={plot}
+        label={title}
+        layer="axis"
+        showGrid={false}
+      />
+      {tracked ? <path d={crosshair} style={CROSSHAIR_STYLE} /> : null}
+      {tracked ? markers(series, slot, at, y) : null}
+      <rect
+        x={plot.left}
+        y={plot.top}
+        width={plot.width}
+        height={plot.height}
+        fill="transparent"
+        style={SLIDER_STYLE}
+        tabIndex={0}
+        role="button"
+        aria-label={
+          tracked
+            ? `Measurement ${categories[slot]}`
+            : (title ?? 'Measurements')
+        }
+        onPointerDown={move}
+        onPointerMove={move}
+        onPointerLeave={leave}
+        onClick={commit}
+        onKeyDown={keys}
+      />
+    </svg>
+  );
+}
+
+function markers(
+  series: readonly ChartSeries[],
+  slot: number,
+  at: number,
+  y: ChartScale,
+): ReactElement {
+  const dots: ReactElement[] = [];
+  for (const item of series) {
+    const value = item.values[slot];
+    if (value === undefined || !Number.isFinite(value)) continue;
+    const cy = round(y.offset + value * y.factor);
+    dots.push(
+      <circle key={item.id} cx={at} cy={cy} r={3.5} fill={item.color} />,
+    );
+  }
+  return (
+    <g stroke="var(--surface)" strokeWidth={1.5}>
+      {dots}
+    </g>
+  );
+}
+
+const LAYER_STYLE = {
+  position: 'absolute',
+  inset: 0,
+  pointerEvents: 'none',
+} as const satisfies CSSProperties;
+
+const SLIDER_STYLE = {
+  pointerEvents: 'auto',
+  touchAction: 'none',
+  cursor: 'crosshair',
+} as const satisfies CSSProperties;
+
+const CROSSHAIR_STYLE = {
+  stroke: 'var(--border-strong)',
+  strokeWidth: 1,
+  strokeDasharray: '3 3',
+} as const satisfies CSSProperties;
+
+const round = (value: number): number => Math.round(value * 100) / 100;

package/src/chart/ui/TrackedLineChart.tsx

@@ -0,0 +1,267 @@
+import type { ReactElement, ReactNode } from 'react';
+import { useState } from 'react';
+
+import type { ChartAxisScale } from '../core/chartAxisScale.ts';
+import { chartAxisScale } from '../core/chartAxisScale.ts';
+import type { ChartBand } from '../core/chartBand.ts';
+import { chartBand } from '../core/chartBand.ts';
+import {
+  EMPTY_EXTENT,
+  chartPadExtent,
+  chartValuesExtent,
+} from '../core/chartExtent.ts';
+import { chartScale } from '../core/chartScale.ts';
+
+import type { ChartAxisSpec } from './ChartFrame.tsx';
+import { ChartFrame } from './ChartFrame.tsx';
+import { ChartSeriesMarks } from './ChartSeriesMarks.tsx';
+import { ChartTrackingLayer } from './ChartTrackingLayer.tsx';
+import { chartOuterRoom, chartPlotArea } from './chartStyles.ts';
+
+/** Whether a series is drawn as a line or as bars from the zero line. */
+export type ChartSeriesKind = 'line' | 'bar';
+
+/** One line or one set of bars. */
+export interface ChartSeries {
+  /** A stable id, used as the React key and named in the tracking callback. */
+  id: string;
+  /** What the legend calls it, e.g. `PC 1`. */
+  label: string;
+  /** One value per slot, in the slots' order. */
+  values: ArrayLike<number>;
+  /** Its colour, normally from `chartSeriesColor`. */
+  color: string;
+  /**
+   * Whether it is drawn as a line or as bars.
+   * @default 'line'
+   */
+  kind?: ChartSeriesKind;
+  /**
+   * Whether it is drawn at all — what a legend entry switches.
+   * @default true
+   */
+  visible?: boolean;
+  /**
+   * Whether it is drawn faintly behind the rest, which is what the average
+   * sample is in every loadings panel.
+   * @default false
+   */
+  muted?: boolean;
+}
+
+/** Where the pointer is, and what stands under it. */
+export interface ChartTrackEvent {
+  /** Which slot, from 0. */
+  index: number;
+  /** What that slot is called. */
+  label: string;
+  /** The middle of the slot, in pixels from the wrapper's left. */
+  x: number;
+  /** The pointer's own vertical position, in pixels from the wrapper's top. */
+  y: number;
+  /** Every visible series' value there, in the order they are drawn. */
+  values: ReadonlyArray<{
+    /** The series' id. */
+    id: string;
+    /** What it is called. */
+    label: string;
+    /** Its value at this slot. */
+    value: number;
+    /** Its colour. */
+    color: string;
+  }>;
+}
+
+/** What {@link TrackedLineChart} needs. */
+export interface TrackedLineChartProps {
+  /** One label per slot along the horizontal axis. */
+  categories: readonly string[];
+  /** The series to draw. */
+  series: readonly ChartSeries[];
+  /** Total width, from `useContainerSize`. */
+  width: number;
+  /** Total height. */
+  height: number;
+  /**
+   * The vertical axis. Its domain is read from the visible series when it is
+   * left out, and includes zero whenever any series is drawn as bars.
+   * @default undefined
+   */
+  y?: Partial<ChartAxisSpec>;
+  /**
+   * The horizontal axis title, e.g. `Measurement` or `Wavenumber (cm⁻¹)`.
+   * @default undefined
+   */
+  xLabel?: string;
+  /**
+   * The slot the crosshair sits on, for a parent driving it from elsewhere —
+   * a hovered row of a table beside the chart. Left out, the chart keeps its
+   * own.
+   * @default undefined
+   */
+  trackedIndex?: number | null;
+  /**
+   * Called as the pointer moves across the plot, and with `null` when it
+   * leaves. It fires only when the slot under the pointer changes, but that is
+   * still every few pixels, so a caller doing real work should hold the value
+   * in a ref rather than in state.
+   * @default undefined
+   */
+  onTrack?: (event: ChartTrackEvent | null) => void;
+  /**
+   * Called when a slot is clicked or committed with Enter, for a caller that
+   * wants a measurement pinned rather than hovered.
+   * @default undefined
+   */
+  onSelect?: (index: number) => void;
+  /**
+   * What floats over the chart, normally an `OverlayBar`.
+   * @default undefined
+   */
+  overlay?: ReactNode;
+  /**
+   * What the axis writes under the slots it labels, one per slot. A number
+   * line hands in rounded values here — `879 cm⁻¹` — while `categories` goes
+   * on naming a slot in whatever the caller measured.
+   * @default undefined — the axis writes the categories themselves
+   */
+  tickLabels?: readonly string[];
+  /**
+   * The most slot labels to write. Past it every nth is written so the labels
+   * never overlap; the ticks themselves stay.
+   * @default 24
+   */
+  maxTickLabels?: number;
+  /**
+   * What a screen reader is told the chart shows.
+   * @default ''
+   */
+  label?: string;
+  /**
+   * Value of the `data-testid` attribute of the wrapper.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * A chart of one or more series over a shared list of measurements, with a
+ * crosshair that reports what stands under the pointer.
+ *
+ * The horizontal axis is a band rather than a number line, so finding the slot
+ * under the pointer is one division instead of a search, and the same
+ * component draws a spectrum as a line and a table's columns as bars.
+ * @param props - See {@link TrackedLineChartProps}.
+ * @returns The chart.
+ */
+export function TrackedLineChart(props: TrackedLineChartProps): ReactElement {
+  const { categories, series, width, height, y, trackedIndex, xLabel } = props;
+  const { onTrack, onSelect, overlay, label, testId, maxTickLabels } = props;
+  const { tickLabels = categories } = props;
+  const [ownIndex, setOwnIndex] = useState<number | null>(null);
+  const drawn = series
+    .filter((item) => item.visible !== false)
+    .toSorted((a, b) => Number(b.muted === true) - Number(a.muted === true));
+  const slots = Math.max(1, categories.length);
+  const domain = y?.domain ?? seriesDomain(drawn, categories.length);
+  const nicing = { count: y?.tickCount, nice: y?.nice };
+  const ticks = chartAxisScale(domain[0], domain[1], nicing);
+  const under: ChartAxisSpec = { domain: [0, slots], label: xLabel };
+  const margins = {
+    bottom: chartOuterRoom('bottom', under, { ...ticks, exponent: 0 }),
+    left: chartOuterRoom('left', { ...y, domain }, ticks),
+  };
+  const plot = chartPlotArea(width, height, margins, margins);
+  const band = chartBand(categories.length, plot.left, plot.right);
+  const [low, high] = ticks.domain;
+
+  function track(slot: number | null, event: ChartTrackEvent | null): void {
+    if (trackedIndex === undefined) setOwnIndex(slot);
+    onTrack?.(event);
+  }
+
+  return (
+    <ChartFrame
+      width={width}
+      height={height}
+      margins={margins}
+      label={label}
+      testId={testId}
+      x={{ domain: [0, slots], showTicks: false, showGrid: false, nice: false }}
+      y={{ ...y, domain }}
+      overlay={
+        <>
+          <ChartTrackingLayer
+            plot={plot}
+            band={band}
+            y={chartScale(low, high, plot.bottom, plot.top)}
+            categories={categories}
+            series={drawn}
+            index={trackedIndex === undefined ? ownIndex : trackedIndex}
+            slotAxis={slotTicks(tickLabels, band, maxTickLabels ?? 24)}
+            title={xLabel}
+            onTrack={track}
+            onSelect={onSelect}
+          />
+          {overlay}
+        </>
+      }
+    >
+      {(frame) => {
+        // Only the bars share a slot; a line is drawn across the whole of it.
+        let bars = 0;
+        for (const item of drawn) if (item.kind === 'bar') bars++;
+        let lane = 0;
+        return drawn.map((item) => (
+          <ChartSeriesMarks
+            key={item.id}
+            item={item}
+            band={band}
+            y={frame.y}
+            lane={
+              item.kind === 'bar'
+                ? { index: lane++, count: bars }
+                : { index: 0, count: 1 }
+            }
+          />
+        ));
+      }}
+    </ChartFrame>
+  );
+}
+
+function seriesDomain(drawn: readonly ChartSeries[], slots: number) {
+  let extent = EMPTY_EXTENT;
+  let grounded = false;
+  for (const item of drawn) {
+    if (item.kind === 'bar') grounded = true;
+    extent = chartValuesExtent(item.values, { limit: slots, into: extent });
+  }
+  const range = chartPadExtent(extent);
+  if (!grounded) return [range.min, range.max] as const;
+  return [Math.min(range.min, 0), Math.max(range.max, 0)] as const;
+}
+
+function slotTicks(
+  categories: readonly string[],
+  band: ChartBand,
+  maxLabels: number,
+): ChartAxisScale {
+  let longest = 1;
+  for (const text of categories) longest = Math.max(longest, text.length);
+  const room = Math.max(1, band.step);
+  const wide = Math.ceil((longest * LABEL_ROOM + LABEL_GAP) / room);
+  const many = Math.ceil(categories.length / Math.max(1, maxLabels));
+  const stride = Math.max(1, wide, many);
+  const values: number[] = [];
+  const labels: string[] = [];
+  for (let index = 0; index < categories.length; index += stride) {
+    values.push(index + 0.5);
+    labels.push(categories[index] ?? '');
+  }
+  const domain = [0, Math.max(1, band.count)] as const;
+  return { domain, values, labels, step: stride, decimals: 0, exponent: 0 };
+}
+
+const LABEL_ROOM = 6.5;
+const LABEL_GAP = 10;

package/src/chart/ui/TrackedStickChart.tsx

@@ -0,0 +1,197 @@
+/**
+ * A peak list drawn as the sticks it is, on a real number line.
+ *
+ * `TrackedLineChart` lays every measurement in a slot of its own and joins
+ * them, which is right for a spectrum that was sampled on a grid and wrong for
+ * one that was picked off it. A peak list has gaps, and the gaps are a
+ * measurement: an empty stretch between m/z 526 and 725 drawn as wide as the
+ * step from 206 to 252 says the run is crowded where it is bare, and a line
+ * across it claims a signal at every mass in between. So the horizontal axis
+ * here is the frame's own — niced ticks over the values themselves — and a
+ * measurement is a stick standing where it was measured.
+ *
+ * A series is one `<path>` whatever its length. Ten thousand peaks are ten
+ * thousand move-and-line pairs in one `d`, which paints as one node; ten
+ * thousand elements would not survive the pointer. The same reasoning as the
+ * pair grid's dots, and the reason a peak list of any size can be drawn here.
+ *
+ * The pointer is answered from one transparent rectangle over the plot rather
+ * than from a hit area per stick, so a finger lands on the nearest peak rather
+ * than having to hit a one-pixel line. Nearest is found by bisecting the
+ * positions, which is what makes it independent of how many there are.
+ */
+
+import type { CSSProperties, MouseEvent, ReactElement, ReactNode } from 'react';
+import { useState } from 'react';
+
+import type { ChartAxisSpec, ChartFrameRender } from './ChartFrame.tsx';
+import { ChartFrame } from './ChartFrame.tsx';
+import type { ChartTrackEvent } from './TrackedLineChart.tsx';
+import type { ChartStickSeries } from './stickChartModel.ts';
+import {
+  nearestPosition,
+  seriesDomain,
+  spanOf,
+  stickPath,
+  valueAt,
+} from './stickChartModel.ts';
+
+export type { ChartStickSeries } from './stickChartModel.ts';
+
+/** What {@link TrackedStickChart} needs. */
+export interface TrackedStickChartProps {
+  /**
+   * Where each measurement sits, ascending, in the series' own order. It must
+   * ascend: the peak under the pointer is found by bisecting it.
+   */
+  positions: readonly number[];
+  /** One label per measurement, for the readout. */
+  categories: readonly string[];
+  /** The series to draw. */
+  series: readonly ChartStickSeries[];
+  /** Total width, from `useContainerSize`. */
+  width: number;
+  /** Total height. */
+  height: number;
+  /**
+   * The vertical axis. Its domain is read from the visible series when it is
+   * left out, and always includes zero, since a stick is read from there.
+   * @default undefined
+   */
+  y?: Partial<ChartAxisSpec>;
+  /**
+   * The horizontal axis title, e.g. `m/z`.
+   * @default undefined
+   */
+  xLabel?: string;
+  /**
+   * Which measurement the crosshair sits on. Present, the caller owns it,
+   * which is how a stack of panels shows one rule across all of them.
+   * @default undefined — the chart keeps its own
+   */
+  trackedIndex?: number | null;
+  /**
+   * Called with the measurement the pointer entered, and with `null` when it
+   * leaves.
+   * @default undefined
+   */
+  onTrack?: (event: ChartTrackEvent | null) => void;
+  /**
+   * What a screen reader is told the chart shows.
+   * @default '' — the chart is hidden from a screen reader
+   */
+  label?: string;
+  /**
+   * What floats over the chart in HTML.
+   * @default undefined
+   */
+  overlay?: ReactNode;
+  /**
+   * Value of the `data-testid` attribute of the wrapper.
+   * @default undefined
+   */
+  testId?: string;
+}
+
+/**
+ * Draw a peak list, and say which peak the pointer is on.
+ * @param props - See {@link TrackedStickChartProps}.
+ * @returns The chart.
+ */
+export function TrackedStickChart(props: TrackedStickChartProps): ReactElement {
+  const { positions, categories, series, width, height, y, xLabel } = props;
+  const { onTrack, label, overlay, testId, trackedIndex } = props;
+  const [ownIndex, setOwnIndex] = useState<number | null>(null);
+  const held = trackedIndex === undefined ? ownIndex : trackedIndex;
+
+  const drawn = series
+    .filter((item) => item.visible !== false)
+    .toSorted((a, b) => Number(b.muted === true) - Number(a.muted === true));
+  const across = spanOf(positions);
+  const domain = y?.domain ?? seriesDomain(drawn, positions.length);
+
+  function report(frame: ChartFrameRender, event: MouseEvent<SVGRectElement>) {
+    const { plot, x } = frame;
+    const box = event.currentTarget.getBoundingClientRect();
+    const scaleX = box.width === 0 ? 1 : plot.width / box.width;
+    const scaleY = box.height === 0 ? 1 : plot.height / box.height;
+    const pixel = plot.left + (event.clientX - box.left) * scaleX;
+    const found = nearestPosition(positions, valueAt(x, pixel));
+    if (found === -1) return;
+    if (trackedIndex === undefined) setOwnIndex(found);
+    onTrack?.({
+      index: found,
+      label: categories[found] ?? '',
+      x: x.offset + (positions[found] as number) * x.factor,
+      y: plot.top + (event.clientY - box.top) * scaleY,
+      values: drawn.map((item) => ({
+        id: item.id,
+        label: item.label,
+        value: item.values[found] ?? Number.NaN,
+        color: item.color,
+      })),
+    });
+  }
+
+  function leave(): void {
+    if (trackedIndex === undefined) setOwnIndex(null);
+    onTrack?.(null);
+  }
+
+  return (
+    <ChartFrame
+      width={width}
+      height={height}
+      label={label}
+      testId={testId}
+      overlay={overlay}
+      x={{ domain: across, label: xLabel, showGrid: false }}
+      y={{ ...y, domain }}
+    >
+      {(frame) => (
+        <>
+          {drawn.map((item) => (
+            <path
+              key={item.id}
+              data-series={item.id}
+              d={stickPath(item, positions, frame)}
+              fill="none"
+              stroke={item.color}
+              strokeWidth={item.muted === true ? 1 : 1.5}
+              strokeOpacity={item.muted === true ? 0.55 : 1}
+              strokeLinecap="butt"
+            />
+          ))}
+          {held === null || positions[held] === undefined ? null : (
+            <path
+              data-chart-rule="tracked"
+              d={`M${frame.x.offset + positions[held] * frame.x.factor} ${frame.plot.top}V${frame.plot.bottom}`}
+              stroke="var(--text-faint)"
+              strokeDasharray="3 3"
+              shapeRendering="crispEdges"
+            />
+          )}
+          <rect
+            x={frame.plot.left}
+            y={frame.plot.top}
+            width={frame.plot.width}
+            height={frame.plot.height}
+            fill="transparent"
+            style={SURFACE_STYLE}
+            aria-label={xLabel}
+            onMouseMove={(event) => {
+              report(frame, event);
+            }}
+            onMouseLeave={leave}
+          />
+        </>
+      )}
+    </ChartFrame>
+  );
+}
+
+const SURFACE_STYLE = {
+  pointerEvents: 'auto',
+  touchAction: 'none',
+  cursor: 'crosshair',
+} as const satisfies CSSProperties;