react-cheminfo 0.8.0 → 0.10.0

package/src/orbital/ui/camera.ts

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

package/src/orbital/ui/renderVolume.ts

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

package/src/orbital/ui/serial.ts

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

package/src/orbital/ui/viewer.ts

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

package/src/overlay/core/emptiestCorner.ts

@@ -0,0 +1,122 @@
+import type { OverlayCorner } from './overlayPlacement.ts';
+
+/** What {@link emptiestCorner} has to know about the figure. */
+export interface EmptiestCornerOptions {
+  /** Width of the plot, in pixels. */
+  width: number;
+  /** Height of the plot, in pixels. */
+  height: number;
+  /**
+   * Width the card is expected to take. It is an estimate on purpose: the card
+   * has not been laid out when the corner is chosen.
+   * @default 210
+   */
+  cardWidth?: number;
+  /**
+   * Height the card is expected to take.
+   * @default 76
+   */
+  cardHeight?: number;
+  /**
+   * The corner kept when two are equally empty, which is the common case on a
+   * sparse plot. Keeping a preference is what stops the card hopping between
+   * corners as one point is added.
+   * @default 'top-right'
+   */
+  preferred?: OverlayCorner;
+}
+
+/**
+ * The corner of a plot with the fewest marks under it.
+ *
+ * A card in a fixed corner eventually sits on the one cluster the reader came
+ * for. Counting first costs four comparisons per point, once per relayout, and
+ * it is the difference between chrome and an obstruction.
+ *
+ * Ties are settled by a fixed order so the answer never depends on which mark
+ * was read first: the preferred corner, then the one diagonally across from it,
+ * then the remaining two clockwise from the top left. The diagonal comes second
+ * because the preferred corner only loses when it holds marks, and the far side
+ * of the plot is the least likely place for the rest of that same cluster.
+ * @param x - Horizontal position of every mark, in pixels from the plot's left.
+ * @param y - Vertical position of every mark, in pixels from the plot's top.
+ * @param options - See {@link EmptiestCornerOptions}.
+ * @returns The emptiest corner; the preferred one when several tie. An empty
+ * plot, or one whose size has not been measured, is entirely empty and so
+ * returns the preferred corner too.
+ */
+export function emptiestCorner(
+  x: ArrayLike<number>,
+  y: ArrayLike<number>,
+  options: EmptiestCornerOptions,
+): OverlayCorner {
+  const {
+    width,
+    height,
+    cardWidth = DEFAULT_CARD_WIDTH,
+    cardHeight = DEFAULT_CARD_HEIGHT,
+    preferred = 'top-right',
+  } = options;
+
+  const leftEdge = cardWidth;
+  const rightEdge = width - cardWidth;
+  const topEdge = cardHeight;
+  const bottomEdge = height - cardHeight;
+
+  const counts: Record<OverlayCorner, number> = {
+    'top-left': 0,
+    'top-right': 0,
+    'bottom-left': 0,
+    'bottom-right': 0,
+  };
+
+  const total = Math.min(x.length, y.length);
+  for (let index = 0; index < total; index++) {
+    const pointX = x[index];
+    const pointY = y[index];
+    if (pointX === undefined || pointY === undefined) continue;
+    const inLeft = pointX <= leftEdge;
+    const inRight = pointX >= rightEdge;
+    const inTop = pointY <= topEdge;
+    const inBottom = pointY >= bottomEdge;
+    if (inTop && inLeft) counts['top-left']++;
+    if (inTop && inRight) counts['top-right']++;
+    if (inBottom && inLeft) counts['bottom-left']++;
+    if (inBottom && inRight) counts['bottom-right']++;
+  }
+
+  let best = preferred;
+  let fewest = counts[preferred];
+  for (const corner of tieOrder(preferred)) {
+    if (counts[corner] >= fewest) continue;
+    best = corner;
+    fewest = counts[corner];
+  }
+  return best;
+}
+
+const DEFAULT_CARD_WIDTH = 210;
+const DEFAULT_CARD_HEIGHT = 76;
+
+const CORNERS: readonly OverlayCorner[] = [
+  'top-left',
+  'top-right',
+  'bottom-right',
+  'bottom-left',
+];
+
+const OPPOSITE: Record<OverlayCorner, OverlayCorner> = {
+  'top-left': 'bottom-right',
+  'top-right': 'bottom-left',
+  'bottom-left': 'top-right',
+  'bottom-right': 'top-left',
+};
+
+function tieOrder(preferred: OverlayCorner): OverlayCorner[] {
+  const opposite = OPPOSITE[preferred];
+  const order: OverlayCorner[] = [opposite];
+  for (const corner of CORNERS) {
+    if (corner !== preferred && corner !== opposite) order.push(corner);
+  }
+  return order;
+}

