react-cheminfo 0.28.0 → 0.29.0

package/src/chart/ui/chartGestures.ts

@@ -0,0 +1,270 @@
+/**
+ * A press on a chart, and what letting go of it answers.
+ *
+ * `useChartZoom` holds the React state — the window on screen, and the drag
+ * being made across it — and this holds the arithmetic that turns a release into
+ * an answer: a window to show, a range to report, a click to report, or nothing
+ * at all. Keeping the two apart is what lets the answer be tested without a
+ * renderer, which is how `zoomedDomain` beside it has always been read, and it
+ * is why this sits next to that file rather than inside the hook.
+ *
+ * The three things a host can be told about are here for the same reason. Only
+ * one of the four answers moves the window; the other three leave the chart
+ * exactly where it was, and deciding between them in one place is what stops a
+ * gesture reporting a range and a click for the same drag.
+ */
+
+import type { PointerEvent as ReactPointerEvent } from 'react';
+
+import type { ChartDomain, ZoomRules } from '../core/chartDomain.ts';
+import type { PlotRect } from '../core/chartGeometry.ts';
+import type { ChartScale } from '../core/chartScale.ts';
+import { chartValue } from '../core/chartScale.ts';
+import type { ChartPoint } from '../core/svgPoint.ts';
+import { svgPointAt } from '../core/svgPoint.ts';
+import type { DragBox } from '../core/zoomDomain.ts';
+import { MINIMUM_DRAG, zoomedDomain } from '../core/zoomDomain.ts';
+
+import { isInsidePlot } from './useChartPointer.ts';
+
+/** One gesture on the SVG, as React hands it over. */
+type PointerHandler = (event: ReactPointerEvent<SVGSVGElement>) => void;
+
+/**
+ * Which keys were held as a click was let go.
+ *
+ * Reported rather than interpreted, because what a modifier *means* is a
+ * question about the measurement and not about the gesture layer: on a mass
+ * spectrum a held shift asks for the peak to be watched for, and on an infrared
+ * one it will mean something else entirely. The chart says which keys were
+ * down; whoever knows what is being measured decides what that asks for.
+ */
+export interface ChartClickModifiers {
+  /** Whether shift was held. */
+  shift: boolean;
+  /** Whether alt — option on a Mac — was held. */
+  alt: boolean;
+}
+
+/** No key held, which is what a plain click reports. */
+export const NO_MODIFIERS: ChartClickModifiers = { shift: false, alt: false };
+
+/** What to spread onto the SVG for it to be zoomed. */
+export interface ChartZoomHandlers {
+  onPointerDown: PointerHandler;
+  onPointerMove: PointerHandler;
+  onPointerUp: PointerHandler;
+  onPointerCancel: PointerHandler;
+  onDoubleClick: () => void;
+}
+
+/** What a host asks to be told, beyond the window it is shown anyway. */
+export interface ChartGestureReports {
+  /**
+   * What to do with the two values a `select` drag swept out, in the units of
+   * the horizontal axis and stated low end first.
+   *
+   * The window is left exactly where it was: the gesture asked where a peak
+   * begins and ends, not to look closer at it, and a chart that zoomed to the
+   * boundaries as they were set would take the neighbouring peaks off the screen
+   * every time. The ends are sorted before anyone is told, because a drag made
+   * right to left is as ordinary as one made left to right and an axis drawn
+   * right to left inverts them again — a range of `[2.9, 2.4]` minutes
+   * integrates nothing.
+   * @default nothing is reported, and a select drag then does nothing at all
+   */
+  onSelectRange?: (range: [number, number]) => void;
+  /**
+   * What to do with a press that went nowhere, in the units the chart is
+   * measured in — an m/z, a wavenumber, a retention time and a value.
+   *
+   * Nowhere means nowhere on **either** axis: a press is a click when it
+   * travelled less than `MINIMUM_DRAG` across and less than `MINIMUM_DRAG` down.
+   * Only the horizontal travel decides whether there is a window to zoom to, so
+   * a drag of one pixel across and three hundred down asks for no window — but
+   * it is plainly a gesture that was made, and calling it a press that went
+   * nowhere would put a scan on the chart nobody pointed at.
+   *
+   * A `select` drag is never reported here at all. Its answer is a range or it
+   * is nothing, and a near-vertical integration drag that moved the cursor
+   * instead would be answering a question the chemist did not ask.
+   *
+   * There is no other way to be told about a click: hovering is a different
+   * question, answered continuously and by every tremor of a hand resting on the
+   * chart, and choosing the scan at 2.500 minutes is a decision made by pressing.
+   * Only a press let go over the plot is reported — the gestures are heard on the
+   * whole SVG, so the axis titles and the tick labels are under them too, and a
+   * click on the word `m/z` inverted through the scales lands at a value the
+   * chart is not even drawing.
+   * @default nothing is reported
+   */
+  onClick?: (point: ChartPoint, modifiers: ChartClickModifiers) => void;
+  /**
+   * Whether a press at this point of the SVG, in its own user units, begins a
+   * drag at all.
+   *
+   * In pixels rather than in data units because that is the question being
+   * asked: whatever else is drawn on the chart — an integration boundary to be
+   * taken hold of, a cursor to be slid — was placed in pixels, and `isInsidePlot`
+   * is here for exactly this. Refusing means the press is never captured, so it
+   * reaches whatever is under it and that thing keeps the rest of the gesture;
+   * captured first and refused afterwards, the handle would never see the move
+   * events that drag it.
+   * @default every press over the SVG begins a drag
+   */
+  shouldStartDrag?: (point: ChartPoint) => boolean;
+}
+
+/** A drag as it is held, tied to the pointer that started it. */
+export interface Drag extends DragBox {
+  /** So a second finger cannot take a drag over from the first. */
+  pointerId: number;
+}
+
+/**
+ * What letting go of a drag comes to, told to the host on the way.
+ *
+ * One reading of the gesture answers all four outcomes, so what a select drag
+ * reports and what a zoom would have shown can never drift apart: the clamping
+ * to the plot, the `MINIMUM_DRAG` test and the sorting after inverting are done
+ * once, in `zoomedDomain`.
+ * @param current - The window in force, kept on the axis that is not asked for.
+ * @param released - The two corners as the button came up, in user units.
+ * @param plot - Where the plot sits inside the SVG.
+ * @param xScale - The x axis as the chart is currently zoomed.
+ * @param yScale - The y axis, likewise.
+ * @param rules - How the y axis behaves and what a drag means.
+ * @param reports - What the host asked to be told.
+ * @param modifiers
+ * @returns The window to show, `null` when the chart stays where it is.
+ */
+export function answeredRelease(
+  current: ChartDomain,
+  released: DragBox,
+  plot: PlotRect,
+  xScale: ChartScale,
+  yScale: ChartScale,
+  rules: ZoomRules,
+  reports: ChartGestureReports,
+  modifiers: ChartClickModifiers = NO_MODIFIERS,
+): ChartDomain | null {
+  const mode = rules.drag ?? 'xAxis';
+  const next = zoomedDomain(current, released, plot, xScale, yScale, rules);
+  if (next === null) {
+    if (mode !== 'select') {
+      reportClick(released, plot, xScale, yScale, reports.onClick, modifiers);
+    }
+    return null;
+  }
+  if (mode === 'select') {
+    reports.onSelectRange?.(next.x);
+    return null;
+  }
+  return next;
+}
+
+/**
+ * The drag a press begins, `null` for a press that begins none.
+ *
+ * The host is asked before the pointer is captured rather than after it: a press
+ * taken from whatever it landed on cannot be handed back mid-gesture, so an
+ * integration boundary or a cursor drawn on the chart would never see the moves
+ * that drag it.
+ * @param event - The press.
+ * @param svg - The SVG it was made on, which is what places it in user units.
+ * @param shouldStartDrag - Whether the host lets the chart have it, absent when
+ * every press over the SVG is the chart's.
+ * @returns The drag, `null` when the press was not the chart's to take or the
+ * SVG cannot place the pointer.
+ */
+export function startedDrag(
+  event: ReactPointerEvent<SVGSVGElement>,
+  svg: SVGSVGElement | null,
+  shouldStartDrag: ((point: ChartPoint) => boolean) | undefined,
+): Drag | null {
+  if (event.button !== LEFT_BUTTON) return null;
+  const point = svgPointAt(svg, event.clientX, event.clientY);
+  if (point === null) return null;
+  if (shouldStartDrag !== undefined && !shouldStartDrag(point)) return null;
+  // Captured so a drag running off the plot — which is how the y axis is asked
+  // for — keeps being reported.
+  event.currentTarget.setPointerCapture(event.pointerId);
+  return {
+    pointerId: event.pointerId,
+    fromX: point.x,
+    fromY: point.y,
+    toX: point.x,
+    toY: point.y,
+  };
+}
+
+/**
+ * Where a drag has got to, when the event belongs to it.
+ * @param drag - The drag being made, `null` when none is.
+ * @param event - The pointer event just received.
+ * @param svg - The SVG the gesture is made on.
+ * @returns The drag with its far corner moved, `null` when the event is not
+ * part of it or the SVG cannot place the pointer.
+ */
+export function draggedTo(
+  drag: Drag | null,
+  event: ReactPointerEvent<SVGSVGElement>,
+  svg: SVGSVGElement | null,
+): Drag | null {
+  if (drag?.pointerId !== event.pointerId) return null;
+  const point = svgPointAt(svg, event.clientX, event.clientY);
+  if (point === null) return null;
+  return { ...drag, toX: point.x, toY: point.y };
+}
+
+/**
+ * Give the pointer back, so the next gesture reaches whatever it is aimed at.
+ * @param event - The event ending the drag.
+ */
+export function releaseDrag(event: ReactPointerEvent<SVGSVGElement>): void {
+  if (event.currentTarget.hasPointerCapture(event.pointerId)) {
+    event.currentTarget.releasePointerCapture(event.pointerId);
+  }
+}
+
+/**
+ * Tell a host where a press that went nowhere landed, in the units the chart is
+ * measured in.
+ *
+ * The travel is measured as the hand made it, before any clamping to the plot: a
+ * gesture that ran out over the tick labels travelled however far it travelled,
+ * and one begun outside the plot is refused by `isInsidePlot` rather than by
+ * arithmetic that pretends it stopped at the edge.
+ * @param released - The gesture as it was let go, in user units of the SVG.
+ * @param plot - Where the plot sits inside that SVG, which a click has to be
+ * over for the values it inverts to be ones the chart is drawing.
+ * @param xScale - The horizontal axis as the chart is currently zoomed.
+ * @param yScale - The vertical axis, likewise.
+ * @param onClick - What the host asked to be told, absent when it asked for
+ * nothing.
+ * @param modifiers - Which keys were held as the button came up.
+ */
+function reportClick(
+  released: DragBox,
+  plot: PlotRect,
+  xScale: ChartScale,
+  yScale: ChartScale,
+  onClick:
+    ((point: ChartPoint, modifiers: ChartClickModifiers) => void) | undefined,
+  modifiers: ChartClickModifiers,
+): void {
+  if (onClick === undefined) return;
+  if (Math.abs(released.toX - released.fromX) >= MINIMUM_DRAG) return;
+  if (Math.abs(released.toY - released.fromY) >= MINIMUM_DRAG) return;
+  // Where the button came up rather than where it went down: the two are within
+  // `MINIMUM_DRAG` of each other, and the release is where the user was looking.
+  const point = { x: released.toX, y: released.toY };
+  if (!isInsidePlot(plot, point)) return;
+  onClick(
+    { x: chartValue(xScale, point.x), y: chartValue(yScale, point.y) },
+    modifiers,
+  );
+}
+
+/** Which button drags a box; the others belong to menus and to panning. */
+const LEFT_BUTTON = 0;

