react-cheminfo 0.28.0 → 0.29.0

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;
+}

package/src/ir/core/irEditorApi.ts

@@ -0,0 +1,44 @@
+/**
+ * The handle a host drives the viewer through.
+ *
+ * A handle rather than props, for the reason NMRium uses one: "frame this band"
+ * and "take these spectra" are *gestures*, and a gesture expressed as a prop has
+ * to change to be obeyed — so asking for the same window twice does nothing the
+ * second time, and a host ends up inventing a nonce to make it work.
+ */
+
+import type { IrDomain, IrSpectrum } from './irSpectrum.ts';
+
+/** How much room to leave either side of a band a host asks to be framed. */
+export interface ZoomToBandOptions {
+  /**
+   * How wide the window is, in cm⁻¹.
+   * @default 200
+   */
+  width?: number;
+}
+
+/** What a host can ask of the viewer. */
+export interface IrEditorHandle {
+  /** The spectra that are open, in the order they were loaded. */
+  getSpectra: () => IrSpectrum[];
+  /** Draw these instead of what is open, and refit to them. */
+  setSpectra: (spectra: IrSpectrum[]) => void;
+  /** Draw these as well as what is open. */
+  addSpectra: (spectra: IrSpectrum[]) => void;
+  /** Close every spectrum. */
+  clear: () => void;
+  /** Show this window. */
+  setDomain: (domain: IrDomain) => void;
+  /** Show what fits. */
+  resetDomain: () => void;
+  /**
+   * Frame a wavenumber, keeping the value axis as it is.
+   *
+   * The commonest thing a host wants: a band named in a table beside the viewer
+   * is clicked, and the chart should go there.
+   */
+  zoomToWavenumber: (wavenumber: number, options?: ZoomToBandOptions) => void;
+  /** Point the panels at one spectrum, or at none. */
+  selectSpectrum: (id: string | null) => void;
+}

package/src/ir/core/irFormat.ts

@@ -0,0 +1,57 @@
+/**
+ * How a wavenumber and a value are written, wherever they are written.
+ *
+ * One module for it because the chart labels, the crosshair readout and any
+ * table beside them must agree to the digit: a band the chart calls 1715 and a
+ * row that calls it 1714.6 read as two bands.
+ */
+
+import type { IrMode } from './irSpectrum.ts';
+
+/** How many decimals an absorbance is written to. */
+export const ABSORBANCE_DECIMALS = 3;
+
+/** How many a percent transmittance is written to. */
+export const TRANSMITTANCE_DECIMALS = 1;
+
+/**
+ * Write a wavenumber the way a chemist quotes one.
+ *
+ * As a whole number, because that is the precision the measurement actually
+ * carries: a bench instrument samples every 2 or 4 cm⁻¹ and a printed
+ * assignment is never quoted to a decimal. Writing 1714.6 would claim a
+ * resolution the spectrum does not have.
+ * @param wavenumber - The wavenumber, in cm⁻¹.
+ * @returns The number as a string, or an empty string when there is no number.
+ */
+export function formatWavenumber(wavenumber: number): string {
+  if (!Number.isFinite(wavenumber)) return '';
+  return Math.round(wavenumber).toString();
+}
+
+/**
+ * Write a value in whichever axis it belongs to.
+ *
+ * Three decimals for an absorbance and one for a percent transmittance, which is
+ * roughly the same precision expressed two ways — an absorbance of 0.001 and a
+ * transmittance of 0.2 percent are both about where a real spectrum's noise
+ * sits.
+ * @param value - The value.
+ * @param mode - Which axis it is in.
+ * @returns The number as a string, without its unit.
+ */
+export function formatIrValue(value: number, mode: IrMode): string {
+  if (!Number.isFinite(value)) return '';
+  return value.toFixed(
+    mode === 'absorbance' ? ABSORBANCE_DECIMALS : TRANSMITTANCE_DECIMALS,
+  );
+}
+
+/**
+ * What the value axis is called where there is room for one word.
+ * @param mode - Which axis is being drawn.
+ * @returns `A` or `%T`, as a spectrum is annotated by hand.
+ */
+export function shortModeLabel(mode: IrMode): string {
+  return mode === 'absorbance' ? 'A' : '%T';
+}

