react-cheminfo 0.63.0 → 0.64.0

package/lib/molstar/core/highlights.js

@@ -0,0 +1,178 @@
+/**
+ * Atoms and bonds of the displayed molecule emphasised in one colour, for as
+ * long as a site keeps pointing at them.
+ *
+ * Neither of molstar's own markings fits: its hover highlight is erased by the
+ * next move of the pointer, and its selection belongs to the measuring tools.
+ * This is an overpaint of the model's own representation instead, so it
+ * follows the model in every style, survives the hover, and leaves the camera
+ * and every other drawing alone.
+ *
+ * molstar paints an atom and every half-bond leaving it from one element loci,
+ * which would tint the C–C bonds of a row that names only C–H ones. So the
+ * overpaint has three layers: the atoms, then those half-bonds cleared again,
+ * then exactly the bonds the paths name, as bond loci.
+ */
+import { OrderedSet, SortedArray } from 'molstar/lib/mol-data/int.js';
+import { Bond, StructureElement, Unit, } from 'molstar/lib/mol-model/structure.js';
+import { PluginStateObject } from 'molstar/lib/mol-plugin-state/objects.js';
+import { Overpaint } from 'molstar/lib/mol-theme/overpaint.js';
+import { highlightedParts, sameHighlights, } from "../../molecule3d/core/highlight.js";
+// Lowercased: they are factories, not constructors.
+const elementLoci = StructureElement.Loci;
+const bondLoci = Bond.Loci;
+const bondLocation = Bond.Location;
+/**
+ * The overpaint that emphasises `highlights` on a representation of
+ * `structure`: their atoms, and exactly the bonds between consecutive atoms of
+ * each path.
+ * @param structure - The structure the representation is drawn from.
+ * @param highlights - The paths; an atom the structure lacks is skipped.
+ * @param color - What they are painted in.
+ * @returns The overpaint, empty when no atom is left to paint.
+ */
+export function highlightOverpaint(structure, highlights, color) {
+    const { atoms, bonds } = highlightedParts(highlights, (atom) => unitOf(structure, atom) !== undefined);
+    if (atoms.length === 0)
+        return { kind: 'bond-loci', layers: [] };
+    const layers = [
+        { loci: atomsLoci(structure, atoms), color, clear: false },
+        { loci: leavingBondsLoci(structure, atoms), color, clear: true },
+    ];
+    if (bonds.length > 0) {
+        layers.push({ loci: pathBondsLoci(structure, bonds), color, clear: false });
+    }
+    // Not `element-loci`, which molstar would remap layer by layer as atoms, and
+    // a bond loci read as atoms is a crash.
+    return { kind: 'bond-loci', layers };
+}
+/**
+ * Keeps one representation of the state tree painted with the highlights a
+ * site asks for: the one there now, and every one built under the same ref
+ * afterwards, so a restyled model or a new conformer comes up already painted.
+ */
+export class HighlightPainter {
+    #plugin;
+    #ref;
+    #unsubscribe;
+    #highlights = [];
+    #color;
+    /**
+     * Start following the representation at `representationRef`.
+     * @param plugin - The molstar context.
+     * @param representationRef - State-tree ref of the representation to paint.
+     */
+    constructor(plugin, representationRef) {
+        this.#plugin = plugin;
+        this.#ref = representationRef;
+        const repaint = (event) => {
+            if (event.ref === this.#ref)
+                this.#paint(event.obj);
+        };
+        const { created, updated } = plugin.state.data.events.object;
+        const subscriptions = [
+            created.subscribe(repaint),
+            updated.subscribe(repaint),
+        ];
+        this.#unsubscribe = () => {
+            for (const subscription of subscriptions)
+                subscription.unsubscribe();
+        };
+    }
+    /**
+     * Paint exactly these highlights, in place of the ones painted.
+     * @param highlights - The paths; an empty list restores the plain model.
+     * @param color - What they are painted in.
+     */
+    set(highlights, color) {
+        if (color === this.#color && sameHighlights(highlights, this.#highlights)) {
+            return;
+        }
+        this.#highlights = highlights;
+        this.#color = color;
+        this.#paint(this.#plugin.state.data.cells.get(this.#ref)?.obj);
+    }
+    /** Stop following the representation. */
+    dispose() {
+        this.#unsubscribe();
+    }
+    #paint(object) {
+        if (!PluginStateObject.Molecule.Structure.Representation3D.is(object)) {
+            return;
+        }
+        const { repr, sourceData } = object.data;
+        const color = this.#color;
+        const overpaint = color === undefined
+            ? Overpaint.Empty
+            : highlightOverpaint(sourceData, this.#highlights, color);
+        if (Overpaint.isEmpty(overpaint) &&
+            Overpaint.isEmpty(repr.state.overpaint)) {
+            return;
+        }
+        repr.setState({ overpaint });
+        // No commit: the scene keeps its bounds, so the camera is never reframed.
+        this.#plugin.canvas3d?.update(repr, true);
+    }
+}
+function unitOf(structure, atom) {
+    const unit = structure.units[atom.unit];
+    if (unit === undefined || atom.element >= unit.elements.length) {
+        return undefined;
+    }
+    return unit;
+}
+function atomsLoci(structure, atoms) {
+    const elements = [];
+    for (let index = 0; index < structure.units.length; index++) {
+        const unit = structure.units[index];
+        const indices = [];
+        for (const atom of atoms) {
+            if (atom.unit === index)
+                indices.push(atom.element);
+        }
+        if (unit === undefined || indices.length === 0)
+            continue;
+        const sorted = SortedArray.ofUnsortedArray(indices);
+        elements.push({ unit, indices: OrderedSet.ofSortedArray(sorted) });
+    }
+    return elementLoci(structure, elements);
+}
+// Every half-bond leaving the atoms, which an element loci paints as well.
+function leavingBondsLoci(structure, atoms) {
+    const locations = [];
+    const iterator = new Bond.ElementBondIterator();
+    for (const atom of atoms) {
+        const unit = unitOf(structure, atom);
+        if (unit === undefined || !Unit.isAtomic(unit))
+            continue;
+        const index = atom.element;
+        iterator.setElement(structure, unit, index);
+        while (iterator.hasNext) {
+            const { otherUnit, otherIndex } = iterator.move();
+            locations.push(bondLocation(structure, unit, index, structure, otherUnit, otherIndex));
+        }
+    }
+    return bondLoci(structure, locations);
+}
+// molstar draws a bond as two halves, one from each atom.
+function pathBondsLoci(structure, bonds) {
+    const locations = [];
+    for (const [first, second] of bonds) {
+        const forward = halfBond(structure, first, second);
+        const backward = halfBond(structure, second, first);
+        if (forward !== undefined && backward !== undefined) {
+            locations.push(forward, backward);
+        }
+    }
+    return bondLoci(structure, locations);
+}
+function halfBond(structure, from, to) {
+    const fromUnit = unitOf(structure, from);
+    const toUnit = unitOf(structure, to);
+    if (fromUnit === undefined || toUnit === undefined)
+        return undefined;
+    const fromIndex = from.element;
+    const toIndex = to.element;
+    return bondLocation(structure, fromUnit, fromIndex, structure, toUnit, toIndex);
+}
+//# sourceMappingURL=highlights.js.map

