react-cheminfo 0.3.0 → 0.4.0

package/src/structure/core/editorValue.ts

@@ -0,0 +1,116 @@
+import { looksLikeMolfile } from './molfile.ts';
+
+/** One structure of an editor's value, with whatever was written next to it. */
+export interface EditorLine {
+  /**
+   * The structure. On a line-oriented value this is the first blank-separated
+   * token, because a line notation never holds a blank; on a molfile it is the
+   * whole file.
+   */
+  structure: string;
+  /**
+   * What followed the structure on its line, which a Daylight `.smi` file uses
+   * as a name. Empty when nothing did.
+   */
+  label: string;
+  /** 1-based line the structure starts on, so an error can point back at it. */
+  line: number;
+}
+
+/** An editor's value, classified and cut into the structures it holds. */
+export interface EditorValue {
+  /** How the value is written; `empty` when it holds no structure at all. */
+  kind: 'molfile' | 'smiles' | 'empty';
+  /**
+   * The molfile, exactly as it arrived, when `kind` is `molfile`. Empty
+   * otherwise — a molfile's fixed-width header does not survive being trimmed.
+   */
+  molfile: string;
+  /**
+   * Every structure the value holds, in order: one per meaningful line for a
+   * line-oriented value, a single entry for a molfile, none for an empty one.
+   */
+  entries: EditorLine[];
+}
+
+/**
+ * Take an editor's value apart.
+ *
+ * A structure box is handed whatever the chemist had: one molfile pasted out
+ * of another tool, or a run of line notations one per line, possibly with a
+ * name after each and with blank and `#` comment lines in between. Both are
+ * read here so a page can take either without asking which it was given.
+ * @param text - The editor's value, as typed, pasted or dropped.
+ * @returns The notation, the molfile when it is one, and the structures.
+ */
+export function splitEditorValue(text: string): EditorValue {
+  if (text.trim() === '') return { kind: 'empty', molfile: '', entries: [] };
+  if (looksLikeMolfile(text)) {
+    return {
+      kind: 'molfile',
+      molfile: text,
+      entries: [{ structure: text, label: '', line: 1 }],
+    };
+  }
+  const entries = splitLines(text);
+  return entries.length === 0
+    ? { kind: 'empty', molfile: '', entries: [] }
+    : { kind: 'smiles', molfile: '', entries };
+}
+
+/** An idCode and, when the writer emitted one, the atom layout beside it. */
+export interface IdCodeValue {
+  idCode: string;
+  /** Absent when the value carried no coordinates. */
+  coordinates?: string;
+}
+
+/**
+ * Take an idCode apart.
+ *
+ * A drawing editor appends the atom coordinates after a space, which
+ * `Molecule.fromIDCode` takes as a second argument rather than as part of the
+ * first, and which two drawings of the same structure differ by.
+ * @param value - The editor value, coordinates included or not.
+ * @returns The idCode and the coordinates, the idCode empty for a blank value.
+ */
+export function splitIdCode(value: string): IdCodeValue {
+  const [idCode = '', coordinates] = value.trim().split(' ');
+  return coordinates === undefined ? { idCode } : { idCode, coordinates };
+}
+
+/**
+ * Whether an idCode describes nothing.
+ *
+ * Erasing a canvas does not leave the editor with an empty string: it leaves
+ * the idCode of the empty molecule, or of the empty fragment in query mode.
+ * Treating either as a structure keeps a filter alive with nothing drawn.
+ * @param value - The editor value, coordinates included or not.
+ * @returns True when there is nothing on the canvas.
+ */
+export function isEmptyIdCode(value: string): boolean {
+  return EMPTY_ID_CODES.has(splitIdCode(value).idCode);
+}
+
+/** What openchemlib writes for a structure with no atoms: molecule, fragment. */
+const EMPTY_ID_CODES = new Set(['', 'd@', 'dH']);
+
+function splitLines(text: string): EditorLine[] {
+  const entries: EditorLine[] = [];
+  const lines = text.split('\n');
+  for (let index = 0; index < lines.length; index++) {
+    const line = (lines[index] ?? '').trim();
+    if (line === '' || line.startsWith('#')) continue;
+    const blank = line.search(/\s/);
+    entries.push(
+      blank === -1
+        ? { structure: line, label: '', line: index + 1 }
+        : {
+            structure: line.slice(0, blank),
+            label: line.slice(blank).trim(),
+            line: index + 1,
+          },
+    );
+  }
+  return entries;
+}

package/src/structure/core/fragmentQuery.ts

