react-cheminfo 0.64.1 → 0.65.0

package/src/core.ts

@@ -1,6 +1,8 @@
 export * from './about/core/index.ts';
 export * from './axis/core/index.ts';
 export * from './build/core/index.ts';
+// The addresses of an answer's card, which a tool server writes in Node.
+export * from './card/core/index.ts';
 export * from './chart/core/index.ts';
 export * from './citation/core/index.ts';
 export * from './clipboard/core/index.ts';
@@ -11,9 +13,11 @@ export * from './delimited/core/index.ts';
 export * from './download/core/index.ts';
 export * from './ecosystem/core/index.ts';
 export * from './error/core/index.ts';
+export * from './fetch/core/index.ts';
 export * from './format/core/index.ts';
 export * from './i18n/core/index.ts';
 export * from './language/core/index.ts';
+export * from './moleculesClient/core/index.ts';
 export * from './moleculesSources/core/index.ts';
 export * from './moleculesToken/core/index.ts';
 export * from './number/core/index.ts';
@@ -24,6 +28,7 @@ export * from './parallel/core/index.ts';
 export * from './pedagogy/core/index.ts';
 export * from './periodic/core/index.ts';
 export * from './projection/core/index.ts';
+export * from './property/core/index.ts';
 export * from './range/core/index.ts';
 export * from './router/core/index.ts';
 export * from './scatter/core/index.ts';

package/src/fetch/core/apiError.ts

@@ -0,0 +1,65 @@
+/**
+ * A request a backend refused, or could not answer, with the reason it gave.
+ *
+ * `status` tells a refusal worth retrying from one that is final — a job still
+ * running from one that is gone — and `message` is written for the reader.
+ */
+export class ApiError extends Error {
+  override name = 'ApiError';
+  /**
+   * The status of the refusal: the envelope's `statusCode` when it names one,
+   * else the response's. 0 when the server could not be reached at all.
+   */
+  readonly status: number;
+  /**
+   * The short name Fastify gives the status, e.g. `Not Found`; the response's
+   * status text when the body names none.
+   */
+  readonly error: string;
+  /**
+   * The body of the refusal as read — the parsed JSON, or the text when it was
+   * none — for a field the envelope does not name.
+   */
+  readonly body: unknown;
+
+  /**
+   * Name a refusal.
+   * @param message - The reason, written for the reader.
+   * @param options - The status, its name, the body and what caused it.
+   */
+  constructor(message: string, options: ApiErrorOptions) {
+    super(message, { cause: options.cause });
+    this.status = options.status;
+    this.error = options.error ?? '';
+    this.body = options.body;
+  }
+
+  /**
+   * The status, under the name Fastify's envelope gives it.
+   * @returns The same number as `status`.
+   */
+  get statusCode(): number {
+    return this.status;
+  }
+}
+
+/** What an {@link ApiError} is built from. */
+export interface ApiErrorOptions {
+  /** The status of the refusal, 0 when the server could not be reached. */
+  status: number;
+  /**
+   * The short name of the status.
+   * @default ''
+   */
+  error?: string;
+  /**
+   * The body of the refusal as read.
+   * @default undefined
+   */
+  body?: unknown;
+  /**
+   * What the error was raised from.
+   * @default undefined
+   */
+  cause?: unknown;
+}

package/src/fetch/core/fetchJson.ts

