react-cheminfo 0.18.0 → 0.20.0

package/src/about/ui/index.ts

@@ -1,5 +1,7 @@
 export type { AboutBuildProps } from './AboutBuild.tsx';
 export { AboutBuild } from './AboutBuild.tsx';
+export type { AboutVersionProps } from './AboutVersion.tsx';
+export { AboutVersion } from './AboutVersion.tsx';
 export type { AboutCitationsProps } from './AboutCitations.tsx';
 export { AboutCitations } from './AboutCitations.tsx';
 export type { AboutPageProps } from './AboutPage.tsx';

package/src/build/core/buildInfo.ts

@@ -25,6 +25,72 @@ export interface BuildInfo {
   reactCheminfo?: string;
 }
 
+/**
+ * The version a build reports when the repository has never been released.
+ *
+ * release-please writes the version into the root `package.json`, so a site
+ * whose first release has not happened yet is built from the `0.0.0` it was
+ * scaffolded with. That is not a version anybody can look up, so nothing shows
+ * it: a page saying `0.0.0` reads as a bug rather than as a release.
+ */
+export const UNRELEASED_VERSION = '0.0.0';
+
+/**
+ * The version to show a reader, if there is one.
+ * @param build - What the build published about itself, or `undefined`.
+ * @returns The released version, or `undefined` when the build published none
+ * or has never been released.
+ */
+export function releasedVersion(
+  build: BuildInfo | undefined,
+): string | undefined {
+  const version = build?.version;
+  if (version === undefined || version === UNRELEASED_VERSION) return undefined;
+  return version;
+}
+
+/**
+ * What the build is called on the page: the release when there is one, and the
+ * commit when there is not.
+ *
+ * A site that has never been released still has to be identifiable in a
+ * report, and `0.0.0` identifies nothing while the commit it was built from
+ * identifies exactly one build.
+ * @param build - What the build published about itself, or `undefined`.
+ * @returns The label, or `undefined` when the build published neither.
+ */
+export function buildLabel(build: BuildInfo | undefined): string | undefined {
+  const version = releasedVersion(build);
+  if (version !== undefined) return version;
+  const commit = build?.commit;
+  return commit === undefined ? undefined : shortCommit(commit);
+}
+
+/**
+ * When the build was made, as it is read on the badge: the day and the minute.
+ *
+ * A build a reader is asked to quote is worth little without a date, and two
+ * builds of the same day are told apart by the minute. The seconds are left to
+ * the hover, where the whole record is.
+ * @param builtAt - The ISO instant the build wrote.
+ * @returns The instant, in UTC, e.g. `2026-09-16 09:41 UTC`.
+ */
+export function buildStamp(builtAt: string): string {
+  return `${builtAt.slice(0, MINUTE_LENGTH).replace('T', ' ')} UTC`;
+}
+
+/**
+ * The whole record in one line, for the hover of a badge that shows one part
+ * of it.
+ * @param build - What the build published about itself.
+ * @returns e.g. `Built 2026-09-16 09:41:07 UTC from commit a1b2c3d`.
+ */
+export function buildSummary(build: BuildInfo): string {
+  const built = `Built ${formatBuiltAt(build.builtAt)}`;
+  if (build.commit === undefined) return built;
+  return `${built} from commit ${shortCommit(build.commit)}`;
+}
+
 /**
  * The commit as it is written for a reader.
  * @param commit - The full hash.
@@ -45,4 +111,5 @@ export function formatBuiltAt(builtAt: string): string {
 }
 
 const SHORT_COMMIT_LENGTH = 7;
+const MINUTE_LENGTH = 16;
 const SECOND_LENGTH = 19;

package/src/build/core/index.ts

@@ -1,2 +1,10 @@
 export type { BuildInfo } from './buildInfo.ts';
-export { formatBuiltAt, shortCommit } from './buildInfo.ts';
+export {
+  UNRELEASED_VERSION,
+  buildLabel,
+  buildStamp,
+  buildSummary,
+  formatBuiltAt,
+  releasedVersion,
+  shortCommit,
+} from './buildInfo.ts';

package/src/build/vite/buildInfo.ts

@@ -15,6 +15,7 @@ import { dirname, join, resolve } from 'node:path';
 import type { Plugin } from 'vite';
 
 import type { BuildInfo } from '../core/buildInfo.ts';
+import { UNRELEASED_VERSION } from '../core/buildInfo.ts';
 
 import { commitFromEnvironment, readGitHead } from './gitHead.ts';
 
@@ -92,7 +93,7 @@ export function resolveBuildInfo(root: string): BuildInfo {
   const repository = findRepositoryRoot(root);
 
   return {
-    version: readVersion(repository) ?? readVersion(root) ?? UNRELEASED,
+    version: readVersion(repository) ?? readVersion(root) ?? UNRELEASED_VERSION,
     builtAt: buildInstant(),
     commit: readGitHead(repository) ?? commitFromEnvironment(),
     reactCheminfo: readOwnVersion(),
@@ -174,5 +175,4 @@ function buildInstant(): string {
 
 const RESOLVED_MODULE = `\0${BUILD_INFO_MODULE}`;
 const OWN_NAME = 'react-cheminfo';
-const UNRELEASED = '0.0.0';
 const SECOND_LENGTH = 19;

package/src/ecosystem/core/sites.ts

@@ -62,6 +62,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     name: { lead: 'openbabel', alt: 'cheminfo', dot: true },
     host: 'openbabel.cheminfo.org',
     repository: 'https://github.com/cheminfo/openbabel.cheminfo.org',
+    publicRepository: true,
     tagline: 'Convert a structure between any pair of chemical file formats.',
     group: 'structures',
     brand: '#0f766e',
@@ -84,6 +85,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     name: { lead: 'dbe', alt: 'cheminfo', dot: true },
     host: 'dbe.cheminfo.org',
     repository: 'https://github.com/cheminfo/dbe.cheminfo.org',
+    publicRepository: true,
     tagline: 'Count rings and double bonds from a formula or a structure.',
     group: 'basics',
     brand: '#63123f',
@@ -97,6 +99,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     name: { lead: 'NMR', alt: 'ium' },
     host: 'www.nmrium.org',
     repository: 'https://github.com/cheminfo/nmrium',
+    publicRepository: true,
     tagline: 'Process and assign NMR spectra in the browser.',
     group: 'spectra',
     brand: '#ea580c',
@@ -133,6 +136,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     name: { lead: 'surge', alt: 'cheminfo', dot: true },
     host: 'surge.cheminfo.org',
     repository: 'https://github.com/cheminfo/surge.cheminfo.org',
+    publicRepository: true,
     tagline: 'Every constitutional isomer of a molecular formula.',
     group: 'structures',
     brand: '#4338ca',
@@ -144,6 +148,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     name: { lead: 'tex', alt: 'cheminfo', dot: true },
     host: 'tex.cheminfo.org',
     repository: 'https://github.com/cheminfo/tex.cheminfo.org',
+    publicRepository: true,
     tagline: 'LaTeX formulas rendered to SVG or PNG from a URL.',
     group: 'computing',
     brand: '#a21caf',
@@ -166,6 +171,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     name: { lead: 'regexp', alt: 'cheminfo', dot: true },
     host: 'regexp.cheminfo.org',
     repository: 'https://github.com/cheminfo/regexp.cheminfo.org',
+    publicRepository: true,
     tagline: 'Learn regular expressions in a live playground.',
     group: 'computing',
     brand: '#1e3a8a',
@@ -177,6 +183,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     name: { lead: 'pdb', alt: 'cheminfo', dot: true },
     host: 'pdb.cheminfo.org',
     repository: 'https://github.com/cheminfo/pdb.cheminfo.org',
+    publicRepository: true,
     tagline: 'A fast look at any Protein Data Bank entry.',
     group: 'research',
     brand: '#2563eb',
@@ -188,6 +195,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     name: { lead: 'elucidation', alt: 'cheminfo', dot: true },
     host: 'elucidation.cheminfo.org',
     repository: 'https://github.com/cheminfo/elucidation.cheminfo.org',
+    publicRepository: true,
     tagline: 'A structure from a 1H NMR spectrum and a formula.',
     group: 'spectra',
     brand: '#7e22ce',
@@ -210,6 +218,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     name: { lead: 'Poly', alt: 'Carp' },
     host: 'polycarp.cheminfo.org',
     repository: 'https://github.com/cheminfo/polycarp.cheminfo.org',
+    publicRepository: true,
     tagline: 'Predict the microstructure of a radical copolymerisation.',
     group: 'research',
     brand: '#701a75',
@@ -243,6 +252,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     name: { lead: 'database', alt: 'cheminfo', dot: true },
     host: 'database.cheminfo.org',
     repository: 'https://github.com/cheminfo/database.cheminfo.org',
+    publicRepository: true,
     tagline: 'Query a real chemical dataset in SQL and in Mango.',
     group: 'research',
     brand: '#7c2d12',
@@ -254,6 +264,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     name: { lead: 'Symme', alt: 'Try' },
     host: 'symmetry.cheminfo.org',
     repository: 'https://github.com/cheminfo/symmetry.cheminfo.org',
+    publicRepository: true,
     tagline: 'Find the symmetry of a molecule, a crystal or a pattern.',
     group: 'basics',
     brand: '#9f1239',
@@ -267,6 +278,7 @@ export const ECOSYSTEM_SITES: readonly EcosystemSite[] = [
     name: { lead: 'osiris', alt: 'cheminfo', dot: true },
     host: 'osiris.cheminfo.org',
     repository: 'https://github.com/cheminfo/osiris.cheminfo.org',
+    publicRepository: true,
     tagline: 'Predicted toxicity risks and properties, one molecule or many.',
     group: 'research',
     brand: '#854d0e',

package/src/ecosystem/core/types.ts

@@ -60,6 +60,14 @@ export interface EcosystemSite {
   host: string;
   /** Where the sources live, and what a Source link opens. */
   repository: string;
