react-cheminfo 0.23.0 → 0.25.0

package/src/structure/core/moleculeCoordinates.ts

@@ -0,0 +1,93 @@
+import type { Molecule } from 'openchemlib';
+
+import type { RelaxableGeometry } from './geometryRelaxer.ts';
+
+/**
+ * Read the elements and 3D coordinates of a molecule into the flat form an
+ * engine takes.
+ * @param molecule - A molecule carrying 3D coordinates. Not modified.
+ * @returns Its geometry in ångström, one entry per atom of `getAllAtoms()`.
+ */
+export function readRelaxableGeometry(molecule: Molecule): RelaxableGeometry {
+  const atoms = molecule.getAllAtoms();
+  const elements = new Array<string>(atoms);
+  const coordinates = new Float64Array(atoms * 3);
+  for (let atom = 0; atom < atoms; atom++) {
+    elements[atom] = molecule.getAtomLabel(atom);
+    coordinates[atom * 3] = molecule.getAtomX(atom);
+    coordinates[atom * 3 + 1] = molecule.getAtomY(atom);
+    coordinates[atom * 3 + 2] = molecule.getAtomZ(atom);
+  }
+  return { elements, coordinates };
+}
+
+/**
+ * Write flat coordinates back onto a molecule, atom for atom.
+ * @param molecule - The molecule to move. Mutated.
+ * @param coordinates - Flat `x,y,z` per atom in ångström.
+ * @throws {Error} When there is not one position per atom.
+ */
+export function writeRelaxedCoordinates(
+  molecule: Molecule,
+  coordinates: Float64Array,
+): void {
+  const atoms = molecule.getAllAtoms();
+  if (coordinates.length !== atoms * 3) {
+    throw new Error(
+      `The relaxed geometry has ${coordinates.length / 3} positions for ${atoms} atoms.`,
+    );
+  }
+  for (let atom = 0; atom < atoms; atom++) {
+    molecule.setAtomX(atom, coordinates[atom * 3] as number);
+    molecule.setAtomY(atom, coordinates[atom * 3 + 1] as number);
+    molecule.setAtomZ(atom, coordinates[atom * 3 + 2] as number);
+  }
+}
+
+/**
+ * Root-mean-square displacement between two geometries of the same atoms, each
+ * taken about its own centroid, in ångström.
+ *
+ * Removing the centroids is what makes the number mean "how far the atoms
+ * moved" rather than "how far the molecule was translated": a relaxer is free
+ * to recentre a molecule, and the `GeometryRelaxer` contract forbids it to
+ * rotate one.
+ * @param before - Flat coordinates before.
+ * @param after - Flat coordinates after.
+ * @returns The RMSD in ångström, `0` for an empty geometry.
+ * @throws {Error} When the two do not hold the same number of atoms.
+ */
+export function centredRmsd(before: Float64Array, after: Float64Array): number {
+  if (before.length !== after.length) {
+    throw new Error(
+      `Cannot compare ${before.length / 3} positions with ${after.length / 3}.`,
+    );
+  }
+  const atoms = before.length / 3;
+  if (atoms === 0) return 0;
+  const centreBefore = centroid(before, atoms);
+  const centreAfter = centroid(after, atoms);
+  let total = 0;
+  for (let atom = 0; atom < atoms; atom++) {
+    for (let axis = 0; axis < 3; axis++) {
+      const gap =
+        (before[atom * 3 + axis] as number) -
+        (centreBefore[axis] as number) -
+        ((after[atom * 3 + axis] as number) - (centreAfter[axis] as number));
+      total += gap * gap;
+    }
+  }
+  return Math.sqrt(total / atoms);
+}
+
+function centroid(coordinates: Float64Array, atoms: number): Float64Array {
+  let x = 0;
+  let y = 0;
+  let z = 0;
+  for (let atom = 0; atom < atoms; atom++) {
+    x += coordinates[atom * 3] as number;
+    y += coordinates[atom * 3 + 1] as number;
+    z += coordinates[atom * 3 + 2] as number;
+  }
+  return new Float64Array([x / atoms, y / atoms, z / atoms]);
+}

