react-cheminfo 0.69.0 → 0.71.0

package/src/mass/ui/massActions.ts

@@ -0,0 +1,109 @@
+/**
+ * Everything the viewer can be asked to do, as functions rather than actions.
+ *
+ * A component that dispatched action objects would have the shape of the reducer
+ * spread across every panel; one that calls `actions.selectSpectrum(id)` does
+ * not, and the reducer stays free to change how it holds things.
+ */
+
+import type { Dispatch } from 'react';
+
+import type { MassAction, SpectrumVisibility } from '../core/massReducer.ts';
+import type { MassPanelId } from '../core/massSidePanels.ts';
+import type { MassDomain, MassSpectrum } from '../core/massSpectrum.ts';
+import type {
+  MassSettings,
+  MassTool,
+  PartialMassState,
+} from '../core/massState.ts';
+
+/** Everything the viewer can be asked to do. */
+export interface MassEditorActions {
+  /** Draw these as well as what is already open. */
+  addSpectra: (spectra: MassSpectrum[]) => void;
+  /** Draw these instead of what is open, and refit the window to them. */
+  setSpectra: (spectra: MassSpectrum[]) => void;
+  /** Close one. */
+  removeSpectrum: (id: string) => void;
+  /** Call one something else. */
+  renameSpectrum: (id: string, name: string) => void;
+  /** Draw one in another colour. */
+  setSpectrumColor: (id: string, color: string) => void;
+  /** Draw one as its profile, as its sticks, or not at all. */
+  setSpectrumVisibility: (id: string, visibility: SpectrumVisibility) => void;
+  /** Point the panels at one, or at none. */
+  selectSpectrum: (id: string | null) => void;
+  /** Show this window. */
+  setDomain: (domain: MassDomain) => void;
+  /** Show what fits again. */
+  resetDomain: () => void;
+  /** Run this tool on the next drag. */
+  setTool: (tool: MassTool) => void;
+  /** Open or close a side panel, the viewer's own or one a host added. */
+  togglePanel: (panelId: MassPanelId) => void;
+  /** Say why something was refused, or that nothing is wrong any more. */
+  setError: (error: string | null) => void;
+  /** Change how the spectra are drawn. */
+  setSettings: (settings: Partial<MassSettings>) => void;
+  /** Take a whole state, as a host restoring one supplies it. */
+  loadState: (state: PartialMassState) => void;
+  /** Close every spectrum and start again from an empty chart. */
+  clear: () => void;
+}
+
+/**
+ * Bind every action to a dispatch.
+ * @param dispatch - The reducer's dispatch.
+ * @returns The actions, stable for as long as the dispatch is.
+ */
+export function createMassActions(
+  dispatch: Dispatch<MassAction>,
+): MassEditorActions {
+  return {
+    addSpectra(spectra) {
+      dispatch({ type: 'addSpectra', spectra });
+    },
+    setSpectra(spectra) {
+      dispatch({ type: 'setSpectra', spectra });
+    },
+    removeSpectrum(id) {
+      dispatch({ type: 'removeSpectrum', id });
+    },
+    renameSpectrum(id, name) {
+      dispatch({ type: 'renameSpectrum', id, name });
+    },
+    setSpectrumColor(id, color) {
+      dispatch({ type: 'setSpectrumColor', id, color });
+    },
+    setSpectrumVisibility(id, visibility) {
+      dispatch({ type: 'setSpectrumVisibility', id, visibility });
+    },
+    selectSpectrum(id) {
+      dispatch({ type: 'selectSpectrum', id });
+    },
+    setDomain(domain) {
+      dispatch({ type: 'setDomain', domain });
+    },
+    resetDomain() {
+      dispatch({ type: 'resetDomain' });
+    },
+    setTool(tool) {
+      dispatch({ type: 'setTool', tool });
+    },
+    togglePanel(panelId) {
+      dispatch({ type: 'togglePanel', panelId });
+    },
+    setError(error) {
+      dispatch({ type: 'setError', error });
+    },
+    setSettings(settings) {
+      dispatch({ type: 'setSettings', settings });
+    },
+    loadState(state) {
+      dispatch({ type: 'loadState', state });
+    },
+    clear() {
+      dispatch({ type: 'clear' });
+    },
+  };
+}

