react-cheminfo 0.3.0 → 0.4.0

package/src/worker/core/messages.ts

@@ -0,0 +1,47 @@
+/** What a channel posts to its worker: one job, tagged with an identifier. */
+export interface WorkerRequestMessage<TRequest> {
+  /** Serial number of the request, which the answer must echo. */
+  id: number;
+  /** The job itself, exactly as the caller wrote it. */
+  request: TRequest;
+}
+
+/**
+ * What a worker posts back. An `Error` does not survive the boundary, so a
+ * failure travels as its message and becomes an `Error` again on this side.
+ */
+export type WorkerResponseMessage<TResponse> =
+  | { id: number; ok: true; response: TResponse }
+  | { id: number; ok: false; message: string };
+
+/**
+ * As much of a `Worker` as a channel uses. A real `Worker` satisfies it, and so
+ * does anything else that speaks the same three calls — which is what lets the
+ * scheduling be unit-tested without a thread.
+ */
+export interface WorkerLike {
+  /** Send one message to the worker. */
+  postMessage(message: unknown): void;
+  /** Listen to what the worker answers, or to its failing outright. */
+  addEventListener(
+    type: 'message' | 'error',
+    listener: (event: WorkerEventLike) => void,
+  ): void;
+  /** Stop the worker; whatever it was doing is lost. */
+  terminate(): void;
+}
+
+/** As much of a worker event as a channel reads. */
+export interface WorkerEventLike {
+  /**
+   * The message the worker posted, before anything checks it against the
+   * protocol. Absent on an error event.
+   * @default undefined
+   */
+  readonly data?: unknown;
+  /**
+   * What went wrong, on an error event. Absent on a message event.
+   * @default undefined
+   */
+  readonly message?: string;
+}

package/src/worker/core/workerChannel.ts

