react-cheminfo 0.69.0 → 0.71.0

package/src/mass/ui/MassEditor.tsx

@@ -0,0 +1,130 @@
+import type { Ref } from 'react';
+import { RootLayout } from 'react-science/ui';
+
+import type { MassEditorHandle, MassPlotClick } from '../core/massEditorApi.ts';
+import type { MassPanelId } from '../core/massSidePanels.ts';
+import type { MassSpectrum } from '../core/massSpectrum.ts';
+import type { MassSettings } from '../core/massState.ts';
+
+import { MassShell } from './MassShell.tsx';
+import { MassStateProvider } from './MassStateProvider.tsx';
+import type { MassHostPanel } from './massHostPanels.ts';
+import { useMassEditor } from './useMassEditor.ts';
+
+export interface MassEditorProps {
+  /**
+   * The spectra to open on. Read when the viewer opens and never again: what is
+   * on the chart belongs to the viewer from then on, so a host re-rendering with
+   * another array does not silently replace what somebody is looking at. The
+   * `ref` handle is how spectra arrive afterwards.
+   * @default []
+   */
+  data?: MassSpectrum[];
+  /**
+   * Called whenever the spectra open change — one loaded, one closed, the chart
+   * cleared — with the spectra now open.
+   *
+   * The document only. A zoom, a selection, a rename and a colour change what is
+   * being looked at rather than what is loaded, and a host told about those
+   * would be told on every drag of the mouse.
+   * @default undefined
+   */
+  onChange?: (spectra: MassSpectrum[]) => void;
+  /**
+   * How the spectra are drawn to begin with: whether the peaks are labelled,
+   * how many, and whether their charges are written.
+   * @default DEFAULT_SETTINGS
+   */
+  settings?: Partial<MassSettings>;
+  /**
+   * The side panels open to begin with: the viewer's own — `'spectra'`,
+   * `'peaks'`, `'metadata'` — or the id of one of `panels`. An id no panel
+   * answers to is ignored.
+   * @default DEFAULT_SIDE_PANELS
+   */
+  defaultPanelIds?: readonly MassPanelId[];
+  /**
+   * Panels the host adds to the viewer's own — a formula to predict an isotopic
+   * pattern from, say. Their icons come first in the activity bar, in the order
+   * given, and each then behaves as a built-in panel does.
+   * @default []
+   */
+  panels?: readonly MassHostPanel[];
+  /**
+   * The plot was clicked (a press that did not travel, so not a zoom drag), with
+   * the m/z it landed at, the picked peak within reach and the spectrum selected
+   * at that moment.
+   * @default undefined
+   */
+  onPlotClick?: (click: MassPlotClick) => void;
+  /**
+   * The handle a host drives the viewer through: take these spectra, read
+   * these files, frame this mass, select that one.
+   * @default undefined
+   */
+  ref?: Ref<MassEditorHandle>;
+}
+
+/**
+ * A mass spectrum viewer: a header across the top, the chart in the middle, the
+ * tools down the left, and the panels that interrogate it down the right.
+ *
+ * The same shape as the infrared viewer, deliberately — a page may well hold
+ * both, and a chemist who has learned one should not have to learn the other.
+ * Files are dropped on the chart or opened from the toolbar: JCAMP-DX and two
+ * columns of text. A profile is peak picked as it is read, every spectrum is
+ * judged high or low resolution, and the peaks of the selected one are labelled
+ * as the chart is zoomed.
+ *
+ * It is sealed the way NMRium is sealed: the spectra go in as `data` and come
+ * back through `onChange`, and everything else a host wants is a gesture on the
+ * `ref` rather than a prop that has to change to be obeyed.
+ * @param props - Component props.
+ * @returns The viewer.
+ */
+export function MassEditor(props: MassEditorProps) {
+  const {
+    data = NO_SPECTRA,
+    onChange,
+    settings,
+    defaultPanelIds,
+    panels = NO_PANELS,
+    onPlotClick,
+    ref,
+  } = props;
+
+  const editor = useMassEditor({
+    spectra: data,
+    ...(settings === undefined ? {} : { settings }),
+    ...(defaultPanelIds === undefined ? {} : { panelIds: defaultPanelIds }),
+    ...(onChange === undefined ? {} : { onChange }),
+  });
+
+  return (
+    <MassStateProvider editor={editor}>
+      {/* `react-science`'s own root: it holds the element the browser is asked
+          to show full screen, points Blueprint's portals at that element so
+          dialogs and tooltips are not left behind in `document.body`, and paints
+          the backdrop white. */}
+      <RootLayout style={rootLayoutStyle}>
+        <MassShell
+          handle={ref}
+          panels={panels}
+          {...(onPlotClick === undefined ? {} : { onPlotClick })}
+        />
+      </RootLayout>
+    </MassStateProvider>
+  );
+}
+
+/**
+ * The viewer fills what it is given, and its own children scroll rather than
+ * push: a flex column with no `minHeight` grows past its parent instead.
+ */
+const rootLayoutStyle = { minHeight: 0 } as const;
+
+/** What a viewer opens on when it is handed nothing, kept stable for the memo. */
+const NO_SPECTRA: MassSpectrum[] = [];
+
+/** What a viewer the host adds no panel to offers, kept stable for the memo. */
+const NO_PANELS: readonly MassHostPanel[] = [];

