react-cheminfo 0.69.0 → 0.71.0

package/src/mass/ui/useMassFiles.ts

@@ -0,0 +1,91 @@
+/**
+ * Reading the files a chemist drops on the chart or picks from a dialog.
+ *
+ * Every file is read on its own, and one that cannot be read is said rather
+ * than stopping the others: a drop of eleven files with one infrared JCAMP among
+ * them draws the ten mass spectra and names the eleventh in the status bar.
+ */
+
+import { useCallback, useMemo } from 'react';
+
+import { errorMessage } from '../../error/core/index.ts';
+import type { LoadMassSpectraResult } from '../core/loadMassSpectra.ts';
+import { loadMassSpectra } from '../core/loadMassSpectra.ts';
+import type { MassSpectrum } from '../core/massSpectrum.ts';
+import { toMassSpectra } from '../core/toMassSpectrum.ts';
+
+import { useMassActions, useMassEditorState } from './massStateContext.ts';
+
+/** How files reach the viewer. */
+export interface MassFiles {
+  /**
+   * Read these files and add what they hold.
+   * @param files - What was dropped or chosen.
+   * @returns Once every file has been read.
+   */
+  readFiles: (files: readonly File[]) => Promise<void>;
+}
+
+/**
+ * Read files into the viewer this is called inside.
+ * @returns How to read them.
+ */
+export function useMassFiles(): MassFiles {
+  const { state } = useMassEditorState();
+  const actions = useMassActions();
+  const { spectra: open } = state.data;
+
+  const readFiles = useCallback(
+    async (files: readonly File[]) => {
+      // Read together, since each read is the browser's work rather than ours,
+      // and then dressed in the order the files were given, so the colours are
+      // handed out in that order too.
+      const results = await Promise.all(files.map(readFile));
+      const colors = open.map((spectrum) => spectrum.color);
+      const read: MassSpectrum[] = [];
+      const problems: string[] = [];
+      for (const [index, result] of results.entries()) {
+        const name = files[index]?.name ?? 'A file';
+        if (typeof result === 'string') {
+          problems.push(result);
+          continue;
+        }
+        try {
+          const spectra = toMassSpectra(result.spectra, { taken: colors });
+          for (const spectrum of spectra) colors.push(spectrum.color);
+          read.push(...spectra);
+        } catch (error) {
+          problems.push(
+            `${name} could not be peak picked — ${errorMessage(error)}`,
+          );
+          continue;
+        }
+        if (result.dropped > 0) {
+          problems.push(
+            `${name} holds ${result.spectra.length + result.dropped} spectra and only the first ${result.spectra.length} were read.`,
+          );
+        }
+      }
+      if (read.length > 0) actions.addSpectra(read);
+      // After the spectra, which clear any error standing from before.
+      if (problems.length > 0) actions.setError(problems.join(' '));
+    },
+    [actions, open],
+  );
+
+  return useMemo(() => ({ readFiles }), [readFiles]);
+}
+
+/**
+ * Read one file, saying why when it cannot be.
+ * @param file - The file.
+ * @returns What it held, or the sentence its refusal came with.
+ */
+async function readFile(file: File): Promise<LoadMassSpectraResult | string> {
+  try {
+    const bytes = new Uint8Array(await file.arrayBuffer());
+    return await loadMassSpectra(bytes, { fileName: file.name });
+  } catch (error) {
+    return errorMessage(error);
+  }
+}

package/src/mass/ui/useMassHandle.ts

