react-cheminfo 0.69.0 → 0.71.0

package/src/mass/ui/SpectraPanel.tsx

@@ -0,0 +1,153 @@
+import { useEffect, useRef } from 'react';
+import { SelectedTotal, Toolbar } from 'react-science/ui';
+
+import { useListKeyboardNavigation } from '../../hooks/ui/useListKeyboardNavigation.ts';
+import {
+  panelBodyStyle,
+  panelEmptyStyle,
+  panelStyle,
+  panelToolbarCountStyle,
+  panelToolbarStyle,
+} from '../../panel/core/panelStyles.ts';
+import { downloadMassSpectra } from '../core/downloadSpectra.ts';
+import { massCommandLabel } from '../core/massCommands.ts';
+
+import { SpectrumRow } from './SpectrumRow.tsx';
+import { useMassCommand } from './massCommandContext.tsx';
+import { useMassActions, useMassEditorState } from './massStateContext.ts';
+
+/**
+ * What is loaded: one row per spectrum, in the order the files gave them.
+ *
+ * The list is the viewer's selection as well as its legend. Whichever row is
+ * selected is the spectrum the acquisition table describes, the peak table holds
+ * and the chart writes its labels on, so a row is not a checkbox with a colour
+ * beside it — it is the control that decides what the other panels are about.
+ * That is also why the arrow keys walk it: a GC/MS export gives a page per scan,
+ * and finding the interesting one means stepping down them watching the chart.
+ *
+ * What acts on the list rather than on one row — opening more, drawing every
+ * trace again, handing the whole list over as a file, closing every one — is a
+ * toolbar under the header, where a panel's own actions belong.
+ * @returns The panel.
+ */
+export function SpectraPanel() {
+  const { state, visibleSpectra } = useMassEditorState();
+  const actions = useMassActions();
+  const run = useMassCommand();
+  const { spectra } = state.data;
+  const { selectedId } = state.view;
+  const listRef = useRef<HTMLDivElement>(null);
+
+  const selectedIndex = spectra.findIndex(
+    (spectrum) => spectrum.id === selectedId,
+  );
+  const onKeyDown = useListKeyboardNavigation({
+    length: spectra.length,
+    selectedIndex,
+    onSelect: (index) => {
+      const spectrum = spectra[index];
+      if (spectrum !== undefined) actions.selectSpectrum(spectrum.id);
+    },
+  });
+
+  useEffect(() => {
+    if (listRef.current === null || selectedId === null) return;
+    listRef.current
+      .querySelector('[data-selected="true"]')
+      ?.scrollIntoView({ block: 'nearest' });
+  }, [selectedId]);
+
+  const allDrawn = spectra.every(
+    (spectrum) => spectrum.showProfile || spectrum.showCentroid,
+  );
+
+  return (
+    <div style={panelStyle}>
+      <div style={panelToolbarStyle}>
+        <Toolbar aria-label="Spectra">
+          <Toolbar.Item
+            icon="folder-open"
+            tooltip={massCommandLabel('openFiles')}
+            aria-label={massCommandLabel('openFiles')}
+            onClick={() => run('openFiles')}
+          />
+          <Toolbar.Item
+            icon="trash"
+            intent="danger"
+            tooltip="Close every spectrum"
+            aria-label="Close every spectrum"
+            disabled={spectra.length === 0}
+            onClick={actions.clear}
+          />
+          <Toolbar.Item
+            icon="eye-open"
+            tooltip="Draw every spectrum again, each as the trace it was read as"
+            aria-label="Draw every spectrum again"
+            disabled={spectra.length === 0 || allDrawn}
+            onClick={() => {
+              for (const spectrum of spectra) {
+                if (spectrum.showProfile || spectrum.showCentroid) continue;
+                actions.setSpectrumVisibility(spectrum.id, {
+                  showProfile: spectrum.profile !== null,
+                  showCentroid: spectrum.profile === null,
+                });
+              }
+            }}
+          />
+          <Toolbar.Item
+            icon="download"
+            tooltip="Download every spectrum as one JCAMP-DX file"
+            aria-label="Download every spectrum"
+            disabled={spectra.length === 0}
+            onClick={() => downloadMassSpectra(spectra)}
+          />
+        </Toolbar>
+        <div
+          style={panelToolbarCountStyle}
+          title={`${visibleSpectra.length} of ${spectra.length} spectra drawn`}
+        >
+          <SelectedTotal count={visibleSpectra.length} total={spectra.length} />
+        </div>
+      </div>
+
+      <div ref={listRef} style={panelBodyStyle}>
+        {spectra.length === 0 ? (
+          <p style={panelEmptyStyle}>
+            No spectrum is open. Drop a JCAMP-DX file, or two columns of m/z and
+            intensity, on the chart.
+          </p>
+        ) : (
+          <ul
+            aria-label="Open spectra"
+            // Reached by Tab, or by clicking a row, and then walked with the
+            // arrows.
+            tabIndex={0}
+            style={listStyle}
+            onKeyDown={onKeyDown}
+          >
+            {spectra.map((spectrum) => (
+              <SpectrumRow
+                key={spectrum.id}
+                spectrum={spectrum}
+                isSelected={spectrum.id === selectedId}
+              />
+            ))}
+          </ul>
+        )}
+      </div>
+    </div>
+  );
+}
+
+/**
+ * The rows, flush against one another: a gap between every pair reads as a
+ * stack of cards rather than as one list to run an eye down.
+ */
+const listStyle = {
+  display: 'flex',
+  flexDirection: 'column',
+  margin: 0,
+  padding: 0,
+  listStyle: 'none',
+} as const;

