react-cheminfo 0.28.0 → 0.29.0

package/src/ir/ui/BandsPanel.tsx

@@ -0,0 +1,271 @@
+import { Icon } from '@blueprintjs/core';
+import { useMemo } from 'react';
+import { Button, Toolbar } from 'react-science/ui';
+
+import {
+  panelBodyStyle,
+  panelCellStyle,
+  panelEmptyStyle,
+  panelHeaderCellStyle,
+  panelNumberCellStyle,
+  panelStyle,
+  panelTableStyle,
+  panelToolbarStyle,
+} from '../../panel/core/panelStyles.ts';
+import type { AssignedBand } from '../core/assignBands.ts';
+import type { IrBand } from '../core/irBand.ts';
+import { sameIrBand } from '../core/irBand.ts';
+import { formatIrValue, formatWavenumber } from '../core/irFormat.ts';
+
+import { useIrActions, useIrEditorState } from './irStateContext.ts';
+
+export interface BandsPanelProps {
+  /**
+   * The band the pointer is resting on, wherever it was hovered.
+   * @default null
+   */
+  highlight?: IrBand | null;
+  /**
+   * Told which band a row is hovered, so the chart can mark it.
+   * @default undefined
+   */
+  onHighlight?: (band: IrBand | null) => void;
+}
+
+/**
+ * Every band of the selected spectrum, and everything each one might be.
+ *
+ * This is the panel the viewer exists for. A trace can be looked at on its own;
+ * it is the table beside it that lets it be *read*, and the column that matters
+ * is the last one — **every** vibration whose range contains the band, not the
+ * best-fitting one. A band at 1715 cm⁻¹ genuinely is a ketone, an aldehyde and a
+ * carboxylic acid until something else decides, and a panel that named one would
+ * be asserting a structure the spectrum does not determine.
+ *
+ * Hovering a row marks the band on the chart and hovering the chart lights the
+ * row, which is the whole reason the highlight is threaded through the shell
+ * rather than held here: the two views are of one thing.
+ * @param props - Component props.
+ * @returns The panel.
+ */
+export function BandsPanel(props: BandsPanelProps) {
+  const { highlight = null, onHighlight } = props;
+  const { state, selectedSpectrum, assigned } = useIrEditorState();
+  const actions = useIrActions();
+  const { mode, pickBands, showAssignments, picking } = state.settings;
+
+  const rows = useMemo(() => assigned, [assigned]);
+
+  const tsv = useMemo(() => bandsToTsv(rows, mode), [rows, mode]);
+
+  return (
+    <div style={panelStyle}>
+      <div style={panelToolbarStyle}>
+        <Toolbar aria-label="Band actions">
+          <Toolbar.Item
+            icon="locate"
+            active={pickBands}
+            tooltip={pickBands ? 'Stop picking bands' : 'Pick the bands'}
+            aria-label="Pick the bands"
+            onClick={() => actions.setSettings({ pickBands: !pickBands })}
+          />
+          <Toolbar.Item
+            icon="label"
+            active={showAssignments}
+            tooltip="Name the assignments on the chart"
+            aria-label="Name the assignments on the chart"
+            disabled={!pickBands}
+            onClick={() =>
+              actions.setSettings({ showAssignments: !showAssignments })
+            }
+          />
+        </Toolbar>
+
+        {/* The threshold is the one picking setting worth reaching for while
+            reading: everything else about a band follows from the spectrum, and
+            this is what decides whether a shoulder is a band at all. */}
+        <label style={thresholdStyle}>
+          <span style={{ opacity: 0.7 }}>threshold</span>
+          <input
+            type="range"
+            min={0.005}
+            max={0.3}
+            step={0.005}
+            value={picking.minRelativeHeight ?? 0.02}
+            disabled={!pickBands}
+            aria-label="How tall a band must be to be picked"
+            onChange={(event) =>
+              actions.setSettings({
+                picking: { minRelativeHeight: event.target.valueAsNumber },
+              })
+            }
+          />
+        </label>
+
+        <span style={{ flex: 1 }} />
+
+        <Button
+          variant="minimal"
+          icon="clipboard"
+          disabled={rows.length === 0}
+          tooltipProps={{ content: 'Copy the table' }}
+          aria-label="Copy the table"
+          onClick={() => void navigator.clipboard?.writeText(tsv)}
+        />
+      </div>
+
+      <div style={panelBodyStyle}>
+        {selectedSpectrum === null ? (
+          <p style={panelEmptyStyle}>No spectrum is selected.</p>
+        ) : !pickBands ? (
+          <p style={panelEmptyStyle}>
+            The bands are not being picked. Press the locate button above to
+            find them.
+          </p>
+        ) : rows.length === 0 ? (
+          <p style={panelEmptyStyle}>
+            No band was found above the threshold. Lower it to pick the weaker
+            ones.
+          </p>
+        ) : (
+          <table style={panelTableStyle}>
+            <thead>
+              <tr>
+                <th style={panelHeaderCellStyle}>cm⁻¹</th>
+                <th style={panelHeaderCellStyle} />
+                <th style={{ ...panelHeaderCellStyle, textAlign: 'right' }}>
+                  {mode === 'absorbance' ? 'A' : '%T'}
+                </th>
+                <th style={panelHeaderCellStyle}>could be</th>
+              </tr>
+            </thead>
+            <tbody>
+              {rows.map((entry) => (
+                <BandRow
+                  key={`${entry.band.spectrumId} ${entry.band.wavenumber}`}
+                  entry={entry}
+                  mode={mode}
+                  lit={sameIrBand(entry.band, highlight)}
+                  onHighlight={onHighlight}
+                />
+              ))}
+            </tbody>
+          </table>
+        )}
+      </div>
+    </div>
+  );
+}
+
+interface BandRowProps {
+  /** The band and everything it might be. */
+  entry: AssignedBand;
+  /** Which value axis is being read. */
+  mode: 'absorbance' | 'transmittance';
+  /** Whether the pointer is on this band, here or on the chart. */
+  lit: boolean;
+  /** Told when the pointer arrives on this row, and when it leaves. */
+  onHighlight?: (band: IrBand | null) => void;
+}
+
+/**
+ * One band: where it is, how strong, and every vibration it could be.
+ *
+ * The candidates are written as one line rather than a list, so a strong band
+ * with four of them stays one row of the table and the wavenumbers keep reading
+ * down the column. The `title` carries them again with each one's note, which is
+ * where the reason to prefer one lives.
+ * @param props - Component props.
+ * @returns The row.
+ */
+function BandRow(props: BandRowProps) {
+  const { entry, mode, lit, onHighlight } = props;
+  const { band, candidates } = entry;
+
+  const value = mode === 'absorbance' ? band.absorbance : band.transmittance;
+  const detail = candidates
+    .map((candidate) =>
+      candidate.note === undefined
+        ? `${candidate.group} ${candidate.vibration}`
+        : `${candidate.group} ${candidate.vibration} — ${candidate.note}`,
+    )
+    .join('\n');
+
+  return (
+    <tr
+      style={lit ? litRowStyle : undefined}
+      onPointerEnter={() => onHighlight?.(band)}
+      onPointerLeave={() => onHighlight?.(null)}
+    >
+      <td style={panelNumberCellStyle}>{formatWavenumber(band.wavenumber)}</td>
+      <td style={panelCellStyle} title={STRENGTH_TITLES[band.strength]}>
+        {band.strength}
+      </td>
+      <td style={panelNumberCellStyle}>{formatIrValue(value, mode)}</td>
+      <td style={panelCellStyle} title={detail}>
+        {candidates.length === 0 ? (
+          <span style={{ opacity: 0.5 }}>—</span>
+        ) : (
+          <span style={{ whiteSpace: 'normal' }}>
+            {candidates[0]?.group} {candidates[0]?.vibration}
+            {candidates.length > 1 ? (
+              <span style={{ opacity: 0.6 }}>
+                {' '}
+                <Icon icon="more" size={10} /> {candidates.length - 1} more
+              </span>
+            ) : null}
+          </span>
+        )}
+      </td>
+    </tr>
+  );
+}
+
+/** What each strength letter means, for the column that shows only the letter. */
+const STRENGTH_TITLES = {
+  w: 'weak, relative to this spectrum',
+  m: 'medium, relative to this spectrum',
+  S: 'strong, relative to this spectrum',
+} as const;
+
+/**
+ * The table as text, for pasting into a notebook.
+ *
+ * Tab separated with every candidate on the 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.
+ * @param rows - The bands, as they are shown.
+ * @param mode - Which value axis is being read.
+ * @returns The table, one line per band, with a heading.
+ */
+function bandsToTsv(
+  rows: readonly AssignedBand[],
+  mode: 'absorbance' | 'transmittance',
+): string {
+  const heading = ['wavenumber', 'strength', mode, 'could be'].join('\t');
+  const lines = rows.map((entry) =>
+    [
+      formatWavenumber(entry.band.wavenumber),
+      entry.band.strength,
+      formatIrValue(
+        mode === 'absorbance'
+          ? entry.band.absorbance
+          : entry.band.transmittance,
+        mode,
+      ),
+      entry.candidates
+        .map((candidate) => `${candidate.group} ${candidate.vibration}`)
+        .join('; '),
+    ].join('\t'),
+  );
+  return [heading, ...lines].join('\n');
+}
+
+const litRowStyle = { background: '#fff3e0' } as const;
+
+const thresholdStyle = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  gap: 4,
+  fontSize: 11,
+} as const;

