react-cheminfo 0.16.0 → 0.18.0

package/src/structure/core/editorGuide.ts

@@ -0,0 +1,221 @@
+/**
+ * What the keyboard and the mouse do in the openchemlib canvas editor, beyond
+ * what its toolbar shows: the keys that change the atom or the bond under the
+ * pointer, the selection gestures and the stereo conventions.
+ */
+
+/** A key, drawn as a key cap. `Mod` is ⌘ on a Mac and Ctrl elsewhere. */
+export interface EditorGuideKey {
+  key: string;
+}
+
+/** Which editors a gesture applies to. */
+export type EditorGuideScope = 'fragment' | 'molecule' | 'reaction';
+
+/** One gesture and what it does. */
+export interface EditorGesture {
+  /** Keys, and plain text for the mouse part; unique within one gesture. */
+  input: ReadonlyArray<string | EditorGuideKey>;
+  action: string;
+  /**
+   * The only editor the gesture works in.
+   * @default undefined — every editor
+   */
+  only?: EditorGuideScope;
+}
+
+/** Gestures that share a context, such as the pointer resting on an atom. */
+export interface EditorGuideSection {
+  title: string;
+  gestures: readonly EditorGesture[];
+  /**
+   * A sentence read after the gestures.
+   * @default undefined
+   */
+  note?: string;
+}
+
+/** A page of the full documentation. */
+export interface EditorGuideLink {
+  title: string;
+  url: string;
+}
+
+/** The sections, in the order the guide lists them. */
+export const STRUCTURE_EDITOR_GUIDE: readonly EditorGuideSection[] = [
+  {
+    title: 'Pointer on an atom',
+    gestures: [
+      { input: ['Type', { key: 'n' }, { key: 'a' }], action: 'Make it Na' },
+      {
+        input: ['Type', { key: 'p' }, { key: 'h' }],
+        action: 'Attach a phenyl; Me, Et, Boc, TMS… work too',
+      },
+      {
+        input: [{ key: 'Enter' }, 'or', { key: 'Esc' }],
+        action: 'Apply or forget what was typed',
+      },
+      {
+        input: [{ key: '1' }, '…', { key: '9' }],
+        action: 'Attach a chain of that many carbons',
+      },
+      {
+        input: [{ key: '+' }, 'or', { key: '-' }],
+        action: 'Raise or lower the charge',
+      },
+      { input: [{ key: '.' }], action: 'Add or remove a radical' },
+      { input: [{ key: ':' }], action: 'Make it a triplet, then a singlet' },
+      { input: [{ key: '?' }], action: 'Make it a connection point' },
+      {
+        input: [{ key: 'q' }],
+        action: 'Edit its query features',
+        only: 'fragment',
+      },
+      { input: [{ key: 'x' }], action: 'Accept any halogen', only: 'fragment' },
+      { input: [{ key: 'Delete' }], action: 'Delete it' },
+    ],
+    note: 'What is typed shows black for an element, blue for a group, grey while incomplete and red when unknown.',
+  },
+  {
+    title: 'Pointer on a bond',
+    gestures: [
+      {
+        input: [{ key: '1' }, { key: '2' }, { key: '3' }],
+        action: 'Single, double or triple',
+      },
+      { input: [{ key: '0' }], action: 'Zero-order (metal–ligand) bond' },
+      {
+        input: [{ key: 'u' }, 'or', { key: 'd' }],
+        action: 'Up or down stereo bond',
+      },
+      { input: [{ key: 'c' }], action: 'Double bond of unknown geometry' },
+      { input: [{ key: 'v' }], action: 'Fuse a 3-membered ring' },
+      {
+        input: [{ key: '4' }, '…', { key: '7' }],
+        action: 'Fuse a ring of that size',
+      },
+      {
+        input: [{ key: 'a' }, 'or', { key: 'b' }],
+        action: 'Fuse a benzene ring',
+      },
+      {
+        input: [{ key: 'q' }],
+        action: 'Edit its query features',
+        only: 'fragment',
+      },
+      { input: [{ key: 'Delete' }], action: 'Delete it' },
+    ],
+  },
+  {
+    title: 'Anywhere',
+    gestures: [
+      { input: [{ key: 'Mod' }, { key: 'Z' }], action: 'Undo' },
+      { input: [{ key: 'Mod' }, { key: 'C' }], action: 'Copy the structure' },
+      {
+        input: [{ key: 'Mod' }, { key: 'V' }],
+        action: 'Paste a molfile, a SMILES or an idCode',
+      },
+      { input: [{ key: 'Delete' }], action: 'Delete the selection' },
+      {
+        input: [{ key: 'h' }, 'or', { key: 'v' }],
+        action: 'Flip horizontally or vertically',
+        only: 'molecule',
+      },
+      { input: [{ key: 'F1' }], action: 'Open this guide' },
+    ],
+    note: 'Keys act once the drawing has been clicked. On empty canvas, a key picks the tool whose tooltip shows it.',
+  },
+  {
+    title: 'Selecting',
+    gestures: [
+      { input: ['Drag'], action: 'Select what the lasso encloses' },
+      { input: [{ key: 'Alt' }, '+ drag'], action: 'Select a rectangle' },
+      { input: [{ key: 'Shift' }, '+ drag'], action: 'Add to the selection' },
+      { input: ['Drag the selection'], action: 'Move it' },
+      {
+        input: [{ key: 'Shift' }, '+ drag the selection'],
+        action: 'Copy it',
+      },
+      {
+        input: ['Double-click'],
+        action: 'Edit the query features of an atom, a bond or the selection',
+        only: 'fragment',
+      },
+    ],
+    note: 'These need the Select tool, which Space picks.',
+  },
+  {
+    title: 'Stereochemistry',
+    gestures: [],
+    note: 'Pink bonds flag a stereocentre with too little or too much information. Draw an up or down bond with its narrow end on the centre, then use the enhanced stereo tool to say whether the drawing is this enantiomer (abs), both of them (&) or one of the two (or).',
+  },
+];
+
+/** The documentation this guide summarises. */
+export const STRUCTURE_EDITOR_DOCS: readonly EditorGuideLink[] = [
+  { title: 'Tools and keys', url: 'https://docs.nmrium.org/help/ocl/' },
+  {
+    title: 'Atom properties',
+    url: 'https://docs.nmrium.org/chemical_structure/ocl/atom-properties/',
+  },
+  {
+    title: 'Stereochemistry',
+    url: 'https://docs.nmrium.org/ocl/stereochemistry/',
+  },
+];
+
+/** The editor a guide is written for. */
+export interface EditorGuideOptions {
+  /**
+   * Whether the editor draws one structure or a reaction.
+   * @default 'molecule'
+   */
+  mode?: 'molecule' | 'reaction';
+  /**
+   * Whether the editor draws a query fragment.
+   * @default false
+   */
+  fragment?: boolean;
+}
+
+/**
+ * The guide for one editor: gestures that do nothing there are left out, and so
+ * is a section left with nothing to say.
+ * @param options - The editor the guide is for.
+ * @returns The sections to show.
+ */
+export function editorGuideSections(
+  options: EditorGuideOptions = {},
+): EditorGuideSection[] {
+  const { mode = 'molecule', fragment = false } = options;
+  const sections: EditorGuideSection[] = [];
+  for (const section of STRUCTURE_EDITOR_GUIDE) {
+    const gestures = section.gestures.filter(({ only }) =>
+      appliesTo(only, mode, fragment),
+    );
+    if (gestures.length === 0 && section.note === undefined) continue;
+    sections.push({ ...section, gestures });
+  }
+  return sections;
+}
+
+function appliesTo(
+  only: EditorGuideScope | undefined,
+  mode: 'molecule' | 'reaction',
+  fragment: boolean,
+): boolean {
+  if (only === undefined) return true;
+  if (only === 'fragment') return fragment;
+  return only === mode;
+}
+
+/**
+ * The text of a key cap.
+ * @param key - The key, `Mod` standing for the platform's shortcut modifier.
+ * @param isMac - Whether the page runs on a Mac.
+ * @returns What the cap shows.
+ */
+export function editorKeyLabel(key: string, isMac: boolean): string {
+  if (key !== 'Mod') return key;
+  return isMac ? '⌘' : 'Ctrl';
+}