package/src/mass/ui/SpectrumRow.tsx

@@ -0,0 +1,246 @@
+import { InputGroup } from '@blueprintjs/core';
+import { useMemo, useState } from 'react';
+import { Button } from 'react-science/ui';
+
+import { SpectrumColorSwatch } from '../../panel/ui/SpectrumColorSwatch.tsx';
+import { downloadMassSpectrum } from '../core/downloadSpectra.ts';
+import type { MassSpectrum } from '../core/massSpectrum.ts';
+import { spectrumSubtitle } from '../core/massSummary.ts';
+import type { MassTraceKind, TraceIconState } from '../core/traceIcon.ts';
+import { nextTraceIconClick, traceIconState } from '../core/traceIcon.ts';
+
+import { useMassActions } from './massStateContext.ts';
+
+export interface SpectrumRowProps {
+  /** The spectrum the row is of. */
+  spectrum: MassSpectrum;
+  /** Whether it is the one the panels act on. */
+  isSelected: boolean;
+}
+
+/**
+ * One loaded spectrum: its colour, its two traces, its name, and the way out.
+ *
+ * Everything on the row addresses the spectrum by its identity, never by where
+ * it sits in the list — a row acts on a list that has been shortened by a close
+ * since it was drawn, and an index would then recolour or close whichever
+ * spectrum has taken that place.
+ *
+ * The two trace icons are the row's centre of gravity, and they are tri-state
+ * rather than checkboxes; `traceIcon.ts` says why. The name is renamed in place
+ * on a double click, because a name is what a chemist tells scans apart by and
+ * a file's own titles are often the same string a dozen times over. The line
+ * under it says what kind of spectrum it is: profile or centroid, how many
+ * peaks, and at what resolution.
+ * @param props - Component props.
+ * @returns The row.
+ */
+export function SpectrumRow(props: SpectrumRowProps) {
+  const { spectrum, isSelected } = props;
+  const actions = useMassActions();
+  const [draftName, setDraftName] = useState<string | null>(null);
+
+  const subtitle = useMemo(
+    () => spectrumSubtitle(spectrum, { describeKind: true }),
+    [spectrum],
+  );
+  const profileState = traceIconState(spectrum.showProfile, isSelected);
+  const centroidState = traceIconState(spectrum.showCentroid, isSelected);
+
+  /**
+   * Run the cycle of one trace icon.
+   * @param kind - The trace the icon stands for.
+   * @param state - What the icon was saying before the click.
+   */
+  function clickTrace(kind: MassTraceKind, state: TraceIconState): void {
+    const click = nextTraceIconClick(kind, state);
+    actions.setSpectrumVisibility(spectrum.id, click.visibility);
+    if (click.select) actions.selectSpectrum(spectrum.id);
+  }
+
+  /** Take the name typed, unless it was emptied — a rename abandoned. */
+  function commitRename(): void {
+    const name = draftName?.trim() ?? '';
+    setDraftName(null);
+    if (name !== '') actions.renameSpectrum(spectrum.id, name);
+  }
+
+  return (
+    <li
+      // A row of controls rather than an option of a listbox, so the one every
+      // panel is about is said to be the current one.
+      aria-current={isSelected ? 'true' : undefined}
+      style={isSelected ? selectedRowStyle : rowStyle}
+      data-selected={isSelected ? 'true' : undefined}
+    >
+      <SpectrumColorSwatch
+        color={spectrum.color}
+        name={spectrum.name}
+        onPick={(color) => actions.setSpectrumColor(spectrum.id, color)}
+      />
+
+      <Button
+        variant="minimal"
+        size="small"
+        icon="timeline-line-chart"
+        active={profileState !== 'hidden'}
+        intent={profileState === 'selected' ? 'primary' : 'none'}
+        disabled={spectrum.profile === null}
+        tooltipProps={{
+          ...rowTooltipProps,
+          content:
+            spectrum.profile === null
+              ? 'This file was already centroided, so it has no continuous trace'
+              : traceTooltip('profile', profileState),
+        }}
+        aria-label={`Continuous trace of ${spectrum.name}`}
+        onClick={() => clickTrace('profile', profileState)}
+      />
+
+      <Button
+        variant="minimal"
+        size="small"
+        icon="timeline-bar-chart"
+        active={centroidState !== 'hidden'}
+        intent={centroidState === 'selected' ? 'primary' : 'none'}
+        tooltipProps={{
+          ...rowTooltipProps,
+          content: traceTooltip('centroid', centroidState),
+        }}
+        aria-label={`Centroid sticks of ${spectrum.name}`}
+        onClick={() => clickTrace('centroid', centroidState)}
+      />
+
+      {draftName === null ? (
+        <button
+          type="button"
+          style={nameStyle}
+          title="Click to work on this spectrum, double click to rename it"
+          onClick={() => actions.selectSpectrum(spectrum.id)}
+          onDoubleClick={() => setDraftName(spectrum.name)}
+        >
+          <span style={nameTextStyle}>{spectrum.name}</span>
+          <span style={subtitleStyle}>{subtitle}</span>
+        </button>
+      ) : (
+        <InputGroup
+          autoFocus
+          size="small"
+          value={draftName}
+          spellCheck={false}
+          autoCapitalize="off"
+          autoCorrect="off"
+          autoComplete="off"
+          aria-label={`Name of ${spectrum.name}`}
+          onValueChange={setDraftName}
+          onBlur={commitRename}
+          onKeyDown={(event) => {
+            if (event.key === 'Enter') commitRename();
+            if (event.key === 'Escape') setDraftName(null);
+          }}
+        />
+      )}
+
+      <Button
+        variant="minimal"
+        size="small"
+        icon="download"
+        aria-label={`Download ${spectrum.name}`}
+        tooltipProps={{
+          ...rowTooltipProps,
+          content: 'Download this spectrum as a JCAMP-DX file',
+        }}
+        onClick={() => downloadMassSpectrum(spectrum)}
+      />
+
+      <Button
+        variant="minimal"
+        size="small"
+        icon="cross"
+        aria-label={`Close ${spectrum.name}`}
+        tooltipProps={{ ...rowTooltipProps, content: 'Close this spectrum' }}
+        onClick={() => actions.removeSpectrum(spectrum.id)}
+      />
+    </li>
+  );
+}
+
+/**
+ * What a click on a trace icon would do, said as a sentence.
+ *
+ * The three states of the icon look alike enough at 16 pixels that the cycle is
+ * actually learned from the tooltip, so each one says what the click does rather
+ * than what the icon means — including that picking one trace puts the other
+ * away, which is the part a reader would otherwise discover by surprise.
+ * @param kind - The trace the icon stands for.
+ * @param state - What the icon is saying.
+ * @returns The tooltip.
+ */
+function traceTooltip(kind: MassTraceKind, state: TraceIconState): string {
+  const trace =
+    kind === 'profile' ? 'the continuous trace' : 'the centroid sticks';
+  const other =
+    kind === 'profile' ? 'the centroid sticks' : 'the continuous trace';
+  if (state === 'hidden') {
+    return `Draw ${trace} instead of ${other}, and work on this spectrum`;
+  }
+  if (state === 'drawn') {
+    return 'Work on this spectrum — its peaks are the ones labelled';
+  }
+  return 'Take this spectrum off the chart';
+}
+
+/**
+ * How a tooltip behaves on a control that sits in a list: a hand crossing forty
+ * rows passes over a hundred of these, and with no delay every one of them
+ * opens.
+ */
+const rowTooltipProps = { compact: true, hoverOpenDelay: 300 } as const;
+
+const rowStyle = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 2,
+  padding: '0 2px',
+  borderRadius: 3,
+} as const;
+
+/** The selected row, which is the one every other panel is about. */
+const selectedRowStyle = { ...rowStyle, background: '#e8f1fb' } as const;
+
+const nameStyle = {
+  display: 'flex',
+  flexDirection: 'column',
+  alignItems: 'flex-start',
+  gap: 1,
+  flex: '1 1 1px',
+  minWidth: 0,
+  padding: '1px 2px',
+  border: 'none',
+  background: 'none',
+  color: 'inherit',
+  font: 'inherit',
+  textAlign: 'left',
+  cursor: 'pointer',
+} as const;
+
+/** One line, cut short rather than wrapped: the rows stay a fixed height. */
+const nameTextStyle = {
+  maxWidth: '100%',
+  fontSize: 12,
+  fontWeight: 600,
+  lineHeight: 1.2,
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+} as const;
+
+const subtitleStyle = {
+  maxWidth: '100%',
+  fontSize: 10,
+  lineHeight: 1.2,
+  opacity: 0.7,
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  whiteSpace: 'nowrap',
+} as const;