@@ -0,0 +1,50 @@
+import { isEmptyIdCode } from './editorValue.ts';
+import type { StructureKind } from './readStructure.ts';
+import { readStructure } from './readStructure.ts';
+
+/** What a substructure field is currently filtering on. */
+export interface FragmentQuery {
+  /** The notation the query should be read as. */
+  kind: StructureKind;
+  /** The query, ready to hand a parser. Empty when nothing is filtered on. */
+  value: string;
+  /**
+   * True when the field filters on nothing — a blank box, or the idCode an
+   * erased canvas leaves behind.
+   */
+  isEmpty: boolean;
+}
+
+/**
+ * Read what a substructure field holds.
+ *
+ * A filter is fed from two places that disagree about what "nothing" is: a
+ * text box hands back the empty string, while a drawing canvas hands back the
+ * idCode of the empty molecule. Both mean the filter is off, and a filter that
+ * stays on with nothing drawn quietly hides every result.
+ * @param text - The field's value: an idCode, a molfile or a line notation.
+ * @returns The notation, the query, and whether anything is being filtered on.
+ */
+export function fragmentQuery(text: string): FragmentQuery {
+  if (isEmptyIdCode(text)) return { kind: 'empty', value: '', isEmpty: true };
+  const read = readStructure(text);
+  return {
+    kind: read.kind,
+    value: read.value,
+    isEmpty: read.kind === 'empty',
+  };
+}
+
+/**
+ * Whether two field values describe the same query, so a search is not run
+ * again for a value that only changed by its surrounding blanks.
+ * @param left - One field value.
+ * @param right - The other field value.
+ * @returns True when both would be read as the same query.
+ */
+export function sameFragmentQuery(left: string, right: string): boolean {
+  const first = fragmentQuery(left);
+  const second = fragmentQuery(right);
+  if (first.isEmpty || second.isEmpty) return first.isEmpty === second.isEmpty;
+  return first.kind === second.kind && first.value === second.value;
+}

package/src/structure/core/index.ts

@@ -0,0 +1,13 @@
+export type { EditorLine, EditorValue } from './editorValue.ts';
+export { splitEditorValue } from './editorValue.ts';
+export type { FragmentQuery } from './fragmentQuery.ts';
+export { fragmentQuery, sameFragmentQuery } from './fragmentQuery.ts';
+export type { MolfileClassification, MolfileVersion } from './molfile.ts';
+export { classifyMolfile, molfileAtomCount } from './molfile.ts';
+export type { ReadStructureResult, StructureKind } from './readStructure.ts';
+export { looksLikeSmarts, readStructure } from './readStructure.ts';
+export type {
+  StructureSource,
+  StructureSourceInput,
+} from './structureSource.ts';
+export { structureSource } from './structureSource.ts';

package/src/structure/core/molfile.ts