package/src/chart/ui/chartStackLevel.tsx

@@ -0,0 +1,210 @@
+/**
+ * One level of a chart stack: the pane drawn at it, and everything under it.
+ *
+ * `SplitPane` takes exactly two children, so a stack is a recursion rather than
+ * a list — the pane at each level is the controlled side and is given a height
+ * in pixels, everything below it is the other side and takes what is left. It
+ * stands beside `ChartStack.tsx` rather than inside it so that the component is
+ * the state and this is the picture drawn from it. Why a height is held above a
+ * floor, and why every pane is wrapped in a box of its own, is in that file's
+ * header.
+ *
+ * The pane at the foot has nothing under it and so needs no split at all, and is
+ * given one regardless. React rebuilds whatever sits at a position the moment
+ * the element there changes type, so a pane drawn as a bare box while it is last
+ * and as a split once something is appended under it would be torn down and
+ * stood up again by the appending — and a chart stood up again is empty: it has
+ * to be measured, fitted and drawn from its twenty thousand points before it is
+ * a picture of anything. Every pane is therefore a split, the last one holding
+ * nothing on its other side, which is exactly what makes it draw no splitter and
+ * answer no drag.
+ */
+
+import type { ReactNode } from 'react';
+import type { SplitPaneSize } from 'react-science/ui';
+import { SplitPane } from 'react-science/ui';
+
+/** One pane of the stack, and how tall it stands. */
+export interface ChartStackPane {
+  /**
+   * Identity, which is what a height is remembered against.
+   *
+   * A pane leaves the stack whenever what it draws stops existing, and comes
+   * back when it exists again. The height is held against this rather than
+   * against the pane's place in the array, so a pane that returns returns the
+   * size it was left at rather than at its default.
+   */
+  id: string;
+  /** What is drawn in it — a chart, and whatever bar is drawn over it. */
+  content: ReactNode;
+  /**
+   * How tall it stands the first time it is stacked, in pixels.
+   *
+   * A default rather than a controlled value: the stack holds the live height
+   * from then on, so a viewer restoring a layout it saved hands it in here and
+   * hears every later change back through `onHeightChange`. A change to this
+   * number afterwards is ignored, the way a defaulted prop always is — what is
+   * on screen is what a chemist dragged it to.
+   * @default 220
+   */
+  defaultHeight?: number;
+  /**
+   * The shortest it may be dragged to, in pixels.
+   *
+   * A hundred and twenty is a plot that still reads: `MARGIN` spends 44 of them
+   * on the tick row and the axis title, which leaves the trace the rest of it.
+   * @default 120
+   */
+  minimumHeight?: number;
+}
+
+/** Everything one level of the nesting needs to draw itself and the rest. */
+export interface StackLevel {
+  /** Every pane of the stack, top to bottom. */
+  panes: readonly ChartStackPane[];
+  /**
+   * How tall a pane stands.
+   * @param pane - The pane to measure.
+   * @returns Its height, in pixels.
+   */
+  heightOf: (pane: ChartStackPane) => number;
+  /**
+   * Take what a drag in progress is asking for.
+   * @param pane - The pane being resized.
+   * @param asked - The size its splitter asked for.
+   */
+  resize: (pane: ChartStackPane, asked: SplitPaneSize) => void;
+  /**
+   * Take where a drag came to rest.
+   * @param pane - The pane that was resized.
+   * @param asked - The size its splitter was let go at.
+   */
+  rest: (pane: ChartStackPane, asked: SplitPaneSize) => void;
+}
+
+/**
+ * The pane at one level of the stack, and everything under it.
+ *
+ * The pane at the foot is given the whole of what it is handed rather than a
+ * height, since there is nothing under it to leave room for, and it is given
+ * neither a close threshold nor anywhere to report a drag: a split with nothing
+ * on its other side draws no splitter, so there is no drag to report and nothing
+ * to close it against — a threshold there would hide the only pane on a stack
+ * squeezed short.
+ * @param level - The panes and what is done with a drag on them.
+ * @param index - Which pane this level draws.
+ * @returns The pane split against the rest below it, the pane alone in a split
+ * of its own at the foot of the stack, and nothing at all for a stack of no
+ * panes.
+ */
+export function stackFrom(level: StackLevel, index: number): ReactNode {
+  const { panes, heightOf, resize, rest } = level;
+  const pane = panes[index];
+  if (pane === undefined) return null;
+
+  const under = stackFrom(level, index + 1);
+  const isLast = under === null;
+
+  return (
+    <SplitPane
+      key={pane.id}
+      direction="vertical"
+      controlledSide="start"
+      size={isLast ? WHOLE_STACK : `${heightOf(pane)}px`}
+      onSizeChange={isLast ? undefined : (asked) => resize(pane, asked)}
+      onResize={isLast ? undefined : (asked) => rest(pane, asked)}
+      closeThreshold={isLast ? undefined : CLOSE_THRESHOLD}
+      unmountChildren={false}
+    >
+      <div key={pane.id} data-chart-pane={pane.id} style={paneStyle}>
+        {pane.content}
+      </div>
+      {under}
+    </SplitPane>
+  );
+}
+
+/**
+ * How tall a pane stands, given the height it was last left at.
+ *
+ * The floor is applied to the default as much as to a stored height: a pane
+ * asking for 40 pixels against a minimum of 150 would otherwise draw the stub
+ * with a full set of axes over it that the header of `ChartStack.tsx` describes,
+ * on its first render and until somebody touched a splitter.
+ * @param pane - The pane to measure.
+ * @param stored - The height it was left at, absent until one is dragged.
+ * @returns Its height, in pixels.
+ */
+export function paneHeight(
+  pane: ChartStackPane,
+  stored: number | undefined,
+): number {
+  return Math.max(
+    stored ?? pane.defaultHeight ?? DEFAULT_PANE_HEIGHT,
+    floorOf(pane),
+  );
+}
+
+/**
+ * The height to keep, given what a splitter asked for.
+ * @param asked - The size the splitter reported, in the pixels it was handed.
+ * @param pane - The pane it belongs to, for its minimum.
+ * @returns The height to store, `null` for a size that is not a length at all.
+ */
+export function keptHeight(
+  asked: SplitPaneSize,
+  pane: ChartStackPane,
+): number | null {
+  const value = Number.parseFloat(asked);
+  if (!Number.isFinite(value)) return null;
+  return Math.max(value, floorOf(pane));
+}
+
+/**
+ * The shortest a pane may stand, whether it said so itself or not.
+ * @param pane - The pane being held up.
+ * @returns Its floor, in pixels.
+ */
+function floorOf(pane: ChartStackPane): number {
+  return pane.minimumHeight ?? MINIMUM_PANE_HEIGHT;
+}
+
+/** How tall a pane stands when nobody has said, in pixels. */
+const DEFAULT_PANE_HEIGHT = 220;
+
+/** The shortest a pane may be dragged to when nobody has said, in pixels. */
+const MINIMUM_PANE_HEIGHT = 120;
+
+/**
+ * What the pane at the foot is given, having nothing under it to leave room for.
+ *
+ * A share rather than a length: handed a percentage, `SplitPane` lays its
+ * controlled side out as a flexible share instead of at a fixed height, so the
+ * pane takes whatever the panes above it left rather than standing at some
+ * number and leaving a gap under itself.
+ */
+const WHOLE_STACK: SplitPaneSize = '100%';
+
+/**
+ * The height below which a split closes its pane rather than squeezing it.
+ *
+ * A stack squeezed to under ninety pixels has no room for a chart of any kind,
+ * and that is under the shortest pane this stack will otherwise keep.
+ * `SplitPane` stops doing this the moment a splitter is touched, so it settles
+ * what a pane does before anyone has an opinion and nothing after that.
+ */
+const CLOSE_THRESHOLD = 90;
+
+/**
+ * The box one pane fills — `minHeight: 0` is the whole reason it exists rather
+ * than the pane's content sitting in the split itself; see the header of
+ * `ChartStack.tsx`.
+ */
+const paneStyle = {
+  display: 'flex',
+  flexDirection: 'column',
+  flex: '1 1 0%',
+  minWidth: 0,
+  minHeight: 0,
+  overflow: 'hidden',
+} as const;