package/src/mass/ui/MassHeader.tsx

@@ -0,0 +1,38 @@
+import { Header, Toolbar, useFullscreen } from 'react-science/ui';
+
+import { MassLogo } from './MassLogo.tsx';
+import { useMassCommandProps } from './massCommandContext.tsx';
+
+/**
+ * The bar across the top: the mark on the left, the viewer on the right.
+ *
+ * Nothing that is done to the spectra is here — that is the rail down the left
+ * and the panels down the right — only what is asked of the viewer itself. The
+ * mark is the About button, in the corner the infrared viewer puts its own, so
+ * a chemist switching between the two looks in one place for what they are in;
+ * and help then full screen close the bar, hard against the right edge.
+ * @returns The header.
+ */
+export function MassHeader() {
+  const command = useMassCommandProps();
+  const { isFullScreen } = useFullscreen();
+
+  return (
+    <Header>
+      <Toolbar aria-label="Mass spectrum viewer">
+        <Toolbar.Item icon={<MassLogo size={16} />} {...command('about')} />
+      </Toolbar>
+      <Toolbar aria-label="Mass spectrum viewer help">
+        <Toolbar.Item icon="help" {...command('documentation')} />
+        {/* Always the last thing in the bar, hard against the right edge: the
+            corner a window is made bigger from is the corner it is looked for
+            in, whatever else the header grows. */}
+        <Toolbar.Item
+          icon="fullscreen"
+          active={isFullScreen}
+          {...command('fullScreen')}
+        />
+      </Toolbar>
+    </Header>
+  );
+}

package/src/mass/ui/MassLogo.tsx

@@ -0,0 +1,84 @@
+import type { ReactElement } from 'react';
+
+import { CHART_COLORS } from '../../chart/core/chartTheme.ts';
+import { SPECTRUM_COLORS } from '../../chart/core/spectrumColor.ts';
+
+export interface MassLogoProps {
+  /**
+   * Width and height of the mark, in pixels.
+   * @default 16
+   */
+  size?: number;
+}
+
+/**
+ * The viewer's mark: a labelled spectrum, drawn the way the chart draws one.
+ *
+ * Three sticks on a baseline with a triangle on the tallest — the same shapes,
+ * the same blue and the same orange the chart itself uses, so the mark is a
+ * small piece of the tool's output rather than a picture of it. Three sticks is
+ * what survives being shrunk to a toolbar icon; a fourth closes the gaps between
+ * them and the mark reads as a solid block at 16 pixels.
+ * @param props - Component props.
+ * @returns The mark, as SVG.
+ */
+export function MassLogo(props: MassLogoProps): ReactElement {
+  const { size = 16 } = props;
+
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox={VIEW_BOX}
+      role="img"
+      aria-label="Mass spectrum viewer"
+    >
+      <line
+        x1={2}
+        y1={BASELINE}
+        x2={30}
+        y2={BASELINE}
+        strokeWidth={BASELINE_WIDTH}
+        style={baselineStyle}
+      />
+      {STICKS.map((stick) => (
+        <line
+          key={stick.x}
+          x1={stick.x}
+          y1={BASELINE}
+          x2={stick.x}
+          y2={stick.top}
+          strokeWidth={STICK_WIDTH}
+          strokeLinecap="butt"
+          style={stickStyle}
+        />
+      ))}
+      <path d={MARK} style={markStyle} />
+    </svg>
+  );
+}
+
+/** Cropped to the ink: a mark carrying its own margin reads as the smaller one. */
+const VIEW_BOX = '1 0 30 29';
+
+/** Where the sticks stand, in the same units. */
+const BASELINE = 27;
+
+const BASELINE_WIDTH = 1.4;
+const STICK_WIDTH = 2.6;
+
+/** The base peak in the middle, with a shoulder either side of it. */
+const STICKS = [
+  { x: 6, top: 15 },
+  { x: 16, top: 7 },
+  { x: 26, top: 19 },
+] as const;
+
+/** The triangle on the base peak: apex on the tip, body clear of it. */
+const MARK = 'M16 6L12.4 0.6L19.6 0.6Z';
+
+const baselineStyle = { stroke: CHART_COLORS.axis } as const;
+
+const stickStyle = { stroke: SPECTRUM_COLORS[0] } as const;
+
+const markStyle = { fill: CHART_COLORS.highlight } as const;