package/lib/molstar/core/highlights.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"highlights.js","sourceRoot":"","sources":["../../../src/molstar/core/highlights.ts"],"names":[],"mappings":"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"}

package/lib/molstar/core/index.d.ts

@@ -1,6 +1,6 @@
 /**
  * The molstar layer under the 3D views: the plugin lifecycle, the camera, the
- * hover labels, the measurements and the picture of a scene.
+ * hover labels, the measurements, the highlights 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
@@ -17,6 +17,7 @@
 export type { CameraPose, CameraReference, PoseOptions } from './cameraPose.ts';
 export { cameraToPose, poseToCamera } from './cameraPose.ts';
 export { DEFAULT_CAMERA_DURATION, DEFAULT_SPIN_SPEED, FRAMING_MARGIN, MINIMUM_FRAMING_RADIUS, framedRadius, setSpin, } from './camera.ts';
+export { HighlightPainter, highlightOverpaint } from './highlights.ts';
 export { atomName, atomText, lociText, subscribeHover } from './hover.ts';
 export type { MolstarPluginOptions } from './plugin.ts';
 export { MolstarPlugin } from './plugin.ts';

package/lib/molstar/core/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/molstar/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,cAAc,EACd,sBAAsB,EACtB,YAAY,EACZ,OAAO,GACR,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC1E,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/molstar/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,YAAY,EAAE,UAAU,EAAE,eAAe,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAChF,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,cAAc,EACd,sBAAsB,EACtB,YAAY,EACZ,OAAO,GACR,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC1E,YAAY,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AACxD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,YAAY,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC;AACjE,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC"}

package/lib/molstar/core/index.js

@@ -1,6 +1,6 @@
 /**
  * The molstar layer under the 3D views: the plugin lifecycle, the camera, the
- * hover labels, the measurements and the picture of a scene.
+ * hover labels, the measurements, the highlights 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
@@ -16,6 +16,7 @@
  */
 export { cameraToPose, poseToCamera } from "./cameraPose.js";
 export { DEFAULT_CAMERA_DURATION, DEFAULT_SPIN_SPEED, FRAMING_MARGIN, MINIMUM_FRAMING_RADIUS, framedRadius, setSpin, } from "./camera.js";