package/src/chart/ui/chartSurface.ts

@@ -0,0 +1,66 @@
+/**
+ * The style the SVG a chart is drawn on carries, and the one thing about it
+ * that moves: the cursor.
+ *
+ * A chart drawing its own crosshair has two pointers on it — the dashed rules
+ * that read the axes, and the operating system's arrow beside them — and only
+ * one of the two is saying anything. The arrow is also the one in the way: it
+ * is drawn down and to the right of its own hot spot, which is exactly where
+ * the crosshair meets and exactly the place being read. So the arrow is hidden
+ * while the crosshair is up, and it comes back the moment the pointer leaves
+ * the plot, where there is no crosshair and the margins are ordinary furniture.
+ *
+ * `target` is why this is a function rather than a constant. Something under
+ * the pointer can be opened — a ring on a peak a survey scan was fragmented at
+ * — and a cursor that never changes is a chart with no way of saying so. The
+ * hand wins over the hidden arrow, and the crosshair goes on being drawn under
+ * it, since where you are is still worth reading while you decide to click.
+ *
+ * One helper for every chart in this package rather than a `svgStyle` constant
+ * in each: a mass spectrum stacked under a chromatogram is two charts a reader
+ * takes to be one instrument, and an arrow over one of them and nothing over
+ * the other is the sort of difference that reads as a fault.
+ */
+
+import type { CSSProperties } from 'react';
+
+/**
+ * What the SVG a chart is drawn on is styled with.
+ * @param tracked - Whether the chart is drawing its crosshair where the pointer
+ *   is, which is true exactly while the pointer is over the plot.
+ * @param target - Whether what is under the pointer can be clicked open.
+ *   Defaults to `false`, which is every chart offering nothing to click.
+ * @returns The style, one of three objects that never change — a fresh one per
+ * pointer move would replace the `style` prop on every tremor of a hand.
+ */
+export function chartSurfaceStyle(
+  tracked: boolean,
+  target = false,
+): CSSProperties {
+  if (!tracked) return IDLE_SURFACE;
+  return target ? TARGET_SURFACE : TRACKED_SURFACE;
+}
+
+/**
+ * Everything about the surface that is not the cursor.
+ *
+ * `touchAction` because every gesture is a pointer gesture and a browser that
+ * scrolled the page instead would take the drag with it; `userSelect` because a
+ * drag across a chart is a gesture and not a selection — without it the tick
+ * labels come up highlighted behind the rectangle, and stay highlighted in the
+ * picture the chart is exported as.
+ */
+const SURFACE = {
+  display: 'block',
+  touchAction: 'none',
+  userSelect: 'none',
+} as const;
+
+/** The pointer is off the plot: whatever cursor the page would have shown. */
+const IDLE_SURFACE: CSSProperties = { ...SURFACE };
+
+/** The chart is drawing the crosshair, so the arrow beside it is hidden. */
+const TRACKED_SURFACE: CSSProperties = { ...SURFACE, cursor: 'none' };
+
+/** Something under the pointer can be opened. */
+const TARGET_SURFACE: CSSProperties = { ...SURFACE, cursor: 'pointer' };

