react-cheminfo 0.70.0 → 0.72.0

package/src/download/core/figurePng.ts

@@ -42,18 +42,31 @@ export async function figurePng(
 }
 
 /**
- * The SVG document, decoded and ready to be painted.
+ * Where the browser reads an SVG document back from, to paint it.
  *
- * It goes through an object URL rather than a `data:` one because a figure of
- * a few thousand dots runs to hundreds of kilobytes, and a `data:` URL that
- * long is refused outright by some browsers.
+ * An object URL rather than a `data:` one, because a figure of a few thousand
+ * dots runs to hundreds of kilobytes and a `data:` URL that long is refused
+ * outright by some browsers — except for a document holding a
+ * `<foreignObject>`, which is how native MathML sits in a chart. Chromium
+ * taints any canvas that paints such a document read from an object URL, and
+ * the figure then cannot be saved at all; read from a `data:` URL it paints
+ * clean. Such a figure carries a handful of labels, far short of that length.
+ * @param markup - The SVG document.
+ * @returns The URL; one starting with `blob:` is revoked once read.
+ */
+export function svgImageUrl(markup: string): string {
+  return markup.includes('<foreignObject')
+    ? `data:${FIGURE_SVG_TYPE},${encodeURIComponent(markup)}`
+    : URL.createObjectURL(new Blob([markup], { type: FIGURE_SVG_TYPE }));
+}
+
+/**
+ * The SVG document, decoded and ready to be painted.
  * @param figure - The figure, already copied off the page.
  * @returns The decoded image.
  */
 async function loadFigure(figure: FigureSvg): Promise<HTMLImageElement> {
-  const url = URL.createObjectURL(
-    new Blob([figure.markup], { type: FIGURE_SVG_TYPE }),
-  );
+  const url = svgImageUrl(figure.markup);
   try {
     const image = new Image(figure.width, figure.height);
     await new Promise<void>((resolve, reject) => {
@@ -65,7 +78,7 @@ async function loadFigure(figure: FigureSvg): Promise<HTMLImageElement> {
     });
     return image;
   } finally {
-    URL.revokeObjectURL(url);
+    if (url.startsWith('blob:')) URL.revokeObjectURL(url);
   }
 }
 

package/src/download/core/svgToPng.ts

@@ -1,3 +1,4 @@
+import { svgImageUrl } from './figurePng.ts';
 import type { SvgBox } from './svgBounds.ts';
 import { svgToString } from './svgToString.ts';
 
@@ -92,9 +93,7 @@ function side(value: number): number {
  * @returns The image, already decoded, so it can be drawn straight away.
  */
 async function loadImage(source: string): Promise<HTMLImageElement> {
-  const url = URL.createObjectURL(
-    new Blob([source], { type: 'image/svg+xml' }),
-  );
+  const url = svgImageUrl(source);
   try {
     const image = new Image();
     image.src = url;
@@ -102,7 +101,7 @@ async function loadImage(source: string): Promise<HTMLImageElement> {
     return image;
   } finally {
     // The decoded image no longer needs the URL it came from.
-    URL.revokeObjectURL(url);
+    if (url.startsWith('blob:')) URL.revokeObjectURL(url);
   }
 }
 

package/src/format/core/relativeTime.ts

@@ -16,7 +16,8 @@ const UNITS: ReadonlyArray<{
   { unit: 'minute', milliseconds: MINUTE },
 ];
 
-const FORMATTER = new Intl.RelativeTimeFormat('en-US', { numeric: 'auto' });
+/** One formatter per locale, made the first time that locale is asked for. */
+const FORMATTERS = new Map<string, Intl.RelativeTimeFormat>();
 
 /** How {@link formatRelativeTime} measures and what it writes for nothing. */
 export interface FormatRelativeTimeOptions {
@@ -32,16 +33,21 @@ export interface FormatRelativeTimeOptions {
    * @default MISSING_VALUE
    */
   missing?: string;
+  /**
+   * The language the phrase is written in: the page's, from `useLanguage()`.
+   * @default 'en-US'
+   */
+  locale?: string;
 }
 
 /**
  * How far an instant is from now, in words: `just now`, `5 minutes ago`,
- * `yesterday`, `in 3 weeks`.
+ * `yesterday`, `in 3 weeks` — or `il y a 5 minutes` in French.
  *
  * The largest unit that fits is used and the count is rounded towards zero, so
  * ninety minutes read `1 hour ago` rather than claiming two. Under a minute
- * either way is `just now`, which also absorbs a clock that is a few seconds
- * ahead. The locale is fixed to `en-US`, like every formatter of this module.
+ * either way is `just now` (the language's own word for now, outside
+ * English), which also absorbs a clock that is a few seconds ahead.
  * @param instant - Epoch milliseconds, an ISO timestamp or a date.
  * @param options - See {@link FormatRelativeTimeOptions}.
  * @returns The phrase, or the missing text when the instant is absent or unreadable.
@@ -50,20 +56,36 @@ export function formatRelativeTime(
   instant: number | string | Date | undefined,
   options: FormatRelativeTimeOptions = {},
 ): string {
-  const { now = Date.now(), missing = MISSING_VALUE } = options;
+  const {
+    now = Date.now(),
+    missing = MISSING_VALUE,
+    locale = 'en-US',
+  } = options;
   const time = toTime(instant);
   const reference = toTime(now);
   if (time === undefined || reference === undefined) return missing;
 
+  const formatter = formatterOf(locale);
   const elapsed = time - reference;
   const distance = Math.abs(elapsed);
   for (const { unit, milliseconds } of UNITS) {
     if (distance >= milliseconds) {
       const count = Math.floor(distance / milliseconds);
-      return FORMATTER.format(elapsed < 0 ? -count : count, unit);
+      return formatter.format(elapsed < 0 ? -count : count, unit);
     }
   }
-  return 'just now';
+  return locale.toLowerCase().startsWith('en')
+    ? 'just now'
+    : formatter.format(0, 'second');
+}
+
+function formatterOf(locale: string): Intl.RelativeTimeFormat {
+  let formatter = FORMATTERS.get(locale);
+  if (formatter === undefined) {
+    formatter = new Intl.RelativeTimeFormat(locale, { numeric: 'auto' });
+    FORMATTERS.set(locale, formatter);
+  }
+  return formatter;
 }
 
 function toTime(

package/src/host/core/connectHost.ts

@@ -1,22 +1,22 @@
 /**
  * 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.
+ * frames it, take the private port that page answers with, serve what arrives
+ * through it, and send back what the host takes back.
  *
  * 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 { HostOutputs } from './hostOutputs.ts';
+import {
+  OUTPUT_DELAY,
+  answerGet,
+  createOutputPublisher,
+} from './hostOutputs.ts';
 import type {
-  GetRequest,
   HelloMessage,
-  HostError,
-  HostItem,
   LoadRequest,
   ResultMessage,
-  ToolInput,
   ToolInterface,
   UsedItem,
 } from './protocol.ts';
@@ -26,13 +26,11 @@ import {
   isConnect,
   parseRequest,
 } from './protocol.ts';
+import type { LoadedInput } from './selectInputs.ts';
+import { selectInputs } from './selectInputs.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;
-}
+export type { InputSelection, LoadedInput } from './selectInputs.ts';
+export { selectInputs } from './selectInputs.ts';
 
 /** What a window `message` event carries, as far as the protocol reads it. */
 export interface HostMessageEvent {
@@ -54,17 +52,25 @@ export interface HostConnectionOptions {
   /** 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.
+   * Show the inputs of a new document. Throwing, or rejecting, 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 | Promise<void>;
+  /**
+   * Where the values of the tool's outputs are read, for `get` and for the
+   * `output` sent when one the host accepted changes.
+   * @default undefined — nothing goes back
    */
-  load: (inputs: readonly LoadedInput[]) => void;
+  outputs?: HostOutputs;
+  /**
+   * How long the outputs must stay still before a change is sent, in
+   * milliseconds.
+   * @default OUTPUT_DELAY
+   */
+  outputDelay?: number;
 }
 
-/** 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.
  *
@@ -72,24 +78,50 @@ export type InputSelection =
  * 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.
+ * Requests are served one at a time, in order, so a `get` sent after a `load`
+ * reads what that load showed, however long it took.
  * @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;
+  const { host, listen, tool, origin, build, load, outputs } = options;
+  const { outputDelay = OUTPUT_DELAY } = options;
   let port: MessagePort | null = null;
   let appliedDocument: string | null = null;
   let appliedUsed: UsedItem[] = [];
+  let served: Promise<void> = Promise.resolve();
+
+  const publisher =
+    outputs === undefined
+      ? null
+      : createOutputPublisher(
+          outputs,
+          (message) => port?.postMessage(message),
+          outputDelay,
+        );
+  const stopHearing = outputs?.subscribe(() => publisher?.changed());
 
   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);
+    served = served
+      .then(async () => {
+        const result =
+          request.type === 'load'
+            ? await applyLoad(request)
+            : answerGet(request, tool, outputs);
+        port?.postMessage(result);
+      })
+      // A request that failed must not stop the ones after it being served,
+      // and must still be seen: it is thrown again, on its own.
+      .catch((error: unknown) => {
+        queueMicrotask(() => {
+          throw error;
+        });
+      });
   }
 
-  function applyLoad(request: LoadRequest): ResultMessage {
+  async function applyLoad(request: LoadRequest): Promise<ResultMessage> {
     const { id, document, items } = request;
     if (document === appliedDocument) {
       return { type: 'result', id, ok: true, used: appliedUsed };
@@ -98,8 +130,11 @@ export function connectHost(options: HostConnectionOptions): () => void {
     if (!selection.ok) {
       return { type: 'result', id, ok: false, error: selection.error };
     }
+    // An edit still settling belongs to the document on screen, which the
+    // outputs describe only until this one replaces it.
+    publisher?.flush();
     try {
-      load(selection.inputs);
+      await load(selection.inputs);
     } catch (error) {
       const message = error instanceof Error ? error.message : String(error);
       return {
@@ -109,11 +144,19 @@ export function connectHost(options: HostConnectionOptions): () => void {
         error: { code: 'unreadable', message },
       };
     }
+    return applied(request, selection.inputs);
+  }
+
+  // Nothing else runs between a load's check and this: requests are served
+  // one at a time.
+  function applied(
+    request: LoadRequest,
+    inputs: readonly LoadedInput[],
+  ): ResultMessage {
+    const { id, document, accept = [] } = request;
     appliedDocument = document;
-    appliedUsed = selection.inputs.map(({ key, item }) => ({
-      key,
-      kind: item.kind,
-    }));
+    appliedUsed = inputs.map(({ key, item }) => ({ key, kind: item.kind }));
+    publisher?.baseline(document, accept);
     return { type: 'result', id, ok: true, used: appliedUsed };
   }
 
@@ -146,95 +189,9 @@ export function connectHost(options: HostConnectionOptions): () => void {
 
   return () => {
     stopListening();
+    stopHearing?.();
+    publisher?.stop();
     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/hostOutputs.ts

@@ -0,0 +1,197 @@
+/**
+ * What a tool hands back: the values a `get` asks for, and the `output` it
+ * sends when a value the host accepted changes.
+ *
+ * An `output` carries only what changed, item by item, against what the host
+ * already has: the values as they stood once its document was applied, then
+ * every value sent since. Opening a document therefore never writes it back,
+ * and a band picked on one spectrum of a sample leaves the others alone.
+ */
+
+import { kindAccepts } from './kinds.ts';
+import type {
+  GetRequest,
+  HostItem,
+  OutputMessage,
+  ResultMessage,
+  ToolInterface,
+} from './protocol.ts';
+
+/** Where a tool's outputs are read, and how their changes are heard. */
+export interface HostOutputs {
+  /**
+   * The value of every output now, one item each, carrying its `key` and the
+   * `id` of the item it was made from. It must already show a document once
+   * `load` has returned, or the host is sent back what it just loaded.
+   */
+  read: () => readonly HostItem[];
+  /** Be told whenever they may have changed; the returned function stops it. */
+  subscribe: (listener: () => void) => () => void;
+}
+
+/**
+ * How long the outputs must stay still before a change is sent, in
+ * milliseconds: a burst of edits is one message.
+ */
+export const OUTPUT_DELAY = 300;
+
+/**
+ * Answer a `get` with the values it asks for — every output when it names
+ * none.
+ * @param request - The request.
+ * @param tool - What the tool hands back.
+ * @param outputs - Where the values are read, if anywhere.
+ * @returns The values, or `no-output` when the tool has none of those asked.
+ */
+export function answerGet(
+  request: GetRequest,
+  tool: ToolInterface,
+  outputs: HostOutputs | undefined,
+): ResultMessage {
+  const { id, keys } = request;
+  const declared = new Set<string>();
+  for (const output of tool.outputs) declared.add(output.key);
+  if (outputs === undefined || declared.size === 0) {
+    return noOutput(id, `${tool.name} has nothing to give back yet.`);
+  }
+  const wanted = keys.length === 0 ? declared : new Set<string>();
+  for (const key of keys) {
+    if (declared.has(key)) wanted.add(key);
+  }
+  if (wanted.size === 0) {
+    return noOutput(
+      id,
+      `${tool.name} has no output called ${LIST.format(keys)}.`,
+    );
+  }
+  const items: HostItem[] = [];
+  for (const item of outputs.read()) {
+    if (item.key !== undefined && wanted.has(item.key)) items.push(item);
+  }
+  return { type: 'result', id, ok: true, items };
+}
+
+/** What the connection tells the publisher, and the means to stop it. */
+export interface OutputPublisher {
+  /** A document was applied: what the host has is what the tool now shows. */
+  baseline: (document: string, accept: readonly string[]) => void;
+  /** The outputs may have changed. */
+  changed: () => void;
+  /**
+   * Send what changed now rather than once it settles: another document is
+   * about to replace what the outputs are read from.
+   */
+  flush: () => void;
+  /** Send nothing more. */
+  stop: () => void;
+}
+
+/**
+ * Send the host what changed of the outputs it accepted, once they settle.
+ * @param outputs - Where the values are read.
+ * @param send - Posts a message to the host, when there is one.
+ * @param delay - How long the values must stay still, in milliseconds.
+ * @returns The publisher.
+ */
+export function createOutputPublisher(
+  outputs: HostOutputs,
+  send: (message: OutputMessage) => void,
+  delay: number,
+): OutputPublisher {
+  let document: string | null = null;
+  let accepted = new Set<string>();
+  let known = new Map<string, string>();
+  let timer: ReturnType<typeof setTimeout> | undefined;
+
+  function flush(): void {
+    timer = undefined;
+    if (document === null) return;
+    const items: HostItem[] = [];
+    for (const [identity, entry] of readAccepted(outputs, accepted)) {
+      if (known.get(identity) === entry.text) continue;
+      known.set(identity, entry.text);
+      items.push(entry.item);
+    }
+    if (items.length > 0) send({ type: 'output', document, items });
+  }
+
+  function stop(): void {
+    clearTimeout(timer);
+    timer = undefined;
+  }
+
+  return {
+    baseline(next, accept) {
+      stop();
+      document = next;
+      accepted = new Set(accept);
+      known = new Map();
+      for (const [identity, entry] of readAccepted(outputs, accepted)) {
+        known.set(identity, entry.text);
+      }
+    },
+    changed() {
+      if (document === null || accepted.size === 0) return;
+      stop();
+      timer = setTimeout(flush, delay);
+    },
+    flush() {
+      stop();
+      flush();
+    },
+    stop,
+  };
+}
+
+/**
+ * The accepted items, each under an identity that survives a re-read: its
+ * key, the id of the item it was made from, and its rank among items sharing
+ * both.
+ * @param outputs - Where the values are read.
+ * @param accepted - The keys and kinds the host takes back.
+ * @returns Each item with its value as text, by identity.
+ */
+function readAccepted(
+  outputs: HostOutputs,
+  accepted: ReadonlySet<string>,
+): Map<string, { item: HostItem; text: string }> {
+  const entries = new Map<string, { item: HostItem; text: string }>();
+  if (accepted.size === 0) return entries;
+  for (const item of outputs.read()) {
+    if (!isAccepted(item, accepted)) continue;
+    const base = `${item.key ?? item.kind}\n${item.id ?? ''}`;
+    let rank = 0;
+    while (entries.has(`${base}\n${rank}`)) rank++;
+    entries.set(`${base}\n${rank}`, {
+      item,
+      text: JSON.stringify(item.value),
+    });
+  }
+  return entries;
+}
+
+/**
+ * Whether the host takes an item back: `accept` names its output's key, or
+ * its kind — a kind taking every kind under it, as an input's does.
+ * @param item - The item.
+ * @param accepted - What the host takes back.
+ * @returns Whether it goes back.
+ */
+function isAccepted(item: HostItem, accepted: ReadonlySet<string>): boolean {
+  if (item.key !== undefined && accepted.has(item.key)) return true;
+  for (const name of accepted) {
+    if (kindAccepts(name, item.kind)) return true;
+  }
+  return false;
+}
+
+function noOutput(id: string, message: string): ResultMessage {
+  return {
+    type: 'result',
+    id,
+    ok: false,
+    error: { code: 'no-output', message },
+  };
+}
+
+const LIST = new Intl.ListFormat('en', { type: 'disjunction' });

package/src/host/core/index.ts

@@ -1,10 +1,11 @@
-export type {
-  HostConnectionOptions,
-  HostMessageEvent,
-  InputSelection,
-  LoadedInput,
-} from './connectHost.ts';
-export { connectHost, selectInputs } from './connectHost.ts';
+export type { HostConnectionOptions, HostMessageEvent } from './connectHost.ts';
+export { connectHost } from './connectHost.ts';
+export type { HostOutputs, OutputPublisher } from './hostOutputs.ts';
+export {
+  OUTPUT_DELAY,
+  answerGet,
+  createOutputPublisher,
+} from './hostOutputs.ts';
 export type { StructureValue } from './hostStructure.ts';
 export {
   STRUCTURE_KINDS,
@@ -12,6 +13,8 @@ export {
   hostStructureSource,
   readHostMolecule,
 } from './hostStructure.ts';
+export type { IrJdxValue, IrPeakValue, IrPeaksValue } from './irKinds.ts';
+export { IR_JDX_SCHEMA, IR_PEAKS_SCHEMA } from './irKinds.ts';
 export type {
   CheckOutcome,
   CheckedValue,
@@ -29,6 +32,7 @@ export type {
   HostItem,
   HostRequest,
   LoadRequest,
+  OutputMessage,
   ResultMessage,
   ToolInput,
   ToolInterface,
@@ -44,3 +48,5 @@ export {
   isConnect,
   parseRequest,
 } from './protocol.ts';
+export type { InputSelection, LoadedInput } from './selectInputs.ts';
+export { selectInputs } from './selectInputs.ts';