@@ -0,0 +1,58 @@
+/**
+ * The handle a host drives the viewer through, filled in from its state.
+ *
+ * A hook of its own beside the shell, because every gesture on the handle reads
+ * the state the shell already reads — and the shell is long enough without it.
+ */
+
+import type { Ref } from 'react';
+import { useImperativeHandle } from 'react';
+
+import { mzFrame } from '../core/massDomain.ts';
+import type {
+  MassEditorHandle,
+  ZoomToMzOptions,
+} from '../core/massEditorApi.ts';
+
+import { useMassActions, useMassEditorState } from './massStateContext.ts';
+
+/**
+ * Fill in a host's handle on the viewer this is called inside.
+ * @param handle - The handle to fill in, if the host asked for one.
+ * @param readFiles - How a file is read into the viewer, as a drop reads it.
+ */
+export function useMassHandle(
+  handle: Ref<MassEditorHandle> | undefined,
+  readFiles: (files: readonly File[]) => Promise<void>,
+): void {
+  const { state, visibleSpectra } = useMassEditorState();
+  const actions = useMassActions();
+  const { domain } = state.view;
+
+  useImperativeHandle(
+    handle,
+    (): MassEditorHandle => ({
+      getSpectra: () => state.data.spectra,
+      setSpectra: (spectra) => actions.setSpectra(spectra),
+      addSpectra: (spectra) => actions.addSpectra(spectra),
+      openFiles: (files) => readFiles(files),
+      clear: () => actions.clear(),
+      setDomain: (next) => actions.setDomain(next),
+      resetDomain: () => actions.resetDomain(),
+      zoomToMz: (mz, options: ZoomToMzOptions = {}) => {
+        actions.setDomain(
+          mzFrame(
+            mz,
+            visibleSpectra,
+            domain,
+            options.halfWidth === undefined
+              ? {}
+              : { halfWidth: options.halfWidth },
+          ),
+        );
+      },
+      selectSpectrum: (id) => actions.selectSpectrum(id),
+    }),
+    [state.data.spectra, actions, readFiles, domain, visibleSpectra],
+  );
+}

package/src/mass/ui/useMassPointer.ts

