react-cheminfo 0.11.0 → 0.13.0

package/src/hooks/ui/pollingController.ts

@@ -0,0 +1,139 @@
+import { toError } from '../../error/core/toError.ts';
+
+/** How a backend is asked again and again until it is done. */
+export interface PollingOptions<TValue> {
+  /**
+   * Milliseconds between the end of one poll and the start of the next, or a
+   * function of the latest answer — short while a job runs, long while idle.
+   */
+  interval: number | ((value: TValue) => number);
+  /**
+   * Milliseconds before a failed poll is tried again.
+   * @default the interval when it is a number, otherwise 10 000
+   */
+  retryInterval?: number;
+  /**
+   * Whether an answer is final, which stops the polling.
+   * @default undefined — the polling never stops by itself
+   */
+  isDone?: (value: TValue) => boolean;
+  /**
+   * Whether nothing is asked while the tab is hidden. The next poll then runs
+   * as soon as the tab is shown again.
+   * @default true
+   */
+  pauseWhenHidden?: boolean;
+}
+
+/** What the polling has learned so far. */
+export interface PollingSnapshot<TValue> {
+  /** The latest answer, kept through a failed poll. */
+  value: TValue | undefined;
+  /** Why the latest poll failed, or `undefined` when it answered. */
+  error: Error | undefined;
+  /** Whether an answer was final and the polling stopped. */
+  done: boolean;
+}
+
+/** The snapshot before anything was asked. */
+export const POLLING_IDLE: PollingSnapshot<never> = {
+  value: undefined,
+  error: undefined,
+  done: false,
+};
+
+/** What one run of the polling is started from. */
+export interface PollingRun<TValue> {
+  /** Asks the backend once. */
+  fetcher: () => Promise<TValue>;
+  /** Whether the polling runs at all. */
+  enabled: boolean;
+}
+
+/**
+ * Whether the polling now describes another run than before, so what the
+ * previous run learned — the answer of another job, a `done` that no longer
+ * holds — must be forgotten rather than shown until the first new answer.
+ * @param previous - The run the snapshot on screen came from.
+ * @param next - The run asked for now.
+ * @returns True when the fetcher changed or the polling was switched.
+ */
+export function isNewPollingRun<TValue>(
+  previous: PollingRun<TValue>,
+  next: PollingRun<TValue>,
+): boolean {
+  return previous.fetcher !== next.fetcher || previous.enabled !== next.enabled;
+}
+
+const DEFAULT_RETRY_INTERVAL = 10_000;
+
+/**
+ * Poll `fetcher` until an answer is final, one request at a time.
+ *
+ * The next poll is scheduled once the previous one settled, so requests never
+ * stack and a slow backend is not asked faster than it answers.
+ * @param fetcher - Asks the backend once.
+ * @param options - See {@link PollingOptions}.
+ * @param onUpdate - Receives every new snapshot.
+ * @returns Stops the polling; an answer still in flight is then ignored.
+ */
+export function startPolling<TValue>(
+  fetcher: () => Promise<TValue>,
+  options: PollingOptions<TValue>,
+  onUpdate: (snapshot: PollingSnapshot<TValue>) => void,
+): () => void {
+  const { interval, isDone, pauseWhenHidden = true } = options;
+  const retryInterval =
+    options.retryInterval ??
+    (typeof interval === 'number' ? interval : DEFAULT_RETRY_INTERVAL);
+  const document = pauseWhenHidden
+    ? (globalThis.document as Document | undefined)
+    : undefined;
+
+  let stopped = false;
+  let waitingForVisible = false;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let snapshot: PollingSnapshot<TValue> = POLLING_IDLE;
+
+  function publish(next: PollingSnapshot<TValue>): void {
+    snapshot = next;
+    onUpdate(next);
+  }
+
+  async function poll(): Promise<void> {
+    timer = undefined;
+    if (stopped) return;
+    if (document?.visibilityState === 'hidden') {
+      waitingForVisible = true;
+      return;
+    }
+    try {
+      const value = await fetcher();
+      if (stopped) return;
+      const done = isDone?.(value) ?? false;
+      publish({ value, error: undefined, done });
+      if (done) return;
+      const delay = typeof interval === 'number' ? interval : interval(value);
+      timer = setTimeout(() => void poll(), delay);
+    } catch (error) {
+      if (stopped) return;
+      publish({ ...snapshot, error: toError(error) });
+      timer = setTimeout(() => void poll(), retryInterval);
+    }
+  }
+
+  function onVisibilityChange(): void {
+    if (!waitingForVisible || document?.visibilityState === 'hidden') return;
+    waitingForVisible = false;
+    void poll();
+  }
+
+  document?.addEventListener('visibilitychange', onVisibilityChange);
+  void poll();
+
+  return () => {
+    stopped = true;
+    if (timer !== undefined) clearTimeout(timer);
+    document?.removeEventListener('visibilitychange', onVisibilityChange);
+  };
+}

