react-cheminfo 0.64.1 → 0.65.0

package/src/molstar/core/framing.ts

@@ -0,0 +1,200 @@
+/**
+ * Framing a scene: the sphere everything on screen fits in, the camera moved
+ * to show it whole, and the zoom onto one point of it.
+ *
+ * What is on screen is measured rather than read off molstar: a canvas's own
+ * `boundingSphereVisible` is read once when the canvas is built, a
+ * ball-and-stick representation pads its sphere by the largest ball it could
+ * ever draw, and an isosurface reports the whole sampled box. So a site hands
+ * the spheres it measured itself, and names which render objects are worth
+ * their own sphere — a mesh it built, whose sphere is exactly its vertices.
+ */
+
+import type { GraphicsRenderObject } from 'molstar/lib/mol-gl/render-object.js';
+import { BoundaryHelper } from 'molstar/lib/mol-math/geometry/boundary-helper.js';
+import { Sphere3D } from 'molstar/lib/mol-math/geometry.js';
+import { Vec3 } from 'molstar/lib/mol-math/linear-algebra.js';
+import type { PluginContext } from 'molstar/lib/mol-plugin/context.js';
+
+import {
+  DEFAULT_CAMERA_DURATION,
+  FRAMING_MARGIN,
+  MINIMUM_FRAMING_RADIUS,
+  framedRadius,
+} from './camera.ts';
+
+/**
+ * Frame everything on screen.
+ *
+ * Without an orientation the camera keeps the direction it already points in,
+ * which is what a reframe after a reader turned the scene must do. A scene with
+ * nothing measured is framed by molstar's own reset.
+ * @param plugin - The molstar context.
+ * @param options - What to frame, from where, and how fast.
+ */
+export function resetCamera(
+  plugin: PluginContext,
+  options: ResetCameraOptions = {},
+): void {
+  const { durationMs = DEFAULT_CAMERA_DURATION, margin = FRAMING_MARGIN } =
+    options;
+  const { sphere, orientation } = options;
+  plugin.canvas3d?.commit(true);
+  const scene = sphere === undefined ? sceneSphere(plugin, options) : sphere;
+  if (scene === null || scene.radius <= 0) {
+    plugin.managers.camera.reset(undefined, durationMs);
+    return;
+  }
+  const { center, radius } = scene;
+  const [x = 0, y = 0, z = 0] = center;
+  focusPoint(plugin, [x, y, z], framedRadius(radius, margin), {
+    durationMs,
+    orientation,
+  });
+}
+
+/**
+ * Frame one ball of the scene: an atom picked, the centre of a bond, the
+ * whole scene.
+ *
+ * The canvas is committed first — `add()` only queues, and a queued object
+ * belongs to no bounding sphere yet — and the ball is framed with no padding
+ * of molstar's own, whose 4 Å default leaves water a twentieth of the canvas.
+ * @param plugin - The molstar context.
+ * @param centre - What to frame, Cartesian ångström.
+ * @param radius - Radius of the ball to fit, ångström.
+ * @param options - From where, and how fast.
+ */
+export function focusPoint(
+  plugin: PluginContext,
+  centre: Point3,
+  radius: number,
+  options: FocusOptions = {},
+): void {
+  const { durationMs = DEFAULT_CAMERA_DURATION, orientation } = options;
+  plugin.canvas3d?.commit(true);
+  const target = Vec3.create(centre[0], centre[1], centre[2]);
+  const camera = plugin.canvas3d?.camera;
+  if (orientation !== undefined && camera !== undefined) {
+    // `getFocus` only matches the sign of a direction against the current
+    // camera; `getInvariantFocus` takes the direction and the up as given.
+    const { eye, up } = orientation;
+    plugin.managers.camera.setSnapshot(
+      camera.getInvariantFocus(
+        target,
+        Math.max(radius, MINIMUM_FRAMING_RADIUS),
+        Vec3.create(up[0], up[1], up[2]),
+        Vec3.create(-eye[0], -eye[1], -eye[2]),
+      ),
+      durationMs,
+    );
+    return;
+  }
+  plugin.managers.camera.focusSphere(Sphere3D.create(target, radius), {
+    extraRadius: 0,
+    minRadius: MINIMUM_FRAMING_RADIUS,
+    durationMs,
+  });
+}
+
+/**
+ * The one sphere everything worth framing fits in: the spheres a site
+ * measured itself, and those of the render objects it names.
+ * @param plugin - The molstar context.
+ * @param options - The measured spheres, and which render objects count.
+ * @returns The sphere, or `null` when nothing was measured.
+ */
+export function sceneSphere(
+  plugin: PluginContext,
+  options: SceneSphereOptions = {},
+): Sphere3D | null {
+  const spheres: Sphere3D[] = [];
+  for (const sphere of options.spheres ?? []) {
+    if (sphere.radius > 0) spheres.push(sphere);
+  }
+  const { include } = options;
+  const canvas3d = plugin.canvas3d;
+  if (include !== undefined && canvas3d !== undefined) {
+    canvas3d.commit(true);
+    for (const object of canvas3d.getRenderObjects()) {
+      if (!include(object)) continue;
+      const sphere = object.values.boundingSphere.ref.value;
+      if (sphere.radius > 0) spheres.push(sphere);
+    }
+  }
+  return unionSphere(spheres);
+}
+
+/**
+ * The smallest sphere holding a set of spheres, as molstar's own camera
+ * manager computes it.
+ * @param spheres - The spheres to hold.
+ * @returns It, the one sphere itself when there is one, `null` when there is none.
+ */
+export function unionSphere(spheres: readonly Sphere3D[]): Sphere3D | null {
+  const first = spheres[0];
+  if (first === undefined) return null;
+  if (spheres.length === 1) return first;
+  boundary.reset();
+  for (const sphere of spheres) boundary.includeSphere(sphere);
+  boundary.finishedIncludeStep();
+  for (const sphere of spheres) boundary.radiusSphere(sphere);
+  return boundary.getSphere();
+}
+
+/** A point in Cartesian ångström. */
+export type Point3 = readonly [x: number, y: number, z: number];
+
+/** Where the camera stands to look at a scene. */
+export interface ViewOrientation {
+  /** The direction from what is looked at to the eye. */
+  eye: Point3;
+  /** The direction that is up on screen. */
+  up: Point3;
+}
+
+/** How {@link focusPoint} moves the camera. */
+export interface FocusOptions {
+  /**
+   * Transition length, in milliseconds; 0 jumps.
+   * @default 250
+   */
+  durationMs?: number;
+  /**
+   * Where to look from.
+   * @default undefined — the direction the camera already points in
+   */
+  orientation?: ViewOrientation;
+}
+
+/** What {@link sceneSphere} measures. */
+export interface SceneSphereOptions {
+  /**
+   * Spheres the site measured itself: a model from its own atoms, a part of
+   * the scene registered as it was drawn.
+   * @default []
+   */
+  spheres?: readonly Sphere3D[];
+  /**
+   * Which render objects of the canvas count with their own sphere.
+   * @default undefined — none does
+   */
+  include?: (object: GraphicsRenderObject) => boolean;
+}
+
+/** What {@link resetCamera} frames, and how. */
+export interface ResetCameraOptions extends SceneSphereOptions, FocusOptions {
+  /**
+   * The sphere to frame, measured by the caller, instead of the scene's.
+   * @default undefined — the sphere `sceneSphere` measures
+   */
+  sphere?: Sphere3D | null;
+  /**
+   * Fraction of the radius kept as breathing room around the scene.
+   * @default 0.08
+   */
+  margin?: number;
+}
+
+// Reused across calls, as molstar's own camera manager does.
+const boundary = new BoundaryHelper('98');

