react-cheminfo 0.65.0 → 0.67.0

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]);
+}

package/src/structure/ui/useStructureImport.ts

@@ -0,0 +1,122 @@
+import { useCallback, useRef, useState } from 'react';
+
+import type { StructureTransfer } from '../core/structureTransfer.ts';
+
+import type { StructureEditorMoleculeChange } from './editorChange.ts';
+
+/** What {@link useStructureImport} needs. */
+export interface StructureImportOptions {
+  /** Bumped by the caller to load its own value, which drops any import. */
+  revision: number;
+  /** Whether the editor draws a query fragment. */
+  fragment: boolean;
+  /** The caller's own reader, which then takes every drop instead. */
+  onImport: ((transfer: StructureTransfer) => void) | undefined;
+  /** Where a structure the editor read goes: the path an edit takes. */
+  onRead: (change: StructureEditorMoleculeChange) => void;
+}
+
+/** Why the last drop loaded nothing. */
+export interface StructureImportProblem {
+  /** The file that was read, `null` for dragged text. */
+  file: string | null;
+}
+
+/** The editor's imports, as the canvas and its corner need them. */
+export interface StructureImport {
+  /**
+   * The idCode the canvas loads instead of the caller's value, `null` while it
+   * shows that value.
+   */
+  idCode: string | null;
+  /** The canvas's key: a new one per import, which loads it. */
+  canvasKey: string;
+  /** Read a drop or a chosen file. */
+  load: (transfer: StructureTransfer) => void;
+  /** Why the last drop loaded nothing, `null` when it did. */
+  problem: StructureImportProblem | null;
+  /** Forget the problem. */
+  dismiss: () => void;
+}
+
+/** One import into the canvas, and which load of it it replaced. */
+interface Imported {
+  revision: number;
+  count: number;
+  idCode: string;
+}
+
+/**
+ * Load what is dropped on the editor, or opened from disk, into its canvas.
+ *
+ * The canvas is uncontrolled, so a dropped structure — one the editor never
+ * produced — remounts it with a new key, and is then reported like an edit.
+ * A drop overtaken by a later one is dropped rather than applied late.
+ * @param options - See {@link StructureImportOptions}.
+ * @returns See {@link StructureImport}.
+ */
+export function useStructureImport(
+  options: StructureImportOptions,
+): StructureImport {
+  const { revision, fragment, onImport, onRead } = options;
+  const [imported, setImported] = useState<Imported | null>(null);
+  const [problem, setProblem] = useState<StructureImportProblem | null>(null);
+  const token = useRef(0);
+
+  const load = useCallback(
+    (transfer: StructureTransfer) => {
+      setProblem(null);
+      if (onImport !== undefined) {
+        onImport(transfer);
+        return;
+      }
+      const current = ++token.current;
+      void readTransfer(transfer, fragment).then(({ file, change }) => {
+        if (current !== token.current) return;
+        if (change === null) {
+          setProblem({ file });
+          return;
+        }
+        setImported((previous) => ({
+          revision,
+          count: previous?.revision === revision ? previous.count + 1 : 1,
+          idCode: change.idCode,
+        }));
+        onRead(change);
+      });
+    },
+    [fragment, onImport, onRead, revision],
+  );
+
+  const dismiss = useCallback(() => setProblem(null), []);
+  const current = imported?.revision === revision ? imported : null;
+
+  return {
+    idCode: current?.idCode ?? null,
+    canvasKey: `${revision}.${current?.count ?? 0}`,
+    load,
+    problem,
+    dismiss,
+  };
+}
+
+async function readTransfer(
+  transfer: StructureTransfer,
+  fragment: boolean,
+): Promise<{
+  file: string | null;
+  change: StructureEditorMoleculeChange | null;
+}> {
+  const file = transfer.kind === 'files' ? transfer.files[0] : undefined;
+  try {
+    const text =
+      transfer.kind === 'text' ? transfer.text : ((await file?.text()) ?? '');
+    const { readImportedStructure } = await import('./importedStructure.ts');
+    return {
+      file: file?.name ?? null,
+      change: readImportedStructure(text, fragment),
+    };
+  } catch {
+    return { file: file?.name ?? null, change: null };
+  }
+}