react-cheminfo 0.69.0 → 0.71.0

package/src/mass/ui/MassCanvas.tsx

@@ -0,0 +1,170 @@
+import type { DragEvent } from 'react';
+import { useCallback, useMemo, useState } from 'react';
+
+import type { MassPlotClick } from '../core/massEditorApi.ts';
+import type { MassDomain } from '../core/massSpectrum.ts';
+import type { NearestPeak } from '../core/nearestPeak.ts';
+
+import { MassChart } from './MassChart.tsx';
+import { MassStatusBar } from './MassStatusBar.tsx';
+import { useMassActions, useMassEditorState } from './massStateContext.ts';
+
+export interface MassCanvasProps {
+  /**
+   * The m/z of the peak the pointer is resting on, wherever it was hovered —
+   * the chart or the peak table.
+   * @default null
+   */
+  highlightMz?: number | null;
+  /**
+   * Told which peak the pointer has come to rest on over the chart.
+   * @default undefined
+   */
+  onHighlight?: (mz: number | null) => void;
+  /**
+   * The `id` put on the box the chart is drawn in, which the "Save figure"
+   * panel is pointed at.
+   * @default undefined
+   */
+  chartId?: string;
+  /**
+   * Told of a click on the plot, with the spectrum selected at that moment.
+   * @default undefined
+   */
+  onPlotClick?: (click: MassPlotClick) => void;
+  /**
+   * Read files dropped on the chart.
+   * @default undefined — a drop is left to the page
+   */
+  onDropFiles?: (files: File[]) => void;
+}
+
+/**
+ * The chart, and the status bar under it.
+ *
+ * This is where the state meets the drawing: the chart holds nothing, so
+ * everything it draws is read out of the state here and every gesture it reports
+ * is written back. The window in particular goes **both** ways — the chart is
+ * told what to show and reports what it arrives at — which is what lets a toolbar
+ * button, a row of the peak table and a drag all move it.
+ *
+ * The chart is also where files are dropped, because that is where a chemist
+ * expects the spectrum to land; the box is outlined while one is held over it.
+ * @param props - Component props.
+ * @returns The canvas.
+ */
+export function MassCanvas(props: MassCanvasProps) {
+  const {
+    highlightMz = null,
+    onHighlight,
+    chartId,
+    onPlotClick,
+    onDropFiles,
+  } = props;
+  const { state, visibleSpectra } = useMassEditorState();
+  const actions = useMassActions();
+  const { domain, tool, selectedId } = state.view;
+  const { showLabels, labelLimit, showCharges, mzDecimals } = state.settings;
+  const [isDropping, setIsDropping] = useState(false);
+
+  const onDomainChange = useCallback(
+    (next: MassDomain) => actions.setDomain(next),
+    [actions],
+  );
+
+  const onPeakHover = useMemo(
+    () =>
+      onHighlight === undefined
+        ? undefined
+        : (peak: NearestPeak | null) => onHighlight(peak?.mz ?? null),
+    [onHighlight],
+  );
+
+  // Which spectrum was selected is the viewer's to say, not the chart's: the
+  // chart only knows where the press landed.
+  const onClick = useMemo(
+    () =>
+      onPlotClick === undefined
+        ? undefined
+        : (mz: number, peak: NearestPeak | null) =>
+            onPlotClick({
+              mz,
+              peakMz: peak?.mz ?? null,
+              spectrumId: selectedId,
+            }),
+    [onPlotClick, selectedId],
+  );
+
+  const drop =
+    onDropFiles === undefined
+      ? {}
+      : {
+          onDragOver: (event: DragEvent<HTMLDivElement>) => {
+            if (!event.dataTransfer.types.includes('Files')) return;
+            // Without this the browser opens the file in place of the page.
+            event.preventDefault();
+            event.dataTransfer.dropEffect = 'copy';
+            if (!isDropping) setIsDropping(true);
+          },
+          onDragLeave: () => setIsDropping(false),
+          onDrop: (event: DragEvent<HTMLDivElement>) => {
+            event.preventDefault();
+            setIsDropping(false);
+            const files = [...event.dataTransfer.files];
+            if (files.length > 0) onDropFiles(files);
+          },
+        };
+
+  return (
+    <div style={rootStyle}>
+      <div
+        id={chartId}
+        style={isDropping ? droppingChartStyle : chartStyle}
+        {...drop}
+      >
+        <MassChart
+          spectra={visibleSpectra}
+          labelledId={selectedId}
+          showLabels={showLabels}
+          labelLimit={labelLimit}
+          showCharges={showCharges}
+          // A number chosen holds for every mass on the chart; left to the
+          // spectra, the chart decides per spectrum, labels and crosshair alike.
+          {...(mzDecimals === 'auto' ? {} : { mzDecimals })}
+          highlightMz={highlightMz}
+          domain={domain}
+          onDomainChange={onDomainChange}
+          drag={tool === 'box' ? 'box' : 'xAxis'}
+          // The shell runs `f` through its command table, where it is listed.
+          answersKeys={false}
+          emphasisedId={visibleSpectra.length > 1 ? selectedId : null}
+          {...(onPeakHover === undefined ? {} : { onPeakHover })}
+          {...(onClick === undefined ? {} : { onPlotClick: onClick })}
+        />
+      </div>
+      <MassStatusBar />
+    </div>
+  );
+}
+
+const rootStyle = {
+  display: 'flex',
+  flexDirection: 'column',
+  flex: '1 1 1px',
+  minWidth: 0,
+  minHeight: 0,
+} as const;
+
+/** The chart takes what the status bar does not. */
+const chartStyle = {
+  flex: '1 1 1px',
+  minHeight: 0,
+  outline: '2px dashed transparent',
+  outlineOffset: -4,
+} as const;
+
+/** The same box while a file is held over it, saying where it will land. */
+const droppingChartStyle = {
+  ...chartStyle,
+  outlineColor: 'var(--accent, currentColor)',
+} as const;