package/src/mass/ui/massChartProps.ts

@@ -0,0 +1,130 @@
+/**
+ * What a consumer hands the chart, and what the chart tells it back.
+ *
+ * Held apart from the component because it is the whole of the chart's public
+ * API — every spectrum drawn, every peak labelled on it and every gesture that
+ * comes back out is one of these — while the component behind it is an assembly
+ * of half a dozen layers nobody needs to read in order to mount one.
+ *
+ * Everything arrives as a prop and nothing is reached for: the chart reads no
+ * store and no context, so the same component serves an editor, a report page
+ * that only ever draws one spectrum, and a test.
+ */
+
+import type { ReactNode } from 'react';
+
+import type { ZoomDragMode } from '../../chart/core/chartDomain.ts';
+import type { MassDomain, MassSpectrum } from '../core/massSpectrum.ts';
+import type { NearestPeak } from '../core/nearestPeak.ts';
+
+export interface MassChartProps {
+  /** The spectra to draw, each saying in itself which of its traces is drawn. */
+  spectra: readonly MassSpectrum[];
+  /**
+   * Identity of the spectrum whose peaks are labelled, `null` for none. One
+   * spectrum and never all of them: two stacks over every shared peak are the
+   * same m/z written twice, a pixel apart, in two colours.
+   * @default the first spectrum drawn
+   */
+  labelledId?: string | null;
+  /**
+   * Whether that spectrum's peaks are labelled at all.
+   * @default true
+   */
+  showLabels?: boolean;
+  /**
+   * At most how many peaks are labelled; every labelled one is still marked.
+   * @default DEFAULT_LABEL_LIMIT
+   */
+  labelLimit?: number;
+  /**
+   * Whether a label writes the charge of a peak whose charge was established.
+   * @default false
+   */
+  showCharges?: boolean;
+  /**
+   * How many decimals every mass is written with, overriding what the spectra
+   * resolve — where the labels follow the labelled spectrum's own resolution,
+   * and the crosshair what the drawn spectra resolve together.
+   * @default what the spectra resolve, as `mzDecimalsOf` decides
+   */
+  mzDecimals?: number;
+  /**
+   * What explains a peak, keyed as `peakKey` keys it — the name written on top
+   * of its label. This is how a host annotates peaks without the chart having
+   * to know where the names came from.
+   * @default undefined
+   */
+  annotationLabels?: ReadonlyMap<string, string>;
+  /**
+   * The m/z a guide is drawn at, `null` for none — the peak a row of a table
+   * beside the chart is resting on.
+   * @default null
+   */
+  highlightMz?: number | null;
+  /**
+   * Told which picked peak the pointer has come to rest on, and told `null` when
+   * it leaves one — called only when the answer changes.
+   * @default undefined
+   */
+  onPeakHover?: (peak: NearestPeak | null) => void;
+  /**
+   * The window to show, `null` to let the chart show what fits.
+   *
+   * The chart holds a window of its own, so this is an override rather than the
+   * chart's state: every window a gesture arrives at is reported through
+   * `onDomainChange`, and a host that keeps one is expected to hand back what it
+   * is told. Handing back `null` where a window was is how a host asks for the
+   * fit again.
+   * @default null
+   */
+  domain?: MassDomain | null;
+  /**
+   * Told the window the chart has come to show, whenever it changes — a drag, a
+   * turn of the wheel, the double click that fits everything again, or a refit
+   * after what is drawn changed.
+   * @default undefined
+   */
+  onDomainChange?: (domain: MassDomain) => void;
+  /**
+   * Told where a click on the plot landed, in m/z, and the picked peak within
+   * reach of it — `null` when it landed on none. The end of a drag is never a
+   * click.
+   * @default undefined
+   */
+  onPlotClick?: (mz: number, peak: NearestPeak | null) => void;
+  /**
+   * What a drag across the plot asks for: the m/z axis alone, or exactly the
+   * rectangle it sweeps out.
+   * @default 'xAxis'
+   */
+  drag?: ZoomDragMode;
+  /**
+   * Whether the chart answers `f` with the fit itself. A viewer around it that
+   * runs its keys through a command table turns this off.
+   * @default true
+   */
+  answersKeys?: boolean;
+  /**
+   * Identity of the spectrum drawn thicker than the rest, `null` for none.
+   * @default null
+   */
+  emphasisedId?: string | null;
+  /**
+   * How wide the chart is drawn, in pixels.
+   * @default the width of its container
+   */
+  width?: number;
+  /**
+   * How tall it is drawn, in pixels.
+   * @default the height of its container
+   */
+  height?: number;
+  /**
+   * Anything else to draw over the spectra, in the same pixels and under the
+   * same clip. Rendered last inside the plot, so a host adds to the chart
+   * instead of forking it.
+   * @default undefined
+   */
+  children?: ReactNode;
+}

