react-cheminfo 0.8.0 → 0.9.0

package/src/delimited/ui/DelimitedTextPanel.tsx

@@ -143,7 +143,7 @@ const CONTROLS_STYLE = {
 } as const satisfies CSSProperties;
 
 const LABEL_STYLE = {
-  color: '#5f6b7c',
+  color: 'var(--text-muted, #5f6b7c)',
   fontSize: 12,
 } as const satisfies CSSProperties;
 

package/src/ecosystem/core/sites.ts

@@ -1,5 +1,7 @@
+// tokens-ok: file — every site's two colours are declared here.
 /** The sites the menu links to, in the order they are listed. */
 export type SiteId =
+  | 'learn'
   | 'inchi'
   | 'vcl'
   | 'smiles'
@@ -70,6 +72,16 @@ export interface SiteMarkColors {
  * go with them live in `marks.tsx`.
  */
 export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
+  {
+    id: 'learn',
+    name: { lead: 'learn', alt: 'cheminfo', dot: true },
+    host: 'learn.cheminfo.org',
+    repository: 'https://github.com/cheminfo/learn.cheminfo.org',
+    tagline: 'Arrange the tools into a course and hand out its link.',
+    brand: '#0d9488',
+    brandAlt: '#b45309',
+    mark: { plate: '#0d9488', accent: '#f59e0b' },
+  },
   {
     id: 'inchi',
     name: { lead: 'inchi', alt: 'cheminfo', dot: true },

package/src/ecosystem/core/tokens.ts

@@ -1,3 +1,4 @@
+// tokens-ok: file — the block a site renders is written here.
 import { siteById } from './lookup.ts';
 import type { EcosystemSite, SiteId } from './sites.ts';
 

package/src/ecosystem/ui/EcosystemLinks.tsx

@@ -17,7 +17,7 @@ const SECTION_STYLE: CSSProperties = {
 };
 const HEADING_STYLE: CSSProperties = {
   margin: 0,
-  color: '#5b6875',
+  color: 'var(--text-muted, #5b6875)',
   fontSize: '0.75rem',
   fontWeight: 600,
 };
@@ -40,7 +40,7 @@ const LINK_STYLE: CSSProperties = {
 };
 const CURRENT_STYLE: CSSProperties = {
   ...LINK_STYLE,
-  color: '#8a96a3',
+  color: 'var(--text-faint, #8a96a3)',
   cursor: 'default',
 };
 

package/src/ecosystem/ui/EcosystemMenu.tsx

@@ -14,7 +14,7 @@ const PANEL_STYLE: CSSProperties = {
   gap: 8,
 };
 const HEADING_STYLE: CSSProperties = {
-  color: '#5b6875',
+  color: 'var(--text-muted, #5b6875)',
   fontSize: '0.75rem',
   fontWeight: 600,
 };

package/src/ecosystem/ui/SiteTile.tsx

@@ -11,7 +11,7 @@ const TILE_STYLE: CSSProperties = {
   padding: '7px 8px',
   border: '1px solid transparent',
   borderRadius: 10,
-  color: '#16202c',
+  color: 'var(--text, #16202c)',
   gap: 10,
   textDecoration: 'none',
   transition: 'background 120ms, border-color 120ms, transform 120ms',
@@ -37,7 +37,7 @@ const HERE_STYLE: CSSProperties = {
   textTransform: 'uppercase',
 };
 const TAGLINE_STYLE: CSSProperties = {
-  color: '#5b6875',
+  color: 'var(--text-muted, #5b6875)',
   fontSize: '0.75rem',
   lineHeight: 1.35,
 };
@@ -91,7 +91,9 @@ export function SiteTile(props: SiteTileProps): ReactElement {
         <div style={NAME_STYLE}>
           <span>
             <span style={{ color: site.brand }}>{site.name.lead}</span>
-            {site.name.dot ? <span style={{ color: '#8a96a3' }}>.</span> : null}
+            {site.name.dot ? (
+              <span style={{ color: 'var(--text-faint, #8a96a3)' }}>.</span>
+            ) : null}
             <span style={{ color: site.brandAlt }}>{site.name.alt}</span>
           </span>
           {isCurrent ? (
@@ -134,7 +136,7 @@ export function SiteTile(props: SiteTileProps): ReactElement {
 // A tile lights up in the colour of the site it opens, never in ours: the
 // pointer moving down the grid is what makes the pairs of colours read.
 function tint(site: EcosystemSite, isCurrent: boolean, lit: boolean): string {
-  if (isCurrent) return '#f5f7fa';
+  if (isCurrent) return 'var(--surface-sunken, #f5f7fa)';
   return lit ? `color-mix(in oklab, ${site.brand} 9%, white)` : 'transparent';
 }
 
@@ -143,6 +145,6 @@ function borderOf(
   isCurrent: boolean,
   lit: boolean,
 ): string {
-  if (isCurrent) return '#dfe3e8';
+  if (isCurrent) return 'var(--border, #dfe3e8)';
   return lit ? `color-mix(in oklab, ${site.brand} 32%, white)` : 'transparent';
 }

package/src/ecosystem/ui/glyphs.tsx

@@ -16,6 +16,46 @@ import type { SiteId } from '../core/sites.ts';
 
 /** Every mark, keyed by site, drawn on top of its plate. */
 export const GLYPHS: Record<SiteId, (alt: string) => ReactNode> = {
+  // Six tiles standing where the six atoms of a benzene ring stand: the
+  // arrangement of tiles is the product and the ring is the subject.
+  learn: (alt) => (
+    <g>
+      <rect x="12.85" y="4.15" width="6.3" height="6.3" rx="1.9" fill={alt} />
+      <rect
+        x="20.39"
+        y="8.5"
+        width="6.3"
+        height="6.3"
+        rx="1.9"
+        fill="#ffffff"
+      />
+      <rect
+        x="20.39"
+        y="17.2"
+        width="6.3"
+        height="6.3"
+        rx="1.9"
+        fill="#ffffff"
+      />
+      <rect
+        x="12.85"
+        y="21.55"
+        width="6.3"
+        height="6.3"
+        rx="1.9"
+        fill="#ffffff"
+      />
+      <rect
+        x="5.31"
+        y="17.2"
+        width="6.3"
+        height="6.3"
+        rx="1.9"
+        fill="#ffffff"
+      />
+      <rect x="5.31" y="8.5" width="6.3" height="6.3" rx="1.9" fill="#ffffff" />
+    </g>
+  ),
   // A hexagon with a tail: the structure, and the string it hashes into.
   inchi: (alt) => (
     <g

package/src/orbital/core/index.ts

@@ -1,5 +1,8 @@
 export type { ResolutionLimits } from './atomicGrid.ts';
-export { atomicGridResolution } from './atomicGrid.ts';
+export {
+  atomicGridResolution,
+  createAtomicOrbitalEvaluator,
+} from './atomicGrid.ts';
 export type { AtomicOrbital, AtomicOrbitalOptions } from './atomicOrbitals.ts';
 export {
   atomicOrbitalsOf,

package/src/orbital/core/realHarmonics.ts

@@ -32,8 +32,11 @@ export interface RealHarmonic {
    * @param y - Offset from the nucleus along y, ångström.
    * @param z - Offset from the nucleus along z, ångström.
    * @param radius - Length of `(x, y, z)`, passed in because the caller has
-   * already computed it for the radial part.
-   * @returns The dimensionless amplitude; 0 at the nucleus for ℓ > 0.
+   * already computed it for the radial part. Never 0: a harmonic names a
+   * direction and the nucleus has none, so every ℓ > 0 divides by it. Build
+   * `ψ` with `createAtomicOrbitalEvaluator`, which answers that one point
+   * itself rather than paying for a branch on every sample.
+   * @returns The dimensionless amplitude.
    */
   evaluate: (x: number, y: number, z: number, radius: number) => number;
 }

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;
+    },
+  };
+}