+  /**
+   * Whether a visitor can open that repository. A private one is named
+   * nowhere: no licence-and-source section, no link from the version, no issue
+   * tracker a reader cannot reach. It is stated rather than assumed, so a site
+   * whose record forgets it advertises nothing rather than a dead link.
+   * @default false
+   */
+  publicRepository?: boolean;
   /** One line on what the site does. */
   tagline: string;
   /**

package/src/molecule3d/core/camera.ts

@@ -0,0 +1,212 @@
+/**
+ * Where the camera stands, in a form a link can carry.
+ *
+ * A position in ångström would not survive the trip: the molecule a link names
+ * is built again on the other side, and a distance that frames a benzene leaves
+ * a peptide off screen. So the camera is stored against the scene rather than
+ * against the coordinates — a rotation from the front view, a zoom against the
+ * distance that frames the whole model, and a target as an offset from the
+ * scene centre in bounding-sphere radii. All three read the same whatever the
+ * molecule and whatever the size of the canvas showing it.
+ */
+
+import { clamp } from '../../format/core/clamp.ts';
+import { roundTo } from '../../format/core/roundTo.ts';
+// Deep import on purpose: the codec is the one way a link carries a camera, and
+// `share/core` knows nothing of molecules, so nothing is pulled in by it.
+import type { ShareParamCodec } from '../../share/core/params.ts';
+
+/** A rotation, as a unit quaternion `[x, y, z, w]`. */
+export type Molecule3DRotation = readonly [number, number, number, number];
+
+/** A point or a direction, `[x, y, z]`. */
+export type Molecule3DVector = readonly [number, number, number];
+
+/** Where the camera stands, against the scene rather than its coordinates. */
+export interface Molecule3DCamera {
+  /**
+   * Rotation of the camera from the front view — looking down -z with y up —
+   * as a unit quaternion.
+   */
+  rotation: Molecule3DRotation;
+  /**
+   * How close the camera is. `1` frames the whole model, as the reset button
+   * does; `2` is twice as close, so the model is drawn twice as large.
+   */
+  zoom: number;
+  /**
+   * Where the camera looks, as an offset from the centre of the model, in
+   * bounding-sphere radii. `[0, 0, 0]` looks at the centre.
+   */
+  offset: Molecule3DVector;
+}
+
+/** Looking at the centre of the model from the front, framing all of it. */
+export const DEFAULT_MOLECULE_3D_CAMERA: Molecule3DCamera = {
+  rotation: [0, 0, 0, 1],
+  zoom: 1,
+  offset: [0, 0, 0],
+};
+
+/** The closest and furthest a link may ask the camera to stand. */
+export const MOLECULE_3D_ZOOM_RANGE = { minimum: 0.01, maximum: 100 } as const;
+
+/** Furthest a link may push the target from the centre, in radii. */
+const MAX_OFFSET = 100;
+
+/** Decimals kept of a quaternion component: 0.0001 is under a hundredth of a degree. */
+const ROTATION_DECIMALS = 4;
+
+/** Decimals kept of the zoom and of the target offset. */
+const POSITION_DECIMALS = 3;
+
+/**
+ * Write a camera as the text a link carries.
+ *
+ * The four components of the rotation come first, then the zoom, then the
+ * target offset — which is left out entirely while the camera looks at the
+ * centre of the model, as it does until someone pans.
+ * @param camera - The camera to write.
+ * @returns Comma-separated numbers: five, or eight when the camera is panned.
+ */
+export function formatMolecule3DCamera(camera: Molecule3DCamera): string {
+  const { rotation, zoom, offset } = normalizeMolecule3DCamera(camera);
+  const parts: string[] = [];
+  for (let index = 0; index < 4; index++) {
+    parts.push(String(roundTo(rotation[index] ?? 0, ROTATION_DECIMALS)));
+  }
+  parts.push(String(roundTo(zoom, POSITION_DECIMALS)));
+  if (offset[0] !== 0 || offset[1] !== 0 || offset[2] !== 0) {
+    for (const value of offset) {
+      parts.push(String(roundTo(value, POSITION_DECIMALS)));
+    }
+  }
+  return parts.join(',');
+}
+
+/**
+ * Read a camera out of the text a link carries.
+ *
+ * A rotation that is not a rotation — four zeros, a stray word — is what makes
+ * the whole value unusable; everything else is brought back into range rather
+ * than rejected, so a link written against an older range still opens.
+ * @param raw - The text of the parameter.
+ * @returns The camera, or `null` when the text does not describe one.
+ */
+export function parseMolecule3DCamera(raw: string): Molecule3DCamera | null {
+  const parts = raw.split(',');
+  if (parts.length !== 5 && parts.length !== 8) return null;
+  const numbers: number[] = [];
+  for (const part of parts) {
+    const value = Number(part.trim());
+    if (!Number.isFinite(value)) return null;
+    numbers.push(value);
+  }
+  const rotation = normalizeRotation([
+    numbers[0] ?? 0,
+    numbers[1] ?? 0,
+    numbers[2] ?? 0,
+    numbers[3] ?? 1,
+  ]);
+  if (rotation === null) return null;
+  return {
+    rotation,
+    zoom: clampZoom(numbers[4] ?? 1),
+    offset: [
+      clampOffset(numbers[5] ?? 0),
+      clampOffset(numbers[6] ?? 0),
+      clampOffset(numbers[7] ?? 0),
+    ],
+  };
+}
+
+/**
+ * A camera with its rotation made a unit quaternion and its numbers in range.
+ * @param camera - The camera to repair.
+ * @returns A camera safe to hand the viewer; the default when the rotation is
+ * degenerate.
+ */
+export function normalizeMolecule3DCamera(
+  camera: Molecule3DCamera,
+): Molecule3DCamera {
+  const rotation = normalizeRotation(camera.rotation);
+  if (rotation === null) return DEFAULT_MOLECULE_3D_CAMERA;
+  return {
+    rotation,
+    zoom: clampZoom(camera.zoom),
+    offset: [
+      clampOffset(camera.offset[0]),
+      clampOffset(camera.offset[1]),
+      clampOffset(camera.offset[2]),
+    ],
+  };
+}
+
+/**
+ * Whether two cameras are the same once written into a link.
+ *
+ * What a link carries is rounded, so two cameras a drag apart by less than the
+ * rounding are one camera as far as the address is concerned — which is what
+ * keeps a settling animation from rewriting it a dozen times.
+ * @param first - One camera, or `null` for none.
+ * @param second - The other.
+ * @returns True when a link would carry the same text for both.
+ */
+export function sameMolecule3DCamera(
+  first: Molecule3DCamera | null,
+  second: Molecule3DCamera | null,
+): boolean {
+  if (first === null || second === null) return first === second;
+  return formatMolecule3DCamera(first) === formatMolecule3DCamera(second);
+}
+
+/**
+ * The codec a site mirrors the camera in the address with.
+ *
+ * The default framing is written as nothing at all, so the address of a page
+ * nobody has turned yet stays a plain link.
+ * @returns The codec, whose value is `null` while the camera is where a reset
+ * would leave it.
+ */
+export function molecule3DCameraParam(): ShareParamCodec<Molecule3DCamera | null> {
+  return {
+    parse(raw) {
+      return raw === null ? null : parseMolecule3DCamera(raw);
+    },
+    serialize(value) {
+      if (value === null) return null;
+      const text = formatMolecule3DCamera(value);
+      return text === formatMolecule3DCamera(DEFAULT_MOLECULE_3D_CAMERA)
+        ? null
+        : text;
+    },
+  };
+}
+
+function normalizeRotation(
+  rotation: Molecule3DRotation,
+): Molecule3DRotation | null {
+  let squared = 0;
+  for (let index = 0; index < 4; index++) {
+    const value = rotation[index] ?? 0;
+    if (!Number.isFinite(value)) return null;
+    squared += value * value;
+  }
+  if (squared <= 0) return null;
+  const scale = 1 / Math.sqrt(squared);
+  return [
+    rotation[0] * scale,
+    rotation[1] * scale,
+    rotation[2] * scale,
+    rotation[3] * scale,
+  ];
+}
+
+function clampZoom(zoom: number): number {
+  const { minimum, maximum } = MOLECULE_3D_ZOOM_RANGE;
+  return clamp(zoom, minimum, maximum, 1);
+}
+
+function clampOffset(value: number): number {
+  return clamp(value, -MAX_OFFSET, MAX_OFFSET, 0);
+}

