react-cheminfo 0.64.1 → 0.66.0

package/src/formula/ui/FormulaInput.tsx

@@ -0,0 +1,50 @@
+import { FormGroup, InputGroup } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+import { useId } from 'react';
+
+/** What {@link FormulaInput} needs. */
+export interface FormulaInputProps {
+  /** What the box is for, written above it. */
+  label: string;
+  /** What is in the box. */
+  value: string;
+  /** Called with the new text on every keystroke. */
+  onChange: (value: string) => void;
+  /**
+   * How to write what the box expects, under it.
+   * @default undefined
+   */
+  helper?: string;
+  /**
+   * Placeholder written in the empty box.
+   * @default undefined
+   */
+  placeholder?: string;
+}
+
+/**
+ * A box to type a molecular formula into, set in a monospace face and with
+ * every correction a phone or a browser would make switched off: a keyboard
+ * that capitalises `co` has written a different compound.
+ * @param props - Its label, its value and what to do on a change.
+ * @returns The box.
+ */
+export function FormulaInput(props: FormulaInputProps): ReactElement {
+  const { label, value, onChange, helper, placeholder } = props;
+  const id = useId();
+  return (
+    <FormGroup label={label} labelFor={id} helperText={helper}>
+      <InputGroup
+        id={id}
+        value={value}
+        placeholder={placeholder}
+        onValueChange={onChange}
+        autoComplete="off"
+        autoCorrect="off"
+        autoCapitalize="off"
+        spellCheck={false}
+        className="formula-input"
+      />
+    </FormGroup>
+  );
+}

package/src/formula/ui/QuestionFormula.tsx

@@ -0,0 +1,20 @@
+import type { ReactElement } from 'react';
+import { MF } from 'react-mf';
+
+import { normalizeFormula } from '../core/normalizeFormula.ts';
+
+/** What {@link QuestionFormula} draws. */
+export interface QuestionFormulaProps {
+  /** The formula, as the data writes it, in whatever notation it gives a charge. */
+  formula: string;
+}
+
+/**
+ * A formula as the list of a series names its question: subscripts and charge
+ * drawn, whatever notation the data writes the charge in.
+ * @param props - The formula.
+ * @returns The formula.
+ */
+export function QuestionFormula(props: QuestionFormulaProps): ReactElement {
+  return <MF mf={normalizeFormula(props.formula)} />;
+}

package/src/formula/ui/index.ts

@@ -0,0 +1,6 @@
+export type { CopyableFormulaProps } from './CopyableFormula.tsx';
+export { CopyableFormula } from './CopyableFormula.tsx';
+export type { FormulaInputProps } from './FormulaInput.tsx';
+export { FormulaInput } from './FormulaInput.tsx';
+export type { QuestionFormulaProps } from './QuestionFormula.tsx';
+export { QuestionFormula } from './QuestionFormula.tsx';

package/src/formula.ts

@@ -0,0 +1,11 @@
+/**
+ * Molecular formulas: read as a student types them, compared, written as HTML
+ * and Unicode, and drawn and copied with their subscripts.
+ *
+ * An entry point of its own, not part of `react-cheminfo/core` or `/ui`,
+ * because it is built on `mf-parser` and `react-mf`: a site that never shows a
+ * formula must not be made to install either.
+ */
+
+export * from './formula/core/index.ts';
+export * from './formula/ui/index.ts';

package/src/hooks/ui/index.ts

@@ -15,6 +15,7 @@ export { handleListNavigationKey } from './listNavigation.ts';
 export type { PollingOptions, PollingSnapshot } from './pollingController.ts';
 export type { ActiveHeadingOptions } from './useActiveHeading.ts';
 export { useActiveHeading } from './useActiveHeading.ts';
+export type { AsyncResult } from './useAsync.ts';
 export { useAsync } from './useAsync.ts';
 export { useContainerSize } from './useContainerSize.ts';
 export { useDebouncedValue } from './useDebouncedValue.ts';

package/src/hooks/ui/keyTargets.ts

@@ -1,7 +1,9 @@
 /**
  * Whether a key event is aimed at somewhere the visitor types: a text field, a
- * select, an editable region or anything carrying `role="textbox"`. A keyboard
- * shortcut listening above it leaves such a key alone.
+ * select, an editable region, anything carrying `role="textbox"`, or a canvas
+ * holding the focus — a structure editor reads its own keys there, `Delete`
+ * and the arrows included. A keyboard shortcut listening above it leaves such
+ * a key alone.
  * @param target - The `target` of the keyboard event.
  * @returns True when the key belongs to the field.
  */