package/src/ir/ui/IrAboutDialog.tsx

@@ -0,0 +1,121 @@
+import { Dialog, DialogBody } from '@blueprintjs/core';
+
+import { IrLogo } from './IrLogo.tsx';
+
+export interface IrAboutDialogProps {
+  /** Whether the dialog is open. */
+  isOpen: boolean;
+  /** Close it. */
+  onClose: () => void;
+}
+
+/**
+ * What the viewer is, what it stands on, and who is owed for it.
+ *
+ * The credits are not decoration. Every band this viewer names is named out of a
+ * correlation table that generations of chemists compiled, every file it opens is
+ * read by somebody else's parser, and the examples it opens on are somebody
+ * else's measurements — so each is named here, with its licence where it has one.
+ * @param props - Component props.
+ * @returns The dialog.
+ */
+export function IrAboutDialog(props: IrAboutDialogProps) {
+  const { isOpen, onClose } = props;
+
+  return (
+    <Dialog
+      isOpen={isOpen}
+      onClose={onClose}
+      title="About the infrared viewer"
+      icon={<IrLogo size={20} />}
+      style={dialogStyle}
+    >
+      <DialogBody>
+        <div style={brandStyle}>
+          <IrLogo size={64} />
+          <div>
+            <p style={leadStyle}>react-cheminfo/ir</p>
+            <p style={paragraphStyle}>
+              Draws an infrared spectrum the way infrared is printed, reads it
+              as absorbance or as percent transmittance, picks its bands and
+              offers every functional group each band could be.
+            </p>
+          </div>
+        </div>
+
+        <h4 style={headingStyle}>Credits</h4>
+        <ul style={listStyle}>
+          <li>
+            <strong>ir-spectrum</strong> (cheminfo, MIT) reads the JCAMP-DX and
+            SPC files, derives the absorbance/transmittance pair, and picks the
+            bands. This package deliberately does none of that arithmetic
+            itself.
+          </li>
+          <li>
+            <strong>common-spectrum</strong>, <strong>jcampconverter</strong>{' '}
+            and <strong>spc-parser</strong> (cheminfo, MIT) are what it reads
+            through.
+          </li>
+          <li>
+            <strong>ml-spectra-processing</strong> (mljs, MIT) for the array
+            work.
+          </li>
+          <li>
+            The <strong>shared chart</strong> of this package for the drawing —
+            the same arithmetic every other spectrum viewer of the family is
+            drawn with.
+          </li>
+          <li>
+            <strong>react-science</strong> and <strong>BlueprintJS</strong>
+            (zakodium, Palantir) for the shell this viewer is shaped like.
+          </li>
+          <li>
+            The <strong>correlation table</strong> is the conventional teaching
+            set of group frequencies, as any introductory spectroscopy text
+            tabulates them. The ranges are deliberately the rounded, generous
+            ones: narrowing them to look precise would rule out assignments that
+            are genuinely possible.
+          </li>
+          <li>
+            The <strong>colours</strong> are Okabe and Ito&apos;s
+            colour-universal palette, so two traces stay distinguishable for a
+            reader with a colour vision deficiency.
+          </li>
+        </ul>
+
+        <h4 style={headingStyle}>Licence</h4>
+        <p style={paragraphStyle}>
+          MIT, in the{' '}
+          <a
+            href="https://github.com/cheminfo/glycans"
+            target="_blank"
+            rel="noopener noreferrer"
+          >
+            cheminfo/glycans
+          </a>{' '}
+          monorepo.
+        </p>
+      </DialogBody>
+    </Dialog>
+  );
+}
+
+const dialogStyle = { width: 'min(680px, 92vw)' } as const;
+
+const brandStyle = {
+  display: 'flex',
+  alignItems: 'flex-start',
+  gap: 16,
+} as const;
+
+const leadStyle = {
+  margin: '0 0 4px',
+  fontWeight: 600,
+  fontSize: 16,
+} as const;
+
+const paragraphStyle = { margin: '0 0 6px' } as const;
+
+const headingStyle = { margin: '14px 0 4px' } as const;
+
+const listStyle = { margin: 0, paddingLeft: 20 } as const;

