react-cheminfo 0.38.0 → 0.39.1

package/src/shared/ui/useActionTooltip.ts

@@ -0,0 +1,103 @@
+/**
+ * When a tooltip on a control that is pressed should be on screen.
+ *
+ * Such a control is where a hover tooltip goes wrong, in two ways that look
+ * like one. What it opens lands over the control, so the `mouseleave` that
+ * would close the card is never delivered and the card is left on screen, over
+ * the thing it was explaining. And the open is *scheduled*: a press within the
+ * hover delay cancels nothing, so the card appears after the press, outlives
+ * what was opened, and comes back when it is closed — with the pointer long
+ * gone.
+ *
+ * Blueprint's own hover handling cannot be told either of those, so the state
+ * is held here and Blueprint is told only when to draw.
+ *
+ * The card is a pointer affordance only, and deliberately does not open on
+ * focus: what a control opens hands the focus back as it closes, which would
+ * put the card on screen with the pointer long gone. Nothing is lost by it —
+ * the control carries the same words as its accessible name, which is what a
+ * screen reader reads.
+ */
+
+import { useEffect, useRef, useState } from 'react';
+
+/** The handlers the target carries, which decide when the card is drawn. */
+export interface ActionTooltipTarget {
+  onPointerEnter: () => void;
+  onPointerLeave: () => void;
+  onPointerDownCapture: () => void;
+  onClickCapture: () => void;
+  onBlurCapture: () => void;
+}
+
+/** Whether the card is drawn, and what decides it. */
+export interface ActionTooltipState {
+  /** What to give the tooltip as `isOpen`. */
+  isOpen: boolean;
+  /** What to give the target, or the element wrapping it. */
+  target: ActionTooltipTarget;
+}
+
+/** Long enough that sweeping the pointer across a row of controls opens none. */
+export const ACTION_TOOLTIP_DELAY = 250;
+
+/**
+ * Hold a tooltip's hover, so a press closes it and nothing reopens it until
+ * the pointer leaves the control and comes back.
+ * @param opened - Whether what the control opens is on screen; while it is,
+ * the card stays shut.
+ * @param delay - How long the pointer rests before the card is drawn, in
+ * milliseconds. A card heavier than a line of text asks for longer.
+ * @returns Whether to draw the card, and the handlers that decide it.
+ */
+export function useActionTooltip(
+  opened = false,
+  delay = ACTION_TOOLTIP_DELAY,
+): ActionTooltipState {
+  const [shown, setShown] = useState(false);
+  const waiting = useRef<ReturnType<typeof setTimeout> | null>(null);
+  // Set by the press, and cleared only by the pointer actually leaving. It is
+  // what the pointer never leaving looks like: the dialog lands over the
+  // control, and removing it again makes the browser hand the control a fresh
+  // `pointerenter` — with the pointer never having moved. Clearing the latch
+  // there, or on the focus the dialog gives back as it closes, is what made
+  // the card reappear the moment the dialog was dismissed.
+  const pressed = useRef(false);
+
+  function cancel(): void {
+    if (waiting.current !== null) clearTimeout(waiting.current);
+    waiting.current = null;
+  }
+
+  function hide(): void {
+    cancel();
+    setShown(false);
+  }
+
+  function press(): void {
+    pressed.current = true;
+    hide();
+  }
+
+  useEffect(() => cancel, []);
+
+  return {
+    isOpen: shown && !opened,
+    target: {
+      onPointerEnter: () => {
+        if (pressed.current) return;
+        cancel();
+        waiting.current = setTimeout(() => setShown(true), delay);
+      },
+      onPointerLeave: () => {
+        pressed.current = false;
+        hide();
+      },
+      onPointerDownCapture: press,
+      // Enter and Space fire no pointer event, so a control worked from the
+      // keyboard is let go of here instead.
+      onClickCapture: press,
+      onBlurCapture: hide,
+    },
+  };
+}

package/src/structure/core/index.ts

@@ -72,6 +72,11 @@ export type { ReadStructureResult, StructureKind } from './readStructure.ts';
 export { looksLikeSmarts, readStructure } from './readStructure.ts';
 export type { StructureError } from './structureError.ts';
 export { structureError } from './structureError.ts';
