react-cheminfo 0.66.0 → 0.67.0

package/src/structure/ui/StructureEditor.tsx

@@ -8,29 +8,26 @@
  */
 
 import type { CSSProperties, ReactElement } from 'react';
-import {
-  Suspense,
-  lazy,
-  useCallback,
-  useEffect,
-  useRef,
-  useState,
-} from 'react';
-import type { CanvasEditorInputFormat } from 'react-ocl';
+import { Suspense, lazy, useCallback } from 'react';
 
 import { useChromeT } from '../../i18n/ui/useT.ts';
 import { TOKEN } from '../../tokens/core/familyTokens.ts';
-import { createPendingCall } from '../core/pendingCall.ts';
 
 import { EditorHelpButton } from './EditorHelpButton.tsx';
+import { EditorImportButton } from './EditorImportButton.tsx';
+import { EditorImportProblem } from './EditorImportProblem.tsx';
+import { StructureDropOverlay } from './StructureDropOverlay.tsx';
 import { ToolbarTooltip } from './ToolbarTooltip.tsx';
-import type {
-  StructureEditorChange,
-  StructureEditorMode,
-} from './editorChange.ts';
+import type { StructureEditorChange } from './editorChange.ts';
+import type { StructureEditorProps } from './structureEditorProps.ts';
+import { useDebouncedChange } from './useDebouncedChange.ts';
 import { useEditorStructure } from './useEditorStructure.ts';
+import { useStructureDrop } from './useStructureDrop.ts';
+import { useStructureImport } from './useStructureImport.ts';
 import { useToolbarFloor } from './useToolbarFloor.ts';
 