package/src/structure/core/molfileExport.ts

@@ -0,0 +1,62 @@
+import type { Molecule } from 'openchemlib';
+
+import { classifyMolfile } from './molfile.ts';
+
+/** A molfile plus the molstar format id that can actually parse it. */
+export interface MolfileExport {
+  /** molstar's format id: `mol` reads V2000, `sdf` reads V2000 and V3000. */
+  format: 'mol' | 'sdf';
+  /** The molfile text, exactly as OpenChemLib wrote it. */
+  data: string;
+}
+
+/**
+ * Serialise a molecule for the 3D viewer and for export.
+ *
+ * V2000 is written whenever it can be: its counts line holds three digits per
+ * field, so above 999 atoms OpenChemLib writes `?` where the count belongs and
+ * the file becomes unreadable. V3000 is used from that size on.
+ *
+ * Coordinates are emitted exactly as OpenChemLib writes them — the whole
+ * molecule is negated in y and z relative to `getAtomY/Z`, which is a rigid
+ * rotation and therefore invisible to the viewer, to the energies and to any
+ * other file consumer.
+ *
+ * Hydrogens are in the file only if they are explicit atoms, so call this on a
+ * conformer, which always carries them.
+ * @param molecule - Structure with 3D coordinates already set. Not mutated.
+ * @returns The molfile and the format id to hand molstar.
+ * @throws {Error} When the molfile carries no atoms.
+ */
+export function toMolfileExport(molecule: Molecule): MolfileExport {
+  const data =
+    molecule.getAllAtoms() > V2000_MAX_ATOMS
+      ? molecule.toMolfileV3()
+      : molecule.toMolfile();
+  return readMolfileExport(data);
+}
+
+/**
+ * Pick the molstar format id for a molfile of unknown version, and refuse the
+ * ones that would render nothing.
+ *
+ * molstar's `mol` parser does not understand a V3000 CTAB: it returns zero atoms
+ * with `isError: false`, so the viewer shows an empty scene and reports no
+ * error. The version is read from the text rather than assumed from whichever
+ * writer produced it, because the text is the only thing molstar itself looks
+ * at.
+ * @param data - A molfile, V2000 or V3000.
+ * @returns The format id paired with the unchanged text.
+ * @throws {Error} When the molfile carries no atoms — the silent failure this guards.
+ */
+export function readMolfileExport(data: string): MolfileExport {
+  const { version, atomCount } = classifyMolfile(data);
+  if (atomCount === 0) {
+    throw new Error(
+      'Molfile has an empty atom block: molstar would render an empty scene without reporting an error.',
+    );
+  }
+  return { format: version === 'v3000' ? 'sdf' : 'mol', data };
+}
+
+const V2000_MAX_ATOMS = 999;

package/src/structure/core/oclResources.ts

@@ -0,0 +1,41 @@
+import { Resources } from 'openchemlib';
+
+/**
+ * Register OpenChemLib's static resources once, without which
+ * `ConformerGenerator` and `ForceFieldMMFF94` throw on construction.
+ *
+ * Repeated calls share the first call's promise; a failed registration is
+ * forgotten so a later call can retry.
+ * @param url - Where to fetch `resources.json`. Omit under Node.js to read it
+ * from the installed package; in a browser or a worker it is required.
+ * @returns A promise that settles once the resources are usable.
+ */
+export function registerResources(url?: string): Promise<void> {
+  registration ??= register(url).catch((error: unknown) => {
+    registration = null;
+    throw error;
+  });
+  return registration;
+}
+
+let registration: Promise<void> | null = null;
+
+async function register(url?: string): Promise<void> {
+  if (url !== undefined) {
+    await Resources.registerFromUrl(url);
+    return;
+  }
+  const runtime = globalThis as { process?: { versions?: { node?: string } } };
+  if (runtime.process?.versions?.node === undefined) {
+    throw new Error(
+      'registerResources needs a url outside Node.js: a browser page or worker cannot read resources.json from node_modules',
+    );
+  }
+  const { createRequire } = await import('node:module');
+  const require = createRequire(import.meta.url);
+  Resources.registerFromNodejs(
+    require
+      .resolve('openchemlib')
+      .replace(/openchemlib\.js$/, 'resources.json'),
+  );
+}