@@ -0,0 +1,90 @@
+/** Which connection-table dialect a molfile is written in. */
+export type MolfileVersion = 'v2000' | 'v3000' | 'unknown';
+
+/** What a molfile's counts line says about it. */
+export interface MolfileClassification {
+  /** The dialect, `unknown` when the text carries no version stamp. */
+  version: MolfileVersion;
+  /**
+   * Atoms the counts line declares, `0` when there is no counts line to read.
+   */
+  atomCount: number;
+}
+
+/**
+ * Read a molfile's version and its declared atom count.
+ *
+ * The two dialects write their counts in unrelated places: V2000 packs them
+ * into the fixed-width fields of the line ending in `V2000`, while a V3000
+ * file leaves those fields at zero and declares the real counts on an
+ * `M  V30 COUNTS` line further down. Reading a V3000 file with the V2000 rule
+ * therefore answers zero atoms without failing, which is what makes a viewer
+ * render an empty scene and report nothing.
+ * @param text - A molfile, or any text that may not be one.
+ * @returns The dialect and the declared atom count.
+ */
+export function classifyMolfile(text: string): MolfileClassification {
+  if (V3000_STAMP.test(text)) {
+    return { version: 'v3000', atomCount: countIn(text, V3000_COUNTS) };
+  }
+  if (V2000_STAMP.test(text)) {
+    return { version: 'v2000', atomCount: countIn(text, V2000_COUNTS) };
+  }
+  return { version: 'unknown', atomCount: 0 };
+}
+
+/**
+ * How many atoms a molfile declares, whichever dialect it is written in.
+ * @param text - A molfile, or any text that may not be one.
+ * @returns The declared atom count, `0` when the text declares none.
+ */
+export function molfileAtomCount(text: string): number {
+  return classifyMolfile(text).atomCount;
+}
+
+/**
+ * Whether a piece of text should be read as a molfile rather than as a line
+ * notation.
+ *
+ * A line notation is a single line and can never carry a version stamp, so a
+ * text holding a header, a counts line and at least one atom line is the one
+ * that is a molfile.
+ * @param text - The structure, as typed, pasted or dropped.
+ * @returns True when it should be read as a molfile.
+ */
+export function looksLikeMolfile(text: string): boolean {
+  if (countLines(text) < 4) return false;
+  return classifyMolfile(text).version !== 'unknown';
+}
+
+/**
+ * The version stamp closes a line whose every other field is a number, so a
+ * data field or a sentence mentioning the dialect is not mistaken for one.
+ */
+const V2000_STAMP = /^[\d ]+V2000[^\S\n]*$/m;
+const V3000_STAMP = /^[\d ]+V3000[^\S\n]*$/m;
+
+/**
+ * The V2000 counts line is fixed-width: three characters for the atoms, three
+ * for the bonds. A writer that trims the padding still lands inside the same
+ * six characters for any count a V2000 file can hold.
+ */
+const V2000_COUNTS = /^(?<atoms>[\d ]{3})[\d ]*V2000[^\S\n]*$/m;
+const V3000_COUNTS = /^M {2}V30 COUNTS +(?<atoms>\d+)/m;
+
+function countIn(text: string, pattern: RegExp): number {
+  const atoms = pattern.exec(text)?.groups?.atoms;
+  if (atoms === undefined) return 0;
+  const count = Number.parseInt(atoms.trim(), 10);
+  return Number.isFinite(count) && count > 0 ? count : 0;
+}
+
+function countLines(text: string): number {
+  let lines = 1;
+  let index = text.indexOf('\n');
+  while (index !== -1) {
+    lines++;
+    index = text.indexOf('\n', index + 1);
+  }
+  return lines;
+}

package/src/structure/core/readStructure.ts

@@ -0,0 +1,73 @@
+import { looksLikeMolfile } from './molfile.ts';
+
+/** How a piece of structure text turned out to be written. */
+export type StructureKind = 'molfile' | 'smiles' | 'smarts' | 'empty';
+
+/** A piece of structure text, and the notation it should be read as. */
+export interface ReadStructureResult {
+  kind: StructureKind;
+  /**
+   * The text to hand a parser. A line notation is trimmed; a molfile is left
+   * exactly as it arrived, because its first three lines are a fixed-width
+   * header whose title line is very often blank — trimming shifts every line
+   * up and the counts line is then read as an atom.
+   */
+  value: string;
+}
+
+/**
+ * Decide what a piece of text is, without parsing it.
+ *
+ * Nothing is asked of the user, because the answer is in the text: a molfile
+ * carries a version stamp and several lines, a query carries syntax that only
+ * exists in SMARTS, and whatever is left is a SMILES. Text that holds nothing
+ * is the third answer, so a field can tell "not typed yet" from "typed
+ * something wrong" and only complain about the second.
+ * @param text - The structure, as typed, pasted or dropped.
+ * @returns The notation and the text to read it with.
+ */
+export function readStructure(text: string): ReadStructureResult {
+  const trimmed = text.trim();
+  if (trimmed === '') return { kind: 'empty', value: '' };
+  if (looksLikeMolfile(text)) return { kind: 'molfile', value: text };
+  if (looksLikeSmarts(trimmed)) return { kind: 'smarts', value: trimmed };
+  return { kind: 'smiles', value: trimmed };
+}
+
+/**
+ * Whether a line notation uses syntax that exists in SMARTS and not in SMILES.
+ *
+ * Only the inside of a bracket atom is inspected for the primitives, because
+ * `#` is a triple bond outside one and `D`, `X`, `R`, `v` and `h` are the
+ * start of real element symbols. `~`, `&`, `,`, `;`, `!` and `$(` are SMARTS
+ * anywhere they appear.
+ * @param text - The line notation, already trimmed.
+ * @returns True when it can only be a query.
+ */
+export function looksLikeSmarts(text: string): boolean {
+  if (/[~&;,!]/.test(text) || text.includes('$(')) return true;
+  for (const match of text.matchAll(BRACKET_ATOM)) {
+    if (QUERY_PRIMITIVE.test(match.groups?.atom ?? '')) return true;
+  }
+  return BARE_WILDCARD.test(text.replaceAll(BRACKET_ATOM, ''));
+}
+
+const BRACKET_ATOM = /\[(?<atom>[^\]]*)\]/g;
+
+/**
+ * `#6` (atomic number), `X3` / `D2` / `R1` / `r5` / `v4` / `h1` / `x2`
+ * (counts), and the `a` / `A` wildcards. A digit is required after the letter,
+ * so `[Xe]` and `[Rn]` stay elements. The wildcard is anchored to the start of
+ * the atom, after an optional isotope: unanchored it matches the `a` of
+ * `[Na+]`, and every bracketed element holding a lowercase a — Na, Ca, Ba, La,
+ * Ta — would then read as a query rather than as the atom it is.
+ */
+const QUERY_PRIMITIVE = /#\d|[DXRrvhx]\d|^\*|^\d*[aA](?![a-z])/;
+
+/**
+ * Outside a bracket the wildcard has to stand on its own: a letter on either
+ * side and it is part of a word, not a pattern. Widening this to any `a` or
+ * `A` reads the header `CAS` as the three-atom SMARTS `C`,`A`,`S`, and a
+ * spreadsheet's header row stops being recognised as one.
+ */
+const BARE_WILDCARD = /(?:^|[^A-Za-z])[aA](?![a-z])/;

