react-cheminfo 0.28.0 → 0.30.0

package/src/ir/ui/IrCommandProvider.tsx

@@ -0,0 +1,32 @@
+import type { ReactNode } from 'react';
+import { useMemo } from 'react';
+
+import type { IrCommandHandlers } from '../core/irCommands.ts';
+
+import type { IrCommandContextValue } from './irCommandContext.tsx';
+import { commandContext } from './irCommandContext.tsx';
+
+export interface IrCommandProviderProps {
+  /** What each command does. */
+  handlers: IrCommandHandlers;
+  /** The viewer. */
+  children: ReactNode;
+}
+
+/**
+ * Put the command handlers where the toolbar and the panels can reach them.
+ * @param props - Component props.
+ * @returns The provider.
+ */
+export function IrCommandProvider(props: IrCommandProviderProps) {
+  const { handlers, children } = props;
+
+  const value = useMemo<IrCommandContextValue>(
+    () => ({ handlers, run: (id) => handlers[id]?.() }),
+    [handlers],
+  );
+
+  return (
+    <commandContext.Provider value={value}>{children}</commandContext.Provider>
+  );
+}

package/src/ir/ui/IrCommandTooltip.tsx

@@ -0,0 +1,36 @@
+import { TooltipHelpContent } from 'react-science/ui';
+
+import type { IrCommand, IrCommandId } from '../core/irCommands.ts';
+import { irCommands } from '../core/irCommands.ts';
+
+export interface IrCommandTooltipProps {
+  /** Which command the tooltip is about. */
+  id: IrCommandId;
+}
+
+/**
+ * One command's tooltip: its title, what it does, and every way to do it.
+ *
+ * `TooltipHelpContent` from react-science, which is what NMRium's tooltips are,
+ * so a page holding this viewer beside NMRium or the glycan editor explains
+ * itself the same way in all three.
+ * @param props - Component props.
+ * @returns The tooltip's content.
+ */
+export function IrCommandTooltip(props: IrCommandTooltipProps) {
+  const { id } = props;
+  const entry = irCommands[id] as IrCommand;
+  const shortcuts = entry.shortcut?.label ?? entry.shortcut?.keys;
+
+  return (
+    <TooltipHelpContent
+      title={entry.title}
+      description={entry.description}
+      shortcuts={shortcuts === undefined ? undefined : [...shortcuts]}
+      subTitles={entry.gestures?.map((gesture) => ({
+        title: gesture.title,
+        shortcuts: [...gesture.shortcuts],
+      }))}
+    />
+  );
+}

package/src/ir/ui/IrDocumentationDialog.tsx