@@ -0,0 +1,129 @@
+/**
+ * One JSON request to one of our backends, and its refusal as an error a page
+ * can show.
+ *
+ * Our backends are Fastify, and a refusal comes back as `{ statusCode, error,
+ * message }`: the message is written for the reader, so it is what the error
+ * says. Nothing here needs more than `fetch`, so it runs in a page, a worker
+ * and Node alike.
+ */
+
+import { ApiError } from './apiError.ts';
+
+/**
+ * Ask a backend one question and read its JSON answer.
+ *
+ * A refusal rejects with an {@link ApiError} carrying the server's own words
+ * and its status; a server that cannot be reached rejects with one of status
+ * 0. An abort is passed on untouched, so a caller tells "nobody asked any
+ * more" from a failure by the signal it aborted. A `204`, or an empty body,
+ * answers `undefined`.
+ * @param url - The address, absolute or relative to the page.
+ * @param options - The request, plus a `json` body and the `fetch` to use.
+ * @returns The parsed answer.
+ * @throws {ApiError} When the server refuses, cannot be reached, or answers
+ * something that is not JSON.
+ */
+export async function fetchJson<T>(
+  url: string,
+  options: FetchJsonOptions = {},
+): Promise<T> {
+  const { json, fetch: send = globalThis.fetch, ...init } = options;
+  const headers = new Headers(init.headers);
+  if (!headers.has('Accept')) headers.set('Accept', 'application/json');
+  if (json !== undefined && !headers.has('Content-Type')) {
+    headers.set('Content-Type', 'application/json');
+  }
+  const body = json === undefined ? init.body : JSON.stringify(json);
+
+  let response: Response;
+  try {
+    response = await send(url, { ...init, headers, body });
+  } catch (error) {
+    if (init.signal?.aborted === true) throw error;
+    throw new ApiError('the server could not be reached', {
+      status: 0,
+      error: 'Network Error',
+      cause: error,
+    });
+  }
+  if (!response.ok) throw await readApiError(response);
+
+  const text = await response.text();
+  if (response.status === 204 || text === '') return undefined as T;
+  try {
+    return JSON.parse(text) as T;
+  } catch (error) {
+    throw new ApiError('the server answered with something that is not JSON', {
+      status: response.status,
+      body: text,
+      cause: error,
+    });
+  }
+}
+
+/**
+ * The error a refusal stands for, in the server's words when it gave any: the
+ * `message` of a Fastify envelope, else a FastAPI `detail`, else the status.
+ * @param response - The response that was not ok.
+ * @returns The error, its body read.
+ */
+export async function readApiError(response: Response): Promise<ApiError> {
+  let body: unknown;
+  try {
+    const text = await response.text();
+    body = text === '' ? undefined : parseOrKeep(text);
+  } catch {
+    body = undefined;
+  }
+  const envelope = isRecord(body) ? body : {};
+  const status =
+    typeof envelope.statusCode === 'number'
+      ? envelope.statusCode
+      : response.status;
+  const error =
+    typeof envelope.error === 'string' ? envelope.error : response.statusText;
+  return new ApiError(refusalMessage(envelope, response), {
+    status,
+    error,
+    body,
+  });
+}
+
+/** What {@link fetchJson} is handed: a `fetch` request, and two additions. */
+export interface FetchJsonOptions extends RequestInit {
+  /**
+   * A value sent as the JSON body, with its content type; it replaces `body`.
+   * @default undefined — the request carries `body`, if any
+   */
+  json?: unknown;
+  /**
+   * The `fetch` to call: a session's own, which signs the request, or a
+   * stand-in in a test.
+   * @default globalThis.fetch
+   */
+  fetch?: typeof globalThis.fetch;
+}
+
+function refusalMessage(
+  envelope: Record<string, unknown>,
+  response: Response,
+): string {
+  const { message, detail } = envelope;
+  if (typeof message === 'string' && message !== '') return message;
+  if (typeof detail === 'string' && detail !== '') return detail;
+  const text = response.statusText === '' ? '' : ` ${response.statusText}`;
+  return `the server answered ${response.status}${text}`;
+}
+
+function parseOrKeep(text: string): unknown {
+  try {
+    return JSON.parse(text) as unknown;
+  } catch {
+    return text;
+  }
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}

package/src/fetch/core/index.ts

@@ -0,0 +1,4 @@
+export type { ApiErrorOptions } from './apiError.ts';
+export { ApiError } from './apiError.ts';
+export type { FetchJsonOptions } from './fetchJson.ts';
+export { fetchJson, readApiError } from './fetchJson.ts';

package/src/formula/core/formulaText.ts

