react-cheminfo 0.18.0 → 0.19.0

package/src/molecule3d/ui/useMoleculeScene.ts

@@ -0,0 +1,141 @@
+/**
+ * Keeping one molstar canvas showing what the props describe: the model, its
+ * surface, its measurements, and where the camera stands over them.
+ *
+ * The draw is coalesced into one animation frame, so dragging a slider costs
+ * one rebuild rather than one per pixel, and the camera is framed only when the
+ * molecule is new — a restyle that snapped the view back would undo the
+ * reader's orientation.
+ */
+
+import type { RefObject } from 'react';
+import { useCallback, useEffect, useRef } from 'react';
+
+import type { Molecule3DCamera } from '../core/camera.ts';
+import type { Measurement } from '../core/measurement.ts';
+import type { Molecule3DFile, Molecule3DSettings } from '../core/settings.ts';
+
+import { drawScene } from './drawScene.ts';
+import type { MoleculeViewer3DProps } from './moleculeViewer3DProps.ts';
+import {
+  DEFAULT_CAMERA_SETTLE_DELAY,
+  useSharedCamera,
+} from './useSharedCamera.ts';
+import type { Molecule3DViewer } from './viewer.ts';
+
+/** What {@link useMoleculeScene} is given. */
+export interface MoleculeSceneOptions {
+  /** The element molstar draws in, or `null` before it exists. */
+  container: HTMLElement | null;
+  /** The viewer mounted in it. */
+  viewerRef: RefObject<Molecule3DViewer | null>;
+  /** What to draw, or `null` to empty the scene. */
+  molfile: Molecule3DFile | null;
+  /** How the camera meets a molecule it has not seen before. */
+  frameNewMolecule: 'front' | 'keep';
+  /** How the model is drawn. */
+  settings: Molecule3DSettings;
+  /** What is drawn over it. */
+  measurements: readonly Measurement[];
+  /** Whether the model is turning on its own. */
+  spinning: boolean;
+  /** Called with a drawing failure, and with `null` once a draw succeeds. */
+  onFailureChange: (message: string | null) => void;
+  /** Where the camera stands when the first molecule is framed, and who to tell. */
+  camera: Pick<
+    MoleculeViewer3DProps,
+    'cameraSettleDelay' | 'initialCamera' | 'onCameraChange'
+  >;
+}
+
+/** What {@link useMoleculeScene} answers. */
+export interface MoleculeScene {
+  /** Frame everything on screen again, as the toolbar's reset button does. */
+  resetView: () => void;
+}
+
+/**
+ * Draw the scene the options describe, and keep it drawn.
+ * @param options - See {@link MoleculeSceneOptions}.
+ * @returns See {@link MoleculeScene}.
+ */
+export function useMoleculeScene(options: MoleculeSceneOptions): MoleculeScene {
+  const {
+    container,
+    viewerRef,
+    molfile,
+    frameNewMolecule,
+    settings,
+    measurements,
+    spinning,
+    onFailureChange,
+    camera: cameraProps,
+  } = options;
+  const framedRef = useRef<{
+    molfile: Molecule3DFile;
+    viewer: Molecule3DViewer;
+  } | null>(null);
+  const reportFailure = useRef(onFailureChange);
+  useEffect(() => {
+    reportFailure.current = onFailureChange;
+  });
+
+  const camera = useSharedCamera({
+    container,
+    viewerRef,
+    spinning,
+    initialCamera: cameraProps.initialCamera ?? null,
+    onCameraChange: cameraProps.onCameraChange,
+    settleDelay: cameraProps.cameraSettleDelay ?? DEFAULT_CAMERA_SETTLE_DELAY,
+  });
+
+  useEffect(() => {
+    const viewer = viewerRef.current;
+    if (container === null || viewer === null) return;
+    let cancelled = false;
+    const frame = requestAnimationFrame(() => {
+      const framed = framedRef.current;
+      const isNew =
+        molfile !== null &&
+        (framed?.molfile !== molfile || framed.viewer !== viewer);
+      framedRef.current = molfile === null ? null : { molfile, viewer };
+      // The link's camera is spent on the first molecule framed; afterwards the
+      // camera is the reader's and a new molecule is framed as usual.
+      const linked: Molecule3DCamera | null = isNew
+        ? camera.takeLinkedCamera()
+        : null;
+      const frameCamera = isNew && linked === null ? frameNewMolecule : 'none';
+      void drawScene(viewer, molfile, settings, measurements, frameCamera)
+        .then(() => {
+          if (cancelled) return;
+          if (linked !== null) void viewer.setCamera(linked);
+          reportFailure.current(null);
+        })
+        .catch((error: unknown) => {
+          if (cancelled) return;
+          reportFailure.current(
+            error instanceof Error ? error.message : String(error),
+          );
+        });
+    });
+    return () => {
+      cancelled = true;
+      cancelAnimationFrame(frame);
+    };
+  }, [
+    container,
+    viewerRef,
+    molfile,
+    frameNewMolecule,
+    settings,
+    measurements,
+    camera,
+  ]);
+
+  const resetView = useCallback(() => {
+    camera.noteMove();
+    void viewerRef.current?.resetCamera();
+  }, [camera, viewerRef]);
+
+  return { resetView };
+}