package/src/overlay/core/index.ts

@@ -0,0 +1,34 @@
+/**
+ * Where a floating control sits over a figure, and how big it is.
+ *
+ * The geometry lives apart from the components that use it so it can be
+ * reasoned about and tested without a browser: which corner of a scatter is
+ * emptiest, whether a panel has room for a labelled strip or only a gear, and
+ * where a card must flip so it stays on screen.
+ */
+
+export type { EmptiestCornerOptions } from './emptiestCorner.ts';
+export { emptiestCorner } from './emptiestCorner.ts';
+export { shouldCollapseOverlay } from './overlayCollapse.ts';
+export type { OverlayMarkShape } from './overlayMarks.ts';
+export { OVERLAY_MARK_SHAPES, isFilledMark } from './overlayMarks.ts';
+export type {
+  OverlayDensity,
+  OverlayMetrics,
+  OverlayPointerKind,
+} from './overlayMetrics.ts';
+export { overlayMetrics } from './overlayMetrics.ts';
+export type {
+  OverlayCorner,
+  OverlayCornerStyle,
+  OverlayPlacement,
+} from './overlayPlacement.ts';
+export { overlayCornerStyle } from './overlayPlacement.ts';
+export type { OverlayTierRoom, OverlayTierSetting } from './overlayTierRoom.ts';
+export type { OverlayTier, OverlayTierWidths } from './overlayTiers.ts';
+export { overlayTier, overlayTierWidths } from './overlayTiers.ts';
+export type {
+  OverlayCardPlacement,
+  OverlayCardPlacementOptions,
+} from './placeOverlayCard.ts';
+export { placeOverlayCard } from './placeOverlayCard.ts';

package/src/overlay/core/overlayCollapse.ts

@@ -0,0 +1,20 @@
+/**
+ * Whether a floating card folds into a single button at this figure width.
+ *
+ * A width of zero — which is what a figure reports before it has been measured,
+ * and what a server render always reports — keeps the card expanded, so the
+ * string-rendering tests and the first paint both see the real controls. A
+ * threshold that is not a real number is read the same way, so a missing
+ * breakpoint never silently hides every control on the figure.
+ * @param width - Width of the figure, in pixels.
+ * @param collapseBelow - The width under which the card folds.
+ * @returns Whether it folds.
+ */
+export function shouldCollapseOverlay(
+  width: number,
+  collapseBelow: number,
+): boolean {
+  if (!Number.isFinite(width) || width <= 0) return false;
+  if (!Number.isFinite(collapseBelow)) return false;
+  return width < collapseBelow;
+}

package/src/overlay/core/overlayMarks.ts

@@ -0,0 +1,43 @@
+/**
+ * The marks a legend entry, a reference point or a series can be drawn with.
+ *
+ * It lives in the framework-free half although only a component ever draws
+ * one, because the data that names a mark is written far from the drawing: a
+ * k-means centroid says it is a cross while it is still a plain object, long
+ * before any of it reaches React. Keeping the union here is what lets a result
+ * describe its own marks without a `core` module reaching into a `ui` one.
+ */
+
+/** Which mark a legend entry, a marker or a series stands for. */
+export type OverlayMarkShape =
+  'dot' | 'ring' | 'square' | 'line' | 'dashed' | 'cross';
+
+/**
+ * Every mark, in the order a picker offers them.
+ *
+ * The first three separate one filled thing from another by colour alone; the
+ * last three carry a second meaning on one figure — a line for a component
+ * beside dots for the samples — which is what keeps a figure readable when the
+ * colours run out or the reader does not separate two of them.
+ */
+export const OVERLAY_MARK_SHAPES: readonly OverlayMarkShape[] = [
+  'dot',
+  'ring',
+  'square',
+  'line',
+  'dashed',
+  'cross',
+];
+
+/**
+ * Whether a mark is drawn as a solid area rather than as a stroke.
+ *
+ * A solid mark takes its colour as a fill and a stroked one as a stroke, which
+ * is the one thing every renderer of a mark has to know and the one thing that
+ * is easy to get wrong in each of them separately.
+ * @param shape - The mark.
+ * @returns `true` for the filled marks, `false` for the drawn ones.
+ */
+export function isFilledMark(shape: OverlayMarkShape): boolean {
+  return shape === 'dot' || shape === 'square';
+}