@@ -0,0 +1,120 @@
+/**
+ * What a mass chart reads under the pointer, and which peak it is asking about.
+ *
+ * Following the pointer at all is `useChartPointer` in the shared chart:
+ * placing it in user units, refusing the margins, and reporting only when the
+ * answer changed. What it *reads* there is the part that is about mass, and is
+ * the whole of this file — the m/z, the intensity, and the peak within reach.
+ */
+
+import type { RefObject } from 'react';
+import { useCallback, useMemo } from 'react';
+
+import type { PlotRect } from '../../chart/core/chartGeometry.ts';
+import type { ChartScale } from '../../chart/core/chartScale.ts';
+import { chartValue } from '../../chart/core/chartScale.ts';
+import type { ChartPoint } from '../../chart/core/svgPoint.ts';
+import type { ChartPointer } from '../../chart/ui/useChartPointer.ts';
+import { useChartPointer } from '../../chart/ui/useChartPointer.ts';
+import type { MassSpectrum } from '../core/massSpectrum.ts';
+import type { NearestPeak } from '../core/nearestPeak.ts';
+import { nearestPeakMz, sameNearestPeak } from '../core/nearestPeak.ts';
+
+/** What the axes say under the pointer, which is what a readout prints. */
+export interface MassReadout {
+  /** What the m/z axis reads there. */
+  mz: number;
+  /** What the intensity axis reads there. */
+  intensity: number;
+  /** The peak within reach of the pointer, `null` when none is. */
+  peak: NearestPeak | null;
+}
+
+export interface MassPointerOptions {
+  /** The SVG the chart is drawn on, as it was handed to its `ref`. */
+  svgRef: RefObject<SVGSVGElement | null>;
+  /** Where the plot sits inside that SVG. */
+  plot: PlotRect;
+  /** The m/z axis as it is currently zoomed. */
+  xScale: ChartScale;
+  /** The intensity axis as it is currently zoomed. */
+  yScale: ChartScale;
+  /** What the chart draws, for the peak under the pointer to be found. */
+  spectra: readonly MassSpectrum[];
+  /**
+   * Told which peak the pointer has come to rest on, and told `null` when it
+   * leaves one — called only when the answer changes, so it is safe to hang a
+   * highlight that redraws half the page on it.
+   * @default undefined
+   */
+  onPeak?: (peak: NearestPeak | null) => void;
+  /**
+   * Told when the pointer leaves the plot, and only then.
+   *
+   * `onPeak` says `null` for the gap between two sticks as well, so it cannot
+   * be read as the reading being over — which is the one thing a host drawing a
+   * picture of whatever is crossed has to know.
+   * @default undefined
+   */
+  onAway?: () => void;
+}
+
+/**
+ * Follow the pointer over a mass chart.
+ * @param options - The chart, its axes and what it holds.
+ * @returns Where the pointer is and what it reads, both `null` while it is
+ * anywhere but over the plot.
+ */
+export function useMassPointer(
+  options: MassPointerOptions,
+): ChartPointer<MassReadout> {
+  const { svgRef, plot, xScale, yScale, spectra, onPeak, onAway } = options;
+
+  const read = useCallback(
+    (point: ChartPoint): MassReadout => ({
+      mz: chartValue(xScale, point.x),
+      intensity: chartValue(yScale, point.y),
+      peak: nearestPeakMz(spectra, xScale, point.x),
+    }),
+    [xScale, yScale, spectra],
+  );
+
+  const onReadout = useMemo(
+    () =>
+      onPeak === undefined && onAway === undefined
+        ? undefined
+        : (readout: MassReadout | null) => {
+            onPeak?.(readout?.peak ?? null);
+            // Only the whole reading is absent off the plot: inside it there is
+            // always an m/z and an intensity, whether or not a stick is within
+            // reach. So this is the leave, and the `null` peak above is not.
+            if (readout === null) onAway?.();
+          },
+    [onPeak, onAway],
+  );
+
+  return useChartPointer({
+    svgRef,
+    plot,
+    read,
+    sameReadout: sameMassReadout,
+    onReadout,
+  });
+}
+
+/**
+ * Whether two readings are about the same peak.
+ *
+ * The peak alone, and never the m/z under the crosshair: that fractional value
+ * changes on every pixel the pointer moves, and comparing it would report a new
+ * answer for every tremor of a hand resting on one stick.
+ * @param current - What was last read.
+ * @param next - What has just been read.
+ * @returns Whether both are about the same peak.
+ */
+export function sameMassReadout(
+  current: MassReadout,
+  next: MassReadout,
+): boolean {
+  return sameNearestPeak(current.peak, next.peak);
+}

package/src/mass/ui/useMassShortcuts.ts

