react-cheminfo 0.77.0 → 0.78.0

package/src/host/core/resultKinds.ts

@@ -0,0 +1,65 @@
+/**
+ * The kinds a tool hands back to the page that frames it: a picture of what it
+ * shows, a name it worked out, a table of values it predicted.
+ *
+ * A host checks what comes back as a tool checks what it is sent: against the
+ * kind it asked for, stripped of the fields that kind does not name.
+ * `chem.name` is a category — a tool names its preferred IUPAC name
+ * `chem.name.iupac` — so a host asking for any name reads every one of them.
+ */
+
+/** `image.svg`: a picture, as an SVG document. */
+export interface SvgImageValue {
+  /** The SVG document, as text. */
+  svg: string;
+}
+
+/** `chem.name`: a name a structure goes by. */
+export interface NameValue {
+  /** The name, as written. */
+  name: string;
+}
+
+/** One cell of a `data.table`: a number, a text, or `null` where there is none. */
+export type TableCell = string | number | null;
+
+/** `data.table`: values laid out as a table, headings first. */
+export interface TableValue {
+  /** The heading of each column, in order. */
+  columns: string[];
+  /** The rows, each holding one cell per column. */
+  rows: TableCell[][];
+}
+
+/** The schema of `image.svg`. */
+export const SVG_IMAGE_SCHEMA = {
+  type: 'object',
+  properties: { svg: { type: 'string' } },
+  required: ['svg'],
+  additionalProperties: false,
+} as const;
+
+/** The schema of `chem.name`. */
+export const NAME_SCHEMA = {
+  type: 'object',
+  properties: { name: { type: 'string' } },
+  required: ['name'],
+  additionalProperties: false,
+} as const;
+
+/** The schema of `data.table`. */
+export const TABLE_SCHEMA = {
+  type: 'object',
+  properties: {
+    columns: { type: 'array', items: { type: 'string' } },
+    rows: {
+      type: 'array',
+      items: {
+        type: 'array',
+        items: { type: ['string', 'number', 'null'] },
+      },
+    },
+  },
+  required: ['columns', 'rows'],
+  additionalProperties: false,
+} as const;

package/src/host/core/toolMessages.ts

