react-cheminfo 0.23.0 → 0.24.0

package/src/translate/core/tables.ts

@@ -0,0 +1,120 @@
+/**
+ * The tables of a site whose rows are translated: the element sheet, a list of
+ * ions, the rules of a nomenclature.
+ *
+ * A site's prose is not only its interface. Most of what a chemistry tool
+ * shows is a table, and a table mixes two kinds of column: what was measured
+ * or computed — an atomic number, a mass, a formula, an identifier — and what
+ * was written — a name, where the name comes from, a note. The first kind is
+ * the same in every language and must never reach a translator; the second is
+ * exactly what a translator is for.
+ *
+ * The line between them is drawn once, here. A site declares its tables, and
+ * only a field it declares can be edited, in a catalog key built the same way
+ * everywhere:
+ *
+ * ```text
+ * <table>.<row>.<field>     element.Fe.name, element.Fe.origin
+ * ```
+ *
+ * Everything else about the row — the mass, the density, the id itself — stays
+ * in the data the site generates from its source, out of reach.
+ */
+
+/** How much room a field's text needs, which is how the editor draws it. */
+export type TranslatableFieldSize = 'line' | 'paragraph';
+
+/** One translated column of a table. */
+export interface TranslatableField {
+  /** Last part of the key, e.g. `name`. */
+  id: string;
+  /** What the column is called in the editor, in English. */
+  label: string;
+  /**
+   * How much text it holds, which is whether the editor gives it one line or
+   * a box.
+   * @default 'line'
+   */
+  size?: TranslatableFieldSize;
+  /**
+   * Whether every row is expected to carry it, so the editor can say what is
+   * still missing rather than only what is there.
+   * @default false
+   */
+  required?: boolean;
+  /**
+   * One sentence telling the translator what the column is, shown above the
+   * column in the editor.
+   * @default undefined
+   */
+  hint?: string;
+}
+
+/** One row of a table. */
+export interface TranslatableRow {
+  /** Middle part of the key, e.g. `Fe`. */
+  id: string;
+  /**
+   * What names the row in the editor — an atomic number and a symbol, a
+   * formula. It is data, never translated, and never a key.
+   */
+  label: string;
+}
+
+/** A table whose rows carry translated text. */
+export interface TranslatableTable {
+  /** First part of the key, e.g. `element`. */
+  id: string;
+  /** What the table is called in the editor, in English. */
+  label: string;
+  /** The catalog its keys belong to, as the page registered it. */
+  catalogId: string;
+  /** The columns a translator may write, in the order the editor shows them. */
+  fields: readonly TranslatableField[];
+  /** The rows, in the order the editor lists them. */
+  rows: readonly TranslatableRow[];
+}
+
+/**
+ * The key one field of one row is kept under.
+ * @param table - The table the row belongs to.
+ * @param rowId - The row.
+ * @param fieldId - The column.
+ * @returns The catalog key, e.g. `element.Fe.name`.
+ */
+export function tableKey(
+  table: Pick<TranslatableTable, 'id'>,
+  rowId: string,
+  fieldId: string,
+): string {
+  return `${table.id}.${rowId}.${fieldId}`;
+}
+
+/**
+ * Every key a table can hold, row by row and field by field.
+ *
+ * It is what the editor walks to draw the grid, and what tells it which cells
+ * are still empty: a key absent from the catalog is a translation nobody has
+ * written yet, not a field that does not exist.
+ * @param table - The table to walk.
+ * @returns One entry per cell, in reading order.
+ */
+export function tableCells(table: TranslatableTable): TableCell[] {
+  const cells: TableCell[] = [];
+  for (const row of table.rows) {
+    for (const field of table.fields) {
+      cells.push({ key: tableKey(table, row.id, field.id), row, field });
+    }
+  }
+  return cells;
+}
+
+/** One cell of a table: where it is, and what it is kept under. */
+export interface TableCell {
+  /** The catalog key. */
+  key: string;
+  /** The row it belongs to. */
+  row: TranslatableRow;
+  /** The column it belongs to. */
+  field: TranslatableField;
+}

package/src/translate.ts

@@ -0,0 +1,5 @@
+// Everything a page, an overlay or a server needs to translate a site of the
+// family: the catalogs, the invisible marker, the checks, and the session a
+// page in translate mode hands to the overlay. It is its own entry point
+// because an ordinary visit loads none of it.
+export * from './translate/core/index.ts';

package/src/ui.ts