@@ -0,0 +1,96 @@
+/**
+ * One formula written several ways: canonically, so two spellings compare
+ * equal; as HTML, so a paste keeps its subscripts; in Unicode, for prose.
+ */
+
+import { MF, ensureCase } from 'mf-parser';
+
+import { DEFAULT_LANGUAGE } from '../../i18n/core/languages.ts';
+
+import { normalizeFormula } from './normalizeFormula.ts';
+import type { FormulaOptions, ParsedFormula } from './readFormula.ts';
+import { FormulaError, parserMessage } from './readFormula.ts';
+
+/** What {@link canonicalFormula} is told beyond the text. */
+export interface CanonicalFormulaOptions extends FormulaOptions {
+  /**
+   * Whether a formula typed in the wrong case is fixed first, so `c9h6n4`
+   * reads as `C9H6N4`. A tool reading exact isotopes and charges leaves it
+   * off: case is what tells `Co` from `CO`.
+   * @default false
+   */
+  fixCase?: boolean;
+}
+
+/**
+ * The canonical spelling of a formula, so two spellings of one compound
+ * compare equal: `NaOH`, `HONa` and `NaHO` all give the same string.
+ * @param text - A formula as typed.
+ * @param options - Whether the case is fixed, and the language of a failure.
+ * @returns The canonical formula.
+ * @throws {FormulaError} When the text is not a formula.
+ */
+export function canonicalFormula(
+  text: string,
+  options: CanonicalFormulaOptions = {},
+): string {
+  const { fixCase = false, language = DEFAULT_LANGUAGE } = options;
+  const normalized = normalizeFormula(text);
+  try {
+    return new MF(fixCase ? ensureCase(normalized) : normalized).toMF();
+  } catch (error) {
+    throw new FormulaError(parserMessage(text, error, language));
+  }
+}
+
+/**
+ * Atom counts per element over a whole formula, isotopes folded into their
+ * element and every part added up.
+ * @param parsed - A formula as `readFormula` read it.
+ * @returns Symbol → count, in the order the formula first names each element.
+ */
+export function atomCounts(parsed: ParsedFormula): Map<string, number> {
+  const counts = new Map<string, number>();
+  for (const part of parsed.parts) {
+    for (const atom of part.atoms) {
+      counts.set(atom.symbol, (counts.get(atom.symbol) ?? 0) + atom.count);
+    }
+  }
+  return counts;
+}
+
+/**
+ * A formula as HTML, its subscripts and its charge marked up, so a value
+ * copied from the page keeps them when it is pasted into a document.
+ * @param text - A formula as typed.
+ * @returns The markup, or the text itself when it is not a formula.
+ */
+export function formulaHtml(text: string): string {
+  try {
+    return new MF(normalizeFormula(text)).toHtml();
+  } catch {
+    return text.trim();
+  }
+}
+
+/**
+ * A formula written for prose, with true subscripts and superscripts and its
+ * charge the way a chemist writes it: `NO₃⁻`, `Fe³⁺`, `²³⁸U¹⁹F₆`.
+ * @param text - A formula as typed.
+ * @returns The formula in Unicode, or the text itself when it is not one.
+ */
+export function formulaText(text: string): string {
+  let written: string;
+  try {
+    written = new MF(normalizeFormula(text)).toText();
+  } catch {
+    return text.trim();
+  }
+  return written
+    .replaceAll(/\s+•\s+/gu, '·')
+    .replace(
+      /(?<sign>[⁺⁻])(?<digits>[⁰¹²³⁴⁵⁶⁷⁸⁹]+)$/u,
+      (_match, sign: string, digits: string) =>
+        `${digits === '¹' ? '' : digits}${sign}`,
+    );
+}

package/src/formula/core/index.ts

