react-cheminfo 0.28.0 → 0.30.0

package/src/ir/ui/IrShell.tsx

@@ -0,0 +1,285 @@
+import type { Ref } from 'react';
+import { useCallback, useImperativeHandle, useMemo, useState } from 'react';
+import { SplitPane, useFullscreen } from 'react-science/ui';
+
+import { sanitizeFileName } from '../../download/core/sanitizeFileName.ts';
+import { ExportImageDialog } from '../../download/ui/ExportImageDialog.tsx';
+import { useDrawingBox } from '../../download/ui/useDrawingBox.ts';
+import { PanelRail } from '../../panel/ui/PanelRail.tsx';
+import type { IrBand } from '../core/irBand.ts';
+import type { IrCommandHandlers } from '../core/irCommands.ts';
+import { fullDomain } from '../core/irDomain.ts';
+import type { IrEditorHandle, ZoomToBandOptions } from '../core/irEditorApi.ts';
+import { otherIrMode, yAxisRules } from '../core/irMode.ts';
+import { irSidePanels } from '../core/irSidePanels.ts';
+import type { IrDomain, IrSpectrum } from '../core/irSpectrum.ts';
+import { DEFAULT_SIDE_PANEL } from '../core/irState.ts';
+
+import { IrAboutDialog } from './IrAboutDialog.tsx';
+import { IrCanvas } from './IrCanvas.tsx';
+import { IrCommandProvider } from './IrCommandProvider.tsx';
+import { IrDocumentationDialog } from './IrDocumentationDialog.tsx';
+import { IrHeader } from './IrHeader.tsx';
+import { IrSidePanel } from './IrSidePanel.tsx';
+import { IrToolbar } from './IrToolbar.tsx';
+import { useIrActions, useIrEditorState } from './irStateContext.ts';
+import { useIrShortcuts } from './useIrShortcuts.ts';
+
+export interface IrShellProps {
+  /**
+   * The handle to fill in, once there is a state for it to act on.
+   * @default undefined
+   */
+  handle?: Ref<IrEditorHandle>;
+}
+
+/**
+ * The viewer's screen: a header, the rails, and the split between the chart and
+ * the panels.
+ *
+ * Kept apart from `IrEditor` so that the handle, the commands and the highlight —
+ * all of which need the state — sit below the providers rather than beside them,
+ * and so the sealed component above is nothing but its props.
+ *
+ * The panels run to the bottom edge while the status bar stops at the splitter,
+ * which is what says the bar belongs to the chart and the panels are their own
+ * column.
+ * @param props - Component props.
+ * @returns The screen.
+ */
+export function IrShell(props: IrShellProps) {
+  const { handle } = props;
+
+  const { state, visibleSpectra, selectedSpectrum } = useIrEditorState();
+  const actions = useIrActions();
+  const { toggle: toggleFullScreen } = useFullscreen();
+  const { openPanelIds, tool, domain } = state.view;
+  const { mode, pickBands, showAssignments } = state.settings;
+
+  const [isAboutOpen, setIsAboutOpen] = useState(false);
+  const [isDocumentationOpen, setIsDocumentationOpen] = useState(false);
+  const [isExportImageOpen, setIsExportImageOpen] = useState(false);
+
+  // The chart is the picture, so the box it is drawn in is what the export
+  // dialog is pointed at: the viewer around it is full of SVG — every icon in
+  // every toolbar is one — and the first found there would be a magnifier.
+  const chart = useDrawingBox();
+  // The highlight is held here rather than in the reducer: what the pointer is
+  // resting on is not part of the document and changes on every move across the
+  // chart, so putting it through the reducer would run every panel's memo sixty
+  // times a second.
+  const [highlight, setHighlight] = useState<IrBand | null>(null);
+
+  /**
+   * ChartScale the value axis by a factor, about the baseline the mode hangs from.
+   * @param factor - Above one to zoom out.
+   */
+  const scaleValueAxis = useCallback(
+    (factor: number) => {
+      const shown = domain ?? fullDomain(visibleSpectra, mode);
+      // Asked of the mode rather than written out again here: the baseline a
+      // value axis is scaled about is `irMode`'s to know, and a second copy of
+      // it is a second thing to get wrong.
+      const { baseline = 0 } = yAxisRules(mode);
+      actions.setDomain({
+        x: shown.x,
+        y: [
+          baseline + (shown.y[0] - baseline) * factor,
+          baseline + (shown.y[1] - baseline) * factor,
+        ],
+      });
+    },
+    [actions, domain, visibleSpectra, mode],
+  );
+
+  const commands = useMemo<IrCommandHandlers>(
+    () => ({
+      about: () => setIsAboutOpen(true),
+      documentation: () => setIsDocumentationOpen(true),
+      fullScreen: toggleFullScreen,
+      readTool: () => actions.setTool('read'),
+      boxTool: () => actions.setTool(tool === 'box' ? 'read' : 'box'),
+      zoomIn: () => scaleValueAxis(1 / ZOOM_STEP),
+      zoomOut: () => scaleValueAxis(ZOOM_STEP),
+      resetZoom: () => actions.resetDomain(),
+      toggleMode: () => actions.setSettings({ mode: otherIrMode(mode) }),
+      togglePicking: () => actions.setSettings({ pickBands: !pickBands }),
+      toggleAssignments: () =>
+        actions.setSettings({ showAssignments: !showAssignments }),
+      exportImage: () => setIsExportImageOpen(true),
+      clear: () => actions.clear(),
+    }),
+    [
+      actions,
+      tool,
+      mode,
+      pickBands,
+      showAssignments,
+      scaleValueAxis,
+      toggleFullScreen,
+    ],
+  );
+
+  // The root is held as state rather than in a ref because the keys are bound to
+  // it from an effect: a ref filled in during the commit would leave the effect
+  // with nothing to listen on for the first render, and no reason ever to run
+  // again.
+  const [root, setRoot] = useState<HTMLElement | null>(null);
+  useIrShortcuts(root, commands);
+
+  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],
+  );
+
+  /**
+   * Open or close the side, as the splitter is dragged shut and back open.
+   * @param open - Whether the side is now open.
+   */
+  function setSideOpen(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 (openPanelIds.length === 0) actions.togglePanel(DEFAULT_SIDE_PANEL);
+  }
+
+  return (
+    <IrCommandProvider handlers={commands}>
+      {/* `tabIndex` so a click anywhere in the viewer makes this the target the
+          shortcuts are heard on: keys are delivered to whatever holds the caret,
+          and an SVG never does. */}
+      <div ref={setRoot} tabIndex={-1} style={rootStyle}>
+        <IrHeader />
+
+        <div style={mainStyle}>
+          {/* The rails are chrome of a fixed width, and a flex child shrinks by
+              default: in a narrow viewer the row would take the width it is
+              short of out of them, and half an icon is what that looks like. */}
+          <div style={railStyle}>
+            <IrToolbar />
+          </div>
+
+          <SplitPane
+            direction="horizontal"
+            controlledSide="end"
+            defaultSize="360px"
+            open={openPanelIds.length > 0}
+            onOpenChange={setSideOpen}
+          >
+            <IrCanvas
+              highlight={highlight}
+              onHighlight={setHighlight}
+              attachChart={chart.attach}
+            />
+
+            <IrSidePanel highlight={highlight} onHighlight={setHighlight} />
+          </SplitPane>
+
+          {/* Outside the split, so the icons stay put against the right edge
+              while the panel beside them is resized or closed. */}
+          <div style={railStyle}>
+            <PanelRail
+              panels={irSidePanels}
+              openIds={openPanelIds}
+              onToggle={actions.togglePanel}
+            />
+          </div>
+        </div>
+      </div>
+
+      <IrAboutDialog
+        isOpen={isAboutOpen}
+        onClose={() => setIsAboutOpen(false)}
+      />
+      <IrDocumentationDialog
+        isOpen={isDocumentationOpen}
+        onClose={() => setIsDocumentationOpen(false)}
+      />
+
+      {/* `element`, not `content`: the chart is drawn to the box it was given,
+          so the box is the picture — measuring the marks inside it would crop
+          the frame to wherever the trace happens to reach and leave the axes
+          hanging. */}
+      <ExportImageDialog
+        isOpen={isExportImageOpen}
+        getDrawing={chart.getDrawing}
+        frame="element"
+        filename={pictureName(visibleSpectra, selectedSpectrum)}
+        label="Infrared spectrum"
+        onClose={() => setIsExportImageOpen(false)}
+      />
+    </IrCommandProvider>
+  );
+}
+
+/**
+ * What one press of zoom in or out is worth.
+ *
+ * A fifth, which is about what one notch of a mouse wheel does — so the button
+ * and the wheel feel like the same gesture at two speeds rather than two
+ * different ones.
+ */
+const ZOOM_STEP = 1.2;
+
+/** How wide a window a host gets when it asks to frame a band without saying. */
+const DEFAULT_FRAME_WIDTH = 200;
+
+/**
+ * What a picture of the chart is called before anything is typed in the box.
+ *
+ * The spectrum being looked at, since a figure of the chart is a figure of that
+ * spectrum, and a chemist who has one run open should not have to work out
+ * which of their downloads `spectra.png` was. A chart holding several and
+ * pointing at none of them is named after the lot.
+ * @param spectra - What is drawn.
+ * @param selected - The one being looked at, `null` when none is.
+ * @returns The name, without its extension.
+ */
+function pictureName(
+  spectra: readonly IrSpectrum[],
+  selected: IrSpectrum | null,
+): string {
+  const named = selected ?? (spectra.length === 1 ? spectra[0] : undefined);
+  return named === undefined
+    ? 'spectra'
+    : sanitizeFileName(named.name, 'spectrum');
+}
+
+const rootStyle = {
+  display: 'flex',
+  flexDirection: 'column',
+  flex: '1 1 1px',
+  width: '100%',
+  height: '100%',
+  minHeight: 0,
+  outline: 'none',
+} as const;
+
+const mainStyle = {
+  display: 'flex',
+  flex: '1 1 1px',
+  minWidth: 0,
+  minHeight: 0,
+} as const;
+
+const railStyle = { flex: 'none' } as const;

