react-cheminfo 0.11.0 → 0.13.0

package/src/molecule3d/ui/Molecule3DToolbar.tsx

@@ -0,0 +1,190 @@
+/**
+ * The toolbars floating over the molecule canvas: the view — reset, spin,
+ * surface, and the options, export and help popovers — in one vertical
+ * react-science `Toolbar`, and the measuring tools with their own clear button
+ * in a second one under it.
+ */
+
+import { Card } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+import { Toolbar } from 'react-science/ui';
+
+import type { MeasurementKind } from '../core/measurement.ts';
+import {
+  MEASUREMENT_ATOM_COUNTS,
+  MEASUREMENT_KINDS,
+  MEASUREMENT_LABELS,
+} from '../core/measurement.ts';
+import type { Molecule3DTools } from '../core/settings.ts';
+
+import { Molecule3DHelp } from './Molecule3DHelp.tsx';
+import {
+  ClearMeasurementsIcon,
+  MeasureIcon,
+  SurfaceIcon,
+} from './molecule3dIcons.tsx';
+
+/** Props of {@link Molecule3DToolbar}. */
+export interface Molecule3DToolbarProps {
+  tools: Molecule3DTools;
+  measureKind: MeasurementKind | null;
+  onMeasureKindChange: (kind: MeasurementKind | null) => void;
+  measurementCount: number;
+  onClearMeasurements: () => void;
+  spinning: boolean;
+  onSpinningChange: (spinning: boolean) => void;
+  showSurface: boolean;
+  onShowSurfaceChange: (showSurface: boolean) => void;
+  onResetView: () => void;
+  /** Content of the options popover. */
+  options: ReactElement;
+  /** Content of the export popover. */
+  exportPanel: ReactElement;
+}
+
+/**
+ * The two toolbars; either is left out when none of its tools is on.
+ * @param props - See {@link Molecule3DToolbarProps}.
+ * @returns The toolbars, stacked.
+ */
+export function Molecule3DToolbar(props: Molecule3DToolbarProps): ReactElement {
+  const {
+    tools,
+    measureKind,
+    onMeasureKindChange,
+    measurementCount,
+    onClearMeasurements,
+    spinning,
+    onSpinningChange,
+    showSurface,
+    onShowSurfaceChange,
+    onResetView,
+    options,
+    exportPanel,
+  } = props;
+  const hasView =
+    tools.spin ||
+    tools.surface ||
+    tools.reset ||
+    tools.options ||
+    tools.export ||
+    tools.help;
+
+  return (
+    <div style={COLUMN_STYLE}>
+      {hasView && (
+        <Card elevation={1} style={CARD_STYLE}>
+          <Toolbar vertical aria-label="View">
+            {tools.reset && (
+              <Toolbar.Item
+                icon="zoom-to-fit"
+                aria-label="Reset view"
+                tooltip="Reset view"
+                tooltipProps={TOOLTIP_PROPS}
+                onClick={onResetView}
+              />
+            )}
+            {tools.spin && (
+              <Toolbar.Item
+                icon="refresh"
+                active={spinning}
+                aria-label="Spin"
+                tooltip="Spin"
+                tooltipProps={TOOLTIP_PROPS}
+                onClick={() => {
+                  onSpinningChange(!spinning);
+                }}
+              />
+            )}
+            {tools.surface && (
+              <Toolbar.Item
+                icon={<SurfaceIcon />}
+                active={showSurface}
+                aria-label="Surface"
+                tooltip="Molecular surface"
+                tooltipProps={TOOLTIP_PROPS}
+                onClick={() => {
+                  onShowSurfaceChange(!showSurface);
+                }}
+              />
+            )}
+            {tools.options && (
+              <Toolbar.PopoverItem
+                placement="right-start"
+                content={options}
+                itemProps={{
+                  icon: 'cog',
+                  'aria-label': 'Display options',
+                  tooltip: 'Display options',
+                  tooltipProps: TOOLTIP_PROPS,
+                }}
+              />
+            )}
+            {tools.export && (
+              <Toolbar.PopoverItem
+                placement="right-start"
+                content={exportPanel}
+                itemProps={{
+                  icon: 'download',
+                  'aria-label': 'Export image',
+                  tooltip: 'Export image',
+                  tooltipProps: TOOLTIP_PROPS,
+                }}
+              />
+            )}
+            {tools.help && (
+              <Toolbar.PopoverItem
+                placement="right-start"
+                content={<Molecule3DHelp />}
+                itemProps={{
+                  icon: 'help',
+                  'aria-label': 'Mouse and keyboard',
+                  tooltip: 'Mouse and keyboard',
+                  tooltipProps: TOOLTIP_PROPS,
+                }}
+              />
+            )}
+          </Toolbar>
+        </Card>
+      )}
+      {tools.measure && (
+        <Card elevation={1} style={CARD_STYLE}>
+          <Toolbar vertical aria-label="Measure">
+            {MEASUREMENT_KINDS.map((kind) => (
+              <Toolbar.Item
+                key={kind}
+                icon={<MeasureIcon kind={kind} />}
+                active={measureKind === kind}
+                aria-label={MEASUREMENT_LABELS[kind]}
+                tooltip={`${MEASUREMENT_LABELS[kind]}: click ${MEASUREMENT_ATOM_COUNTS[kind]} atoms`}
+                tooltipProps={TOOLTIP_PROPS}
+                onClick={() => {
+                  onMeasureKindChange(measureKind === kind ? null : kind);
+                }}
+              />
+            ))}
+            <Toolbar.Item
+              icon={<ClearMeasurementsIcon />}
+              disabled={measurementCount === 0}
+              aria-label="Remove all measurements"
+              tooltip="Remove all measurements"
+              tooltipProps={TOOLTIP_PROPS}
+              onClick={onClearMeasurements}
+            />
+          </Toolbar>
+        </Card>
+      )}
+    </div>
+  );
+}
+
+const TOOLTIP_PROPS = { placement: 'right' } as const;
+
+const COLUMN_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+  pointerEvents: 'auto',
+};
+
+const CARD_STYLE: CSSProperties = { padding: 0 };