package/src/structure/core/structureSource.ts

@@ -0,0 +1,57 @@
+import { isEmptyIdCode, splitIdCode } from './editorValue.ts';
+import { molfileAtomCount } from './molfile.ts';
+
+/** Every notation a read-only depiction may be handed. */
+export interface StructureSourceInput {
+  /** A canonical openchemlib idCode, coordinates included or not. */
+  idCode?: string;
+  /** Encoded 2D coordinates, when they did not travel with the idCode. */
+  coordinates?: string;
+  /** A molfile, V2000 or V3000. */
+  molfile?: string;
+  /** A SMILES. */
+  smiles?: string;
+}
+
+/** The one notation a depiction should be drawn from. */
+export interface StructureSource {
+  /** Which notation was picked; `empty` when none of them holds a structure. */
+  kind: 'idcode' | 'molfile' | 'smiles' | 'empty';
+  /** The text to draw, empty when there is nothing to draw. */
+  value: string;
+  /** Encoded 2D coordinates, only ever set beside an idCode. */
+  coordinates?: string;
+}
+
+/**
+ * Pick the notation a depiction is drawn from when several were supplied.
+ *
+ * The most exact one wins: an idCode says precisely which structure, a molfile
+ * additionally carries the layout its author chose, and a SMILES leaves the
+ * layout to be invented. A notation that describes nothing — a blank string, a
+ * molfile with an empty atom block, the idCode an erased canvas leaves behind
+ * — is skipped rather than drawn, which is what turns a broken box into the
+ * next best picture, or into an honest placeholder.
+ * @param input - Whatever notations the caller has.
+ * @returns The notation to draw, and the text to draw it from.
+ */
+export function structureSource(input: StructureSourceInput): StructureSource {
+  const { idCode, coordinates, molfile, smiles } = input;
+
+  if (idCode !== undefined && !isEmptyIdCode(idCode)) {
+    const split = splitIdCode(idCode);
+    const layout = split.coordinates ?? coordinates;
+    return layout === undefined || layout === ''
+      ? { kind: 'idcode', value: split.idCode }
+      : { kind: 'idcode', value: split.idCode, coordinates: layout };
+  }
+
+  if (molfile !== undefined && molfileAtomCount(molfile) > 0) {
+    return { kind: 'molfile', value: molfile };
+  }
+
+  const line = smiles?.trim() ?? '';
+  if (line !== '') return { kind: 'smiles', value: line };
+
+  return { kind: 'empty', value: '' };
+}

package/src/structure/core/toolbarFloor.ts

@@ -0,0 +1,31 @@
+/** The two 1px borders of a container that sizes itself border-box. */
+export const TOOLBAR_BORDERS = 2;
+
+/**
+ * The smallest height a drawing editor's container may take.
+ *
+ * The editor's toolbar is a canvas of a fixed height, drawn from a sprite of a
+ * fixed number of buttons: a container any shorter than that does not scroll,
+ * it simply cuts the last buttons off. So the floor is whichever is taller,
+ * the height the caller asked for or the toolbar plus the borders around it.
+ * @param toolbarHeight - Height the toolbar was measured at, in pixels.
+ * @param minHeight - Smallest height the caller asked for, in pixels.
+ * @param borders - Borders the container adds around the toolbar, in pixels.
+ * @returns The height to give the container, in pixels.
+ */
+export function toolbarFloorHeight(
+  toolbarHeight: number,
+  minHeight: number,
+  borders: number = TOOLBAR_BORDERS,
+): number {
+  const asked = positive(minHeight);
+  const measured = positive(toolbarHeight);
+  // A toolbar with no layout yet measures zero, and a floor of two pixels of
+  // border would collapse the editor before it has had a chance to draw.
+  if (measured === 0) return asked;
+  return Math.max(asked, measured + positive(borders));
+}
+
+function positive(value: number): number {
+  return Number.isFinite(value) && value > 0 ? value : 0;
+}

package/src/structure/ui/EditorCanvas.tsx

@@ -0,0 +1,130 @@
+import type { CSSProperties, ReactElement } from 'react';
+import { useCallback, useState } from 'react';
+import type {
+  CanvasEditorInputFormat,
+  CanvasEditorOnChangeMolecule,
+  CanvasEditorOnChangeReaction,
+} from 'react-ocl';
+import { CanvasMoleculeEditor, CanvasReactionEditor } from 'react-ocl';
+
+/** What the editor draws: one structure, or a reaction with its arrow. */
+export type StructureEditorMode = 'molecule' | 'reaction';
+
+/** Everything the editor holds at the moment it changed. */
+export interface StructureEditorChange {
+  /** Which kind of editor produced it. */
+  mode: StructureEditorMode;
+  /**
+   * The idCode, with the coordinates the editor laid out written after a
+   * space. `splitIdCode` takes the two apart.
+   */
+  idCode: string;
+  /** The V2000 molfile of a molecule, or the RXN file of a reaction. */
+  molfile: string;
+  /** The SMILES of a molecule, or the reaction SMILES. */
+  smiles: string;
+}
+
+export interface EditorCanvasProps {
+  /** Called on every stroke, with the editor read out synchronously. */
+  onChange: (change: StructureEditorChange) => void;
+  /**
+   * Draw a query fragment rather than a whole structure, which is what a
+   * substructure filter needs.
+   * @default false
+   */
+  fragment?: boolean;
+  /**
+   * How `value` is written.
+   * @default 'idcode'
+   */
+  inputFormat?: CanvasEditorInputFormat;
+  /**
+   * What the canvas holds when it appears. Read once, at mount: the editor is
+   * uncontrolled, so feeding a later value back would replace the structure
+   * and reset every coordinate under the pen.
+   * @default ''
+   */
+  value?: string;
+  /**
+   * Whether the editor draws one structure or a reaction.
+   * @default 'molecule'
+   */
+  mode?: StructureEditorMode;
+}
+
+/**
+ * The react-ocl canvas, filling whatever box it is put in.
+ *
+ * Its value is frozen at mount, so the caller remounts it — by changing its
+ * `key` — to load a different structure into it.
+ * @param props - What to draw, how it is written, and where to send it.
+ * @returns The canvas.
+ */
+export function EditorCanvas(props: EditorCanvasProps): ReactElement {
+  const {
+    onChange,
+    fragment = false,
+    inputFormat = 'idcode',
+    value = '',
+    mode = 'molecule',
+  } = props;
+  const [initialValue] = useState(value);
+
+  const handleMolecule = useCallback(
+    (event: CanvasEditorOnChangeMolecule) => {
+      // The event describes the editor only while the callback runs, so every
+      // notation is read now and whatever waiting there is happens afterwards.
+      onChange({
+        mode: 'molecule',
+        idCode: event.getIdcode(),
+        molfile: event.getMolfile(),
+        smiles: event.getSmiles(),
+      });
+    },
+    [onChange],
+  );
+
+  const handleReaction = useCallback(
+    (event: CanvasEditorOnChangeReaction) => {
+      onChange({
+        mode: 'reaction',
+        idCode: event.getIdcode(),
+        molfile: event.getRxn(),
+        smiles: event.getSmiles(),
+      });
+    },
+    [onChange],
+  );
+
+  return (
+    <div style={CANVAS_STYLE}>
+      {mode === 'reaction' ? (
+        <CanvasReactionEditor
+          width="100%"
+          height="100%"
+          fragment={fragment}
+          inputFormat={inputFormat}
+          inputValue={initialValue}
+          onChange={handleReaction}
+        />
+      ) : (
+        <CanvasMoleculeEditor
+          width="100%"
+          height="100%"
+          fragment={fragment}
+          inputFormat={inputFormat}
+          inputValue={initialValue}
+          onChange={handleMolecule}
+        />
+      )}
+    </div>
+  );
+}
+
+/**
+ * The canvas measures its container in pixels, so it is taken out of the
+ * height computation: otherwise the container and the canvas grow each other
+ * without ever settling.
+ */
+const CANVAS_STYLE: CSSProperties = { position: 'absolute', inset: 0 };