react-cheminfo 0.50.0 → 0.52.0

package/src/download/ui/FigureDownloadPanel.tsx

@@ -5,6 +5,7 @@ import { OverlayAction } from '../../overlay/ui/OverlayAction.tsx';
 import { OverlayPanel } from '../../overlay/ui/OverlayPanel.tsx';
 import type { OverlayOption } from '../../overlay/ui/OverlayRow.tsx';
 import { OverlaySegmented } from '../../overlay/ui/OverlaySegmented.tsx';
+import type { FigureNotice } from '../core/copyFigure.ts';
 import type { FigureFormat } from '../core/downloadFigure.ts';
 import { figureLayoutSize } from '../core/figureLayout.ts';
 import type { FigurePixels } from '../core/figureScale.ts';
@@ -18,7 +19,6 @@ import {
 import type { FigureSizing } from './FigureSizeRows.tsx';
 import { FigureSizeRows } from './FigureSizeRows.tsx';
 import { hintOf } from './figureDownloadHint.ts';
-import type { FigureNotice } from './useFigureActions.ts';
 
 /** What {@link FigureDownloadPanel} is drawn from. */
 export interface FigureDownloadPanelProps {
@@ -51,9 +51,8 @@ export interface FigureDownloadPanelProps {
   /**
    * Called when they press copy, which puts a PNG at the resolution picked on
    * the clipboard.
-   * @default undefined — no copy is offered
    */
-  onCopy?: () => void;
+  onCopy: () => void;
   /**
    * Whether the SVG holds a rendered picture rather than vector drawings, as
    * for a WebGL scene: its resolution is then the pixels of that picture, it
@@ -122,14 +121,12 @@ export function FigureDownloadPanel(
             disabled={saving || size === null}
             onClick={onSave}
           />
-          {onCopy === undefined ? null : (
-            <OverlayAction
-              text={t('clipboard.copy')}
-              icon="clipboard"
-              disabled={saving || size === null}
-              onClick={onCopy}
-            />
-          )}
+          <OverlayAction
+            text={t('clipboard.copy')}
+            icon="clipboard"
+            disabled={saving || size === null}
+            onClick={onCopy}
+          />
         </>
       }
     >

package/src/download/ui/figureDownloadHint.ts

@@ -1,11 +1,10 @@
 import type { ChromeKey } from '../../i18n/core/chromeCatalog.ts';
 import type { Translate } from '../../i18n/ui/useT.ts';
+import type { FigureNotice } from '../core/copyFigure.ts';
 import type { FigureFormat } from '../core/downloadFigure.ts';
 import type { FigurePixels } from '../core/figureScale.ts';
 import { figurePixels, formatFigurePixels } from '../core/figureScale.ts';
 
-import type { FigureNotice } from './useFigureActions.ts';
-
 /** What the line at the foot of the panel is written from. */
 export interface HintState {
   /** Which file the reader is about to write. */

package/src/download/ui/index.ts

@@ -19,4 +19,3 @@ export type {
   FigureDownloadState,
 } from './useFigureDownload.tsx';
 export { useFigureDownload } from './useFigureDownload.tsx';
-export type { FigureNotice } from './useFigureActions.ts';

package/src/download/ui/useFigureActions.ts

@@ -1,6 +1,4 @@
-import { useCallback, useState } from 'react';
-
-import { writeImageToClipboard } from '../../clipboard/core/copyPng.ts';
+import { copyFigure } from '../core/copyFigure.ts';
 import type { FigureFormat } from '../core/downloadFigure.ts';
 import { downloadFigure } from '../core/downloadFigure.ts';
 import { figurePng } from '../core/figurePng.ts';
@@ -8,9 +6,8 @@ import type { FigurePixels } from '../core/figureScale.ts';
 import { figureSvg } from '../core/figureSvg.ts';
 
 import type { FigureRedraw } from './useFigureRedraw.tsx';
-
-/** What the last copy came to, when it is worth a line of its own. */
-export type FigureNotice = 'copied' | 'copyUnsupported';
+import type { FigureTask } from './useFigureTask.ts';
+import { useFigureTask } from './useFigureTask.ts';
 
 /** What {@link useFigureActions} works from. */
 export interface FigureActionsOptions {
@@ -34,19 +31,11 @@ export interface FigureActionsOptions {
 }
 
 /** What {@link useFigureActions} hands back. */
-export interface FigureActions {
+export interface FigureActions extends Omit<FigureTask, 'run'> {
   /** Write the figure to a file, in the format picked. */
   save: () => void;
   /** Put the figure on the clipboard, as a PNG at the resolution picked. */
   copy: () => void;
-  /** Whether a file or a copy is being written right now. */
-  busy: boolean;
-  /** What went wrong the last time, if anything. */
-  failure: string | null;
-  /** What the last copy came to, if it is still what the panel describes. */
-  notice: FigureNotice | null;
-  /** Forget the last outcome, once the choices it answered have changed. */
-  clear: () => void;
 }
 
 /**
@@ -60,9 +49,7 @@ export interface FigureActions {
 export function useFigureActions(options: FigureActionsOptions): FigureActions {
   const { targetId, format, scale, fileName, background } = options;
   const { redrawAt, redraw } = options;
-  const [busy, setBusy] = useState(false);
-  const [failure, setFailure] = useState<string | null>(null);
-  const [notice, setNotice] = useState<FigureNotice | null>(null);
+  const { run, busy, failure, notice, clear } = useFigureTask();
 
   function withFigure(write: (box: string | Element) => Promise<void>) {
     return redrawAt === null
@@ -70,17 +57,6 @@ export function useFigureActions(options: FigureActionsOptions): FigureActions {
       : redraw(targetId, redrawAt, write);
   }
 
-  function run(task: Promise<FigureNotice | null>): void {
-    setBusy(true);
-    setFailure(null);
-    setNotice(null);
-    void task
-      .then(setNotice, (error: unknown) => {
-        setFailure(error instanceof Error ? error.message : String(error));
-      })
-      .finally(() => setBusy(false));
-  }
-
   function save(): void {
     const options = { format, scale, fileName, background };
     run(withFigure((box) => downloadFigure(box, options)).then(() => null));
@@ -94,20 +70,8 @@ export function useFigureActions(options: FigureActionsOptions): FigureActions {
         resolve(await figurePng(figureSvg(box, { background }), scale));
       }).catch(reject);
     });
-    // A browser whose clipboard takes text only never reads the picture, so
-    // its failure would otherwise go unhandled.
-    png.catch(() => undefined);
-    run(
-      writeImageToClipboard(png).then((copied) =>
-        copied ? 'copied' : 'copyUnsupported',
-      ),
-    );
+    run(copyFigure(png));
   }
 
-  const clear = useCallback(() => {
-    setFailure(null);
-    setNotice(null);
-  }, []);
-
   return { save, copy, busy, failure, notice, clear };
 }

package/src/download/ui/useFigureTask.ts

@@ -0,0 +1,46 @@
+import { useCallback, useState } from 'react';
+
+import type { FigureNotice } from '../core/copyFigure.ts';
+
+/** What {@link useFigureTask} hands back. */
+export interface FigureTask {
+  /** Run a save or a copy, keeping what it came to. */
+  run: (task: Promise<FigureNotice | null>) => void;
+  /** Whether a file or a copy is being written right now. */
+  busy: boolean;
+  /** What went wrong the last time, if anything. */
+  failure: string | null;
+  /** What the last copy came to, if it is still what the panel describes. */
+  notice: FigureNotice | null;
+  /** Forget the last outcome, once the choices it answered have changed. */
+  clear: () => void;
+}
+
+/**
+ * The state behind the figure panel's save and copy buttons, whatever the
+ * figure is drawn with: whether one is running, and what the last one came to.
+ * @returns See {@link FigureTask}.
+ */
+export function useFigureTask(): FigureTask {
+  const [busy, setBusy] = useState(false);
+  const [failure, setFailure] = useState<string | null>(null);
+  const [notice, setNotice] = useState<FigureNotice | null>(null);
+
+  const run = useCallback((task: Promise<FigureNotice | null>) => {
+    setBusy(true);
+    setFailure(null);
+    setNotice(null);
+    void task
+      .then(setNotice, (error: unknown) => {
+        setFailure(error instanceof Error ? error.message : String(error));
+      })
+      .finally(() => setBusy(false));
+  }, []);
+
+  const clear = useCallback(() => {
+    setFailure(null);
+    setNotice(null);
+  }, []);
+
+  return { run, busy, failure, notice, clear };
+}

package/src/host/core/connectHost.ts

@@ -0,0 +1,240 @@
+/**
+ * A tool's side of the host protocol: introduce itself to the page that
+ * frames it, take the private port that page answers with, and serve what
+ * arrives through it.
+ *
+ * Free of React and of the DOM — the window is handed in — so a test drives the
+ * whole exchange with a fake host and a real `MessageChannel`.
+ */
+
+import type { CheckedValue, KnownKind } from './kinds.ts';
+import { checkValue, isKnownKind, kindAccepts } from './kinds.ts';
+import type {
+  GetRequest,
+  HelloMessage,
+  HostError,
+  HostItem,
+  LoadRequest,
+  ResultMessage,
+  ToolInput,
+  ToolInterface,
+  UsedItem,
+} from './protocol.ts';
+import {
+  HELLO_TYPE,
+  PROTOCOL_VERSION,
+  isConnect,
+  parseRequest,
+} from './protocol.ts';
+
+/** The item an input took, and its value as the input's kind reads it. */
+export interface LoadedInput {
+  key: string;
+  item: HostItem;
+  checked: CheckedValue;
+}
+
+/** What a window `message` event carries, as far as the protocol reads it. */
+export interface HostMessageEvent {
+  data: unknown;
+  source: unknown;
+  ports: readonly MessagePort[];
+}
+
+/** Where the connection runs, and what it serves. */
+export interface HostConnectionOptions {
+  /** The page to introduce the tool to: the parent frame, or the opener. */
+  host: { postMessage: (message: unknown, targetOrigin: string) => void };
+  /** Subscribe to this window's messages; the returned function unsubscribes. */
+  listen: (listener: (event: HostMessageEvent) => void) => () => void;
+  /** What the tool takes and gives, as `hello` announces it. */
+  tool: ToolInterface;
+  /** The tool's origin, as `hello` states it. */
+  origin: string;
+  /** The build that is running, as the About states it, or `null`. */
+  build: unknown;
+  /**
+   * Show the inputs of a new document. Throwing means they could not be read:
+   * the error's message goes back to the host, and the document is not marked
+   * as applied.
+   */
+  load: (inputs: readonly LoadedInput[]) => void;
+}
+
+/** What choosing the items of a request gave. */
+export type InputSelection =
+  { ok: true; inputs: LoadedInput[] } | { ok: false; error: HostError };
+
+/**
+ * Say `hello` to the host, and serve its requests once it connects.
+ *
+ * A `connect` is accepted only from the window `hello` went to, and a second
+ * one replaces the first — a host that reloads its own script connects again.
+ * A document is applied once: the same one again is answered as before and
+ * changes nothing, so a host re-sending it never overwrites the user's work.
+ * @param options - The window, the tool, and its load function.
+ * @returns The function that stops listening and closes the port.
+ */
+export function connectHost(options: HostConnectionOptions): () => void {
+  const { host, listen, tool, origin, build, load } = options;
+  let port: MessagePort | null = null;
+  let appliedDocument: string | null = null;
+  let appliedUsed: UsedItem[] = [];
+
+  function serve(data: unknown): void {
+    const request = parseRequest(data);
+    if (request === null) return;
+    const result =
+      request.type === 'load' ? applyLoad(request) : answerGet(request, tool);
+    port?.postMessage(result);
+  }
+
+  function applyLoad(request: LoadRequest): ResultMessage {
+    const { id, document, items } = request;
+    if (document === appliedDocument) {
+      return { type: 'result', id, ok: true, used: appliedUsed };
+    }
+    const selection = selectInputs(tool, items);
+    if (!selection.ok) {
+      return { type: 'result', id, ok: false, error: selection.error };
+    }
+    try {
+      load(selection.inputs);
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      return {
+        type: 'result',
+        id,
+        ok: false,
+        error: { code: 'unreadable', message },
+      };
+    }
+    appliedDocument = document;
+    appliedUsed = selection.inputs.map(({ key, item }) => ({
+      key,
+      kind: item.kind,
+    }));
+    return { type: 'result', id, ok: true, used: appliedUsed };
+  }
+
+  const stopListening = listen((event) => {
+    if (event.source !== host || !isConnect(event.data)) return;
+    const received = event.ports[0];
+    if (received === undefined) return;
+    port?.close();
+    port = received;
+    port.addEventListener('message', (message) => {
+      serve(message.data);
+    });
+    port.start();
+  });
+
+  const hello: HelloMessage = {
+    type: HELLO_TYPE,
+    version: PROTOCOL_VERSION,
+    tool: {
+      name: tool.name,
+      origin,
+      build,
+      inputs: tool.inputs,
+      outputs: tool.outputs,
+    },
+  };
+  // `hello` says nothing a stranger may not read, and the parent's origin is
+  // not knowable until it answers.
+  host.postMessage(hello, '*');
+
+  return () => {
+    stopListening();
+    port?.close();
+    port = null;
+  };
+}
+
+/**
+ * Give each input of the tool one item of a request.
+ *
+ * Each input tries its kinds in its own order of preference, and takes the
+ * first item that falls under one and passes that kind's schema: the tool
+ * knows which notation serves it best, whatever order the host listed them in.
+ * An item naming another input's `key` is left to that input.
+ * @param tool - What the tool takes.
+ * @param items - What the host sent.
+ * @returns One item per input, or why an input got none.
+ */
+export function selectInputs(
+  tool: ToolInterface,
+  items: readonly HostItem[],
+): InputSelection {
+  const inputs: LoadedInput[] = [];
+  for (const input of tool.inputs) {
+    const errors: string[] = [];
+    const loaded = selectInput(input, items, errors);
+    if (loaded !== null) {
+      inputs.push(loaded);
+      continue;
+    }
+    if (errors.length > 0) {
+      return {
+        ok: false,
+        error: {
+          code: 'invalid',
+          message: `No item for ${input.key} has the shape its kind requires, so ${tool.name} loaded nothing.`,
+          errors,
+        },
+      };
+    }
+    return {
+      ok: false,
+      error: {
+        code: 'no-input',
+        message: `No item is a ${KIND_LIST.format(input.kinds)}, so ${tool.name} loaded nothing.`,
+      },
+    };
+  }
+  return { ok: true, inputs };
+}
+
+function selectInput(
+  input: ToolInput,
+  items: readonly HostItem[],
+  errors: string[],
+): LoadedInput | null {
+  for (const accepted of input.kinds) {
+    if (!isKnownKind(accepted)) continue;
+    for (const item of items) {
+      if (item.key !== undefined && item.key !== input.key) continue;
+      if (!kindAccepts(accepted, item.kind)) continue;
+      const loaded = checkItem(input.key, accepted, item, errors);
+      if (loaded !== null) return loaded;
+    }
+  }
+  return null;
+}
+
+function checkItem(
+  key: string,
+  accepted: KnownKind,
+  item: HostItem,
+  errors: string[],
+): LoadedInput | null {
+  const outcome = checkValue(accepted, item.value);
+  if (outcome.valid) return { key, item, checked: outcome.checked };
+  for (const error of outcome.errors) errors.push(`${item.kind} ${error}`);
+  return null;
+}
+
+function answerGet(request: GetRequest, tool: ToolInterface): ResultMessage {
+  // Nothing goes back yet: no tool declares an output.
+  return {
+    type: 'result',
+    id: request.id,
+    ok: false,
+    error: {
+      code: 'no-output',
+      message: `${tool.name} has nothing to give back yet.`,
+    },
+  };
+}
+
+const KIND_LIST = new Intl.ListFormat('en', { type: 'disjunction' });

package/src/host/core/hostStructure.ts

@@ -0,0 +1,129 @@
+/**
+ * A structure a host handed over, read into the molecule a tool works on.
+ *
+ * Every tool of the family that takes a structure takes it the same way — in
+ * the three notations a notebook keeps, the one that says the most first — so
+ * the kinds, the parsing and the sentence a host reads when it fails are
+ * written once, here.
+ */
+
+import type { Molecule } from 'openchemlib';
+
+import { sourceMolecule } from '../../structure/core/sourceMolecule.ts';
+import { structureError } from '../../structure/core/structureError.ts';
+import type { StructureSource } from '../../structure/core/structureSource.ts';
+
+import type { LoadedInput } from './connectHost.ts';
+import type { CheckedValue } from './kinds.ts';
+
+/**
+ * The kinds a structure input accepts, in order of preference: a molfile
+ * carries the layout its author drew, an idcode the exact structure, a SMILES
+ * only the connectivity.
+ */
+export const STRUCTURE_KINDS = [
+  'chem.molfile',
+  'chem.ocl.id',
+  'chem.smiles',
+] as const;
+
+/** A checked value holding a structure. */
+export type StructureValue = Extract<
+  CheckedValue,
+  { kind: (typeof STRUCTURE_KINDS)[number] }
+>;
+
+/**
+ * The function a tool hands `useHostConnection` as `load` when its input is a
+ * structure.
+ *
+ * The structure is parsed before `show` is called, so one that cannot be read
+ * is answered `unreadable` with a sentence the host can show, and nothing on
+ * the tool's screen changes.
+ * @param show - Puts the molecule on screen, under the host's label for it.
+ * @param key - The input the structure arrives on.
+ * @returns The `load` function.
+ */
+export function hostStructureLoader(
+  show: (molecule: Molecule, label: string | undefined) => void,
+  key = 'structure',
+): (inputs: readonly LoadedInput[]) => void {
+  return (inputs) => {
+    for (const { key: inputKey, item, checked } of inputs) {
+      if (inputKey !== key || !isStructureValue(checked)) continue;
+      show(readHostMolecule(checked), item.label);
+    }
+  };
+}
+
+/**
+ * Read a structure a host sent.
+ *
+ * A molfile whose atoms all sit on one point — SciPeaks stores some that way —
+ * is laid out again, so a tool that draws it does not draw one dot.
+ * @param checked - The value, already checked against its kind.
+ * @returns A molecule with at least one atom.
+ * @throws {Error} When the notation does not parse or describes no atoms; the
+ * message is the sentence the host is answered with.
+ */
+export function readHostMolecule(checked: StructureValue): Molecule {
+  const notation = NOTATIONS[checked.kind];
+  let molecule: Molecule;
+  try {
+    molecule = sourceMolecule(hostStructureSource(checked));
+  } catch (error) {
+    const { message } = structureError(error);
+    throw new Error(
+      `The ${notation} could not be read, so nothing was loaded: ${message}`,
+      { cause: error },
+    );
+  }
+  if (molecule.getAllAtoms() === 0) {
+    throw new Error(
+      `The ${notation} describes no atoms, so nothing was loaded.`,
+    );
+  }
+  if (atomsCoincide(molecule)) molecule.inventCoordinates();
+  return molecule;
+}
+
+/**
+ * A structure a host sent, as the notation a depiction is drawn from.
+ * @param checked - The value, already checked against its kind.
+ * @returns The notation and its text; an idcode keeps its coordinates.
+ */
+export function hostStructureSource(checked: StructureValue): StructureSource {
+  if (checked.kind === 'chem.molfile') {
+    return { kind: 'molfile', value: checked.value.molfile };
+  }
+  if (checked.kind === 'chem.ocl.id') {
+    const { idCode, coordinates } = checked.value;
+    return coordinates === ''
+      ? { kind: 'idcode', value: idCode }
+      : { kind: 'idcode', value: idCode, coordinates };
+  }
+  return { kind: 'smiles', value: checked.value.smiles.trim() };
+}
+
+const NOTATIONS: Record<StructureValue['kind'], string> = {
+  'chem.molfile': 'molfile',
+  'chem.ocl.id': 'idcode',
+  'chem.smiles': 'SMILES',
+};
+
+function atomsCoincide(molecule: Molecule): boolean {
+  const atoms = molecule.getAllAtoms();
+  if (atoms < 2) return false;
+  const x = molecule.getAtomX(0);
+  const y = molecule.getAtomY(0);
+  for (let atom = 1; atom < atoms; atom++) {
+    if (molecule.getAtomX(atom) !== x || molecule.getAtomY(atom) !== y) {
+      return false;
+    }
+  }
+  return true;
+}
+
+function isStructureValue(checked: CheckedValue): checked is StructureValue {
+  return Object.hasOwn(NOTATIONS, checked.kind);
+}

package/src/host/core/index.ts

@@ -0,0 +1,46 @@
+export type {
+  HostConnectionOptions,
+  HostMessageEvent,
+  InputSelection,
+  LoadedInput,
+} from './connectHost.ts';
+export { connectHost, selectInputs } from './connectHost.ts';
+export type { StructureValue } from './hostStructure.ts';
+export {
+  STRUCTURE_KINDS,
+  hostStructureLoader,
+  hostStructureSource,
+  readHostMolecule,
+} from './hostStructure.ts';
+export type {
+  CheckOutcome,
+  CheckedValue,
+  KnownKind,
+  MolfileValue,
+  OclIdValue,
+  SmilesValue,
+} from './kinds.ts';
+export { checkValue, isKnownKind, kindAccepts } from './kinds.ts';
+export type {
+  GetRequest,
+  HelloMessage,
+  HostError,
+  HostErrorCode,
+  HostItem,
+  HostRequest,
+  LoadRequest,
+  ResultMessage,
+  ToolInput,
+  ToolInterface,
+  ToolOutput,
+  UsedItem,
+} from './protocol.ts';
+export {
+  CONNECT_TYPE,
+  HELLO_TYPE,
+  MAX_ITEMS,
+  MAX_LABEL_LENGTH,
+  PROTOCOL_VERSION,
+  isConnect,
+  parseRequest,
+} from './protocol.ts';