package/src/ir/ui/IrCanvas.tsx

@@ -0,0 +1,91 @@
+import { useCallback } from 'react';
+
+import type { IrBand } from '../core/irBand.ts';
+import type { IrDomain } from '../core/irSpectrum.ts';
+
+import { IrChart } from './IrChart.tsx';
+import { IrStatusBar } from './IrStatusBar.tsx';
+import { useIrActions, useIrEditorState } from './irStateContext.ts';
+
+export interface IrCanvasProps {
+  /**
+   * The band the pointer is resting on, wherever it was hovered — the chart or
+   * the band table.
+   * @default null
+   */
+  highlight?: IrBand | null;
+  /**
+   * Told which band the pointer has come to rest on.
+   * @default undefined
+   */
+  onHighlight?: (band: IrBand | null) => void;
+  /**
+   * Put on the box the chart is drawn in, so a picture can be taken of it. The
+   * box rather than the chart itself, because the chart is laid out again on
+   * every resize.
+   * @default undefined
+   */
+  attachChart?: (element: HTMLDivElement | null) => void;
+}
+
+/**
+ * The chart, and the status bar under it.
+ *
+ * This is where the state meets the drawing: the chart holds nothing, so
+ * everything it draws is read out of the state here and every gesture it reports
+ * is written back. The window in particular goes **both** ways — the chart is
+ * told what to show and reports what it arrives at — which is what lets a toolbar
+ * button and a drag both move it.
+ *
+ * The status bar is inside the canvas rather than under the whole shell, so it
+ * stops at the splitter: what is open on the right belongs to the chart, and a
+ * bar running under the panels as well would read as belonging to the page.
+ * @param props - Component props.
+ * @returns The canvas.
+ */
+export function IrCanvas(props: IrCanvasProps) {
+  const { highlight = null, onHighlight, attachChart } = props;
+  const { state, visibleSpectra, assigned } = useIrEditorState();
+  const actions = useIrActions();
+  const { domain, tool, selectedId } = state.view;
+  const { mode, showAssignments, labelLimit } = state.settings;
+
+  const onDomainChange = useCallback(
+    (next: IrDomain) => {
+      actions.setDomain(next);
+    },
+    [actions],
+  );
+
+  return (
+    <div style={rootStyle}>
+      <div ref={attachChart} style={chartStyle}>
+        <IrChart
+          spectra={visibleSpectra}
+          mode={mode}
+          assigned={assigned}
+          showAssignments={showAssignments}
+          labelLimit={labelLimit}
+          highlight={highlight}
+          onHighlight={onHighlight}
+          domain={domain}
+          onDomainChange={onDomainChange}
+          drag={tool === 'box' ? 'box' : 'xAxis'}
+          emphasisedId={selectedId}
+        />
+      </div>
+      <IrStatusBar />
+    </div>
+  );
+}
+
+const rootStyle = {
+  display: 'flex',
+  flexDirection: 'column',
+  flex: '1 1 1px',
+  minWidth: 0,
+  minHeight: 0,
+} as const;
+
+/** The chart takes what the status bar does not. */
+const chartStyle = { flex: '1 1 1px', minHeight: 0 } as const;

