react-cheminfo 0.17.0 → 0.19.0

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],
   );
 

package/src/structure/ui/EditorHelpButton.tsx

@@ -0,0 +1,70 @@
+import { Button, PopoverNext, Tooltip } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement, RefObject } from 'react';
+import { useEffect, useState } from 'react';
+
+import { StructureEditorHelp } from './StructureEditorHelp.tsx';
+import type { StructureEditorMode } from './editorChange.ts';
+
+/** What {@link EditorHelpButton} needs. */
+export interface EditorHelpButtonProps {
+  /** The element wrapping the editor, which F1 is listened for on. */
+  containerRef: RefObject<HTMLElement | null>;
+  /** Which editor the guide is written for. */
+  mode: StructureEditorMode;
+  /** Whether the editor draws a query fragment. */
+  fragment: boolean;
+}
+
+/**
+ * The editor's help button, in the corner of the drawing, opening the guide to
+ * the mouse and the keyboard.
+ *
+ * F1 opens it too: openchemlib binds that key to a help dialog it does not
+ * implement on the web.
+ * @param props - See {@link EditorHelpButtonProps}.
+ * @returns The button and its popover.
+ */
+export function EditorHelpButton(props: EditorHelpButtonProps): ReactElement {
+  const { containerRef, mode, fragment } = props;
+  const [isOpen, setIsOpen] = useState(false);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (container === null) return;
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (event.key !== 'F1') return;
+      event.preventDefault();
+      setIsOpen(true);
+    };
+    container.addEventListener('keydown', onKeyDown);
+    return () => container.removeEventListener('keydown', onKeyDown);
+  }, [containerRef]);
+
+  return (
+    <div style={CORNER_STYLE}>
+      <PopoverNext
+        isOpen={isOpen}
+        onInteraction={setIsOpen}
+        placement="left-start"
+        content={<StructureEditorHelp mode={mode} fragment={fragment} />}
+      >
+        <Tooltip content={LABEL} placement="left" disabled={isOpen}>
+          <Button
+            variant="minimal"
+            size="small"
+            icon="help"
+            aria-label={LABEL}
+          />
+        </Tooltip>
+      </PopoverNext>
+    </div>
+  );
+}
+
+const LABEL = 'Mouse and keyboard';
+
+const CORNER_STYLE: CSSProperties = {
+  position: 'absolute',
+  top: 4,
+  right: 4,
+};

package/src/structure/ui/KeyCaps.tsx

@@ -0,0 +1,40 @@
+import { Classes } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+
+import { editorKeyLabel } from '../core/editorGuide.ts';
+
+/**
+ * Keys pressed together, each drawn as a key cap, `Mod` as the modifier the
+ * editor listens to on this platform.
+ * @param props - The keys.
+ * @param props.keys - The keys, unique within the list.
+ * @returns The key caps.
+ */
+export function KeyCaps(props: { keys: readonly string[] }): ReactElement {
+  const isMac = isMacPlatform();
+  return (
+    <span style={KEYS_STYLE}>
+      {props.keys.map((key) => (
+        <kbd key={key} className={Classes.KEY}>
+          {editorKeyLabel(key, isMac)}
+        </kbd>
+      ))}
+    </span>
+  );
+}
+
+/**
+ * Whether the page runs on a Mac, decided as openchemlib decides it, so the
+ * cap shown is the modifier the editor actually reads: ⌘ there, Ctrl elsewhere.
+ * @returns True on a Mac.
+ */
+function isMacPlatform(): boolean {
+  return typeof navigator !== 'undefined' && navigator.platform === 'MacIntel';
+}
+
+const KEYS_STYLE: CSSProperties = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  gap: 3,
+  whiteSpace: 'nowrap',
+};

package/src/structure/ui/StructureEditor.tsx

@@ -8,15 +8,25 @@
  */
 
 import type { CSSProperties, ReactElement } from 'react';