package/src/molecule3d/ui/MoleculeCanvas3D.tsx

@@ -0,0 +1,235 @@
+/**
+ * The molstar canvas of `MoleculeViewer3D`, with its toolbars over it.
+ *
+ * Reached through `React.lazy`, so a page that never shows a molecule never
+ * downloads molstar.
+ */
+
+import type { CSSProperties, ReactElement } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import type { Measurement, MeasurementKind } from '../core/measurement.ts';
+import type { Molecule3DFile } from '../core/settings.ts';
+import {
+  normalizeMolecule3DSettings,
+  resolveMolecule3DTools,
+} from '../core/settings.ts';
+
+import { Molecule3DExport } from './Molecule3DExport.tsx';
+import { Molecule3DOptions } from './Molecule3DOptions.tsx';
+import { Molecule3DToolbar } from './Molecule3DToolbar.tsx';
+import { DEFAULT_SPIN_SPEED } from './camera.ts';
+import { drawScene } from './drawScene.ts';
+import type { MoleculeViewer3DProps } from './moleculeViewer3DProps.ts';
+import { useControlledState } from './useControlledState.ts';
+import { useImageExport } from './useImageExport.ts';
+import { usePolarSurfaceArea } from './usePolarSurfaceArea.ts';
+import type { Molecule3DViewer } from './viewer.ts';
+import { createMolecule3DViewer } from './viewer.ts';
+
+/** Props of {@link MoleculeCanvas3D}. */
+export interface MoleculeCanvas3DProps extends Omit<
+  MoleculeViewer3DProps,
+  'fallback' | 'renderUnsupported'
+> {
+  /** Called with a drawing failure, and with `null` once a draw succeeds. */
+  onFailureChange: (message: string | null) => void;
+}
+
+/**
+ * Mount one molstar canvas and keep it showing what the props describe.
+ * @param props - See {@link MoleculeCanvas3DProps}.
+ * @returns The canvas with its toolbars.
+ */
+export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
+  const {
+    molfile,
+    tools: toolsProp,
+    settings: settingsProp,
+    defaultSettings,
+    onSettingsChange,
+    spinning: spinningProp,
+    defaultSpinning = false,
+    onSpinningChange,
+    spinSpeed = DEFAULT_SPIN_SPEED,
+    measurements: measurementsProp,
+    onMeasurementsChange,
+    fileName = 'molecule',
+    background,
+    minHeight = 320,
+    onFailureChange,
+  } = props;
+  const tools = resolveMolecule3DTools(toolsProp);
+  const [settings, setSettings] = useControlledState(
+    settingsProp,
+    () => normalizeMolecule3DSettings(defaultSettings),
+    onSettingsChange,
+  );
+  const [spinning, setSpinning] = useControlledState(
+    spinningProp,
+    defaultSpinning,
+    onSpinningChange,
+  );
+  const [measurements, setMeasurements] = useControlledState<
+    readonly Measurement[]
+  >(measurementsProp, NO_MEASUREMENTS, onMeasurementsChange);
+  const [measureKind, setMeasureKind] = useState<MeasurementKind | null>(null);
+  const polarSurfaceArea = usePolarSurfaceArea(
+    molfile,
+    settings.surfaceColoring === 'polarity',
+  );
+
+  // A callback ref: the element arriving is what creates the viewer, and every
+  // effect keyed on it runs again, in order, after the viewer exists.
+  const [container, setContainer] = useState<HTMLDivElement | null>(null);
+  const viewerRef = useRef<Molecule3DViewer | null>(null);
+  const framedRef = useRef<{
+    molfile: Molecule3DFile;
+    viewer: Molecule3DViewer;
+  } | null>(null);
+
+  // The viewer is created once, so what its callbacks read is kept fresh here.
+  const latest = useRef({
+    measurements,
+    setMeasurements,
+    onFailureChange,
+    background,
+  });
+  useEffect(() => {
+    latest.current = {
+      measurements,
+      setMeasurements,
+      onFailureChange,
+      background,
+    };
+  });
+
+  useEffect(() => {
+    if (container === null) return;
+    const viewer = createMolecule3DViewer(container, {
+      background: latest.current.background,
+      onMeasure: (measurement) => {
+        const current = latest.current;
+        current.setMeasurements([...current.measurements, measurement]);
+      },
+    });
+    viewerRef.current = viewer;
+    const observer = new ResizeObserver(() => {
+      viewer.handleResize();
+    });
+    observer.observe(container);
+    return () => {
+      observer.disconnect();
+      viewerRef.current = null;
+      viewer.dispose();
+    };
+  }, [container]);
+
+  // One animation frame of coalescing, so dragging a slider costs one rebuild.
+  useEffect(() => {
+    const viewer = viewerRef.current;
+    if (container === null || viewer === null) return;
+    let cancelled = false;
+    const frame = requestAnimationFrame(() => {
+      // Framed on a new molecule or a new viewer, never on a restyle: a slider
+      // that snapped the camera back would undo the reader's orientation.
+      const framed = framedRef.current;
+      const frameCamera =
+        molfile !== null &&
+        (framed?.molfile !== molfile || framed.viewer !== viewer);
+      framedRef.current = molfile === null ? null : { molfile, viewer };
+      void drawScene(viewer, molfile, settings, measurements, frameCamera)
+        .then(() => {
+          if (!cancelled) latest.current.onFailureChange(null);
+        })
+        .catch((error: unknown) => {
+          if (cancelled) return;
+          latest.current.onFailureChange(
+            error instanceof Error ? error.message : String(error),
+          );
+        });
+    });
+    return () => {
+      cancelled = true;
+      cancelAnimationFrame(frame);
+    };
+  }, [container, molfile, settings, measurements]);
+
+  useEffect(() => {
+    void viewerRef.current?.setSpin(spinning, spinSpeed);
+  }, [container, spinning, spinSpeed]);
+
+  useEffect(() => {
+    void viewerRef.current?.setMeasureKind(measureKind);
+  }, [container, measureKind]);
+
+  const resetView = useCallback(() => {
+    void viewerRef.current?.resetCamera();
+  }, []);
+
+  const { canvasSize, exportImage } = useImageExport(
+    container,
+    viewerRef,
+    fileName,
+  );
+
+  return (
+    <div style={{ ...STAGE_STYLE, minHeight }}>
+      <div ref={setContainer} style={CANVAS_STYLE} data-testid="molecule3d" />
+      {molfile !== null && (
+        <div style={OVERLAY_STYLE}>
+          <Molecule3DToolbar
+            tools={tools}
+            measureKind={measureKind}
+            onMeasureKindChange={setMeasureKind}
+            measurementCount={measurements.length}
+            onClearMeasurements={() => {
+              setMeasurements(NO_MEASUREMENTS);
+            }}
+            spinning={spinning}
+            onSpinningChange={setSpinning}
+            showSurface={settings.showSurface}
+            onShowSurfaceChange={(showSurface) => {
+              setSettings({ ...settings, showSurface });
+            }}
+            onResetView={resetView}
+            options={
+              <Molecule3DOptions
+                settings={settings}
+                onChange={setSettings}
+                polarSurfaceArea={polarSurfaceArea}
+              />
+            }
+            exportPanel={
+              <Molecule3DExport getSize={canvasSize} onExport={exportImage} />
+            }
+          />
+        </div>
+      )}
+    </div>
+  );
+}
+
+const NO_MEASUREMENTS: readonly Measurement[] = [];
+
+const STAGE_STYLE: CSSProperties = {
+  position: 'relative',
+  flex: '1 0 auto',
+  width: '100%',
+  borderRadius: 3,
+  overflow: 'hidden',
+};
+
+/** molstar inserts its canvas here, which therefore has a size of its own. */
+const CANVAS_STYLE: CSSProperties = { position: 'absolute', inset: 0 };
+
+const OVERLAY_STYLE: CSSProperties = {
+  position: 'absolute',
+  top: 8,
+  left: 8,
+  zIndex: 2,
+  display: 'flex',
+  alignItems: 'flex-start',
+  gap: 8,
+  pointerEvents: 'none',
+};

