react-cheminfo 0.65.0 → 0.67.0

package/src/ir/ui/SpectrumRow.tsx

@@ -1,12 +1,20 @@
 import { Button } from 'react-science/ui';
 
 import { SpectrumColorSwatch } from '../../panel/ui/SpectrumColorSwatch.tsx';
-import { formatWavenumber } from '../core/irFormat.ts';
+import { formatWavenumberRange } from '../core/irFormat.ts';
 import type { IrSpectrum } from '../core/irSpectrum.ts';
+import type { IrTechnique } from '../core/irTechnique.ts';
+import { IR_TECHNIQUE_RULES } from '../core/irTechnique.ts';
 
 export interface SpectrumRowProps {
   /** The spectrum the row is about. */
   spectrum: IrSpectrum;
+  /**
+   * What it was measured with, which decides the order its range is written
+   * in: high to low for infrared, low to high for Raman.
+   * @default 'infrared'
+   */
+  technique?: IrTechnique;
   /** Whether the panels are about it. */
   selected: boolean;
   /** Point the panels at it. */
@@ -31,6 +39,7 @@ export interface SpectrumRowProps {
 export function SpectrumRow(props: SpectrumRowProps) {
   const {
     spectrum,
+    technique = 'infrared',
     selected,
     onSelect,
     onToggle,
@@ -40,10 +49,10 @@ export function SpectrumRow(props: SpectrumRowProps) {
     onRename,
   } = props;
 
-  const range =
-    spectrum.wavenumber.length === 0
-      ? ''
-      : `${formatWavenumber(spectrum.wavenumber.at(-1) as number)}–${formatWavenumber(spectrum.wavenumber[0] as number)} cm⁻¹`;
+  const range = formatWavenumberRange(
+    spectrum.wavenumber,
+    IR_TECHNIQUE_RULES[technique].reverseX,
+  );
 
   return (
     <div

package/src/ir/ui/VibrationalEditor.tsx

@@ -0,0 +1,113 @@
+import type { Ref } from 'react';
+import { RootLayout } from 'react-science/ui';
+
+import type { IrEditorHandle, IrPlotClick } from '../core/irEditorApi.ts';
+import type { IrPanelId } from '../core/irSidePanels.ts';
+import type { IrMode, IrSpectrum } from '../core/irSpectrum.ts';
+import type { IrTechnique } from '../core/irTechnique.ts';
+
+import { IrShell } from './IrShell.tsx';
+import { IrStateProvider } from './IrStateProvider.tsx';
+import type { IrHostPanel } from './irHostPanels.ts';
+import { useIrEditor } from './useIrEditor.ts';
+
+export interface VibrationalEditorProps {
+  /**
+   * What the spectra were measured with. Read when the viewer opens and fixed
+   * from then on: it decides the value axes, the direction and name of the
+   * wavenumber axis, and whether the correlation table is asked about a band.
+   */
+  technique: IrTechnique;
+  /**
+   * The spectra to open on. Read when the viewer opens and never again.
+   * @default []
+   */
+  data?: IrSpectrum[];
+  /**
+   * Called whenever the spectra open change, with the spectra now open.
+   * @default undefined
+   */
+  onChange?: (spectra: IrSpectrum[]) => void;
+  /**
+   * Which value axis to open in; one the technique does not offer opens its
+   * first instead.
+   * @default the technique's first
+   */
+  mode?: IrMode;
+  /**
+   * The side panels open to begin with, the viewer's own or the host's. An id
+   * no panel answers to is ignored.
+   * @default DEFAULT_SIDE_PANELS
+   */
+  defaultPanelIds?: readonly IrPanelId[];
+  /**
+   * Panels the host adds to the viewer's own: their icons come first in the
+   * activity bar, in the order given, and each behaves as a built-in panel does.
+   * @default []
+   */
+  panels?: readonly IrHostPanel[];
+  /**
+   * The plot was clicked at this wavenumber (a press that did not travel, i.e.
+   * not a zoom drag), with the spectrum selected at that moment.
+   * @default undefined
+   */
+  onPlotClick?: (click: IrPlotClick) => void;
+  /**
+   * The handle a host drives the viewer through.
+   * @default undefined
+   */
+  ref?: Ref<IrEditorHandle>;
+}
+
+/**
+ * The viewer `IrEditor` and `RamanEditor` both are: one shell, one set of
+ * panels and gestures, with what differs between the techniques read from
+ * `IR_TECHNIQUE_RULES` rather than written into either.
+ * @param props - Component props.
+ * @returns The viewer.
+ */
+export function VibrationalEditor(props: VibrationalEditorProps) {
+  const {
+    technique,
+    data = NO_SPECTRA,
+    onChange,
+    mode,
+    defaultPanelIds,
+    panels = NO_PANELS,
+    onPlotClick,
+    ref,
+  } = props;
+
+  const editor = useIrEditor({
+    spectra: data,
+    settings: { technique, ...(mode === undefined ? {} : { mode }) },
+    panelIds: defaultPanelIds,
+    onChange,
+  });
+
+  return (
+    <IrStateProvider editor={editor}>
+      {/* `react-science`'s own root: it holds the element the browser is asked
+          to show full screen, points Blueprint's portals at that element so
+          dialogs and tooltips are not left behind in `document.body`, and paints
+          the backdrop white. Above the shell rather than inside it, so the shell
+          can ask whether it is full screen and offer the way out. */}
+      <RootLayout style={rootLayoutStyle}>
+        <IrShell handle={ref} panels={panels} onPlotClick={onPlotClick} />
+      </RootLayout>
+    </IrStateProvider>
+  );
+}
+
+/**
+ * The viewer fills what it is given, and its own children scroll rather than
+ * push: `react-science` lays its root out as a column of full width and height,
+ * and a flex column with no `minHeight` grows past its parent instead.
+ */
+const rootLayoutStyle = { minHeight: 0 } as const;
+
+/** What a viewer opens on when it is handed nothing, kept stable for the memo. */
+const NO_SPECTRA: IrSpectrum[] = [];
+
+/** What a viewer the host adds no panel to offers, kept stable for the memo. */
+const NO_PANELS: readonly IrHostPanel[] = [];

package/src/ir/ui/bandsTsv.ts

@@ -0,0 +1,46 @@
+/**
+ * The band table as text, for pasting into a notebook.
+ */
+
+import type { AssignedBand } from '../core/assignBands.ts';
+import { bandValue } from '../core/irBand.ts';
+import { formatIrValue, formatWavenumber } from '../core/irFormat.ts';
+import type { IrMode } from '../core/irSpectrum.ts';
+
+/**
+ * The table as tab separated text.
+ *
+ * Every candidate is on its band's row, because the reason to copy a band table
+ * is to put it beside a structure and argue about it — and the argument is over
+ * the candidates rather than over the wavenumbers. A technique the correlation
+ * table does not cover has no such column.
+ * @param rows - The bands, as they are shown.
+ * @param mode - Which value axis is being read.
+ * @param assignments - Whether the table has a column for the candidates.
+ * @returns The table, one line per band, with a heading.
+ */
+export function bandsToTsv(
+  rows: readonly AssignedBand[],
+  mode: IrMode,
+  assignments: boolean,
+): string {
+  const heading = ['wavenumber', 'strength', mode];
+  if (assignments) heading.push('could be');
+  const lines = [heading.join('\t')];
+  for (const { band, candidates } of rows) {
+    const cells = [
+      formatWavenumber(band.wavenumber),
+      band.strength,
+      formatIrValue(bandValue(band, mode) ?? Number.NaN, mode),
+    ];
+    if (assignments) {
+      cells.push(
+        candidates
+          .map((candidate) => `${candidate.group} ${candidate.vibration}`)
+          .join('; '),
+      );
+    }
+    lines.push(cells.join('\t'));
+  }
+  return lines.join('\n');
+}

package/src/ir/ui/index.ts

@@ -47,6 +47,7 @@ export { createIrActions } from './irActions.ts';
 export type { IrChartProps } from './irChartProps.ts';
 export type { IrCommandContextValue } from './irCommandContext.tsx';
 export { useIrCommand, useIrCommandProps } from './irCommandContext.tsx';
+export type { IrHostPanel } from './irHostPanels.ts';
 export { useIrActions, useIrEditorState } from './irStateContext.ts';
 export type { IrEditorApi, UseIrEditorOptions } from './useIrEditor.ts';
 export { useIrEditor } from './useIrEditor.ts';

package/src/ir/ui/irActions.ts

@@ -9,7 +9,7 @@
 import type { Dispatch } from 'react';
 
 import type { IrAction } from '../core/irReducer.ts';
-import type { IrSidePanelId } from '../core/irSidePanels.ts';
+import type { IrPanelId } from '../core/irSidePanels.ts';
 import type { IrDomain, IrSpectrum } from '../core/irSpectrum.ts';
 import type { IrSettings, IrTool, PartialIrState } from '../core/irState.ts';
 
@@ -35,8 +35,8 @@ export interface IrEditorActions {
   resetDomain: () => void;
   /** Run this tool on the next drag. */
   setTool: (tool: IrTool) => void;
-  /** Open or close a side panel. */
-  togglePanel: (panelId: IrSidePanelId) => void;
+  /** Open or close a side panel, the viewer's own or one a host added. */
+  togglePanel: (panelId: IrPanelId) => void;
   /** Say why something was refused, or that nothing is wrong any more. */
   setError: (error: string | null) => void;
   /** Change how the spectra are drawn and read. */

package/src/ir/ui/irChartProps.ts

@@ -7,8 +7,9 @@
  * of half a dozen layers nobody needs to read in order to mount one.
  *
  * Everything arrives as a prop and nothing is reached for: the chart reads no
- * context and no store, so the same component serves an editor, a report page
- * that only ever draws one spectrum, and a test.
+ * store and no context but the language the page is written in, so the same
+ * component serves an editor, a report page that only ever draws one spectrum,
+ * and a test.
  */
 
 import type { ReactNode } from 'react';
@@ -17,17 +18,26 @@ import type { ZoomDragMode } from '../../chart/core/chartDomain.ts';
 import type { AssignedBand } from '../core/assignBands.ts';
 import type { IrBand } from '../core/irBand.ts';
 import type { IrDomain, IrMode, IrSpectrum } from '../core/irSpectrum.ts';
+import type { IrTechnique } from '../core/irTechnique.ts';
 
 export interface IrChartProps {
   /** The spectra to draw, each saying in itself whether it is drawn. */
   spectra: readonly IrSpectrum[];
   /**
-   * Which value axis to draw them in.
+   * What the spectra were measured with, which names the wavenumber axis and
+   * decides which way it runs: high to low for infrared, low to high for Raman.
+   * @default 'infrared'
+   */
+  technique?: IrTechnique;
+  /**
+   * Which value axis to draw them in. One the technique does not offer draws
+   * its first instead.
    *
    * A prop rather than state, so the switch lives with whoever owns the toolbar
    * that flips it — and so two charts of the same spectra can be shown side by
    * side, one in each, which is the clearest way to see what the pair means.
-   * @default 'transmittance'
+   * @default the technique's first: `'transmittance'` for infrared,
+   * `'intensity'` for Raman
    */
   mode?: IrMode;
   /**
@@ -84,6 +94,13 @@ export interface IrChartProps {
    * @default undefined
    */
   onDomainChange?: (domain: IrDomain) => void;
+  /**
+   * Told the wavenumber a click on the plot landed at: a press let go over the
+   * plot without travelling. The end of a drag is never one, nor is a press let
+   * go over the axis labels, which inverts to a value the chart is not drawing.
+   * @default undefined
+   */
+  onPlotClick?: (wavenumber: number) => void;
   /**
    * What a drag across the plot asks for: the wavenumber axis alone, or exactly
    * the rectangle it sweeps out. A viewer offering a square-zoom tool switches

package/src/ir/ui/irCommandContext.tsx

@@ -12,14 +12,18 @@ import type {
   IrCommandId,
   RunIrCommand,
 } from '../core/irCommands.ts';
-import { irCommandLabel } from '../core/irCommands.ts';
+import { irCommandEntryLabel, irCommands } from '../core/irCommands.ts';
+import type { IrTechnique } from '../core/irTechnique.ts';
 
 import { IrCommandTooltip } from './IrCommandTooltip.tsx';
+import { useIrText } from './useIrText.ts';
 
 /** What the provider holds. */
 export interface IrCommandContextValue {
   /** What each command does. */
   handlers: IrCommandHandlers;
+  /** What the spectra were measured with, which words the commands. */
+  technique: IrTechnique;
   /** Run one. */
   run: RunIrCommand;
 }
@@ -36,6 +40,14 @@ export function useIrCommand(): RunIrCommand {
   return value?.run ?? noRun;
 }
 
+/**
+ * What the spectra were measured with, from anywhere inside the viewer.
+ * @returns The technique; infrared outside a provider.
+ */
+export function useIrCommandTechnique(): IrTechnique {
+  return useContext(commandContext)?.technique ?? 'infrared';
+}
+
 /**
  * Everything a toolbar item needs to be one command, in one spread.
  *
@@ -46,10 +58,13 @@ export function useIrCommand(): RunIrCommand {
  */
 export function useIrCommandProps() {
   const run = useIrCommand();
+  const technique = useIrCommandTechnique();
+  const text = useIrText(technique);
   return function command(id: IrCommandId) {
+    const entry = text.command(id) ?? irCommands[id];
     return {
-      tooltip: <IrCommandTooltip id={id} />,
-      'aria-label': irCommandLabel(id),
+      tooltip: <IrCommandTooltip id={id} technique={technique} />,
+      'aria-label': irCommandEntryLabel(entry),
       onClick: () => run(id),
     };
   };

package/src/ir/ui/irHostPanels.ts

@@ -0,0 +1,76 @@
+/**
+ * The panels a host adds to the viewer's own, and the one list both make.
+ *
+ * A host panel is a panel like any other once it is in the list: the activity
+ * bar and the stack read the same list, so it toggles, folds and closes
+ * exactly as the spectra or the bands do. The host brings the body and nothing
+ * else — the header, its close button and the place in the column are the
+ * viewer's, which is what keeps every header reading the same.
+ */
+
+import type { IconName } from '@blueprintjs/core';
+import type { ReactNode } from 'react';
+
+import { irSidePanels } from '../core/irSidePanels.ts';
+
+/** A panel the host adds to the editor's own stack. */
+export interface IrHostPanel {
+  /**
+   * Its identity in the activity bar and in `defaultPanelIds`; never a
+   * built-in id. One that is, or that an earlier host panel already took, is
+   * left out: one icon cannot open two panels.
+   */
+  id: string;
+  /** What its header and its activity-bar item say. */
+  title: string;
+  /** Its glyph in the activity bar (a Blueprint IconName). */
+  icon: IconName;
+  /**
+   * Its body. It brings its own toolbar as first row: the header carries the
+   * close button only.
+   *
+   * It is laid out in a column filling the panel's share of the height, so a
+   * toolbar row in `panelToolbarStyle` followed by a body in `panelBodyStyle`,
+   * both from `react-cheminfo/core`, keeps the toolbar in place while a tall
+   * body scrolls under it. It is rendered inside the viewer, so a component in
+   * it reaches the viewer it stands in through `useIrEditorState` and
+   * `useIrActions` — to overlay a predicted spectrum, say.
+   */
+  content: ReactNode;
+}
+
+/** One panel of the side: one of the viewer's own, or one a host added. */
+export type IrStackPanel = (typeof irSidePanels)[number] | IrHostPanel;
+
+/**
+ * Every panel the side offers, in the order the activity bar stacks them: the
+ * host's first, in the order given, then the viewer's own.
+ * @param hostPanels - What the host adds.
+ * @returns The panels; the viewer's own list itself when the host adds none.
+ */
+export function irStackPanels(
+  hostPanels: readonly IrHostPanel[],
+): readonly IrStackPanel[] {
+  if (hostPanels.length === 0) return irSidePanels;
+  const taken = new Set<string>(BUILT_IN_IDS);
+  const panels: IrStackPanel[] = [];
+  for (const panel of hostPanels) {
+    if (taken.has(panel.id)) continue;
+    taken.add(panel.id);
+    panels.push(panel);
+  }
+  panels.push(...irSidePanels);
+  return panels;
+}
+
+/**
+ * Whether a panel of the side is one a host added, whose body it brings.
+ * @param panel - The panel.
+ * @returns True for a host's panel.
+ */
+export function isIrHostPanel(panel: IrStackPanel): panel is IrHostPanel {
+  return 'content' in panel;
+}
+
+/** The ids no host panel may take. */
+const BUILT_IN_IDS: readonly string[] = irSidePanels.map((panel) => panel.id);

package/src/ir/ui/useIrEditor.ts

@@ -17,10 +17,13 @@ import { useEffect, useMemo, useReducer, useRef } from 'react';
 
 import type { AssignedBand } from '../core/assignBands.ts';
 import { assignBands } from '../core/assignBands.ts';
-import type { CreateIrStateOptions } from '../core/irReducer.ts';
-import { createIrState, irReducer } from '../core/irReducer.ts';
+import type { BandAssignment } from '../core/bandAssignments.ts';
+import { BAND_ASSIGNMENTS } from '../core/bandAssignments.ts';
+import { irReducer } from '../core/irReducer.ts';
 import type { IrSpectrum } from '../core/irSpectrum.ts';
-import type { IrState } from '../core/irState.ts';
+import type { CreateIrStateOptions, IrState } from '../core/irState.ts';
+import { createIrState } from '../core/irState.ts';
+import { IR_TECHNIQUE_RULES } from '../core/irTechnique.ts';
 import { pickBands } from '../core/pickBands.ts';
 
 import type { IrEditorActions } from './irActions.ts';
@@ -46,7 +49,8 @@ export interface IrEditorApi {
   selectedSpectrum: IrSpectrum | null;
   /**
    * The bands of the selected spectrum, with everything each might be. Empty
-   * while nothing is selected or while picking is switched off.
+   * while nothing is selected or while picking is switched off, and every band
+   * without a candidate for a technique the correlation table does not cover.
    */
   assigned: AssignedBand[];
   /** Everything to do. */
@@ -67,7 +71,7 @@ export function useIrEditor(options: UseIrEditorOptions = {}): IrEditorApi {
   const { spectra } = state.data;
   const { selectedId } = state.view;
   const { pickBands: picking, picking: pickingOptions } = state.settings;
-  const { assignmentTolerance } = state.settings;
+  const { assignmentTolerance, technique } = state.settings;
 
   const visibleSpectra = useMemo(() => {
     const visible: IrSpectrum[] = [];
@@ -95,10 +99,15 @@ export function useIrEditor(options: UseIrEditorOptions = {}): IrEditorApi {
 
   // Assigning is a walk of thirty ranges per band, which is nothing beside the
   // picking — so it is a memo of its own, and moving the tolerance does not
-  // re-pick.
+  // re-pick. A technique the table does not cover is matched against no table.
+  const { assignments } = IR_TECHNIQUE_RULES[technique];
   const assigned = useMemo(
-    () => assignBands(bands, { tolerance: assignmentTolerance }),
-    [bands, assignmentTolerance],
+    () =>
+      assignBands(bands, {
+        tolerance: assignmentTolerance,
+        assignments: assignments ? BAND_ASSIGNMENTS : NO_ASSIGNMENTS,
+      }),
+    [bands, assignmentTolerance, assignments],
   );
 
   // What was reported last, so a host passing a fresh callback on every render
@@ -118,6 +127,9 @@ export function useIrEditor(options: UseIrEditorOptions = {}): IrEditorApi {
   );
 }
 
+/** The table a technique the correlation table does not cover is matched against. */
+const NO_ASSIGNMENTS: readonly BandAssignment[] = [];
+
 /**
  * Whether two lists hold the same spectra, by identity and in order.
  * @param current - What was reported last.

package/src/ir/ui/useIrHandle.ts

@@ -0,0 +1,51 @@
+/**
+ * The handle a host drives the viewer through, filled in from its state.
+ *
+ * A hook of its own beside the shell, because every gesture on the handle reads
+ * the state the shell already reads — and the shell is long enough without it.
+ */
+
+import type { Ref } from 'react';
+import { useImperativeHandle } from 'react';
+
+import { fullDomain } from '../core/irDomain.ts';
+import type { IrEditorHandle, ZoomToBandOptions } from '../core/irEditorApi.ts';
+import type { IrDomain } from '../core/irSpectrum.ts';
+
+import { useIrActions, useIrEditorState } from './irStateContext.ts';
+
+/**
+ * Fill in a host's handle on the viewer this is called inside.
+ * @param handle - The handle to fill in, if the host asked for one.
+ */
+export function useIrHandle(handle: Ref<IrEditorHandle> | undefined): void {
+  const { state, visibleSpectra } = useIrEditorState();
+  const actions = useIrActions();
+  const { domain } = state.view;
+  const { mode } = state.settings;
+
+  useImperativeHandle(
+    handle,
+    (): IrEditorHandle => ({
+      getSpectra: () => state.data.spectra,
+      setSpectra: (spectra) => actions.setSpectra(spectra),
+      addSpectra: (spectra) => actions.addSpectra(spectra),
+      clear: () => actions.clear(),
+      setDomain: (next) => actions.setDomain(next),
+      resetDomain: () => actions.resetDomain(),
+      zoomToWavenumber: (wavenumber, options: ZoomToBandOptions = {}) => {
+        const { width = DEFAULT_FRAME_WIDTH } = options;
+        const shown: IrDomain = domain ?? fullDomain(visibleSpectra, mode);
+        actions.setDomain({
+          x: [wavenumber - width / 2, wavenumber + width / 2],
+          y: shown.y,
+        });
+      },
+      selectSpectrum: (id) => actions.selectSpectrum(id),
+    }),
+    [state.data.spectra, actions, domain, visibleSpectra, mode],
+  );
+}
+
+/** How wide a window a host gets when it asks to frame a band without saying. */
+const DEFAULT_FRAME_WIDTH = 200;

package/src/ir/ui/useIrSide.ts

@@ -0,0 +1,60 @@
+/**
+ * The side of the viewer: the panels it offers, whether any of them is open,
+ * and what dragging the splitter shut and back open does to them.
+ *
+ * A hook of its own beside the shell, because the shell lays the side out and
+ * this decides what is on it.
+ */
+
+import { useMemo } from 'react';
+
+import { DEFAULT_SIDE_PANEL } from '../core/irState.ts';
+
+import type { IrHostPanel, IrStackPanel } from './irHostPanels.ts';
+import { irStackPanels } from './irHostPanels.ts';
+import { useIrActions, useIrEditorState } from './irStateContext.ts';
+
+/** The side, as the shell lays it out. */
+export interface IrSide {
+  /** Every panel on offer, in the order their icons are stacked. */
+  panels: readonly IrStackPanel[];
+  /** Whether a panel on offer is open, which is whether the side is. */
+  isOpen: boolean;
+  /**
+   * Open or close the side, as the splitter is dragged shut and back open.
+   * @param open - Whether the side is now open.
+   */
+  setOpen: (open: boolean) => void;
+}
+
+/**
+ * The side of the viewer this is called inside.
+ * @param hostPanels - The panels the host adds to the viewer's own.
+ * @returns The panels on offer, whether the side is open, and how to open it.
+ */
+export function useIrSide(hostPanels: readonly IrHostPanel[]): IrSide {
+  const { state } = useIrEditorState();
+  const actions = useIrActions();
+  const { openPanelIds } = state.view;
+
+  const panels = useMemo(() => irStackPanels(hostPanels), [hostPanels]);
+  // Read off the panels on offer rather than off the ids: an id no panel
+  // answers to opens nothing, and a side open on it alone is an empty column.
+  const isOpen = panels.some((panel) => openPanelIds.includes(panel.id));
+
+  /**
+   * Open or close the side.
+   * @param open - Whether the side is now open.
+   */
+  function setOpen(open: boolean): void {
+    if (!open) {
+      for (const panelId of openPanelIds) actions.togglePanel(panelId);
+      return;
+    }
+    // Dragging the splitter back open must land on something, or it opens on an
+    // empty column and reads as broken.
+    if (!isOpen) actions.togglePanel(DEFAULT_SIDE_PANEL);
+  }
+
+  return { panels, isOpen, setOpen };
+}