react-cheminfo 0.65.0 → 0.67.0

package/src/server/answerAddresses.ts

@@ -6,9 +6,9 @@
  * The two are written however the deployment writes them — an origin, an
  * origin and a mount, with or without a trailing slash — and a page is named
  * from the site's own root, `/titration` and `titration` alike: every helper
- * joins the two with exactly one slash, so `https://www.cheminfo.org/surge`
- * and `https://www.cheminfo.org/surge/` both put `/generator` at
- * `https://www.cheminfo.org/surge/generator`.
+ * joins the two with exactly one slash, so `https://www.cheminfo.org/isomers`
+ * and `https://www.cheminfo.org/isomers/` both put `/generator` at
+ * `https://www.cheminfo.org/isomers/generator`.
  */
 
 import { trimTrailingSlash } from '../router/core/address.ts';

package/src/structure/core/index.ts

@@ -82,3 +82,11 @@ export type {
   StructureSourceInput,
 } from './structureSource.ts';
 export { structureSource } from './structureSource.ts';
+export type {
+  StructureTransfer,
+  StructureTransferSource,
+} from './structureTransfer.ts';
+export {
+  carriesStructure,
+  readStructureTransfer,
+} from './structureTransfer.ts';

package/src/structure/core/structureTransfer.ts

@@ -0,0 +1,37 @@
+/** What a paste or a drop carried that a structure can be read from. */
+export type StructureTransfer =
+  { kind: 'files'; files: File[] } | { kind: 'text'; text: string };
+
+/** The part of a `DataTransfer` a structure is read from. */
+export interface StructureTransferSource {
+  files: ArrayLike<File>;
+  getData: (format: string) => string;
+}
+
+/**
+ * What a paste or a drop holds: its files when it carries any, otherwise its
+ * text — a SMILES, an idCode, a molfile. A file copied in the file manager also
+ * carries its name as text, so the files win.
+ * @param transfer - The clipboard or drag data, `null` when the event has none.
+ * @returns The files or the trimmed text, or `null` when there is nothing.
+ */
+export function readStructureTransfer(
+  transfer: StructureTransferSource | null,
+): StructureTransfer | null {
+  if (transfer === null) return null;
+  if (transfer.files.length > 0) {
+    return { kind: 'files', files: Array.from(transfer.files) };
+  }
+  const text = transfer.getData('text').trim();
+  return text === '' ? null : { kind: 'text', text };
+}
+
+/**
+ * Whether a drag in progress may carry a structure. Until the drop only the
+ * types are readable, never the content, so a file or plain text is enough.
+ * @param types - `DataTransfer.types` of the drag.
+ * @returns Whether it is worth offering to take the drop.
+ */
+export function carriesStructure(types: readonly string[]): boolean {
+  return types.includes('Files') || types.includes('text/plain');
+}

package/src/structure/ui/EditorImportButton.tsx

@@ -0,0 +1,59 @@
+import { Button } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+import { useRef } from 'react';
+
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import { ActionTooltip } from '../../shared/ui/ActionTooltip.tsx';
+import type { StructureTransfer } from '../core/structureTransfer.ts';
+
+/** What {@link EditorImportButton} needs. */
+export interface EditorImportButtonProps {
+  /** Called with the files chosen. */
+  onImport: (transfer: StructureTransfer) => void;
+  /**
+   * The file types the picker offers, as an `accept` attribute.
+   * @default undefined
+   */
+  accept?: string;
+}
+
+/**
+ * The editor's open button, beside the export one, for a visitor who cannot
+ * drag a file onto the canvas — on a phone, or from a picker.
+ * @param props - See {@link EditorImportButtonProps}.
+ * @returns The button and its hidden file input.
+ */
+export function EditorImportButton(
+  props: EditorImportButtonProps,
+): ReactElement {
+  const { onImport, accept } = props;
+  const t = useChromeT();
+  const input = useRef<HTMLInputElement>(null);
+
+  return (
+    <>
+      <ActionTooltip content={t('structure.import.open')} placement="left">
+        <Button
+          variant="minimal"
+          size="small"
+          icon="import"
+          aria-label={t('structure.import.open')}
+          onClick={() => input.current?.click()}
+        />
+      </ActionTooltip>
+      <input
+        ref={input}
+        type="file"
+        accept={accept}
+        hidden
+        data-testid="structure-editor-file"
+        onChange={(event) => {
+          const files = Array.from(event.currentTarget.files ?? []);
+          // Cleared, so choosing the same file again is a change.
+          event.currentTarget.value = '';
+          if (files.length > 0) onImport({ kind: 'files', files });
+        }}
+      />
+    </>
+  );
+}

package/src/structure/ui/EditorImportProblem.tsx