@@ -0,0 +1,174 @@
+import { Dialog, DialogBody } from '@blueprintjs/core';
+
+import { TOKEN } from '../../tokens/core/familyTokens.ts';
+import type { IrCommand, IrCommandId } from '../core/irCommands.ts';
+import { irCommands } from '../core/irCommands.ts';
+import { IR_MODE_RULES } from '../core/irMode.ts';
+
+import { IrLogo } from './IrLogo.tsx';
+
+export interface IrDocumentationDialogProps {
+  /** Whether the dialog is open. */
+  isOpen: boolean;
+  /** Close it. */
+  onClose: () => void;
+}
+
+/**
+ * How to use the viewer, written in the viewer.
+ *
+ * In the component rather than on a site, so there is nowhere to leave for and
+ * nothing to keep in step: every key in the table below is read out of the same
+ * `irCommands` the toolbar and the key handler read, so a shortcut cannot be
+ * documented as one thing and bound as another.
+ * @param props - Component props.
+ * @returns The dialog.
+ */
+export function IrDocumentationDialog(props: IrDocumentationDialogProps) {
+  const { isOpen, onClose } = props;
+
+  return (
+    <Dialog
+      isOpen={isOpen}
+      onClose={onClose}
+      title="Using the infrared viewer"
+      icon={<IrLogo size={20} />}
+      style={dialogStyle}
+    >
+      <DialogBody>
+        <h4 style={headingStyle}>Opening a spectrum</h4>
+        <p style={paragraphStyle}>
+          JCAMP-DX (<code>.jdx</code>, <code>.dx</code>) and Thermo Galactic SPC
+          (<code>.spc</code>) are read. A file holding several blocks — a sample
+          beside its background, or an infrared spectrum beside a Raman one —
+          gives one spectrum per infrared block; the others are left to their
+          own viewers. Two columns of numbers are not read yet.
+        </p>
+
+        <h4 style={headingStyle}>The axis runs backwards</h4>
+        <p style={paragraphStyle}>
+          Wavenumber decreases to the right, from 4000 cm⁻¹ down to 400, which
+          is how infrared spectra have been printed since the instruments
+          scanned that way. Every window is still stated low end first.
+        </p>
+
+        <h4 style={headingStyle}>Absorbance or transmittance</h4>
+        <p style={paragraphStyle}>
+          The same measurement, read the other way up — the file carries both,
+          whichever it was written in. In{' '}
+          <strong>{IR_MODE_RULES.transmittance.title}</strong> the bands hang
+          down from a baseline near 100; in{' '}
+          <strong>{IR_MODE_RULES.absorbance.title}</strong> they stand up out of
+          zero. The labels and the marks follow, so the pair reads the same way
+          up in either.
+        </p>
+
+        <h4 style={headingStyle}>Reading the bands</h4>
+        <p style={paragraphStyle}>
+          The bands of the <em>selected</em> spectrum are picked, marked on the
+          chart, and listed in the bands panel with{' '}
+          <strong>every vibration whose range contains them</strong> — narrowest
+          claim first. That is deliberate: a band at 1715 cm⁻¹ really is a
+          ketone, an aldehyde and a carboxylic acid until something else decides
+          between them, and the note on each candidate is what tells them apart.
+          Hovering a row marks the band on the chart, and hovering the chart
+          lights the row.
+        </p>
+        <p style={paragraphStyle}>
+          A band is reported at the sampled point it peaked on, so on a 4 cm⁻¹
+          grid a carbonyl centred at 1710 reads 1708 or 1712. Do not quote one
+          as though it were measured to the wavenumber.
+        </p>
+
+        <h4 style={headingStyle}>Gestures and keys</h4>
+        <table style={tableStyle}>
+          <tbody>
+            {(Object.keys(irCommands) as IrCommandId[]).map((id) => (
+              <CommandRow key={id} id={id} />
+            ))}
+          </tbody>
+        </table>
+      </DialogBody>
+    </Dialog>
+  );
+}
+
+interface CommandRowProps {
+  /** Which command the row is about. */
+  id: IrCommandId;
+}
+
+/**
+ * One command: what it is called, its key, and what it does.
+ * @param props - Component props.
+ * @returns The row.
+ */
+function CommandRow(props: CommandRowProps) {
+  const { id } = props;
+  const entry = irCommands[id] as IrCommand;
+  const keys = entry.shortcut?.label ?? entry.shortcut?.keys;
+
+  return (
+    <tr>
+      <th style={commandCellStyle}>{entry.title}</th>
+      <td style={keyCellStyle}>
+        {keys === undefined
+          ? null
+          : keys.map((key) => (
+              <kbd key={key} style={keyStyle}>
+                {key}
+              </kbd>
+            ))}
+        {entry.gestures?.map((gesture) => (
+          <span key={gesture.title} style={gestureStyle}>
+            {gesture.shortcuts.join(', ')}
+          </span>
+        ))}
+      </td>
+      <td style={descriptionCellStyle}>{entry.description}</td>
+    </tr>
+  );
+}
+
+const dialogStyle = { width: 'min(760px, 92vw)' } as const;
+
+const headingStyle = { margin: '14px 0 4px' } as const;
+
+const paragraphStyle = { margin: '0 0 6px' } as const;
+
+const tableStyle = {
+  width: '100%',
+  borderCollapse: 'collapse',
+  fontSize: 13,
+} as const;
+
+const commandCellStyle = {
+  textAlign: 'left',
+  fontWeight: 600,
+  verticalAlign: 'top',
+  padding: '3px 8px 3px 0',
+  whiteSpace: 'nowrap',
+} as const;
+
+const keyCellStyle = {
+  verticalAlign: 'top',
+  padding: '3px 8px 3px 0',
+  whiteSpace: 'nowrap',
+} as const;
+
+const descriptionCellStyle = {
+  verticalAlign: 'top',
+  padding: '3px 0',
+} as const;
+
+const keyStyle = {
+  display: 'inline-block',
+  marginRight: 3,
+  padding: '0 4px',
+  border: `1px solid ${TOKEN.border}`,
+  borderRadius: 3,
+  background: TOKEN.surfaceSunken,
+  fontSize: 11,
+} as const;
+
+const gestureStyle = { opacity: 0.7, fontSize: 12 } as const;

package/src/ir/ui/IrEditor.tsx

