react-cheminfo 0.64.1 → 0.65.0

package/src/state/core/persistSignalBucket.ts

@@ -1,5 +1,7 @@
+import type { LegacyStorageKey } from './legacyEntries.ts';
 import { isPlainRecord } from './mergeStored.ts';
 import { persistBucket } from './persistBucket.ts';
+import { readStorageText } from './storageEntry.ts';
 
 /**
  * Keep a tree of signals in `localStorage`, under one versioned key.
@@ -19,6 +21,12 @@ import { persistBucket } from './persistBucket.ts';
  * the tracking is always done by the copy of the library that made the
  * signals. A member that is neither a signal nor a plain object is ignored.
  * Never put a `computed()` in a bucket: it cannot be written back.
+ *
+ * With `syncAcrossTabs`, every tab follows the entry: a tab opened before
+ * another one stored its work would otherwise write its stale copy over it. A
+ * write that would store what is already there is skipped, so two tabs cannot
+ * echo each other, and nothing is written while another tab's copy is being
+ * taken on.
  * @param options - See {@link PersistSignalBucketOptions}.
  * @returns The same bucket, rehydrated, so it can be exported directly.
  */
@@ -26,26 +34,51 @@ export function persistSignalBucket<TBucket extends object>(
   options: PersistSignalBucketOptions<TBucket>,
 ): TBucket {
   const { key, version, bucket, effect, onQuotaExceeded } = options;
+  const { legacyKeys, forgetLegacyKeys, syncAcrossTabs = false } = options;
   const stored = persistBucket({
     key,
     version,
     defaults: snapshotBucket(bucket),
     onQuotaExceeded,
+    legacyKeys,
+    forgetLegacyKeys,
   });
 
   const { value, firstRun } = stored.read();
   if (!firstRun) hydrateBucket(bucket, value);
 
   let subscribed = false;
+  let adopting = false;
   effect(() => {
     const snapshot = snapshotBucket(bucket);
     if (!subscribed) {
       subscribed = true;
       return;
     }
+    if (adopting) return;
+    if (
+      syncAcrossTabs !== false &&
+      readStorageText(stored.storageKey) === JSON.stringify(snapshot)
+    ) {
+      return;
+    }
     stored.write(snapshot);
   });
 
+  if (syncAcrossTabs !== false) {
+    stored.subscribe((read) => {
+      if (typeof syncAcrossTabs === 'function' && !syncAcrossTabs(bucket)) {
+        return;
+      }
+      adopting = true;
+      try {
+        hydrateBucket(bucket, read.value);
+      } finally {
+        adopting = false;
+      }
+    });
+  }
+
   return bucket;
 }
 
@@ -77,6 +110,25 @@ export interface PersistSignalBucketOptions<TBucket extends object> {
    * @default undefined
    */
   onQuotaExceeded?: (error: unknown) => void;
+  /**
+   * The entries the bucket was kept under before this key, the preferred one
+   * first; see `persistBucket`.
+   * @default []
+   */
+  legacyKeys?: readonly LegacyStorageKey[];
+  /**
+   * Remove every legacy entry found once it has been read.
+   * @default false
+   */
+  forgetLegacyKeys?: boolean;
+  /**
+   * Take on what another tab stores, and skip a write that would store what is
+   * already there. A function decides each time, handed the bucket as this tab
+   * holds it: a bucket of work in progress keeps its own while it has some,
+   * rather than two tabs overwriting each other in turn.
+   * @default false
+   */
+  syncAcrossTabs?: boolean | ((bucket: TBucket) => boolean);
 }
 
 interface SignalLeaf {

package/src/state/core/storageEntry.ts

@@ -81,6 +81,38 @@ export function removeStorageEntry(storageKey: string): void {
   }
 }
 