package/src/molecule3d/ui/MoleculeViewer3D.tsx

@@ -0,0 +1,84 @@
+/**
+ * A molecule in three dimensions, with a toolbar to measure it, turn it, wrap
+ * it in its surface and restyle it — and what to say when there cannot be one.
+ *
+ * The WebGL probe runs before molstar is touched, so a machine without WebGL
+ * gets an explanation instead of a blank rectangle, and the canvas sits behind
+ * `React.lazy`, so a page that never reaches it never downloads molstar.
+ *
+ * ```tsx
+ * import { MoleculeViewer3D } from 'react-cheminfo/molecule3d';
+ *
+ * <MoleculeViewer3D
+ *   molfile={{ format: 'mol', data: molfile }}
+ *   tools={{ measure: false }}
+ * />;
+ * ```
+ */
+
+import { Callout } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+import { Suspense, lazy, useState } from 'react';
+
+// Deep import on purpose: `capability.ts` imports nothing, while the canvas
+// pulls molstar in — which is exactly what this probe exists to avoid.
+import { probeViewerCapability } from '../../orbital/ui/capability.ts';
+
+import type { MoleculeViewer3DProps } from './moleculeViewer3DProps.ts';
+
+const MoleculeCanvas3D = lazy(async () => {
+  const module = await import('./MoleculeCanvas3D.tsx');
+  return { default: module.MoleculeCanvas3D };
+});
+
+/**
+ * The 3D molecule viewer.
+ * @param props - See {@link MoleculeViewer3DProps}.
+ * @returns The viewer, or an explanation of why this machine cannot show one.
+ */
+export function MoleculeViewer3D(props: MoleculeViewer3DProps): ReactElement {
+  const {
+    fallback = 'Loading the 3D viewer…',
+    renderUnsupported,
+    ...canvas
+  } = props;
+  const [capability] = useState(probeViewerCapability);
+  const [failure, setFailure] = useState<string | null>(null);
+
+  if (!capability.supported) {
+    return (
+      <Callout intent="warning" compact>
+        {renderUnsupported?.(capability) ?? capability.message}
+      </Callout>
+    );
+  }
+
+  return (
+    <div style={ROOT_STYLE}>
+      <Suspense fallback={<div style={NOTE_STYLE}>{fallback}</div>}>
+        <MoleculeCanvas3D {...canvas} onFailureChange={setFailure} />
+      </Suspense>
+      {failure !== null && (
+        <Callout intent="danger" compact title="The viewer could not draw this">
+          {failure}
+        </Callout>
+      )}
+    </div>
+  );
+}
+
+const ROOT_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+  flex: '1 0 auto',
+  minWidth: 0,
+};
+
+const NOTE_STYLE: CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  minHeight: 320,
+  fontSize: 13,
+};