package/src/molecule3d/ui/useSharedCamera.ts

@@ -0,0 +1,121 @@
+/**
+ * The camera of the canvas as something a site can keep: the one a link
+ * carried, applied to the first molecule framed, and every move the reader
+ * makes afterwards, reported once it has come to rest.
+ *
+ * The camera is never controlled. It belongs to whoever is dragging it, so the
+ * site is told where it went rather than asked where it should be — anything
+ * else fights the trackball.
+ */
+
+import type { RefObject } from 'react';
+import { useCallback, useEffect, useMemo, useRef } from 'react';
+
+import type { Molecule3DCamera } from '../core/camera.ts';
+import { formatMolecule3DCamera } from '../core/camera.ts';
+
+import type { Molecule3DViewer } from './viewer.ts';
+
+/** How long the camera must be still before a move is reported, milliseconds. */
+export const DEFAULT_CAMERA_SETTLE_DELAY = 400;
+
+/** What {@link useSharedCamera} is given. */
+export interface SharedCameraOptions {
+  /** The element molstar draws in, or `null` before it exists. */
+  container: HTMLElement | null;
+  /** The viewer mounted in it. */
+  viewerRef: RefObject<Molecule3DViewer | null>;
+  /** Where the camera stands when the first molecule is framed. */
+  initialCamera: Molecule3DCamera | null;
+  /** Called once a move of the reader's has come to rest. */
+  onCameraChange?: (camera: Molecule3DCamera) => void;
+  /** Whether the model is turning, which suspends reporting. */
+  spinning: boolean;
+  /** How long the camera must be still before a move is reported. */
+  settleDelay: number;
+}
+
+/**
+ * What {@link useSharedCamera} answers. The same object on every render: the
+ * draw effect keys on it, and a fresh one would tear the scene down and build
+ * it again — which makes molstar frame the model afresh and loses the camera a
+ * link had just restored.
+ */
+export interface SharedCamera {
+  /**
+   * The camera a link carried, answered once and then never again — the next
+   * molecule is framed the way the viewer frames any other.
+   * @returns The camera to stand at, or `null` to frame the molecule.
+   */
+  takeLinkedCamera: () => Molecule3DCamera | null;
+  /** Note a move of the reader's, which is what starts reporting. */
+  noteMove: () => void;
+}
+
+/**
+ * Keep the camera of one canvas in step with the site that shows it.
+ * @param options - See {@link SharedCameraOptions}.
+ * @returns See {@link SharedCamera}.
+ */
+export function useSharedCamera(options: SharedCameraOptions): SharedCamera {
+  const { container, viewerRef, settleDelay } = options;
+  // Spent on the first molecule framed.
+  const linkedRef = useRef(false);
+  // What the last report said, so the settling of a move we ordered ourselves
+  // is not handed back to the site as a move the reader made.
+  const reportedRef = useRef<string | null>(null);
+  // Whether the reader has touched the canvas, which is what starts reporting.
+  const movedRef = useRef(false);
+  const latest = useRef(options);
+  useEffect(() => {
+    latest.current = options;
+  });
+
+  const noteMove = useCallback(() => {
+    movedRef.current = true;
+  }, []);
+
+  const takeLinkedCamera = useCallback(() => {
+    if (linkedRef.current) return null;
+    linkedRef.current = true;
+    const camera = latest.current.initialCamera;
+    if (camera !== null) reportedRef.current = formatMolecule3DCamera(camera);
+    return camera;
+  }, []);
+
+  // Reporting waits for a first gesture. The camera also drifts on its own — a
+  // surface added after the model was framed grows the scene, and the same
+  // camera then reads as slightly closer — and a view nobody chose is not one
+  // to hand back to the site, let alone to put in a link.
+  useEffect(() => {
+    const viewer = viewerRef.current;
+    if (container === null || viewer === null) return;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+    container.addEventListener('pointerdown', noteMove);
+    container.addEventListener('wheel', noteMove, { passive: true });
+    const stopWatching = viewer.watchCamera((camera) => {
+      if (camera === null) return;
+      if (timer !== null) clearTimeout(timer);
+      timer = setTimeout(() => {
+        timer = null;
+        const current = latest.current;
+        if (current.spinning || !movedRef.current) return;
+        const text = formatMolecule3DCamera(camera);
+        if (text === reportedRef.current) return;
+        reportedRef.current = text;
+        current.onCameraChange?.(camera);
+      }, settleDelay);
+    });
+    return () => {
+      if (timer !== null) clearTimeout(timer);
+      container.removeEventListener('pointerdown', noteMove);
+      container.removeEventListener('wheel', noteMove);
+      stopWatching();
+    };
+  }, [container, viewerRef, settleDelay, noteMove]);
+
+  return useMemo(
+    () => ({ takeLinkedCamera, noteMove }),
+    [takeLinkedCamera, noteMove],
+  );
+}