+export { HighlightPainter, highlightOverpaint } from "./highlights.js";
 export { atomName, atomText, lociText, subscribeHover } from "./hover.js";
 export { MolstarPlugin } from "./plugin.js";
 export { captureScene } from "./captureScene.js";

package/lib/molstar/core/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/molstar/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,cAAc,EACd,sBAAsB,EACtB,YAAY,EACZ,OAAO,GACR,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE1E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/molstar/core/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,EACL,uBAAuB,EACvB,kBAAkB,EAClB,cAAc,EACd,sBAAsB,EACtB,YAAY,EACZ,OAAO,GACR,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE1E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAEjD,OAAO,EACL,iBAAiB,EACjB,eAAe,EACf,iBAAiB,EACjB,kBAAkB,GACnB,MAAM,mBAAmB,CAAC"}

package/lib/molstar/core/measurements.d.ts

@@ -10,7 +10,9 @@
  * measurement.
  */
 import type { ElementIndex, Structure } from 'molstar/lib/mol-model/structure.js';
+import { StructureElement } from 'molstar/lib/mol-model/structure.js';
 import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
+import type { StructureMeasurementManager } from 'molstar/lib/mol-plugin-state/manager/structure/measurement.js';
 import type { AtomReference, Measurement, MeasurementKind } from '../../molecule3d/core/measurement.ts';
 /**
  * Where the atoms a measurement addresses are found in the plugin's state.
@@ -28,6 +30,14 @@ export type MoleculeStructureSource = (plugin: PluginContext) => Structure | und
  * @returns Nothing; resolves once every label is on screen.
  */
 export declare function renderMeasurements(plugin: PluginContext, measurements: readonly Measurement[], structureOf: MoleculeStructureSource): Promise<void>;