@@ -0,0 +1,218 @@
+import { CancelledRequestError, RequestTimeoutError } from './errors.ts';
+import type {
+  WorkerLike,
+  WorkerRequestMessage,
+  WorkerResponseMessage,
+} from './messages.ts';
+
+/**
+ * Turn a worker into something a page can await.
+ *
+ * Several requests may be in flight at once; each one is tagged with an
+ * identifier the answer echoes, so replies are matched to callers whatever
+ * order they arrive in. A request that rejects — cancelled, timed out, or
+ * failed — drops out of the pending map at that moment, so a page that fires
+ * one job per keystroke never accumulates them.
+ *
+ * The worker is the caller's: the channel posts to it and terminates it when
+ * asked, but never creates one, which is what lets a site keep its own lazy
+ * construction and its own in-process fallback.
+ * @param worker - The worker to talk to, or anything that speaks its three calls.
+ * @param options - See {@link WorkerChannelOptions}.
+ * @returns The channel.
+ */
+export function createWorkerChannel<TRequest, TResponse>(
+  worker: WorkerLike,
+  options: WorkerChannelOptions = {},
+): WorkerChannel<TRequest, TResponse> {
+  const name = options.name ?? 'worker';
+  const defaultTimeoutMs = positiveMilliseconds(
+    options.defaultTimeoutMs,
+    DEFAULT_TIMEOUT_MS,
+  );
+
+  const pending = new Map<number, PendingRequest<TResponse>>();
+  let nextId = 0;
+  let terminated = false;
+
+  function settle(id: number): PendingRequest<TResponse> | undefined {
+    const entry = pending.get(id);
+    if (entry === undefined) return undefined;
+    pending.delete(id);
+    entry.dispose();
+    return entry;
+  }
+
+  function rejectAll(error: Error): void {
+    for (const entry of pending.values()) {
+      entry.dispose();
+      entry.reject(error);
+    }
+    pending.clear();
+  }
+
+  worker.addEventListener('message', (event) => {
+    const message = event.data;
+    if (!isResponseMessage(message)) return;
+    const entry = settle(message.id);
+    if (entry === undefined) return;
+    if (message.ok) entry.resolve(message.response as TResponse);
+    else entry.reject(new Error(message.message));
+  });
+
+  worker.addEventListener('error', (event) => {
+    const detail = event.message ?? '';
+    rejectAll(
+      new Error(detail === '' ? `${name} failed` : `${name} failed: ${detail}`),
+    );
+  });
+
+  return {
+    get pendingCount() {
+      return pending.size;
+    },
+    request: (payload: TRequest, requestOptions: WorkerRequestOptions = {}) => {
+      const { signal, timeoutMs } = requestOptions;
+      if (terminated) {
+        return Promise.reject(
+          new CancelledRequestError(`${name} was terminated`),
+        );
+      }
+      if (signal?.aborted === true) {
+        return Promise.reject(
+          new CancelledRequestError(`${name} request was cancelled`),
+        );
+      }
+
+      nextId += 1;
+      const id = nextId;
+      const budget = positiveMilliseconds(timeoutMs, defaultTimeoutMs);
+
+      return new Promise<TResponse>((resolve, reject) => {
+        const timeout = setTimeout(() => {
+          settle(id)?.reject(
+            new RequestTimeoutError(
+              `${name} request ${id} timed out after ${budget} ms`,
+            ),
+          );
+        }, budget);
+        const onAbort = () => {
+          settle(id)?.reject(
+            new CancelledRequestError(`${name} request ${id} was cancelled`),
+          );
+        };
+        signal?.addEventListener('abort', onAbort);
+
+        pending.set(id, {
+          resolve,
+          reject,
+          dispose: () => {
+            clearTimeout(timeout);
+            signal?.removeEventListener('abort', onAbort);
+          },
+        });
+
+        const message: WorkerRequestMessage<TRequest> = {
+          id,
+          request: payload,
+        };
+        try {
+          worker.postMessage(message);
+        } catch (error) {
+          settle(id);
+          reject(error instanceof Error ? error : new Error(String(error)));
+        }
+      });
+    },
+    terminate: () => {
+      terminated = true;
+      rejectAll(new CancelledRequestError(`${name} was terminated`));
+      worker.terminate();
+    },
+  };
+}
+
+/** How a channel names itself and how long it waits. */
+export interface WorkerChannelOptions {
+  /**
+   * What the channel is called in the message of an error it raises, e.g.
+   * `conformers`.
+   * @default 'worker'
+   */
+  name?: string;
+  /**
+   * Milliseconds a request waits before it is given up on, when the call passes
+   * no budget of its own. A value that is not a positive finite number falls
+   * back to two minutes.
+   * @default 120000
+   */
+  defaultTimeoutMs?: number;
+}
+
+/** What one call may ask of the channel. */
+export interface WorkerRequestOptions {
+  /**
+   * Abort the call. Its promise then rejects with a
+   * {@link CancelledRequestError}; the worker itself is left alone, since a job
+   * already running cannot be interrupted from outside.
+   * @default undefined
+   */
+  signal?: AbortSignal;
+  /**
+   * Milliseconds this call alone waits, overriding the channel default —
+   * a calculation budget is often a user preference. A value that is not a
+   * positive finite number falls back to the channel default.
+   * @default the channel's defaultTimeoutMs
+   */
+  timeoutMs?: number;
+}
+
+/** A channel to one worker, over which several jobs may be in flight. */
+export interface WorkerChannel<TRequest, TResponse> {
+  /**
+   * Post one job and wait for the answer that carries its identifier.
+   * @param payload - The job.
+   * @param options - Per-call signal and budget.
+   * @returns What the worker answered.
+   */
+  request: (
+    payload: TRequest,
+    options?: WorkerRequestOptions,
+  ) => Promise<TResponse>;
+  /** How many requests are still waiting for an answer. */
+  readonly pendingCount: number;
+  /**
+   * Terminate the worker, rejecting everything still waiting with a
+   * {@link CancelledRequestError}. The channel accepts no further request.
+   */
+  terminate: () => void;
+}
+
+interface PendingRequest<TResponse> {
+  resolve: (response: TResponse) => void;
+  reject: (error: Error) => void;
+  dispose: () => void;
+}
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+
+function isResponseMessage(
+  message: unknown,
+): message is WorkerResponseMessage<unknown> {
+  if (typeof message !== 'object' || message === null) return false;
+  const candidate = message as {
+    id?: unknown;
+    ok?: unknown;
+    message?: unknown;
+  };
+  if (typeof candidate.id !== 'number' || typeof candidate.ok !== 'boolean') {
+    return false;
+  }
+  return candidate.ok || typeof candidate.message === 'string';
+}
+
+function positiveMilliseconds(value: number | undefined, fallback: number) {
+  return typeof value === 'number' && Number.isFinite(value) && value > 0
+    ? value
+    : fallback;
+}

package/styles/chrome.css