package/src/mass/ui/MassPointerTracker.tsx

@@ -0,0 +1,72 @@
+import type { ReactElement } from 'react';
+
+import type { PlotRect } from '../../chart/core/chartGeometry.ts';
+import type { ChartPoint } from '../../chart/core/svgPoint.ts';
+import { ChartTracker } from '../../chart/ui/ChartTracker.tsx';
+import { formatIntensity, formatMz } from '../core/massFormat.ts';
+
+import type { MassReadout } from './useMassPointer.ts';
+
+export interface MassPointerTrackerProps {
+  /** Where the pointer is, `null` whenever it is off the plot. */
+  position: ChartPoint | null;
+  /** What the axes read under it, `null` whenever it is off the plot. */
+  readout: MassReadout | null;
+  /** Where the plot sits inside the SVG. */
+  plot: PlotRect;
+  /**
+   * How many decimals the masses on screen are written with.
+   * @default 4
+   */
+  mzDecimals?: number;
+  /**
+   * What one unit of the measured intensity is written as.
+   * @default 1
+   */
+  intensityScale?: number;
+  /**
+   * The sign that unit carries, `%` on a derived basis. This number stands on
+   * its own with nothing beside it to say what it is, so it takes the sign where
+   * the axis would otherwise have carried it.
+   * @default ''
+   */
+  suffix?: string;
+}
+
+/**
+ * The crosshair, and what the axes say where it stands.
+ *
+ * Two rules rather than one, because both axes are being read: the vertical one
+ * answers *what mass is this*, and the horizontal one answers *how tall is that
+ * against this*, which is how a peak is judged against its neighbours without
+ * counting grid lines. The picked peak within reach is not written here: the
+ * guide on its exact m/z and its lit row in the peak table say which it is, and
+ * a readout a line longer than the shared chart places would run off the foot
+ * of the plot.
+ * @param props - Component props.
+ * @returns The crosshair, or nothing while the pointer is off the plot.
+ */
+export function MassPointerTracker(
+  props: MassPointerTrackerProps,
+): ReactElement | null {
+  const {
+    position,
+    readout,
+    plot,
+    mzDecimals,
+    intensityScale = 1,
+    suffix = '',
+  } = props;
+
+  // A magnitude: the lower half of a mirrored pair is a second spectrum drawn
+  // downwards, never a negative intensity.
+  const lines =
+    readout === null
+      ? null
+      : [
+          `m/z ${formatMz(readout.mz, mzDecimals)}`,
+          `${formatIntensity(Math.abs(readout.intensity) * intensityScale, mzDecimals)}${suffix}`,
+        ];
+
+  return <ChartTracker position={position} plot={plot} lines={lines} />;
+}

package/src/mass/ui/MassShell.tsx