package/src/hooks/ui/useActiveHeading.ts

@@ -0,0 +1,73 @@
+import { useEffect, useState } from 'react';
+
+import { activeHeadingIndex } from './activeHeading.ts';
+import type { ElementTarget } from './elementTarget.ts';
+import { resolveElementTarget } from './elementTarget.ts';
+
+/** How the headings of an article are found and read. */
+export interface ActiveHeadingOptions {
+  /**
+   * Selects the headings inside the container; each needs an `id`.
+   * @default 'h2[id], h3[id], h4[id]'
+   */
+  selector?: string;
+  /**
+   * Distance from the top of the viewport, in CSS pixels, a heading must pass
+   * to count as the one being read — usually the height of a sticky header.
+   * @default 96
+   */
+  readingLine?: number;
+}
+
+/**
+ * The id of the heading the reader is under, for the table of contents beside
+ * a long article.
+ *
+ * Measured once the container is there, then again on any scroll — of the page
+ * or of a panel holding the article — and on resize, at most once a frame. The
+ * headings are looked up at every measure, so content inserted later is found.
+ * @param container - Ref holding the article, or the article itself. Pass the
+ * element when it mounts later than the component.
+ * @param options - See {@link ActiveHeadingOptions}.
+ * @returns The heading's id, or `null` while there is no heading.
+ */
+export function useActiveHeading(
+  container: ElementTarget,
+  options: ActiveHeadingOptions = {},
+): string | null {
+  const { selector = HEADING_SELECTOR, readingLine = 96 } = options;
+  const [activeId, setActiveId] = useState<string | null>(null);
+
+  useEffect(() => {
+    const document = globalThis.document as Document | undefined;
+    if (document === undefined) return;
+    let frame = 0;
+
+    function measure(): void {
+      frame = 0;
+      const element = resolveElementTarget(container);
+      if (element === null) return;
+      const headings = element.querySelectorAll(selector);
+      const index = activeHeadingIndex(headings, readingLine);
+      setActiveId(index === -1 ? null : (headings[index] as Element).id);
+    }
+
+    function schedule(): void {
+      frame ||= requestAnimationFrame(measure);
+    }
+
+    schedule();
+    const listening = { capture: true, passive: true };
+    document.addEventListener('scroll', schedule, listening);
+    globalThis.addEventListener('resize', schedule, { passive: true });
+    return () => {
+      document.removeEventListener('scroll', schedule, listening);
+      globalThis.removeEventListener('resize', schedule);
+      if (frame !== 0) cancelAnimationFrame(frame);
+    };
+  }, [container, selector, readingLine]);
+
+  return activeId;
+}
+
+const HEADING_SELECTOR = 'h2[id], h3[id], h4[id]';

package/src/hooks/ui/useAsync.ts