@@ -14,6 +14,7 @@ export * from './ecosystem/ui/index.ts';
 export * from './error/ui/index.ts';
 export * from './help/ui/index.ts';
 export * from './hooks/ui/index.ts';
+export * from './language/ui/index.ts';
 export * from './overlay/ui/index.ts';
 export * from './parallel/ui/index.ts';
 export * from './pedagogy/ui/index.ts';

package/src/xtb/core/xtbRelaxer.ts

@@ -0,0 +1,160 @@
+import type * as XtbWasm from 'xtb-wasm';
+
+import { errorMessage } from '../../error/core/toError.ts';
+import type {
+  GeometryRelaxer,
+  RelaxableGeometry,
+  RelaxedGeometry,
+  RelaxerOptions,
+} from '../../structure/core/geometryRelaxer.ts';
+
+/**
+ * kcal/mol per hartree, CODATA 2018. Every energy a relaxer reports is in
+ * kcal/mol, so it can be read against a force-field energy without the reader
+ * converting anything.
+ */
+export const KCAL_PER_MOL_PER_HARTREE = 627.509_474_063_1;
+
+/** How many occjs instances a relaxation may use. */
+export interface XtbRelaxerOptions {
+  /**
+   * Hard cap on the number of GFN2 instances. Each one costs about 100 MB of
+   * WebAssembly memory, so a long batch on a small machine is worth capping.
+   * @default one per structure, one below the core count
+   */
+  maxWorkers?: number;
+  /**
+   * Total molecular charge in units of e, applied to every structure.
+   * @default 0
+   */
+  charge?: number;
+  /**
+   * Unpaired electrons, applied to every structure. `1` for a doublet radical.
+   * @default 0
+   */
+  unpairedElectrons?: number;
+  /**
+   * Cycle budget of one optimization.
+   * @default 250
+   */
+  maxCycles?: number;
+}
+
+/**
+ * GFN2-xTB as a {@link GeometryRelaxer}: the second stage that decides how good
+ * a force field's conformers really are.
+ *
+ * `xtb-wasm` is loaded on the **first call**, never on the import, so a page that
+ * offers refinement as an action downloads the 21.5 MB WebAssembly only once a
+ * visitor asks for it. The module is cached afterwards, and the worker pool it
+ * starts is kept alive between calls.
+ *
+ * Energies come back in kcal/mol, which is the unit `conformer.energy` is
+ * already in.
+ * @param options - Instance cap, charge, spin and the cycle budget.
+ * @returns A relaxer to hand to `refineConformers`, or to call directly.
+ */
+export function xtbRelaxer(options: XtbRelaxerOptions = {}): GeometryRelaxer {
+  return async (
+    geometries: readonly RelaxableGeometry[],
+    runOptions: RelaxerOptions = {},
+  ): Promise<RelaxedGeometry[]> => {
+    const xtb = await loadXtb();
+    const settings = {
+      charge: options.charge ?? 0,
+      unpairedElectrons: options.unpairedElectrons ?? 0,
+      ...(options.maxCycles === undefined
+        ? {}
+        : { maxCycles: options.maxCycles }),
+    };
+    const requests = geometries.map((geometry) => ({ geometry, settings }));
+    const results = isXtbRelaxerAvailable()
+      ? await xtb.relaxGeometries(requests, {
+          maxWorkers: options.maxWorkers,
+          onSettled: runOptions.onSettled,
+          signal: runOptions.signal,
+        })
+      : await relaxHere(xtb, requests, runOptions);
+    const relaxed: RelaxedGeometry[] = [];
+    for (const result of results) {
+      relaxed.push({
+        coordinates: result.coordinates,
+        energy: result.energy.total * KCAL_PER_MOL_PER_HARTREE,
+        dispersionEnergy:
+          result.energy.dispersion === null
+            ? null
+            : result.energy.dispersion * KCAL_PER_MOL_PER_HARTREE,
+        cycles: result.cycles,
+        converged: result.converged,
+        warnings: result.warnings,
+      });
+    }
+    return relaxed;
+  };
+}
+
+/**
+ * Whether this environment has the worker pool the relaxer prefers.
+ *
+ * Without `Worker` — Node, a prerender pass, a test run — the relaxer still
+ * works, one structure at a time on the calling thread, so a site keeps one code
+ * path. It is the caller's business only when the difference in speed matters.
+ * @returns `true` in a browser, `false` in a plain Node process.
+ */
+export function isXtbRelaxerAvailable(): boolean {
+  return typeof Worker !== 'undefined';
+}
+
+/**
+ * Drop the GFN2 worker pool and the memory it holds, about 100 MB per instance.
+ * The next relaxation starts a fresh one.
+ */
+export async function disposeXtbRelaxer(): Promise<void> {
+  const loaded = await pending;
+  loaded?.disposeOccPool();
+}
+
+/**
+ * Relax one structure after another on this thread, for want of a pool.
+ * @param xtb - The loaded `xtb-wasm` module.
+ * @param requests - The structures to relax, with their settings.
+ * @param runOptions - Progress and cancellation.
+ * @returns One `xtb-wasm` result per request, in request order.
+ * @throws {Error} When the run is cancelled, or when occ fails.
+ */
+async function relaxHere(
+  xtb: XtbModule,
+  requests: ReadonlyArray<Parameters<XtbModule['relaxGeometryInProcess']>[0]>,
+  runOptions: RelaxerOptions,
+): Promise<Array<Awaited<ReturnType<XtbModule['relaxGeometryInProcess']>>>> {
+  const results = [];
+  for (const [index, request] of requests.entries()) {
+    if (runOptions.signal?.aborted === true) {
+      throw new Error('calculation cancelled');
+    }
+    /* eslint-disable-next-line no-await-in-loop -- there is one thread: the
+       whole point of this path is that the structures run in turn. */
+    results.push(await xtb.relaxGeometryInProcess(request));
+    runOptions.onSettled?.(index + 1, requests.length);
+  }
+  return results;
+}
+
+type XtbModule = typeof XtbWasm;
+
+let pending: Promise<XtbModule> | null = null;
+
+function loadXtb(): Promise<XtbModule> {
+  pending ??= import('xtb-wasm').catch((error: unknown) => {
+    // A failed chunk load must not poison every later call of the session.
+    pending = null;
+    // The reason is in the message, not only in `cause`: what a reader sees is
+    // whatever the UI renders, and "could not be loaded" alone names neither a
+    // missing install nor a chunk that failed to come down the wire.
+    throw new Error(
+      `xtb-wasm could not be loaded, so geometries cannot be refined: ${errorMessage(error)}`,
+      { cause: error },
+    );
+  });
+  return pending;
+}