+/**
+ * Add one measurement to the scene, its label in front of the atoms it names.
+ * @param manager - molstar's measurement manager.
+ * @param kind - What is measured.
+ * @param loci - Its atoms, in order; fewer than the kind needs adds nothing.
+ * @returns Nothing; resolves once the measurement is committed.
+ */
+export declare function addMeasurement(manager: Pick<StructureMeasurementManager, 'addDistance' | 'addAngle' | 'addDihedral'>, kind: MeasurementKind, loci: readonly StructureElement.Loci[]): Promise<void>;
 /**
  * Remove every measurement from the scene.
  * @param plugin - The molstar context.

package/lib/molstar/core/measurements.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"measurements.d.ts","sourceRoot":"","sources":["../../../src/molstar/core/measurements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACV,MAAM,oCAAoC,CAAC;AAE5C,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AAIvE,OAAO,KAAK,EACV,aAAa,EACb,WAAW,EACX,eAAe,EAChB,MAAM,sCAAsC,CAAC;AAM9C;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,CACpC,MAAM,EAAE,aAAa,KAClB,SAAS,GAAG,SAAS,CAAC;AAE3B;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,aAAa,EACrB,YAAY,EAAE,SAAS,WAAW,EAAE,EACpC,WAAW,EAAE,uBAAuB,GACnC,OAAO,CAAC,IAAI,CAAC,CAiBf;AAED;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ5E;AAED,2EAA2E;AAC3E,qBAAa,iBAAiB;;IAO5B;;;;;OAKG;gBAED,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,IAAI,EAC7C,WAAW,EAAE,uBAAuB;IAmBtC;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI;IAO3C,oCAAoC;IACpC,OAAO,IAAI,IAAI;CAqBhB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,YAAY,GACpB,aAAa,GAAG,SAAS,CAS3B"}
+{"version":3,"file":"measurements.d.ts","sourceRoot":"","sources":["../../../src/molstar/core/measurements.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAKH,OAAO,KAAK,EACV,YAAY,EACZ,SAAS,EACV,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AACtE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,mCAAmC,CAAC;AACvE,OAAO,KAAK,EAAE,2BAA2B,EAAE,MAAM,+DAA+D,CAAC;AAIjH,OAAO,KAAK,EACV,aAAa,EACb,WAAW,EACX,eAAe,EAChB,MAAM,sCAAsC,CAAC;AAM9C;;;;;GAKG;AACH,MAAM,MAAM,uBAAuB,GAAG,CACpC,MAAM,EAAE,aAAa,KAClB,SAAS,GAAG,SAAS,CAAC;AAE3B;;;;;;;GAOG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,aAAa,EACrB,YAAY,EAAE,SAAS,WAAW,EAAE,EACpC,WAAW,EAAE,uBAAuB,GACnC,OAAO,CAAC,IAAI,CAAC,CAaf;AAED;;;;;;GAMG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,IAAI,CACX,2BAA2B,EAC3B,aAAa,GAAG,UAAU,GAAG,aAAa,CAC3C,EACD,IAAI,EAAE,eAAe,EACrB,IAAI,EAAE,SAAS,gBAAgB,CAAC,IAAI,EAAE,GACrC,OAAO,CAAC,IAAI,CAAC,CASf;AAQD;;;;GAIG;AACH,wBAAsB,iBAAiB,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO,CAAC,IAAI,CAAC,CAQ5E;AAED,2EAA2E;AAC3E,qBAAa,iBAAiB;;IAO5B;;;;;OAKG;gBAED,MAAM,EAAE,aAAa,EACrB,SAAS,EAAE,CAAC,WAAW,EAAE,WAAW,KAAK,IAAI,EAC7C,WAAW,EAAE,uBAAuB;IAmBtC;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,eAAe,GAAG,IAAI,GAAG,IAAI;IAO3C,oCAAoC;IACpC,OAAO,IAAI,IAAI;CAqBhB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,SAAS,EACpB,OAAO,EAAE,YAAY,GACpB,aAAa,GAAG,SAAS,CAS3B"}

package/lib/molstar/core/measurements.js

@@ -31,20 +31,34 @@ export async function renderMeasurements(plugin, measurements, structureOf) {
         return;
     const manager = plugin.managers.structure.measurement;
     for (const measurement of measurements) {
-        const [a, b, c, d] = atomLoci(structure, measurement.atoms);
-        /* eslint-disable no-await-in-loop -- each add commits to the state tree, and commits must not interleave */
-        if (measurement.kind === 'distance' && a && b) {
-            await manager.addDistance(a, b);
-        }
-        else if (measurement.kind === 'angle' && a && b && c) {
-            await manager.addAngle(a, b, c);
-        }
-        else if (measurement.kind === 'dihedral' && a && b && c && d) {
-            await manager.addDihedral(a, b, c, d);
-        }
-        /* eslint-enable no-await-in-loop */
+        // eslint-disable-next-line no-await-in-loop -- each add commits to the state tree, and commits must not interleave
+        await addMeasurement(manager, measurement.kind, atomLoci(structure, measurement.atoms));
     }
 }