@@ -0,0 +1,63 @@
+import { Button, Callout } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+
+import { useChromeT } from '../../i18n/ui/useT.ts';
+
+import type { StructureImportProblem } from './useStructureImport.ts';
+
+/** What {@link EditorImportProblem} needs. */
+export interface EditorImportProblemProps {
+  /** What went wrong. */
+  problem: StructureImportProblem;
+  /** Forget it. */
+  onDismiss: () => void;
+}
+
+/**
+ * The line along the bottom of the canvas that says a drop loaded nothing,
+ * and that the drawing is still there.
+ * @param props - See {@link EditorImportProblemProps}.
+ * @returns The line.
+ */
+export function EditorImportProblem(
+  props: EditorImportProblemProps,
+): ReactElement {
+  const { problem, onDismiss } = props;
+  const t = useChromeT();
+  return (
+    <div role="alert" style={PLACE}>
+      <Callout intent="danger" icon={null} compact style={LINE}>
+        <span style={TEXT}>
+          {problem.file === null
+            ? t('structure.import.unreadableText')
+            : t('structure.import.unreadableFile', { name: problem.file })}
+        </span>
+        <Button
+          variant="minimal"
+          size="small"
+          icon="cross"
+          aria-label={t('overlay.dismiss')}
+          onClick={onDismiss}
+        />
+      </Callout>
+    </div>
+  );
+}
+
+/** Clear of the tool palette, two 21px columns in a 2px border, at the left. */
+const PLACE: CSSProperties = {
+  position: 'absolute',
+  right: 4,
+  bottom: 4,
+  left: 52,
+  zIndex: 10,
+};
+
+const LINE: CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 6,
+  fontSize: 12,
+};
+
+const TEXT: CSSProperties = { flex: 1 };

package/src/structure/ui/StructureDrop.tsx

@@ -0,0 +1,66 @@
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import type { StructureTransfer } from '../core/structureTransfer.ts';
+
+import { StructureDropOverlay } from './StructureDropOverlay.tsx';
+import { useStructureDrop } from './useStructureDrop.ts';
+
+/** What {@link StructureDrop} needs. */
+export interface StructureDropProps {
+  /** Called with the files or the text dropped. */
+  onDrop: (transfer: StructureTransfer) => void;
+  /** What the drop lands on. */
+  children: ReactNode;
+  /**
+   * What the overlay says while something is dragged over.
+   * @default 'Drop to load the structure', in the page's language
+   */
+  label?: string;
+  /**
+   * Take no drop, while a load is already running for instance.
+   * @default false
+   */
+  disabled?: boolean;
+  /**
+   * Class of the wrapping element.
+   * @default undefined
+   */
+  className?: string;
+  /**
+   * Extra style for the wrapping element, which is positioned so the overlay
+   * covers it.
+   * @default undefined
+   */
+  style?: CSSProperties;
+}
+
+/**
+ * Make an area take a structure file, or structure text dragged from another
+ * page, with the same veil the structure editor raises over its canvas. What
+ * was dropped is handed over unread: the page knows which formats it takes.
+ * @param props - See {@link StructureDropProps}.
+ * @returns The area.
+ */
+export function StructureDrop(props: StructureDropProps): ReactElement {
+  const { onDrop, children, label, disabled = false } = props;
+  const { className, style } = props;
+  const t = useChromeT();
+  const drop = useStructureDrop(disabled ? undefined : onDrop);
+
+  return (
+    <div
+      className={className}
+      style={{ position: 'relative', ...style }}
+      {...drop.targetProps}
+    >
+      {children}
+      {drop.over ? (
+        <StructureDropOverlay
+          label={label ?? t('structure.import.drop')}
+          handlers={drop.overlayProps}
+        />
+      ) : null}
+    </div>
+  );
+}

package/src/structure/ui/StructureDropOverlay.tsx

@@ -0,0 +1,50 @@
+import { Icon } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+
+import type { DropHandlers } from './useStructureDrop.ts';
+
+/** What {@link StructureDropOverlay} needs. */
+export interface StructureDropOverlayProps {
+  /** What the overlay says. */
+  label: string;
+  /** The overlay handlers of `useStructureDrop`. */
+  handlers: DropHandlers;
+}
+
+/**
+ * The veil a drop target raises while a file or text is dragged over it.
+ * @param props - See {@link StructureDropOverlayProps}.
+ * @returns The overlay.
+ */
+export function StructureDropOverlay(
+  props: StructureDropOverlayProps,
+): ReactElement {
+  const { label, handlers } = props;
+  return (
+    <div data-testid="structure-drop-overlay" style={OVERLAY} {...handlers}>
+      {/* Nothing inside takes the pointer, so leaving the overlay is the only
+          dragleave it hears. */}
+      <Icon icon="import" size={28} style={PASSIVE} />
+      <span style={PASSIVE}>{label}</span>
+    </div>
+  );
+}
+
+const OVERLAY: CSSProperties = {
+  position: 'absolute',
+  inset: 0,
+  zIndex: 20,
+  display: 'flex',
+  flexDirection: 'column',
+  alignItems: 'center',
+  justifyContent: 'center',
+  gap: 8,
+  border: '2px dashed var(--accent)',
+  borderRadius: 'inherit',
+  background: 'color-mix(in oklab, var(--accent) 10%, rgb(255 255 255 / 88%))',
+  color: 'var(--accent)',
+  fontSize: 14,
+  fontWeight: 600,
+};
+
+const PASSIVE: CSSProperties = { pointerEvents: 'none' };

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';