react-cheminfo 0.28.0 → 0.30.0

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

package/src/ir/core/irReducer.ts

@@ -0,0 +1,273 @@
+/**
+ * Every change the viewer can undergo, as one function over one object.
+ *
+ * A reducer rather than a graph of signals, for the reason
+ * `docs/decisions.md` gives about the glycan editor: a published component must
+ * not impose a state library on the page that mounts it, and two viewers on one
+ * page must not share a module-level singleton. The state is a plain object, so a
+ * host can save it, restore it and compare it.
+ *
+ * Every case returns the state **itself** when it has nothing to do, so a render
+ * memoised on the state is not defeated by an action that changed nothing —
+ * selecting the spectrum already selected, closing an error that is already
+ * closed.
+ */
+
+import type { IrSidePanelId } from './irSidePanels.ts';
+import type { IrDomain, IrSpectrum } from './irSpectrum.ts';
+import type { IrSettings, IrState, IrTool, PartialIrState } from './irState.ts';
+import {
+  DEFAULT_SETTINGS,
+  DEFAULT_SIDE_PANELS,
+  isIrWindow,
+  mergeIrSettings,
+} from './irState.ts';
+
+/** Everything that can be asked of the viewer. */
+export type IrAction =
+  | { type: 'addSpectra'; spectra: IrSpectrum[] }
+  | { type: 'setSpectra'; spectra: IrSpectrum[] }
+  | { type: 'removeSpectrum'; id: string }
+  | { type: 'renameSpectrum'; id: string; name: string }
+  | { type: 'setSpectrumColor'; id: string; color: string }
+  | { type: 'setSpectrumVisible'; id: string; visible: boolean }
+  | { type: 'selectSpectrum'; id: string | null }
+  | { type: 'setDomain'; domain: IrDomain }
+  | { type: 'resetDomain' }
+  | { type: 'setTool'; tool: IrTool }
+  | { type: 'togglePanel'; panelId: IrSidePanelId }
+  | { type: 'setError'; error: string | null }
+  | { type: 'setSettings'; settings: Partial<IrSettings> }
+  | { type: 'loadState'; state: PartialIrState }
+  | { type: 'clear' };
+
+/** What a viewer opens on. */
+export interface CreateIrStateOptions {
+  /**
+   * The spectra to open on.
+   * @default []
+   */
+  spectra?: IrSpectrum[];
+  /**
+   * The workspace to open in.
+   * @default DEFAULT_SETTINGS
+   */
+  settings?: Partial<IrSettings>;
+  /**
+   * The panels open to begin with.
+   * @default DEFAULT_SIDE_PANELS
+   */
+  panelIds?: IrSidePanelId[];
+}
+
+/**
+ * The state a viewer opens with.
+ *
+ * The panel list is spread rather than stored by reference: a caller's array is
+ * the caller's to mutate, and a viewer holding it would find its open panels
+ * changing under it.
+ * @param options - What it opens on.
+ * @returns The state.
+ */
+export function createIrState(options: CreateIrStateOptions = {}): IrState {
+  const { spectra = [], settings, panelIds } = options;
+  return {
+    data: { spectra: [...spectra] },
+    view: {
+      selectedId: spectra[0]?.id ?? null,
+      domain: null,
+      tool: 'read',
+      openPanelIds: [...(panelIds ?? DEFAULT_SIDE_PANELS)],
+      error: null,
+    },
+    settings: mergeIrSettings(DEFAULT_SETTINGS, settings),
+  };
+}
+
+/**
+ * Fold one action into the state.
+ * @param state - The state in force.
+ * @param action - What is being asked.
+ * @returns The new state, or the old one when nothing changed.
+ */
+export function irReducer(state: IrState, action: IrAction): IrState {
+  switch (action.type) {
+    case 'addSpectra': {
+      if (action.spectra.length === 0) return state;
+      const spectra = [...state.data.spectra, ...action.spectra];
+      return {
+        ...state,
+        data: { spectra },
+        view: {
+          ...state.view,
+          // Whatever arrived is what somebody wants to look at, so it takes the
+          // selection — but only when nothing was selected, since a spectrum
+          // added for comparison must not steal the panels from the one being
+          // read.
+          selectedId: state.view.selectedId ?? action.spectra[0]?.id ?? null,
+          error: null,
+        },
+      };
+    }
+
+    case 'setSpectra': {
+      return {
+        ...state,
+        data: { spectra: [...action.spectra] },
+        view: {
+          ...state.view,
+          selectedId: action.spectra[0]?.id ?? null,
+          // Replacing what is drawn is the one change that throws the window
+          // away: a window over one spectrum's wavenumbers means nothing over
+          // another's, and the chart refits when it is handed `null`.
+          domain: null,
+          error: null,
+        },
+      };
+    }
+
+    case 'removeSpectrum': {
+      const spectra = state.data.spectra.filter(
+        (spectrum) => spectrum.id !== action.id,
+      );
+      if (spectra.length === state.data.spectra.length) return state;
+      return {
+        ...state,
+        data: { spectra },
+        view: {
+          ...state.view,
+          selectedId:
+            state.view.selectedId === action.id
+              ? (spectra[0]?.id ?? null)
+              : state.view.selectedId,
+        },
+      };
+    }
+
+    case 'renameSpectrum': {
+      const name = action.name.trim();
+      if (name === '') {
+        return withError(state, 'A spectrum needs a name to be called by.');
+      }
+      return mapSpectrum(state, action.id, (spectrum) =>
+        spectrum.name === name ? spectrum : { ...spectrum, name },
+      );
+    }
+
+    case 'setSpectrumColor': {
+      return mapSpectrum(state, action.id, (spectrum) =>
+        spectrum.color === action.color
+          ? spectrum
+          : { ...spectrum, color: action.color },
+      );
+    }
+
+    case 'setSpectrumVisible': {
+      return mapSpectrum(state, action.id, (spectrum) =>
+        spectrum.visible === action.visible
+          ? spectrum
+          : { ...spectrum, visible: action.visible },
+      );
+    }
+
+    case 'selectSpectrum': {
+      if (state.view.selectedId === action.id) return state;
+      return { ...state, view: { ...state.view, selectedId: action.id } };
+    }
+
+    case 'setDomain': {
+      if (!isIrWindow(action.domain)) return state;
+      return { ...state, view: { ...state.view, domain: action.domain } };
+    }
+
+    case 'resetDomain': {
+      if (state.view.domain === null) return state;
+      return { ...state, view: { ...state.view, domain: null } };
+    }
+
+    case 'setTool': {
+      if (state.view.tool === action.tool) return state;
+      return { ...state, view: { ...state.view, tool: action.tool } };
+    }
+
+    case 'togglePanel': {
+      const { openPanelIds } = state.view;
+      const open = openPanelIds.includes(action.panelId);
+      return {
+        ...state,
+        view: {
+          ...state.view,
+          openPanelIds: open
+            ? openPanelIds.filter((id) => id !== action.panelId)
+            : [...openPanelIds, action.panelId],
+        },
+      };
+    }
+
+    case 'setError': {
+      if (state.view.error === action.error) return state;
+      return { ...state, view: { ...state.view, error: action.error } };
+    }
+
+    case 'setSettings': {
+      const settings = mergeIrSettings(state.settings, action.settings);
+      return { ...state, settings };
+    }
+
+    case 'loadState': {
+      const { data, view, settings } = action.state;
+      return {
+        data: data === undefined ? state.data : { spectra: [...data.spectra] },
+        view: { ...state.view, ...view },
+        settings: mergeIrSettings(state.settings, settings),
+      };
+    }
+
+    case 'clear': {
+      if (state.data.spectra.length === 0 && state.view.error === null) {
+        return state;
+      }
+      return {
+        ...state,
+        data: { spectra: [] },
+        view: { ...state.view, selectedId: null, domain: null, error: null },
+      };
+    }
+    /* Every action is handled above, and TypeScript is what keeps that true
+       when one is added — so there is nothing for a fallback to do. */
+    // no default
+  }
+}
+
+/**
+ * Change one spectrum, leaving the state alone when it did not change.
+ * @param state - The state in force.
+ * @param id - Which spectrum.
+ * @param change - What to make of it; return it unchanged for no change.
+ * @returns The new state, or the old one.
+ */
+function mapSpectrum(
+  state: IrState,
+  id: string,
+  change: (spectrum: IrSpectrum) => IrSpectrum,
+): IrState {
+  let changed = false;
+  const spectra = state.data.spectra.map((spectrum) => {
+    if (spectrum.id !== id) return spectrum;
+    const next = change(spectrum);
+    if (next !== spectrum) changed = true;
+    return next;
+  });
+  if (!changed) return state;
+  return { ...state, data: { spectra }, view: { ...state.view, error: null } };
+}
+
+/**
+ * Refuse an action, saying why.
+ * @param state - The state in force.
+ * @param error - The sentence to show whoever asked.
+ * @returns The state carrying the refusal.
+ */
+function withError(state: IrState, error: string): IrState {
+  return { ...state, view: { ...state.view, error } };
+}

package/src/ir/core/irSidePanels.ts

@@ -0,0 +1,20 @@
+import type { ActivityBarItemProps } from 'react-science/ui';
+
+/**
+ * The panels the side of the viewer can hold, in the order their icons stack.
+ *
+ * One frozen list read by both the activity bar and the panel stack, so a panel
+ * switched off and on again comes back where it was rather than at the end.
+ */
+export const irSidePanels = [
+  { id: 'spectra', title: 'Spectra', icon: 'timeline-line-chart' },
+  { id: 'bands', title: 'Bands', icon: 'th-list' },
+  { id: 'metadata', title: 'Acquisition', icon: 'properties' },
+] as const satisfies ReadonlyArray<{
+  id: string;
+  title: string;
+  icon: ActivityBarItemProps['icon'];
+}>;
+
+/** Identity of one of the panels the activity bar offers. */
+export type IrSidePanelId = (typeof irSidePanels)[number]['id'];