@@ -0,0 +1,44 @@
+import { useEffect, useState } from 'react';
+
+import type { AsyncState } from './asyncState.ts';
+import { ASYNC_LOADING, asyncFailed, asyncSucceeded } from './asyncState.ts';
+
+/**
+ * Run an async task and follow where it stands, as a discriminated union.
+ *
+ * The task runs on mount and again whenever it or `refreshKey` changes. A
+ * re-run does not flip the state back to `loading`: what is on screen stays
+ * until the new answer arrives, and a refresh that fails keeps it rather than
+ * replacing it with an error. An answer that arrives after the component
+ * unmounted, or after a newer run started, is ignored.
+ *
+ * The task is a dependency, so pass a stable function — declared at module
+ * scope, or wrapped in `useCallback` over the values it reads.
+ * @param task - The async function to run.
+ * @param refreshKey - Changing it runs the task again; only its identity
+ * matters. Defaults to `undefined`.
+ * @returns Where the latest run stands.
+ */
+export function useAsync<TData>(
+  task: () => Promise<TData>,
+  refreshKey?: unknown,
+): AsyncState<TData> {
+  const [state, setState] = useState<AsyncState<TData>>(ASYNC_LOADING);
+
+  useEffect(() => {
+    let cancelled = false;
+    task().then(
+      (data) => {
+        if (!cancelled) setState(asyncSucceeded(data));
+      },
+      (error: unknown) => {
+        if (!cancelled) setState((previous) => asyncFailed(previous, error));
+      },
+    );
+    return () => {
+      cancelled = true;
+    };
+  }, [task, refreshKey]);
+
+  return state;
+}

package/src/hooks/ui/useDocumentListNavigation.ts

@@ -0,0 +1,70 @@
+import type { RefObject } from 'react';
+import { useEffect, useRef } from 'react';
+
+import type { DocumentListNavigationOptions } from './documentListNavigation.ts';
+import { handleDocumentListKey } from './documentListNavigation.ts';
+
+/** What {@link useDocumentListNavigation} is given. */
+export interface DocumentListNavigationHookOptions extends DocumentListNavigationOptions {
+  /**
+   * Finds the selected row inside the container, to scroll it into view when
+   * a key moved the selection.
+   * @default '[aria-selected="true"], [data-selected="true"]'
+   */
+  selectedSelector?: string;
+}
+
+/**
+ * Arrow-key navigation for a list the visitor does not have to click first.
+ *
+ * The keys are heard on the whole document, and the options are read through a
+ * ref, so the one listener always acts on the list as it now is. `ArrowUp` and
+ * `ArrowDown` move the selection, `Enter` activates it when `onActivate` is
+ * given, and nothing is taken from a text field, a modified key or a key an
+ * earlier handler already used. When a key moved the selection, the selected
+ * row is scrolled into view inside the container the returned ref is put on,
+ * on the next frame, once the page has drawn it. A selection set any other way
+ * — a click, the address, the first render — is left where it is, so a page
+ * never jumps on load.
+ * @param options - See {@link DocumentListNavigationHookOptions}.
+ * @returns The ref to put on the scrolling container of the rows.
+ */
+export function useDocumentListNavigation<TElement extends Element>(
+  options: DocumentListNavigationHookOptions,
+): RefObject<TElement | null> {
+  const containerRef = useRef<TElement>(null);
+  const optionsRef = useRef(options);
+
+  useEffect(() => {
+    optionsRef.current = options;
+  });
+
+  useEffect(() => {
+    const document = globalThis.document as Document | undefined;
+    if (document === undefined) return;
+    let frame: number | undefined;
+
+    function onKeyDown(event: KeyboardEvent): void {
+      const current = optionsRef.current;
+      if (!handleDocumentListKey(event, current)) return;
+      const selector = current.selectedSelector ?? SELECTED_SELECTOR;
+      if (frame !== undefined) cancelAnimationFrame(frame);
+      frame = requestAnimationFrame(() => {
+        frame = undefined;
+        containerRef.current
+          ?.querySelector(selector)
+          ?.scrollIntoView({ block: 'nearest' });
+      });
+    }
+
+    document.addEventListener('keydown', onKeyDown);
+    return () => {
+      document.removeEventListener('keydown', onKeyDown);
+      if (frame !== undefined) cancelAnimationFrame(frame);
+    };
+  }, []);
+
+  return containerRef;
+}
+
+const SELECTED_SELECTOR = '[aria-selected="true"], [data-selected="true"]';