@@ -0,0 +1,160 @@
+/**
+ * What a framed tool sends its host, read as the untrusted input it is: the
+ * `hello` it posts to the window, and on the port the `result` of each request
+ * and the `output` it sends when a value the host takes back changes.
+ *
+ * Anything that is not well formed is `null` and is ignored, as a tool ignores
+ * a request it does not know: a newer tool talking, not an error.
+ */
+
+import {
+  MAX_LABEL_LENGTH,
+  isRecord,
+  readItems,
+  readStrings,
+} from './messageValues.ts';
+import type {
+  HelloMessage,
+  HostError,
+  HostErrorCode,
+  OutputMessage,
+  ResultMessage,
+  ToolInput,
+  ToolOutput,
+  UsedItem,
+} from './protocol.ts';
+import { HELLO_TYPE, PROTOCOL_VERSION } from './protocol.ts';
+
+/** What a tool says of itself in `hello`. */
+export type ToolHello = HelloMessage['tool'];
+
+/** How long the sentence of an error may be, in characters; the rest is cut. */
+const MAX_MESSAGE_LENGTH = 500;
+
+const ERROR_CODES: readonly HostErrorCode[] = [
+  'invalid',
+  'unreadable',
+  'no-input',
+  'no-output',
+];
+
+/**
+ * Read a tool's `hello`, in this version of the protocol.
+ * @param data - What the window delivered.
+ * @returns What the tool takes and gives, or `null` for anything else.
+ */
+export function readHello(data: unknown): ToolHello | null {
+  if (
+    !isRecord(data) ||
+    data.type !== HELLO_TYPE ||
+    data.version !== PROTOCOL_VERSION
+  ) {
+    return null;
+  }
+  const { tool } = data;
+  if (
+    !isRecord(tool) ||
+    typeof tool.name !== 'string' ||
+    typeof tool.origin !== 'string'
+  ) {
+    return null;
+  }
+  return {
+    name: tool.name.slice(0, MAX_LABEL_LENGTH),
+    origin: tool.origin,
+    build: tool.build ?? null,
+    inputs: readInputs(tool.inputs),
+    outputs: readOutputs(tool.outputs),
+  };
+}
+
+/**
+ * Read a message a tool sent through the port.
+ * @param data - What the port delivered.
+ * @returns The `result` or the `output`, or `null` for anything else.
+ */
+export function readToolMessage(
+  data: unknown,
+): ResultMessage | OutputMessage | null {
+  if (!isRecord(data)) return null;
+  if (data.type === 'output') {
+    if (typeof data.document !== 'string' || !Array.isArray(data.items)) {
+      return null;
+    }
+    return {
+      type: 'output',
+      document: data.document,
+      items: readItems(data.items),
+    };
+  }
+  if (data.type !== 'result') return null;
+  const { id, ok, items, used, error } = data;
+  if (typeof id !== 'string') return null;
+  if (ok === true) {
+    return Array.isArray(items)
+      ? { type: 'result', id, ok: true, items: readItems(items) }
+      : { type: 'result', id, ok: true, used: readUsed(used) };
+  }
+  return { type: 'result', id, ok: false, error: readError(error) };
+}
+
+function readInputs(value: unknown): ToolInput[] {
+  const inputs: ToolInput[] = [];
+  if (!Array.isArray(value)) return inputs;
+  for (const entry of value) {
+    if (!isRecord(entry) || typeof entry.key !== 'string') continue;
+    const input: ToolInput = {
+      key: entry.key,
+      kinds: readStrings(entry.kinds),
+    };
+    if (entry.many === true) input.many = true;
+    if (entry.optional === true) input.optional = true;
+    inputs.push(input);
+  }
+  return inputs;
+}
+
+function readOutputs(value: unknown): ToolOutput[] {
+  const outputs: ToolOutput[] = [];
+  if (!Array.isArray(value)) return outputs;
+  for (const entry of value) {
+    if (
+      isRecord(entry) &&
+      typeof entry.key === 'string' &&
+      typeof entry.kind === 'string'
+    ) {
+      outputs.push({ key: entry.key, kind: entry.kind });
+    }
+  }
+  return outputs;
+}
+
+function readUsed(value: unknown): UsedItem[] {
+  const used: UsedItem[] = [];
+  if (!Array.isArray(value)) return used;
+  for (const entry of value) {
+    if (
+      isRecord(entry) &&
+      typeof entry.key === 'string' &&
+      typeof entry.kind === 'string'
+    ) {
+      used.push({ key: entry.key, kind: entry.kind });
+    }
+  }
+  return used;
+}
+
+function readError(value: unknown): HostError {
+  const error: HostError = {
+    code: 'invalid',
+    message: 'The tool refused the request and gave no reason.',
+  };
+  if (!isRecord(value)) return error;
+  const code = ERROR_CODES.find((known) => known === value.code);
+  if (code !== undefined) error.code = code;
+  if (typeof value.message === 'string' && value.message.trim() !== '') {
+    error.message = value.message.slice(0, MAX_MESSAGE_LENGTH);
+  }
+  if (Array.isArray(value.errors)) error.errors = readStrings(value.errors);
+  return error;
+}

package/src/host/ui/index.ts

@@ -1,2 +1,8 @@
+export type {
+  FramedTool,
+  FramedToolOptions,
+  FramedToolStatus,
+} from './useFramedTool.ts';
+export { HELLO_TIMEOUT, useFramedTool } from './useFramedTool.ts';
 export type { HostHandlers } from './useHostConnection.ts';
 export { useHostConnection } from './useHostConnection.ts';

package/src/host/ui/useFramedTool.ts

