react-cheminfo 0.28.0 → 0.30.0

package/src/ir/core/downloadSpectra.ts

@@ -0,0 +1,57 @@
+/**
+ * Handing spectra over as a file, from the list they are drawn from.
+ *
+ * Kept apart from `spectrumJcamp.ts` so that what a file holds can be tested
+ * without a DOM, and so that a page wanting the text for something other than a
+ * download — a POST to an ELN, a zip of a whole session — reaches for the writer
+ * and not for this.
+ */
+
+import { downloadText } from '../../download/core/downloadText.ts';
+import { sanitizeFileName } from '../../download/core/sanitizeFileName.ts';
+
+import type { IrMode, IrSpectrum } from './irSpectrum.ts';
+import {
+  JCAMP_EXTENSION,
+  JCAMP_MIME_TYPE,
+  irSpectraToJcamp,
+  irSpectrumToJcamp,
+} from './spectrumJcamp.ts';
+
+/**
+ * Download one spectrum, named after what the list calls it.
+ * @param spectrum - The spectrum.
+ * @param mode - The axis being read, used when the file named none.
+ */
+export function downloadIrSpectrum(spectrum: IrSpectrum, mode: IrMode): void {
+  downloadText(
+    irSpectrumToJcamp(spectrum, mode),
+    `${sanitizeFileName(spectrum.name, 'spectrum')}${JCAMP_EXTENSION}`,
+    JCAMP_MIME_TYPE,
+  );
+}
+
+/**
+ * Download the whole list as one file.
+ *
+ * A list of one is saved under that spectrum's own name, since the file is that
+ * spectrum: a chemist who has one spectrum open and asks the panel for it should
+ * not have to work out which of their downloads `spectra.jdx` was.
+ * @param spectra - The spectra, in the order the list holds them.
+ * @param mode - The axis being read, used for a spectrum whose file named none.
+ */
+export function downloadIrSpectra(
+  spectra: readonly IrSpectrum[],
+  mode: IrMode,
+): void {
+  const only = spectra.length === 1 ? spectra[0] : undefined;
+  if (only !== undefined) {
+    downloadIrSpectrum(only, mode);
+    return;
+  }
+  downloadText(
+    irSpectraToJcamp(spectra, mode),
+    `spectra${JCAMP_EXTENSION}`,
+    JCAMP_MIME_TYPE,
+  );
+}

package/src/ir/core/fromJcamp.ts

@@ -0,0 +1,70 @@
+/**
+ * Read a JCAMP-DX file into infrared spectra.
+ *
+ * `ir-spectrum` does the reading, which matters for one reason worth stating: it
+ * adds an absorbance and a percent transmittance variable to every spectrum it
+ * builds, whichever of the two the instrument wrote. So a file exported as
+ * transmittance and one exported as absorbance arrive carrying both axes, and
+ * nothing downstream has to know which it was — or to do the conversion itself.
+ */
+
+import type { TextData } from 'cheminfo-types';
+import { fromJcamp as irAnalysis } from 'ir-spectrum';
+
+import { describeSource, errorMessage } from '../../error/core/index.ts';
+
+import type { LoadedIrSpectrum } from './analysisSpectra.ts';
+import { analysisSpectra } from './analysisSpectra.ts';
+
+/** How a JCAMP is read. */
+export interface IrJcampReadOptions {
+  /**
+   * The file's name, carried onto every spectrum it produced.
+   * @default undefined
+   */
+  fileName?: string;
+}
+
+/**
+ * Read every infrared spectrum a JCAMP-DX file holds.
+ *
+ * All of them, never the first: a JCAMP is a container, and an instrument
+ * exporting a sample beside its background writes both as blocks of one file.
+ * Taking only the first would quietly drop the block the chemist exported the
+ * file for, and would do it without an error, which is the worst way to lose
+ * data.
+ * @param data - The file, as bytes or as text.
+ * @param options - The file's name.
+ * @returns One entry per block, in the order the file wrote them.
+ * @throws {Error} When the file holds no readable spectrum, or when the
+ * converter gave up on it.
+ */
+export function fromJcamp(
+  data: TextData,
+  options: IrJcampReadOptions = {},
+): LoadedIrSpectrum[] {
+  const { fileName } = options;
+
+  let spectra: LoadedIrSpectrum[];
+  try {
+    const origin: LoadedIrSpectrum['origin'] = { format: 'jcamp' };
+    if (fileName !== undefined) origin.fileName = fileName;
+    spectra = analysisSpectra(irAnalysis(data), origin);
+  } catch (error) {
+    // The converter's own words are kept because they name the record it
+    // stopped on, which is more than anything written here could say — but they
+    // are said about nothing, and a chemist who has just dropped eleven files
+    // needs to know which of them this is.
+    throw new Error(
+      `${describeSource(fileName)} could not be read as JCAMP-DX — the converter stopped on it with: ${errorMessage(error)}`,
+      { cause: error },
+    );
+  }
+
+  if (spectra.length === 0) {
+    throw new Error(
+      `${describeSource(fileName)} was read as JCAMP-DX but holds no infrared spectrum — no block in it carries an XY data record with at least two points.`,
+    );
+  }
+  return spectra;
+}