package/src/translate/core/catalog.ts

@@ -0,0 +1,83 @@
+/**
+ * The shape of the messages a site or a library owns, and where they are kept.
+ *
+ * A catalog is one directory of a repository holding `en.json`, the source of
+ * truth, and one flat file per locale beside it. The site registers each of
+ * its catalogs with the repository and the directory, so a translation made
+ * anywhere on the page can be sent back to the file it belongs to.
+ */
+
+/** Messages by key; every value is an ICU MessageFormat string. */
+export type Messages = Record<string, string>;
+
+/** The locale every catalog is written in first. */
+export const SOURCE_LOCALE = 'en';
+
+/** One catalog a page renders messages from. */
+export interface CatalogSource {
+  /**
+   * The name the page knows the catalog by, unique on the page, e.g.
+   * `translate.cheminfo.org` or `react-cheminfo/share`.
+   */
+  id: string;
+  /** The GitHub repository the files live in, written `owner/repo`. */
+  repository: string;
+  /**
+   * The directory holding `en.json` and the locale files, relative to the
+   * repository root, e.g. `frontend/src/locales`.
+   */
+  directory: string;
+  /** The English messages. */
+  messages: Messages;
+}
+
+/** Which message of which catalog. */
+export interface MessageRef {
+  /** The catalog, by the id the page registered it under. */
+  catalogId: string;
+  /** The key of the message in that catalog. */
+  key: string;
+}
+
+const DIRECTORY_SEGMENT = /^[\w-][\w.-]*$/;
+
+/**
+ * The message a catalog holds under a key, never one inherited from
+ * `Object.prototype`: a key like `constructor` is only a message when the
+ * catalog defines it.
+ * @param messages - The catalog's messages.
+ * @param key - The key asked for.
+ * @returns The message, or `undefined` when the catalog has none.
+ */
+export function ownMessage(
+  messages: Messages,
+  key: string,
+): string | undefined {
+  return Object.hasOwn(messages, key) ? messages[key] : undefined;
+}
+
+/**
+ * Whether a path can name a catalog directory: relative, without `.` or `..`
+ * segments, and ending in a directory called `locales`. The server only ever
+ * writes inside such a directory.
+ * @param value - The candidate path, e.g. `frontend/src/locales`.
+ * @returns True when the path is acceptable.
+ */
+export function isCatalogDirectory(value: string): boolean {
+  const segments = value.split('/');
+  if (segments.at(-1) !== 'locales') return false;
+  for (const segment of segments) {
+    if (!DIRECTORY_SEGMENT.test(segment)) return false;
+  }
+  return true;
+}
+
+/**
+ * The file a catalog keeps one locale's messages in.
+ * @param directory - The catalog directory.
+ * @param locale - The locale.
+ * @returns The path, relative to the repository root.
+ */
+export function catalogFile(directory: string, locale: string): string {
+  return `${directory}/${locale}.json`;
+}

package/src/translate/core/checkTranslation.ts