+export type { StructureEditorProps } from './structureEditorProps.ts';
+
 const EditorExportButton = lazy(async () => {
   const module = await import('./EditorExportButton.tsx');
   return { default: module.EditorExportButton };
@@ -41,84 +38,6 @@ 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`
-   * milliseconds, with every notation read out of the editor.
-   */
-  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. Read once, when the editor appears and again on
-   * every change of `revision`: the editor is uncontrolled, so feeding the
-   * drawing back into it would replace the structure and reset every
-   * coordinate under the pen.
-   * @default ''
-   */
-  value?: string;
-  /**
-   * Bumped by the caller to load `value` into the canvas again, which is what
-   * an example, a share link or a Clear button does. Changing it discards
-   * whatever was being drawn.
-   * @default 0
-   */
-  revision?: number;
-  /**
-   * How long the drawing has to be still before `onChange` is called, in
-   * milliseconds. Long enough that drawing a ring does not publish six
-   * structures; `0` reports every stroke.
-   * @default 300
-   */
-  debounce?: number;
-  /**
-   * Smallest height of the drawing area, in pixels. Raised to whatever the
-   * toolbar needs, which is usually more.
-   * @default 320
-   */
-  minHeight?: number;
-  /**
-   * Whether the editor draws one structure or a reaction. A reaction canvas
-   * has its own toolbar and its own arrow.
-   * @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;
-  /**
-   * Put a button in the corner that opens every notation of the drawing — its
-   * SMILES, its molfiles, its canonical identifiers — and the picture of it,
-   * ready to copy or to save. A reaction has none of those, so it is never
-   * offered one.
-   * @default true
-   */
-  exportable?: boolean;
-  /**
-   * 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.
-   * @default undefined
-   */
-  style?: CSSProperties;
-}
-
 /**
  * The canvas structure editor, sized to fill its container and never to hide
  * part of its toolbar, with a tooltip on every toolbar button and a guide to
@@ -138,13 +57,15 @@ export function StructureEditor(props: StructureEditorProps): ReactElement {
     mode = 'molecule',
     help = true,
     exportable = true,
+    importable = true,
+    onImport,
     className,
     style,
   } = props;
 
   const t = useChromeT();
   const containerRef = useToolbarFloor({ minHeight, revision });
-  const handleChange = useDebounced(onChange, debounce, revision);
+  const handleChange = useDebouncedChange(onChange, debounce, revision);
   const drawing = useEditorStructure({ value, inputFormat, revision });
   const handleEdit = useCallback(
     (change: StructureEditorChange) => {
@@ -155,12 +76,21 @@ export function StructureEditor(props: StructureEditorProps): ReactElement {
     },
     [drawing, handleChange],
   );
+  const imports = useStructureImport({
+    revision,
+    fragment,
+    onImport,
+    onRead: handleEdit,
+  });
+  const takesImports = importable && mode === 'molecule';
+  const drop = useStructureDrop(takesImports ? imports.load : undefined);
 
   return (
     <div
       ref={containerRef}
       className={className}
       style={{ ...ROOT_STYLE, minHeight, ...style }}
+      {...drop.targetProps}
     >
       <Suspense
         fallback={
@@ -168,17 +98,23 @@ export function StructureEditor(props: StructureEditorProps): ReactElement {
         }
       >
         <EditorCanvas
-          key={revision}
+          key={imports.canvasKey}
           onChange={handleEdit}
           fragment={fragment}
-          inputFormat={inputFormat}
-          value={value}
+          inputFormat={imports.idCode === null ? inputFormat : 'idcode'}
+          value={imports.idCode ?? value}
           mode={mode}
         />
         {help ? (
           <ToolbarTooltip containerRef={containerRef} mode={mode} />
         ) : null}
         <div style={CORNER_STYLE}>
+          {takesImports ? (
+            <EditorImportButton
+              onImport={imports.load}
+              accept={onImport === undefined ? STRUCTURE_FILES : undefined}
+            />
+          ) : null}
           {exportable && mode === 'molecule' ? (
             <EditorExportButton
               source={drawing.source}
@@ -194,47 +130,23 @@ export function StructureEditor(props: StructureEditorProps): ReactElement {
             />
           ) : null}
         </div>
+        {imports.problem === null ? null : (
+          <EditorImportProblem
+            problem={imports.problem}
+            onDismiss={imports.dismiss}
+          />
+        )}
       </Suspense>
+      {drop.over ? (
+        <StructureDropOverlay
+          label={t('structure.import.drop')}
+          handlers={drop.overlayProps}
+        />
+      ) : null}
     </div>
   );
 }
 
-/**
- * Report the last edit of a burst rather than every one of them.
- *
- * 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
- * replaces the structure describes a canvas that no longer exists.
- * @returns The handler to give the canvas.
- */
-function useDebounced(
-  onChange: (change: StructureEditorChange) => void,
-  delay: number,
-  resetKey: number,
-): (change: StructureEditorChange) => void {
-  const [pending] = useState(createPendingCall<StructureEditorChange>);
-  const onChangeRef = useRef(onChange);
-  useEffect(() => {
-    onChangeRef.current = onChange;
-  });
-  useEffect(() => {
-    pending.drop();
-  }, [pending, resetKey]);
-  useEffect(() => () => pending.flush(), [pending]);
-
-  return useCallback(
-    (change: StructureEditorChange) => {
-      pending.push(change, delay, (value) => onChangeRef.current(value));
-    },
-    [pending, delay],
-  );
-}
-
 /**
  * The canvas is positioned out of the height computation, so the container's
  * own height is what the measured toolbar floor writes on it. The `minHeight`
@@ -252,8 +164,8 @@ const ROOT_STYLE: CSSProperties = {
 };
 
 /**
- * The corner the editor's own buttons sit in: export first, then help, so the
- * one that does something to the drawing is the nearer of the two to it.
+ * The corner the editor's own buttons sit in: open, export, then help — the
+ * drawing in, the drawing out, and the guide last.
  */
 const CORNER_STYLE: CSSProperties = {
   position: 'absolute',
@@ -273,3 +185,6 @@ const LOADING_STYLE: CSSProperties = {
   color: TOKEN.textFaint,
   fontSize: 13,
 };
+
+/** What the editor reads itself, offered first by the file picker. */
+const STRUCTURE_FILES = '.mol,.sdf,.sd,.smi,.smiles,.txt';

package/src/structure/ui/importedStructure.ts

@@ -0,0 +1,83 @@
+/**
+ * Read a structure dropped on the editor, or opened from disk.
+ *
+ * **Not exported from `ui/index.ts`**: it value-imports `openchemlib`. The
+ * editor loads it on the first drop, by which time the canvas has already
+ * brought openchemlib in.
+ */
+
+import { Canonizer, Molecule } from 'openchemlib';
+
+import { splitEditorValue } from '../core/editorValue.ts';
+
+import type { StructureEditorMoleculeChange } from './editorChange.ts';
+
+/**
+ * Turn dropped text into what the editor reports after an edit.
+ *
+ * A molfile is read whole, so an SDF gives its first record. Anything else is
+ * read from its first meaningful line, as a SMILES and then as an idCode — but
+ * an idCode only when it is the canonical one, because openchemlib decodes
+ * almost any word into some molecule: `ethanol` read as an idCode has 1106
+ * atoms. A word holding a character no idCode holds is never decoded, since
+ * openchemlib does not return from some of them — `O=Cc1cccc`, a SMILES with
+ * an unclosed ring, is one. A 3D structure is laid out flat, since the canvas
+ * draws in 2D.
+ * @param text - The file's content or the dragged text.
+ * @param fragment - Whether the editor draws a query fragment.
+ * @returns The change, or `null` when the text holds no structure.
+ */
+export function readImportedStructure(
+  text: string,
+  fragment: boolean,
+): StructureEditorMoleculeChange | null {
+  const molecule = parseStructure(text);
+  if (molecule === null || molecule.getAllAtoms() === 0) return null;
+  if (hasDepth(molecule)) molecule.inventCoordinates();
+  molecule.setFragment(fragment);
+
+  const canonizer = new Canonizer(molecule);
+  return {
+    mode: 'molecule',
+    idCode: `${canonizer.getIDCode()} ${canonizer.getEncodedCoordinates(false)}`,
+    molfile: molecule.toMolfile(),
+    smiles: molecule.toIsomericSmiles(),
+    molecule: molecule.getCompactCopy(),
+  };
+}
+
+function parseStructure(text: string): Molecule | null {
+  const value = splitEditorValue(text);
+  if (value.kind === 'molfile') {
+    return attempt(() => Molecule.fromMolfile(value.molfile));
+  }
+  const notation = value.entries[0]?.structure;
+  if (notation === undefined) return null;
+  return (
+    attempt(() => Molecule.fromSmiles(notation)) ?? canonicalIdCode(notation)
+  );
+}
+
+function canonicalIdCode(text: string): Molecule | null {
+  if (!ID_CODE.test(text)) return null;
+  const molecule = attempt(() => Molecule.fromIDCode(text));
+  return molecule?.getIDCode() === text ? molecule : null;
+}
+
+function attempt(parse: () => Molecule): Molecule | null {
+  try {
+    return parse();
+  } catch {
+    return null;
+  }
+}
+
+function hasDepth(molecule: Molecule): boolean {
+  for (let atom = 0; atom < molecule.getAllAtoms(); atom++) {
+    if (molecule.getAtomZ(atom) !== 0) return true;
+  }
+  return false;
+}
+
+/** An idCode is written in six-bit groups offset to `@`, so in `@` to DEL. */
+const ID_CODE = /^[\u0040-\u007F]+$/;

package/src/structure/ui/index.ts

@@ -21,6 +21,8 @@ export type { StructureLabels, StructureProps } from './Structure.tsx';
 export { Structure } from './Structure.tsx';
 export type { StructureEditorProps } from './StructureEditor.tsx';
 export { StructureEditor } from './StructureEditor.tsx';
+export type { StructureDropProps } from './StructureDrop.tsx';
+export { StructureDrop } from './StructureDrop.tsx';
 export type { StructureEditorHelpProps } from './StructureEditorHelp.tsx';
 export { StructureEditorHelp } from './StructureEditorHelp.tsx';
 export type { StructureExportDialogProps } from './StructureExportDialog.tsx';

package/src/structure/ui/structureEditorProps.ts

@@ -0,0 +1,103 @@
+import type { CSSProperties } from 'react';
+import type { CanvasEditorInputFormat } from 'react-ocl';
+
+import type { StructureTransfer } from '../core/structureTransfer.ts';
+
+import type {
+  StructureEditorChange,
+  StructureEditorMode,
+} from './editorChange.ts';
+
+/** What `StructureEditor` needs. */
+export interface StructureEditorProps {
+  /**
+   * Called after every edit, once the drawing has been still for `debounce`
+   * milliseconds, with every notation read out of the editor.
+   */
+  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. Read once, when the editor appears and again on
+   * every change of `revision`: the editor is uncontrolled, so feeding the
+   * drawing back into it would replace the structure and reset every
+   * coordinate under the pen.
+   * @default ''
+   */
+  value?: string;
+  /**
+   * Bumped by the caller to load `value` into the canvas again, which is what
+   * an example, a share link or a Clear button does. Changing it discards
+   * whatever was being drawn.
+   * @default 0
+   */
+  revision?: number;
+  /**
+   * How long the drawing has to be still before `onChange` is called, in
+   * milliseconds. Long enough that drawing a ring does not publish six
+   * structures; `0` reports every stroke.
+   * @default 300
+   */
+  debounce?: number;
+  /**
+   * Smallest height of the drawing area, in pixels. Raised to whatever the
+   * toolbar needs, which is usually more.
+   * @default 320
+   */
+  minHeight?: number;
+  /**
+   * Whether the editor draws one structure or a reaction. A reaction canvas
+   * has its own toolbar and its own arrow.
+   * @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;
+  /**
+   * Put a button in the corner that opens every notation of the drawing — its
+   * SMILES, its molfiles, its canonical identifiers — and the picture of it,
+   * ready to copy or to save. A reaction has none of those, so it is never
+   * offered one.
+   * @default true
+   */
+  exportable?: boolean;
+  /**
+   * Take a structure dropped on the canvas — a molfile, an SDF, a SMILES or
+   * an idCode, as a file or as text dragged from another page — and put a
+   * button in the corner that opens one from disk. A reaction canvas takes
+   * none.
+   * @default true
+   */
+  importable?: boolean;
+  /**
+   * Take what is dropped or opened yourself instead of letting the editor read
+   * it, for a page that reads more than the canvas does — an XYZ, a PDB, a 3D
+   * geometry the canvas would flatten. The page then loads the structure back
+   * through `value` and `revision`, like any other.
+   * @default undefined
+   */
+  onImport?: (transfer: StructureTransfer) => void;
+  /**
+   * 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.
+   * @default undefined
+   */
+  style?: CSSProperties;
+}

package/src/structure/ui/useDebouncedChange.ts

@@ -0,0 +1,41 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import { createPendingCall } from '../core/pendingCall.ts';
+
+import type { StructureEditorChange } from './editorChange.ts';
+
+/**
+ * Report the last edit of a burst rather than every one of them.
+ *
+ * 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
+ * replaces the structure describes a canvas that no longer exists.
+ * @returns The handler to give the canvas.
+ */
+export function useDebouncedChange(
+  onChange: (change: StructureEditorChange) => void,
+  delay: number,
+  resetKey: number,
+): (change: StructureEditorChange) => void {
+  const [pending] = useState(createPendingCall<StructureEditorChange>);
+  const onChangeRef = useRef(onChange);
+  useEffect(() => {
+    onChangeRef.current = onChange;
+  });
+  useEffect(() => {
+    pending.drop();
+  }, [pending, resetKey]);
+  useEffect(() => () => pending.flush(), [pending]);
+
+  return useCallback(
+    (change: StructureEditorChange) => {
+      pending.push(change, delay, (value) => onChangeRef.current(value));
+    },
+    [pending, delay],
+  );
+}

package/src/structure/ui/useStructureDrop.ts

@@ -0,0 +1,76 @@
+import type { DragEvent } from 'react';
+import { useMemo, useState } from 'react';
+
+import type { StructureTransfer } from '../core/structureTransfer.ts';
+import {
+  carriesStructure,
+  readStructureTransfer,
+} from '../core/structureTransfer.ts';
+
+/** The drag handlers of one element. */
+export interface DropHandlers {
+  onDragEnter?: (event: DragEvent<HTMLElement>) => void;
+  onDragOver?: (event: DragEvent<HTMLElement>) => void;
+  onDragLeave?: (event: DragEvent<HTMLElement>) => void;
+  onDrop?: (event: DragEvent<HTMLElement>) => void;
+}
+
+/** A drop target, in two parts: the element and the overlay it raises. */
+export interface StructureDropTarget {
+  /** Whether a file or text is being dragged over the target. */
+  over: boolean;
+  /** Put on the element that takes the drop. */
+  targetProps: DropHandlers;
+  /**
+   * Put on the overlay drawn while `over`. It covers the target and takes
+   * every drag event from then on, so moving across the canvas and the buttons
+   * underneath never reads as leaving, and leaving the overlay is leaving.
+   */
+  overlayProps: DropHandlers;
+}
+
+/**
+ * Take a file or text dropped on an element.
+ * @param onDrop - Where the drop goes; `undefined` takes none.
+ * @returns Whether a drag is over the element, and the handlers to put on it
+ * and on its overlay.
+ */
+export function useStructureDrop(
+  onDrop: ((transfer: StructureTransfer) => void) | undefined,
+): StructureDropTarget {
+  const [over, setOver] = useState(false);
+
+  return useMemo(() => {
+    if (onDrop === undefined) {
+      return { over: false, targetProps: {}, overlayProps: {} };
+    }
+    const accept = (event: DragEvent<HTMLElement>): boolean => {
+      if (!carriesStructure(event.dataTransfer.types)) return false;
+      event.preventDefault();
+      event.dataTransfer.dropEffect = 'copy';
+      return true;
+    };
+    return {
+      over,
+      targetProps: {
+        onDragEnter: (event) => {
+          if (accept(event)) setOver(true);
+        },
+        onDragOver: accept,
+      },
+      overlayProps: {
+        onDragOver: accept,
+        onDragLeave: (event) => {
+          if (event.target === event.currentTarget) setOver(false);
+        },
+        onDrop: (event) => {
+          setOver(false);
+          const transfer = readStructureTransfer(event.dataTransfer);
+          if (transfer === null) return;
+          event.preventDefault();
+          onDrop(transfer);
+        },
+      },
+    };
+  }, [onDrop, over]);
+}