package/src/chart/ui/index.ts

@@ -31,3 +31,38 @@ export { TrackedLineChart } from './TrackedLineChart.tsx';
 export type { ChartStickSeries } from './stickChartModel.ts';
 export type { TrackedStickChartProps } from './TrackedStickChart.tsx';
 export { TrackedStickChart } from './TrackedStickChart.tsx';
+
+export type { AxesProps } from './Axes.tsx';
+export { Axes } from './Axes.tsx';
+export type { AxisGuideProps } from './AxisGuide.tsx';
+export { AxisGuide } from './AxisGuide.tsx';
+export type { ChartStackPane, ChartStackProps } from './ChartStack.tsx';
+export { ChartStack } from './ChartStack.tsx';
+export type { ChartTrackerProps } from './ChartTracker.tsx';
+export { ChartTracker } from './ChartTracker.tsx';
+export type { PlotCaptionProps } from './PlotCaption.tsx';
+export { PlotCaption } from './PlotCaption.tsx';
+export type { SelectionRectProps } from './SelectionRect.tsx';
+export { SelectionRect } from './SelectionRect.tsx';
+export type { LegendEntry, TraceLegendProps } from './TraceLegend.tsx';
+export { TraceLegend } from './TraceLegend.tsx';
+export type { ChartClickModifiers } from './chartGestures.ts';
+export { NO_MODIFIERS } from './chartGestures.ts';
+export { chartSurfaceStyle } from './chartSurface.ts';
+export type { ChartPointer, ChartPointerOptions } from './useChartPointer.ts';
+export {
+  isInsidePlot,
+  leftChart,
+  nextChartPointer,
+  sameReading,
+  useChartPointer,
+} from './useChartPointer.ts';
+export type { ChartSizeHandle } from './useChartSize.ts';
+export { nextChartSize, useChartSize } from './useChartSize.ts';
+export type {
+  ChartZoom,
+  ChartZoomHandlers,
+  ChartZoomOptions,
+} from './useChartZoom.ts';
+export { useChartZoom } from './useChartZoom.ts';
+export { useWheelListener } from './useWheelListener.ts';