@@ -0,0 +1,128 @@
+import type { MessageFormatElement } from '@formatjs/icu-messageformat-parser';
+import { TYPE, parse } from '@formatjs/icu-messageformat-parser';
+
+/** What can be wrong with one translated message. */
+export type MessageProblemKind =
+  | 'empty'
+  | 'syntax'
+  | 'source-syntax'
+  | 'missing-argument'
+  | 'unknown-argument';
+
+/** One thing wrong with a translated message, worded for the translator. */
+export interface MessageProblem {
+  /** What kind of problem it is. */
+  kind: MessageProblemKind;
+  /** The sentence the translator reads. */
+  message: string;
+  /**
+   * The placeholder or tag the problem is about, written as it appears in a
+   * message: `{count}` or `<link>`.
+   * @default undefined
+   */
+  argument?: string;
+}
+
+/**
+ * Check a translation against the English message it translates: it must be
+ * a valid ICU message and use exactly the placeholders and tags of the source.
+ * @param source - The English message.
+ * @param translation - The translated message.
+ * @returns Every problem found; empty when the translation can be used.
+ */
+export function checkTranslation(
+  source: string,
+  translation: string,
+): MessageProblem[] {
+  if (translation.trim() === '') {
+    return [{ kind: 'empty', message: 'The translation is empty.' }];
+  }
+
+  let expected: Set<string>;
+  try {
+    expected = messageArguments(source);
+  } catch (error) {
+    return [
+      {
+        kind: 'source-syntax',
+        message: `The English message itself is not valid: ${describe(error)}`,
+      },
+    ];
+  }
+
+  let actual: Set<string>;
+  try {
+    actual = messageArguments(translation);
+  } catch (error) {
+    return [{ kind: 'syntax', message: describe(error) }];
+  }
+
+  const problems: MessageProblem[] = [];
+  for (const argument of expected) {
+    if (!actual.has(argument)) {
+      problems.push({
+        kind: 'missing-argument',
+        argument,
+        message: `${argument} is in the English message but not in the translation.`,
+      });
+    }
+  }
+  for (const argument of actual) {
+    if (!expected.has(argument)) {
+      problems.push({
+        kind: 'unknown-argument',
+        argument,
+        message: `${argument} is not in the English message, so nothing would fill it.`,
+      });
+    }
+  }
+  return problems;
+}
+
+/**
+ * The placeholders and tags a message uses, each written as it appears in the
+ * message: `{count}` for an argument, `<link>` for a tag.
+ * @param message - An ICU message.
+ * @returns The set of placeholders and tags.
+ * @throws {SyntaxError} When the message does not parse.
+ */
+export function messageArguments(message: string): Set<string> {
+  const found = new Set<string>();
+  collect(parse(message), found);
+  return found;
+}
+
+function collect(elements: MessageFormatElement[], found: Set<string>): void {
+  for (const element of elements) {
+    switch (element.type) {
+      case TYPE.argument:
+      case TYPE.number:
+      case TYPE.date:
+      case TYPE.time:
+        found.add(`{${element.value}}`);
+        break;
+      case TYPE.select:
+      case TYPE.plural:
+        found.add(`{${element.value}}`);
+        for (const option of Object.values(element.options)) {
+          collect(option.value, found);
+        }
+        break;
+      case TYPE.tag:
+        found.add(`<${element.value}>`);
+        collect(element.children, found);
+        break;
+      case TYPE.literal:
+      case TYPE.pound:
+        break;
+      // no default
+    }
+  }
+}
+
+function describe(error: unknown): string {
+  if (error instanceof Error) {
+    return `The message does not parse (${error.message}).`;
+  }
+  return 'The message does not parse.';
+}

package/src/translate/core/contribution.ts