package/src/mass/ui/massCommandContext.tsx

@@ -0,0 +1,65 @@
+/**
+ * How a component reaches the commands, and what a toolbar item needs to be one.
+ *
+ * The hooks and the context object, with no component of its own: a module that
+ * exports a component and a constant together cannot be hot reloaded, which is
+ * why the provider and the tooltip are files of their own beside this one.
+ */
+
+import { createContext, useContext } from 'react';
+
+import type {
+  MassCommandHandlers,
+  MassCommandId,
+  RunMassCommand,
+} from '../core/massCommands.ts';
+import { massCommandLabel } from '../core/massCommands.ts';
+
+import { MassCommandTooltip } from './MassCommandTooltip.tsx';
+
+/** What the provider holds. */
+export interface MassCommandContextValue {
+  /** What each command does. */
+  handlers: MassCommandHandlers;
+  /** Run one. */
+  run: RunMassCommand;
+}
+
+/** Where the provider puts it. */
+export const massCommandContext = createContext<MassCommandContextValue | null>(
+  null,
+);
+
+/**
+ * Run a command from anywhere inside the viewer.
+ * @returns The runner; a command nothing handles does nothing.
+ */
+export function useMassCommand(): RunMassCommand {
+  const value = useContext(massCommandContext);
+  return value?.run ?? noRun;
+}
+
+/**
+ * Everything a toolbar item needs to be one command, in one spread.
+ *
+ * The tooltip, the label a screen reader is given and the click handler all come
+ * from the same table entry, so a button cannot end up titled one thing and
+ * doing another.
+ * @returns A function from a command's identity to the props for its button.
+ */
+export function useMassCommandProps() {
+  const run = useMassCommand();
+  return function command(id: MassCommandId) {
+    return {
+      tooltip: <MassCommandTooltip id={id} />,
+      'aria-label': massCommandLabel(id),
+      onClick: () => run(id),
+    };
+  };
+}
+
+/** What running a command comes to outside a provider: nothing at all. */
+function noRun(): void {
+  // Deliberately empty: a chart mounted without the shell has no commands, and
+  // a missing provider is not a reason to throw at a button press.
+}

package/src/mass/ui/massHostPanels.ts