package/src/ir/core/irMode.ts

@@ -0,0 +1,203 @@
+/**
+ * Everything that differs between reading a spectrum as absorbance and reading
+ * it as percent transmittance.
+ *
+ * The two are the same measurement drawn upside down, and nearly every
+ * difference between them is one of a handful of facts: what the axis is called,
+ * where its baseline is, whether that baseline is held in the window, which way
+ * a band points, and which zoom gestures are worth answering. Gathering them
+ * here is what keeps the switch from being an `if (mode === …)` in the chart,
+ * the tracker, the band marks, the zoom and the fitting separately, where they
+ * would eventually disagree.
+ *
+ * **No conversion happens here, or anywhere in this package.** `ir-spectrum`
+ * adds both an absorbance and a transmittance variable to every spectrum it
+ * reads, whichever the instrument wrote, so the arithmetic that relates them is
+ * its business and is done once at the point the file is understood. A second
+ * implementation here would be a second answer.
+ */
+
+import type {
+  YAxisRules,
+  ZoomDragMode,
+  ZoomGestures,
+} from '../../chart/core/chartDomain.ts';
+
+import type { IrMode } from './irSpectrum.ts';
+
+/** The two ways a spectrum is read, in the order a control offers them. */
+export const IR_MODES: readonly IrMode[] = ['transmittance', 'absorbance'];
+
+/**
+ * How each mode behaves, every fact in one place.
+ *
+ * `transmittance` comes first because it is what the majority of instruments
+ * export and what most chemists picture when they say "the IR": bands hanging
+ * down from a baseline near 100.
+ */
+export const IR_MODE_RULES = {
+  transmittance: {
+    /** What the vertical axis is called. */
+    title: 'transmittance (%)',
+    /**
+     * The clear baseline a band hangs from, which the wheel scales about.
+     *
+     * A hundred rather than zero, and this is the whole reason `YAxisRules`
+     * exists: scaling percent transmittance about zero walks the entire trace
+     * off the top of the plot, because the trace lives just under 100 and
+     * nothing interesting is near the origin.
+     */
+    baseline: 100,
+    /**
+     * Whether 100 is held inside the window a drag asks for.
+     *
+     * It is not. A band dragged out between 20 and 60 percent is being asked
+     * about between 20 and 60 percent; forcing the baseline back in would undo
+     * the zoom in the act of granting it. This is the opposite of a mass
+     * spectrum, whose sticks are drawn *from* their baseline and are cut off at
+     * the ankles without it.
+     */
+    keepBaseline: false,
+    /** Bands point down, away from the baseline above them. */
+    bandsPointDown: true,
+    /**
+     * A drag is the rectangle it sweeps out, whatever tool is chosen.
+     *
+     * Percent transmittance is bounded at both ends and the trace fills nearly
+     * all of it, so the question this axis is asked is never "between which two
+     * percentages" — it is "look closer at that corner", which is a rectangle
+     * and nothing else. Leaving the reading gesture available here would offer a
+     * choice between one useful answer and one that changes nothing.
+     */
+    boxZoomOnly: true,
+    /**
+     * The wheel is left to the page.
+     *
+     * The axis is bounded — a transmittance is a percentage of the light that
+     * got through, so it lies between 0 and 100 and the trace already fills it.
+     * Scaling it freely about 100 therefore only ever takes the window past one
+     * end or crushes it against the other, which is a poor thing to have a
+     * pointer resting over a chart do by accident. The rectangle asks the same
+     * question properly, by naming the two percentages it lands between.
+     *
+     * The zoom in and zoom out **commands** still scale the axis here: they are
+     * aimed at, they step by a known factor, and the reader who pressed one
+     * knows what it did.
+     */
+    wheelZoom: false,
+  },
+  absorbance: {
+    title: 'absorbance',
+    /** Zero absorbance is a real floor: no light absorbed. */
+    baseline: 0,
+    /**
+     * Whether zero is held inside the window a drag asks for.
+     *
+     * It is not, for the same reason as transmittance: a weak band between 0.02
+     * and 0.05 absorbance is unreadable in a window that starts at zero, and
+     * being able to drag to it is the point of the gesture. Zero remains the
+     * baseline the wheel scales about, which is what keeps the trace anchored.
+     */
+    keepBaseline: false,
+    /** Bands point up, out of the baseline under them. */
+    bandsPointDown: false,
+    /**
+     * Both drags are worth having, so the tool decides between them.
+     *
+     * Absorbance is open at the top and its weak bands lie against zero, so "what
+     * is between 1650 and 1750" and "what is in that rectangle" are two different
+     * questions a chemist genuinely asks of the same trace.
+     */
+    boxZoomOnly: false,
+    /**
+     * The wheel scales the axis about zero, which is what brings a weak band up
+     * out of the baseline without narrowing the wavenumbers at all.
+     */
+    wheelZoom: true,
+  },
+} as const satisfies Record<
+  IrMode,
+  {
+    title: string;
+    baseline: number;
+    keepBaseline: boolean;
+    bandsPointDown: boolean;
+    boxZoomOnly: boolean;
+    wheelZoom: boolean;
+  }
+>;
+
+/**
+ * What the vertical axis is called in a mode.
+ * @param mode - Which value axis is being drawn.
+ * @returns The axis title.
+ */
+export function yAxisTitle(mode: IrMode): string {
+  return IR_MODE_RULES[mode].title;
+}
+
+/**
+ * How the vertical axis behaves under a gesture in a mode.
+ * @param mode - Which value axis is being drawn.
+ * @returns The rules to hand to the zoom.
+ */
+export function yAxisRules(mode: IrMode): YAxisRules {
+  const { baseline, keepBaseline, bandsPointDown } = IR_MODE_RULES[mode];
+  // `pointsDown` is what tells the zoom which way "released past the baseline"
+  // points: percent transmittance hangs from 100 at the top of the plot, so the
+  // gesture is a drag released above it rather than below.
+  return { baseline, keepBaseline, pointsDown: bandsPointDown };
+}
+
+/**
+ * Which zoom gestures a mode answers, and what a drag in it asks for.
+ *
+ * The mode has the last word on the drag rather than the tool, because the tool
+ * is a preference and this is not: percent transmittance has one useful drag,
+ * and a viewer that let a tool button ask for the other would answer with a
+ * gesture that narrows the wavenumbers and leaves the crowded axis exactly as it
+ * was. The tool is still read — in absorbance both drags mean something — so a
+ * chemist who chose the square zoom keeps it across a switch to %T and back.
+ * @param mode - Which value axis is being drawn.
+ * @param tool - What a drag asks for where the mode leaves the choice open.
+ * Defaults to the reading gesture.
+ * @returns The gestures to hand to the zoom.
+ */
+export function zoomGestures(
+  mode: IrMode,
+  tool: ZoomDragMode = 'xAxis',
+): Required<ZoomGestures> {
+  const { boxZoomOnly, wheelZoom } = IR_MODE_RULES[mode];
+  return { drag: boxZoomOnly ? 'box' : tool, wheel: wheelZoom };
+}
+
+/**
+ * Whether a mode leaves the square zoom as the only drag there is.
+ *
+ * What the toolbar and the status bar need in order to say so: a tool button
+ * showing `read` as available in percent transmittance would be describing a
+ * gesture the chart will not make.
+ * @param mode - Which value axis is being drawn.
+ * @returns Whether every drag is a rectangle.
+ */
+export function boxZoomOnly(mode: IrMode): boolean {
+  return IR_MODE_RULES[mode].boxZoomOnly;
+}
+
+/**
+ * Which way a band points in a mode, which is which way its label is stacked.
+ * @param mode - Which value axis is being drawn.
+ * @returns Whether bands hang downwards.
+ */
+export function bandsPointDown(mode: IrMode): boolean {
+  return IR_MODE_RULES[mode].bandsPointDown;
+}
+
+/**
+ * The other mode, for a control that toggles between the two.
+ * @param mode - The mode in force.
+ * @returns The one to switch to.
+ */
+export function otherIrMode(mode: IrMode): IrMode {
+  return mode === 'absorbance' ? 'transmittance' : 'absorbance';
+}