package/src/overlay/core/overlayMetrics.ts

@@ -0,0 +1,112 @@
+/** How tightly a floating card packs its controls. */
+export type OverlayDensity = 'compact' | 'comfortable';
+
+/**
+ * What kind of pointer the reader has.
+ *
+ * A finger cannot hover and cannot aim at a twenty-four pixel target, so a
+ * coarse pointer overrides the density outright rather than nudging it.
+ */
+export type OverlayPointerKind = 'fine' | 'coarse';
+
+/** Every measurement a floating card and its controls are drawn from. */
+export interface OverlayMetrics {
+  /** Height of a control, in pixels. */
+  controlHeight: number;
+  /** Space between two controls, and between a caption and its control. */
+  gap: number;
+  /** Space inside the card, left and right. */
+  paddingX: number;
+  /** Space inside the card, top and bottom. */
+  paddingY: number;
+  /** Size of the text a control says. */
+  fontSize: number;
+  /** Size of the caption in front of a control. */
+  labelSize: number;
+  /** Corner radius of a control; the card itself uses `--radius`. */
+  controlRadius: number;
+  /** Space kept between the card and the edge of the figure. */
+  inset: number;
+  /** Side of the square button the card collapses to. */
+  buttonSize: number;
+  /** The size Blueprint's own controls are asked for. */
+  blueprintSize: 'small' | 'medium' | 'large';
+}
+
+/**
+ * The measurements a card is drawn from.
+ * @param density - How tightly the caller asked for the controls to be packed.
+ * @param pointer - What the reader is pointing with. Defaults to `'fine'`.
+ * @returns The measurements. A coarse pointer always gets the largest set,
+ * whatever the density says.
+ */
+export function overlayMetrics(
+  density: OverlayDensity,
+  pointer: OverlayPointerKind = 'fine',
+): OverlayMetrics {
+  if (pointer === 'coarse') return COARSE_METRICS;
+  return density === 'compact' ? COMPACT_METRICS : COMFORTABLE_METRICS;
+}
+
+/**
+ * The set a figure embedded in somebody else's page is drawn from.
+ *
+ * A figure that is a guest on a page it does not own has to spend as little of
+ * that page as it can, so every measurement here is the smallest one that is
+ * still honest. The control stays at twenty-four pixels — the floor a mouse
+ * can be aimed at, and the reason nothing below it is offered at all — while
+ * the room around it goes: a four pixel gap, a three pixel band above and
+ * below, and a six pixel inset from the figure's edge. A bar built from these
+ * stands thirty pixels tall, which is one line of the host's own text.
+ *
+ * The type steps down a size with it. Eleven pixels is what a control says and
+ * ten is what its caption says, because the caption is read once to find the
+ * control and the control's own words are read every time it is used.
+ */
+const COMPACT_METRICS: OverlayMetrics = {
+  controlHeight: 24,
+  gap: 4,
+  paddingX: 6,
+  paddingY: 3,
+  fontSize: 11,
+  labelSize: 10,
+  controlRadius: 5,
+  inset: 6,
+  buttonSize: 24,
+  blueprintSize: 'small',
+};
+
+/** The everyday set: room to read the captions without crowding the figure. */
+const COMFORTABLE_METRICS: OverlayMetrics = {
+  controlHeight: 30,
+  gap: 8,
+  paddingX: 8,
+  paddingY: 6,
+  fontSize: 12,
+  labelSize: 11,
+  controlRadius: 6,
+  inset: 8,
+  buttonSize: 30,
+  blueprintSize: 'medium',
+};
+
+/**
+ * Forty pixels is the smallest target a fingertip hits reliably, and the type
+ * grows with it because a phone is held further from the eye than a screen.
+ *
+ * Nothing here follows the density down. A finger does not become smaller
+ * because the figure was embedded, so a compact chart on a phone is a compact
+ * chart whose controls are still forty pixels across.
+ */
+const COARSE_METRICS: OverlayMetrics = {
+  controlHeight: 40,
+  gap: 10,
+  paddingX: 10,
+  paddingY: 8,
+  fontSize: 13,
+  labelSize: 12,
+  controlRadius: 8,
+  inset: 10,
+  buttonSize: 40,
+  blueprintSize: 'large',
+};