package/src/molecule3d/ui/viewer.ts

@@ -1,21 +1,17 @@
 /**
- * Lifecycle of one molstar molecule viewer.
+ * Lifecycle of one molstar molecule viewer: `createMolecule3DViewer` builds
+ * one, and every operation a component performs on it is a method here.
  *
- * `createMolecule3DViewer` is **synchronous** on purpose. React 19 runs an
- * effect, its cleanup and the effect again on every mount in development, so an
- * awaited constructor hands the cleanup nothing to dispose and leaks a WebGL
- * context per mount. Returning the handle immediately means `dispose()` can
- * always be called; the work is queued behind `ready`.
- *
- * molstar's own UI is not mounted: every control is the component's.
+ * The constructor returns before the canvas exists — see `createViewer.ts` —
+ * so every method queues its work behind `ready` and resolves to nothing once
+ * the viewer has been disposed. molstar's own UI is not mounted: every control
+ * is the component's.
  */
 
-import { PluginViewModel } from 'molstar/lib/extensions/plugin/view-model.js';
+import type { PluginViewModel } from 'molstar/lib/extensions/plugin/view-model.js';
 import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
-// Lowercased on import: it is a factory, not a constructor.
-import { DefaultPluginSpec as defaultPluginSpec } from 'molstar/lib/mol-plugin/spec.js';
-import { Color } from 'molstar/lib/mol-util/color/color.js';
 
+import type { Molecule3DCamera } from '../core/camera.ts';
 import type { ImageSize } from '../core/exportImage.ts';
 import type { Measurement, MeasurementKind } from '../core/measurement.ts';
 import type { Molecule3DFile } from '../core/settings.ts';
@@ -23,9 +19,12 @@ import type { Molecule3DFile } from '../core/settings.ts';
 import {
   DEFAULT_CAMERA_DURATION,
   DEFAULT_SPIN_SPEED,
+  applyCamera,
   resetCamera,
   setSpin,
+  watchCamera,
 } from './camera.ts';