package/src/mass/ui/MassChart.tsx

@@ -0,0 +1,266 @@
+import type { ReactElement } from 'react';
+import { useId, useLayoutEffect, useMemo, useRef } from 'react';
+
+import { sameChartDomain } from '../../chart/core/chartDomain.ts';
+import { MARGIN, plotRect } from '../../chart/core/chartGeometry.ts';
+import { Axes } from '../../chart/ui/Axes.tsx';
+import { AxisGuide } from '../../chart/ui/AxisGuide.tsx';
+import { SelectionRect } from '../../chart/ui/SelectionRect.tsx';
+import { chartSurfaceStyle } from '../../chart/ui/chartSurface.ts';
+import { useChartSize } from '../../chart/ui/useChartSize.ts';
+import type { MassSpectrum } from '../core/massSpectrum.ts';
+import { DEFAULT_LABEL_LIMIT } from '../core/massState.ts';
+import { mzDecimalsOf } from '../core/resolutionOf.ts';
+
+import { MassPointerTracker } from './MassPointerTracker.tsx';
+import { PeakLabels } from './PeakLabels.tsx';
+import { SpectrumTrace } from './SpectrumTrace.tsx';
+import type { MassChartProps } from './massChartProps.ts';
+import { useMassPointer } from './useMassPointer.ts';
+import { useMassZoom } from './useMassZoom.ts';
+
+/**
+ * The chart: every layer of a mass spectrum, in one SVG.
+ *
+ * The axes go under the data, so a grid line is never read as a peak. Only the
+ * data band is clipped, so a zoomed trace stops at the plot edge while the
+ * labels over the tallest peaks are allowed out over the margin — clip those and
+ * the base peak of every spectrum loses its label. The guide, the drag rectangle
+ * and the crosshair go over everything, because each answers a question being
+ * asked right now.
+ *
+ * Nothing is held here. The spectra, what is labelled, what is being looked at
+ * and the window are all props, and every gesture comes back out as a callback
+ * — so one component draws an editor's chart, a report page's single spectrum
+ * and a test.
+ * @param props - Component props.
+ * @returns The chart.
+ */
+export function MassChart(props: MassChartProps): ReactElement {
+  const {
+    spectra,
+    labelledId,
+    showLabels = true,
+    labelLimit = DEFAULT_LABEL_LIMIT,
+    showCharges = false,
+    mzDecimals: askedDecimals,
+    annotationLabels,
+    highlightMz = null,
+    onPeakHover,
+    domain = null,
+    onDomainChange,
+    onPlotClick,
+    drag = 'xAxis',
+    answersKeys = true,
+    emphasisedId = null,
+    width,
+    height,
+    children,
+  } = props;
+
+  const [containerRef, measured] = useChartSize<HTMLDivElement>();
+  const svgRef = useRef<SVGSVGElement | null>(null);
+
+  const plot = useMemo(
+    () =>
+      plotRect({
+        width: width ?? measured.width,
+        height: height ?? measured.height,
+      }),
+    [width, height, measured.width, measured.height],
+  );
+  // Read back off the plot rather than off the measurement, so a chart briefly
+  // laid out at nothing still draws its axes inside a box that holds them.
+  const frameWidth = plot.right + MARGIN.right;
+  const frameHeight = plot.bottom + MARGIN.bottom;
+
+  // The host's window goes *into* the zoom rather than over it, so a drag is
+  // always measured against what is on screen.
+  const zoom = useMassZoom({
+    spectra,
+    svgRef,
+    plot,
+    domain,
+    drag,
+    keys: answersKeys,
+    ...(onPlotClick === undefined
+      ? {}
+      : { onClick: ({ mz, peak }) => onPlotClick(mz, peak) }),
+  });
+  const { domain: shown, xScale, yScale, selection, handlers } = zoom;
+
+  // A chart holding nothing still builds scales on a placeholder window, and a
+  // placeholder reported would become a window the host imposes on whatever is
+  // dropped next — drawn entirely off screen.
+  const holdsNothing = spectra.length === 0;
+  const reported = useRef(shown);
+  // Before the browser paints, so a host that stores the window and hands it
+  // back does so in the frame the gesture landed in rather than the one after.
+  useLayoutEffect(() => {
+    if (holdsNothing || sameChartDomain(reported.current, shown)) return;
+    reported.current = shown;
+    onDomainChange?.(shown);
+  }, [holdsNothing, shown, onDomainChange]);
+
+  const pointer = useMassPointer({
+    svgRef,
+    plot,
+    xScale,
+    yScale,
+    spectra,
+    ...(onPeakHover === undefined ? {} : { onPeak: onPeakHover }),
+  });
+
+  const labelled = useMemo(
+    () => labelledSpectrum(spectra, labelledId),
+    [spectra, labelledId],
+  );
+  const painted = useMemo(
+    () => emphasisedLast(spectra, emphasisedId),
+    [spectra, emphasisedId],
+  );
+
+  // The crosshair reads every drawn spectrum, so it is written to what they
+  // resolve together; the labels are of one spectrum, and written to its own.
+  const readoutDecimals = useMemo(
+    () => askedDecimals ?? mzDecimalsOf(spectra),
+    [askedDecimals, spectra],
+  );
+  const labelDecimals = useMemo(
+    () =>
+      askedDecimals ??
+      (labelled === null ? readoutDecimals : mzDecimalsOf([labelled])),
+    [askedDecimals, labelled, readoutDecimals],
+  );
+
+  // React's generated id carries the punctuation it keeps its own ids apart
+  // with, which a URL fragment is under no obligation to accept.
+  const clipId = `mass-plot-${useId().replaceAll(/\W/g, '')}`;
+
+  return (
+    <div ref={containerRef} style={containerStyle}>
+      <svg
+        ref={svgRef}
+        role="img"
+        aria-label={CHART_LABEL}
+        width={frameWidth}
+        height={frameHeight}
+        viewBox={`0 0 ${frameWidth} ${frameHeight}`}
+        style={chartSurfaceStyle(pointer.position !== null)}
+        {...handlers}
+      >
+        <defs>
+          <clipPath id={clipId}>
+            <rect
+              x={plot.left}
+              y={plot.top}
+              width={plot.width}
+              height={plot.height}
+            />
+          </clipPath>
+        </defs>
+
+        <Axes
+          plot={plot}
+          xDomain={shown.x}
+          yDomain={shown.y}
+          xScale={xScale}
+          yScale={yScale}
+          xTitle="m/z"
+          yTitle="relative intensity (%)"
+        />
+
+        <g clipPath={`url(#${clipId})`}>
+          {painted.map((spectrum) => (
+            <SpectrumTrace
+              key={spectrum.id}
+              spectrum={spectrum}
+              plot={plot}
+              xScale={xScale}
+              yScale={yScale}
+              strokeWidth={
+                spectrum.id === emphasisedId ? EMPHASISED_WIDTH : undefined
+              }
+            />
+          ))}
+          {children}
+        </g>
+
+        {showLabels && labelled !== null ? (
+          <PeakLabels
+            spectrum={labelled}
+            plot={plot}
+            xScale={xScale}
+            yScale={yScale}
+            limit={labelLimit}
+            showCharges={showCharges}
+            mzDecimals={labelDecimals}
+            {...(annotationLabels === undefined ? {} : { annotationLabels })}
+            color={spectra.length > 1 ? labelled.color : undefined}
+          />
+        ) : null}
+        <AxisGuide value={highlightMz} plot={plot} xScale={xScale} />
+        <SelectionRect selection={selection} plot={plot} />
+        <MassPointerTracker
+          position={pointer.position}
+          readout={pointer.readout}
+          plot={plot}
+          mzDecimals={readoutDecimals}
+        />
+      </svg>
+    </div>
+  );
+}
+
+/**
+ * The one spectrum whose peaks are labelled.
+ * @param spectra - What the chart draws.
+ * @param labelledId - The identity asked for, `null` for none, absent to let the
+ * chart take the first.
+ * @returns The spectrum, or `null` when none answers.
+ */
+function labelledSpectrum(
+  spectra: readonly MassSpectrum[],
+  labelledId: string | null | undefined,
+): MassSpectrum | null {
+  if (labelledId === undefined) return spectra[0] ?? null;
+  if (labelledId === null) return null;
+  for (const spectrum of spectra) {
+    if (spectrum.id === labelledId) return spectrum;
+  }
+  return null;
+}
+
+/**
+ * The traces in painting order, with the emphasised one last — last is in
+ * front, and in front is what lets a trace crossing a dozen others be followed.
+ * @param spectra - The traces, in the order they were opened.
+ * @param emphasisedId - Identity of the one to raise, `null` for none.
+ * @returns The order to paint in — the array itself when nothing moves.
+ */
+function emphasisedLast(
+  spectra: readonly MassSpectrum[],
+  emphasisedId: string | null,
+): readonly MassSpectrum[] {
+  if (emphasisedId === null) return spectra;
+  const at = spectra.findIndex((spectrum) => spectrum.id === emphasisedId);
+  if (at === -1 || at === spectra.length - 1) return spectra;
+  return [
+    ...spectra.slice(0, at),
+    ...spectra.slice(at + 1),
+    spectra[at] as MassSpectrum,
+  ];
+}
+
+/** What the chart is, and what can be done to it, for whoever cannot see it. */
+const CHART_LABEL =
+  'Mass spectrum. Drag across it to zoom the m/z axis, drag below the baseline to take the intensity axis with it, turn the wheel to scale the intensity, and double click to fit everything again.';
+
+/**
+ * How thick the trace every panel is about is drawn: barely thicker, so it
+ * reads as the same kind of thing as the others.
+ */
+const EMPHASISED_WIDTH = 2;
+
+/** The box the chart is measured against, and fills. */
+const containerStyle = { width: '100%', height: '100%' } as const;