package/src/hooks/ui/usePolling.ts

@@ -0,0 +1,97 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+
+import type {
+  PollingOptions,
+  PollingRun,
+  PollingSnapshot,
+} from './pollingController.ts';
+import {
+  POLLING_IDLE,
+  isNewPollingRun,
+  startPolling,
+} from './pollingController.ts';
+
+/** What {@link usePolling} is given. */
+export interface UsePollingOptions<TValue> extends PollingOptions<TValue> {
+  /**
+   * Whether the polling runs. Turning it off stops it and forgets what it
+   * learned; turning it on starts a fresh run.
+   * @default true
+   */
+  enabled?: boolean;
+}
+
+/** Where the polling stands, and how to start it over. */
+export interface PollingState<TValue> extends PollingSnapshot<TValue> {
+  /** Forget what was learned and poll again from now, e.g. after a job was launched. */
+  restart: () => void;
+}
+
+/**
+ * Poll a backend job until it is done.
+ *
+ * One request at a time: the next poll is scheduled once the previous one
+ * settled, a failed poll keeps the last answer and is retried, and nothing is
+ * asked while the tab is hidden. A new `fetcher` — the status of another job —
+ * starts a fresh run and forgets what the previous one learned, as turning
+ * `enabled` off and on and `restart` do, so pass a stable function; `interval`
+ * and `isDone` are read at each poll and may be inline.
+ * @param fetcher - Asks the backend once.
+ * @param options - See {@link UsePollingOptions}.
+ * @returns The latest answer, the latest failure, whether it is done, and `restart`.
+ */
+export function usePolling<TValue>(
+  fetcher: () => Promise<TValue>,
+  options: UsePollingOptions<TValue>,
+): PollingState<TValue> {
+  const {
+    enabled = true,
+    interval,
+    retryInterval,
+    isDone,
+    pauseWhenHidden = true,
+  } = options;
+  const [snapshot, setSnapshot] =
+    useState<PollingSnapshot<TValue>>(POLLING_IDLE);
+  const [run, setRun] = useState(0);
+  const [currentRun, setCurrentRun] = useState<PollingRun<TValue>>({
+    fetcher,
+    enabled,
+  });
+  if (isNewPollingRun(currentRun, { fetcher, enabled })) {
+    setCurrentRun({ fetcher, enabled });
+    setSnapshot(POLLING_IDLE);
+  }
+
+  const latestRef = useRef({ interval, isDone });
+  useEffect(() => {
+    latestRef.current = { interval, isDone };
+  });
+
+  const fixedRetryInterval =
+    retryInterval ?? (typeof interval === 'number' ? interval : undefined);
+
+  useEffect(() => {
+    if (!enabled) return;
+    return startPolling(
+      fetcher,
+      {
+        interval: (value) => {
+          const current = latestRef.current.interval;
+          return typeof current === 'number' ? current : current(value);
+        },
+        retryInterval: fixedRetryInterval,
+        isDone: (value) => latestRef.current.isDone?.(value) ?? false,
+        pauseWhenHidden,
+      },
+      setSnapshot,
+    );
+  }, [fetcher, enabled, run, fixedRetryInterval, pauseWhenHidden]);
+
+  const restart = useCallback(() => {
+    setSnapshot(POLLING_IDLE);
+    setRun((count) => count + 1);
+  }, []);
+
+  return useMemo(() => ({ ...snapshot, restart }), [snapshot, restart]);
+}

package/src/hooks/ui/useResizeObserver.ts

@@ -1,6 +1,8 @@
-import type { RefObject } from 'react';
 import { useEffect, useRef } from 'react';
 