@@ -42,7 +44,7 @@ export function isInteractiveTarget(
   return role !== null && INTERACTIVE_ROLES.has(role);
 }
 
-const TEXT_ENTRY_TAGS = new Set(['INPUT', 'TEXTAREA', 'SELECT']);
+const TEXT_ENTRY_TAGS = new Set(['INPUT', 'TEXTAREA', 'SELECT', 'CANVAS']);
 const INTERACTIVE_TAGS = new Set(['BUTTON', 'A', 'SUMMARY']);
 const INTERACTIVE_ROLES = new Set([
   'button',

package/src/hooks/ui/useAsync.ts

@@ -1,44 +1,80 @@
-import { useEffect, useState } from 'react';
+import { useEffect, useMemo, useState } from 'react';
 
 import type { AsyncState } from './asyncState.ts';
 import { ASYNC_LOADING, asyncFailed, asyncSucceeded } from './asyncState.ts';
 
+/**
+ * Where a task stands, and whether what is on screen still answers the
+ * question being asked.
+ */
+export type AsyncResult<TData> = AsyncState<TData> & {
+  /**
+   * True from the moment the question changes — a new task, a new
+   * `refreshKey` — until its run settles: the data on screen, if any, answers
+   * an earlier question. Also true while the very first run is loading.
+   */
+  pending: boolean;
+};
+
 /**
  * Run an async task and follow where it stands, as a discriminated union.
  *
  * The task runs on mount and again whenever it or `refreshKey` changes. A
  * re-run does not flip the state back to `loading`: what is on screen stays
  * until the new answer arrives, and a refresh that fails keeps it rather than
- * replacing it with an error. An answer that arrives after the component
- * unmounted, or after a newer run started, is ignored.
+ * replacing it with an error; `pending` says the answer is stale meanwhile. An
+ * answer that arrives after the component unmounted, or after a newer run
+ * started, is ignored, and the run's signal is aborted at that moment, so a
+ * task that hands it to `fetch` stops asking a question nobody waits for.
  *
  * The task is a dependency, so pass a stable function — declared at module
  * scope, or wrapped in `useCallback` over the values it reads.
- * @param task - The async function to run.
+ * @param task - The async function to run, handed a signal aborted once its
+ * answer is no longer wanted.
  * @param refreshKey - Changing it runs the task again; only its identity
  * matters. Defaults to `undefined`.
- * @returns Where the latest run stands.
+ * @returns Where the latest run stands, and whether it is still running.
  */
 export function useAsync<TData>(
-  task: () => Promise<TData>,
+  task: (signal: AbortSignal) => Promise<TData>,
   refreshKey?: unknown,
-): AsyncState<TData> {
-  const [state, setState] = useState<AsyncState<TData>>(ASYNC_LOADING);
+): AsyncResult<TData> {
+  const [answer, setAnswer] = useState<Answer<TData>>(UNANSWERED);
 
   useEffect(() => {
-    let cancelled = false;
-    task().then(
+    const controller = new AbortController();
+    task(controller.signal).then(
       (data) => {
-        if (!cancelled) setState(asyncSucceeded(data));
+        if (controller.signal.aborted) return;
+        setAnswer({ state: asyncSucceeded(data), task, refreshKey });
       },
       (error: unknown) => {
-        if (!cancelled) setState((previous) => asyncFailed(previous, error));
+        if (controller.signal.aborted) return;
+        setAnswer((previous) => ({
+          state: asyncFailed(previous.state, error),
+          task,
+          refreshKey,
+        }));
       },
     );
     return () => {
-      cancelled = true;
+      controller.abort();
     };
   }, [task, refreshKey]);
 
-  return state;
+  const pending =
+    answer.task !== task || !Object.is(answer.refreshKey, refreshKey);
+  return useMemo(() => ({ ...answer.state, pending }), [answer.state, pending]);
 }
+
+interface Answer<TData> {
+  state: AsyncState<TData>;
+  task: unknown;
+  refreshKey: unknown;
+}
+
+const UNANSWERED: Answer<never> = {
+  state: ASYNC_LOADING,
+  task: null,
+  refreshKey: undefined,
+};

package/src/ir/core/analysisSpectra.ts

@@ -14,14 +14,31 @@ import { xySortX } from 'ml-spectra-processing';
 
 import type { IrMeta, IrMode, IrOrigin } from './irSpectrum.ts';
 
-/** One spectrum as a reader produced it, before it is named and coloured. */
+/**
+ * One spectrum as a reader produced it, before it is named and coloured.
+ *
+ * The readers of this package produce infrared spectra, which carry absorbance
+ * and transmittance; a host reading a Raman file builds one carrying its
+ * intensity instead.
+ */
 export interface LoadedIrSpectrum {
-  /** The wavenumbers, ascending. */
+  /** The wavenumbers — or, for a Raman spectrum, the Raman shifts — ascending. */
   wavenumber: Float64Array;
-  /** Absorbance at each. */
-  absorbance: Float64Array;
-  /** Percent transmittance at each. */
-  transmittance: Float64Array;
+  /**
+   * Absorbance at each, for an infrared spectrum.
+   * @default undefined
+   */
+  absorbance?: Float64Array;
+  /**
+   * Percent transmittance at each, for an infrared spectrum.
+   * @default undefined
+   */
+  transmittance?: Float64Array;
+  /**
+   * Intensity at each, for a Raman spectrum.
+   * @default undefined
+   */
+  intensity?: Float64Array;
   /** What the file said about the acquisition, `null` when it said nothing. */
   meta: IrMeta | null;
   /** Where it came from. */
@@ -96,10 +113,9 @@ export function analysisSpectra(
   return spectra;
 }
 
-/** The three arrays of one spectrum, in ascending wavenumber. */
-type SortedTraces = Pick<
-  LoadedIrSpectrum,
-  'wavenumber' | 'absorbance' | 'transmittance'
+/** The three arrays of one infrared spectrum, in ascending wavenumber. */
+type SortedTraces = Required<
+  Pick<LoadedIrSpectrum, 'wavenumber' | 'absorbance' | 'transmittance'>
 >;
 
 /**

package/src/ir/core/bandLabelPlan.ts

@@ -18,6 +18,7 @@ import { labelStackBaselines } from '../../chart/core/labelStack.ts';
 import type { AssignedBand } from './assignBands.ts';
 import { bandLabel } from './assignBands.ts';
 import type { IrBand } from './irBand.ts';
+import { bandHeight, bandValue } from './irBand.ts';
 import { formatWavenumber } from './irFormat.ts';
 import { bandsPointDown } from './irMode.ts';
 import type { IrMode } from './irSpectrum.ts';
@@ -99,12 +100,15 @@ export function planBandLabels(options: BandLabelPlanOptions): BandLabelPlan[] {
     limit = 12,
   } = options;
 
-  const inside: AssignedBand[] = [];
+  const inside: NamedBand[] = [];
   for (const entry of assigned) {
+    // A band with no value on the axis being read has no tip to hang from.
+    const value = bandValue(entry.band, mode);
+    if (value === undefined) continue;
     const pixelX = chartPixel(xScale, entry.band.wavenumber);
     if (!Number.isFinite(pixelX)) continue;
     if (pixelX < plot.left || pixelX > plot.right) continue;
-    inside.push(entry);
+    inside.push({ entry, value });
   }
 
   const named =
@@ -112,18 +116,20 @@ export function planBandLabels(options: BandLabelPlanOptions): BandLabelPlan[] {
       ? inside
       : inside
           .toSorted(
-            (first, second) => second.band.absorbance - first.band.absorbance,
+            (first, second) =>
+              bandHeight(second.entry.band) - bandHeight(first.entry.band),
           )
           .slice(0, limit)
           .toSorted(
-            (first, second) => first.band.wavenumber - second.band.wavenumber,
+            (first, second) =>
+              first.entry.band.wavenumber - second.entry.band.wavenumber,
           );
 
   const centres = new Float64Array(named.length);
   for (let index = 0; index < named.length; index++) {
     centres[index] = chartPixel(
       xScale,
-      (named[index] as AssignedBand).band.wavenumber,
+      (named[index] as NamedBand).entry.band.wavenumber,
     );
   }
   const placed = layoutAnnotationBoxes(
@@ -136,12 +142,9 @@ export function planBandLabels(options: BandLabelPlanOptions): BandLabelPlan[] {
   const down = bandsPointDown(mode);
   const plans: BandLabelPlan[] = new Array<BandLabelPlan>(named.length);
   for (let index = 0; index < named.length; index++) {
-    const entry = named[index] as AssignedBand;
+    const { entry, value } = named[index] as NamedBand;
     const lines = labelLines(entry, showAssignments);
-    const tipY = chartPixel(
-      yScale,
-      mode === 'absorbance' ? entry.band.absorbance : entry.band.transmittance,
-    );
+    const tipY = chartPixel(yScale, value);
     plans[index] = {
       band: entry.band,
       tipX: centres[index] as number,
@@ -161,6 +164,14 @@ export function planBandLabels(options: BandLabelPlanOptions): BandLabelPlan[] {
   return plans;
 }
 
+/** A band inside the window, with its value on the axis being read. */
+interface NamedBand {
+  /** The band and whatever the table said about it. */
+  entry: AssignedBand;
+  /** Where its tip is, on the value axis. */
+  value: number;
+}
+
 /**
  * How wide a label is taken to be while it is being spaced out.
  *

package/src/ir/core/index.ts

@@ -10,7 +10,8 @@
  * 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.
+ * put in the beam. A Raman spectrum is the one other technique held, and what
+ * differs for it is in `IR_TECHNIQUE_RULES`.
  */
 
 export type { LoadedIrSpectrum } from './analysisSpectra.ts';
@@ -26,16 +27,22 @@ 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 { bandHeight, bandValue, sameIrBand } from './irBand.ts';
 export type {
   IrCommand,
   IrCommandHandlers,
   IrCommandId,
+  IrCommandTable,
   IrGesture,
   IrShortcut,
   RunIrCommand,
 } from './irCommands.ts';
-export { irCommandLabel, irCommands } from './irCommands.ts';
+export {
+  irCommandEntryLabel,
+  irCommandLabel,
+  irCommands,
+} from './irCommands.ts';
+export { irCommandOffered, irCommandsFor } from './irTechniqueCommands.ts';
 export {
   LABEL_HEADROOM,
   X_DOMAIN_PADDING,
@@ -46,9 +53,11 @@ export {
 export type { IrEditorHandle, ZoomToBandOptions } from './irEditorApi.ts';
 export {
   ABSORBANCE_DECIMALS,
+  INTENSITY_DIGITS,
   TRANSMITTANCE_DECIMALS,
   formatIrValue,
   formatWavenumber,
+  formatWavenumberRange,
   shortModeLabel,
 } from './irFormat.ts';
 export {
@@ -61,8 +70,8 @@ export {
   yAxisTitle,
   zoomGestures,
 } from './irMode.ts';
-export type { CreateIrStateOptions, IrAction } from './irReducer.ts';
-export { createIrState, irReducer } from './irReducer.ts';
+export type { IrAction } from './irReducer.ts';
+export { irReducer } from './irReducer.ts';
 export type {
   IrDomain,
   IrFormat,
@@ -75,6 +84,7 @@ export type {
 } from './irSpectrum.ts';
 export { traceOf } from './irSpectrum.ts';
 export type {
+  CreateIrStateOptions,
   IrData,
   IrSettings,
   IrState,
@@ -89,9 +99,19 @@ export {
   DEFAULT_SIDE_PANEL,
   DEFAULT_SIDE_PANELS,
   MAXIMUM_LABEL_LIMIT,
+  createIrState,
   isIrWindow,
   mergeIrSettings,
 } from './irState.ts';
+export type { IrTechnique, IrTechniqueRules } from './irTechnique.ts';
+export {
+  IR_TECHNIQUES,
+  IR_TECHNIQUE_RULES,
+  defaultIrMode,
+  irModeFor,
+  irModeTechnique,
+  offersIrMode,
+} from './irTechnique.ts';
 export type {
   LoadIrSpectraOptions,
   LoadIrSpectraResult,

package/src/ir/core/irBand.ts

@@ -1,21 +1,24 @@
 /**
  * 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.
+ * A band is the vibrational analogue of a mass spectrum's peak: the thing a
+ * chemist points at, names, and reads a functional group off. An infrared band
+ * carries both value axes for the same reason its 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. A Raman band carries its intensity.
  */
 
+import type { IrMode } from './irSpectrum.ts';
+
 /**
  * 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.
+ * `w` weak, `m` medium, `S` strong — decided 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 value. That is what a printed table means by
+ * them too. `ir-spectrum` decides it for an infrared band from its
+ * transmittance, and the same rule is applied to a Raman band's intensity.
  */
 export type IrBandStrength = 'w' | 'm' | 'S';
 
@@ -25,10 +28,21 @@ export interface IrBand {
   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;
+  /**
+   * Its absorbance, which an infrared band is picked as a maximum of.
+   * @default undefined
+   */
+  absorbance?: number;
+  /**
+   * Its percent transmittance, the same infrared band read the other way up.
+   * @default undefined
+   */
+  transmittance?: number;
+  /**
+   * Its intensity, which a Raman band is picked as a maximum of.
+   * @default undefined
+   */
+  intensity?: number;
   /** How strong it is, relative to the spectrum it came from. */
   strength: IrBandStrength;
 }
@@ -55,3 +69,27 @@ export function sameIrBand(
     current.wavenumber === next.wavenumber
   );
 }
+
+/**
+ * A band's value on the axis being read.
+ * @param band - The band.
+ * @param mode - Which value axis is being read.
+ * @returns The value, or `undefined` when its spectrum carries no such axis.
+ */
+export function bandValue(band: IrBand, mode: IrMode): number | undefined {
+  return band[mode];
+}
+
+/**
+ * How tall a band stands, which is what a cut to the strongest bands ranks by.
+ *
+ * The value it was picked as a maximum of: its absorbance for an infrared band,
+ * its intensity for a Raman one. Never its transmittance, in which a stronger
+ * band is a smaller number.
+ * @param band - The band.
+ * @returns The height, or negative infinity for a band carrying neither, so it
+ * ranks last.
+ */
+export function bandHeight(band: IrBand): number {
+  return band.absorbance ?? band.intensity ?? Number.NEGATIVE_INFINITY;
+}

package/src/ir/core/irCommands.ts

@@ -10,6 +10,9 @@
  * 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.
+ *
+ * This is the infrared table; `irTechniqueCommands.ts` derives the Raman one
+ * from it.
  */
 
 /** The key a command answers to. */
@@ -134,6 +137,9 @@ export const irCommands = {
 /** Identity of one of the commands the viewer offers. */
 export type IrCommandId = keyof typeof irCommands;
 
+/** The commands a viewer offers, in the order they are reached for. */
+export type IrCommandTable = Readonly<Partial<Record<IrCommandId, IrCommand>>>;
+
 /** What to do when each command is run, as the shell wires them. */
 export type IrCommandHandlers = Partial<
   Record<IrCommandId, (() => void) | undefined>
@@ -148,7 +154,15 @@ export type RunIrCommand = (id: IrCommandId) => void;
  * @returns The title, and the key in parentheses when it has one.
  */
 export function irCommandLabel(id: IrCommandId): string {
-  const entry = irCommands[id] as IrCommand;
+  return irCommandEntryLabel(irCommands[id]);
+}
+
+/**
+ * A command's title, with its key in parentheses when it has one.
+ * @param entry - The command, as a table words it.
+ * @returns The label.
+ */
+export function irCommandEntryLabel(entry: IrCommand): string {
   const key = entry.shortcut?.label?.[0] ?? entry.shortcut?.keys[0];
   return key === undefined ? entry.title : `${entry.title} (${key})`;
 }

package/src/ir/core/irDomain.ts

@@ -5,9 +5,10 @@
  * 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.
+ * The x window is in ascending wavenumbers even though the infrared 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';
@@ -57,9 +58,8 @@ export function fullDomain(
   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] };
+    // A percentage runs to 100; absorbance and intensity are open at the top.
+    return { x: [400, 4000], y: mode === 'transmittance' ? [0, 100] : [0, 1] };
   }
 
   const { xMinimum, xMaximum, yMinimum, yMaximum } = extent;
@@ -135,7 +135,9 @@ function traceExtent(
   for (const spectrum of spectra) {
     if (!spectrum.visible) continue;
     if (!includeExcluded && spectrum.excludeFromDomain) continue;
-    const { x, y } = traceOf(spectrum, mode);
+    const trace = traceOf(spectrum, mode);
+    if (trace === undefined) continue;
+    const { x, y } = trace;
     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