package/src/mass/ui/MassCommandProvider.tsx

@@ -0,0 +1,34 @@
+import type { ReactNode } from 'react';
+import { useMemo } from 'react';
+
+import type { MassCommandHandlers } from '../core/massCommands.ts';
+
+import type { MassCommandContextValue } from './massCommandContext.tsx';
+import { massCommandContext } from './massCommandContext.tsx';
+
+export interface MassCommandProviderProps {
+  /** What each command does. */
+  handlers: MassCommandHandlers;
+  /** The viewer. */
+  children: ReactNode;
+}
+
+/**
+ * Put the command handlers where the toolbar and the panels can reach them.
+ * @param props - Component props.
+ * @returns The provider.
+ */
+export function MassCommandProvider(props: MassCommandProviderProps) {
+  const { handlers, children } = props;
+
+  const value = useMemo<MassCommandContextValue>(
+    () => ({ handlers, run: (id) => handlers[id]?.() }),
+    [handlers],
+  );
+
+  return (
+    <massCommandContext.Provider value={value}>
+      {children}
+    </massCommandContext.Provider>
+  );
+}

package/src/mass/ui/MassCommandTooltip.tsx

@@ -0,0 +1,36 @@
+import { TooltipHelpContent } from 'react-science/ui';
+
+import type { MassCommand, MassCommandId } from '../core/massCommands.ts';
+import { massCommands } from '../core/massCommands.ts';
+
+export interface MassCommandTooltipProps {
+  /** Which command the tooltip is about. */
+  id: MassCommandId;
+}
+
+/**
+ * One command's tooltip: its title, what it does, and every way to do it.
+ *
+ * `TooltipHelpContent` from react-science, which is what NMRium's tooltips and
+ * the infrared viewer's are, so a page holding these viewers side by side
+ * explains itself the same way in all of them.
+ * @param props - Component props.
+ * @returns The tooltip's content.
+ */
+export function MassCommandTooltip(props: MassCommandTooltipProps) {
+  const { id } = props;
+  const entry: MassCommand = massCommands[id];
+  const shortcuts = entry.shortcut?.label ?? entry.shortcut?.keys;
+
+  return (
+    <TooltipHelpContent
+      title={entry.title}
+      description={entry.description}
+      shortcuts={shortcuts === undefined ? undefined : [...shortcuts]}
+      subTitles={entry.gestures?.map((gesture) => ({
+        title: gesture.title,
+        shortcuts: [...gesture.shortcuts],
+      }))}
+    />
+  );
+}