+import type { ElementTarget } from './elementTarget.ts';
+import { resolveElementTarget } from './elementTarget.ts';
+
 /** The content-box size of an element, in CSS pixels. */
 export interface ElementSize {
   /** Content-box width. */
@@ -16,11 +18,13 @@ export interface ElementSize {
  * passed on every render without tearing the observer down and setting it up
  * again. Nothing is observed where `ResizeObserver` is missing — a server
  * render, or a test rendering to a string — so the hook is safe to call there.
- * @param ref - Ref holding the element to watch.
+ * @param target - Ref holding the element to watch, or the element itself.
+ * Pass the element when it mounts later than the component, so the observer
+ * follows it.
  * @param callback - Receives the new content-box size.
  */
 export function useResizeObserver(
-  ref: RefObject<Element | null>,
+  target: ElementTarget,
   callback: (size: ElementSize) => void,
 ): void {
   const callbackRef = useRef(callback);
@@ -30,7 +34,7 @@ export function useResizeObserver(
   });
 
   useEffect(() => {
-    const element = ref.current;
+    const element = resolveElementTarget(target);
     const Observer = globalThis.ResizeObserver as
       typeof ResizeObserver | undefined;
     if (element === null || Observer === undefined) return;
@@ -46,5 +50,5 @@ export function useResizeObserver(
     return () => {
       observer.disconnect();
     };
-  }, [ref]);
+  }, [target]);
 }

package/src/molecule3d/core/exportImage.ts

@@ -0,0 +1,50 @@
+/**
+ * The pieces of an image export that need neither React nor molstar: wrapping
+ * a rendered picture in an SVG file, and reading a data URI back as bytes.
+ */
+
+/** The pixel size of a rendered image. */
+export interface ImageSize {
+  width: number;
+  height: number;
+}
+
+/**
+ * An SVG document holding one raster image at its own size.
+ *
+ * A molecule rendered by WebGL has no vector form, so its SVG is the picture
+ * itself, embedded: it opens in every editor and can be placed beside vector
+ * artwork, but it does not stay sharp past the resolution it was rendered at.
+ * @param dataUri - The image, as a `data:` URI.
+ * @param size - Its pixel size.
+ * @returns The SVG markup.
+ */
+export function rasterSvgMarkup(dataUri: string, size: ImageSize): string {
+  const { width, height } = size;
+  const href = escapeAttribute(dataUri);
+  return `<svg xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" width="${width}" height="${height}" viewBox="0 0 ${width} ${height}"><image width="${width}" height="${height}" href="${href}" xlink:href="${href}"/></svg>`;
+}
+
+/**
+ * Decode a base64 `data:` URI into its bytes, without `fetch`, which a page's
+ * content security policy may forbid for `data:` addresses.
+ * @param dataUri - A base64 data URI, e.g. `data:image/png;base64,iVBOR…`.
+ * @returns The decoded bytes.
+ * @throws {Error} When the URI is not base64-encoded.
+ */
+export function dataUriBytes(dataUri: string): Uint8Array<ArrayBuffer> {
+  const comma = dataUri.indexOf(',');
+  if (comma === -1 || !dataUri.slice(0, comma).endsWith(';base64')) {
+    throw new Error('Expected a base64 data URI.');
+  }
+  const binary = atob(dataUri.slice(comma + 1));
+  const bytes = new Uint8Array(binary.length);
+  for (let i = 0; i < binary.length; i++) {
+    bytes[i] = binary.codePointAt(i) ?? 0;
+  }
+  return bytes;
+}
+
+function escapeAttribute(value: string): string {
+  return value.replaceAll('&', '&amp;').replaceAll('"', '&quot;');
+}

package/src/molecule3d/core/gestures.ts