package/src/mass/ui/SpectrumTrace.tsx

@@ -0,0 +1,119 @@
+import { xyReduce, xyReduceNonContinuous } from 'ml-spectra-processing';
+import type { ReactElement } from 'react';
+import { 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 { profilePath, stickPath } from '../../chart/core/tracePath.ts';
+import type { MassSpectrum } from '../core/massSpectrum.ts';
+
+export interface SpectrumTraceProps {
+  /** The spectrum, which says in itself which of its traces are drawn. */
+  spectrum: MassSpectrum;
+  /** Where the plot sits, whose width is how many points are worth drawing. */
+  plot: PlotRect;
+  /**
+   * The m/z axis as it is currently zoomed. It must be stable while the window
+   * is — a scale rebuilt on every render rebuilds both paths with it, and a
+   * profile scan reduced afresh on each pointer move is what makes a chart
+   * stutter under the hand.
+   */
+  xScale: ChartScale;
+  /** The intensity axis as it is currently zoomed, and the same requirement. */
+  yScale: ChartScale;
+  /**
+   * How thick both traces are drawn, in pixels.
+   * @default 1
+   */
+  strokeWidth?: number;
+}
+
+/**
+ * One spectrum, drawn as at most two paths in its own colour.
+ *
+ * The window the traces are reduced to is read back off the scale rather than
+ * passed in beside it, so the reduction can never have been computed for a
+ * window other than the one being drawn — the two would disagree for exactly
+ * one render after a zoom, which is the render the eye catches.
+ *
+ * A measured profile is reduced to the pixel columns it will occupy, keeping
+ * the extremes of each column so the noise still looks like noise. A
+ * **calculated** trace is never reduced: an isotopic distribution is emitted as
+ * a stick with an explicit zero either side of it, a reducer takes the zeros for
+ * the flat stretches they look like and drops them, and the line then runs from
+ * peak top to peak top without ever coming back to the baseline. The centroid is
+ * reduced against the current view too: a peak table of fifty thousand sticks
+ * has no more than one per pixel column to show, and which peak wins a column
+ * changes with every zoom.
+ * @param props - Component props.
+ * @returns The spectrum, as SVG.
+ */
+export function SpectrumTrace(props: SpectrumTraceProps): ReactElement {
+  const { spectrum, plot, xScale, yScale, strokeWidth = TRACE_WIDTH } = props;
+  const { profile, centroid, origin, color, showProfile, showCentroid } =
+    spectrum;
+
+  const from = chartValue(xScale, plot.left);
+  const to = chartValue(xScale, plot.right);
+  const columns = Math.max(2, Math.round(plot.width));
+
+  const profileD = useMemo(() => {
+    if (!showProfile || profile === null || profile.x.length === 0) return '';
+    const drawn =
+      origin.format === 'calculated'
+        ? profile
+        : xyReduce(profile, {
+            from,
+            to,
+            nbPoints: columns * PROFILE_POINTS_PER_COLUMN,
+          });
+    return profilePath(drawn.x, drawn.y, xScale, yScale);
+  }, [showProfile, profile, origin.format, from, to, columns, xScale, yScale]);
+
+  const centroidD = useMemo(() => {
+    if (!showCentroid || centroid.x.length === 0) return '';
+    const drawn = xyReduceNonContinuous(centroid, {
+      from,
+      to,
+      maxApproximateNbPoints: columns,
+    });
+    return stickPath(drawn.x, drawn.y, xScale, yScale);
+  }, [showCentroid, centroid, from, to, columns, xScale, yScale]);
+
+  return (
+    <g pointerEvents="none">
+      {profileD === '' ? null : (
+        <path
+          d={profileD}
+          fill="none"
+          stroke={color}
+          strokeWidth={strokeWidth}
+          strokeLinejoin="round"
+        />
+      )}
+      {centroidD === '' ? null : (
+        <path
+          d={centroidD}
+          fill="none"
+          stroke={color}
+          strokeWidth={strokeWidth}
+        />
+      )}
+    </g>
+  );
+}
+
+/** How thick a trace is when nobody asks for anything else. */
+const TRACE_WIDTH = 1;
+
+/**
+ * How many reduced samples each pixel column of a profile is given.
+ *
+ * The reduction keeps the lowest and the highest sample of every slot, so two
+ * per column is the least that draws a column at all — and `xyReduce` asks for
+ * about four times what is displayed before a narrow peak survives at its true
+ * height rather than at the height of whichever sample the slot boundary
+ * happened to land on.
+ */
+const PROFILE_POINTS_PER_COLUMN = 4;

package/src/mass/ui/index.ts

@@ -0,0 +1,69 @@
+/**
+ * The mass spectrum chart, the panels beside it and the editor they sit in.
+ *
+ * `MassChart` is the drawing and holds nothing: it takes spectra, what to label
+ * and a window as props and hands every gesture back, so it fits a report page
+ * or a test as readily as an editor. The chart's own drawing — scales, ticks,
+ * plot geometry, the zoom gestures and the label placement — is the shared
+ * chart layer, which every viewer of the family draws with.
+ */
+
+export type { MassAboutDialogProps } from './MassAboutDialog.tsx';
+export { MassAboutDialog } from './MassAboutDialog.tsx';
+export type { MassCanvasProps } from './MassCanvas.tsx';
+export { MassCanvas } from './MassCanvas.tsx';
+export { MassChart } from './MassChart.tsx';
+export type { MassCommandProviderProps } from './MassCommandProvider.tsx';
+export { MassCommandProvider } from './MassCommandProvider.tsx';
+export type { MassCommandTooltipProps } from './MassCommandTooltip.tsx';
+export { MassCommandTooltip } from './MassCommandTooltip.tsx';
+export type { MassDocumentationDialogProps } from './MassDocumentationDialog.tsx';
+export { MassDocumentationDialog } from './MassDocumentationDialog.tsx';
+export type { MassEditorProps } from './MassEditor.tsx';
+export { MassEditor } from './MassEditor.tsx';
+export { MassHeader } from './MassHeader.tsx';
+export type { MassLogoProps } from './MassLogo.tsx';
+export { MassLogo } from './MassLogo.tsx';
+export type { MassPointerTrackerProps } from './MassPointerTracker.tsx';
+export { MassPointerTracker } from './MassPointerTracker.tsx';
+export type { MassSidePanelProps } from './MassSidePanel.tsx';
+export { MassSidePanel } from './MassSidePanel.tsx';
+export type { MassStateProviderProps } from './MassStateProvider.tsx';
+export { MassStateProvider } from './MassStateProvider.tsx';
+export { MassStatusBar } from './MassStatusBar.tsx';
+export type { MassToolbarProps } from './MassToolbar.tsx';
+export { MassToolbar } from './MassToolbar.tsx';
+export type { MassMetadataProps } from './MetadataPanel.tsx';
+export { MassMetadata, MetadataPanel } from './MetadataPanel.tsx';
+export type { MzDecimalsMenuProps } from './MzDecimalsMenu.tsx';
+export { MzDecimalsMenu } from './MzDecimalsMenu.tsx';
+export type { PeakLabelsProps } from './PeakLabels.tsx';
+export { PeakLabels } from './PeakLabels.tsx';
+export type { PeakSortKey, PeakTableProps } from './PeakTable.tsx';
+export { PeakTable } from './PeakTable.tsx';
+export type { PeaksPanelProps } from './PeaksPanel.tsx';
+export { PeaksPanel } from './PeaksPanel.tsx';
+export { SpectraPanel } from './SpectraPanel.tsx';
+export type { SpectrumRowProps } from './SpectrumRow.tsx';
+export { SpectrumRow } from './SpectrumRow.tsx';
+export type { SpectrumTraceProps } from './SpectrumTrace.tsx';
+export { SpectrumTrace } from './SpectrumTrace.tsx';
+export type { MassEditorActions } from './massActions.ts';
+export { createMassActions } from './massActions.ts';
+export type { MassChartProps } from './massChartProps.ts';
+export type { MassCommandContextValue } from './massCommandContext.tsx';
+export { useMassCommand, useMassCommandProps } from './massCommandContext.tsx';
+export type { MassHostPanel, MassStackPanel } from './massHostPanels.ts';
+export { isMassHostPanel, massStackPanels } from './massHostPanels.ts';
+export { useMassActions, useMassEditorState } from './massStateContext.ts';
+export type { IntensityZoom } from './useIntensityZoom.ts';
+export { useIntensityZoom } from './useIntensityZoom.ts';
+export type { MassEditorApi, UseMassEditorOptions } from './useMassEditor.ts';
+export { useMassEditor } from './useMassEditor.ts';
+export type { MassFiles } from './useMassFiles.ts';
+export { useMassFiles } from './useMassFiles.ts';
+export type { MassPointerOptions, MassReadout } from './useMassPointer.ts';
+export { sameMassReadout, useMassPointer } from './useMassPointer.ts';
+export { useMassShortcuts } from './useMassShortcuts.ts';
+export type { MassZoomClick, MassZoomOptions } from './useMassZoom.ts';
+export { useMassZoom } from './useMassZoom.ts';