@@ -0,0 +1,237 @@
+import type { ChangeEvent, Ref } from 'react';
+import { useId, useMemo, useRef, useState } from 'react';
+import { SplitPane, useFullscreen } from 'react-science/ui';
+
+import { sanitizeFileName } from '../../download/core/sanitizeFileName.ts';
+import { useFigureDownload } from '../../download/ui/useFigureDownload.tsx';
+import { PanelRail } from '../../panel/ui/PanelRail.tsx';
+import type { MassCommandHandlers } from '../core/massCommands.ts';
+import type { MassEditorHandle, MassPlotClick } from '../core/massEditorApi.ts';
+import type { MassSpectrum } from '../core/massSpectrum.ts';
+
+import { MassAboutDialog } from './MassAboutDialog.tsx';
+import { MassCanvas } from './MassCanvas.tsx';
+import { MassCommandProvider } from './MassCommandProvider.tsx';
+import { MassDocumentationDialog } from './MassDocumentationDialog.tsx';
+import { MassHeader } from './MassHeader.tsx';
+import { MassSidePanel } from './MassSidePanel.tsx';
+import { MassToolbar } from './MassToolbar.tsx';
+import type { MassHostPanel } from './massHostPanels.ts';
+import { useMassActions, useMassEditorState } from './massStateContext.ts';
+import { useIntensityZoom } from './useIntensityZoom.ts';
+import { useMassFiles } from './useMassFiles.ts';
+import { useMassHandle } from './useMassHandle.ts';
+import { useMassShortcuts } from './useMassShortcuts.ts';
+import { useMassSide } from './useMassSide.ts';
+
+export interface MassShellProps {
+  /**
+   * The handle to fill in, once there is a state for it to act on.
+   * @default undefined
+   */
+  handle?: Ref<MassEditorHandle>;
+  /** The panels the host adds to the viewer's own, ahead of them. */
+  panels: readonly MassHostPanel[];
+  /**
+   * Told of a click on the plot, with the spectrum selected at that moment.
+   * @default undefined
+   */
+  onPlotClick?: (click: MassPlotClick) => void;
+}
+
+/**
+ * The viewer's screen: a header, the rails, and the split between the chart and
+ * the panels.
+ *
+ * Kept apart from `MassEditor` so that the handle, the commands and the
+ * highlight — all of which need the state — sit below the providers rather than
+ * beside them, and so the sealed component above is nothing but its props.
+ * @param props - Component props.
+ * @returns The screen.
+ */
+export function MassShell(props: MassShellProps) {
+  const { handle, panels, onPlotClick } = props;
+
+  const { state, visibleSpectra, selectedSpectrum } = useMassEditorState();
+  const actions = useMassActions();
+  const { toggle: toggleFullScreen } = useFullscreen();
+  const { openPanelIds, tool } = state.view;
+  const { showLabels, showCharges } = state.settings;
+  const side = useMassSide(panels);
+  const files = useMassFiles();
+  const fileInput = useRef<HTMLInputElement>(null);
+  const { zoomIn, zoomOut } = useIntensityZoom();
+
+  const [isAboutOpen, setIsAboutOpen] = useState(false);
+  const [isDocumentationOpen, setIsDocumentationOpen] = useState(false);
+  // What the pointer is resting on is not part of the document and changes on
+  // every move across the chart, so it is held here rather than in the reducer,
+  // where every panel's memo would run sixty times a second.
+  const [highlightMz, setHighlightMz] = useState<number | null>(null);
+
+  // The chart is the picture, so the box it is drawn in is what the figure
+  // panel is pointed at: the viewer around it is full of SVG icons.
+  const chartId = useId();
+  const figure = useFigureDownload({
+    targetId: chartId,
+    fileName: pictureName(visibleSpectra, selectedSpectrum),
+  });
+  const { isOpen: isFigureOpen, setOpen: setFigureOpen } = figure;
+
+  const commands = useMemo<MassCommandHandlers>(
+    () => ({
+      about: () => setIsAboutOpen(true),
+      documentation: () => setIsDocumentationOpen(true),
+      fullScreen: toggleFullScreen,
+      openFiles: () => fileInput.current?.click(),
+      readTool: () => actions.setTool('read'),
+      boxTool: () => actions.setTool(tool === 'box' ? 'read' : 'box'),
+      zoomIn,
+      zoomOut,
+      resetZoom: () => actions.resetDomain(),
+      toggleLabels: () => actions.setSettings({ showLabels: !showLabels }),
+      toggleCharges: () => actions.setSettings({ showCharges: !showCharges }),
+      exportImage: () => setFigureOpen(!isFigureOpen),
+      clear: () => actions.clear(),
+    }),
+    [
+      actions,
+      tool,
+      showLabels,
+      showCharges,
+      zoomIn,
+      zoomOut,
+      toggleFullScreen,
+      isFigureOpen,
+      setFigureOpen,
+    ],
+  );
+
+  // The root is held as state rather than in a ref because the keys are bound to
+  // it from an effect: a ref filled in during the commit would leave the effect
+  // with nothing to listen on for the first render, and no reason ever to run
+  // again.
+  const [root, setRoot] = useState<HTMLElement | null>(null);
+  useMassShortcuts(root, commands);
+  useMassHandle(handle, files.readFiles);
+
+  return (
+    <MassCommandProvider handlers={commands}>
+      {/* `tabIndex` so a click anywhere in the viewer makes this the target the
+          shortcuts are heard on: keys are delivered to whatever holds the caret,
+          and an SVG never does. */}
+      <div ref={setRoot} tabIndex={-1} style={rootStyle}>
+        <MassHeader />
+
+        <div style={mainStyle}>
+          <div style={railStyle}>
+            <MassToolbar figure={figure} />
+          </div>
+
+          <SplitPane
+            direction="horizontal"
+            controlledSide="end"
+            defaultSize="360px"
+            open={side.isOpen}
+            onOpenChange={side.setOpen}
+          >
+            <MassCanvas
+              highlightMz={highlightMz}
+              onHighlight={setHighlightMz}
+              chartId={chartId}
+              onDropFiles={(dropped) => void files.readFiles(dropped)}
+              {...(onPlotClick === undefined ? {} : { onPlotClick })}
+            />
+
+            <MassSidePanel
+              panels={panels}
+              highlightMz={highlightMz}
+              onHighlight={setHighlightMz}
+            />
+          </SplitPane>
+
+          {/* Outside the split, so the icons stay put against the right edge
+              while the panel beside them is resized or closed. */}
+          <div style={railStyle}>
+            <PanelRail
+              panels={side.panels}
+              openIds={openPanelIds}
+              onToggle={actions.togglePanel}
+            />
+          </div>
+        </div>
+
+        <input
+          ref={fileInput}
+          type="file"
+          multiple
+          accept={ACCEPTED_FILES}
+          style={hiddenStyle}
+          aria-label="Open spectra"
+          onChange={(event: ChangeEvent<HTMLInputElement>) => {
+            const chosen = [...(event.currentTarget.files ?? [])];
+            // Emptied so that choosing the same file again is still a change.
+            event.currentTarget.value = '';
+            if (chosen.length > 0) void files.readFiles(chosen);
+          }}
+        />
+      </div>
+
+      <MassAboutDialog
+        isOpen={isAboutOpen}
+        onClose={() => setIsAboutOpen(false)}
+      />
+      <MassDocumentationDialog
+        isOpen={isDocumentationOpen}
+        onClose={() => setIsDocumentationOpen(false)}
+      />
+    </MassCommandProvider>
+  );
+}
+
+/**
+ * What a picture of the chart is called: the spectrum being looked at, since a
+ * figure of the chart is a figure of that spectrum, and a chart holding several
+ * and pointing at none of them is named after the lot.
+ * @param spectra - What is drawn.
+ * @param selected - The one being looked at, `null` when none is.
+ * @returns The name, without its extension.
+ */
+function pictureName(
+  spectra: readonly MassSpectrum[],
+  selected: MassSpectrum | null,
+): string {
+  const named = selected ?? (spectra.length === 1 ? spectra[0] : undefined);
+  return named === undefined
+    ? 'spectra'
+    : sanitizeFileName(named.name, 'spectrum');
+}
+
+/** What the file dialog offers, which is what the readers understand. */
+const ACCEPTED_FILES = '.jdx,.dx,.jcamp,.txt,.csv,.tsv,.xy,.asc,.dat';
+
+const rootStyle = {
+  display: 'flex',
+  flexDirection: 'column',
+  flex: '1 1 1px',
+  width: '100%',
+  height: '100%',
+  minHeight: 0,
+  outline: 'none',
+} as const;
+
+const mainStyle = {
+  display: 'flex',
+  flex: '1 1 1px',
+  minWidth: 0,
+  minHeight: 0,
+} as const;
+
+/**
+ * The rails are chrome of a fixed width, and a flex child shrinks by default: in
+ * a narrow viewer the row would take the width it is short of out of them.
+ */
+const railStyle = { flex: 'none' } as const;
+
+/** The file input is opened by the toolbar, never clicked itself. */
+const hiddenStyle = { display: 'none' } as const;