@@ -0,0 +1,213 @@
+/**
+ * Frame a tool of the family and talk to it: hand it the document to show,
+ * keep what it sends back, and ask it for other values.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import type {
+  LoadOutcome,
+  ToolConnection,
+  ToolDocument,
+} from '../core/connectTool.ts';
+import { connectTool } from '../core/connectTool.ts';
+import type { HostItem } from '../core/protocol.ts';
+import type { ToolHello } from '../core/toolMessages.ts';
+
+/** What {@link useFramedTool} frames, and what it hands over. */
+export interface FramedToolOptions {
+  /**
+   * The address the frame opens, `?embed=1` included. Its origin is the only
+   * one talked to.
+   */
+  url: string;
+  /** How the host introduces itself to the tool. */
+  host: string;
+  /**
+   * The document to show, or `null` while there is none. It is handed over
+   * whenever its `document` changes, and never twice in a row.
+   */
+  document: ToolDocument | null;
+  /**
+   * How long the tool has to say `hello` before it counts as unavailable, in
+   * milliseconds.
+   * @default HELLO_TIMEOUT
+   */
+  helloTimeout?: number;
+}
+
+/** Whether the tool answered: still loading, talking, or silent past the wait. */
+export type FramedToolStatus = 'connecting' | 'connected' | 'unavailable';
+
+/** A framed tool, as the host page sees it. */
+export interface FramedTool {
+  /**
+   * The callback ref of the `<iframe>`, rendered with the hook and given no
+   * `src` of its own: the address is set once this page listens, so the
+   * tool's `hello` cannot be missed.
+   */
+  attachFrame: (element: HTMLIFrameElement | null) => void;
+  /**
+   * Show the frame on the whole screen, from a click; Esc brings it back.
+   * Rejects where the browser will not.
+   */
+  fullscreen: () => Promise<void>;
+  /** Whether the tool answered. */
+  status: FramedToolStatus;
+  /** What the tool said it takes and gives, once it has. */
+  tool: ToolHello | null;
+  /** What became of the document on screen, once the tool answered. */
+  outcome: LoadOutcome | null;
+  /**
+   * The values the document's `accept` names, by output key: those the tool
+   * held once it showed the document, then every change it sent.
+   */
+  outputs: ReadonlyMap<string, HostItem>;
+  /** Ask for the current value of some outputs; rejects with the tool's reason. */
+  get: (keys: readonly string[]) => Promise<HostItem[]>;
+}
+
+/**
+ * How long a tool has to say `hello`, in milliseconds: a cold start fetches the
+ * tool's page, its scripts and its fonts, on a slow line as well.
+ */
+export const HELLO_TIMEOUT = 20_000;
+
+const NO_OUTPUTS: ReadonlyMap<string, HostItem> = new Map();
+
+/**
+ * Frame a tool, and keep it showing a document.
+ *
+ * The frame is opened once and stays: a new document goes to the tool through
+ * the protocol, the way a host hands over data, rather than as a new address
+ * that would reload the tool and lose what its visitor did in it. A tool that
+ * reloads all the same is handed the document again.
+ * @param options - See {@link FramedToolOptions}.
+ * @returns See {@link FramedTool}.
+ */
+export function useFramedTool(options: FramedToolOptions): FramedTool {
+  const { url, host, document, helloTimeout = HELLO_TIMEOUT } = options;
+  const frame = useRef<HTMLIFrameElement | null>(null);
+  const attachFrame = useCallback((element: HTMLIFrameElement | null) => {
+    frame.current = element;
+  }, []);
+  const connection = useRef<ToolConnection | null>(null);
+  const latest = useRef(document);
+  const [link, setLink] = useState<Link | null>(null);
+  const [answer, setAnswer] = useState<Answer | null>(null);
+  const [held, setHeld] = useState<Held | null>(null);
+
+  useEffect(() => {
+    latest.current = document;
+  });
+
+  useEffect(() => {
+    const element = frame.current;
+    if (element === null) return;
+    let greeted = false;
+    const opened = connectTool({
+      frame: () => element.contentWindow,
+      origin: new URL(url, globalThis.location.href).origin,
+      host: { name: host },
+      listen: (listener) => {
+        globalThis.addEventListener('message', listener);
+        return () => {
+          globalThis.removeEventListener('message', listener);
+        };
+      },
+      onHello: (tool) => {
+        greeted = true;
+        setLink({ url, status: 'connected', tool });
+      },
+      onOutput: (message) => {
+        setHeld((previous) =>
+          hold(previous, `${url}\n${message.document}`, message.items),
+        );
+      },
+    });
+    connection.current = opened;
+    const timer = setTimeout(() => {
+      if (!greeted) setLink({ url, status: 'unavailable', tool: null });
+    }, helloTimeout);
+    // Set once the listener exists, and again when the effect runs anew, so
+    // the tool greets this listener rather than one already closed.
+    element.src = url;
+    return () => {
+      clearTimeout(timer);
+      opened.close();
+      if (connection.current === opened) connection.current = null;
+    };
+  }, [url, host, helloTimeout]);
+
+  const name = document?.document ?? null;
+  useEffect(() => {
+    const opened = connection.current;
+    const shown = latest.current;
+    if (opened === null || shown === null) return;
+    const key = `${url}\n${shown.document}`;
+    void opened.load(shown).then(async (outcome) => {
+      setAnswer({ key, outcome });
+      const accept = shown.accept ?? [];
+      if (outcome.status !== 'loaded' || accept.length === 0) return;
+      // What the tool held once it showed the document is never sent unasked.
+      const items = await opened.get(accept).catch(() => []);
+      setHeld((previous) => hold(previous, key, items));
+    });
+  }, [name, url, host]);
+
+  const fullscreen = useCallback(async () => {
+    const element = frame.current;
+    if (element === null) throw new Error('The tool is not open.');
+    await element.requestFullscreen();
+  }, []);
+
+  const get = useCallback(async (keys: readonly string[]) => {
+    const opened = connection.current;
+    if (opened === null) {
+      throw new Error('The tool is not open, so it has nothing to give.');
+    }
+    return opened.get(keys);
+  }, []);
+
+  const key = name === null ? null : `${url}\n${name}`;
+  const current = link?.url === url ? link : null;
+  return {
+    attachFrame,
+    fullscreen,
+    status: current?.status ?? 'connecting',
+    tool: current?.tool ?? null,
+    outcome: answer !== null && answer.key === key ? answer.outcome : null,
+    outputs: held !== null && held.key === key ? held.outputs : NO_OUTPUTS,
+    get,
+  };
+}
+
+interface Link {
+  url: string;
+  status: Exclude<FramedToolStatus, 'connecting'>;
+  tool: ToolHello | null;
+}
+
+interface Answer {
+  key: string;
+  outcome: LoadOutcome;
+}
+
+interface Held {
+  key: string;
+  outputs: ReadonlyMap<string, HostItem>;
+}
+
+function hold(
+  previous: Held | null,
+  key: string,
+  items: readonly HostItem[],
+): Held {
+  const outputs = new Map(
+    previous?.key === key ? previous.outputs : NO_OUTPUTS,
+  );
+  for (const item of items) {
+    if (item.key !== undefined) outputs.set(item.key, item);
+  }
+  return { key, outputs };
+}