+export type {
+  StructurePicture,
+  StructurePictureOptions,
+} from './structurePicture.ts';
+export { STRUCTURE_BOND_LENGTH, structurePicture } from './structurePicture.ts';
 export type {
   StructureSource,
   StructureSourceInput,

package/src/structure/core/sourceMolecule.ts

@@ -0,0 +1,26 @@
+/**
+ * Read the notation a depiction was handed into the molecule it draws.
+ *
+ * **Not exported from `core/index.ts`**: it value-imports `openchemlib`, so a
+ * barrel carrying it would pull the whole library into every site that imports
+ * `react-cheminfo/core`. The depiction and the export dialog both load it
+ * lazily, which is where openchemlib already is.
+ */
+
+import { Molecule } from 'openchemlib';
+
+import type { StructureSource } from './structureSource.ts';
+
+/**
+ * Parse one picked notation.
+ * @param source - The notation, as `structureSource` picked it.
+ * @returns The molecule, which holds no atom for an empty source.
+ * @throws {Error} Whatever OpenChemLib throws on a notation it cannot read.
+ */
+export function sourceMolecule(source: StructureSource): Molecule {
+  const { kind, value, coordinates } = source;
+  if (kind === 'idcode') return Molecule.fromIDCode(value, coordinates);
+  if (kind === 'molfile') return Molecule.fromMolfile(value);
+  if (kind === 'smiles') return Molecule.fromSmiles(value);
+  return new Molecule(0, 0);
+}

package/src/structure/core/structureNotations.ts

@@ -0,0 +1,125 @@
+/**
+ * Every way this package writes a drawn structure out.
+ *
+ * **Not exported from `core/index.ts`, and it must not be.** It is the one
+ * structure module that value-imports `openchemlib`, because the canonical
+ * forms below are `CanonizerUtil`'s and nothing on `Molecule` reaches them, so
+ * a barrel carrying it would pull openchemlib into every site that imports
+ * `react-cheminfo/core` for a formatter. The export dialog loads it lazily
+ * instead, next to the editor that already has openchemlib.
+ */
+
+import type { Molecule } from 'openchemlib';
+import { CanonizerUtil } from 'openchemlib';
+
+/** The notations offered, in the order they are offered in. */
+export type StructureNotationKind =
+  | 'smiles'
+  | 'molfileV3000'
+  | 'molfileV2000'
+  | 'idCode'
+  | 'noStereoIdCode'
+  | 'noStereoTautomerIdCode';
+
+/** How a notation leaves the page as a file. */
+export interface StructureNotationFile {
+  /** Added to the structure's own name, so two molfiles do not collide. */
+  suffix: string;
+  /** The extension, without its dot. */
+  extension: string;
+  /** What the file holds, so the system opens it with the right application. */
+  mimeType: string;
+}
+
+/** One way of writing a structure. */
+export interface StructureNotation {
+  /** Which notation it is. */
+  kind: StructureNotationKind;
+  /** The notation itself, empty when OpenChemLib would not write it. */
+  value: string;
+  /**
+   * Whether it is one of the canonical identifiers — a string that names the
+   * molecule rather than describes the drawing, and that a record is looked up
+   * by. They answer a database question rather than a drawing one, so they are
+   * shown apart from the rest.
+   */
+  canonical: boolean;
+  /**
+   * The file it is saved as. Absent for a notation that is only ever copied.
+   * @default undefined
+   */
+  file?: StructureNotationFile;
+  /**
+   * Whether it runs over several lines, so it is shown as a block rather than
+   * on the label's own line.
+   */
+  block: boolean;
+}
+
+/** What a molfile is, for the application that opens one. */
+const MOLFILE_TYPE = 'chemical/x-mdl-molfile';
+
+/**
+ * Write a structure every way the export dialog offers.
+ *
+ * A notation OpenChemLib refuses — a query fragment has no SMILES, a generic
+ * tautomer cannot always be canonized — comes back empty rather than taking
+ * the rest of the list down with it.
+ * @param molecule - The structure, as the editor handed it over. Not modified.
+ * @returns One entry per notation, in the order they are shown.
+ */
+export function structureNotations(molecule: Molecule): StructureNotation[] {
+  const idCode = written(() => molecule.getIDCode());
+  return [
+    {
+      kind: 'smiles',
+      value: written(() => molecule.toIsomericSmiles()),
+      canonical: false,
+      block: false,
+    },
+    {
+      kind: 'molfileV3000',
+      value: written(() => molecule.toMolfileV3()),
+      canonical: false,
+      file: { suffix: '-v3000', extension: 'mol', mimeType: MOLFILE_TYPE },
+      block: true,
+    },
+    {
+      kind: 'molfileV2000',
+      value: written(() => molecule.toMolfile()),
+      canonical: false,
+      file: { suffix: '-v2000', extension: 'mol', mimeType: MOLFILE_TYPE },
+      block: true,
+    },
+    { kind: 'idCode', value: idCode, canonical: true, block: false },
+    {
+      kind: 'noStereoIdCode',
+      value: written(() =>
+        CanonizerUtil.getIDCode(molecule, CanonizerUtil.NOSTEREO),
+      ),
+      canonical: true,
+      block: false,
+    },
+    {
+      kind: 'noStereoTautomerIdCode',
+      value: written(() =>
+        CanonizerUtil.getIDCode(molecule, CanonizerUtil.NOSTEREO_TAUTOMER),
+      ),
+      canonical: true,
+      block: false,
+    },
+  ];
+}
+
+/**
+ * One notation, or nothing when OpenChemLib will not write it.
+ * @param write - What writes it.
+ * @returns The notation, empty on a refusal.
+ */
+function written(write: () => string): string {
+  try {
+    return write();
+  } catch {
+    return '';
+  }
+}

package/src/structure/core/structurePicture.ts

@@ -0,0 +1,119 @@
+/**
+ * A structure as a picture, drawn at the size it is saved at.
+ *
+ * The resolution is a bond length rather than a canvas: OpenChemLib caps the
+ * bond it draws at 24 pixels whatever box it is given, so asking for a canvas
+ * four times larger produces the same small drawing with more white around it
+ * — a resolution control that changes the file and not the picture. Lifting
+ * the cap and cropping to the structure is what makes `4×` genuinely four
+ * times the drawing.
+ */
+
+import type { Molecule } from 'openchemlib';
+
+import type { FigurePixels } from '../../download/core/figureScale.ts';
+
+/** How the picture is drawn. */
+export interface StructurePictureOptions {
+  /**
+   * The longest bond drawn, in pixels, which is what sets the size of
+   * everything else — the picture is cropped to the structure afterwards.
+   * @default 60
+   */
+  bondLength?: number;
+  /**
+   * What is painted behind the structure. An SVG left unpainted opens
+   * transparent, and a structure is drawn in black, so it disappears in
+   * anything with a dark background — a slide, a reader in dark mode.
+   * @default '#ffffff'
+   */
+  background?: string;
+}
+
+/** A structure drawn, and how big it came out. */
+export interface StructurePicture extends FigurePixels {
+  /** The SVG document, ready to be saved or rasterized. */
+  markup: string;
+}
+
+/**
+ * The bond length a picture is drawn at before the resolution multiplies it.
+ *
+ * Chosen so a drug-sized molecule comes out around 300 pixels wide, which is
+ * what a note or a chat window wants; two or three times that is a slide, and
+ * four is print.
+ */
+export const STRUCTURE_BOND_LENGTH = 60;
+
+/**
+ * The canvas the structure is laid out in before it is cropped out of it.
+ *
+ * Only a ceiling: past it the box, rather than the bond length, would decide
+ * the size, and it is far beyond what a browser will paint anyway.
+ */
+const CANVAS = 20_000;
+
+/** Where the opening `<svg …>` tag ends, so the background goes after it. */
+const OPEN_TAG = /<svg\b[^>]*>/u;
+
+/** The size OpenChemLib wrote on the document it produced. */
+const SIDE = /\b(?<side>width|height)="(?<pixels>\d+)px"/gu;
+
+/**
+ * Draw a structure as a standalone SVG document, cropped to the structure.
+ * @param molecule - The structure. Not modified.
+ * @param options - How large to draw it, and what to paint behind it.
+ * @returns The document and the size it came out at.
+ */
+export function structurePicture(
+  molecule: Molecule,
+  options: StructurePictureOptions = {},
+): StructurePicture {
+  const { bondLength = STRUCTURE_BOND_LENGTH, background = '#ffffff' } =
+    options;
+  const markup = molecule.toSVG(CANVAS, CANVAS, undefined, {
+    autoCrop: true,
+    autoCropMargin: Math.max(2, Math.round(bondLength / 6)),
+    maxAVBL: Math.max(1, Math.round(bondLength)),
+  });
+
+  return { markup: painted(markup, background), ...sizeOf(markup) };
+}
+
+/**
+ * Paint a background into the document, so the file does not open
+ * transparent.
+ * @param markup - The document as OpenChemLib wrote it.
+ * @param background - What to paint, or `transparent` to paint nothing.
+ * @returns The document.
+ */
+function painted(markup: string, background: string): string {
+  if (background === 'transparent') return markup;
+  const open = OPEN_TAG.exec(markup);
+  // A document whose opening tag cannot be found is handed back unpainted
+  // rather than corrupted by an insertion at a guessed offset.
+  if (open === null) return markup;
+  const end = open.index + open[0].length;
+  return `${markup.slice(0, end)}<rect width="100%" height="100%" fill="${background}" />${markup.slice(end)}`;
+}
+
+/**
+ * How big the cropped document came out.
+ *
+ * Read off the document rather than computed, because the crop is the
+ * structure's own shape: two molecules asked for at the same bond length come
+ * out at different sizes, and the size is what the reader is shown.
+ * @param markup - The document as OpenChemLib wrote it.
+ * @returns Its size in pixels.
+ */
+function sizeOf(markup: string): FigurePixels {
+  const sides: Record<string, number> = {};
+  SIDE.lastIndex = 0;
+  for (const match of markup.matchAll(SIDE)) {
+    const { side, pixels } = match.groups ?? {};
+    if (side !== undefined && pixels !== undefined && !(side in sides)) {
+      sides[side] = Number(pixels);
+    }
+  }
+  return { width: sides.width ?? CANVAS, height: sides.height ?? CANVAS };
+}

package/src/structure/ui/EditorExportButton.tsx

@@ -0,0 +1,62 @@
+import { Button } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+import { useState } from 'react';
+
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import { ActionTooltip } from '../../shared/ui/ActionTooltip.tsx';
+import type { StructureSourceInput } from '../core/structureSource.ts';
+
+import { StructureExportDialog } from './StructureExportDialog.tsx';
+
+/** What {@link EditorExportButton} needs. */
+export interface EditorExportButtonProps {
+  /** Reads what is drawn, called the moment the dialog is opened. */
+  source: () => StructureSourceInput;
+  /** Whether the editor draws a query fragment. */
+  fragment: boolean;
+  /** Whether the canvas holds nothing to export. */
+  empty: boolean;
+}
+
+/**
+ * The editor's export button, beside the help one, opening every notation of
+ * the drawing and the picture of it.
+ *
+ * The structure is read when the button is pressed rather than kept beside the
+ * canvas, so the dialog opens on what is drawn now and the editor is not
+ * re-rendered on every stroke to keep a copy in step.
+ * @param props - See {@link EditorExportButtonProps}.
+ * @returns The button and its dialog.
+ */
+export function EditorExportButton(
+  props: EditorExportButtonProps,
+): ReactElement {
+  const { source, fragment, empty } = props;
+  const t = useChromeT();
+  const [opened, setOpened] = useState<StructureSourceInput | null>(null);
+
+  return (
+    <>
+      <ActionTooltip
+        content={t('structure.export.open')}
+        placement="left"
+        opened={opened !== null}
+      >
+        <Button
+          variant="minimal"
+          size="small"
+          icon="export"
+          disabled={empty}
+          aria-label={t('structure.export.open')}
+          onClick={() => setOpened(source())}
+        />
+      </ActionTooltip>
+      <StructureExportDialog
+        {...opened}
+        isOpen={opened !== null}
+        fragment={fragment}
+        onClose={() => setOpened(null)}
+      />
+    </>
+  );
+}

package/src/structure/ui/EditorHelpButton.tsx

@@ -1,8 +1,9 @@
-import { Button, PopoverNext, Tooltip } from '@blueprintjs/core';
-import type { CSSProperties, ReactElement, RefObject } from 'react';
+import { Button, PopoverNext } from '@blueprintjs/core';
+import type { ReactElement, RefObject } from 'react';
 import { useEffect, useState } from 'react';
 
 import { useChromeT } from '../../i18n/ui/useT.ts';
+import { ActionTooltip } from '../../shared/ui/ActionTooltip.tsx';
 
 import { StructureEditorHelp } from './StructureEditorHelp.tsx';
 import type { StructureEditorMode } from './editorChange.ts';
@@ -18,8 +19,11 @@ export interface EditorHelpButtonProps {
 }
 
 /**
- * The editor's help button, in the corner of the drawing, opening the guide to
- * the mouse and the keyboard.
+ * The editor's help button, opening the guide to the mouse and the keyboard.
+ *
+ * It is placed by whoever renders it — the editor puts it in the corner of the
+ * drawing, next to the export button — so the two read as one group rather
+ * than as two controls that happen to overlap.
  *
  * F1 opens it too: openchemlib binds that key to a help dialog it does not
  * implement on the web.
@@ -44,32 +48,24 @@ export function EditorHelpButton(props: EditorHelpButtonProps): ReactElement {
   }, [containerRef]);
 
   return (
-    <div style={CORNER_STYLE}>
-      <PopoverNext
-        isOpen={isOpen}
-        onInteraction={setIsOpen}
-        placement="left-start"
-        content={<StructureEditorHelp mode={mode} fragment={fragment} />}
+    <PopoverNext
+      isOpen={isOpen}
+      onInteraction={setIsOpen}
+      placement="left-start"
+      content={<StructureEditorHelp mode={mode} fragment={fragment} />}
+    >
+      <ActionTooltip
+        content={t('structure.mouseAndKeyboard')}
+        placement="left"
+        opened={isOpen}
       >
-        <Tooltip
-          content={t('structure.mouseAndKeyboard')}
-          placement="left"
-          disabled={isOpen}
-        >
-          <Button
-            variant="minimal"
-            size="small"
-            icon="help"
-            aria-label={t('structure.mouseAndKeyboard')}
-          />
-        </Tooltip>
-      </PopoverNext>
-    </div>
+        <Button
+          variant="minimal"
+          size="small"
+          icon="help"
+          aria-label={t('structure.mouseAndKeyboard')}
+        />
+      </ActionTooltip>
+    </PopoverNext>
   );
 }
-
-const CORNER_STYLE: CSSProperties = {
-  position: 'absolute',
-  top: 4,
-  right: 4,
-};

package/src/structure/ui/StructureEditor.tsx

@@ -28,8 +28,14 @@ import type {
   StructureEditorChange,
   StructureEditorMode,
 } from './editorChange.ts';
+import { useEditorStructure } from './useEditorStructure.ts';
 import { useToolbarFloor } from './useToolbarFloor.ts';
 
+const EditorExportButton = lazy(async () => {
+  const module = await import('./EditorExportButton.tsx');
+  return { default: module.EditorExportButton };
+});
+
 const EditorCanvas = lazy(async () => {
   const module = await import('./EditorCanvas.tsx');
   return { default: module.EditorCanvas };
@@ -93,6 +99,14 @@ export interface StructureEditorProps {
    * @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
@@ -123,6 +137,7 @@ export function StructureEditor(props: StructureEditorProps): ReactElement {
     minHeight = 320,
     mode = 'molecule',
     help = true,
+    exportable = true,
     className,
     style,
   } = props;
@@ -130,6 +145,16 @@ export function StructureEditor(props: StructureEditorProps): ReactElement {
   const t = useChromeT();
   const containerRef = useToolbarFloor({ minHeight, revision });
   const handleChange = useDebounced(onChange, debounce, revision);
+  const drawing = useEditorStructure({ value, inputFormat, revision });
+  const handleEdit = useCallback(
+    (change: StructureEditorChange) => {
+      // Tapped undebounced, so a button beside the canvas reads the structure
+      // as it stands rather than as it stood before the last burst.
+      drawing.track(change);
+      handleChange(change);
+    },
+    [drawing, handleChange],
+  );
 
   return (
     <div
@@ -144,22 +169,31 @@ export function StructureEditor(props: StructureEditorProps): ReactElement {
       >
         <EditorCanvas
           key={revision}
-          onChange={handleChange}
+          onChange={handleEdit}
           fragment={fragment}
           inputFormat={inputFormat}
           value={value}
           mode={mode}
         />
         {help ? (
-          <>
-            <ToolbarTooltip containerRef={containerRef} mode={mode} />
+          <ToolbarTooltip containerRef={containerRef} mode={mode} />
+        ) : null}
+        <div style={CORNER_STYLE}>
+          {exportable && mode === 'molecule' ? (
+            <EditorExportButton
+              source={drawing.source}
+              fragment={fragment}
+              empty={drawing.empty}
+            />
+          ) : null}
+          {help ? (
             <EditorHelpButton
               containerRef={containerRef}
               mode={mode}
               fragment={fragment}
             />
-          </>
-        ) : null}
+          ) : null}
+        </div>
       </Suspense>
     </div>
   );
@@ -217,6 +251,18 @@ const ROOT_STYLE: CSSProperties = {
   background: '#fff',
 };
 
+/**
+ * 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.
+ */
+const CORNER_STYLE: CSSProperties = {
+  position: 'absolute',
+  top: 4,
+  right: 4,
+  display: 'flex',
+  gap: 2,
+};
+
 /** The box the canvas will fill, so its arrival moves nothing. */
 const LOADING_STYLE: CSSProperties = {
   position: 'absolute',