package/src/ir/ui/IrChart.tsx

@@ -0,0 +1,215 @@
+import type { ReactElement } from 'react';
+import { useCallback, useId, useLayoutEffect, useMemo, useRef } from 'react';
+
+import { sameChartDomain } from '../../chart/core/chartDomain.ts';
+import { MARGIN, plotRect } from '../../chart/core/chartGeometry.ts';
+import { Axes } from '../../chart/ui/Axes.tsx';
+import { SelectionRect } from '../../chart/ui/SelectionRect.tsx';
+import { chartSurfaceStyle } from '../../chart/ui/chartSurface.ts';
+import { useChartSize } from '../../chart/ui/useChartSize.ts';
+import type { AssignedBand } from '../core/assignBands.ts';
+import type { IrBand } from '../core/irBand.ts';
+import { boxZoomOnly, yAxisTitle } from '../core/irMode.ts';
+import type { IrMode } from '../core/irSpectrum.ts';
+
+import { BandMarks } from './BandMarks.tsx';
+import { IrPointerTracker } from './IrPointerTracker.tsx';
+import { IrTraces } from './IrTraces.tsx';
+import type { IrChartProps } from './irChartProps.ts';
+import { useIrPointer } from './useIrPointer.ts';
+import { useIrZoom } from './useIrZoom.ts';
+
+/**
+ * The chart: every layer of an infrared spectrum, in one SVG.
+ *
+ * **The wavenumber axis runs right to left**, 4000 at the left edge down to 400
+ * at the right, which is how every infrared spectrum has been printed since the
+ * technique was dispersive and the instrument scanned that way. It is done by
+ * building the scale onto a reversed pixel range and nothing else: the data stays
+ * in ascending wavenumbers, every window stays low end first, and no other piece
+ * of arithmetic in either package has to know. That is the whole reason
+ * `createScale` takes its range rather than deriving it.
+ *
+ * The axes go under the data, so a grid line is never read as a band. Only the
+ * data band is clipped, so a zoomed trace stops at the plot edge while the
+ * wavenumbers pinned to the bands are allowed out over the margin — clip those
+ * and the strongest band in the window loses its label. The drag rectangle and
+ * the crosshair go over everything, because each answers a question being asked
+ * right now.
+ *
+ * Nothing is held here. The spectra, the bands, what is being looked at and the
+ * window are all props, and every gesture comes back out as a callback — so one
+ * component draws an editor's chart, a report page's single spectrum and a test.
+ * @param props - Component props.
+ * @returns The chart.
+ */
+export function IrChart(props: IrChartProps): ReactElement {
+  const {
+    spectra,
+    mode = 'transmittance',
+    assigned = NO_BANDS,
+    showAssignments = false,
+    labelLimit,
+    highlight = null,
+    onHighlight,
+    domain = null,
+    onDomainChange,
+    drag = 'xAxis',
+    emphasisedId = null,
+    width,
+    height,
+    children,
+  } = props;
+
+  const [containerRef, measured] = useChartSize<HTMLDivElement>();
+  const svgRef = useRef<SVGSVGElement | null>(null);
+
+  const plot = useMemo(
+    () =>
+      plotRect({
+        width: width ?? measured.width,
+        height: height ?? measured.height,
+      }),
+    [width, height, measured.width, measured.height],
+  );
+  // Read back off the plot rather than off the measurement, so a chart briefly
+  // laid out at nothing still draws its axes inside a box that holds them.
+  const frameWidth = plot.right + MARGIN.right;
+  const frameHeight = plot.bottom + MARGIN.bottom;
+
+  // The host's window goes *into* the zoom rather than over it, so a drag is
+  // always measured against what is on screen.
+  const zoom = useIrZoom({ spectra, mode, svgRef, plot, domain, drag });
+
+  // The scales the zoom measured its gestures against — the x one running right
+  // to left. Taken from the hook rather than built here, because two scales over
+  // one axis is two chances to disagree about which way it runs, and a chart that
+  // disagreed with its own gestures would zoom to the mirror image of whatever
+  // was dragged over.
+  const { domain: shown, xScale, yScale, selection, handlers } = zoom;
+
+  const reported = useRef(shown);
+  // Before the browser paints, so a host that stores the window and hands it
+  // back does so in the frame the gesture landed in rather than the one after.
+  useLayoutEffect(() => {
+    if (sameChartDomain(reported.current, shown)) return;
+    reported.current = shown;
+    onDomainChange?.(shown);
+  }, [shown, onDomainChange]);
+
+  const bands = useMemo(() => {
+    const found: IrBand[] = [];
+    for (const entry of assigned) found.push(entry.band);
+    return found;
+  }, [assigned]);
+
+  const onBand = useCallback(
+    (band: IrBand | null) => {
+      onHighlight?.(band);
+    },
+    [onHighlight],
+  );
+  const pointer = useIrPointer({
+    svgRef,
+    plot,
+    xScale,
+    yScale,
+    mode,
+    bands,
+    onBand,
+  });
+
+  // React's generated id carries the punctuation it keeps its own ids apart
+  // with, which a URL fragment is under no obligation to accept.
+  const clipId = `ir-plot-${useId().replaceAll(/\W/g, '')}`;
+
+  return (
+    <div ref={containerRef} style={containerStyle}>
+      <svg
+        ref={svgRef}
+        role="img"
+        aria-label={chartLabel(mode)}
+        width={frameWidth}
+        height={frameHeight}
+        viewBox={`0 0 ${frameWidth} ${frameHeight}`}
+        // The arrow gives way to the chart's own crosshair over the plot, and
+        // comes back over the margins, exactly as it does on a mass chart.
+        style={chartSurfaceStyle(pointer.position !== null)}
+        {...handlers}
+      >
+        <defs>
+          <clipPath id={clipId}>
+            <rect
+              x={plot.left}
+              y={plot.top}
+              width={plot.width}
+              height={plot.height}
+            />
+          </clipPath>
+        </defs>
+
+        <Axes
+          plot={plot}
+          xDomain={shown.x}
+          yDomain={shown.y}
+          xScale={xScale}
+          yScale={yScale}
+          xTitle="wavenumber (cm⁻¹)"
+          yTitle={yAxisTitle(mode)}
+        />
+
+        <g clipPath={`url(#${clipId})`}>
+          <IrTraces
+            spectra={spectra}
+            mode={mode}
+            plot={plot}
+            xDomain={shown.x}
+            xScale={xScale}
+            yScale={yScale}
+            emphasisedId={emphasisedId}
+          />
+          {children}
+        </g>
+
+        <BandMarks
+          assigned={assigned}
+          plot={plot}
+          xScale={xScale}
+          yScale={yScale}
+          mode={mode}
+          showAssignments={showAssignments}
+          highlight={highlight}
+          {...(labelLimit === undefined ? {} : { limit: labelLimit })}
+        />
+        <SelectionRect selection={selection} plot={plot} />
+        <IrPointerTracker
+          position={pointer.position}
+          readout={pointer.readout}
+          plot={plot}
+        />
+      </svg>
+    </div>
+  );
+}
+
+/**
+ * What the chart is, and what can be done to it, for whoever cannot see it.
+ *
+ * The gestures differ by mode, so the sentence does too — a label promising the
+ * wheel to a reader who cannot watch it fail to do anything is worse than no
+ * label at all.
+ * @param mode - Which value axis is being drawn.
+ * @returns The label.
+ */
+function chartLabel(mode: IrMode): string {
+  const axis = `Infrared spectrum read as ${yAxisTitle(mode)}, wavenumber running from high at the left to low at the right.`;
+  return boxZoomOnly(mode)
+    ? `${axis} Drag a rectangle over it to zoom to that rectangle, and double click to fit everything again.`
+    : `${axis} Drag across it to zoom the wavenumber axis, drag past the baseline to take the value axis with it, turn the wheel to scale the value axis, and double click to fit everything again.`;
+}
+
+/** What a chart nobody has picked any bands for marks. */
+const NO_BANDS: readonly AssignedBand[] = Object.freeze([]);
+
+/** The box the chart is measured against, and fills. */
+const containerStyle = { width: '100%', height: '100%' } as const;