react-cheminfo 0.51.0 → 0.52.0

package/lib/host/ui/useHostConnection.js

@@ -0,0 +1,62 @@
+/**
+ * Connect a tool to the page that frames it, when there is one.
+ *
+ * The protocol and its schemas are fetched only then, so a visitor on the site
+ * itself never downloads them.
+ */
+import { useEffect, useRef } from 'react';
+/** Once per page: React may mount the caller twice, the host is greeted once. */
+let started = false;
+/**
+ * Introduce the tool to its parent frame, or to the window that opened it, and
+ * serve that host for the life of the page.
+ *
+ * Call it after the hook that applies the address: effects run in order, so
+ * the address has been applied by the time the host is greeted, and a host's
+ * structure replaces the one the frame's link named rather than the reverse.
+ * The latest `load` is always the one called, so it may close over state.
+ * @param tool - What the tool takes and gives.
+ * @param handlers - See {@link HostHandlers}.
+ */
+export function useHostConnection(tool, handlers) {
+    const latest = useRef(handlers);
+    useEffect(() => {
+        latest.current = handlers;
+    });
+    useEffect(() => {
+        if (started)
+            return;
+        const host = hostWindow();
+        if (host === null)
+            return;
+        started = true;
+        import("../core/connectHost.js")
+            .then(({ connectHost }) => {
+            connectHost({
+                host,
+                listen: (listener) => {
+                    globalThis.addEventListener('message', listener);
+                    return () => {
+                        globalThis.removeEventListener('message', listener);
+                    };
+                },
+                tool,
+                origin: globalThis.location.origin,
+                build: latest.current.build ?? null,
+                load: (inputs) => {
+                    latest.current.load(inputs);
+                },
+            });
+        })
+            .catch(() => {
+            started = false;
+        });
+    }, [tool]);
+}
+function hostWindow() {
+    const { parent, opener } = globalThis.window;
+    if (parent !== globalThis.window)
+        return parent;
+    return opener ?? null;
+}
+//# sourceMappingURL=useHostConnection.js.map

package/lib/host/ui/useHostConnection.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useHostConnection.js","sourceRoot":"","sources":["../../../src/host/ui/useHostConnection.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAqB1C,iFAAiF;AACjF,IAAI,OAAO,GAAG,KAAK,CAAC;AAEpB;;;;;;;;;;GAUG;AACH,MAAM,UAAU,iBAAiB,CAC/B,IAAmB,EACnB,QAAsB;IAEtB,MAAM,MAAM,GAAG,MAAM,CAAC,QAAQ,CAAC,CAAC;IAChC,SAAS,CAAC,GAAG,EAAE;QACb,MAAM,CAAC,OAAO,GAAG,QAAQ,CAAC;IAC5B,CAAC,CAAC,CAAC;IAEH,SAAS,CAAC,GAAG,EAAE;QACb,IAAI,OAAO;YAAE,OAAO;QACpB,MAAM,IAAI,GAAG,UAAU,EAAE,CAAC;QAC1B,IAAI,IAAI,KAAK,IAAI;YAAE,OAAO;QAC1B,OAAO,GAAG,IAAI,CAAC;QACf,MAAM,CAAC,wBAAwB,CAAC;aAC7B,IAAI,CAAC,CAAC,EAAE,WAAW,EAAE,EAAE,EAAE;YACxB,WAAW,CAAC;gBACV,IAAI;gBACJ,MAAM,EAAE,CAAC,QAAQ,EAAE,EAAE;oBACnB,UAAU,CAAC,gBAAgB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;oBACjD,OAAO,GAAG,EAAE;wBACV,UAAU,CAAC,mBAAmB,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC;oBACtD,CAAC,CAAC;gBACJ,CAAC;gBACD,IAAI;gBACJ,MAAM,EAAE,UAAU,CAAC,QAAQ,CAAC,MAAM;gBAClC,KAAK,EAAE,MAAM,CAAC,OAAO,CAAC,KAAK,IAAI,IAAI;gBACnC,IAAI,EAAE,CAAC,MAAM,EAAE,EAAE;oBACf,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;gBAC9B,CAAC;aACF,CAAC,CAAC;QACL,CAAC,CAAC;aACD,KAAK,CAAC,GAAG,EAAE;YACV,OAAO,GAAG,KAAK,CAAC;QAClB,CAAC,CAAC,CAAC;IACP,CAAC,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC;AACb,CAAC;AAED,SAAS,UAAU;IACjB,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,GAAG,UAAU,CAAC,MAAM,CAAC;IAC7C,IAAI,MAAM,KAAK,UAAU,CAAC,MAAM;QAAE,OAAO,MAAM,CAAC;IAChD,OAAQ,MAAwB,IAAI,IAAI,CAAC;AAC3C,CAAC"}