package/src/molecule3d/ui/camera.ts

@@ -0,0 +1,76 @@
+/**
+ * The two camera moves the molecule viewer needs: frame whatever is on screen,
+ * and the slow spin that makes a still picture of a 3D molecule readable.
+ */
+
+import { Vec3 } from 'molstar/lib/mol-math/linear-algebra.js';
+import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
+
+/** Transition length used when the caller does not pick one, milliseconds. */
+export const DEFAULT_CAMERA_DURATION = 250;
+
+/** Turn rate used when the caller does not pick one, in molstar's spin unit. */
+export const DEFAULT_SPIN_SPEED = 1 / 3;
+
+/**
+ * Fraction of the bounding sphere kept as breathing room around the model.
+ *
+ * `camera.reset()` frames the scene with molstar's own margin, which suits a
+ * protein filling a wide viewport and leaves a small molecule a speck in the
+ * middle. Framing the visible bounding sphere directly is what makes a single
+ * ethanol legible.
+ */
+const FRAMING_MARGIN = 0.08;
+
+/** Axis the automatic spin turns about: screen up. */
+const SPIN_AXIS = Vec3.create(0, 1, 0);
+
+/** Smallest radius framed, in ångström, so a single atom is not a close-up. */
+const MIN_FRAMING_RADIUS = 0.5;
+
+/**
+ * Frame everything currently in the scene.
+ *
+ * The canvas refreshes its visible bounding sphere only when its render loop
+ * commits the scene, one frame after the state tree has resolved. Reading the
+ * sphere now would centre and clip on whatever was drawn before — atoms cut by
+ * the near plane — so the framing is computed when molstar resolves the reset,
+ * after that commit.
+ * @param plugin - The molstar context.
+ * @param durationMilliseconds - Transition length. Pass 0 for an instant jump.
+ */
+export function resetCamera(
+  plugin: PluginContext,
+  durationMilliseconds = DEFAULT_CAMERA_DURATION,
+): void {
+  plugin.canvas3d?.requestCameraReset({
+    durationMs: durationMilliseconds,
+    snapshot: (scene, camera) => {
+      const { center, radius } = scene.boundingSphereVisible;
+      return camera.getFocus(
+        center,
+        Math.max(radius * (1 + FRAMING_MARGIN), MIN_FRAMING_RADIUS),
+      );
+    },
+  });
+}
+
+/**
+ * Turn the automatic spin on or off.
+ * @param plugin - The molstar context.
+ * @param spinning - Whether the scene should keep turning.
+ * @param speed - Turn rate, in molstar's own spin unit.
+ */
+export function setSpin(
+  plugin: PluginContext,
+  spinning: boolean,
+  speed = DEFAULT_SPIN_SPEED,
+): void {
+  plugin.canvas3d?.setProps({
+    trackball: {
+      animate: spinning
+        ? { name: 'spin', params: { speed, axis: SPIN_AXIS } }
+        : { name: 'off', params: {} },
+    },
+  });
+}