package/src/mass/ui/MassDocumentationDialog.tsx

@@ -0,0 +1,136 @@
+import type { ReactNode } from 'react';
+
+import type { DocumentationSection } from '../../panel/ui/DocumentationDialogFrame.tsx';
+import { DocumentationDialogFrame } from '../../panel/ui/DocumentationDialogFrame.tsx';
+import type { MassCommand } from '../core/massCommands.ts';
+import { massCommandLabel, massCommands } from '../core/massCommands.ts';
+import { HIGH_RESOLVING_POWER } from '../core/massResolution.ts';
+
+export interface MassDocumentationDialogProps {
+  /** Whether the dialog is open. */
+  isOpen: boolean;
+  /** Close it. */
+  onClose: () => void;
+}
+
+/**
+ * How to use the viewer, written in the viewer.
+ *
+ * In the component rather than on a site, so there is nowhere to leave for and
+ * nothing to keep in step: every key in the last section is read out of the
+ * same command table the toolbar and the key handler read, so a shortcut cannot
+ * be documented as one thing and bound as another.
+ * @param props - Component props.
+ * @returns The dialog.
+ */
+export function MassDocumentationDialog(props: MassDocumentationDialogProps) {
+  const { isOpen, onClose } = props;
+  return (
+    <DocumentationDialogFrame
+      isOpen={isOpen}
+      onClose={onClose}
+      title="Using the mass spectrum viewer"
+      sections={SECTIONS}
+    />
+  );
+}
+
+/**
+ * One row of the gestures table: a command, its key and what it does.
+ * @param props - Component props.
+ * @param props.entry - The command, as the table words it.
+ * @returns The row.
+ */
+function CommandRow(props: { entry: MassCommand }): ReactNode {
+  const { entry } = props;
+  const keys = entry.shortcut?.label ?? entry.shortcut?.keys ?? [];
+  const gestures = (entry.gestures ?? []).flatMap(
+    (gesture) => gesture.shortcuts,
+  );
+  return (
+    <tr>
+      <th style={labelCellStyle}>{entry.title}</th>
+      <td style={keyCellStyle}>{[...keys, ...gestures].join(' · ')}</td>
+      <td style={cellStyle}>{entry.description}</td>
+    </tr>
+  );
+}
+
+const tableStyle = {
+  width: '100%',
+  borderCollapse: 'collapse',
+  fontSize: 12,
+} as const;
+
+const cellStyle = { padding: '3px 6px', verticalAlign: 'top' } as const;
+
+const labelCellStyle = {
+  ...cellStyle,
+  textAlign: 'left',
+  whiteSpace: 'nowrap',
+} as const;
+
+const keyCellStyle = {
+  ...cellStyle,
+  whiteSpace: 'nowrap',
+  opacity: 0.7,
+} as const;
+
+/** What the guide says, in reading order. */
+const SECTIONS: readonly DocumentationSection[] = [
+  {
+    id: 'open',
+    title: 'Opening a spectrum',
+    body: (
+      <p>
+        Drop JCAMP-DX files (<code>.jdx</code>, <code>.dx</code>) or two columns
+        of m/z and intensity (<code>.txt</code>, <code>.csv</code>,{' '}
+        <code>.xy</code>) on the chart, or use {massCommandLabel('openFiles')}.
+        A JCAMP holding several blocks, or a GC/MS export holding a page per
+        scan, gives one spectrum per block or page.
+      </p>
+    ),
+  },
+  {
+    id: 'peaks',
+    title: 'Profile and centroid',
+    body: (
+      <p>
+        A continuous profile is peak picked as it is read; a peak table is taken
+        as it stands. Each row of the Spectra panel draws a spectrum as its
+        profile or as its picked peaks, never both. The peaks of the selected
+        spectrum are labelled on the chart: zoom onto a cluster and every line
+        of it is labelled.
+      </p>
+    ),
+  },
+  {
+    id: 'resolution',
+    title: 'High or low resolution',
+    body: (
+      <p>
+        A profile is measured: the median resolving power of its tallest peaks,
+        at half height, is high resolution from{' '}
+        {HIGH_RESOLVING_POWER.toLocaleString('en-US')}. A peak table has no
+        widths, so the instrument its file names decides, and failing that the
+        decimals its masses were written with. Masses are written as high
+        resolution, to four decimals, or as nominal masses, whole. To write them
+        another way, pick the number of decimals in the Peaks panel toolbar; it
+        holds for the chart and the tables alike.
+      </p>
+    ),
+  },
+  {
+    id: 'keys',
+    title: 'Gestures and keys',
+    body: (
+      <table style={tableStyle}>
+        <tbody>
+          {Object.values(massCommands).map((entry) => (
+            <CommandRow key={entry.title} entry={entry} />
+          ))}
+        </tbody>
+      </table>
+    ),
+  },
+];