@@ -0,0 +1,99 @@
+/**
+ * What the overlay sends the server, and what the server answers.
+ */
+
+import type { Messages } from './catalog.ts';
+
+/** The longest message a contribution may carry, in characters. */
+export const MAX_MESSAGE_LENGTH = 5000;
+
+/** The most messages one catalog of a contribution may carry. */
+export const MAX_MESSAGES_PER_CATALOG = 2000;
+
+/** The most catalogs one contribution may carry. */
+export const MAX_CATALOGS = 32;
+
+/** The longest name a translator may be credited under. */
+export const MAX_CONTRIBUTOR_LENGTH = 100;
+
+/** The longest note a translator may leave for the reviewer. */
+export const MAX_NOTE_LENGTH = 1000;
+
+/** The messages translated for one catalog. */
+export interface ContributionCatalog {
+  /** The repository the catalog lives in, written `owner/repo`. */
+  repository: string;
+  /** The catalog directory, relative to the repository root. */
+  directory: string;
+  /** The translated messages by key. */
+  messages: Messages;
+}
+
+/** One submission from the overlay. */
+export interface Contribution {
+  /** The locale the messages are written in. */
+  locale: string;
+  /** The translated messages, catalog by catalog. */
+  catalogs: ContributionCatalog[];
+  /**
+   * The name the pull request credits.
+   * @default undefined
+   */
+  contributor?: string;
+  /**
+   * A note for whoever reviews the pull request.
+   * @default undefined
+   */
+  note?: string;
+  /**
+   * Continuation tokens of pull requests this translator opened before: a
+   * repository that has an open one gets a new commit there, not a new PR.
+   * @default []
+   */
+  continuations?: string[];
+}
+
+/** A pull request a contribution opened or added to. */
+export interface ContributionPullRequest {
+  /** The repository the pull request is on, `owner/repo`. */
+  repository: string;
+  /** Its number. */
+  number: number;
+  /** Where to read it. */
+  url: string;
+  /** How many messages this contribution changed in it. */
+  messageCount: number;
+  /** Whether an existing pull request was added to rather than opened. */
+  updated: boolean;
+  /** The token that lets the same translator add to it next time. */
+  continuation: string;
+}
+
+/** What a successful submission answers. */
+export interface ContributionResult {
+  /** One entry per repository that changed; empty when nothing did. */
+  pullRequests: ContributionPullRequest[];
+}
+
+/** One reason a submission was refused. */
+export interface ContributionProblem {
+  /** The repository concerned. */
+  repository: string;
+  /** The catalog directory concerned. */
+  directory: string;
+  /**
+   * The message concerned, when the problem is about one.
+   * @default undefined
+   */
+  key?: string;
+  /** The sentence the translator reads. */
+  message: string;
+}
+
+/** What a refused submission answers. */
+export interface ContributionRejection {
+  /** A summary of why. */
+  error: string;
+  /** Every problem found. */
+  problems: ContributionProblem[];
+}

package/src/translate/core/index.ts

@@ -0,0 +1,72 @@
+// Both travel with the catalogs: a server validating a submission and naming
+// the language in a pull request must not have to load the whole of
+// `react-cheminfo/core` to do it.
+export { languageName } from '../../language/core/languageName.ts';
+export { isLanguageTag } from '../../language/core/languageParam.ts';
+export type { CatalogSource, MessageRef, Messages } from './catalog.ts';
+export {
+  SOURCE_LOCALE,
+  catalogFile,
+  isCatalogDirectory,
+  ownMessage,
+} from './catalog.ts';
+export type { MessageProblem, MessageProblemKind } from './checkTranslation.ts';
+export { checkTranslation, messageArguments } from './checkTranslation.ts';
+export type {
+  Contribution,
+  ContributionCatalog,
+  ContributionProblem,
+  ContributionPullRequest,
+  ContributionRejection,
+  ContributionResult,
+} from './contribution.ts';
+export {
+  MAX_CATALOGS,
+  MAX_CONTRIBUTOR_LENGTH,
+  MAX_MESSAGES_PER_CATALOG,
+  MAX_MESSAGE_LENGTH,
+  MAX_NOTE_LENGTH,
+} from './contribution.ts';
+export {
+  encodeMarker,
+  hasMarker,
+  markText,
+  readMarkers,
+  stripMarkers,
+} from './marker.ts';
+export {
+  changedKeys,
+  mergeMessages,
+  parseMessages,
+  serializeMessages,
+} from './mergeMessages.ts';
+export type {
+  CatalogSnapshot,
+  MessageValues,
+  TranslateBridge,
+  TranslateSessionOptions,
+} from './session.ts';
+export { BRIDGE_GLOBAL, BRIDGE_PROTOCOL, TranslateSession } from './session.ts';
+export type { LoadOverlayOptions, StartTranslatingOptions } from './start.ts';
+export {
+  TRANSLATE_ORIGIN,
+  TRANSLATE_PARAM,
+  loadOverlay,
+  readTranslateLocale,
+  startTranslating,
+} from './start.ts';
+export type {
+  MessageSuggestion,
+  SuggestionKind,
+  SuggestionOptions,
+  TranslatedPair,
+} from './suggestions.ts';
+export { messageSimilarity, messageSuggestions } from './suggestions.ts';
+export type {
+  TableCell,
+  TranslatableField,
+  TranslatableFieldSize,
+  TranslatableRow,
+  TranslatableTable,
+} from './tables.ts';
+export { tableCells, tableKey } from './tables.ts';