package/src/structure/core/editorToolbar.ts

@@ -0,0 +1,175 @@
+/**
+ * What each button of the openchemlib canvas editor's toolbar does.
+ *
+ * The toolbar is one canvas painted from a sprite, so there is no element per
+ * button to carry a title: the button under the pointer is found from where
+ * the pointer is (see `editorToolbarGeometry.ts`) and its entry here is what
+ * the tooltip says.
+ */
+
+/**
+ * Which editor a button works in. The reaction-only button is drawn greyed in
+ * a molecule editor, and the text tool is greyed in every editor react-ocl
+ * builds, since neither enables drawing objects.
+ */
+export type EditorToolbarAvailability = 'always' | 'reaction' | 'never';
+
+/** One button of the toolbar. */
+export interface EditorToolbarButton {
+  /** What the button is called. */
+  name: string;
+  /** What it does, in a sentence or two. */
+  description: string;
+  /**
+   * Keys that pick the tool, pressed while the pointer is over empty canvas.
+   * `Mod` stands for ⌘ on a Mac and Ctrl elsewhere.
+   * @default undefined — no key
+   */
+  keys?: readonly string[];
+  /**
+   * Which editor the button works in.
+   * @default 'always'
+   */
+  availability?: EditorToolbarAvailability;
+}
+
+/**
+ * The buttons, in the order the toolbar numbers them: down the first column,
+ * then down the second.
+ */
+export const EDITOR_TOOLBAR_BUTTONS: readonly EditorToolbarButton[] = [
+  { name: 'Clear', description: 'Erase the whole drawing.' },
+  {
+    name: 'Clean up',
+    description:
+      'Redraw the structure with fresh 2D coordinates. With part of it selected, the rest keeps its layout.',
+  },
+  {
+    name: 'Select',
+    description:
+      'Drag around atoms to select them: hold Alt for a rectangle, Shift to add to the selection. Drag a selection to move it, Shift-drag to copy it.',
+    keys: ['Space'],
+  },
+  {
+    name: 'Unknown configuration',
+    description:
+      'Click a stereocentre to mark its configuration as unknown; click again to undo it.',
+  },
+  {
+    name: 'Delete',
+    description: 'Click an atom or a bond to delete it.',
+    keys: ['0'],
+  },
+  {
+    name: 'Single bond',
+    description:
+      'Click empty space for a new bond, or drag from an atom. Clicking a bond again makes it double, then triple.',
+    keys: ['1'],
+  },
+  {
+    name: 'Up bond',
+    description:
+      'Wedged stereo bond, pointing toward the viewer. Its narrow end goes on the stereocentre.',
+    keys: ['u'],
+  },
+  ring('3-membered ring', '3'),
+  ring('5-membered ring', '5'),
+  ring('7-membered ring', '7'),
+  {
+    name: 'Positive charge',
+    description: 'Click an atom to raise its charge by one.',
+    keys: ['+'],
+  },
+  atom('Carbon', 'C', 'c'),
+  atom('Nitrogen', 'N', 'n'),
+  atom('Oxygen', 'O', 'o'),
+  atom('Fluorine', 'F', 'f'),
+  atom('Bromine', 'Br', 'b'),
+  atom('Hydrogen', 'H'),
+  { name: 'Undo', description: 'Revert the last change.', keys: ['Mod', 'Z'] },
+  {
+    name: 'Zoom and rotate',
+    description:
+      'Press where the centre should be, then drag up or down to zoom and sideways to rotate. With a selection, only that part moves.',
+    keys: ['z'],
+  },
+  {
+    name: 'Atom mapping',
+    description:
+      'Drag from a reactant atom to the same atom in a product: both get the same number. Click a mapped atom to unmap it.',
+    keys: ['m'],
+    availability: 'reaction',
+  },
+  {
+    name: 'Enhanced stereo',
+    description:
+      'Click a stereo bond to say what its centre means: abs, this enantiomer; &, both (racemic); or, one of the two. Press the button again to switch between the three.',
+  },
+  {
+    name: 'Text',
+    description: 'Place a text label in the drawing.',
+    availability: 'never',
+  },
+  {
+    name: 'Chain',
+    description:
+      'Drag from empty space or from an atom to draw a zigzag carbon chain.',
+    keys: ['2'],
+  },
+  {
+    name: 'Down bond',
+    description:
+      'Hashed stereo bond, pointing away from the viewer. Its narrow end goes on the stereocentre.',
+    keys: ['d'],
+  },
+  ring('4-membered ring', '4'),
+  ring('6-membered ring', '6'),
+  ring('Benzene ring', 'a'),
+  {
+    name: 'Negative charge',
+    description: 'Click an atom to lower its charge by one.',
+    keys: ['-'],
+  },
+  atom('Silicon', 'Si'),
+  atom('Phosphorus', 'P', 'p'),
+  atom('Sulfur', 'S', 's'),
+  atom('Chlorine', 'Cl', 'l'),
+  atom('Iodine', 'I', 'i'),
+  {
+    name: 'Any atom',
+    description:
+      'Pick any element, isotope, valence or radical in a dialog, then click to place it or to change an atom. Alt-click an atom to edit its own properties.',
+    keys: ['.'],
+  },
+];
+
+/**
+ * Whether a button can be used in an editor of the given kind.
+ * @param button - The button.
+ * @param mode - The kind of editor.
+ * @returns True when pressing the button selects its tool.
+ */
+export function isEditorToolbarButtonAvailable(
+  button: EditorToolbarButton,
+  mode: 'molecule' | 'reaction',
+): boolean {
+  const { availability = 'always' } = button;
+  if (availability === 'always') return true;
+  return availability === 'reaction' && mode === 'reaction';
+}
+
+function ring(name: string, key: string): EditorToolbarButton {
+  return {
+    name,
+    description:
+      'Click empty space for a new ring, a bond to fuse one onto it, or an atom for a spiro ring.',
+    keys: [key],
+  };
+}
+
+function atom(name: string, symbol: string, key?: string): EditorToolbarButton {
+  const description = `Click empty space for a new ${symbol} atom, or an atom to turn it into ${symbol}.`;
+  return key === undefined
+    ? { name, description }
+    : { name, description, keys: [key] };
+}