package/src/ir/core/fromSpc.ts

@@ -0,0 +1,61 @@
+/**
+ * Read a Thermo Galactic SPC file into infrared spectra.
+ *
+ * `ir-spectrum` does the reading, through `spc-parser`, and adds both value axes
+ * exactly as it does for a JCAMP — so an SPC and a JCAMP of the same measurement
+ * reach the viewer indistinguishable but for their `origin`.
+ */
+
+import { fromSPC as irAnalysis } from 'ir-spectrum';
+
+import { describeSource, errorMessage } from '../../error/core/index.ts';
+
+import type { LoadedIrSpectrum } from './analysisSpectra.ts';
+import { analysisSpectra } from './analysisSpectra.ts';
+
+/** How an SPC file is read. */
+export interface IrSpcReadOptions {
+  /**
+   * The file's name, carried onto every spectrum it produced.
+   * @default undefined
+   */
+  fileName?: string;
+}
+
+/**
+ * Read every infrared spectrum an SPC file holds.
+ *
+ * SPC is a multi-file format in its own right — one file can carry a whole
+ * kinetic series — so every subfile becomes a spectrum, for the same reason
+ * every JCAMP block does.
+ * @param data - The file, as bytes.
+ * @param options - The file's name.
+ * @returns One entry per subfile, in the order the file wrote them.
+ * @throws {Error} When the file holds no readable spectrum, or when the parser
+ * gave up on it.
+ */
+export function fromSpc(
+  data: ArrayBuffer | Uint8Array,
+  options: IrSpcReadOptions = {},
+): LoadedIrSpectrum[] {
+  const { fileName } = options;
+
+  let spectra: LoadedIrSpectrum[];
+  try {
+    const origin: LoadedIrSpectrum['origin'] = { format: 'spc' };
+    if (fileName !== undefined) origin.fileName = fileName;
+    spectra = analysisSpectra(irAnalysis(data), origin);
+  } catch (error) {
+    throw new Error(
+      `${describeSource(fileName)} could not be read as SPC — the parser stopped on it with: ${errorMessage(error)}`,
+      { cause: error },
+    );
+  }
+
+  if (spectra.length === 0) {
+    throw new Error(
+      `${describeSource(fileName)} was read as SPC but holds no infrared spectrum — no subfile in it carries at least two points.`,
+    );
+  }
+  return spectra;
+}

package/src/ir/core/index.ts