package/src/xtb.ts

@@ -0,0 +1,16 @@
+/**
+ * GFN2-xTB, the opt-in second stage after a force field.
+ *
+ * Its own door because it drags `xtb-wasm` and a 21.5 MB WebAssembly binary
+ * behind it, and because most pages never refine anything. The contract it
+ * implements — `GeometryRelaxer` — lives in `react-cheminfo/core`, so the code
+ * that orchestrates a refinement (`refineConformers`) loads none of this.
+ */
+
+export type { XtbRelaxerOptions } from './xtb/core/xtbRelaxer.ts';
+export {
+  KCAL_PER_MOL_PER_HARTREE,
+  disposeXtbRelaxer,
+  isXtbRelaxerAvailable,
+  xtbRelaxer,
+} from './xtb/core/xtbRelaxer.ts';

package/styles/chrome.css

@@ -170,6 +170,47 @@ button {
   flex: 1;
 }
 
+/* A utility of the bar is its glyph: the name it carries is the tooltip and the
+   accessible name, never written beside it. About, Cite, Tools and Share read
+   as four marks the eye passes over, and the pages keep the width the labels
+   would take — which in a long language is most of the bar. An entry with no
+   glyph keeps its text, or it would be left an empty button: that is how a
+   toggle of the bar still shows the value it is set to. */
+.app-header-actions .nav-link--icon .nav-link__label,
+.app-header-actions
+  .bp6-button:has(> .bp6-icon:not(.bp6-icon-caret-down))
+  > .bp6-button-text,
+.app-header-actions
+  .bp6-button:has(> .bp6-icon:not(.bp6-icon-caret-down))
+  > .bp6-icon-caret-down {
+  display: none;
+}
+
+.app-header-actions .nav-link--icon,
+.citation-button .bp6-button,
+.ecosystem-button .bp6-button {
+  padding: 0.3rem 0.5rem;
+}
+
+/* A setting the bar shows as its own values — the language, the scale a
+   temperature is read on — the one in force pressed. The values carry no
+   glyph, which is what keeps them written where a utility is only its mark. */
+.site-toggle .bp6-button {
+  padding: 0.25rem 0.4rem;
+  color: var(--text-muted);
+  font-size: 0.8125rem;
+  font-weight: 500;
+}
+
+.site-toggle .bp6-button.bp6-active {
+  color: var(--text);
+}
+
+/* Narrow: the one value in force, a click away from the next. */
+.site-toggle--compact {
+  color: var(--text);
+}
+
 /* Carried by a link and by a button alike, so the whole row reads as one menu
    rather than as a button dropped among addresses. */
 .nav-link {
@@ -257,29 +298,11 @@ button {
   flex: none;
 }
 
-/* The utilities give up their labels and keep their icons. An entry with no
-   icon keeps its label, or it would be left an empty button. */
 @container app-header (max-width: 48rem) {
   .app-header__inner {
     padding: 0 0.75rem;
     gap: 0.5rem;
   }
-
-  .app-header-actions .nav-link--icon .nav-link__label,
-  .app-header-actions
-    .bp6-button:has(> .bp6-icon:not(.bp6-icon-caret-down))
-    > .bp6-button-text,
-  .app-header-actions
-    .bp6-button:has(> .bp6-icon:not(.bp6-icon-caret-down))
-    > .bp6-icon-caret-down {
-    display: none;
-  }
-
-  .app-header-actions .nav-link--icon,
-  .citation-button .bp6-button,
-  .ecosystem-button .bp6-button {
-    padding: 0.3rem 0.5rem;
-  }
 }
 
 /* A phone: the pages fold into one menu beside the brand. */
@@ -365,14 +388,25 @@ select,
 
 /* ── Click to copy ───────────────────────────────────────────────────────── */
 
-/* The copy cursor, the tint and the clipboard glyph are the promise; a tick
-   keeps it. The glyph is `clipboard`, never `duplicate`: two overlapping squares
-   read as "add another". Green and red are the confirmation's own colours,
-   the ones Blueprint gives success and danger. */
+/* The cursor is the promise: a pointer carrying a clipboard, so the hover says
+   "click and this is yours" without a glyph crowding the line of text. The OS
+   `copy` cursor is not it — its badge is a plus, which reads as "add". The glyph
+   stays for what the cursor cannot say: the tick or cross after a click, and the
+   affordance for a keyboard, which has no pointer. Green and red are the
+   confirmation's own colours, the ones Blueprint gives success and danger. */
+:root {
+  /* A cursor is a file of its own and cannot read a token, so its ink and its
+     halo are literal; the halo is what keeps it legible on a dark background. */
+  --cursor-copy:
+    url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' width='24' height='24'%3E%3Cpath d='M1 1 1 17 5 13 7.5 18.5 10 17.4 7.6 12.4 12 12.4Z' fill='%231c2127' stroke='%23ffffff' stroke-width='2' stroke-linejoin='round' paint-order='stroke'/%3E%3Crect x='13' y='11.5' width='10' height='11.5' rx='2' fill='%231c2127' stroke='%23ffffff' stroke-width='2' paint-order='stroke'/%3E%3Crect x='15.5' y='9.8' width='5' height='3.6' rx='1.2' fill='%231c2127' stroke='%23ffffff' stroke-width='1.6' paint-order='stroke'/%3E%3C/svg%3E")
+      1 1,
+    copy;
+}
+
 .click-to-copy {
   position: relative;
   border-radius: 4px;
-  cursor: copy;
+  cursor: var(--cursor-copy);
   transition: background-color 120ms ease;
 }
 
@@ -398,8 +432,9 @@ select,
   transition: opacity 120ms ease;
 }
 
-/* In a line of text the glyph floats just past the value, so the line keeps
-   its spacing; a block keeps room for it inside its right edge. */
+/* The glyph is shown to a keyboard and after a copy, never on hover. In a line
+   of text it floats just past the value, so the line keeps its spacing; a block
+   keeps room for it inside its right edge. */
 .click-to-copy--inline .click-to-copy__icon {
   left: 100%;
   transform: translate(3px, -50%);
@@ -433,17 +468,13 @@ select,
   .click-to-copy:not([data-copy]):hover {
     background-color: color-mix(in oklab, var(--accent) 12%, transparent);
   }
-
-  .click-to-copy:hover .click-to-copy__icon {
-    opacity: 1;
-  }
 }
 
 /* Blueprint's interactive and striped tables paint and point every cell from
    three classes deep, so a copyable cell repeats its class to stay ahead. */
 .click-to-copy.click-to-copy.click-to-copy.click-to-copy:is(td, th) {
   border-radius: 0;
-  cursor: copy;
+  cursor: var(--cursor-copy);
 }
 
 .click-to-copy.click-to-copy.click-to-copy.click-to-copy:is(