+/**
+ * Add one measurement to the scene, its label in front of the atoms it names.
+ * @param manager - molstar's measurement manager.
+ * @param kind - What is measured.
+ * @param loci - Its atoms, in order; fewer than the kind needs adds nothing.
+ * @returns Nothing; resolves once the measurement is committed.
+ */
+export async function addMeasurement(manager, kind, loci) {
+    const [a, b, c, d] = loci;
+    if (kind === 'distance' && a && b) {
+        await manager.addDistance(a, b, MEASUREMENT_LABEL);
+    }
+    else if (kind === 'angle' && a && b && c) {
+        await manager.addAngle(a, b, c, MEASUREMENT_LABEL);
+    }
+    else if (kind === 'dihedral' && a && b && c && d) {
+        await manager.addDihedral(a, b, c, d, MEASUREMENT_LABEL);
+    }
+}
+/**
+ * A label drawn at the depth of its atoms hides half behind them: it is drawn
+ * in front of them, as molstar's own order labels are.
+ */
+const MEASUREMENT_LABEL = { labelParams: { offsetZ: 0.75 } };
 /**
  * Remove every measurement from the scene.
  * @param plugin - The molstar context.

package/lib/molstar/core/measurements.js.map

@@ -1 +1 @@
-{"version":3,"file":"measurements.js","sourceRoot":"","sources":["../../../src/molstar/core/measurements.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"measurements.js","sourceRoot":"","sources":["../../../src/molstar/core/measurements.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-cheminfo",
-  "version": "0.63.0",
+  "version": "0.64.0",
   "license": "MIT",
   "description": "React components, hooks and framework-free helpers shared by the cheminfo sites: site chrome, citations, sharing, routing, pedagogy, charts, and the structure, orbital and 3D molecule viewers",
   "author": "Luc Patiny",

package/src/molecule3d/core/highlight.ts

@@ -0,0 +1,133 @@
+/**
+ * What a highlight on a 3D molecule is, without React and without molstar: a
+ * bonded path of atoms a site points at — the two atoms of a bond, the three of
+ * an angle, the four of a dihedral — for the model to emphasise.
+ *
+ * Atoms are named by position, as measurements name them, so a row of a table
+ * read off one conformer lands on the same atoms of every other conformer of
+ * the same molecule.
+ */
+
+import type { AtomReference } from './measurement.ts';
+
+/** One bonded path of atoms to emphasise on the model. */
+export interface Molecule3DHighlight {
+  /**
+   * The atoms in the order they are bonded: two for a bond, three for the two
+   * bonds of an angle, four for the three bonds of a dihedral. One atom
+   * emphasises that atom alone.
+   */
+  atoms: readonly AtomReference[];
+}
+
+/** Two consecutive atoms of a path: the bond a highlight emphasises. */
+export type HighlightedBond = readonly [AtomReference, AtomReference];
+
+/** Everything a list of highlights emphasises, each atom and bond once. */
+export interface HighlightedParts {
+  /** Every atom of every path, in the order the paths first name them. */
+  atoms: readonly AtomReference[];
+  /** Every pair of consecutive atoms, in the order the paths first name them. */
+  bonds: readonly HighlightedBond[];
+}
+
+/**
+ * The atoms and the bonds a list of highlights emphasises.
+ *
+ * A bond is a pair of consecutive atoms of one path, and nothing else: two
+ * atoms that are both highlighted, but by different paths or not next to each
+ * other in one, are not a bond of the highlight — so six C–H paths never
+ * emphasise the C–C bond between two of their carbons. An atom the structure
+ * lacks is left out, with the two pairs it stands in; the atoms on either side
+ * of it are not joined in its place.
+ * @param highlights - The paths, as a site passes them.
+ * @param hasAtom - Whether the structure on screen has an atom; asked only of
+ * references whose two numbers are whole and not negative.
+ * @default () => true
+ * @returns The atoms and the bonds, each once, in the order first named.
+ */
+export function highlightedParts(
+  highlights: readonly Molecule3DHighlight[],
+  hasAtom: (atom: AtomReference) => boolean = isAnyAtom,
+): HighlightedParts {
+  const atoms: AtomReference[] = [];
+  const bonds: HighlightedBond[] = [];
+  const atomKeys = new Set<string>();
+  const bondKeys = new Set<string>();
+  for (const highlight of highlights) {
+    let previous: AtomReference | undefined;
+    for (const atom of highlight.atoms) {
+      const present = isAtomReference(atom) && hasAtom(atom);
+      if (present && !atomKeys.has(atomKey(atom))) {
+        atomKeys.add(atomKey(atom));
+        atoms.push({ unit: atom.unit, element: atom.element });
+      }
+      if (present && previous !== undefined) {
+        const key = bondKey(previous, atom);
+        if (key !== null && !bondKeys.has(key)) {
+          bondKeys.add(key);
+          bonds.push([
+            { unit: previous.unit, element: previous.element },
+            { unit: atom.unit, element: atom.element },
+          ]);
+        }
+      }
+      previous = present ? atom : undefined;
+    }
+  }
+  return { atoms, bonds };
+}
+
+/**
+ * Whether two lists of highlights name the same atoms, in the same paths and
+ * the same order — what decides that the model needs no repainting.
+ * @param first - One list.
+ * @param second - The other.
+ * @returns True when every path of one is the path of the other at its place.
+ */
+export function sameHighlights(
+  first: readonly Molecule3DHighlight[],
+  second: readonly Molecule3DHighlight[],
+): boolean {
+  if (first === second) return true;
+  if (first.length !== second.length) return false;
+  for (let index = 0; index < first.length; index++) {
+    const one = first[index]?.atoms;
+    const other = second[index]?.atoms;
+    if (one === undefined || other === undefined) return false;
+    if (one.length !== other.length) return false;
+    for (let position = 0; position < one.length; position++) {
+      const atom = one[position];
+      const match = other[position];
+      if (atom?.unit !== match?.unit || atom?.element !== match?.element) {
+        return false;
+      }
+    }
+  }
+  return true;
+}
+
+function isAnyAtom(): boolean {
+  return true;
+}
+
+function isAtomReference(atom: AtomReference): boolean {
+  return (
+    Number.isInteger(atom.unit) &&
+    atom.unit >= 0 &&
+    Number.isInteger(atom.element) &&
+    atom.element >= 0
+  );
+}
+
+function atomKey(atom: AtomReference): string {
+  return `${atom.unit}:${atom.element}`;
+}
+
+// One key for a pair whichever way round, and none for an atom with itself.
+function bondKey(first: AtomReference, second: AtomReference): string | null {
+  const one = atomKey(first);
+  const other = atomKey(second);
+  if (one === other) return null;
+  return one < other ? `${one}-${other}` : `${other}-${one}`;
+}