@@ -0,0 +1,113 @@
+/**
+ * What an infrared spectrum is, and everything true of one that draws nothing.
+ *
+ * Reading a file, picking the bands, saying what each band might be, writing
+ * the spectra back out as JCAMP — none of it needs React, so a script that
+ * assigns a directory of spectra loads none.
+ *
+ * What is here is only what is true of infrared: that the axis runs from 4000
+ * down to 400, that a spectrum is read either as absorbance or as percent
+ * transmittance and a band points the other way in each, and that a wavenumber
+ * maps to a range of vibrations rather than to one. Nothing here knows what a
+ * glycan is, and nothing should: an infrared spectrum answers for whatever was
+ * put in the beam.
+ */
+
+export type { LoadedIrSpectrum } from './analysisSpectra.ts';
+export { analysisSpectra } from './analysisSpectra.ts';
+export type { AssignBandsOptions, AssignedBand } from './assignBands.ts';
+export { assignBands, bandLabel, countAssigned } from './assignBands.ts';
+export type { BandAssignment } from './bandAssignments.ts';
+export { BAND_ASSIGNMENTS } from './bandAssignments.ts';
+export type { BandLabelPlan, BandLabelPlanOptions } from './bandLabelPlan.ts';
+export { planBandLabels } from './bandLabelPlan.ts';
+export { detectIrFormat } from './detectIrFormat.ts';
+export { downloadIrSpectra, downloadIrSpectrum } from './downloadSpectra.ts';
+export type { IrJcampReadOptions } from './fromJcamp.ts';
+export type { IrSpcReadOptions } from './fromSpc.ts';
+export type { IrBand, IrBandStrength } from './irBand.ts';
+export { sameIrBand } from './irBand.ts';
+export type {
+  IrCommand,
+  IrCommandHandlers,
+  IrCommandId,
+  IrGesture,
+  IrShortcut,
+  RunIrCommand,
+} from './irCommands.ts';
+export { irCommandLabel, irCommands } from './irCommands.ts';
+export {
+  LABEL_HEADROOM,
+  X_DOMAIN_PADDING,
+  Y_DOMAIN_PADDING,
+  fittedTo,
+  fullDomain,
+} from './irDomain.ts';
+export type { IrEditorHandle, ZoomToBandOptions } from './irEditorApi.ts';
+export {
+  ABSORBANCE_DECIMALS,
+  TRANSMITTANCE_DECIMALS,
+  formatIrValue,
+  formatWavenumber,
+  shortModeLabel,
+} from './irFormat.ts';
+export {
+  IR_MODES,
+  IR_MODE_RULES,
+  bandsPointDown,
+  boxZoomOnly,
+  otherIrMode,
+  yAxisRules,
+  yAxisTitle,
+  zoomGestures,
+} from './irMode.ts';
+export type { CreateIrStateOptions, IrAction } from './irReducer.ts';
+export { createIrState, irReducer } from './irReducer.ts';
+export type {
+  IrDomain,
+  IrFormat,
+  IrMeta,
+  IrMetaField,
+  IrMode,
+  IrOrigin,
+  IrSpectrum,
+  IrTrace,
+} from './irSpectrum.ts';
+export { traceOf } from './irSpectrum.ts';
+export type {
+  IrData,
+  IrSettings,
+  IrState,
+  IrTool,
+  IrView,
+  PartialIrState,
+} from './irState.ts';
+export {
+  DEFAULT_LABEL_LIMIT,
+  DEFAULT_PICKING,
+  DEFAULT_SETTINGS,
+  DEFAULT_SIDE_PANEL,
+  DEFAULT_SIDE_PANELS,
+  MAXIMUM_LABEL_LIMIT,
+  isIrWindow,
+  mergeIrSettings,
+} from './irState.ts';
+export type {
+  LoadIrSpectraOptions,
+  LoadIrSpectraResult,
+} from './loadIrSpectra.ts';
+export { loadIrSpectra } from './loadIrSpectra.ts';
+export { BAND_HIT_RADIUS, nearestBandAt } from './nearestBand.ts';
+export type { PickBandsOptions } from './pickBands.ts';
+export { pickBands } from './pickBands.ts';
+export {
+  DEFAULT_DATA_TYPE,
+  JCAMP_EXTENSION,
+  JCAMP_MIME_TYPE,
+  irSpectraToJcamp,
+  irSpectrumToJcamp,
+} from './spectrumJcamp.ts';
+export type { ToIrSpectrumOptions } from './toIrSpectrum.ts';
+export { toIrSpectra, toIrSpectrum } from './toIrSpectrum.ts';
+export type { IrSidePanelId } from './irSidePanels.ts';
+export { irSidePanels } from './irSidePanels.ts';