@@ -0,0 +1,71 @@
+/**
+ * The panels a host adds to the viewer's own, and the one list both make.
+ *
+ * A host panel is a panel like any other once it is in the list: the activity
+ * bar and the stack read the same list, so it toggles, folds and closes exactly
+ * as the spectra or the peaks do. The host brings the body and nothing else —
+ * the header, its close button and the place in the column are the viewer's,
+ * which is what keeps every header reading the same.
+ */
+
+import type { IconName } from '@blueprintjs/core';
+import type { ReactNode } from 'react';
+
+import { massSidePanels } from '../core/massSidePanels.ts';
+
+/** A panel the host adds to the editor's own stack. */
+export interface MassHostPanel {
+  /**
+   * Its identity in the activity bar and in `defaultPanelIds`; never a built-in
+   * id. One that is, or that an earlier host panel already took, is left out:
+   * one icon cannot open two panels.
+   */
+  id: string;
+  /** What its header and its activity-bar item say. */
+  title: string;
+  /** Its glyph in the activity bar (a Blueprint IconName). */
+  icon: IconName;
+  /**
+   * Its body. It brings its own toolbar as first row: the header carries the
+   * close button only. It is rendered inside the viewer, so a component in it
+   * reaches the viewer it stands in through `useMassEditorState` and
+   * `useMassActions` — to overlay a predicted isotopic pattern, say.
+   */
+  content: ReactNode;
+}
+
+/** One panel of the side: one of the viewer's own, or one a host added. */
+export type MassStackPanel = (typeof massSidePanels)[number] | MassHostPanel;
+
+/**
+ * Every panel the side offers, in the order the activity bar stacks them: the
+ * host's first, in the order given, then the viewer's own.
+ * @param hostPanels - What the host adds.
+ * @returns The panels; the viewer's own list itself when the host adds none.
+ */
+export function massStackPanels(
+  hostPanels: readonly MassHostPanel[],
+): readonly MassStackPanel[] {
+  if (hostPanels.length === 0) return massSidePanels;
+  const taken = new Set<string>(BUILT_IN_IDS);
+  const panels: MassStackPanel[] = [];
+  for (const panel of hostPanels) {
+    if (taken.has(panel.id)) continue;
+    taken.add(panel.id);
+    panels.push(panel);
+  }
+  panels.push(...massSidePanels);
+  return panels;
+}
+
+/**
+ * Whether a panel of the side is one a host added, whose body it brings.
+ * @param panel - The panel.
+ * @returns True for a host's panel.
+ */
+export function isMassHostPanel(panel: MassStackPanel): panel is MassHostPanel {
+  return 'content' in panel;
+}
+
+/** The ids no host panel may take. */
+const BUILT_IN_IDS: readonly string[] = massSidePanels.map((panel) => panel.id);

package/src/mass/ui/massStateContext.ts

@@ -0,0 +1,48 @@
+/**
+ * How a panel reaches the viewer it is inside.
+ *
+ * Two contexts rather than one, because the actions never change while the state
+ * changes on every drag of the chart: a panel that only ever acts — a toolbar
+ * button — reads the second and is not re-rendered by the first.
+ */
+
+import { createContext, useContext } from 'react';
+
+import type { MassEditorActions } from './massActions.ts';
+import type { MassEditorApi } from './useMassEditor.ts';
+
+/** Everything one viewer knows, as the provider holds it. */
+export const massStateContext = createContext<MassEditorApi | null>(null);
+
+/** Everything that changes it, as the provider holds it. */
+export const massActionsContext = createContext<MassEditorActions | null>(null);
+
+/**
+ * Everything the viewer knows, from inside it.
+ * @returns The state and what follows from it.
+ * @throws {Error} When read outside a `MassStateProvider`.
+ */
+export function useMassEditorState(): MassEditorApi {
+  const editor = useContext(massStateContext);
+  if (editor === null) {
+    throw new Error(
+      'The mass spectrum viewer state was read outside a MassStateProvider',
+    );
+  }
+  return editor;
+}
+
+/**
+ * Everything to do, from inside the viewer.
+ * @returns The actions.
+ * @throws {Error} When read outside a `MassStateProvider`.
+ */
+export function useMassActions(): MassEditorActions {
+  const actions = useContext(massActionsContext);
+  if (actions === null) {
+    throw new Error(
+      'The mass spectrum viewer actions were read outside a MassStateProvider',
+    );
+  }
+  return actions;
+}