package/src/molecule3d/core/index.ts

@@ -1,3 +1,17 @@
+export type {
+  Molecule3DCamera,
+  Molecule3DRotation,
+  Molecule3DVector,
+} from './camera.ts';
+export {
+  DEFAULT_MOLECULE_3D_CAMERA,
+  MOLECULE_3D_ZOOM_RANGE,
+  formatMolecule3DCamera,
+  molecule3DCameraParam,
+  normalizeMolecule3DCamera,
+  parseMolecule3DCamera,
+  sameMolecule3DCamera,
+} from './camera.ts';
 export type { ImageSize } from './exportImage.ts';
 export { dataUriBytes, rasterSvgMarkup } from './exportImage.ts';
 export type { Molecule3DGesture, Molecule3DGestureKey } from './gestures.ts';

package/src/molecule3d/ui/MoleculeCanvas3D.tsx

@@ -6,10 +6,9 @@
  */
 
 import type { CSSProperties, ReactElement } from 'react';
-import { useCallback, useEffect, useRef, useState } from 'react';
+import { useEffect, useRef, useState } from 'react';
 
 import type { Measurement, MeasurementKind } from '../core/measurement.ts';
-import type { Molecule3DFile } from '../core/settings.ts';
 import {
   normalizeMolecule3DSettings,
   resolveMolecule3DTools,
@@ -19,13 +18,13 @@ 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 { createMolecule3DViewer } from './createViewer.ts';
 import type { MoleculeViewer3DProps } from './moleculeViewer3DProps.ts';
 import { useControlledState } from './useControlledState.ts';
 import { useImageExport } from './useImageExport.ts';
+import { useMoleculeScene } from './useMoleculeScene.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<
@@ -84,11 +83,6 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
   // 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,
@@ -126,37 +120,6 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
     };
   }, [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 isNew =
-        molfile !== null &&
-        (framed?.molfile !== molfile || framed.viewer !== viewer);
-      framedRef.current = molfile === null ? null : { molfile, viewer };
-      const frameCamera = isNew ? frameNewMolecule : 'none';
-      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, frameNewMolecule, settings, measurements]);
-
   useEffect(() => {
     void viewerRef.current?.setSpin(spinning, spinSpeed);
   }, [container, spinning, spinSpeed]);
@@ -165,9 +128,17 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
     void viewerRef.current?.setMeasureKind(measureKind);
   }, [container, measureKind]);
 
-  const resetView = useCallback(() => {
-    void viewerRef.current?.resetCamera();
-  }, []);
+  const { resetView } = useMoleculeScene({
+    container,
+    viewerRef,
+    molfile,
+    frameNewMolecule,
+    settings,
+    measurements,
+    spinning,
+    onFailureChange,
+    camera: props,
+  });
 
   const { canvasSize, exportImage } = useImageExport(
     container,