@@ -0,0 +1,20 @@
+export type { CanonicalFormulaOptions } from './formulaText.ts';
+export {
+  atomCounts,
+  canonicalFormula,
+  formulaHtml,
+  formulaText,
+} from './formulaText.ts';
+export { normalizeFormula } from './normalizeFormula.ts';
+export type {
+  FormulaAtom,
+  FormulaOptions,
+  FormulaPart,
+  ParsedFormula,
+} from './readFormula.ts';
+export {
+  FormulaError,
+  atomicNumber,
+  elementName,
+  readFormula,
+} from './readFormula.ts';

package/src/formula/core/normalizeFormula.ts

@@ -0,0 +1,50 @@
+/**
+ * The ways a student types a charge or a hydrate, rewritten into the syntax
+ * `mf-parser` reads.
+ *
+ * The parser silently drops a trailing minus — `NO3-` would be read as neutral
+ * nitrate and `SO4--` as neutral sulfate — and reads the dot of `CuSO4.5H2O` as
+ * a decimal, giving `H2CuO5.5S`. Both are rewritten here, before the parser
+ * ever sees the text, rather than by every site that reads a formula.
+ */
+
+/**
+ * Rewrite the ways a charge and a hydrate are commonly typed into the syntax
+ * the parser reads.
+ *
+ * - `NO3-`, `SO4--`, `S2O3-2`, `CO3 2-`, `CO3^2-` → `NO3(-1)`, `SO4(-2)`, …
+ * - `CuSO4.5H2O`, `CuSO4·5H2O`, `CuSO4*5H2O` → `CuSO4 . 5H2O`
+ *
+ * A charge already written in parentheses, `Fe(3+)`, is left as it is.
+ * @param text - The formula as typed.
+ * @returns The formula the parser is given.
+ */
+export function normalizeFormula(text: string): string {
+  let formula = text.trim().replaceAll(/[·•*]/g, '.');
+  formula = formula.replaceAll(/\s*\.\s*/g, ' . ');
+
+  const separated =
+    /^(?<body>.*?\S)(?:\s+|\^)(?<digits>\d*)(?<signs>[+-]+)$/u.exec(formula);
+  if (separated?.groups) {
+    const { body = '', digits = '', signs = '' } = separated.groups;
+    return withCharge(body, signs, digits);
+  }
+  const signThenDigits =
+    /^(?<body>.*?[^\s(])(?<sign>[+-])(?<digits>\d+)$/u.exec(formula);
+  if (signThenDigits?.groups) {
+    const { body = '', sign = '', digits = '' } = signThenDigits.groups;
+    return withCharge(body, sign, digits);
+  }
+  const trailingSigns = /^(?<body>.*?[^\s+-])(?<signs>[+-]+)$/u.exec(formula);
+  if (trailingSigns?.groups) {
+    const { body = '', signs = '' } = trailingSigns.groups;
+    return withCharge(body, signs, '');
+  }
+  return formula;
+}
+
+function withCharge(body: string, signs: string, digits: string): string {
+  const sign = signs.startsWith('-') ? '-' : '+';
+  const magnitude = digits === '' ? signs.length : Number(digits);
+  return `${body.trim()}(${sign}${magnitude})`;
+}

package/src/formula/core/readFormula.ts

@@ -0,0 +1,211 @@
+/**
+ * A formula read into its parts, atoms and charges, with every failure
+ * explained in a sentence written for a student rather than for a parser.
+ */
+
+import { MF } from 'mf-parser';
+
+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 { elementBySymbol } from '../../periodic/core/elements.ts';
+
+import { normalizeFormula } from './normalizeFormula.ts';
+
+/** One kind of atom in one part of a formula. */
+export interface FormulaAtom {
+  /** Element symbol, e.g. `Fe`. */
+  symbol: string;
+  /** Mass number when the formula names the isotope, e.g. 56 in `[56Fe]`. */
+  massNumber: number | null;
+  /** How many of them the part holds. */
+  count: number;
+}
+
+/** One `.`-separated part of a formula: its atoms and its charge. */
+export interface FormulaPart {
+  /** The atoms of the part, in the order the formula first names them. */
+  atoms: FormulaAtom[];
+  /** The charge of the part. */
+  charge: number;
+}
+
+/** A formula as {@link readFormula} reads it. */
+export interface ParsedFormula {
+  /** What was handed to the parser, after {@link normalizeFormula}. */
+  formula: string;
+  /** Its `.`-separated parts. */
+  parts: FormulaPart[];
+  /** Sum of the charges of every part. */
+  charge: number;
+}
+
+/** What the formula readers are told beyond the text. */
+export interface FormulaOptions {
+  /**
+   * The language a failure is explained in.
+   * @default 'en'
+   */
+  language?: Language;
+}
+
+/** A formula that cannot be read, with a message written for a student. */
+export class FormulaError extends Error {
+  override name = 'FormulaError';
+}
+
+interface ParserEntry {
+  kind: string;
+  value: unknown;
+  multiplier?: number;
+}
+
+/**
+ * Read a formula into its parts, atoms and charges.
+ * @param text - A formula as typed, e.g. `Fe(3+)`, `NO3-` or `[238U][19F]6`.
+ * @param options - The language a failure is explained in.
+ * @returns The parsed formula.
+ * @throws {FormulaError} When the text is empty or is not a formula.
+ */
+export function readFormula(
+  text: string,
+  options: FormulaOptions = {},
+): ParsedFormula {
+  const { language = DEFAULT_LANGUAGE } = options;
+  const t = catalogTranslate(CHROME_CATALOG, language);
+  const formula = normalizeFormula(text);
+  if (formula === '') throw new FormulaError(t('formula.typeFirst'));
+
+  let rawParts: ParserEntry[][];
+  try {
+    rawParts = new MF(formula).toParts() as ParserEntry[][];
+  } catch (error) {
+    throw new FormulaError(parserMessage(text, error, language));
+  }
+
+  const order = writtenOrder(formula);
+  const parts: FormulaPart[] = [];
+  let total = 0;
+  for (const rawPart of rawParts) {
+    const part = readPart(text, rawPart, language);
+    part.atoms.sort(
+      (a, b) =>
+        (order.get(a.symbol) ?? order.size) -
+        (order.get(b.symbol) ?? order.size),
+    );
+    total += part.charge;
+    parts.push(part);
+  }
+  if (parts.every((part) => part.atoms.length === 0)) {
+    throw new FormulaError(t('formula.noAtom', { formula: text.trim() }));
+  }
+  return { formula, parts, charge: total };
+}
+
+/**
+ * The atomic number of an element.
+ * @param symbol - Its symbol.
+ * @param options - The language a failure is explained in.
+ * @returns Z.
+ * @throws {FormulaError} When the symbol is not an element.
+ */
+export function atomicNumber(
+  symbol: string,
+  options: FormulaOptions = {},
+): number {
+  const element = elementBySymbol(symbol);
+  if (element === undefined) {
+    const t = catalogTranslate(
+      CHROME_CATALOG,
+      options.language ?? DEFAULT_LANGUAGE,
+    );
+    throw new FormulaError(t('formula.notElement', { symbol }));
+  }
+  return element.atomicNumber;
+}
+
+/**
+ * The name of an element, as the periodic table writes it.
+ * @param symbol - Its symbol.
+ * @returns The English name, or the symbol itself for an unknown one.
+ */
+export function elementName(symbol: string): string {
+  return elementBySymbol(symbol)?.name ?? symbol;
+}
+
+/**
+ * Explain a failure of the parser in a student's terms.
+ * @param text - The formula as typed.
+ * @param error - What the parser threw.
+ * @param language - The language of the sentence.
+ * @returns The sentence.
+ */
+export function parserMessage(
+  text: string,
+  error: unknown,
+  language: Language,
+): string {
+  const t = catalogTranslate(CHROME_CATALOG, language);
+  const raw = error instanceof Error ? error.message : String(error);
+  const unknown = /element unknown: (?<symbol>\S+)/u.exec(raw);
+  if (unknown?.groups?.symbol) {
+    return t('formula.notElement', { symbol: unknown.groups.symbol });
+  }
+  const reason = raw.split('\n', 1)[0] ?? raw;
+  return t('formula.unreadable', { formula: text.trim(), reason });
+}
+
+/**
+ * Where each element first appears in a formula as it is written, so a table
+ * lists Sb before O for Sb2O5 rather than in the parser's canonical order.
+ * @param formula - The formula as given to the parser.
+ * @returns Symbol → position of its first appearance.
+ */
+function writtenOrder(formula: string): Map<string, number> {
+  const order = new Map<string, number>();
+  for (const match of formula.matchAll(/[A-Z][a-z]*/gu)) {
+    if (!order.has(match[0])) order.set(match[0], order.size);
+  }
+  return order;
+}
+
+function readPart(
+  text: string,
+  rawPart: ParserEntry[],
+  language: Language,
+): FormulaPart {
+  const t = catalogTranslate(CHROME_CATALOG, language);
+  const atoms: FormulaAtom[] = [];
+  let charge = 0;
+  for (const entry of rawPart) {
+    if (entry.kind === 'charge') {
+      charge += Number(entry.value);
+      continue;
+    }
+    const count = entry.multiplier ?? 1;
+    if (!Number.isInteger(count) || count <= 0) {
+      throw new FormulaError(
+        t('formula.wholeCounts', { formula: text.trim(), count }),
+      );
+    }
+    if (entry.kind === 'atom' && typeof entry.value === 'string') {
+      atomicNumber(entry.value, { language });
+      atoms.push({ symbol: entry.value, massNumber: null, count });
+      continue;
+    }
+    if (entry.kind === 'isotope') {
+      const { atom, isotope } = entry.value as {
+        atom: string;
+        isotope: number;
+      };
+      atomicNumber(atom, { language });
+      atoms.push({ symbol: atom, massNumber: isotope, count });
+      continue;
+    }
+    throw new FormulaError(
+      t('formula.unknownNotation', { formula: text.trim() }),
+    );
+  }
+  return { atoms, charge };
+}

package/src/formula/ui/CopyableFormula.tsx

@@ -0,0 +1,51 @@
+import type { ReactElement } from 'react';
+import { MF } from 'react-mf';
+
+import type { ClickToCopyElement } from '../../clipboard/ui/ClickToCopy.tsx';
+import { ClickToCopy } from '../../clipboard/ui/ClickToCopy.tsx';
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import { formulaHtml } from '../core/formulaText.ts';
+import { normalizeFormula } from '../core/normalizeFormula.ts';
+
+/** What {@link CopyableFormula} draws and copies. */
+export interface CopyableFormulaProps {
+  /** The formula, as the data writes it: `NO3-`, `CuSO4.5H2O`, `C6H12O6`. */
+  formula: string;
+  /**
+   * The element drawn: a cell of its own inside a table.
+   * @default 'span'
+   */
+  as?: Extract<ClickToCopyElement, 'span' | 'td'>;
+  /**
+   * What the value is called in the hover title.
+   * @default the chrome's own word for it, in the language of the page
+   */
+  label?: string;
+  /**
+   * Class the value carries, in addition to `click-to-copy`.
+   * @default undefined
+   */
+  className?: string;
+}
+
+/**
+ * A formula drawn with its subscripts and copied by a click: as text for
+ * another tool, and as HTML, so a paste into a document keeps the subscripts
+ * and the charge.
+ * @param props - The formula, the element it is drawn as, and its label.
+ * @returns The formula.
+ */
+export function CopyableFormula(props: CopyableFormulaProps): ReactElement {
+  const { formula, as = 'span', label, className } = props;
+  const t = useChromeT();
+  return (
+    <ClickToCopy
+      as={as}
+      className={className}
+      label={label ?? t('formula.copyLabel')}
+      value={{ text: formula, html: formulaHtml(formula) }}
+    >
+      <MF mf={normalizeFormula(formula)} />
+    </ClickToCopy>
+  );
+}