package/src/mass/ui/useIntensityZoom.ts

@@ -0,0 +1,55 @@
+/**
+ * The zoom in and zoom out commands, which scale the intensity axis alone.
+ *
+ * They scale it about zero, the baseline every stick stands on, so a small peak
+ * comes up out of the baseline rather than the whole spectrum drifting off the
+ * plot — what a turn of the wheel does, at the speed of a key press.
+ */
+
+import { useMemo } from 'react';
+
+import { fullDomain } from '../core/massDomain.ts';
+
+import { useMassActions, useMassEditorState } from './massStateContext.ts';
+
+/** The two commands, ready to hand to a button or a key. */
+export interface IntensityZoom {
+  /** Bring the peaks up by one step. */
+  zoomIn: () => void;
+  /** Put the axis back out by one step. */
+  zoomOut: () => void;
+}
+
+/**
+ * Zoom the intensity axis of the viewer this is called inside.
+ * @returns The two commands.
+ */
+export function useIntensityZoom(): IntensityZoom {
+  const { state, visibleSpectra } = useMassEditorState();
+  const actions = useMassActions();
+  const { domain } = state.view;
+
+  return useMemo(() => {
+    /**
+     * Scale the intensity axis by a factor, about zero.
+     * @param factor - Above one to zoom out.
+     */
+    function scale(factor: number): void {
+      const shown = domain ?? fullDomain(visibleSpectra);
+      actions.setDomain({
+        x: shown.x,
+        y: [shown.y[0] * factor, shown.y[1] * factor],
+      });
+    }
+    return {
+      zoomIn: () => scale(1 / ZOOM_STEP),
+      zoomOut: () => scale(ZOOM_STEP),
+    };
+  }, [actions, domain, visibleSpectra]);
+}
+
+/**
+ * What one press of zoom in or out is worth: about what one notch of a mouse
+ * wheel does, so the button and the wheel feel like one gesture at two speeds.
+ */
+const ZOOM_STEP = 1.2;

package/src/mass/ui/useMassEditor.ts