package/src/structure/core/editorToolbarGeometry.ts

@@ -0,0 +1,80 @@
+/**
+ * Where the openchemlib editor draws each toolbar button.
+ *
+ * The toolbar is two columns of seventeen square buttons inside a thin border,
+ * numbered down the first column and then down the second, as
+ * `EDITOR_TOOLBAR_BUTTONS` lists them. Every length here is in CSS pixels at
+ * the size openchemlib draws the toolbar, and is scaled by the height the
+ * toolbar is measured at, so a toolbar drawn larger still maps correctly.
+ */
+
+/** Buttons in one column of the toolbar. */
+export const EDITOR_TOOLBAR_ROWS = 17;
+
+/** Columns of the toolbar. */
+export const EDITOR_TOOLBAR_COLUMNS = 2;
+
+/** Side of one button, in CSS pixels. */
+const BUTTON_SIZE = 21;
+
+/** Border around the buttons, in CSS pixels. */
+const BORDER = 2;
+
+/** Height of the toolbar as openchemlib draws it, in CSS pixels. */
+const DRAWN_HEIGHT = EDITOR_TOOLBAR_ROWS * BUTTON_SIZE + 2 * BORDER;
+
+/** Where a button is drawn, in CSS pixels from the toolbar's top left corner. */
+export interface EditorToolbarButtonBox {
+  left: number;
+  top: number;
+  width: number;
+  height: number;
+}
+
+/**
+ * The button under a point of the toolbar.
+ * @param x - Distance from the toolbar's left edge, in CSS pixels.
+ * @param y - Distance from the toolbar's top edge, in CSS pixels.
+ * @param toolbarHeight - Height the toolbar is measured at, in CSS pixels.
+ * @returns The button's index, or -1 when the point is on no button.
+ */
+export function editorToolbarButtonAt(
+  x: number,
+  y: number,
+  toolbarHeight: number,
+): number {
+  const scale = scaleOf(toolbarHeight);
+  if (scale === 0) return -1;
+  const column = Math.floor((x / scale - BORDER) / BUTTON_SIZE);
+  const row = Math.floor((y / scale - BORDER) / BUTTON_SIZE);
+  if (column < 0 || column >= EDITOR_TOOLBAR_COLUMNS) return -1;
+  if (row < 0 || row >= EDITOR_TOOLBAR_ROWS) return -1;
+  return column * EDITOR_TOOLBAR_ROWS + row;
+}
+
+/**
+ * Where a button is drawn.
+ * @param button - The button's index.
+ * @param toolbarHeight - Height the toolbar is measured at, in CSS pixels.
+ * @returns The button's box, relative to the toolbar.
+ */
+export function editorToolbarButtonBox(
+  button: number,
+  toolbarHeight: number,
+): EditorToolbarButtonBox {
+  const scale = scaleOf(toolbarHeight);
+  const column = Math.floor(button / EDITOR_TOOLBAR_ROWS);
+  const row = button % EDITOR_TOOLBAR_ROWS;
+  return {
+    left: (BORDER + column * BUTTON_SIZE) * scale,
+    top: (BORDER + row * BUTTON_SIZE) * scale,
+    width: BUTTON_SIZE * scale,
+    height: BUTTON_SIZE * scale,
+  };
+}
+
+function scaleOf(toolbarHeight: number): number {
+  return Number.isFinite(toolbarHeight) && toolbarHeight > 0
+    ? toolbarHeight / DRAWN_HEIGHT
+    : 0;
+}