package/lib/host-testing.d.ts

@@ -0,0 +1,8 @@
+/**
+ * A stand-in host for a tool's end-to-end tests, and the messages SciPeaks
+ * sends. Node only: it serves a page.
+ */
+export type { StandInHost, StandInHostLog, } from './host/testing/standInHost.ts';
+export { readStandInHostLog, startStandInHost, } from './host/testing/standInHost.ts';
+export { SCIPEAKS_ETHYLBENZENE_LOAD, SCIPEAKS_ETHYLBENZENE_MOLFILE, SCIPEAKS_HOST_NAME, } from './host/testing/sciPeaks.ts';
+//# sourceMappingURL=host-testing.d.ts.map

package/lib/host-testing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-testing.d.ts","sourceRoot":"","sources":["../src/host-testing.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,YAAY,EACV,WAAW,EACX,cAAc,GACf,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,EAC7B,kBAAkB,GACnB,MAAM,4BAA4B,CAAC"}

package/lib/host-testing.js

@@ -0,0 +1,7 @@
+/**
+ * A stand-in host for a tool's end-to-end tests, and the messages SciPeaks
+ * sends. Node only: it serves a page.
+ */
+export { readStandInHostLog, startStandInHost, } from "./host/testing/standInHost.js";
+export { SCIPEAKS_ETHYLBENZENE_LOAD, SCIPEAKS_ETHYLBENZENE_MOLFILE, SCIPEAKS_HOST_NAME, } from "./host/testing/sciPeaks.js";
+//# sourceMappingURL=host-testing.js.map

package/lib/host-testing.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host-testing.js","sourceRoot":"","sources":["../src/host-testing.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAMH,OAAO,EACL,kBAAkB,EAClB,gBAAgB,GACjB,MAAM,+BAA+B,CAAC;AACvC,OAAO,EACL,0BAA0B,EAC1B,6BAA6B,EAC7B,kBAAkB,GACnB,MAAM,4BAA4B,CAAC"}

package/lib/host.d.ts

@@ -0,0 +1,11 @@
+/**
+ * The host protocol: a page that frames a tool — an electronic lab notebook, a
+ * course — hands it typed data, checked against pipeline.cheminfo.org's kinds.
+ *
+ * Its own door because the schemas are checked with ajv. `useHostConnection`
+ * fetches ajv and the connection only when the page is framed, so a site that
+ * calls it ships nothing extra to a visitor who opened it directly.
+ */
+export * from './host/core/index.ts';
+export * from './host/ui/index.ts';
+//# sourceMappingURL=host.d.ts.map

package/lib/host.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.d.ts","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC"}

package/lib/host.js

@@ -0,0 +1,11 @@
+/**
+ * The host protocol: a page that frames a tool — an electronic lab notebook, a
+ * course — hands it typed data, checked against pipeline.cheminfo.org's kinds.
+ *
+ * Its own door because the schemas are checked with ajv. `useHostConnection`
+ * fetches ajv and the connection only when the page is framed, so a site that
+ * calls it ships nothing extra to a visitor who opened it directly.
+ */
+export * from "./host/core/index.js";
+export * from "./host/ui/index.js";
+//# sourceMappingURL=host.js.map

package/lib/host.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"host.js","sourceRoot":"","sources":["../src/host.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,cAAc,sBAAsB,CAAC;AACrC,cAAc,oBAAoB,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-cheminfo",
-  "version": "0.51.0",
+  "version": "0.52.0",
   "license": "MIT",
   "description": "React components, hooks and framework-free helpers shared by the cheminfo sites: site chrome, citations, sharing, routing, pedagogy, charts, and the structure, orbital and 3D molecule viewers",
   "author": "Luc Patiny",
@@ -18,6 +18,8 @@
     "./build-info": "./lib/build-info.js",
     "./conformers": "./lib/conformers.js",
     "./core": "./lib/core.js",
+    "./host": "./lib/host.js",
+    "./host-testing": "./lib/host-testing.js",
     "./ir": "./lib/ir.js",
     "./molecule3d": "./lib/molecule3d.js",
     "./molstar/*": "./lib/molstar/*/index.js",
@@ -66,6 +68,7 @@
   "dependencies": {
     "@formatjs/icu-messageformat-parser": "^3.5.20",
     "@tanstack/react-virtual": "^3.14.13",
+    "ajv": "^8.20.0",
     "cheminfo-font": "^1.28.0",
     "cheminfo-types": "^1.16.0",
     "convert-to-jcamp": "^7.0.1",

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