+import { captureScene } from './captureScene.ts';
 import {
   MeasurementPicker,
   clearMeasurements,
@@ -33,25 +32,13 @@ import {
 } from './measurements.ts';
 import { clearMolecule, renderMolecule } from './renderMolecule.ts';
 import { clearSurface, renderSurface } from './renderSurface.ts';
+import { mountMolecule3DPlugin } from './viewerSpec.ts';
 import type {
   Molecule3DViewerOptions,
   MoleculeStyle,
   SurfaceStyle,
 } from './viewerTypes.ts';
 
-/**
- * Create a viewer inside `container` and start initialising it.
- * @param container - A positioned element; molstar inserts its canvas into it.
- * @param options - See {@link Molecule3DViewerOptions}.
- * @returns A handle that is safe to dispose immediately.
- */
-export function createMolecule3DViewer(
-  container: HTMLElement,
-  options: Molecule3DViewerOptions = {},
-): Molecule3DViewer {
-  return new Molecule3DViewer(container, options);
-}
-
 /**
  * One molstar canvas, and every operation the component performs on it. Every
  * method resolves to nothing once `dispose` has been called.
@@ -74,18 +61,7 @@ export class Molecule3DViewer {
       background = '#ffffff', // tokens-ok: a WebGL clear colour
       onMeasure = ignore,
     } = options;
-    const spec = defaultPluginSpec();
-    this.#model = new PluginViewModel({
-      spec: {
-        ...spec,
-        canvas3d: {
-          ...spec.canvas3d,
-          renderer: { backgroundColor: Color.fromHexStyle(background) },
-          camera: { helper: { axes: { name: 'off', params: {} } } },
-        },
-      },
-    });
-    this.#model.mount(container);
+    this.#model = mountMolecule3DPlugin(container, background);
     this.ready = this.#model.initialized;
     // Registered before any `#run`, so the picker exists by the time one runs.
     this.ready.then(() => {
@@ -164,19 +140,7 @@ export class Molecule3DViewer {
    * @throws {Error} When the plugin has no screenshot helper.
    */
   captureImage(size: ImageSize): Promise<string | undefined> {
-    return this.#run(async (plugin) => {
-      const helper = plugin.helpers.viewportScreenshot;
-      if (helper === undefined) {
-        throw new Error('This viewer cannot take a picture of its scene.');
-      }
-      helper.behaviors.values.next({
-        ...helper.values,
-        resolution: { name: 'custom', params: size },
-        axes: { name: 'off', params: {} },
-        transparent: false,
-      });
-      return helper.getImageDataUri();
-    });
+    return this.#run((plugin) => captureScene(plugin, size));
   }
 
   /**
@@ -194,6 +158,37 @@ export class Molecule3DViewer {
     });
   }
 
+  /**
+   * Put the camera where a link says it stood.
+   * @param camera - Where to stand.
+   * @param durationMilliseconds - Transition length; 0 jumps.
+   * @returns Nothing; resolves once the move has been ordered.
+   */
+  setCamera(camera: Molecule3DCamera, durationMilliseconds = 0): Promise<void> {
+    return this.#run((plugin) => {
+      applyCamera(plugin, camera, durationMilliseconds);
+    });
+  }
+
+  /**
+   * Follow the camera, however it moves.
+   * @param listener - Called after every move.
+   * @returns A function that stops calling the listener; safe to call before
+   * the canvas exists.
+   */
+  watchCamera(listener: (camera: Molecule3DCamera | null) => void): () => void {
+    let stop: (() => void) | null = null;
+    let cancelled = false;
+    void this.#run((plugin) => {
+      if (!cancelled) stop = watchCamera(plugin, listener);
+    });
+    return () => {
+      cancelled = true;
+      stop?.();
+      stop = null;
+    };
+  }
+
   /**
    * Turn the automatic spin on or off.
    * @param spinning - Whether the scene should keep turning.

package/src/molecule3d/ui/viewerSpec.ts

@@ -0,0 +1,38 @@
+/**
+ * How the molecule viewer configures molstar: the plugin spec it mounts with.
+ *
+ * molstar's own UI is not mounted — every control is the component's — and the
+ * axes helper is off, since a molecule is read from its own shape rather than
+ * from the world axes.
+ */
+
+import { PluginViewModel } from 'molstar/lib/extensions/plugin/view-model.js';
+// Lowercased on import: it is a factory, not a constructor.
+import { DefaultPluginSpec as defaultPluginSpec } from 'molstar/lib/mol-plugin/spec.js';
+import { Color } from 'molstar/lib/mol-util/color/color.js';
+
+/**
+ * Build a view model for one canvas and mount it.
+ * @param container - A positioned element; molstar inserts its canvas into it.
+ * @param background - Scene background as `#rrggbb`; a WebGL clear colour, so
+ * it cannot be a CSS custom property.
+ * @returns The mounted view model, still initialising.
+ */
+export function mountMolecule3DPlugin(
+  container: HTMLElement,
+  background: string,
+): PluginViewModel {
+  const spec = defaultPluginSpec();
+  const model = new PluginViewModel({
+    spec: {
+      ...spec,
+      canvas3d: {
+        ...spec.canvas3d,
+        renderer: { backgroundColor: Color.fromHexStyle(background) },
+        camera: { helper: { axes: { name: 'off', params: {} } } },
+      },
+    },
+  });
+  model.mount(container);
+  return model;
+}