package/src/structure/core/index.ts

@@ -1,5 +1,34 @@
 export type { AtomLabelPlacement, LabelledMolecule } from './atomLabels.ts';
 export { applyAtomLabels, customAtomLabel } from './atomLabels.ts';
+export type {
+  EditorGesture,
+  EditorGuideKey,
+  EditorGuideLink,
+  EditorGuideOptions,
+  EditorGuideScope,
+  EditorGuideSection,
+} from './editorGuide.ts';
+export {
+  STRUCTURE_EDITOR_DOCS,
+  STRUCTURE_EDITOR_GUIDE,
+  editorGuideSections,
+  editorKeyLabel,
+} from './editorGuide.ts';
+export type {
+  EditorToolbarAvailability,
+  EditorToolbarButton,
+} from './editorToolbar.ts';
+export {
+  EDITOR_TOOLBAR_BUTTONS,
+  isEditorToolbarButtonAvailable,
+} from './editorToolbar.ts';
+export type { EditorToolbarButtonBox } from './editorToolbarGeometry.ts';
+export {
+  EDITOR_TOOLBAR_COLUMNS,
+  EDITOR_TOOLBAR_ROWS,
+  editorToolbarButtonAt,
+  editorToolbarButtonBox,
+} from './editorToolbarGeometry.ts';
 export type { EditorLine, EditorValue } from './editorValue.ts';
 export type { IdCodeValue } from './editorValue.ts';
 export { isEmptyIdCode, splitEditorValue, splitIdCode } from './editorValue.ts';

