react-cheminfo 0.39.0 → 0.40.0

package/src/molstar/core/plugin.ts

@@ -0,0 +1,159 @@
+/**
+ * Lifecycle of one headless molstar canvas: created now, disposed whenever,
+ * every call queued behind initialisation.
+ *
+ * The constructor is **synchronous** on purpose. React 19 runs an effect, its
+ * cleanup and the effect again on every mount in development, so an `await`ed
+ * constructor hands the cleanup nothing to dispose and leaks a WebGL context
+ * per mount — browsers drop the oldest after about sixteen, and the viewer
+ * silently goes blank. Returning the handle immediately means `dispose()` can
+ * always be called, even before initialisation has finished; the work is queued
+ * behind `ready`.
+ *
+ * molstar's own UI is never mounted: every control on our sites is ours.
+ */
+
+import { PluginViewModel } from 'molstar/lib/extensions/plugin/view-model.js';
+import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
+import type { PluginSpec } from 'molstar/lib/mol-plugin/spec.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';
+
+/** Settings fixed for the life of a plugin. */
+export interface MolstarPluginOptions {
+  /**
+   * Scene background, as `#rrggbb`. A WebGL clear colour, so it cannot be a CSS
+   * custom property.
+   * @default '#ffffff'
+   */
+  background?: string;
+  /**
+   * How long molstar animates a reframe it decided on itself; 0 jumps.
+   *
+   * Replacing a scene commits several times — the old drawing is deleted, the
+   * new one added — and molstar glides the camera on each, so the model appears
+   * to drift into place. Reframing is right; animating it between two unrelated
+   * scenes is not.
+   * @default molstar's own 250 ms
+   */
+  cameraResetDurationMilliseconds?: number;
+  /**
+   * The last word on the spec, applied over everything above: a site that needs
+   * a behaviour dropped, a marking colour or a renderer setting of its own
+   * passes it here rather than mounting its own view model.
+   */
+  spec?: (spec: PluginSpec) => PluginSpec;
+}
+
+/** One molstar canvas, and the queue everything drawn on it goes through. */
+export class MolstarPlugin {
+  readonly #model: PluginViewModel;
+  #disposed = false;
+
+  /** Resolves once the canvas exists; every call awaits it internally. */
+  readonly ready: Promise<void>;
+
+  /**
+   * Mount a canvas in `container` and start initialising it.
+   * @param container - An element with `position: relative`; molstar inserts
+   * its own canvas into it.
+   * @param options - See {@link MolstarPluginOptions}.
+   */
+  constructor(container: HTMLElement, options: MolstarPluginOptions = {}) {
+    const {
+      background = '#ffffff', // tokens-ok: a WebGL clear colour
+      cameraResetDurationMilliseconds,
+      spec: refine,
+    } = options;
+    const base = defaultPluginSpec();
+    const spec: PluginSpec = {
+      ...base,
+      canvas3d: {
+        ...base.canvas3d,
+        renderer: { backgroundColor: Color.fromHexStyle(background) },
+        // A scene is read from its own shape, never from the world axes.
+        camera: { helper: { axes: { name: 'off', params: {} } } },
+        ...(cameraResetDurationMilliseconds === undefined
+          ? {}
+          : { cameraResetDurationMs: cameraResetDurationMilliseconds }),
+      },
+    };
+    this.#model = new PluginViewModel({
+      spec: refine === undefined ? spec : refine(spec),
+    });
+    this.#model.mount(container);
+    this.ready = this.#model.initialized;
+  }
+
+  /** Whether {@link dispose} has been called. */
+  get disposed(): boolean {
+    return this.#disposed;
+  }
+
+  /**
+   * Wait for initialisation, then run `action` on the plugin.
+   * @param action - What to do with the molstar context.
+   * @returns What `action` returned, or `undefined` once the plugin has been
+   * disposed — before the call or while `action` was still running. An
+   * initialisation failure, and anything `action` throws while the plugin is
+   * alive, still reach the caller.
+   */
+  async 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) {
+      if (this.#disposed) return undefined;
+      throw error;
+    }
+  }
+
+  /**
+   * Start a subscription once the plugin exists.
+   * @param start - Subscribes, and returns its own unsubscribe function.
+   * @returns A function that stops the subscription, or stops it from ever
+   * starting; safe to call at any time.
+   */
+  subscribe(start: (plugin: PluginContext) => () => void): () => void {
+    let stop: (() => void) | null = null;
+    let cancelled = false;
+    void this.run((plugin) => {
+      if (cancelled) return;
+      stop = start(plugin);
+    });
+    return () => {
+      cancelled = true;
+      stop?.();
+      stop = null;
+    };
+  }
+
+  /** Re-read the container's size. Call from a `ResizeObserver`. */
+  handleResize(): void {
+    if (this.#disposed) return;
+    this.#model.plugin.handleResize();
+  }
+
+  /**
+   * Tear the canvas down and release its WebGL context. Idempotent, and safe to
+   * call before initialisation has finished.
+   */
+  dispose(): void {
+    if (this.#disposed) return;
+    this.#disposed = true;
+    // `mount` creates the canvas synchronously, so the context exists even when
+    // initialisation went on to fail; releasing it is what stops the browser
+    // dropping an older viewer's. A rejected `ready` must not escape here
+    // either — nobody is left to handle it.
+    void this.ready
+      .catch(() => undefined)
+      .then(() => {
+        this.#model.plugin.dispose();
+      });
+  }
+}

package/src/molstar.ts

@@ -0,0 +1,22 @@
+/**
+ * The molstar layer under the 3D views: the plugin lifecycle, the camera, the
+ * hover labels, the measurements and the picture of a scene.
+ *
+ * Three of our sites mount a headless molstar canvas — the molecule viewer
+ * here, lcao's orbitals and symmetry's crystals — and each of them had its own
+ * copy of the lifecycle, the spec and the spin. This is that one copy; what
+ * stays in a site is the scene it draws.
+ *
+ * **Importing this pulls molstar in statically.** A site that only wants
+ * `<MoleculeViewer3D>` imports `react-cheminfo/molecule3d`, whose canvas is
+ * lazy.
+ */
+
+export * from './molstar/core/index.ts';
+export { captureScene } from './molecule3d/ui/captureScene.ts';
+export type { MoleculeStructureSource } from './molecule3d/ui/measurements.ts';
+export {
+  atomReferenceOf,
+  clearMeasurements,
+  renderMeasurements,
+} from './molecule3d/ui/measurements.ts';

package/src/share/ui/SharePreview.tsx

@@ -22,6 +22,12 @@ import { SharePreviewDevices } from './SharePreviewDevices.tsx';
 /** Room the window's own bar takes, which the page is not scaled into. */
 const CHROME_HEIGHT = 26;
 
+/** How often the framed page is asked again while it has answered nothing. */
+const ASK_INTERVAL = 300;
+
+/** How many times, so a page with nothing to report is left alone. */
+const ASK_LIMIT = 10;
+
 export interface SharePreviewProps {
   /** The address the frame loads — the link as it stands. */
   url: string;
@@ -97,6 +103,31 @@ export function SharePreview(props: SharePreviewProps): ReactElement {
     mark.current?.scrollIntoView({ block: 'nearest', inline: 'nearest' });
   }, [highlight?.part]);
 
+  // The frame's own load says the document is there, never that the page it
+  // builds is listening: a React tree mounts in a task of its own, after it.
+  // So the question is repeated until it is answered — there is no event on
+  // this side to wait for, and a page that answers nothing is a page with no
+  // parts to point at, which costs ten messages and stops.
+  useEffect(() => {
+    if (regions.length > 0) return undefined;
+    let asked = 0;
+    const timer = setInterval(() => {
+      asked += 1;
+      if (asked > ASK_LIMIT) {
+        clearInterval(timer);
+        return;
+      }
+      frame.current?.contentWindow?.postMessage(
+        { type: SHARE_REGIONS_REQUEST },
+        '*',
+      );
+    }, ASK_INTERVAL);
+
+    return () => {
+      clearInterval(timer);
+    };
+  }, [regions, src]);
+
   return (
     <section className="share-preview" aria-label={t('share.preview')}>
       <header className="share-preview__header">

package/src/share/ui/useShareRegionReports.ts

@@ -33,25 +33,47 @@ export function useShareRegionReports(hidden: ReadonlySet<string>): boolean {
   useEffect(() => {
     if (!marking) return undefined;
     const host = globalThis.parent;
+    let scheduled = 0;
+    let reported = '';
 
     function report(): void {
-      host.postMessage(
-        { type: SHARE_REGIONS_MESSAGE, regions: measureRegions() },
-        '*',
-      );
+      scheduled = 0;
+      const regions = measureRegions();
+      // A page that is drawing — a structure, a result, a chart — mutates many
+      // times a second while its boxes stay where they are, and every message
+      // sent re-renders the dialog on the other side. Only a move is news.
+      const signature = JSON.stringify(regions);
+      if (signature === reported) return;
+      reported = signature;
+      host.postMessage({ type: SHARE_REGIONS_MESSAGE, regions }, '*');
+    }
+
+    // A search that returns, a structure that draws and a font that lands all
+    // move the boxes within a frame of each other, so the page is measured
+    // once after them rather than once per notification.
+    function schedule(): void {
+      if (scheduled === 0) scheduled = requestAnimationFrame(report);
     }
 
     // A chart, a web font or a structure drawn after mount all move the boxes,
-    // so the page is measured again whenever anything in it resizes rather
-    // than once, on a deadline it would lose.
-    const observer = new ResizeObserver(report);
-    observer.observe(document.documentElement);
-    globalThis.addEventListener('resize', report);
+    // so the page is measured again whenever anything in it changes rather
+    // than once, on a deadline it would lose. Watching its size is not enough:
+    // a page laid out to the height of the viewport keeps that height while a
+    // result appears inside a column of it, and the part nobody measured is
+    // the one the reader is pointing at.
+    const resizes = new ResizeObserver(schedule);
+    resizes.observe(document.documentElement);
+    resizes.observe(document.body);
+    const mutations = new MutationObserver(schedule);
+    mutations.observe(document.body, { childList: true, subtree: true });
+    globalThis.addEventListener('resize', schedule);
     report();
 
     return () => {
-      observer.disconnect();
-      globalThis.removeEventListener('resize', report);
+      if (scheduled !== 0) cancelAnimationFrame(scheduled);
+      resizes.disconnect();
+      mutations.disconnect();
+      globalThis.removeEventListener('resize', schedule);
     };
   }, [marking, hidden]);
 
@@ -71,12 +93,14 @@ function measureRegions(): ShareRegion[] {
     range.selectNodeContents(marker);
     const box = range.getBoundingClientRect();
     if (box.width === 0 || box.height === 0) continue;
+    // Rounded, so a layout that settles half a pixel to the left is not
+    // reported as a part that moved.
     regions.push({
       part,
-      x: box.x + globalThis.scrollX,
-      y: box.y + globalThis.scrollY,
-      width: box.width,
-      height: box.height,
+      x: Math.round(box.x + globalThis.scrollX),
+      y: Math.round(box.y + globalThis.scrollY),
+      width: Math.round(box.width),
+      height: Math.round(box.height),
     });
   }
 

package/src/structure/ui/ConformerTable.tsx

@@ -78,6 +78,14 @@ export interface ConformerTableProps {
    * @default undefined — every column keeps its own
    */
   columnLabels?: Partial<Record<ConformerColumn, string>>;
+  /**
+   * Whether the energies on screen are expected to be replaced — a force
+   * field's numbers while a better method is still working on the set. They
+   * are then drawn muted, so a reader can tell at a glance which of the two
+   * rankings they are looking at.
+   * @default false
+   */
+  provisional?: boolean;
 }
 
 /**
@@ -102,6 +110,7 @@ export function ConformerTable(
     label = 'Conformers, most stable first',
     rowName = String,
     columnLabels,
+    provisional = false,
   } = props;
 
   const bodyRef = useRef<HTMLTableSectionElement>(null);
@@ -208,7 +217,7 @@ export function ConformerTable(
                   <ClickToCopy
                     key={column}
                     as="td"
-                    style={cellStyle(column)}
+                    style={cellStyle(column, provisional)}
                     value={content}
                     label={COPY_LABELS[column]}
                     testId={CELL_TEST_IDS[column]}
@@ -218,7 +227,7 @@ export function ConformerTable(
                 ) : (
                   <td
                     key={column}
-                    style={cellStyle(column)}
+                    style={cellStyle(column, provisional)}
                     data-testid={CELL_TEST_IDS[column]}
                   >
                     {content}
@@ -360,8 +369,24 @@ function headerStyle(column: ConformerColumn): CSSProperties | undefined {
   return NUMERIC_CONFORMER_COLUMNS.has(column) ? numericStyle : undefined;
 }
 
-function cellStyle(column: ConformerColumn): CSSProperties | undefined {
-  return NUMERIC_CONFORMER_COLUMNS.has(column) ? numericStyle : undefined;
+/**
+ * A cell's own style: numbers are right-aligned and tabular, and every cell a
+ * better method will restate is muted while it works. The rank is not one of
+ * them — it names the row rather than measuring it, and it is what a reader
+ * follows as the order changes under them.
+ * @param column - The column the cell is in.
+ * @param provisional - Whether the energies are still expected to change.
+ * @returns The cell's inline style, or `undefined` when it needs none.
+ */
+function cellStyle(
+  column: ConformerColumn,
+  provisional: boolean,
+): CSSProperties | undefined {
+  const numeric = NUMERIC_CONFORMER_COLUMNS.has(column);
+  if (!provisional || column === 'id') {
+    return numeric ? numericStyle : undefined;
+  }
+  return numeric ? provisionalNumericStyle : provisionalStyle;
 }
 
 const tableStyle = { width: '100%' } as const satisfies CSSProperties;
@@ -371,6 +396,15 @@ const numericStyle = {
   fontVariantNumeric: 'tabular-nums',
 } as const satisfies CSSProperties;
 
+const provisionalStyle = {
+  color: 'var(--text-muted)',
+} as const satisfies CSSProperties;
+
+const provisionalNumericStyle = {
+  ...numericStyle,
+  ...provisionalStyle,
+} as const satisfies CSSProperties;
+
 /**
  * The selected row is tinted with the site's own accent, so the table belongs
  * to whichever site draws it; a row is a pointer only where a click does

package/lib/molecule3d/ui/viewerSpec.d.ts

@@ -1,17 +0,0 @@
-/**
- * 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';
-/**
- * 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 declare function mountMolecule3DPlugin(container: HTMLElement, background: string): PluginViewModel;
-//# sourceMappingURL=viewerSpec.d.ts.map

package/lib/molecule3d/ui/viewerSpec.d.ts.map

@@ -1 +0,0 @@
-{"version":3,"file":"viewerSpec.d.ts","sourceRoot":"","sources":["../../../src/molecule3d/ui/viewerSpec.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAC;AAK9E;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CACnC,SAAS,EAAE,WAAW,EACtB,UAAU,EAAE,MAAM,GACjB,eAAe,CAcjB"}

package/lib/molecule3d/ui/viewerSpec.js

@@ -1,34 +0,0 @@
-/**
- * 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, background) {
-    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;
-}
-//# sourceMappingURL=viewerSpec.js.map

package/lib/molecule3d/ui/viewerSpec.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"viewerSpec.js","sourceRoot":"","sources":["../../../src/molecule3d/ui/viewerSpec.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAC;AAC9E,4DAA4D;AAC5D,OAAO,EAAE,iBAAiB,IAAI,iBAAiB,EAAE,MAAM,gCAAgC,CAAC;AACxF,OAAO,EAAE,KAAK,EAAE,MAAM,qCAAqC,CAAC;AAE5D;;;;;;GAMG;AACH,MAAM,UAAU,qBAAqB,CACnC,SAAsB,EACtB,UAAkB;IAElB,MAAM,IAAI,GAAG,iBAAiB,EAAE,CAAC;IACjC,MAAM,KAAK,GAAG,IAAI,eAAe,CAAC;QAChC,IAAI,EAAE;YACJ,GAAG,IAAI;YACP,QAAQ,EAAE;gBACR,GAAG,IAAI,CAAC,QAAQ;gBAChB,QAAQ,EAAE,EAAE,eAAe,EAAE,KAAK,CAAC,YAAY,CAAC,UAAU,CAAC,EAAE;gBAC7D,MAAM,EAAE,EAAE,MAAM,EAAE,EAAE,IAAI,EAAE,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,EAAE,EAAE,EAAE,EAAE,EAAE;aAC1D;SACF;KACF,CAAC,CAAC;IACH,KAAK,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;IACvB,OAAO,KAAK,CAAC;AACf,CAAC"}

package/src/molecule3d/ui/viewerSpec.ts

@@ -1,38 +0,0 @@
-/**
- * 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;
-}