package/src/ir/ui/IrSidePanel.tsx

@@ -0,0 +1,78 @@
+import { SidePanelStack } from '../../panel/ui/SidePanelStack.tsx';
+import type { IrBand } from '../core/irBand.ts';
+import type { IrSidePanelId } from '../core/irSidePanels.ts';
+import { irSidePanels } from '../core/irSidePanels.ts';
+
+import { BandsPanel } from './BandsPanel.tsx';
+import { MetadataPanel } from './MetadataPanel.tsx';
+import { SpectraPanel } from './SpectraPanel.tsx';
+import { useIrActions, useIrEditorState } from './irStateContext.ts';
+
+export interface IrSidePanelProps {
+  /**
+   * The band the pointer is resting on.
+   * @default null
+   */
+  highlight?: IrBand | null;
+  /**
+   * Told when a row is hovered.
+   * @default undefined
+   */
+  onHighlight?: (band: IrBand | null) => void;
+}
+
+/**
+ * The panels that are open, stacked down the right.
+ *
+ * Every open panel gets a share of the height rather than a turn, because the
+ * things they hold are read together: which spectrum is selected and what its
+ * bands are is one question asked of two panels. The header carries the close
+ * button and nothing else — a panel's own actions are a toolbar inside its body,
+ * so they travel with it.
+ * @param props - Component props.
+ * @returns The panel stack.
+ */
+export function IrSidePanel(props: IrSidePanelProps) {
+  const { highlight = null, onHighlight } = props;
+  const { state } = useIrEditorState();
+  const actions = useIrActions();
+  const { openPanelIds } = state.view;
+
+  return (
+    <SidePanelStack
+      panels={irSidePanels}
+      openPanelIds={openPanelIds}
+      onClose={actions.togglePanel}
+    >
+      {(panel) => (
+        <PanelBody
+          panelId={panel.id}
+          highlight={highlight}
+          onHighlight={onHighlight}
+        />
+      )}
+    </SidePanelStack>
+  );
+}
+
+interface PanelBodyProps {
+  /** Which panel to draw. */
+  panelId: IrSidePanelId;
+  /** The band the pointer is resting on. */
+  highlight: IrBand | null;
+  /** Told when a row is hovered. */
+  onHighlight?: (band: IrBand | null) => void;
+}
+
+/**
+ * Which panel a panel id is.
+ * @param props - Component props.
+ * @returns The panel's body.
+ */
+function PanelBody(props: PanelBodyProps) {
+  const { panelId, highlight, onHighlight } = props;
+
+  if (panelId === 'spectra') return <SpectraPanel />;
+  if (panelId === 'metadata') return <MetadataPanel />;
+  return <BandsPanel highlight={highlight} onHighlight={onHighlight} />;
+}