package/src/ir/core/irBand.ts

@@ -0,0 +1,57 @@
+/**
+ * One band picked out of a spectrum.
+ *
+ * A band is the infrared analogue of a mass spectrum's peak: the thing a chemist
+ * points at, names, and reads a functional group off. It carries both value axes
+ * for the same reason the spectrum does — the band a reader sees at 30 percent
+ * transmittance and the one a table calls strongly absorbing are one band, and
+ * making the caller convert to find out would be the conversion this package
+ * does not do.
+ */
+
+/**
+ * How strong a band is, in the letters a correlation table uses.
+ *
+ * `w` weak, `m` medium, `S` strong — `ir-spectrum` decides which from where the
+ * band sits between the spectrum's own extremes, so the letters are relative to
+ * the spectrum in hand rather than to an absolute absorbance. That is what a
+ * printed table means by them too.
+ */
+export type IrBandStrength = 'w' | 'm' | 'S';
+
+/** One band picked out of one spectrum. */
+export interface IrBand {
+  /** Identity of the spectrum it was picked from. */
+  spectrumId: string;
+  /** Where it sits, in cm⁻¹. */
+  wavenumber: number;
+  /** Its absorbance, which is what it was picked as a maximum of. */
+  absorbance: number;
+  /** Its percent transmittance, the same band read the other way up. */
+  transmittance: number;
+  /** How strong it is, relative to the spectrum it came from. */
+  strength: IrBandStrength;
+}
+
+/**
+ * Whether two bands are the same band.
+ *
+ * The wavenumber is compared exactly, and that is not an oversight: both numbers
+ * were read out of the same picked band, so either they are the very same
+ * measurement or they are two different bands. A tolerance here would declare a
+ * carbonyl pair thirty wavenumbers apart to be one band.
+ * @param current - What was last reported.
+ * @param next - What would be reported now.
+ * @returns Whether the report can be skipped.
+ */
+export function sameIrBand(
+  current: IrBand | null,
+  next: IrBand | null,
+): boolean {
+  if (current === next) return true;
+  if (current === null || next === null) return false;
+  return (
+    current.spectrumId === next.spectrumId &&
+    current.wavenumber === next.wavenumber
+  );
+}

package/src/ir/core/irCommands.ts