package/src/molstar/core/hover.ts

@@ -38,6 +38,32 @@ export function subscribeHover(
   };
 }
 
+/** What the pointer rests on, in a line, and the loci it names. */
+export interface HoverLabel {
+  /** `O 1`, `Si 4 — O 8`, or the label a drawing of the site carries. */
+  label: string;
+  /** The loci, for a site that wants more of it — the atom it holds, say. */
+  loci: Loci;
+}
+
+/**
+ * Report the label of whatever the pointer rests on: an atom named as a
+ * reader would name it, anything else by the label it was drawn with.
+ * @param plugin - The molstar context.
+ * @param listener - Called with the label and its loci, or `null` when the
+ * pointer leaves everything or rests on something with nothing to say.
+ * @returns The unsubscribe function.
+ */
+export function subscribeHoverLabel(
+  plugin: PluginContext,
+  listener: (hover: HoverLabel | null) => void,
+): () => void {
+  return subscribeHover(plugin, (loci) => {
+    const label = loci === null ? null : (atomText(loci) ?? lociText(loci));
+    listener(label === null || loci === null ? null : { label, loci });
+  });
+}
+
 /**
  * The one line a loci is worth, in molstar's own words.
  * @param loci - What the pointer is over.

package/src/molstar/core/index.ts

@@ -25,8 +25,28 @@ export {
   framedRadius,
   setSpin,
 } from './camera.ts';
+export type {
+  FocusOptions,
+  Point3,
+  ResetCameraOptions,
+  SceneSphereOptions,
+  ViewOrientation,
+} from './framing.ts';
+export {
+  focusPoint,
+  resetCamera,
+  sceneSphere,
+  unionSphere,
+} from './framing.ts';
 export { HighlightPainter, highlightOverpaint } from './highlights.ts';
-export { atomName, atomText, lociText, subscribeHover } from './hover.ts';
+export type { HoverLabel } from './hover.ts';
+export {
+  atomName,
+  atomText,
+  lociText,
+  subscribeHover,
+  subscribeHoverLabel,
+} from './hover.ts';
 export type { MolstarPluginOptions } from './plugin.ts';
 export { MolstarPlugin } from './plugin.ts';
 export { captureScene } from './captureScene.ts';

package/src/pedagogy/core/answers.ts

@@ -0,0 +1,94 @@
+/**
+ * Reading what a student typed into an answer box, and the verdicts a grader
+ * gives a box it cannot grade.
+ */
+
+import { CHROME_CATALOG } from '../../i18n/core/chromeCatalog.ts';
+import type { Language } from '../../i18n/core/languages.ts';
+import { DEFAULT_LANGUAGE } from '../../i18n/core/languages.ts';
+import { catalogTranslate } from '../../i18n/core/translate.ts';
+import { readNumber } from '../../number/core/numberText.ts';
+
+import type { FieldCase } from './series.ts';
+
+/**
+ * Read a number the way a student types it: `42`, `+5`, `−3` with a real minus
+ * sign, `1,5` with a decimal comma, `75.8 %`, `1 000`.
+ *
+ * What a typed answer carries beyond a number box — a typographic minus, a
+ * percent sign, a space between thousands — is taken off first; the number
+ * itself is read by `readNumber`, as every box of the family reads one.
+ * @param text - What was typed.
+ * @param integer - Whether only a whole number is an answer.
+ * @default integer false
+ * @returns The number, or undefined when the text is not one.
+ */
+export function readAnswerNumber(
+  text: string,
+  integer = false,
+): number | undefined {
+  const cleaned = text
+    .trim()
+    .replaceAll(/[−–]/gu, '-')
+    .replace(/\s*%$/u, '')
+    .replaceAll(/\s/gu, '');
+  return readNumber(cleaned, integer);
+}
+
+/**
+ * Write a signed whole number the way an oxidation state or a charge is
+ * written: `+5`, `−2`, `0`.
+ * @param value - The number.
+ * @returns The number with its sign, and a true minus sign.
+ */
+export function formatSigned(value: number): string {
+  if (value > 0) return `+${value}`;
+  if (value < 0) return `−${-value}`;
+  return '0';
+}
+
+/**
+ * The verdict on a field left empty.
+ * @param label - The field, as its box labels it.
+ * @param what - What the box asks for, e.g. `a number of electrons`.
+ * @param language - The language the reason is written in.
+ * @default language 'en'
+ * @returns A failed case that says what to type.
+ */
+export function emptyCase(
+  label: string,
+  what: string,
+  language: Language = DEFAULT_LANGUAGE,
+): FieldCase {
+  const t = catalogTranslate(CHROME_CATALOG, language);
+  return {
+    label,
+    passed: false,
+    reason: t('pedagogy.answerEmpty', { what }),
+    actual: null,
+  };
+}
+
+/**
+ * The verdict on a field that does not read as the kind of value it asks for.
+ * @param label - The field, as its box labels it.
+ * @param typed - What was typed.
+ * @param what - What the box asks for, e.g. `a whole number`.
+ * @param language - The language the reason is written in.
+ * @default language 'en'
+ * @returns A failed case quoting what was typed.
+ */
+export function unreadableCase(
+  label: string,
+  typed: string,
+  what: string,
+  language: Language = DEFAULT_LANGUAGE,
+): FieldCase {
+  const t = catalogTranslate(CHROME_CATALOG, language);
+  return {
+    label,
+    passed: false,
+    reason: t('pedagogy.answerUnreadable', { typed: typed.trim(), what }),
+    actual: typed,
+  };
+}