package/src/ir/ui/IrStateProvider.tsx

@@ -0,0 +1,32 @@
+import type { ReactNode } from 'react';
+
+import { actionsContext, stateContext } from './irStateContext.ts';
+import type { IrEditorApi } from './useIrEditor.ts';
+
+export interface IrStateProviderProps {
+  /** The viewer's state, as `useIrEditor` holds it. */
+  editor: IrEditorApi;
+  /** The viewer. */
+  children: ReactNode;
+}
+
+/**
+ * Put one viewer's state where its panels can reach it.
+ *
+ * The state and the actions go into separate contexts on purpose — see
+ * `irStateContext.ts` for why — and the actions are handed over as they are,
+ * since `useIrEditor` already keeps them stable for the life of the viewer.
+ * @param props - Component props.
+ * @returns The provider.
+ */
+export function IrStateProvider(props: IrStateProviderProps) {
+  const { editor, children } = props;
+
+  return (
+    <stateContext.Provider value={editor}>
+      <actionsContext.Provider value={editor.actions}>
+        {children}
+      </actionsContext.Provider>
+    </stateContext.Provider>
+  );
+}

package/src/ir/ui/IrStatusBar.tsx

@@ -0,0 +1,97 @@
+import { Icon } from '@blueprintjs/core';
+
+import {
+  countLabel,
+  statusBarStyle as barStyle,
+  statusItemStyle as itemStyle,
+  statusMutedStyle as mutedStyle,
+  statusSpacerStyle as spacerStyle,
+} from '../../panel/core/statusBar.ts';
+import { countAssigned } from '../core/assignBands.ts';
+import { formatWavenumber } from '../core/irFormat.ts';
+import { boxZoomOnly, yAxisTitle } from '../core/irMode.ts';
+
+import { useIrEditorState } from './irStateContext.ts';
+
+/**
+ * The one line under the chart: what is drawn, what was found, what went wrong.
+ *
+ * Everything in it is derived, so it is the cheapest place in the viewer to
+ * answer "did that work" — how many spectra are drawn of those open, how many
+ * bands the picking found and how many the table had something to say about, and
+ * the range the selected spectrum covers.
+ *
+ * The refusal is last and is the only red in the shell, so the eye that has just
+ * pressed something and seen nothing happen lands on the reason.
+ * @returns The status bar.
+ */
+export function IrStatusBar() {
+  const { state, visibleSpectra, selectedSpectrum, assigned } =
+    useIrEditorState();
+  const { spectra } = state.data;
+  const { error, tool } = state.view;
+  const { mode, pickBands } = state.settings;
+
+  const range =
+    selectedSpectrum === null || selectedSpectrum.wavenumber.length === 0
+      ? null
+      : `${formatWavenumber(selectedSpectrum.wavenumber.at(-1) as number)}–${formatWavenumber(selectedSpectrum.wavenumber[0] as number)} cm⁻¹`;
+
+  return (
+    <div style={barStyle}>
+      <span style={itemStyle}>
+        {spectra.length === 0
+          ? 'no spectrum open'
+          : `${countLabel(visibleSpectra.length, 'spectrum', 'spectra')} drawn of ${spectra.length}`}
+      </span>
+
+      <span style={itemStyle}>{yAxisTitle(mode)}</span>
+
+      {selectedSpectrum === null ? null : (
+        <span style={nameStyle} title={selectedSpectrum.name}>
+          {selectedSpectrum.name}
+        </span>
+      )}
+
+      {range === null ? null : <span style={mutedStyle}>{range}</span>}
+
+      {pickBands && assigned.length > 0 ? (
+        <span style={itemStyle}>
+          {countLabel(assigned.length, 'band', 'bands')},{' '}
+          {countAssigned(assigned)} assigned
+        </span>
+      ) : null}
+
+      {boxZoomOnly(mode) || tool === 'box' ? (
+        <span style={mutedStyle}>square zoom: drag a rectangle</span>
+      ) : null}
+
+      <span style={spacerStyle} />
+
+      {error === null ? null : (
+        <span style={errorStyle} title={error}>
+          <Icon icon="warning-sign" size={12} />
+          {error}
+        </span>
+      )}
+    </div>
+  );
+}
+
+const nameStyle = {
+  ...itemStyle,
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  maxWidth: '32%',
+  fontWeight: 600,
+} as const;
+
+/** The one red in the shell: a refusal, and nothing else, is written in it. */
+const errorStyle = {
+  ...itemStyle,
+  gap: 4,
+  color: '#C0392B',
+  overflow: 'hidden',
+  textOverflow: 'ellipsis',
+  maxWidth: '60%',
+} as const;