+/**
+ * Read one `localStorage` entry as the text it was stored as, so two copies of
+ * a payload can be compared without parsing either.
+ * @param storageKey - The full key.
+ * @returns The stored text, or `null` when there is none or the store cannot
+ * be reached.
+ */
+export function readStorageText(storageKey: string): string | null {
+  try {
+    return globalThis.localStorage?.getItem(storageKey) ?? null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Write one `localStorage` entry as text, exactly as given. Best effort.
+ * @param storageKey - The full key.
+ * @param text - What to store.
+ * @returns Whether the store took it.
+ */
+export function writeStorageText(storageKey: string, text: string): boolean {
+  try {
+    const storage = globalThis.localStorage as Storage | undefined;
+    if (storage === undefined) return false;
+    storage.setItem(storageKey, text);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
 function isQuotaExceeded(error: unknown): boolean {
   if (typeof error !== 'object' || error === null) return false;
   const { name, code } = error as { name?: unknown; code?: unknown };

package/src/structure/ui/StructureExportButton.tsx

@@ -0,0 +1,57 @@
+import type { ReactElement } from 'react';
+import { useState } from 'react';
+
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import { OverlayIconButton } from '../../overlay/ui/OverlayIconButton.tsx';
+
+import { StructureExportDialog } from './StructureExportDialog.tsx';
+import type { StructureExportPanelProps } from './StructureExportPanel.tsx';
+
+/** What {@link StructureExportButton} hands over. */
+export interface StructureExportButtonProps extends StructureExportPanelProps {
+  /**
+   * What the glyph is called, for the pointer and for a screen reader.
+   * @default the chrome's own line, `Copy or save the structure: SMILES,
+   *   molfile`
+   */
+  label?: string;
+  /**
+   * Value of the `data-testid` attribute of the glyph.
+   * @default 'card-structure'
+   */
+  testId?: string;
+}
+
+/**
+ * The glyph beside a figure that hands its one structure over: as a SMILES,
+ * a molfile or an idCode, each copied with a click, or as a picture — the
+ * export dialog, the one the chat opens on its own molecule cards. It is drawn
+ * like the figure's other glyphs, so it sits in the `tools` of a `CardFigure`
+ * or of any overlay bar.
+ * @param props - The structure, the name of its files, and the glyph's name.
+ * @returns The glyph; the dialog is drawn over the page while it is open.
+ */
+export function StructureExportButton(
+  props: StructureExportButtonProps,
+): ReactElement {
+  const { label, testId = 'card-structure', ...structure } = props;
+  const t = useChromeT();
+  const [isOpen, setIsOpen] = useState(false);
+  return (
+    <>
+      <OverlayIconButton
+        icon="export"
+        label={label ?? t('structure.export.glyph')}
+        active={isOpen}
+        opensMenu
+        testId={testId}
+        onClick={() => setIsOpen(true)}
+      />
+      <StructureExportDialog
+        {...structure}
+        isOpen={isOpen}
+        onClose={() => setIsOpen(false)}
+      />
+    </>
+  );
+}

package/src/structure/ui/index.ts

@@ -25,6 +25,10 @@ export type { StructureEditorHelpProps } from './StructureEditorHelp.tsx';
 export { StructureEditorHelp } from './StructureEditorHelp.tsx';
 export type { StructureExportDialogProps } from './StructureExportDialog.tsx';
 export { StructureExportDialog } from './StructureExportDialog.tsx';
+export type { StructureExportButtonProps } from './StructureExportButton.tsx';
+export { StructureExportButton } from './StructureExportButton.tsx';
 export type { StructureExportPanelProps } from './StructureExportPanel.tsx';
 export type { ToolbarFloorOptions } from './useToolbarFloor.ts';
 export { useToolbarFloor } from './useToolbarFloor.ts';
+export type { StructureDraft } from './useStructureDraft.ts';
+export { useStructureDraft } from './useStructureDraft.ts';

package/src/structure/ui/useStructureDraft.ts

@@ -0,0 +1,47 @@
+import { useCallback, useState } from 'react';
+
+/** What a structure editor is drawing, and how a page reloads it. */
+export interface StructureDraft<TValue> {
+  /** What the canvas holds: the structure last loaded or last drawn. */
+  value: TValue;
+  /**
+   * What `StructureEditor` takes as `revision`: it reloads `value` into the
+   * canvas each time this changes, and only then.
+   */
+  revision: number;
+  /**
+   * Put a structure in the canvas, replacing what is drawn: an example, the
+   * query a dialog is opened on, a Clear button loading the empty string.
+   * @param value - The structure, as the editor's `inputFormat` reads it.
+   */
+  load: (value: TValue) => void;
+  /**
+   * Keep what the editor drew, without reloading the canvas: what its
+   * `onChange` hands over. The same value twice changes nothing.
+   * @param value - The structure the editor reports.
+   */
+  update: (value: TValue) => void;
+}
+
+/**
+ * The draft a `StructureEditor` is fed: what it draws, and the revision that
+ * makes it reload. The editor is uncontrolled, so feeding every stroke back
+ * into it would replace the structure under the pen; this keeps the drawing
+ * out of the canvas until the page means to load one.
+ * @param initial - What the canvas opens on.
+ * @returns The draft, and the two ways to change it.
+ */
+export function useStructureDraft<TValue = string>(
+  initial: TValue,
+): StructureDraft<TValue> {
+  const [draft, setDraft] = useState({ value: initial, revision: 0 });
+  const load = useCallback((value: TValue) => {
+    setDraft((previous) => ({ value, revision: previous.revision + 1 }));
+  }, []);
+  const update = useCallback((value: TValue) => {
+    setDraft((previous) =>
+      Object.is(previous.value, value) ? previous : { ...previous, value },
+    );
+  }, []);
+  return { value: draft.value, revision: draft.revision, load, update };
+}

package/src/ui.ts

@@ -27,12 +27,14 @@ export * from './parallel/ui/index.ts';
 export * from './pedagogy/ui/index.ts';
 export * from './periodic/ui/index.ts';
 export * from './projection/ui/index.ts';
+export * from './property/ui/index.ts';
 export * from './range/ui/index.ts';
 export * from './router/ui/index.ts';
 export * from './scatter/ui/index.ts';
 export * from './scatter3d/ui/index.ts';
 export * from './share/ui/index.ts';
 export * from './shared/ui/index.ts';
+export * from './shell/ui/index.ts';
 export * from './split/ui/index.ts';
 export * from './taxonomy/ui/index.ts';
 // The conformer table, from the structure module's file rather than its

package/src/worker/core/index.ts

@@ -18,6 +18,7 @@ export { createWorkerChannel } from './workerChannel.ts';
 export type {
   WorkerChannel,
   WorkerChannelOptions,
+  WorkerFailure,
   WorkerJobContext,
   WorkerRequestOptions,
   WorkerSchedule,

package/src/worker/core/messages.ts

@@ -27,12 +27,13 @@ export interface WorkerProgressMessage<TProgress> {
 
 /**
  * What a worker posts once a job is over. An `Error` does not survive the
- * boundary, so a failure travels as its message and becomes an `Error` again
- * on this side.
+ * boundary, so a failure travels as its message — plus, when the worker was
+ * told how, a `detail` the page reads to say it in its own words — and becomes
+ * an `Error` again on this side.
  */
 export type WorkerResponseMessage<TResponse> =
   | { id: number; ok: true; response: TResponse }
-  | { id: number; ok: false; message: string };
+  | { id: number; ok: false; message: string; detail?: unknown };
 
 /**
  * As much of a `Worker` as a channel uses. A real `Worker` satisfies it, and so

package/src/worker/core/oclResourcesUrl.ts

@@ -0,0 +1,21 @@
+/** The file OpenChemLib's static resources are served as, at the site's root. */
+export const OCL_RESOURCES_FILE = 'openchemlib-resources.json';
+
+/**
+ * Where OpenChemLib's static resources sit, as this page is mounted.
+ *
+ * A worker fetches them, but a worker has no `document` and so cannot read the
+ * `<base>` the page carries, and its own script address is no help either: it
+ * sits under `assets/` in the build and under `src/` in development. So the
+ * page resolves the address and posts it with the job — the argument
+ * `registerResources` needs in a worker.
+ * @param file - The file, relative to the site's own root.
+ * @returns The absolute address, or `undefined` outside a page, where
+ * `registerResources` reads the file from the installed package instead.
+ */
+export function oclResourcesUrl(
+  file: string = OCL_RESOURCES_FILE,
+): string | undefined {
+  const baseUri = globalThis.document?.baseURI;
+  return baseUri ? new URL(file, baseUri).href : undefined;
+}

package/src/worker/core/serveWorkerRequests.ts

@@ -37,6 +37,14 @@ export interface ServeWorkerRequestsOptions<TRequest, TResponse> {
    * @default undefined — every answer is copied
    */
   transfer?: (response: TResponse) => Transferable[];
+  /**
+   * What a failed answer carries besides its message, for the page's channel
+   * to word the failure in its own language — the key of a translatable
+   * message and its values, say. It must survive being posted; answering
+   * `undefined` adds nothing.
+   * @default undefined — a failure carries its message alone
+   */
+  detail?: (error: unknown) => unknown;
 }
 
 /**
@@ -59,7 +67,7 @@ export function serveWorkerRequests<TRequest, TResponse, TProgress = never>(
   ) => TResponse | Promise<TResponse>,
   options: ServeWorkerRequestsOptions<TRequest, TResponse> = {},
 ): boolean {
-  const { accepts, transfer } = options;
+  const { accepts, transfer, detail } = options;
   const scope = options.scope ?? dedicatedWorkerScope();
   if (scope === undefined) return false;
   const running = new Map<number, AbortController>();
@@ -99,7 +107,15 @@ export function serveWorkerRequests<TRequest, TResponse, TProgress = never>(
           answer(scope, { id, ok: true, response }, transfer);
         },
         (error: unknown) => {
-          answer(scope, { id, ok: false, message: errorMessage(error) });
+          const message = errorMessage(error);
+          const extra =
+            detail === undefined ? undefined : describe(detail, error);
+          answer(
+            scope,
+            extra === undefined
+              ? { id, ok: false, message }
+              : { id, ok: false, message, detail: extra },
+          );
         },
       )
       .finally(() => {
@@ -127,6 +143,18 @@ function answer<TResponse>(
   }
 }
 
+function describe(
+  detail: (error: unknown) => unknown,
+  error: unknown,
+): unknown {
+  try {
+    return detail(error);
+  } catch {
+    // A detail that cannot be worked out leaves the message to say it all.
+    return undefined;
+  }
+}
+
 function dedicatedWorkerScope(): WorkerScopeLike | undefined {
   const candidate = globalThis as {
     postMessage?: unknown;

package/src/worker/core/workerChannel.ts

@@ -1,7 +1,7 @@
 import { toError } from '../../error/core/toError.ts';
 
 import { CancelledRequestError, RequestTimeoutError } from './errors.ts';
-import type { WorkerLike, WorkerRequestMessage } from './messages.ts';
+import type { WorkerRequestMessage } from './messages.ts';
 import type {
   Outcome,
   PendingRequest,
@@ -12,7 +12,6 @@ import {
   positiveMilliseconds,
   postCancel,
   runJobInProcess,
-  subscribeToWorker,
   watchRequest,
 } from './workerChannelParts.ts';
 import type {
@@ -21,6 +20,7 @@ import type {
   WorkerRequestOptions,
   WorkerSource,
 } from './workerChannelTypes.ts';
+import { createWorkerSlot } from './workerSlot.ts';
 
 /**
  * Turn a worker into something a page can await.
@@ -30,10 +30,9 @@ import type {
  * — cancelled, superseded, timed out, or failed — drops out of the pending map
  * at that moment. The worker may post progress about a job while it runs.
  *
- * Handed a worker, the channel posts to it and terminates it when asked, but
- * never creates one. Handed a function, it creates the worker on the first
- * request, replaces one that failed or was terminated, and can fall back to an
- * in-process run where there is no `Worker`.
+ * Handed a worker, the channel posts to it and terminates it when asked. Handed
+ * a function, it creates the worker when needed and can run the job in-process
+ * instead; see `createWorkerSlot`.
  * @param source - The worker, or the function that creates it.
  * @param options - See {@link WorkerChannelOptions}.
  * @returns The channel.
@@ -43,38 +42,44 @@ export function createWorkerChannel<TRequest, TResponse, TProgress = never>(
   source: WorkerSource,
   options: WorkerChannelOptions<TRequest, TResponse, TProgress> = {},
 ): WorkerChannel<TRequest, TResponse, TProgress> {
-  const {
-    name = 'worker',
-    schedule = 'parallel',
-    cooperativeCancel = false,
-    defaultTimeoutMs,
-    runInProcess,
-  } = options;
+  const { name = 'worker', schedule = 'parallel' } = options;
+  const { cooperativeCancel = false, retryAfterWorkerFailure } = options;
+  const { defaultTimeoutMs, runInProcess, failure } = options;
   const fallbackTimeoutMs = positiveMilliseconds(
     defaultTimeoutMs,
     DEFAULT_TIMEOUT_MS,
   );
-  const factory = typeof source === 'function' ? source : undefined;
-  if (schedule === 'restart' && factory === undefined) {
+  if (schedule === 'restart' && typeof source !== 'function') {
     throw new Error(`${name}: the restart schedule needs a worker factory`);
   }
-  const hasNoWorker = !('Worker' in globalThis);
-  const runLocally = factory && hasNoWorker ? runInProcess : undefined;
+  const retries = typeof source === 'function' && retryAfterWorkerFailure;
 
   const pending = new Map<number, PendingRequest<TResponse, TProgress>>();
-  let worker: WorkerLike | null = null;
+  const posted = new Map<number, QueuedRequest<TRequest>>();
+  const retried = new Set<number>();
   let closed = false;
   let nextId = 0;
   let activeId: number | null = null;
   let queued: QueuedRequest<TRequest> | null = null;
-  if (typeof source !== 'function') {
-    worker = source;
-    listen(source);
-  }
+  const slot = createWorkerSlot<TRequest, TResponse, TProgress>(source, {
+    name,
+    runInProcess,
+    failure,
+    isWaited: (id) => pending.has(id),
+    report: {
+      progress: (id, progress) => {
+        pending.get(id)?.onProgress?.(progress as TProgress);
+      },
+      answer: (id, outcome) => complete(id, outcome),
+      failure: (error) => workerFailed(error),
+    },
+  });
 
   function take(id: number): PendingRequest<TResponse, TProgress> | undefined {
     const entry = pending.get(id);
     pending.delete(id);
+    posted.delete(id);
+    retried.delete(id);
     entry?.dispose();
     return entry;
   }
@@ -93,7 +98,7 @@ export function createWorkerChannel<TRequest, TResponse, TProgress = never>(
     const entry = take(id);
     if (entry === undefined) return false;
     entry.controller?.abort();
-    if (cooperativeCancel && entry.dispatched) postCancel(worker, id);
+    if (cooperativeCancel && entry.dispatched) postCancel(slot.current, id);
     entry.reject(error);
     return true;
   }
@@ -106,22 +111,18 @@ export function createWorkerChannel<TRequest, TResponse, TProgress = never>(
   }
 
   function rejectAll(error: Error): void {
-    for (const entry of pending.values()) {
-      entry.dispose();
+    for (const [id, entry] of pending) {
+      take(id);
       entry.controller?.abort();
       entry.reject(error);
     }
-    pending.clear();
     activeId = null;
     queued = null;
   }
 
   function abandonActive(): void {
     activeId = null;
-    if (factory !== undefined && worker !== null) {
-      worker.terminate();
-      worker = null;
-    }
+    slot.abandon();
   }
 
   function startQueued(): void {
@@ -135,55 +136,55 @@ export function createWorkerChannel<TRequest, TResponse, TProgress = never>(
     if (entry === undefined) return;
     entry.dispatched = true;
     if (schedule !== 'parallel') activeId = id;
-    if (runLocally !== undefined) {
-      entry.controller = runJobInProcess(
-        runLocally,
-        payload,
-        (progress) => pending.get(id)?.onProgress?.(progress),
-        (outcome) => complete(id, outcome),
-      );
-      return;
-    }
-    const message: WorkerRequestMessage<TRequest> = { id, request: payload };
     try {
-      const target = currentWorker();
-      if (transfer === undefined) target.postMessage(message);
-      else target.postMessage(message, transfer);
+      const target = slot.acquire();
+      if (target !== null) {
+        if (retries && transfer === undefined) {
+          posted.set(id, { id, payload, transfer });
+        }
+        const message: WorkerRequestMessage<TRequest> = {
+          id,
+          request: payload,
+        };
+        if (transfer === undefined) target.postMessage(message);
+        else target.postMessage(message, transfer);
+        return;
+      }
     } catch (error) {
       complete(id, { ok: false, error: toError(error) });
+      return;
     }
+    entry.controller = runJobInProcess(
+      slot.runLocally,
+      payload,
+      (progress) => pending.get(id)?.onProgress?.(progress),
+      (outcome) => complete(id, outcomeOf(outcome)),
+    );
   }
 
-  function currentWorker(): WorkerLike {
-    if (worker === null) {
-      if (factory === undefined) {
-        throw new CancelledRequestError(`${name} was terminated`);
-      }
-      worker = factory();
-      listen(worker);
-    }
-    return worker;
+  function outcomeOf(outcome: Outcome<TResponse>): Outcome<TResponse> {
+    return outcome.ok
+      ? outcome
+      : { ok: false, error: slot.jobFailed(outcome.error) };
   }
 
-  function listen(target: WorkerLike): void {
-    subscribeToWorker(target, {
-      progress: (id, progress) => {
-        if (target !== worker) return;
-        pending.get(id)?.onProgress?.(progress as TProgress);
-      },
-      answer: (id, outcome) => {
-        if (target === worker) complete(id, outcome as Outcome<TResponse>);
-      },
-      failure: (detail) => {
-        if (target !== worker) return;
-        if (factory !== undefined) {
-          target.terminate();
-          worker = null;
-        }
-        const suffix = detail === '' ? '' : `: ${detail}`;
-        rejectAll(new Error(`${name} failed${suffix}`));
-      },
-    });
+  function workerFailed(error: Error): void {
+    if (!retries) {
+      rejectAll(error);
+      return;
+    }
+    activeId = null;
+    for (const [id, entry] of pending) {
+      if (!entry.dispatched) continue;
+      const job = posted.get(id);
+      if (job === undefined || retried.has(id)) {
+        drop(id, error);
+        continue;
+      }
+      retried.add(id);
+      dispatch(id, job.payload);
+    }
+    if (activeId === null) startQueued();
   }
 
   function expire(id: number, budget: number): void {
@@ -242,9 +243,8 @@ export function createWorkerChannel<TRequest, TResponse, TProgress = never>(
     cancel: () => dropAll('was cancelled'),
     terminate: () => {
       rejectAll(new CancelledRequestError(`${name} was terminated`));
-      worker?.terminate();
-      if (factory === undefined) closed = true;
-      else worker = null;
+      slot.terminate();
+      if (!slot.hasFactory) closed = true;
     },
   };
 }