@@ -0,0 +1,156 @@
+/**
+ * One viewer's state, and everything derived from it.
+ *
+ * What is derived here is what three panels and the chart read alike — which
+ * spectra are drawn, which one is selected, and how many decimals every mass on
+ * screen is written with — so it is worked out once per change rather than once
+ * per reader.
+ */
+
+import { useEffect, useMemo, useReducer, useRef } from 'react';
+
+import { massReducer } from '../core/massReducer.ts';
+import type { MassSpectrum } from '../core/massSpectrum.ts';
+import { isSpectrumDrawn } from '../core/massSpectrum.ts';
+import type { CreateMassStateOptions, MassState } from '../core/massState.ts';
+import { createMassState } from '../core/massState.ts';
+import { mzDecimalsFor } from '../core/mzDecimalsSetting.ts';
+import { mzDecimalsOf } from '../core/resolutionOf.ts';
+
+import type { MassEditorActions } from './massActions.ts';
+import { createMassActions } from './massActions.ts';
+
+/** What a viewer opens on, and who to tell when the spectra change. */
+export interface UseMassEditorOptions extends CreateMassStateOptions {
+  /**
+   * Called whenever the spectra open change — one loaded, one closed, the chart
+   * cleared — with the spectra now open.
+   * @default undefined
+   */
+  onChange?: (spectra: MassSpectrum[]) => void;
+}
+
+/** What a component drives the viewer through. */
+export interface MassEditorApi {
+  /** Everything the viewer knows, in its three buckets. */
+  state: MassState;
+  /** The spectra currently drawn, by either trace, in the order they were loaded. */
+  visibleSpectra: MassSpectrum[];
+  /** The spectrum the panels act on, `null` while none is selected. */
+  selectedSpectrum: MassSpectrum | null;
+  /**
+   * How many decimals the masses the panels write are written with: the number
+   * chosen in the settings, or else the selected spectrum's own, since the peak
+   * table, the acquisition table and the labels are all about it alone — a
+   * nominal-mass table is written in whole numbers even beside an Orbitrap
+   * scan. With nothing selected, what the drawn spectra resolve together — see
+   * `mzDecimalsOf`.
+   */
+  mzDecimals: number;
+  /**
+   * What `mzDecimals` comes to when nothing is chosen, for a control that says
+   * what choosing nothing would mean.
+   */
+  autoMzDecimals: number;
+  /** Everything to do. */
+  actions: MassEditorActions;
+}
+
+/**
+ * Hold one viewer's state.
+ * @param options - What it opens on.
+ * @returns The state, what follows from it, and everything to do.
+ */
+export function useMassEditor(
+  options: UseMassEditorOptions = {},
+): MassEditorApi {
+  const { onChange, ...initial } = options;
+
+  const [state, dispatch] = useReducer(massReducer, initial, createMassState);
+  const actions = useMemo(() => createMassActions(dispatch), [dispatch]);
+
+  const { spectra } = state.data;
+  const { selectedId } = state.view;
+
+  const visibleSpectra = useMemo(() => {
+    const visible: MassSpectrum[] = [];
+    for (const spectrum of spectra) {
+      if (isSpectrumDrawn(spectrum)) visible.push(spectrum);
+    }
+    return visible;
+  }, [spectra]);
+
+  const selectedSpectrum = useMemo(() => {
+    if (selectedId === null) return null;
+    for (const spectrum of spectra) {
+      if (spectrum.id === selectedId) return spectrum;
+    }
+    return null;
+  }, [spectra, selectedId]);
+
+  const decimalsSetting = state.settings.mzDecimals;
+  const shownSpectra = useMemo(
+    () => (selectedSpectrum === null ? visibleSpectra : [selectedSpectrum]),
+    [visibleSpectra, selectedSpectrum],
+  );
+  const autoMzDecimals = useMemo(
+    () => mzDecimalsOf(shownSpectra),
+    [shownSpectra],
+  );
+  const mzDecimals = useMemo(
+    () => mzDecimalsFor(decimalsSetting, shownSpectra),
+    [decimalsSetting, shownSpectra],
+  );
+
+  // What was reported last, so a host passing a fresh callback on every render
+  // is not told about spectra that did not change. The identities are compared
+  // rather than the array: a rename or a colour builds a new spectrum around
+  // the same peaks, and that is not a change of what is loaded.
+  const reported = useRef(spectra);
+  useEffect(() => {
+    if (sameSpectra(reported.current, spectra)) return;
+    reported.current = spectra;
+    onChange?.(spectra);
+  }, [spectra, onChange]);
+
+  return useMemo(
+    () => ({
+      state,
+      visibleSpectra,
+      selectedSpectrum,
+      mzDecimals,
+      autoMzDecimals,
+      actions,
+    }),
+    [
+      state,
+      visibleSpectra,
+      selectedSpectrum,
+      mzDecimals,
+      autoMzDecimals,
+      actions,
+    ],
+  );
+}
+
+/**
+ * Whether two lists hold the same spectra, in order.
+ * @param current - What was reported last.
+ * @param next - What is open now.
+ * @returns Whether the report can be skipped.
+ */
+function sameSpectra(
+  current: readonly MassSpectrum[],
+  next: readonly MassSpectrum[],
+): boolean {
+  if (current === next) return true;
+  if (current.length !== next.length) return false;
+  for (let index = 0; index < current.length; index++) {
+    if (
+      (current[index] as MassSpectrum).id !== (next[index] as MassSpectrum).id
+    ) {
+      return false;
+    }
+  }
+  return true;
+}