package/src/mass/ui/MassSidePanel.tsx

@@ -0,0 +1,107 @@
+import { useMemo } from 'react';
+
+import { panelStyle } from '../../panel/core/panelStyles.ts';
+import { SidePanelStack } from '../../panel/ui/SidePanelStack.tsx';
+import type { MassSidePanelId } from '../core/massSidePanels.ts';
+
+import { MetadataPanel } from './MetadataPanel.tsx';
+import { PeaksPanel } from './PeaksPanel.tsx';
+import { SpectraPanel } from './SpectraPanel.tsx';
+import type { MassHostPanel } from './massHostPanels.ts';
+import { isMassHostPanel, massStackPanels } from './massHostPanels.ts';
+import { useMassActions, useMassEditorState } from './massStateContext.ts';
+
+export interface MassSidePanelProps {
+  /**
+   * The panels the host adds to the viewer's own, stacked above them in the
+   * order given.
+   * @default []
+   */
+  panels?: readonly MassHostPanel[];
+  /**
+   * The m/z of the peak the pointer is resting on.
+   * @default null
+   */
+  highlightMz?: number | null;
+  /**
+   * Told when a row of the peak table is hovered.
+   * @default undefined
+   */
+  onHighlight?: (mz: number | null) => void;
+}
+
+/**
+ * The panels that are open, stacked down the right.
+ *
+ * Every open panel gets a share of the height rather than a turn, because the
+ * things they hold are read together: which spectrum is selected and what its
+ * peaks are is one question asked of two panels. The header carries the close
+ * button and nothing else — a panel's own actions are a toolbar inside its
+ * body, so they travel with it.
+ * @param props - Component props.
+ * @returns The panel stack.
+ */
+export function MassSidePanel(props: MassSidePanelProps) {
+  const {
+    panels: hostPanels = NO_PANELS,
+    highlightMz = null,
+    onHighlight,
+  } = props;
+  const { state } = useMassEditorState();
+  const actions = useMassActions();
+  const { openPanelIds } = state.view;
+  const panels = useMemo(() => massStackPanels(hostPanels), [hostPanels]);
+
+  return (
+    <SidePanelStack
+      panels={panels}
+      openPanelIds={openPanelIds}
+      onClose={actions.togglePanel}
+    >
+      {(panel) =>
+        isMassHostPanel(panel) ? (
+          <div style={panelStyle}>{panel.content}</div>
+        ) : (
+          <PanelBody
+            panelId={panel.id}
+            highlightMz={highlightMz}
+            {...(onHighlight === undefined ? {} : { onHighlight })}
+          />
+        )
+      }
+    </SidePanelStack>
+  );
+}
+
+interface PanelBodyProps {
+  /** Which panel to draw. */
+  panelId: MassSidePanelId;
+  /** The m/z of the peak the pointer is resting on. */
+  highlightMz: number | null;
+  /**
+   * Told when a row of the peak table is hovered.
+   * @default undefined
+   */
+  onHighlight?: (mz: number | null) => void;
+}
+
+/**
+ * Which panel a panel id is.
+ * @param props - Component props.
+ * @returns The panel's body.
+ */
+function PanelBody(props: PanelBodyProps) {
+  const { panelId, highlightMz, onHighlight } = props;
+
+  if (panelId === 'spectra') return <SpectraPanel />;
+  if (panelId === 'metadata') return <MetadataPanel />;
+  return (
+    <PeaksPanel
+      highlightMz={highlightMz}
+      {...(onHighlight === undefined ? {} : { onHighlight })}
+    />
+  );
+}
+
+/** What a stack the host adds nothing to holds, kept stable for the memo. */
+const NO_PANELS: readonly MassHostPanel[] = [];