package/src/molecule3d/core/index.ts

@@ -16,6 +16,12 @@ export type { ImageSize } from './exportImage.ts';
 export { dataUriBytes, rasterSvgMarkup } from './exportImage.ts';
 export type { Molecule3DGesture, Molecule3DGestureKey } from './gestures.ts';
 export { MOLECULE_3D_GESTURES } from './gestures.ts';
+export type {
+  HighlightedBond,
+  HighlightedParts,
+  Molecule3DHighlight,
+} from './highlight.ts';
+export { highlightedParts, sameHighlights } from './highlight.ts';
 export type {
   AtomReference,
   Measurement,

package/src/molecule3d/ui/MoleculeCanvas3D.tsx

@@ -10,6 +10,7 @@ import type { CSSProperties, ReactElement } from 'react';
 import { useEffect, useRef, useState } from 'react';
 
 import { DEFAULT_SPIN_SPEED } from '../../molstar/core/index.ts';
+import type { Molecule3DHighlight } from '../core/highlight.ts';
 import type { Measurement, MeasurementKind } from '../core/measurement.ts';
 import {
   normalizeMolecule3DSettings,
@@ -21,6 +22,7 @@ import { Molecule3DOptions } from './Molecule3DOptions.tsx';
 import { Molecule3DStage } from './Molecule3DStage.tsx';
 import { Molecule3DToolbar } from './Molecule3DToolbar.tsx';
 import { createMolecule3DViewer } from './createViewer.ts';
+import { highlightColorOf } from './highlightColor.ts';
 import type { MoleculeViewer3DProps } from './moleculeViewer3DProps.ts';
 import { useControlledState } from './useControlledState.ts';
 import { useImageExport } from './useImageExport.ts';
@@ -56,6 +58,7 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
     spinSpeed = DEFAULT_SPIN_SPEED,
     measurements: measurementsProp,
     onMeasurementsChange,
+    highlights = NO_HIGHLIGHTS,
     fileName = 'molecule',
     background,
     minHeight = 320,
@@ -133,6 +136,14 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
     void viewerRef.current?.setMeasureKind(measureKind);
   }, [container, measureKind]);
 