@@ -0,0 +1,85 @@
+/**
+ * The keys, heard on the viewer's own root rather than on the document.
+ *
+ * Two viewers on one page must not both answer `f`, and a page that holds this
+ * beside an infrared viewer must not have its own keys eaten. So the viewer
+ * hears a key only while it holds the caret — the root carries `tabIndex={-1}`
+ * so a click anywhere in it does — and a key it acted on goes no further.
+ */
+
+import { useEffect, useLayoutEffect, useRef } from 'react';
+
+import { isEditingField } from '../../panel/core/isEditingField.ts';
+import type {
+  MassCommand,
+  MassCommandHandlers,
+  MassCommandId,
+} from '../core/massCommands.ts';
+import { massCommands } from '../core/massCommands.ts';
+
+/**
+ * Fire the viewer's commands from the keyboard.
+ *
+ * The handlers are read live through a ref rather than closed over, so the
+ * listener is attached once for the life of the viewer instead of being torn
+ * down and rebuilt on every render — and the chart re-renders on every move of
+ * the pointer across it.
+ * @param root - The viewer's root, `null` until it is mounted.
+ * @param handlers - What each command does.
+ */
+export function useMassShortcuts(
+  root: HTMLElement | null,
+  handlers: MassCommandHandlers,
+): void {
+  const latest = useRef(handlers);
+
+  useLayoutEffect(() => {
+    latest.current = handlers;
+  });
+
+  useEffect(() => {
+    if (root === null) return;
+
+    /**
+     * Run the command a key names, if it names one.
+     * @param event - The key that arrived.
+     */
+    function onKeyDown(event: KeyboardEvent): void {
+      // A key pressed with a modifier belongs to the browser or to the page:
+      // Ctrl+F is a search, and a viewer that swallowed it to fit its chart
+      // would be a viewer people stop typing in.
+      if (event.ctrlKey || event.metaKey || event.altKey) return;
+      // Never while a name is being typed into the spectra panel.
+      if (isEditingField(event.target)) return;
+
+      const id = KEYS.get(event.key.toLowerCase());
+      if (id === undefined) return;
+      const handler = latest.current[id];
+      if (handler === undefined) return;
+
+      event.preventDefault();
+      // So the same key does not also reach a viewer mounted beside this one.
+      event.stopPropagation();
+      handler();
+    }
+
+    root.addEventListener('keydown', onKeyDown);
+    return () => {
+      root.removeEventListener('keydown', onKeyDown);
+    };
+  }, [root]);
+}
+
+/**
+ * Every key the viewer answers to, against the command it runs — built once
+ * from the command table, lower-cased so a capital arriving from a held shift
+ * still reaches the command a lowercase key names.
+ */
+const KEYS = new Map<string, MassCommandId>(
+  Object.entries(massCommands as Record<string, MassCommand>).flatMap(
+    ([id, command]) =>
+      (command.shortcut?.keys ?? []).map(
+        (key) => [key.toLowerCase(), id as MassCommandId] as const,
+      ),
+  ),
+);

package/src/mass/ui/useMassSide.ts

@@ -0,0 +1,63 @@
+/**
+ * The side of the viewer: the panels it offers, whether any of them is open,
+ * and what dragging the splitter shut and back open does to them.
+ *
+ * A hook of its own beside the shell, because the shell lays the side out and
+ * this decides what is on it.
+ */
+
+import { useMemo } from 'react';
+
+import { DEFAULT_SIDE_PANEL } from '../core/massState.ts';
+
+import type { MassHostPanel, MassStackPanel } from './massHostPanels.ts';
+import { massStackPanels } from './massHostPanels.ts';
+import { useMassActions, useMassEditorState } from './massStateContext.ts';
+
+/** The side, as the shell lays it out. */
+export interface MassSide {
+  /** Every panel on offer, in the order their icons are stacked. */
+  panels: readonly MassStackPanel[];
+  /** Whether a panel on offer is open, which is whether the side is. */
+  isOpen: boolean;
+  /**
+   * Open or close the side, as the splitter is dragged shut and back open.
+   * @param open - Whether the side is now open.
+   */
+  setOpen: (open: boolean) => void;
+}
+
+/**
+ * The side of the viewer this is called inside.
+ * @param hostPanels - The panels the host adds to the viewer's own.
+ * @returns The panels on offer, whether the side is open, and how to open it.
+ */
+export function useMassSide(hostPanels: readonly MassHostPanel[]): MassSide {
+  const { state } = useMassEditorState();
+  const actions = useMassActions();
+  const { openPanelIds } = state.view;
+
+  const panels = useMemo(() => massStackPanels(hostPanels), [hostPanels]);
+  // Read off the panels on offer rather than off the ids: an id no panel
+  // answers to opens nothing, and a side open on it alone is an empty column.
+  const isOpen = useMemo(() => {
+    const open = new Set<string>(openPanelIds);
+    return panels.some((panel) => open.has(panel.id));
+  }, [panels, openPanelIds]);
+
+  /**
+   * Open or close the side.
+   * @param open - Whether the side is now open.
+   */
+  function setOpen(open: boolean): void {
+    if (!open) {
+      for (const panelId of openPanelIds) actions.togglePanel(panelId);
+      return;
+    }
+    // Dragging the splitter back open must land on something, or it opens on an
+    // empty column and reads as broken.
+    if (!isOpen) actions.togglePanel(DEFAULT_SIDE_PANEL);
+  }
+
+  return { panels, isOpen, setOpen };
+}

package/src/mass/ui/useMassZoom.ts

@@ -0,0 +1,157 @@
+/**
+ * The generic zoom, told what a mass spectrum's window is fitted to.
+ *
+ * Every gesture — the drag, the wheel, the double click — is `useChartZoom` in
+ * the shared chart and is not written here, because none of it is about mass.
+ * What *is* about mass is the fit: a spectrum carries two traces where only one
+ * is drawn, and a previewed pattern is left out of the extents. That arithmetic
+ * is `massDomain.ts`, and this hook is what joins the two.
+ *
+ * One gesture is about mass in the same way. A click on a mass chart is a peak
+ * or it is nothing at all, and only the axis the gesture was measured against
+ * can say which of the two it was — so the hook that owns that axis answers it,
+ * and the chart above is handed the peak rather than a place on the plot.
+ */
+
+import type { RefObject } from 'react';
+import { useCallback, useLayoutEffect, useMemo, useRef } from 'react';
+
+import type { ZoomDragMode } from '../../chart/core/chartDomain.ts';
+import type { PlotRect } from '../../chart/core/chartGeometry.ts';
+import type { ChartScale } from '../../chart/core/chartScale.ts';
+import type { ChartPoint } from '../../chart/core/svgPoint.ts';
+import type { ChartClickModifiers } from '../../chart/ui/chartGestures.ts';
+import type { ChartZoom } from '../../chart/ui/useChartZoom.ts';
+import { useChartZoom } from '../../chart/ui/useChartZoom.ts';
+import { fittedTo, fullDomain } from '../core/massDomain.ts';
+import type { MassDomain, MassSpectrum } from '../core/massSpectrum.ts';
+import type { NearestPeak } from '../core/nearestPeak.ts';
+import { peakAtMz } from '../core/nearestPeak.ts';
+
+/** A click on the plot, with everything needed to say what it was on. */
+export interface MassZoomClick {
+  /** Where it landed on the m/z axis. */
+  mz: number;
+  /** The picked peak within reach of it, `null` when it landed on none. */
+  peak: NearestPeak | null;
+  /**
+   * The m/z axis the click was measured against, for a host testing marks of
+   * its own — a ring on a fragmented peak — before the sticks.
+   */
+  xScale: ChartScale;
+  /** The modifier keys held as the button came up. */
+  modifiers: ChartClickModifiers;
+}
+
+export interface MassZoomOptions {
+  /** What the chart draws. */
+  spectra: readonly MassSpectrum[];
+  /**
+   * What the window is fitted to instead, when that is not what the chart
+   * draws — every pane of a stack is fitted to the union, so a faint spectrum
+   * and a bright one are not drawn alike.
+   * @default the spectra the chart draws
+   */
+  fitTo?: readonly MassSpectrum[];
+  /**
+   * Whether one spectrum is drawn below the axis, which fits the window about
+   * zero.
+   * @default false
+   */
+  mirror?: boolean;
+  /** The SVG the gestures are made on, as it was handed to its `ref`. */
+  svgRef: RefObject<SVGSVGElement | null>;
+  /** Where the plot sits inside that SVG, which the axes are laid over. */
+  plot: PlotRect;
+  /**
+   * The window a host is imposing, `null` while it imposes none. Handed straight
+   * through; `useChartZoom` documents what imposing one does.
+   * @default null
+   */
+  domain?: MassDomain | null;
+  /**
+   * What a drag asks for: the m/z axis alone, or the rectangle swept out.
+   * @default 'xAxis'
+   */
+  drag?: ZoomDragMode;
+  /**
+   * Whether the chart answers `f` with the fit itself. A viewer running its own
+   * keys through a command table, where the key is documented, turns it off.
+   * @default true
+   */
+  keys?: boolean;
+  /**
+   * Told where a click on the plot landed — a press let go over it without
+   * travelling, never the end of a drag — and the peak within reach of it.
+   * @default undefined
+   */
+  onClick?: (click: MassZoomClick) => void;
+}
+
+/**
+ * Zoom a mass chart by dragging it, by the wheel and by double clicking it.
+ *
+ * The y axis keeps its default rules, which are a stick spectrum's: zero is the
+ * baseline the wheel scales about, and it stays inside the window however the
+ * chart is zoomed, because a window starting at a tenth of the base peak would
+ * cut every stick off at the ankles.
+ * @param options - The chart and what it holds.
+ * @returns The window and the gestures that move it.
+ */
+export function useMassZoom(options: MassZoomOptions): ChartZoom {
+  const {
+    spectra,
+    fitTo,
+    mirror = false,
+    svgRef,
+    plot,
+    domain = null,
+    drag = 'xAxis',
+    keys = true,
+    onClick,
+  } = options;
+
+  const measured = fitTo ?? spectra;
+  const fitted = useMemo(
+    () => fullDomain(measured, mirror),
+    [measured, mirror],
+  );
+  const fitKey = useMemo(() => fittedTo(measured, mirror), [measured, mirror]);
+  const gestures = useMemo(() => ({ drag, wheel: true, keys }), [drag, keys]);
+
+  // The axis a click is measured against is the one the zoom arrived at, and
+  // the click comes back out of that same hook: it therefore reaches the
+  // handler through a ref, read as the button comes up rather than closed over
+  // when the gesture layer was built.
+  const axis = useRef<ChartScale | null>(null);
+
+  const onPress = useCallback(
+    (point: ChartPoint, modifiers: ChartClickModifiers) => {
+      const xScale = axis.current;
+      if (xScale === null || onClick === undefined) return;
+      onClick({
+        mz: point.x,
+        peak: peakAtMz(spectra, xScale, point.x),
+        xScale,
+        modifiers,
+      });
+    },
+    [spectra, onClick],
+  );
+
+  const zoom = useChartZoom({
+    fitted,
+    fitKey,
+    svgRef,
+    plot,
+    domain,
+    gestures,
+    ...(onClick === undefined ? {} : { onClick: onPress }),
+  });
+
+  useLayoutEffect(() => {
+    axis.current = zoom.xScale;
+  });
+
+  return zoom;
+}