package/src/molecule3d/ui/drawScene.ts

@@ -0,0 +1,43 @@
+import type { Measurement } from '../core/measurement.ts';
+import type { Molecule3DFile, Molecule3DSettings } from '../core/settings.ts';
+import { normalizeMolecule3DSettings } from '../core/settings.ts';
+
+import type { Molecule3DViewer } from './viewer.ts';
+
+/**
+ * Draw the scene. `showMolecule` empties it, so the surface and the
+ * measurements are added after the model, and the camera is framed last.
+ * @param viewer - The viewer holding the canvas.
+ * @param molfile - What to draw, or `null` to empty the scene.
+ * @param settings - How to draw it.
+ * @param measurements - What to draw over it.
+ * @param frameCamera - Whether to frame the camera once everything is there.
+ * @returns Nothing; resolves once the scene is complete.
+ */
+export async function drawScene(
+  viewer: Molecule3DViewer,
+  molfile: Molecule3DFile | null,
+  settings: Molecule3DSettings,
+  measurements: readonly Measurement[],
+  frameCamera: boolean,
+): Promise<void> {
+  if (molfile === null) {
+    await viewer.hideMolecule();
+    return;
+  }
+  const safe = normalizeMolecule3DSettings(settings);
+  await viewer.showMolecule(molfile, {
+    representation: safe.representation,
+    sizeFactor: safe.sizeFactor,
+  });
+  if (safe.showSurface) {
+    await viewer.showSurface({
+      alpha: safe.surfaceAlpha,
+      probeRadius: safe.probeRadius,
+      coloring: safe.surfaceColoring,
+      color: safe.surfaceColor,
+    });
+  }
+  await viewer.showMeasurements(measurements);
+  if (frameCamera) await viewer.resetCamera();
+}