package/src/structure/core/pendingCall.ts

@@ -0,0 +1,59 @@
+/** A call held back until its value has been still, which can be cut short. */
+export interface PendingCall<TValue> {
+  /**
+   * Hold a value back, replacing whichever one was waiting.
+   * @param value - The value to deliver.
+   * @param delay - How long to wait, in milliseconds; `0` or less delivers now.
+   * @param deliver - What the value is handed to.
+   */
+  push: (
+    value: TValue,
+    delay: number,
+    deliver: (value: TValue) => void,
+  ) => void;
+  /** Forget the value waiting, which is then never delivered. */
+  drop: () => void;
+  /** Deliver the value waiting now rather than when its delay runs out. */
+  flush: () => void;
+}
+
+/**
+ * A trailing debounce for one value at a time, whose waiting value can be
+ * delivered early or thrown away.
+ * @returns The pending call, holding nothing.
+ */
+export function createPendingCall<TValue>(): PendingCall<TValue> {
+  let pending: {
+    value: TValue;
+    deliver: (value: TValue) => void;
+    timer: ReturnType<typeof setTimeout>;
+  } | null = null;
+
+  function drop(): void {
+    if (pending === null) return;
+    clearTimeout(pending.timer);
+    pending = null;
+  }
+
+  return {
+    push(value, delay, deliver) {
+      drop();
+      if (delay <= 0) {
+        deliver(value);
+        return;
+      }
+      const timer = setTimeout(() => {
+        pending = null;
+        deliver(value);
+      }, delay);
+      pending = { value, deliver, timer };
+    },
+    drop,
+    flush() {
+      if (pending === null) return;
+      const { value, deliver } = pending;
+      drop();
+      deliver(value);
+    },
+  };
+}

package/src/structure/ui/EditorCanvas.tsx

@@ -7,23 +7,11 @@ import type {
 } 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;
-}
+import type {
+  StructureEditorChange,
+  StructureEditorMode,
+} from './editorChange.ts';
+import { moleculeChange, reactionChange } from './editorChange.ts';
 
 interface EditorCanvasProps {
   /** Called on every stroke, with the editor read out synchronously. */
@@ -71,29 +59,15 @@ export function EditorCanvas(props: EditorCanvasProps): ReactElement {
   } = props;
   const [initialValue] = useState(value);
 
+  // The event describes the editor only while the callback runs, so it is read
+  // out now and whatever waiting there is happens afterwards.
   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(),
-      });
-    },
+    (event: CanvasEditorOnChangeMolecule) => onChange(moleculeChange(event)),
     [onChange],
   );
 
   const handleReaction = useCallback(
-    (event: CanvasEditorOnChangeReaction) => {
-      onChange({
-        mode: 'reaction',
-        idCode: event.getIdcode(),
-        molfile: event.getRxn(),
-        smiles: event.getSmiles(),
-      });
-    },
+    (event: CanvasEditorOnChangeReaction) => onChange(reactionChange(event)),
     [onChange],
   );