package/src/translate/core/marker.ts

@@ -0,0 +1,85 @@
+/**
+ * The invisible mark a message carries while a page is being translated.
+ *
+ * In translate mode every formatted message is prefixed with its id, written
+ * in characters that take no space and join nothing. Whatever the string then
+ * becomes — a text node, a `title`, a `placeholder`, a prop handed to a
+ * third-party component — the overlay finds it in the DOM and knows which
+ * message it is, without any component having been written for it.
+ *
+ * The digits are the invisible mathematical operators U+2061–U+2064, closed by
+ * WORD JOINER U+2060: none of them is whitespace, none joins emoji the way
+ * ZERO WIDTH JOINER does, and all are default-ignorable, so fonts draw nothing.
+ */
+
+const DIGITS = ['⁡', '⁢', '⁣', '⁤'] as const;
+const END = '⁠';
+const BASE = DIGITS.length;
+const FIRST_DIGIT = 0x20_61;
+
+const MARKER = /[⁡-⁤]+⁠/;
+const MARKERS = /[⁡-⁤]+⁠/g;
+
+/**
+ * Write a message id as an invisible marker.
+ * @param id - The id, a non-negative integer.
+ * @returns The marker, to be put in front of the formatted message.
+ */
+export function encodeMarker(id: number): string {
+  if (!Number.isSafeInteger(id) || id < 0) {
+    throw new RangeError(`a marker id is a non-negative integer, got ${id}`);
+  }
+  let digits = '';
+  let rest = id;
+  do {
+    digits = `${DIGITS[rest % BASE]}${digits}`;
+    rest = Math.floor(rest / BASE);
+  } while (rest > 0);
+  return `${digits}${END}`;
+}
+
+/**
+ * Prefix a formatted message with the marker of its id.
+ * @param text - The message as it will be shown.
+ * @param id - The id of the message.
+ * @returns The same text, with the invisible marker in front.
+ */
+export function markText(text: string, id: number): string {
+  return `${encodeMarker(id)}${text}`;
+}
+
+/**
+ * The ids of every message a string carries, in the order they appear.
+ * @param text - A text node's data or an attribute's value.
+ * @returns The ids; empty when the string holds no marker.
+ */
+export function readMarkers(text: string): number[] {
+  const ids: number[] = [];
+  for (const match of text.matchAll(MARKERS)) {
+    const marker = match[0];
+    let id = 0;
+    for (let index = 0; index < marker.length - 1; index++) {
+      id = id * BASE + (marker.codePointAt(index) ?? FIRST_DIGIT) - FIRST_DIGIT;
+    }
+    ids.push(id);
+  }
+  return ids;
+}
+
+/**
+ * Whether a string carries at least one marker.
+ * @param text - The string to look at.
+ * @returns True when a marker is present.
+ */
+export function hasMarker(text: string): boolean {
+  return MARKER.test(text);
+}
+
+/**
+ * The string with every marker removed, as it reads outside translate mode.
+ * @param text - A string that may carry markers.
+ * @returns The visible text only.
+ */
+export function stripMarkers(text: string): string {
+  return text.replaceAll(MARKERS, '');
+}