package/src/ir/ui/IrToolbar.tsx

@@ -0,0 +1,102 @@
+import { Toolbar } from 'react-science/ui';
+
+import { boxZoomOnly } from '../core/irMode.ts';
+
+import { useIrCommandProps } from './irCommandContext.tsx';
+import { useIrEditorState } from './irStateContext.ts';
+
+/**
+ * The tools, down the left of the chart.
+ *
+ * Only what is done to the spectra: what is asked of the viewer itself — the
+ * mark, help, full screen — is in the header. The two **tools** — read and
+ * square zoom — come first and show which of the two a drag is currently
+ * running, then the zoom commands that act at once, then what is being read: the
+ * value axis, the picking, the assignments. Closing every spectrum is last and
+ * alone, being the only one that throws something away.
+ *
+ * Reading percent transmittance, the pair is settled rather than chosen: every
+ * drag on that axis is a rectangle, so both buttons go dead with the square zoom
+ * lit. Showing `read` as available there would offer a gesture the chart does not
+ * make, and showing it as *active* would name the wrong one.
+ * @returns The toolbar.
+ */
+export function IrToolbar() {
+  const { state, selectedSpectrum } = useIrEditorState();
+  const command = useIrCommandProps();
+  const { spectra } = state.data;
+  const { domain, tool } = state.view;
+  const { mode, pickBands, showAssignments } = state.settings;
+
+  const isEmpty = spectra.length === 0;
+  const settled = boxZoomOnly(mode);
+
+  return (
+    // `collapse`, not the default `wrap`: a wrapping vertical toolbar measures
+    // itself and writes the result back as an inline width, so in a row short of
+    // space it settles at half an icon and stays there.
+    <Toolbar vertical overflow="collapse" aria-label="Infrared spectrum tools">
+      <Toolbar.Item
+        icon="trash"
+        intent="danger"
+        {...command('clear')}
+        disabled={isEmpty}
+      />
+      {/* The read tool drags along one axis, so it is drawn as that; the box
+          tool sweeps a rectangle, which is what a marquee icon means. */}
+      <Toolbar.Item
+        icon="arrows-horizontal"
+        active={!settled && tool === 'read'}
+        {...command('readTool')}
+        disabled={isEmpty || settled}
+      />
+      <Toolbar.Item
+        icon="select"
+        active={settled || tool === 'box'}
+        {...command('boxTool')}
+        disabled={isEmpty || settled}
+      />
+
+      <Toolbar.Item icon="zoom-in" {...command('zoomIn')} disabled={isEmpty} />
+      <Toolbar.Item
+        icon="zoom-out"
+        {...command('zoomOut')}
+        disabled={isEmpty}
+      />
+      <Toolbar.Item
+        icon="zoom-to-fit"
+        {...command('resetZoom')}
+        disabled={domain === null}
+      />
+
+      <Toolbar.Item
+        icon={mode === 'absorbance' ? 'arrow-up' : 'arrow-down'}
+        active={mode === 'absorbance'}
+        {...command('toggleMode')}
+        disabled={isEmpty}
+      />
+      <Toolbar.Item
+        icon="locate"
+        active={pickBands}
+        {...command('togglePicking')}
+        disabled={selectedSpectrum === null}
+      />
+      <Toolbar.Item
+        icon="label"
+        active={showAssignments}
+        {...command('toggleAssignments')}
+        disabled={!pickBands || selectedSpectrum === null}
+      />
+
+      {/* What the chart looks like right now is what a figure is of — the
+          window it was dragged to, the way up it is being read, the
+          assignments written under the bands — so the picture is taken here
+          rather than rebuilt from the spectra in a panel. */}
+      <Toolbar.Item
+        icon="media"
+        {...command('exportImage')}
+        disabled={isEmpty}
+      />
+    </Toolbar>
+  );
+}