package/src/mass.ts

@@ -0,0 +1,16 @@
+/**
+ * Displaying mass spectra: the chart, the peak table and the whole editor.
+ *
+ * A door of its own, and not part of `react-cheminfo/core` or
+ * `react-cheminfo/ui`, because reading a spectrum drags the formats it may
+ * arrive in — `jcampconverter` and `xy-parser` for the files, `ms-spectrum` and
+ * `ml-gsd` for the peak picking, `convert-to-jcamp` for writing them back out.
+ * A site with no spectra to look at installs none of it.
+ *
+ * The infrared viewer, `react-cheminfo/ir`, is its sibling: the same shell, the
+ * same three buckets of state, the same chart underneath. Neither imports the
+ * other.
+ */
+
+export * from './mass/core/index.ts';
+export * from './mass/ui/index.ts';

package/src/panel/ui/PanelRail.tsx

@@ -51,8 +51,12 @@ export function PanelRail<TId extends string>(
     <ActivityBar>
       {panels.map((panel) => (
         <ActivityBar.Item
+          // The panel id goes on a data attribute rather than on `id`: it is
+          // unique within one rail, not on the page, and a page can hold two —
+          // AGA2S hands the mass viewer the glycan editor's own panels, so both
+          // rails carry `fragments`.
+          data-panel-id={panel.id}
           key={panel.id}
-          id={panel.id}
           icon={panel.icon}
           tooltip={panel.title}
           // A tooltip is not an accessible name: without this every toggle is