-import { Suspense, lazy, useCallback, useEffect, useRef } from 'react';
+import {
+  Suspense,
+  lazy,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
 import type { CanvasEditorInputFormat } from 'react-ocl';
 
 import { TOKEN } from '../../tokens/core/familyTokens.ts';
+import { createPendingCall } from '../core/pendingCall.ts';
 
+import { EditorHelpButton } from './EditorHelpButton.tsx';
+import { ToolbarTooltip } from './ToolbarTooltip.tsx';
 import type {
   StructureEditorChange,
   StructureEditorMode,
-} from './EditorCanvas.tsx';
+} from './editorChange.ts';
 import { useToolbarFloor } from './useToolbarFloor.ts';
 
 const EditorCanvas = lazy(async () => {
@@ -76,6 +86,12 @@ export interface StructureEditorProps {
    * @default 'molecule'
    */
   mode?: StructureEditorMode;
+  /**
+   * Explain each toolbar button in a tooltip, and put a button in the corner
+   * that opens a guide to the mouse and the keyboard, which F1 opens too.
+   * @default true
+   */
+  help?: boolean;
   /**
    * Class the container carries, so a site can reach it from its stylesheet.
    * @default undefined
@@ -90,7 +106,8 @@ export interface StructureEditorProps {
 
 /**
  * The canvas structure editor, sized to fill its container and never to hide
- * part of its toolbar.
+ * part of its toolbar, with a tooltip on every toolbar button and a guide to
+ * the keys.
  * @param props - What to draw, when to reload it, and where to send it.
  * @returns The editor.
  */
@@ -104,6 +121,7 @@ export function StructureEditor(props: StructureEditorProps): ReactElement {
     debounce = 300,
     minHeight = 320,
     mode = 'molecule',
+    help = true,
     className,
     style,
   } = props;
@@ -126,6 +144,16 @@ export function StructureEditor(props: StructureEditorProps): ReactElement {
           value={value}
           mode={mode}
         />
+        {help ? (
+          <>
+            <ToolbarTooltip containerRef={containerRef} mode={mode} />
+            <EditorHelpButton
+              containerRef={containerRef}
+              mode={mode}
+              fragment={fragment}
+            />
+          </>
+        ) : null}
       </Suspense>
     </div>
   );
@@ -136,6 +164,8 @@ export function StructureEditor(props: StructureEditorProps): ReactElement {
  *
  * The editor's own event is read out before the wait starts, so what arrives
  * late is a plain object rather than a handle on an editor that has moved on.
+ * An editor removed mid-burst — a tab switched, a card folded — still reports
+ * its last edit, which would otherwise be lost with the timer.
  * @param onChange - What the caller wants told.
  * @param delay - How long the drawing has to be still, in milliseconds.
  * @param resetKey - Dropped edits: a burst still waiting when the caller
@@ -147,33 +177,21 @@ function useDebounced(
   delay: number,
   resetKey: number,
 ): (change: StructureEditorChange) => void {
-  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [pending] = useState(createPendingCall<StructureEditorChange>);
   const onChangeRef = useRef(onChange);
   useEffect(() => {
     onChangeRef.current = onChange;
   });
   useEffect(() => {
-    return () => {
-      if (timerRef.current !== null) {
-        clearTimeout(timerRef.current);
-        timerRef.current = null;
-      }
-    };
-  }, [resetKey]);
+    pending.drop();
+  }, [pending, resetKey]);
+  useEffect(() => () => pending.flush(), [pending]);
 
   return useCallback(
     (change: StructureEditorChange) => {
-      if (timerRef.current !== null) clearTimeout(timerRef.current);
-      if (delay <= 0) {
-        onChangeRef.current(change);
-        return;
-      }
-      timerRef.current = setTimeout(() => {
-        timerRef.current = null;
-        onChangeRef.current(change);
-      }, delay);
+      pending.push(change, delay, (value) => onChangeRef.current(value));
     },
-    [delay],
+    [pending, delay],
   );
 }