@@ -0,0 +1,223 @@
+/*
+ * The chrome every *.cheminfo.org site carries: the neutrals, the geometry and
+ * the type the family shares, then the bar, the menu and the footer drawn from
+ * them. A site imports this once and adds only the two colours it owns —
+ * `--brand`, `--brand-alt`, the readable `--brand-alt-text` when the second one
+ * is too light for text, and `--accent: var(--brand)`.
+ *
+ * The page background, the box-sizing reset and the focus policy stay with the
+ * site: a rule shipped from a package cannot be relied on to lose the cascade
+ * against the page importing it.
+ */
+
+:root {
+  /* The neutrals, the geometry and the depth are identical on every site of
+     the family, so two of them opened side by side read as one house. */
+  --surface: #ffffff;
+  --surface-sunken: #f5f7fa;
+  --surface-raised: #ffffff;
+  --border: #dfe3e8;
+  --border-strong: #c3cad3;
+  --text: #16202c;
+  --text-muted: #5b6875;
+  --text-faint: #8a96a3;
+
+  --radius: 10px;
+  --radius-lg: 16px;
+  --shadow-sm: 0 1px 2px rgb(16 32 48 / 8%);
+  --shadow-md: 0 4px 14px rgb(16 32 48 / 10%);
+  --shadow-lg: 0 12px 32px rgb(16 32 48 / 16%);
+
+  --header-height: 3.5rem;
+  --page-max: 84rem;
+}
+
+/* The size goes on `body`, never on `html`: `rem` has to stay the browser's
+   16px, or every measurement written here shrinks by 6.25% and the bar renders
+   52.5px tall on one site and 56px on its sibling. */
+body {
+  font-family:
+    -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Helvetica, Arial,
+    sans-serif;
+  font-size: 15px;
+  line-height: 1.5;
+  -webkit-font-smoothing: antialiased;
+}
+
+/* A form control does not inherit the page font: it would otherwise be set in
+   the UA's Helvetica beside text in ours. */
+input,
+textarea,
+select,
+button {
+  font-family: inherit;
+}
+
+/* ── The bar ─────────────────────────────────────────────────────────────── */
+
+.app-header {
+  position: sticky;
+  z-index: 20;
+  top: 0;
+  flex: none;
+  border-bottom: 1px solid var(--border);
+  background: var(--surface);
+}
+
+.app-header__inner {
+  display: flex;
+  height: var(--header-height);
+  max-width: var(--page-max);
+  align-items: center;
+  padding: 0 1.25rem;
+  margin: 0 auto;
+  gap: 1rem;
+}
+
+.brand {
+  display: flex;
+  align-items: center;
+  color: var(--text);
+  font-weight: 700;
+  gap: 0.55rem;
+  text-decoration: none;
+}
+
+.brand:hover {
+  color: var(--text);
+  text-decoration: none;
+}
+
+.brand-mark {
+  display: block;
+  flex: none;
+}
+
+.wordmark {
+  font-size: 1.0625rem;
+  letter-spacing: -0.01em;
+  white-space: nowrap;
+}
+
+.wordmark__lead {
+  color: var(--brand);
+}
+
+/* Neutral, so the two coloured halves read as the name rather than as three
+   equal parts. */
+.wordmark__dot {
+  color: var(--text-faint);
+}
+
+/* The answering colour of several sites is an amber or a yellow sitting around
+   2:1 on white, so the name takes the darkened form wherever there is one. */
+.wordmark__alt {
+  color: var(--brand-alt-text, var(--brand-alt));
+}
+
+/* The pages start at the brand and scroll on a narrow window rather than
+   pushing the utilities off the edge. */
+.app-header-nav {
+  display: flex;
+  flex: 1 1 auto;
+  min-width: 0;
+  align-items: center;
+  justify-content: flex-start;
+  overflow-x: auto;
+  overflow-y: hidden;
+  gap: 0.15rem;
+  scrollbar-width: thin;
+}
+
+/* The utilities keep the right edge, and never scroll with the pages. */
+.app-header-actions {
+  display: flex;
+  flex: 0 0 auto;
+  align-items: center;
+  gap: 0.15rem;
+}
+
+/* Only needed when the pages do not grow — a bar with no page links at all. */
+.spacer {
+  flex: 1;
+}
+
+/* Carried by a link and by a button alike, so the whole row reads as one menu
+   rather than as a button dropped among addresses. */
+.nav-link {
+  display: inline-flex;
+  align-items: center;
+  padding: 0.4rem 0.7rem;
+  border: 0;
+  border-radius: 8px;
+  background: none;
+  color: var(--text-muted);
+  font-size: 0.875rem;
+  font-weight: 600;
+  white-space: nowrap;
+  gap: 0.4rem;
+  cursor: pointer;
+  text-decoration: none;
+}
+
+.nav-link:hover {
+  background: var(--surface-sunken);
+  color: var(--text);
+  text-decoration: none;
+}
+
+/* The brand tint is what says "you are here", so hovering never impersonates
+   the page you are on. */
+.nav-link--active,
+.nav-link--active:hover {
+  background: color-mix(in oklab, var(--accent) 12%, white);
+  color: var(--accent);
+}
+
+.nav-link svg {
+  width: 14px;
+  height: 14px;
+}
+
+/* The Cite and Tools buttons arrive already dressed as bar items, so only their
+   type is brought to the one the links beside them are set in. */
+.citation-button .bp6-button,
+.ecosystem-button .bp6-button {
+  padding: 0.4rem 0.7rem;
+  border-radius: 8px;
+  color: var(--text-muted);
+  font-size: 0.875rem;
+  font-weight: 600;
+}
+
+/* The brand marks the current entry of a header menu too, not Blueprint's own
+   blue. */
+.nav-menu .bp6-menu-item.bp6-active,
+.nav-menu .bp6-menu-item.bp6-active:hover {
+  background: color-mix(in oklab, var(--accent) 12%, white);
+  color: var(--accent);
+}
+
+/* ── The footer ──────────────────────────────────────────────────────────── */
+
+/* The family, in the page rather than only behind the Tools button: this is
+   what lets a crawler — and a reader — walk from one of our tools to the next. */
+.app-footer {
+  border-top: 1px solid var(--border);
+  background: var(--surface);
+}
+
+.app-footer__inner {
+  max-width: var(--page-max);
+  padding: 1.25rem;
+  margin: 0 auto;
+}
+
+/* ── Printing ────────────────────────────────────────────────────────────── */
+
+/* Students print the cheatsheet. Let them, without the chrome. */
+@media print {
+  .no-print {
+    display: none !important;
+  }
+}