package/src/molecule3d/ui/MoleculeCanvas3D.tsx

@@ -64,6 +64,7 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
     fileName = 'molecule',
     background,
     minHeight = 320,
+    onCapture,
     onFailureChange,
   } = props;
   const tools = resolveMolecule3DTools(toolsProp);
@@ -139,13 +140,21 @@ export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
     camera: props,
   });
 
-  const { canvasSize, exportImage, copyImage } = useImageExport(
+  const { canvasSize, exportImage, copyImage, capture } = useImageExport(
     container,
     viewerRef,
     fileName,
     framesPerSecond,
   );
 
+  useEffect(() => {
+    if (onCapture === undefined || container === null) return;
+    onCapture(capture);
+    return () => {
+      onCapture(null);
+    };
+  }, [onCapture, container, capture]);
+
   return (
     <Molecule3DStage style={{ ...STAGE_STYLE, minHeight }}>
       {(fullscreen) => (

package/src/molecule3d/ui/exportMoleculeImage.ts

@@ -59,6 +59,28 @@ export async function captureMoleculePng(
   return new Blob([dataUriBytes(dataUri)], { type: FIGURE_PNG_TYPE });
 }
 
+/**
+ * Render the scene as an SVG holding the rendered image, as the export writes
+ * it.
+ * @param viewer - The viewer holding the scene.
+ * @param scale - Multiple of the canvas on screen it is rendered at.
+ * @param size - Size of the canvas on screen, CSS pixels.
+ * @returns The SVG markup.
+ * @throws {Error} When the viewer has nothing to render.
+ */
+export async function captureMoleculeSvg(
+  viewer: SceneCapture,
+  scale: number,
+  size: ImageSize,
+): Promise<string> {
+  const pixels = figurePixels(size, scale);
+  const dataUri = await viewer.captureImage(pixels);
+  if (dataUri === undefined) {
+    throw new Error('There is no picture to copy yet.');
+  }
+  return rasterSvgMarkup(dataUri, pixels);
+}
+
 /**
  * Render the scene and hand it to the browser as a file.
  * @param viewer - The viewer holding the scene.

package/src/molecule3d/ui/index.ts

@@ -25,4 +25,7 @@ export { exportMoleculeImage } from './exportMoleculeImage.ts';
 export type { ImageExport } from './useImageExport.ts';
 export { useImageExport } from './useImageExport.ts';
 export { MoleculeViewer3D } from './MoleculeViewer3D.tsx';
-export type { MoleculeViewer3DProps } from './moleculeViewer3DProps.ts';
+export type {
+  Molecule3DCapture,
+  MoleculeViewer3DProps,
+} from './moleculeViewer3DProps.ts';

package/src/molecule3d/ui/moleculeViewer3DProps.ts

@@ -7,6 +7,23 @@ import type { Molecule3DHighlight } from '../core/highlight.ts';
 import type { Measurement } from '../core/measurement.ts';
 import type { Molecule3DSettings, Molecule3DTools } from '../core/settings.ts';
 
+/** The scene on screen, rendered as a picture on request. */
+export interface Molecule3DCapture {
+  /**
+   * Render the scene as an SVG document holding the rendered image: a molecule
+   * drawn by WebGL has no vector form.
+   * @param scale - Multiple of the canvas on screen it is rendered at.
+   * @returns The SVG markup.
+   */
+  svg: (scale: number) => Promise<string>;
+  /**
+   * Render the scene as a PNG.
+   * @param scale - Multiple of the canvas on screen it is rendered at.
+   * @returns The PNG.
+   */
+  png: (scale: number) => Promise<Blob>;
+}
+
 /**
  * Props of `MoleculeViewer3D`.
  *
@@ -129,6 +146,13 @@ export interface MoleculeViewer3DProps {
    * @default 'molecule'
    */
   fileName?: string;
+  /**
+   * Handed the means to render the scene on screen once the viewer exists, and
+   * `null` when it goes — for a page that hands the picture on, to a host
+   * framing it. Keep it stable: a new function is handed the means again.
+   * @default undefined
+   */
+  onCapture?: (capture: Molecule3DCapture | null) => void;
   /**
    * Scene background, as `#rrggbb`.
    * @default '#ffffff'

package/src/molecule3d/ui/useImageExport.ts

@@ -1,5 +1,5 @@
 import type { RefObject } from 'react';
-import { useCallback } from 'react';
+import { useCallback, useMemo } from 'react';
 
 import type { FigureNotice } from '../../download/core/copyFigure.ts';
 import { copyFigure } from '../../download/core/copyFigure.ts';
@@ -10,8 +10,10 @@ import { DEFAULT_FRAMES_PER_SECOND } from '../core/animatedPng.ts';
 import type { SceneCapture } from './exportMoleculeImage.ts';
 import {
   captureMoleculePng,
+  captureMoleculeSvg,
   exportMoleculeImage,
 } from './exportMoleculeImage.ts';
+import type { Molecule3DCapture } from './moleculeViewer3DProps.ts';
 
 /** What {@link useImageExport} hands the export panel. */
 export interface ImageExport {
@@ -31,6 +33,8 @@ export interface ImageExport {
    * from the click itself: Safari only allows a write the click started.
    */
   copyImage: (scale: number) => Promise<FigureNotice>;
+  /** The scene rendered on request, for a page handing the picture on. */
+  capture: Molecule3DCapture;
 }
 
 /**
@@ -85,5 +89,27 @@ export function useImageExport(
     [canvasSize, viewerRef],
   );
 
-  return { canvasSize, exportImage, copyImage };
+  const capture = useMemo(
+    (): Molecule3DCapture => ({
+      svg: async (scale) => {
+        const viewer = viewerRef.current;
+        const size = canvasSize();
+        if (viewer === null || size === null) {
+          throw new Error('There is no picture to copy yet.');
+        }
+        return captureMoleculeSvg(viewer, scale, size);
+      },
+      png: async (scale) => {
+        const viewer = viewerRef.current;
+        const size = canvasSize();
+        if (viewer === null || size === null) {
+          throw new Error('There is no picture to copy yet.');
+        }
+        return captureMoleculePng(viewer, scale, size);
+      },
+    }),
+    [canvasSize, viewerRef],
+  );
+
+  return { canvasSize, exportImage, copyImage, capture };
 }