package/src/molecule3d/ui/exportMoleculeImage.ts

@@ -0,0 +1,49 @@
+import { downloadBlob } from '../../download/core/downloadBlob.ts';
+import type { FigureFormat } from '../../download/core/downloadFigure.ts';
+import { FIGURE_PNG_TYPE } from '../../download/core/figurePng.ts';
+import { figurePixels } from '../../download/core/figureScale.ts';
+import { FIGURE_SVG_TYPE } from '../../download/core/figureSvg.ts';
+import { sanitizeFileName } from '../../download/core/sanitizeFileName.ts';
+import type { ImageSize } from '../core/exportImage.ts';
+import { dataUriBytes, rasterSvgMarkup } from '../core/exportImage.ts';
+
+import type { Molecule3DViewer } from './viewer.ts';
+
+/** What {@link exportMoleculeImage} writes. */
+export interface MoleculeImageRequest {
+  format: FigureFormat;
+  /** Multiple of the canvas on screen the picture is rendered at. */
+  scale: number;
+  /** Size of the canvas on screen, CSS pixels. */
+  size: ImageSize;
+  /** File name without its extension. */
+  fileName: string;
+}
+
+/**
+ * Render the scene and hand it to the browser as a file.
+ * @param viewer - The viewer holding the scene.
+ * @param request - See {@link MoleculeImageRequest}.
+ * @returns Nothing; resolves once the download has been started.
+ */
+export async function exportMoleculeImage(
+  viewer: Molecule3DViewer,
+  request: MoleculeImageRequest,
+): Promise<void> {
+  const { format, scale, size, fileName } = request;
+  const pixels = figurePixels(size, scale);
+  const dataUri = await viewer.captureImage(pixels);
+  if (dataUri === undefined) return;
+  const base = sanitizeFileName(fileName, 'molecule');
+  if (format === 'png') {
+    downloadBlob(
+      new Blob([dataUriBytes(dataUri)], { type: FIGURE_PNG_TYPE }),
+      `${base}.png`,
+    );
+    return;
+  }
+  downloadBlob(
+    new Blob([rasterSvgMarkup(dataUri, pixels)], { type: FIGURE_SVG_TYPE }),
+    `${base}.svg`,
+  );
+}

package/src/molecule3d/ui/index.ts

@@ -0,0 +1,11 @@
+/**
+ * What a site imports to show a molecule in 3D.
+ *
+ * **Nothing exported here may pull molstar in statically.** The canvas and the
+ * viewer class are deliberately absent: re-exporting either would defeat the
+ * `React.lazy` boundary inside `MoleculeViewer3D`. Type-only re-exports are
+ * erased and so are safe.
+ */
+
+export { MoleculeViewer3D } from './MoleculeViewer3D.tsx';
+export type { MoleculeViewer3DProps } from './moleculeViewer3DProps.ts';