@@ -0,0 +1,154 @@
+/**
+ * Everything the viewer offers, what each is called, and the key it answers to.
+ *
+ * One table, read by three things that must agree: the toolbar draws it, the
+ * tooltip explains it, and the key handler fires it. Written apart from all
+ * three so a command cannot be added to the toolbar without a name, or bound to
+ * a key nothing tells the reader about.
+ *
+ * The provider, the hooks and the tooltip are three files of their own beside
+ * this one, because a module that exports a component and a constant together
+ * cannot be hot reloaded — `react-refresh/only-export-components` is the rule
+ * that says so, and the split is the fix rather than the exception.
+ */
+
+/** The key a command answers to. */
+export interface IrShortcut {
+  /** The `event.key` values it fires on, the first being the one shown. */
+  keys: readonly string[];
+  /**
+   * How to write the key in a tooltip, where the raw value would read badly.
+   * @default the first of `keys`
+   */
+  label?: readonly string[];
+}
+
+/** A gesture that does the same thing, listed under the tooltip's title. */
+export interface IrGesture {
+  /** Where the gesture is made, or what it is made with. */
+  title: string;
+  /** The buttons, keys or wheel that make it. */
+  shortcuts: readonly string[];
+}
+
+/** One thing the viewer can be asked to do. */
+export interface IrCommand {
+  /** What it is called, which is what the tooltip is titled. */
+  title: string;
+  /**
+   * The key it answers to, absent for a command with none.
+   * @default undefined
+   */
+  shortcut?: IrShortcut;
+  /**
+   * What it does, in a sentence, under the title in the tooltip.
+   * @default undefined
+   */
+  description?: string;
+  /**
+   * The gestures that do the same thing, for the ones a key cannot describe.
+   * @default undefined
+   */
+  gestures?: readonly IrGesture[];
+}
+
+/** Everything the viewer offers, in the order it is reached for. */
+export const irCommands = {
+  about: {
+    title: 'About the infrared viewer',
+    description: 'What it reads, what it is built on, and what it credits.',
+  },
+  documentation: {
+    title: 'Documentation',
+    shortcut: { keys: ['h'] },
+    description:
+      'How to open a spectrum, what the panels hold, and every gesture.',
+  },
+  fullScreen: {
+    title: 'Full screen',
+    description:
+      'The viewer takes the whole screen rather than its corner of the page. Esc gives it back.',
+  },
+  readTool: {
+    title: 'Read',
+    shortcut: { keys: ['r'] },
+    description:
+      'A drag narrows the wavenumber axis, which is the question a spectrum is nearly always asked. Released past the baseline it takes the value axis with it. Reading absorbance only: percent transmittance is zoomed by rectangle alone.',
+    gestures: [{ title: 'Reading absorbance', shortcuts: ['Drag'] }],
+  },
+  boxTool: {
+    title: 'Square zoom',
+    shortcut: { keys: ['b'] },
+    description:
+      'A drag zooms to exactly the rectangle it sweeps out, both axes at once — for looking into a baseline or a shoulder rather than across the spectrum. It is the only drag on percent transmittance.',
+    gestures: [{ title: 'Over the chart', shortcuts: ['Drag a rectangle'] }],
+  },
+  zoomIn: {
+    title: 'Zoom in',
+    shortcut: { keys: ['+', '='] },
+    description: 'Brings the weak bands up, about the baseline they hang from.',
+    gestures: [{ title: 'Reading absorbance', shortcuts: ['Scroll wheel'] }],
+  },
+  zoomOut: {
+    title: 'Zoom out',
+    shortcut: { keys: ['-'] },
+    description: 'Puts the value axis back out again.',
+    gestures: [{ title: 'Reading absorbance', shortcuts: ['Scroll wheel'] }],
+  },
+  resetZoom: {
+    title: 'Zoom to fit',
+    shortcut: { keys: ['f'] },
+    description: 'Shows every spectrum that is drawn, whole.',
+    gestures: [{ title: 'Over the chart', shortcuts: ['Double click'] }],
+  },
+  toggleMode: {
+    title: 'Absorbance or transmittance',
+    shortcut: { keys: ['t'] },
+    description:
+      'The same measurement read the other way up. Bands hang down from 100 % transmittance and stand up out of zero absorbance.',
+  },
+  togglePicking: {
+    title: 'Pick the bands',
+    shortcut: { keys: ['p'] },
+    description:
+      'Finds the bands of the selected spectrum, marks them on the chart and lists them with everything each might be.',
+  },
+  toggleAssignments: {
+    title: 'Name the assignments',
+    shortcut: { keys: ['a'] },
+    description:
+      'Writes what each labelled band might be under its wavenumber. Worth turning off once the chart is crowded.',
+  },
+  exportImage: {
+    title: 'Export as an image…',
+    shortcut: { keys: ['x'] },
+    description:
+      'The chart as it stands, at a chosen resolution — PNG, or SVG, which is drawn again at whatever size it is printed rather than enlarged.',
+  },
+  clear: {
+    title: 'Close every spectrum',
+    description: 'Empties the chart and starts again.',
+  },
+} as const satisfies Record<string, IrCommand>;
+
+/** Identity of one of the commands the viewer offers. */
+export type IrCommandId = keyof typeof irCommands;
+
+/** What to do when each command is run, as the shell wires them. */
+export type IrCommandHandlers = Partial<
+  Record<IrCommandId, (() => void) | undefined>
+>;
+
+/** How a component runs a command. */
+export type RunIrCommand = (id: IrCommandId) => void;
+
+/**
+ * What a command is called, with its key, for a label and an `aria-label`.
+ * @param id - Which command.
+ * @returns The title, and the key in parentheses when it has one.
+ */
+export function irCommandLabel(id: IrCommandId): string {
+  const entry = irCommands[id] as IrCommand;
+  const key = entry.shortcut?.label?.[0] ?? entry.shortcut?.keys[0];
+  return key === undefined ? entry.title : `${entry.title} (${key})`;
+}