+  // Kept out of the scene: a new highlight repaints the model, never redraws it.
+  useEffect(() => {
+    void viewerRef.current?.setHighlights(
+      highlights,
+      highlightColorOf(container),
+    );
+  }, [container, highlights]);
+
   const { resetView } = useMoleculeScene({
     container,
     viewerRef,
@@ -204,6 +215,8 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
 
 const NO_MEASUREMENTS: readonly Measurement[] = [];
 
+const NO_HIGHLIGHTS: readonly Molecule3DHighlight[] = [];
+
 const STAGE_STYLE: CSSProperties = {
   position: 'relative',
   flex: '1 0 auto',

package/src/molecule3d/ui/highlightColor.ts

@@ -0,0 +1,34 @@
+/**
+ * The colour the 3D view emphasises in, read off the page it sits on.
+ *
+ * A WebGL colour cannot be a custom property, and the family's accent is the
+ * one colour a site owns, so it cannot be written into a shared library either:
+ * the view asks the browser what `--accent` resolved to where it is drawn, as
+ * the parallel coordinates do, and hands molstar the answer.
+ */
+
+import { normalizeColor } from '../../tokens/core/colors.ts';
+import { FAMILY_TOKEN_VALUES } from '../../tokens/core/familyTokens.ts';
+
+/**
+ * What `--accent` resolved to on an element of the view.
+ * @param element - An element of the view, once it is on the page, or `null`
+ * before it is.
+ * @returns The accent as `#rrggbb`. A site that declares none emphasises in its
+ * text colour, and a page that declares neither, or no page yet, in the
+ * family's.
+ */
+export function highlightColorOf(element: Element | null): string {
+  return (
+    tokenColor(element, '--accent') ??
+    tokenColor(element, '--text') ??
+    FAMILY_TOKEN_VALUES['--text']
+  );
+}
+
+function tokenColor(element: Element | null, name: string): string | undefined {
+  const resolve = globalThis.getComputedStyle;
+  if (element === null || typeof resolve !== 'function') return undefined;
+  const color = normalizeColor(resolve(element).getPropertyValue(name));
+  return color === null ? undefined : `#${color}`;
+}

package/src/molecule3d/ui/moleculeViewer3DProps.ts

@@ -2,6 +2,7 @@ import type { ReactNode } from 'react';
 
 import type { ViewerCapability } from '../../orbital/ui/capability.ts';
 import type { Molecule3DCamera } from '../core/camera.ts';
+import type { Molecule3DHighlight } from '../core/highlight.ts';
 import type { Measurement } from '../core/measurement.ts';
 import type {
   Molecule3DFile,
@@ -80,6 +81,18 @@ export interface MoleculeViewer3DProps {
    * @default undefined
    */
   onMeasurementsChange?: (measurements: readonly Measurement[]) => void;
+  /**
+   * The parts of the model to emphasise in the site's accent colour, each a
+   * bonded path of atoms named as measurements name them: two atoms are that
+   * bond, three the two bonds of an angle, four the three bonds of a dihedral,
+   * and one atom is that atom alone. Only the bonds between consecutive atoms
+   * of one path are emphasised, never another bond between two highlighted
+   * atoms, and an atom the structure lacks is skipped. Changing them repaints
+   * the model and nothing else: the camera, the measurements and the hover are
+   * left as they are.
+   * @default [] — nothing is emphasised
+   */
+  highlights?: readonly Molecule3DHighlight[];
   /**
    * Where the camera stands when the first molecule is framed — what a shared
    * link carries. The camera belongs to whoever is dragging it afterwards, so

package/src/molecule3d/ui/renderMolecule.ts

@@ -26,7 +26,7 @@ export const MOLECULE_STRUCTURE_REF = 'molecule3d-structure';
 const MOLECULE_DATA_REF = 'molecule3d-data';
 
 /** The drawn model, replaced in place whenever the style changes. */
-const MODEL_REPRESENTATION_REF = 'molecule3d-model';
+export const MODEL_REPRESENTATION_REF = 'molecule3d-model';
 
 /**
  * molstar's ball-and-stick radius factor that a size factor of 1 stands for: