react-cheminfo 0.11.0 → 0.13.0

package/src/state/core/storageEntry.ts

@@ -0,0 +1,93 @@
+/**
+ * The storage key an entry occupies once its schema version is appended.
+ * @param key - Name of the entry, namespaced by the site, e.g. `smiles:exercises`.
+ * @param version - Schema version of what is stored under it.
+ * @returns The versioned key, e.g. `smiles:exercises:v1`.
+ */
+export function versionedStorageKey(key: string, version: number): string {
+  return `${key}:v${version}`;
+}
+
+/**
+ * Read one `localStorage` entry back as JSON.
+ *
+ * A page framed by a course may have no storage at all — third-party storage
+ * is partitioned in Chrome and blocked in Safari — so touching the store may
+ * throw before it is even reached. Nothing of that reaches the caller: an
+ * unreadable store, a missing entry and corrupt JSON all read as nothing.
+ * @param storageKey - The full key, version included.
+ * @returns What was parsed, or `undefined` when there is nothing readable.
+ */
+export function readStorageEntry(storageKey: string): unknown {
+  let raw: string | null;
+  try {
+    raw = globalThis.localStorage?.getItem(storageKey) ?? null;
+  } catch {
+    return undefined;
+  }
+  if (raw === null) return undefined;
+  try {
+    return JSON.parse(raw) as unknown;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Write one `localStorage` entry as JSON, replacing what was there.
+ *
+ * Best effort: a value that cannot be serialised, an unavailable store and a
+ * refused write are all swallowed. A write refused because the store is full
+ * is reported through `onQuotaExceeded`, so a page can tell its visitor that
+ * what they are doing is no longer being kept.
+ * @param storageKey - The full key, version included.
+ * @param value - What to store; it must be JSON serialisable.
+ * @param onQuotaExceeded - Called with the error when the store is full.
+ */
+export function writeStorageEntry(
+  storageKey: string,
+  value: unknown,
+  onQuotaExceeded?: (error: unknown) => void,
+): void {
+  let serialized: string;
+  try {
+    serialized = JSON.stringify(value);
+  } catch {
+    // A value that cannot be serialised is a bug in the caller, never a reason
+    // to take the page down with it.
+    return;
+  }
+  try {
+    globalThis.localStorage?.setItem(storageKey, serialized);
+  } catch (error) {
+    if (!isQuotaExceeded(error) || onQuotaExceeded === undefined) return;
+    try {
+      onQuotaExceeded(error);
+    } catch {
+      // A callback that throws must not turn a lost entry into a crash.
+    }
+  }
+}
+
+/**
+ * Forget one `localStorage` entry. An unavailable store has nothing to forget.
+ * @param storageKey - The full key, version included.
+ */
+export function removeStorageEntry(storageKey: string): void {
+  try {
+    globalThis.localStorage?.removeItem(storageKey);
+  } catch {
+    // Nothing to do: the entry cannot be reached, so it cannot be read either.
+  }
+}
+
+function isQuotaExceeded(error: unknown): boolean {
+  if (typeof error !== 'object' || error === null) return false;
+  const { name, code } = error as { name?: unknown; code?: unknown };
+  return (
+    name === 'QuotaExceededError' ||
+    name === 'NS_ERROR_DOM_QUOTA_REACHED' ||
+    code === 22 ||
+    code === 1014
+  );
+}

package/src/structure/core/atomLabels.ts

@@ -0,0 +1,63 @@
+/**
+ * Text written on a depiction next to, or in place of, an atom's symbol.
+ *
+ * openchemlib stores such text as a custom atom label, and reads a label that
+ * begins with `]` as "draw this above the atom" rather than "draw this instead
+ * of it". That one character is the whole difference between numbering a
+ * structure and relabelling its atoms, which is why it is written here once.
+ */
+
+/**
+ * Where a label goes: beside the element symbol, as a small superscript, or in
+ * place of it.
+ */
+export type AtomLabelPlacement = 'beside' | 'instead';
+
+/** The two methods of an openchemlib `Molecule` a label is written through. */
+export interface LabelledMolecule {
+  /** How many atoms the molecule holds, hydrogens included. */
+  getAllAtoms(): number;
+  /** Replace the custom label of one atom; `null` removes it. */
+  setAtomCustomLabel(atom: number, label: string | null): unknown;
+}
+
+/**
+ * The custom label openchemlib draws where it is asked to.
+ * @param text - What is written, without any marker.
+ * @param placement - Beside the symbol or instead of it.
+ * @returns The label to store on the atom.
+ */
+export function customAtomLabel(
+  text: string,
+  placement: AtomLabelPlacement = 'beside',
+): string {
+  return placement === 'beside' ? `]${text}` : text;
+}
+
+/**
+ * Write labels onto the atoms of a molecule.
+ *
+ * The molecule is changed in place, so a caller holding a structure other
+ * code also reads passes a copy (`getCompactCopy()`). An empty text, and an
+ * index the molecule has no atom at, are skipped.
+ * @param molecule - The molecule to label.
+ * @param labels - What to write, keyed by atom index as openchemlib counts
+ * atoms, from 0.
+ * @param placement - Beside the symbols or instead of them.
+ * @returns How many labels were written.
+ */
+export function applyAtomLabels(
+  molecule: LabelledMolecule,
+  labels: ReadonlyMap<number, string>,
+  placement: AtomLabelPlacement = 'beside',
+): number {
+  const atomCount = molecule.getAllAtoms();
+  let written = 0;
+  for (const [atom, text] of labels) {
+    if (text === '' || !Number.isInteger(atom)) continue;
+    if (atom < 0 || atom >= atomCount) continue;
+    molecule.setAtomCustomLabel(atom, customAtomLabel(text, placement));
+    written++;
+  }
+  return written;
+}

package/src/structure/core/editorValue.ts

@@ -60,8 +60,12 @@ export function splitEditorValue(text: string): EditorValue {
 
 /** An idCode and, when the writer emitted one, the atom layout beside it. */
 export interface IdCodeValue {
+  /** The idCode alone, empty for a blank value. */
   idCode: string;
-  /** Absent when the value carried no coordinates. */
+  /**
+   * The encoded atom coordinates; absent when the value carried none.
+   * @default undefined
+   */
   coordinates?: string;
 }
 

package/src/structure/core/index.ts

@@ -1,11 +1,20 @@
+export type { AtomLabelPlacement, LabelledMolecule } from './atomLabels.ts';
+export { applyAtomLabels, customAtomLabel } from './atomLabels.ts';
 export type { EditorLine, EditorValue } from './editorValue.ts';
-export { splitEditorValue } from './editorValue.ts';
+export type { IdCodeValue } from './editorValue.ts';
+export { isEmptyIdCode, splitEditorValue, splitIdCode } 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 {
+  classifyMolfile,
+  looksLikeMolfile,
+  molfileAtomCount,
+} from './molfile.ts';
 export type { ReadStructureResult, StructureKind } from './readStructure.ts';
 export { looksLikeSmarts, readStructure } from './readStructure.ts';
+export type { StructureError } from './structureError.ts';
+export { structureError } from './structureError.ts';
 export type {
   StructureSource,
   StructureSourceInput,

package/src/structure/core/readStructure.ts

@@ -5,6 +5,7 @@ export type StructureKind = 'molfile' | 'smiles' | 'smarts' | 'empty';
 
 /** A piece of structure text, and the notation it should be read as. */
 export interface ReadStructureResult {
+  /** The notation the text is written in. */
   kind: StructureKind;
   /**
    * The text to hand a parser. A line notation is trimmed; a molfile is left

package/src/structure/core/structureError.ts

@@ -0,0 +1,58 @@
+/** What went wrong while reading a structure, and where. */
+export interface StructureError {
+  /** The reason, as one sentence a chemist can act on. */
+  message: string;
+  /**
+   * Index of the offending character in the input, when the parser named one.
+   * @default undefined
+   */
+  position?: number;
+}
+
+/**
+ * Turn a parse failure into a readable reason and the position it names.
+ *
+ * openchemlib is compiled from Java, so a failure arrives as
+ * `Class$S19: SmilesParser: dangling ring closure: 1; position:4` — a mangled
+ * class name, the name of the parser, the reason, and sometimes the character
+ * it stopped on. Only the last two mean anything to someone writing a
+ * structure, and the position is what lets a page point at the mistake, so
+ * the reason is returned without it and the position beside it.
+ * @param error - Whatever the parser threw.
+ * @returns The reason, capitalised, and the offending position when one was
+ * named.
+ */
+export function structureError(error: unknown): StructureError {
+  const raw = messageOf(error);
+  const message = cleanMessage(raw);
+  const position = readPosition(raw);
+  return position === undefined ? { message } : { message, position };
+}
+
+function messageOf(error: unknown): string {
+  if (error instanceof Error) return error.message;
+  if (typeof error === 'string') return error;
+  return '';
+}
+
+/** What is said when the parser gave no reason at all. */
+const SILENT_FAILURE = 'This structure could not be read.';
+
+function readPosition(raw: string): number | undefined {
+  const index = /position\s*:\s*(?<index>\d+)/i.exec(raw)?.groups?.index;
+  return index === undefined ? undefined : Number(index);
+}
+
+function cleanMessage(raw: string): string {
+  const text = raw
+    // The generated class name of the exception, which names nothing.
+    .replace(/^\w*\$\w+:\s*/, '')
+    // The parser that raised it: the page already says what it was reading.
+    .replace(/^(?:SmilesParser|MolfileParser|Molfile\w*|IDCodeParser):\s*/, '')
+    // The position is returned on its own, so it leaves the sentence together
+    // with the words that only lead up to it.
+    .replace(/[;,]?\s*(?:at\s+unexpected\s+)?position\s*:\s*\d+\.?\s*$/i, '')
+    .trim();
+  if (text === '') return SILENT_FAILURE;
+  return text.charAt(0).toUpperCase() + text.slice(1);
+}

package/src/structure/core/structureSource.ts

@@ -3,13 +3,25 @@ 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. */
+  /**
+   * A canonical openchemlib idCode, coordinates included or not.
+   * @default undefined
+   */
   idCode?: string;
-  /** Encoded 2D coordinates, when they did not travel with the idCode. */
+  /**
+   * Encoded 2D coordinates, when they did not travel with the idCode.
+   * @default undefined
+   */
   coordinates?: string;
-  /** A molfile, V2000 or V3000. */
+  /**
+   * A molfile, V2000 or V3000.
+   * @default undefined
+   */
   molfile?: string;
-  /** A SMILES. */
+  /**
+   * A SMILES.
+   * @default undefined
+   */
   smiles?: string;
 }
 
@@ -19,7 +31,10 @@ export interface StructureSource {
   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. */
+  /**
+   * Encoded 2D coordinates, only ever set beside an idCode.
+   * @default undefined
+   */
   coordinates?: string;
 }
 

package/src/structure/ui/EditorCanvas.tsx

@@ -25,7 +25,7 @@ export interface StructureEditorChange {
   smiles: string;
 }
 
-export interface EditorCanvasProps {
+interface EditorCanvasProps {
   /** Called on every stroke, with the editor read out synchronously. */
   onChange: (change: StructureEditorChange) => void;
   /**

package/src/structure/ui/Structure.tsx

@@ -11,6 +11,7 @@
 import type { ReactElement, ReactNode } from 'react';
 import { Suspense, lazy } from 'react';
 
+import type { AtomLabelPlacement } from '../core/atomLabels.ts';
 import { structureSource } from '../core/structureSource.ts';
 
 import { StructurePlaceholder } from './StructurePlaceholder.tsx';
@@ -37,6 +38,11 @@ export interface StructureLabels {
    * @default false
    */
   mapping?: boolean;
+  /**
+   * Write the CIP descriptor, R or S, next to every stereocentre.
+   * @default false
+   */
+  stereo?: boolean;
   /**
    * A caption drawn inside the picture, under the structure.
    * @default undefined
@@ -44,6 +50,7 @@ export interface StructureLabels {
   caption?: string;
 }
 
+/** What {@link Structure} needs. */
 export interface StructureProps {
   /**
    * A canonical openchemlib idCode, coordinates included or not. The most
@@ -82,6 +89,20 @@ export interface StructureProps {
    * @default {}
    */
   labels?: StructureLabels;
+  /**
+   * Text of the caller's own written on atoms — ring numbers, canonical
+   * numbers, an assignment — keyed by atom index as openchemlib counts atoms,
+   * from 0. An empty text, or an index the structure has no atom at, writes
+   * nothing.
+   * @default undefined
+   */
+  atomLabels?: ReadonlyMap<number, string>;
+  /**
+   * Where the `atomLabels` go: beside each element symbol, as a small
+   * superscript, or in place of it.
+   * @default 'beside'
+   */
+  atomLabelPlacement?: AtomLabelPlacement;
   /**
    * Crop the picture to the atoms rather than centring them in the box.
    * @default true
@@ -112,6 +133,17 @@ export interface StructureProps {
    * @default '#ffd8a8'
    */
   bondHighlightColor?: string;
+  /**
+   * Called with the index of the atom that was clicked, counted from 0 as
+   * openchemlib counts atoms.
+   * @default undefined
+   */
+  onAtomClick?: (atom: number) => void;
+  /**
+   * Called with the index of the bond that was clicked, counted from 0.
+   * @default undefined
+   */
+  onBondClick?: (bond: number) => void;
   /**
    * What is shown when there is no structure, or when the one supplied cannot
    * be read. An em dash rather than a red box: a missing structure is a row of
@@ -141,12 +173,16 @@ export function Structure(props: StructureProps): ReactElement {
     width = 200,
     height = 140,
     labels = {},
+    atomLabels,
+    atomLabelPlacement = 'beside',
     autoCrop = true,
     autoCropMargin = 4,
     atomHighlight,
     atomHighlightColor = '#a5d8ff',
     bondHighlight,
     bondHighlightColor = '#ffd8a8',
+    onAtomClick,
+    onBondClick,
     fallback = '—',
   } = props;
 
@@ -175,7 +211,12 @@ export function Structure(props: StructureProps): ReactElement {
         showAtomNumber={labels.atoms ?? false}
         showBondNumber={labels.bonds ?? false}
         showMapping={labels.mapping ?? false}
+        showCIPParity={labels.stereo ?? false}
         label={labels.caption}
+        atomLabels={atomLabels}
+        atomLabelPlacement={atomLabelPlacement}
+        onAtomClick={onAtomClick}
+        onBondClick={onBondClick}
         fallback={fallback}
       />
     </Suspense>

package/src/structure/ui/StructureEditor.tsx

@@ -11,6 +11,8 @@ import type { CSSProperties, ReactElement } from 'react';
 import { Suspense, lazy, useCallback, useEffect, useRef } from 'react';
 import type { CanvasEditorInputFormat } from 'react-ocl';
 
+import { TOKEN } from '../../tokens/core/familyTokens.ts';
+
 import type {
   StructureEditorChange,
   StructureEditorMode,
@@ -22,6 +24,7 @@ const EditorCanvas = lazy(async () => {
   return { default: module.EditorCanvas };
 });
 
+/** What {@link StructureEditor} needs. */
 export interface StructureEditorProps {
   /**
    * Called after every edit, once the drawing has been still for `debounce`
@@ -73,9 +76,15 @@ export interface StructureEditorProps {
    * @default 'molecule'
    */
   mode?: StructureEditorMode;
-  /** Class the container carries, so a site can reach it from its stylesheet. */
+  /**
+   * Class the container carries, so a site can reach it from its stylesheet.
+   * @default undefined
+   */
   className?: string;
-  /** Extra style for the container, merged over the packaged one. */
+  /**
+   * Extra style for the container, merged over the packaged one.
+   * @default undefined
+   */
   style?: CSSProperties;
 }
 
@@ -179,7 +188,7 @@ const ROOT_STYLE: CSSProperties = {
   position: 'relative',
   overflow: 'hidden',
   boxSizing: 'border-box',
-  border: '1px solid var(--border, #d3d8de)',
+  border: `1px solid ${TOKEN.border}`,
   borderRadius: 6,
   background: '#fff',
 };
@@ -191,6 +200,6 @@ const LOADING_STYLE: CSSProperties = {
   display: 'flex',
   alignItems: 'center',
   justifyContent: 'center',
-  color: 'var(--text-faint, #8a96a3)',
+  color: TOKEN.textFaint,
   fontSize: 13,
 };

package/src/structure/ui/StructurePlaceholder.tsx

@@ -9,8 +9,10 @@
 
 import type { CSSProperties, ReactElement, ReactNode } from 'react';
 
+import { TOKEN } from '../../tokens/core/familyTokens.ts';
+
 /** Props of {@link StructurePlaceholder}. */
-export interface StructurePlaceholderProps {
+interface StructurePlaceholderProps {
   /** Width of the box, in pixels: the width the picture would have had. */
   width: number;
   /** Height of the box, in pixels. */
@@ -43,6 +45,6 @@ const PLACEHOLDER_STYLE: CSSProperties = {
   display: 'inline-flex',
   alignItems: 'center',
   justifyContent: 'center',
-  color: 'var(--text-faint, #8a96a3)',
+  color: TOKEN.textFaint,
   fontSize: '0.75rem',
 };