@@ -0,0 +1,35 @@
+/**
+ * What the mouse and the keyboard do on the molecule canvas: molstar's default
+ * trackball and focus bindings, which the viewer keeps.
+ */
+
+/** A key, drawn as a key cap. */
+export interface Molecule3DGestureKey {
+  key: string;
+}
+
+/** One gesture and what it does. */
+export interface Molecule3DGesture {
+  /** Keys, and plain text for the mouse part; unique within one gesture. */
+  input: ReadonlyArray<string | Molecule3DGestureKey>;
+  action: string;
+}
+
+/** The gestures, in the order the help popover lists them. */
+export const MOLECULE_3D_GESTURES: readonly Molecule3DGesture[] = [
+  { input: ['Drag'], action: 'Rotate' },
+  {
+    input: [{ key: 'Shift' }, '+', { key: 'Ctrl' }, '+ drag'],
+    action: 'Rotate in the plane of the screen',
+  },
+  {
+    input: [{ key: 'Q' }, 'or', { key: 'E' }],
+    action: 'Rotate in the plane, while held',
+  },
+  { input: ['Right-drag'], action: 'Move' },
+  { input: [{ key: 'Ctrl' }, '+ drag'], action: 'Move' },
+  { input: ['Scroll'], action: 'Zoom' },
+  { input: [{ key: 'Shift' }, '+ scroll'], action: 'Clip around the centre' },
+  { input: ['Click an atom'], action: 'Centre on it' },
+  { input: ['Click the background'], action: 'Centre on the molecule' },
+];

package/src/molecule3d/core/index.ts

@@ -0,0 +1,35 @@
+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 {
+  AtomReference,
+  Measurement,
+  MeasurementKind,
+} from './measurement.ts';
+export {
+  MEASUREMENT_ATOM_COUNTS,
+  MEASUREMENT_KINDS,
+  MEASUREMENT_LABELS,
+} from './measurement.ts';
+export type {
+  Molecule3DFile,
+  Molecule3DSettings,
+  Molecule3DTools,
+  RepresentationId,
+  SurfaceColoringId,
+} from './settings.ts';
+export {
+  DEFAULT_MOLECULE_3D_SETTINGS,
+  DEFAULT_MOLECULE_3D_TOOLS,
+  MOLECULE_3D_RANGES,
+  REPRESENTATIONS,
+  REPRESENTATION_LABELS,
+  SURFACE_CHARGE_COLORS,
+  SURFACE_COLORINGS,
+  SURFACE_COLORING_LABELS,
+  isRepresentationId,
+  isSurfaceColoringId,
+  normalizeMolecule3DSettings,
+  resolveMolecule3DTools,
+} from './settings.ts';

package/src/molecule3d/core/measurement.ts

@@ -0,0 +1,43 @@
+/**
+ * What a measurement on a 3D molecule is, without React and without molstar,
+ * so a site can store, persist or share measurements on its own.
+ *
+ * Atoms are named by position rather than by molstar loci, so a measurement
+ * taken on one conformer lands on the same atoms of every other conformer of
+ * the same molecule — which is what lets a reader watch a dihedral change down
+ * a list of conformers.
+ */
+
+/** The three geometric measurements, in the order the toolbar offers them. */
+export const MEASUREMENT_KINDS = ['distance', 'angle', 'dihedral'] as const;
+
+/** One of {@link MEASUREMENT_KINDS}. */
+export type MeasurementKind = (typeof MEASUREMENT_KINDS)[number];
+
+/** How many atoms each kind is measured between. */
+export const MEASUREMENT_ATOM_COUNTS: Record<MeasurementKind, number> = {
+  distance: 2,
+  angle: 3,
+  dihedral: 4,
+};
+
+/** What the toolbar calls each kind. */
+export const MEASUREMENT_LABELS: Record<MeasurementKind, string> = {
+  distance: 'Distance',
+  angle: 'Angle',
+  dihedral: 'Dihedral angle',
+};
+
+/** One atom of the displayed structure, by position. */
+export interface AtomReference {
+  /** Index of the unit in molstar's `structure.units`; 0 for a molfile. */
+  unit: number;
+  /** Index of the atom inside that unit. */
+  element: number;
+}
+
+/** One measurement, with its atoms in the order they were picked. */
+export interface Measurement {
+  kind: MeasurementKind;
+  atoms: readonly AtomReference[];
+}