@@ -0,0 +1,99 @@
+import type { Ref } from 'react';
+import { RootLayout } from 'react-science/ui';
+
+import type { IrEditorHandle } from '../core/irEditorApi.ts';
+import type { IrSidePanelId } from '../core/irSidePanels.ts';
+import type { IrMode, IrSpectrum } from '../core/irSpectrum.ts';
+
+import { IrShell } from './IrShell.tsx';
+import { IrStateProvider } from './IrStateProvider.tsx';
+import { useIrEditor } from './useIrEditor.ts';
+
+export interface IrEditorProps {
+  /**
+   * The spectra to open on. Read when the viewer opens and never again: what is
+   * on the chart belongs to the viewer from then on, so a host re-rendering with
+   * another array does not silently replace what somebody is looking at. The
+   * `ref` handle is how spectra arrive afterwards.
+   * @default []
+   */
+  data?: IrSpectrum[];
+  /**
+   * Called whenever the spectra open change — one loaded, one closed, the chart
+   * cleared — with the spectra now open.
+   *
+   * The document only. A zoom, a selection, a rename and a colour change what is
+   * being looked at rather than what is loaded, and a host told about those would
+   * be told on every drag of the mouse.
+   * @default undefined
+   */
+  onChange?: (spectra: IrSpectrum[]) => void;
+  /**
+   * Which value axis to open in.
+   * @default 'transmittance'
+   */
+  mode?: IrMode;
+  /**
+   * The side panels open to begin with.
+   * @default DEFAULT_SIDE_PANELS
+   */
+  defaultPanelIds?: IrSidePanelId[];
+  /**
+   * The handle a host drives the viewer through: take these spectra, frame this
+   * wavenumber, select that one.
+   * @default undefined
+   */
+  ref?: Ref<IrEditorHandle>;
+}
+
+/**
+ * An infrared spectrum viewer: a header across the top, the chart in the middle,
+ * the tools down the left, and the panels that interrogate it down the right.
+ *
+ * The same shape as the mass viewer, deliberately — a page may well hold both,
+ * and a chemist who has learned one should not have to learn the other. The chart
+ * is where a spectrum is read and the panels are where it is questioned, which is
+ * why the panels are switched on from the activity bar on the far right: a
+ * spectrum is mostly chart, and a panel is worth its width only while it is being
+ * used.
+ *
+ * It is sealed the way NMRium is sealed: the spectra go in as `data` and come back
+ * through `onChange`, and everything else a host wants — frame this band, take
+ * these spectra — is a gesture on the `ref` rather than a prop that has to change
+ * to be obeyed.
+ * @param props - Component props.
+ * @returns The viewer.
+ */
+export function IrEditor(props: IrEditorProps) {
+  const { data = NO_SPECTRA, onChange, mode, defaultPanelIds, ref } = props;
+
+  const editor = useIrEditor({
+    spectra: data,
+    settings: mode === undefined ? 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} />
+      </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[] = [];

package/src/ir/ui/IrHeader.tsx

@@ -0,0 +1,39 @@
+import { Header, Toolbar, useFullscreen } from 'react-science/ui';
+
+import { IrLogo } from './IrLogo.tsx';
+import { useIrCommandProps } from './irCommandContext.tsx';
+
+/**
+ * The bar across the top: the mark on the left, the viewer on the right.
+ *
+ * Nothing that is done to the spectra is here — that is the rail down the left
+ * and the panels down the right — only what is asked of the viewer itself. The
+ * mark is the About button, in the corner `react-mass` and `react-glycan` put
+ * theirs in, so a chemist switching between the three tools looks in one place
+ * for what they are in; and help then full screen close the bar, hard against
+ * the right edge, in all three.
+ * @returns The header.
+ */
+export function IrHeader() {
+  const command = useIrCommandProps();
+  const { isFullScreen } = useFullscreen();
+
+  return (
+    <Header>
+      <Toolbar aria-label="Infrared spectrum viewer">
+        <Toolbar.Item icon={<IrLogo size={16} />} {...command('about')} />
+      </Toolbar>
+      <Toolbar aria-label="Infrared spectrum viewer help">
+        <Toolbar.Item icon="help" {...command('documentation')} />
+        {/* Always the last thing in the bar, hard against the right edge: the
+            corner a window is made bigger from is the corner it is looked for
+            in, whatever else the header grows. */}
+        <Toolbar.Item
+          icon="fullscreen"
+          active={isFullScreen}
+          {...command('fullScreen')}
+        />
+      </Toolbar>
+    </Header>
+  );
+}

package/src/ir/ui/IrLogo.tsx

@@ -0,0 +1,49 @@
+export interface IrLogoProps {
+  /**
+   * How big to draw it, in pixels.
+   * @default 16
+   */
+  size?: number;
+}
+
+/**
+ * The viewer's mark: three bands hanging from a baseline.
+ *
+ * Drawn from the domain's own primitives rather than being a picture of a chart —
+ * a transmittance baseline near the top with a strong band, a medium one and a
+ * weak one dropping out of it, which is what an infrared spectrum looks like at a
+ * glance and what nothing else looks like. Three elements, because that is what
+ * survives 16 pixels.
+ * @param props - Component props.
+ * @returns The mark, as SVG.
+ */
+export function IrLogo(props: IrLogoProps) {
+  const { size = 16 } = props;
+
+  return (
+    <svg
+      width={size}
+      height={size}
+      viewBox="0 0 16 16"
+      role="img"
+      aria-label="Infrared viewer"
+    >
+      {/* The baseline, high up, where 100 % transmittance runs. */}
+      <path
+        d="M1 3H15"
+        fill="none"
+        stroke="#94a3b8"
+        strokeWidth={1}
+        strokeLinecap="round"
+      />
+      {/* Three bands dropping out of it, strong, medium, weak. */}
+      <path
+        d="M3 3V13M8 3V8.5M12.5 3V6"
+        fill="none"
+        stroke="#0072b2"
+        strokeWidth={2}
+        strokeLinecap="round"
+      />
+    </svg>
+  );
+}

package/src/ir/ui/IrPointerTracker.tsx

@@ -0,0 +1,102 @@
+import type { ReactElement } from 'react';
+
+import type { PlotRect } from '../../chart/core/chartGeometry.ts';
+import {
+  CHART_COLORS,
+  CHART_FONT,
+  LABEL_HALO,
+} from '../../chart/core/chartTheme.ts';
+import type { ChartPoint } from '../../chart/core/svgPoint.ts';
+import { readoutPlacement } from '../../chart/core/trackerReadout.ts';
+import {
+  formatIrValue,
+  formatWavenumber,
+  shortModeLabel,
+} from '../core/irFormat.ts';
+
+import type { IrReadout } from './useIrPointer.ts';
+
+export interface IrPointerTrackerProps {
+  /** Where the pointer is, `null` whenever it is off the plot. */
+  position: ChartPoint | null;
+  /** What the axes read under it, `null` whenever it is off the plot. */
+  readout: IrReadout | null;
+  /** Where the plot sits inside the SVG. */
+  plot: PlotRect;
+}
+
+/**
+ * The crosshair, and what the axes say under it.
+ *
+ * Drawn last of everything, so it is never occluded by what it is being used to
+ * read. Where the text goes is `readoutPlacement` in the shared chart, which
+ * flips it to the left of the pointer near the right edge and holds it inside the
+ * plot at the top — the same placement the mass viewer uses, because the awkward
+ * places are the same places in any chart.
+ *
+ * A third line names the band under the pointer when there is one, which is what
+ * makes the crosshair worth having on an infrared chart: the wavenumber alone is
+ * a number a reader then has to look up.
+ * @param props - Component props.
+ * @returns The crosshair and its readout, or nothing while the pointer is away.
+ */
+export function IrPointerTracker(
+  props: IrPointerTrackerProps,
+): ReactElement | null {
+  const { position, readout, plot } = props;
+  if (position === null || readout === null) return null;
+
+  const band = readout.band;
+  const lines = [
+    `${formatWavenumber(readout.wavenumber)} cm⁻¹`,
+    `${shortModeLabel(readout.mode)} ${formatIrValue(readout.value, readout.mode)}`,
+  ];
+  if (band !== null) {
+    lines.push(`band ${formatWavenumber(band.wavenumber)} (${band.strength})`);
+  }
+  const place = readoutPlacement(position, plot, lines.length);
+
+  return (
+    <g pointerEvents="none">
+      <line
+        x1={position.x}
+        y1={plot.top}
+        x2={position.x}
+        y2={plot.bottom}
+        style={crosshairStyle}
+      />
+      <line
+        x1={plot.left}
+        y1={position.y}
+        x2={plot.right}
+        y2={position.y}
+        style={crosshairStyle}
+      />
+      {lines.map((line, index) => (
+        <text
+          key={line}
+          x={place.x}
+          y={place.y + index * CHART_FONT.readout}
+          textAnchor={place.anchor}
+          style={readoutStyle}
+        >
+          {line}
+        </text>
+      ))}
+    </g>
+  );
+}
+
+const crosshairStyle = {
+  stroke: CHART_COLORS.tracker,
+  strokeDasharray: '3 3',
+} as const;
+
+const readoutStyle = {
+  fill: CHART_COLORS.trackerText,
+  fontSize: CHART_FONT.readout,
+  // Haloed like every other label written onto the plot, and it needs it more
+  // than any of them: the pointer is put wherever the question is, which is over
+  // the trace rather than beside it.
+  ...LABEL_HALO,
+} as const;