react-cheminfo 0.7.0 → 0.9.0

package/src/orbital/ui/AtomicOrbitalCanvas.tsx

@@ -6,9 +6,12 @@
  * reason the two components are separate files.
  */
 
+import { Button } from '@blueprintjs/core';
 import type { CSSProperties, ReactElement } from 'react';
 import { useEffect, useRef, useState } from 'react';
 
+import type { HelpContent } from '../../help/ui/HelpBody.tsx';
+import { HelpTooltip } from '../../help/ui/HelpTooltip.tsx';
 import type { ResolutionLimits } from '../core/atomicGrid.ts';
 import type { PhasePalette } from '../core/palette.ts';
 import { PHASE_PALETTES } from '../core/palette.ts';
@@ -39,6 +42,24 @@ export interface AtomicOrbitalCanvasProps {
    * @default 56
    */
   resolution?: number | ResolutionLimits;
+  /**
+   * Whether the labelled x, y, z frame is drawn through the nucleus when the
+   * canvas opens. A `3d_xz` is only `3d_xz` because of where its lobes sit
+   * against those axes, and a lone isosurface says nothing about that, so the
+   * frame is on unless a site says otherwise.
+   *
+   * The canvas owns the state from then on: the button in its corner flips it,
+   * and {@link AtomicOrbitalCanvasProps.onAxesChange} reports the new value to
+   * a site that wants to remember it for the next mount.
+   * @default true
+   */
+  axes?: boolean;
+  /**
+   * Called when the student flips the frame, with its new state — so a site can
+   * persist the choice and pass it back as `axes`.
+   * @default undefined
+   */
+  onAxesChange?: (axes: boolean) => void;
   /**
    * Whether the scene turns on its own, which is what makes a still screenshot
    * of a 3D shape readable.
@@ -82,9 +103,11 @@ export function AtomicOrbitalCanvas(
     orbitalId,
     palette = PHASE_PALETTES.textbook,
     resolution = DEFAULT_RESOLUTION,
+    axes: initialAxes = true,
     spinning = false,
     spinSpeed = DEFAULT_SPIN_SPEED,
     sample = sampleInProcess,
+    onAxesChange,
     onNodeRadii,
     onError,
   } = props;
@@ -93,6 +116,15 @@ export function AtomicOrbitalCanvas(
   const viewerRef = useRef<OrbitalViewer | null>(null);
   const [drawn, setDrawn] = useState<string | null>(null);
 
+  // How far the drawn surface reaches, and whether the frame is wanted around
+  // it. Both are read by the sampling effect, which finishes long after the
+  // render that started it; keeping them in refs is what lets the frame be
+  // switched on without re-sampling the orbital.
+  const reachRef = useRef<number | null>(null);
+  const axesRef = useRef(initialAxes);
+
+  const [axes, setAxes] = useState(initialAxes);
+
   // What the canvas is being asked to show. Comparing it with what it *is*
   // showing gives the progress note without a state write on every prop change.
   const wanted = `${atomicNumber}|${orbitalId}|${resolutionKey(resolution)}|${palette.id}`;
@@ -100,9 +132,9 @@ export function AtomicOrbitalCanvas(
 
   // Callbacks are read through refs so a caller passing an inline arrow does
   // not re-sample the orbital on every render of its parent.
-  const callbacks = useRef({ onNodeRadii, onError });
+  const callbacks = useRef({ onAxesChange, onNodeRadii, onError });
   useEffect(() => {
-    callbacks.current = { onNodeRadii, onError };
+    callbacks.current = { onAxesChange, onNodeRadii, onError };
   });
 
   // Created and disposed once per mount. React 19 runs this twice in
@@ -136,7 +168,8 @@ export function AtomicOrbitalCanvas(
           positiveColour: palette.positive,
           negativeColour: palette.negative,
         });
-        await viewer.frame(reach);
+        reachRef.current = reach ?? null;
+        await viewer.refit(await fitAxes(viewer, reach, axesRef.current));
         if (!cancelled) setDrawn(wanted);
       })
       .catch((error: unknown) => {
@@ -150,6 +183,16 @@ export function AtomicOrbitalCanvas(
     };
   }, [atomicNumber, orbitalId, resolution, palette, sample, wanted]);
 
+  // Toggling the frame on an orbital already on screen: the field it was drawn
+  // from is unchanged, so nothing is re-sampled.
+  useEffect(() => {
+    axesRef.current = axes;
+    const viewer = viewerRef.current;
+    const reach = reachRef.current;
+    if (viewer === null || reach === null) return;
+    void fitAxes(viewer, reach, axes).then((framed) => viewer.refit(framed));
+  }, [axes]);
+
   useEffect(() => {
     void viewerRef.current?.setSpin(spinning, spinSpeed);
   }, [spinning, spinSpeed]);
@@ -157,10 +200,75 @@ export function AtomicOrbitalCanvas(
   return (
     <div ref={containerRef} style={CANVAS_STYLE}>
       {busy && <div style={BUSY_STYLE}>Sampling…</div>}
+      <div style={CONTROLS_STYLE}>
+        <HelpTooltip content={AXES_HELP} placement="bottom">
+          <Button
+            variant="minimal"
+            size="small"
+            icon="grid"
+            active={axes}
+            aria-label="Show the x, y, z axes"
+            aria-pressed={axes}
+            onClick={() => {
+              setAxes(!axes);
+              callbacks.current.onAxesChange?.(!axes);
+            }}
+          />
+        </HelpTooltip>
+        <HelpTooltip content={RESET_HELP} placement="bottom">
+          <Button
+            variant="minimal"
+            size="small"
+            icon="zoom-to-fit"
+            aria-label="Reset the view"
+            onClick={() => {
+              void viewerRef.current?.resetView();
+            }}
+          />
+        </HelpTooltip>
+      </div>
     </div>
   );
 }
 
+/**
+ * Draw the cartesian frame around the orbital, or remove it.
+ * @param viewer - The viewer holding the canvas.
+ * @param reach - How far the drawn surface reaches, as `showOrbital` returned
+ * it.
+ * @param axes - Whether the frame is wanted.
+ * @returns What the camera has to fit: the frame reaches past the surface, so
+ * turning it on has to zoom out or the labels sit off screen.
+ */
+async function fitAxes(
+  viewer: OrbitalViewer,
+  reach: number | undefined,
+  axes: boolean,
+): Promise<number | undefined> {
+  if (!axes) {
+    await viewer.hideAxes();
+    return reach;
+  }
+  if (reach === undefined) return undefined;
+  return (await viewer.showAxes(reach)) ?? reach;
+}
+
+/** What the frame button says it is for. */
+const AXES_HELP: HelpContent = {
+  title: 'Cartesian axes',
+  body: 'Draw x, y and z through the nucleus. The label names an orbital by where its lobes sit against them.',
+  example: {
+    code: '3d_yz',
+    note: 'four lobes between the y and z axes, none on either.',
+  },
+};
+
+/** What the reset button says it is for. */
+const RESET_HELP: HelpContent = {
+  title: 'Reset the view',
+  body: 'Back to the angle and zoom the orbital opened on. A change of orbital keeps whatever view you have turned it to.',
+};
+
 /** Samples per edge; 56 resolves the radial node of a 3s in about 25 ms. */
 const DEFAULT_RESOLUTION = 56;
 
@@ -191,6 +299,20 @@ const CANVAS_STYLE: CSSProperties = {
   overflow: 'hidden',
 };
 
+/**
+ * The two controls the canvas owns: the frame, and the way back to the framing
+ * the orbital opened on — a change of orbital now keeps whatever angle and zoom
+ * the student is on.
+ */
+const CONTROLS_STYLE: CSSProperties = {
+  position: 'absolute',
+  top: 4,
+  right: 4,
+  zIndex: 1,
+  display: 'flex',
+  gap: 2,
+};
+
 const BUSY_STYLE: CSSProperties = {
   position: 'absolute',
   top: 8,
@@ -199,6 +321,6 @@ const BUSY_STYLE: CSSProperties = {
   padding: '3px 8px',
   borderRadius: 3,
   background: 'rgba(255, 255, 255, 0.85)',
-  color: '#5f6b7c',
+  color: 'var(--text-muted, #5f6b7c)',
   fontSize: 11,
 };

package/src/orbital/ui/AtomicOrbitalViewer.tsx

@@ -51,6 +51,19 @@ export interface AtomicOrbitalViewerProps {
    * @default 56
    */
   resolution?: number | ResolutionLimits;
+  /**
+   * Whether the labelled x, y, z frame is drawn through the nucleus when the
+   * canvas opens — it is what tells a `3d_xz` from a `3d_yz`. The button in the
+   * canvas's corner flips it from there.
+   * @default true
+   */
+  axes?: boolean;
+  /**
+   * Called when the student flips the frame, with its new state — so a site can
+   * persist the choice and pass it back as `axes`.
+   * @default undefined
+   */
+  onAxesChange?: (axes: boolean) => void;
   /**
    * Whether the scene turns on its own.
    * @default false
@@ -145,7 +158,7 @@ const NOTE_STYLE: CSSProperties = {
   padding: 12,
   borderRadius: 3,
   background: 'rgb(241 245 249)',
-  color: '#5f6b7c',
+  color: 'var(--text-muted, #5f6b7c)',
   fontSize: 13,
   textAlign: 'center',
 };

package/src/orbital/ui/camera.ts

@@ -107,11 +107,92 @@ export function frameOrbital(
       position: Vec3.add(Vec3.zero(), centre, offset),
       up: Vec3.clone(ORBITAL_VIEW_UP),
       radius,
+      ...radiusMaxOf(canvas3d),
     },
     durationMs,
   );
 }
 
+/**
+ * Keep the view the student has set, and rescale it for an orbital of a
+ * different extent.
+ *
+ * Every atomic orbital is drawn at one canonical size, so the two extents are
+ * normally equal and the camera does not move at all: clicking through a shell
+ * keeps the rotation and the zoom instead of throwing them away. When they do
+ * differ, the offset from the target and the radius are multiplied by the same
+ * factor, which keeps the zoom *relative* to the orbital.
+ * @param plugin - The molstar context.
+ * @param previousRadius - Extent the camera is currently fitted to.
+ * @param orbitalRadius - Extent to fit now.
+ * @param durationMs - Transition length. Pass 0 for an instant jump.
+ */
+export function refitOrbital(
+  plugin: PluginContext,
+  previousRadius: number,
+  orbitalRadius: number,
+  durationMs = DEFAULT_CAMERA_DURATION,
+): void {
+  const canvas3d = plugin.canvas3d;
+  if (canvas3d === undefined) return;
+  const scale = orbitalRadius / previousRadius;
+  if (!Number.isFinite(scale) || scale <= 0) {
+    frameOrbital(plugin, orbitalRadius, durationMs);
+    return;
+  }
+  // The box a sampled orbital lives in changes with the orbital, and molstar
+  // only tracks that for a camera it also reframes, which this one is not.
+  const radiusMax = radiusMaxOf(canvas3d);
+  if (scale === 1) {
+    canvas3d.camera.setState(radiusMax, 0);
+    return;
+  }
+  const { target, position, radius } = canvas3d.camera.state;
+  const offset = Vec3.sub(Vec3.zero(), position, target);
+  Vec3.scale(offset, offset, scale);
+  canvas3d.camera.setState(
+    {
+      position: Vec3.add(Vec3.zero(), target, offset),
+      radius: radius * scale,
+      ...radiusMax,
+    },
+    durationMs,
+  );
+}
+
+/**
+ * The far plane's share of a camera state, left out when the scene cannot be
+ * measured yet.
+ * @param canvas3d - The canvas whose scene to measure.
+ * @returns `{ radiusMax }`, or an empty object to keep the camera's own value.
+ */
+function radiusMaxOf(canvas3d: PluginContext['canvas3d'] & object): {
+  radiusMax?: number;
+} {
+  const radiusMax = sceneRadius(canvas3d);
+  return radiusMax > 0 ? { radiusMax } : {};
+}
+
+/**
+ * How far the whole scene reaches, as molstar measures it for its near and far
+ * planes.
+ *
+ * `boundingSphere` covers the whole scene but is only recomputed on a draw, so
+ * in the moment after a representation was added it still reads 0 — and a zero
+ * `radiusMax` collapses the near and far planes onto the target, leaving the
+ * orbital sliced into a few thin arcs. The visible sphere is current there, so
+ * it stands in.
+ * @param canvas3d - The canvas whose scene to measure.
+ * @returns The radius, in scene units; 0 when neither sphere is ready.
+ */
+function sceneRadius(canvas3d: PluginContext['canvas3d'] & object): number {
+  const radius =
+    canvas3d.boundingSphere.radius > 0
+      ? canvas3d.boundingSphere.radius
+      : canvas3d.boundingSphereVisible.radius;
+  return radius * canvas3d.props.sceneRadiusFactor;
+}
+
 /**
  * Turn the automatic spin on or off.
  * @param plugin - The molstar context.

package/src/orbital/ui/renderVolume.ts

@@ -108,7 +108,14 @@ export async function renderSampledVolume(
   const drawn = surfaces.filter(
     (surface): surface is Representation.Any => surface !== null,
   );
-  representations.set(plugin, drawn);
+  // Added to whatever is already recorded rather than replacing it, so the
+  // record is every surface on the canvas and the next clear can take them all
+  // away. Overwriting it would strand any pair that reached the canvas without
+  // being the last one recorded, and a stranded pair is on screen for good.
+  representations.set(plugin, [
+    ...(representations.get(plugin) ?? []),
+    ...drawn,
+  ]);
   for (const representation of drawn) canvas3d.add(representation);
   // add() only queues; nothing appears until the queue is committed.
   canvas3d.commit();

package/src/orbital/ui/serial.ts

@@ -0,0 +1,35 @@
+/**
+ * Running asynchronous work one piece at a time.
+ *
+ * Everything the viewer does mutates one canvas, and it does it across an
+ * `await`: replacing an orbital removes the surfaces on screen before it has
+ * finished building the new ones. Two of those interleaved both add their own
+ * pair and only one of them is remembered, so the atom ends up wearing several
+ * orbitals at once and the ones nobody recorded can never be removed again.
+ */
+
+/** Runs what it is given after everything handed to it before. */
+export interface SerialRunner {
+  /**
+   * Queue `task`, and resolve to what it returns.
+   * @param task - The work to run once the queue reaches it.
+   * @returns What `task` resolved to; its rejection reaches this caller alone.
+   */
+  run: <Result>(task: () => Promise<Result>) => Promise<Result>;
+}
+
+/**
+ * A queue of one.
+ * @returns The runner. A task that throws is reported to whoever queued it and
+ * never stalls the tasks behind it.
+ */
+export function createSerialRunner(): SerialRunner {
+  let tail: Promise<unknown> = Promise.resolve();
+  return {
+    run: <Result>(task: () => Promise<Result>): Promise<Result> => {
+      const result = tail.then(task);
+      tail = result.catch(() => undefined);
+      return result;
+    },
+  };
+}

package/src/orbital/ui/viewer.ts

@@ -26,12 +26,14 @@ import {
   DEFAULT_CAMERA_DURATION,
   DEFAULT_SPIN_SPEED,
   frameOrbital,
+  refitOrbital,
   setSpin,
 } from './camera.ts';
 import type { AxesStyle } from './renderAxes.ts';
 import { clearOrbitalAxes, renderOrbitalAxes } from './renderAxes.ts';
 import type { VolumeStyle } from './renderVolume.ts';
 import { clearSampledVolume, renderSampledVolume } from './renderVolume.ts';
+import { createSerialRunner } from './serial.ts';
 
 /** Settings fixed for the life of a viewer. */
 export interface OrbitalViewerOptions {
@@ -64,7 +66,12 @@ export function createOrbitalViewer(
  */
 export class OrbitalViewer {
   readonly #model: PluginViewModel;
+  // One canvas, so one operation at a time — see `serial.ts` for what
+  // interleaving two of them does to the scene.
+  readonly #serial = createSerialRunner();
   #disposed = false;
+  /** Extent the camera was last fitted to; `null` before it has been placed. */
+  #fittedRadius: number | null = null;
 
   /** Resolves once the canvas exists; every method awaits it internally. */
   readonly ready: Promise<void>;
@@ -78,7 +85,16 @@ export class OrbitalViewer {
         canvas3d: {
           ...spec.canvas3d,
           renderer: { backgroundColor: Color.fromHexStyle(background) },
-          camera: { helper: { axes: { name: 'off', params: {} } } },
+          camera: {
+            helper: { axes: { name: 'off', params: {} } },
+            // The camera is ours alone. Molstar reframes itself whenever a
+            // scene commit leaves the renderable count at zero, which is what
+            // replacing one orbital by another does — the old surfaces are
+            // removed and committed before the new ones exist — and it frames
+            // the whole sampled box rather than the isosurface inside it,
+            // which leaves the orbital a fifth of the frame wide.
+            manualReset: true,
+          },
         },
       },
     });
@@ -159,9 +175,49 @@ export class OrbitalViewer {
   ): Promise<void> {
     return this.#run((plugin) => {
       frameOrbital(plugin, orbitalRadius, durationMs);
+      this.#fittedRadius = orbitalRadius ?? null;
     });
   }
 
+  /**
+   * Fit a newly drawn orbital without disturbing the view.
+   *
+   * The first call frames the orbital, since there is no view to keep yet.
+   * Later ones leave the rotation and the zoom the student set and only rescale
+   * them when the drawn extent changed — clicking through a shell must not
+   * throw their view away.
+   * @param orbitalRadius - Extent of the drawn surface, as `showOrbital`
+   * returned it.
+   * @param durationMs - Transition length; 0 jumps.
+   * @returns Nothing, once the camera has been set.
+   */
+  refit(
+    orbitalRadius?: number,
+    durationMs = DEFAULT_CAMERA_DURATION,
+  ): Promise<void> {
+    const fitted = this.#fittedRadius;
+    if (fitted === null || orbitalRadius === undefined) {
+      return this.frame(orbitalRadius, durationMs);
+    }
+    return this.#run((plugin) => {
+      refitOrbital(plugin, fitted, orbitalRadius, durationMs);
+      this.#fittedRadius = orbitalRadius;
+    });
+  }
+
+  /**
+   * Put the camera back where the orbital was first framed from.
+   *
+   * The counterpart of `refit`: since a view is now kept across a change of
+   * orbital, a student who has turned the atom into an unreadable angle needs
+   * one way back.
+   * @param durationMs - Transition length; 0 jumps.
+   * @returns Nothing, once the camera has been set.
+   */
+  resetView(durationMs = DEFAULT_CAMERA_DURATION): Promise<void> {
+    return this.frame(this.#fittedRadius ?? undefined, durationMs);
+  }
+
   /**
    * Turn the automatic spin on or off.
    * @param spinning - Whether the scene should keep turning.
@@ -199,23 +255,26 @@ export class OrbitalViewer {
   }
 
   /**
-   * Wait for initialisation, then run `action` on the plugin. Resolves to
-   * `undefined` when the viewer was disposed, before the call or while `action`
-   * was still running; an initialisation failure still reaches the caller.
+   * Wait for the operations queued before this one and for initialisation,
+   * then run `action` on the plugin. Resolves to `undefined` when the viewer
+   * was disposed, before the call or while `action` was still running; an
+   * initialisation failure still reaches the caller.
    * @param action - What to run once the canvas is ready.
    * @returns What `action` returned, or `undefined` when disposed.
    */
-  async #run<Result>(
+  #run<Result>(
     action: (plugin: PluginContext) => Result | Promise<Result>,
   ): Promise<Result | undefined> {
-    if (this.#disposed) return undefined;
-    await this.ready;
-    if (this.#disposed) return undefined;
-    try {
-      return await action(this.#model.plugin);
-    } catch (error) {
+    return this.#serial.run(async () => {
       if (this.#disposed) return undefined;
-      throw error;
-    }
+      await this.ready;
+      if (this.#disposed) return undefined;
+      try {
+        return await action(this.#model.plugin);
+      } catch (error) {
+        if (this.#disposed) return undefined;
+        throw error;
+      }
+    });
   }
 }

package/src/pedagogy/ui/ExerciseProgressHeader.tsx

@@ -129,7 +129,7 @@ const ROW_STYLE: CSSProperties = {
 const COUNT_STYLE: CSSProperties = { fontWeight: 600 };
 
 const PERCENT_STYLE: CSSProperties = {
-  color: '#5b6875',
+  color: 'var(--text-muted, #5b6875)',
   flex: '1 1 auto',
   fontSize: 12,
 };

package/src/pedagogy/ui/GlossaryText.tsx

@@ -140,7 +140,7 @@ const TITLE_STYLE: CSSProperties = { fontWeight: 600, fontSize: 13 };
 const SUMMARY_STYLE: CSSProperties = {
   fontSize: 12,
   lineHeight: 1.45,
-  color: '#d3d8de',
+  color: 'var(--border, #d3d8de)',
 };
 
 const LIST_STYLE: CSSProperties = {
@@ -159,6 +159,6 @@ const CODE_STYLE: CSSProperties = {
   color: '#8abbff',
 };
 
-const INPUT_STYLE: CSSProperties = { color: '#f6f7f9' };
+const INPUT_STYLE: CSSProperties = { color: 'var(--surface-sunken, #f6f7f9)' };
 
 const NOTE_STYLE: CSSProperties = { fontStyle: 'italic', color: '#abb3bf' };

package/src/pedagogy/ui/ReferenceSectionBlock.tsx

@@ -140,7 +140,10 @@ function syntaxStyle(
     fontWeight: 600,
     color: '#1c2127',
     ...(interactive
-      ? { borderBottom: '1px dotted #5b6875', alignSelf: 'flex-start' }
+      ? {
+          borderBottom: '1px dotted var(--text-muted, #5b6875)',
+          alignSelf: 'flex-start',
+        }
       : {}),
   };
 }
@@ -153,7 +156,7 @@ const SECTION_STYLE: CSSProperties = {
 
 const INTRO_STYLE: CSSProperties = {
   margin: '0 0 4px',
-  color: '#5b6875',
+  color: 'var(--text-muted, #5b6875)',
   fontSize: 12,
 };
 

package/src/pedagogy/ui/SyntaxTooltip.tsx

@@ -191,7 +191,7 @@ const TAG_STYLE: CSSProperties = { color: '#abb3bf', fontSize: 11 };
 const SUMMARY_STYLE: CSSProperties = { fontSize: 12, lineHeight: 1.4 };
 
 const DETAIL_STYLE: CSSProperties = {
-  color: '#d3d8de',
+  color: 'var(--border, #d3d8de)',
   fontSize: 12,
   lineHeight: 1.45,
 };
@@ -209,7 +209,7 @@ const ROW_STYLE: CSSProperties = { display: 'flex', gap: 6, fontSize: 12 };
 const LABEL_STYLE: CSSProperties = { color: '#abb3bf', flex: '0 0 68px' };
 
 const VALUE_STYLE: CSSProperties = {
-  color: '#f6f7f9',
+  color: 'var(--surface-sunken, #f6f7f9)',
   fontFamily: MONOSPACE,
   overflowWrap: 'anywhere',
 };