package/src/ir/core/irDomain.ts

@@ -0,0 +1,163 @@
+/**
+ * The window a chart opens on, worked out from the spectra it was handed.
+ *
+ * This is what "zoom to fit" and the first render both call, so it has to answer
+ * something usable when it is handed nothing at all — a chart with no data is
+ * still mounted, still measured, and still builds its scales.
+ *
+ * The x window is in ascending wavenumbers even though the axis is drawn from
+ * 4000 down to 400: which way round it is read is the chart's business, and
+ * every piece of arithmetic that moves a window expects its ends in order.
+ */
+
+import { xMaxValue, xMinValue } from 'ml-spectra-processing';
+
+import { bandsPointDown } from './irMode.ts';
+import type { IrDomain, IrMode, IrSpectrum } from './irSpectrum.ts';
+import { traceOf } from './irSpectrum.ts';
+
+/**
+ * How much air is left either side of the outermost point, as a fraction.
+ *
+ * A trace drawn hard against the axis reads as a spectrum that was cut off
+ * there; two percent is enough to show that it was not.
+ */
+export const X_DOMAIN_PADDING = 0.02;
+
+/** The same, on the value axis, where a trace touching an edge reads the same. */
+export const Y_DOMAIN_PADDING = 0.05;
+
+/**
+ * The extra room kept on the side the band labels occupy, as a fraction.
+ *
+ * A named band carries its wavenumber and its assignment on two lines, stacked
+ * away from the baseline — upwards from an absorbance maximum, downwards from a
+ * transmittance minimum — so the room has to be on a different side in each
+ * mode. Twenty percent is what those two lines take on a chart of any usual
+ * height.
+ */
+export const LABEL_HEADROOM = 0.2;
+
+/**
+ * The window that shows everything currently drawn.
+ *
+ * A spectrum marked `excludeFromDomain` is left out of the extents, because it
+ * is a reference held up for comparison rather than data: letting it move the
+ * axes would throw away the zoom the user set every time they held one up. The
+ * exclusion is dropped when it would leave nothing at all.
+ * @param spectra - Everything the chart holds, drawn or not.
+ * @param mode - Which value axis is being drawn, which decides both the extents
+ * and the side the label room is kept on.
+ * @returns The window, in wavenumbers and in the value axis.
+ */
+export function fullDomain(
+  spectra: readonly IrSpectrum[],
+  mode: IrMode,
+): IrDomain {
+  const extent =
+    traceExtent(spectra, mode, false) ?? traceExtent(spectra, mode, true);
+  if (extent === null) {
+    return mode === 'absorbance'
+      ? { x: [400, 4000], y: [0, 1] }
+      : { x: [400, 4000], y: [0, 100] };
+  }
+
+  const { xMinimum, xMaximum, yMinimum, yMaximum } = extent;
+  const xPadding = (xMaximum - xMinimum) * X_DOMAIN_PADDING;
+  // A spectrum of a single point has no width to take a fraction of.
+  const x: [number, number] =
+    xPadding > 0
+      ? [xMinimum - xPadding, xMaximum + xPadding]
+      : [xMinimum - 1, xMaximum + 1];
+
+  const ySpan = yMaximum - yMinimum;
+  const yPadding = ySpan > 0 ? ySpan * Y_DOMAIN_PADDING : 1;
+  const headroom = ySpan > 0 ? ySpan * LABEL_HEADROOM : 1;
+  const down = bandsPointDown(mode);
+  const y: [number, number] = [
+    yMinimum - (down ? headroom : yPadding),
+    yMaximum + (down ? yPadding : headroom),
+  ];
+  return { x, y };
+}
+
+/**
+ * What a fitted window was fitted *to*, as one string two renders can compare.
+ *
+ * The chart puts its window back to `fullDomain` when it is handed different
+ * data, and must not when the same data is merely redrawn — so something has to
+ * tell the two apart.
+ *
+ * **The mode is part of it**, and that is the one place this differs from a mass
+ * spectrum's fit key. Switching from transmittance to absorbance does not nudge
+ * the extents, it replaces the value axis outright — a window of 25 to 100
+ * percent means nothing at all in absorbance — so it has to refit, where a
+ * change of colour or of name must not.
+ * @param spectra - Everything the chart holds, drawn or not.
+ * @param mode - Which value axis is being drawn.
+ * @returns A string equal to itself exactly when a fit would be made to the
+ * same thing.
+ */
+export function fittedTo(spectra: readonly IrSpectrum[], mode: IrMode): string {
+  let key = mode;
+  for (const spectrum of spectra) {
+    if (spectrum.excludeFromDomain || !spectrum.visible) continue;
+    key += ` ${spectrum.id}`;
+  }
+  return key;
+}
+
+/** The extremes of a set of traces, before any padding is added. */
+interface TraceExtent {
+  /** The lowest wavenumber drawn. */
+  xMinimum: number;
+  /** The highest wavenumber drawn. */
+  xMaximum: number;
+  /** The lowest value drawn. */
+  yMinimum: number;
+  /** The highest value drawn. */
+  yMaximum: number;
+}
+
+/**
+ * The extremes over every trace that is currently drawn.
+ * @param spectra - Everything the chart holds.
+ * @param mode - Which value axis is being drawn.
+ * @param includeExcluded - Whether to count the spectra kept out of the domain.
+ * @returns The extremes, or `null` when nothing is drawn.
+ */
+function traceExtent(
+  spectra: readonly IrSpectrum[],
+  mode: IrMode,
+  includeExcluded: boolean,
+): TraceExtent | null {
+  let extent: TraceExtent | null = null;
+  for (const spectrum of spectra) {
+    if (!spectrum.visible) continue;
+    if (!includeExcluded && spectrum.excludeFromDomain) continue;
+    const { x, y } = traceOf(spectrum, mode);
+    if (x.length === 0 || y.length === 0) continue;
+    // The wavenumber ends are read off the first and last sample rather than
+    // searched for: the array is ascending by construction, so a scan would walk
+    // every point of the spectrum to learn what index zero already says.
+    const first = x[0] as number;
+    const last = x.at(-1) as number;
+    const lowest = xMinValue(y);
+    const highest = xMaxValue(y);
+    extent =
+      extent === null
+        ? {
+            xMinimum: first,
+            xMaximum: last,
+            yMinimum: lowest,
+            yMaximum: highest,
+          }
+        : {
+            xMinimum: Math.min(extent.xMinimum, first),
+            xMaximum: Math.max(extent.xMaximum, last),
+            yMinimum: Math.min(extent.yMinimum, lowest),
+            yMaximum: Math.max(extent.yMaximum, highest),
+          };
+  }
+  return extent;
+}