package/src/pedagogy/core/attempts.ts

@@ -0,0 +1,205 @@
+/**
+ * How far a student has got on a graded series, kept in this browser.
+ *
+ * Best effort and never a precondition: a framed page whose storage is
+ * partitioned still works, it just forgets. An attempt is keyed by tool, series
+ * and question, so a new series starts clean and a shared link reopens its own.
+ * The store is a plain subscribable value, so a page reads it with React's
+ * `useSyncExternalStore` or from a signal of its own, and the series components
+ * re-render on it without knowing which.
+ */
+
+import { persistBucket } from '../../state/core/persistBucket.ts';
+
+import type { ProgressRecords, ProgressStore } from './progress.ts';
+import { localStorageProgressStore } from './progress.ts';
+import type { ExerciseStatus } from './types.ts';
+
+/** One question as the student left it. */
+export interface Attempt {
+  /** Where the student stands on it. */
+  status: ExerciseStatus;
+  /** What was typed, or drawn, field by field. */
+  answers: Record<string, string>;
+  /** The answers as they were when last checked, so a change hides the verdict. */
+  checked: string | null;
+  /** How many hints of the ladder are open. */
+  hintsRevealed: number;
+  /** Whether the worked answer is on screen. */
+  showSolution: boolean;
+}
+
+/**
+ * What a question looks like before anything is typed into it.
+ * @returns A fresh attempt.
+ */
+export function emptyAttempt(): Attempt {
+  return {
+    status: 'idle',
+    answers: {},
+    checked: null,
+    hintsRevealed: 0,
+    showSolution: false,
+  };
+}
+
+/**
+ * The key an attempt is kept under.
+ * @param tool - The tool.
+ * @param seed - The series.
+ * @param question - The question's key in the tool's pool.
+ * @returns `tool/seed/question`.
+ */
+export function attemptKey(
+  tool: string,
+  seed: number,
+  question: string,
+): string {
+  return `${tool}/${seed}/${question}`;
+}
+
+/** What {@link createAttemptStore} is built from. */
+export interface AttemptStoreOptions {
+  /**
+   * The site, which namespaces both entries: `atoms` keeps its attempts under
+   * `atoms:attempts:v1` and the series each tool was last on under
+   * `atoms:seeds:v1`.
+   */
+  key: string;
+  /**
+   * Where the attempts are kept, for a course that keeps them itself.
+   * @default the browser's `localStorage`, under `<key>:attempts:v1`
+   */
+  binding?: ProgressStore<Attempt>;
+  /**
+   * Called when a save was refused because the store is full.
+   * @default undefined
+   */
+  onQuotaExceeded?: (error: unknown) => void;
+}
+
+/** The attempts of a site, and the series each of its tools was last on. */
+export interface AttemptStore {
+  /** Every attempt this browser remembers; a new object after each change. */
+  records: () => ProgressRecords<Attempt>;
+  /** Be told after each change; returns the function that stops it. */
+  subscribe: (listener: () => void) => () => void;
+  /** One question's attempt, or a fresh one. */
+  attemptFor: (key: string) => Attempt;
+  /** Change one attempt and keep it. */
+  updateAttempt: (key: string, change: Partial<Attempt>) => void;
+  /** Forget the attempts of some questions. */
+  clearAttempts: (keys: readonly string[]) => void;
+  /**
+   * Forget every series of a tool but one, so storage does not grow with every
+   * new series drawn.
+   */
+  forgetOtherSeries: (tool: string, seed: number) => void;
+  /** The series a tool was last on in this browser, or null. */
+  storedSeed: (tool: string) => number | null;
+  /** Remember the series a tool is on. */
+  storeSeed: (tool: string, seed: number) => void;
+}
+
+/**
+ * The attempts of a site's graded series, kept in this browser.
+ * @param options - The site's namespace, and where else to keep them.
+ * @returns The store.
+ */
+export function createAttemptStore(options: AttemptStoreOptions): AttemptStore {
+  const { key, onQuotaExceeded } = options;
+  const binding =
+    options.binding ??
+    localStorageProgressStore<Attempt>({
+      key: `${key}:attempts`,
+      version: 1,
+      defaults: emptyAttempt(),
+      onQuotaExceeded,
+    });
+  const seeds = persistBucket<Record<string, number>>({
+    key: `${key}:seeds`,
+    version: 1,
+    defaults: {},
+    onQuotaExceeded,
+  });
+  const listeners = new Set<() => void>();
+  let current: ProgressRecords<Attempt> = {};
+  // Kept in memory as well, so a framed page whose storage is blocked still
+  // reopens the series it is on for as long as it stays open.
+  let seedsByTool = seeds.read().value;
+
+  function publish(next: ProgressRecords<Attempt>, save: boolean): void {
+    current = next;
+    if (save) void binding.save(next);
+    for (const listener of listeners) listener();
+  }
+
+  const loaded = binding.load();
+  if (loaded instanceof Promise) {
+    void loaded.then(
+      (records) => {
+        publish(records, false);
+      },
+      () => {
+        // A binding that cannot answer leaves the page working from nothing.
+      },
+    );
+  } else {
+    current = loaded;
+  }
+
+  function attemptFor(attempt: string): Attempt {
+    return current[attempt] ?? emptyAttempt();
+  }
+
+  return {
+    records: () => current,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => {
+        listeners.delete(listener);
+      };
+    },
+    attemptFor,
+    updateAttempt(attempt, change) {
+      publish(
+        { ...current, [attempt]: { ...attemptFor(attempt), ...change } },
+        true,
+      );
+    },
+    clearAttempts(keys) {
+      const cleared = new Set(keys);
+      publish(
+        keep(current, (attempt) => !cleared.has(attempt)),
+        true,
+      );
+    },
+    forgetOtherSeries(tool, seed) {
+      const kept = `${tool}/${seed}/`;
+      publish(
+        keep(
+          current,
+          (attempt) =>
+            !attempt.startsWith(`${tool}/`) || attempt.startsWith(kept),
+        ),
+        true,
+      );
+    },
+    storedSeed: (tool) => seedsByTool[tool] ?? null,
+    storeSeed(tool, seed) {
+      seedsByTool = { ...seedsByTool, [tool]: seed };
+      seeds.write(seedsByTool);
+    },
+  };
+}
+
+function keep(
+  records: ProgressRecords<Attempt>,
+  wanted: (key: string) => boolean,
+): ProgressRecords<Attempt> {
+  const next: ProgressRecords<Attempt> = {};
+  for (const [key, attempt] of Object.entries(records)) {
+    if (wanted(key)) next[key] = attempt;
+  }
+  return next;
+}

package/src/pedagogy/core/index.ts

@@ -40,3 +40,39 @@ export type {
   ValidationResult,
 } from './validation.ts';
 export { failedValidation, finishValidation } from './validation.ts';
+export {
+  emptyCase,
+  formatSigned,
+  readAnswerNumber,
+  unreadableCase,
+} from './answers.ts';
+export type { Attempt, AttemptStore, AttemptStoreOptions } from './attempts.ts';
+export { attemptKey, createAttemptStore, emptyAttempt } from './attempts.ts';
+export type {
+  ControlledProgress,
+  ProgressController,
+  ProgressControllerOptions,
+  ProgressSignal,
+} from './progressController.ts';
+export { createProgressController } from './progressController.ts';
+export type {
+  PickSeededOptions,
+  SeedDraw,
+  SeedRange,
+  SeedValue,
+} from './seed.ts';
+export {
+  EACH_SEED,
+  LARGEST_SEED,
+  freshSeed,
+  parseSeed,
+  pickSeeded,
+  seedParam,
+} from './seed.ts';
+export type {
+  AnswerCheck,
+  AnswerField,
+  Answers,
+  FieldCase,
+  SeriesTool,
+} from './series.ts';