react-cheminfo 0.75.0 → 0.77.0

package/src/osiris/ui/PropertyRows.tsx

@@ -0,0 +1,92 @@
+/**
+ * The ten predicted numbers, one row each: a name, a bar and a value.
+ *
+ * The order is the legacy panel's — cLogP, solubility, molweight, TPSA,
+ * drug-likeness, the two hydrogen-bond counts, stereocentres, rotatable bonds,
+ * drug score — and it is `PROPERTY_KEYS`, which the comparison table's columns
+ * and the plot's default axes also read. A reader who learned the panel reads
+ * the table without relearning it.
+ *
+ * A value the predictor could not answer prints the missing marker and draws no
+ * bar. It is never zero: `DrugScoreCalculator` consumes every sentinel and
+ * hands back a plausible number, so a bar drawn from one would be a wrong
+ * answer with nothing saying it is wrong.
+ */
+
+import type { ReactElement } from 'react';
+
+import { MISSING_VALUE } from '../../format/core/missing.ts';
+import { formatDecimal } from '../../format/core/numbers.ts';
+import { barGeometry } from '../core/barGeometry.ts';
+import type { PropertyKey } from '../core/propertyKeys.ts';
+import { PROPERTY_KEYS, propertyValue } from '../core/propertyKeys.ts';
+import { propertyScale } from '../core/scales.ts';
+import type { OsirisProperties } from '../core/types.ts';
+
+import { PropertyBar } from './PropertyBar.tsx';
+
+/** What {@link PropertyRows} needs. */
+export interface PropertyRowsProps {
+  /**
+   * What was predicted, or `null` while the molecule is still being worked on —
+   * in which case every row stands with its name and no value, so nothing moves
+   * when the answer arrives.
+   * @default null
+   */
+  properties?: OsirisProperties | null;
+  /**
+   * The rows to draw. They are drawn in the panel's order whatever order they
+   * are given in, so a narrowed panel still reads as the whole one does.
+   * @default PROPERTY_KEYS
+   */
+  keys?: readonly PropertyKey[];
+}
+
+/**
+ * The property rows, all ten unless fewer are asked, in the panel's order.
+ * @param props - See {@link PropertyRowsProps}.
+ * @returns One row per property.
+ */
+export function PropertyRows(props: PropertyRowsProps): ReactElement {
+  const { properties = null, keys = PROPERTY_KEYS } = props;
+
+  return (
+    <div className="property-rows">
+      {PROPERTY_KEYS.filter((key) => keys.includes(key)).map((key) => (
+        <PropertyRow
+          key={key}
+          propertyKey={key}
+          value={properties === null ? null : propertyValue(properties, key)}
+        />
+      ))}
+    </div>
+  );
+}
+
+interface PropertyRowProps {
+  propertyKey: PropertyKey;
+  value: number | null;
+}
+
+function PropertyRow(props: PropertyRowProps): ReactElement {
+  const { propertyKey, value } = props;
+  const scale = propertyScale(propertyKey);
+  const geometry = barGeometry(propertyKey, value);
+
+  return (
+    <div className="property-row">
+      <span className="property-row__label">
+        {scale.label}
+        {scale.unit === '' ? null : (
+          <span className="property-row__unit">{scale.unit}</span>
+        )}
+      </span>
+      <span className="property-row__bar">
+        {geometry === null ? null : <PropertyBar geometry={geometry} />}
+      </span>
+      <span className="property-row__value">
+        {value === null ? MISSING_VALUE : formatDecimal(value, scale.decimals)}
+      </span>
+    </div>
+  );
+}

package/src/osiris/ui/RiskFindings.tsx

@@ -0,0 +1,137 @@
+/**
+ * Why one risk came back as it did.
+ *
+ * Two branches of the predictor reach the same red square and mean different
+ * things. *This molecule is known to be mutagenic* means the compound's own
+ * idCode is in a list derived from RTECS — data on this exact compound, and
+ * nothing on the drawing to point at. *High-risk fragments indicating
+ * Mutagenicity* means a substructure matched, and that substructure is drawn
+ * beside the molecule with its atoms painted on it.
+ *
+ * Telling them apart is the whole point of opening a square: aspirin, caffeine
+ * and paracetamol are all red through the first branch, and highlighting the
+ * whole molecule there would call the compound its own toxicophore.
+ *
+ * A fragment heading is repeated on each of the fragments under it, so it is
+ * printed once and the matches follow.
+ */
+
+import { Callout, Spinner } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+
+import { Structure } from '../../structure/ui/Structure.tsx';
+import { RISK_LABELS } from '../core/constants.ts';
+import { KNOWN_MOLECULE_NOTE } from '../core/riskAppearance.ts';
+import type { RiskDetail, RiskFinding, RiskType } from '../core/types.ts';
+
+/** What {@link RiskFindings} needs. */
+export interface RiskFindingsProps {
+  /** Which risk is open. */
+  risk: RiskType;
+  /** The molecule it was assessed on: the idCode, with its coordinates after a space. */
+  structure: string;
+  /**
+   * What the predictor found, or `null` while it is being worked out.
+   * @default null
+   */
+  detail?: RiskDetail | null;
+  /**
+   * Why the explanation could not be fetched, or `null`.
+   * @default null
+   */
+  error?: string | null;
+}
+
+/** How big a drawing in the explanation is, in pixels. */
+const DRAWING = { width: 190, height: 130 };
+
+/**
+ * The explanation of one risk.
+ * @param props - See {@link RiskFindingsProps}.
+ * @returns The predictor's own sentences, with every matched fragment drawn.
+ */
+export function RiskFindings(props: RiskFindingsProps): ReactElement {
+  const { risk, structure, detail = null, error = null } = props;
+
+  if (error !== null) {
+    return <Callout intent="warning">{error}</Callout>;
+  }
+  if (detail === null) {
+    return (
+      // A div, not a paragraph: the spinner draws a div of its own.
+      <div className="osiris-note osiris-note--working">
+        <Spinner size={14} /> Working out why {RISK_LABELS[risk]} came back as
+        it did.
+      </div>
+    );
+  }
+
+  return (
+    <div className="risk-findings">
+      {detail.findings.map((finding, index) => (
+        <Finding
+          // The predictor prints each heading once and each matching fragment
+          // once under it, so the pair names the line without an index.
+          key={`${finding.kind}:${finding.description}:${finding.idCode ?? ''}`}
+          finding={finding}
+          structure={structure}
+          heading={
+            detail.findings[index - 1]?.description === finding.description
+              ? null
+              : finding.description
+          }
+        />
+      ))}
+    </div>
+  );
+}
+
+interface FindingProps {
+  finding: RiskFinding;
+  structure: string;
+  heading: string | null;
+}
+
+function Finding(props: FindingProps): ReactElement {
+  const { finding, structure, heading } = props;
+
+  return (
+    <div className="risk-finding">
+      {heading === null ? null : (
+        <p className="risk-finding__heading">{heading}</p>
+      )}
+      {finding.kind === 'known' ? (
+        <p className="osiris-note">{KNOWN_MOLECULE_NOTE}</p>
+      ) : null}
+      {finding.idCode === null ? null : (
+        <div className="risk-finding__drawings">
+          <figure className="risk-finding__figure">
+            <Structure
+              idCode={finding.idCode}
+              width={DRAWING.width}
+              height={DRAWING.height}
+            />
+            <figcaption>
+              {finding.severity === 'medium' ? 'Medium-risk' : 'High-risk'}{' '}
+              fragment
+            </figcaption>
+          </figure>
+          <figure className="risk-finding__figure">
+            <Structure
+              idCode={structure}
+              width={DRAWING.width}
+              height={DRAWING.height}
+              atomHighlight={[...finding.atoms]}
+              bondHighlight={[...finding.bonds]}
+            />
+            <figcaption>
+              {finding.atoms.length === 0
+                ? 'Not located on this drawing'
+                : 'Where it sits on the molecule'}
+            </figcaption>
+          </figure>
+        </div>
+      )}
+    </div>
+  );
+}

package/src/osiris/ui/RiskPanel.tsx

@@ -0,0 +1,81 @@
+/**
+ * The four toxicity risks, and the sentence that keeps them honest.
+ *
+ * OSIRIS assesses mutagenicity, tumorigenicity, irritating effects and
+ * reproductive effects, in that order, and answers each with one of three
+ * levels — the same three the drug score multiplies by. A red square is very
+ * often the known-molecule branch rather than a matched fragment, which is why
+ * every assessed square opens its explanation.
+ *
+ * The caveat under them is the author's own, quoted rather than paraphrased: it
+ * is the sentence that stops a red square being read as a verdict, and softening
+ * it would be our words over his.
+ */
+
+import { H5 } from '@blueprintjs/core';
+import type { ReactElement } from 'react';
+
+import { RISK_CAVEAT } from '../core/riskAppearance.ts';
+import type { RiskLevel, RiskType } from '../core/types.ts';
+import { RISK_TYPES } from '../core/types.ts';
+
+import { RiskSquare } from './RiskSquare.tsx';
+
+/** What {@link RiskPanel} needs. */
+export interface RiskPanelProps {
+  /**
+   * How the four came back, or `null` when none of them has been assessed.
+   * @default null
+   */
+  risks?: Record<RiskType, RiskLevel> | null;
+  /**
+   * Whether a prediction is running for the molecule the panel is showing.
+   * @default false
+   */
+  pending?: boolean;
+  /**
+   * Which risk has its explanation open.
+   * @default null
+   */
+  openRisk?: RiskType | null;
+  /**
+   * Called with the risk to open, or `null` to close the one that is open.
+   * Without it the squares are not clickable.
+   * @default undefined
+   */
+  onOpenRisk?: (risk: RiskType | null) => void;
+}
+
+/**
+ * The four risk squares.
+ * @param props - See {@link RiskPanelProps}.
+ * @returns The panel, with the caveat under it.
+ */
+export function RiskPanel(props: RiskPanelProps): ReactElement {
+  const { risks = null, pending = false, openRisk = null, onOpenRisk } = props;
+
+  return (
+    <section className="risk-panel">
+      <H5>Predicted toxicity risks</H5>
+      <div className="risk-grid">
+        {RISK_TYPES.map((risk) => (
+          <RiskSquare
+            key={risk}
+            risk={risk}
+            level={risks?.[risk]}
+            pending={pending}
+            selected={openRisk === risk}
+            onSelect={
+              onOpenRisk === undefined
+                ? undefined
+                : (chosen) => {
+                    onOpenRisk(chosen === openRisk ? null : chosen);
+                  }
+            }
+          />
+        ))}
+      </div>
+      <p className="osiris-note">{RISK_CAVEAT}</p>
+    </section>
+  );
+}

package/src/osiris/ui/RiskSquare.tsx

@@ -0,0 +1,108 @@
+/**
+ * One toxicity risk, as a coloured square with its name beside it.
+ *
+ * The square is a button whenever the page can explain it, because the
+ * explanation is the honest half of the colour: aspirin, caffeine and
+ * paracetamol come back red through the known-molecule branch, not through a
+ * toxicophore, and only opening it says so.
+ *
+ * `compact` drops the words and keeps the square, which is what a cell of the
+ * comparison table needs; the name and the level stay on the accessible label,
+ * so the cell is still readable to a screen reader and on hover.
+ */
+
+import type { ReactElement } from 'react';
+
+import { RISK_LABELS } from '../core/constants.ts';
+import { riskAppearance } from '../core/riskAppearance.ts';
+import type { RiskLevel, RiskType } from '../core/types.ts';
+
+/** What {@link RiskSquare} needs. */
+export interface RiskSquareProps {
+  /** Which of the four risks this shows. */
+  risk: RiskType;
+  /** How it came back, or `undefined` when it has not been assessed. */
+  level: RiskLevel | undefined;
+  /**
+   * Whether a prediction is running for this molecule. It is what tells an
+   * unassessed square to say it is working rather than that there is nothing
+   * to work on.
+   * @default false
+   */
+  pending?: boolean;
+  /**
+   * Whether this risk's explanation is the one open.
+   * @default false
+   */
+  selected?: boolean;
+  /**
+   * Called with the risk when the square is clicked. Without it the square is
+   * not a button.
+   * @default undefined
+   */
+  onSelect?: (risk: RiskType) => void;
+  /**
+   * Draw the square alone, for a cell of a table.
+   * @default false
+   */
+  compact?: boolean;
+}
+
+/**
+ * One risk's square.
+ * @param props - See {@link RiskSquareProps}.
+ * @returns The square, as a button when the page can explain it.
+ */
+export function RiskSquare(props: RiskSquareProps): ReactElement {
+  const {
+    risk,
+    level,
+    pending = false,
+    selected = false,
+    onSelect,
+    compact = false,
+  } = props;
+  const { tone, label, explainable } = riskAppearance(level, pending);
+  const name = RISK_LABELS[risk];
+  const description = `${name}: ${label}`;
+  const clickable = onSelect !== undefined && explainable;
+
+  const body = (
+    <>
+      <span className="risk-square__swatch" data-level={tone} />
+      {compact ? null : (
+        <span className="risk-square__text">
+          <span className="risk-square__name">{name}</span>
+          <span className="risk-square__level">{label}</span>
+        </span>
+      )}
+    </>
+  );
+
+  if (!clickable) {
+    return (
+      <span
+        className={compact ? 'risk-square risk-square--compact' : 'risk-square'}
+        title={description}
+        aria-label={compact ? description : undefined}
+      >
+        {body}
+      </span>
+    );
+  }
+
+  return (
+    <button
+      type="button"
+      className={compact ? 'risk-square risk-square--compact' : 'risk-square'}
+      title={`${description} — why?`}
+      aria-label={compact ? description : undefined}
+      aria-pressed={selected}
+      onClick={() => {
+        onSelect(risk);
+      }}
+    >
+      {body}
+    </button>
+  );
+}

package/src/osiris/ui/index.ts

@@ -0,0 +1,17 @@
+export type { PropertyBarProps } from './PropertyBar.tsx';
+export { PropertyBar } from './PropertyBar.tsx';
+export type { PropertyPanelProps } from './PropertyPanel.tsx';
+export { PropertyPanel } from './PropertyPanel.tsx';
+export type { PropertyRowsProps } from './PropertyRows.tsx';
+export { PropertyRows } from './PropertyRows.tsx';
+export type { RiskFindingsProps } from './RiskFindings.tsx';
+export { RiskFindings } from './RiskFindings.tsx';
+export type { RiskPanelProps } from './RiskPanel.tsx';
+export { RiskPanel } from './RiskPanel.tsx';
+export type { RiskSquareProps } from './RiskSquare.tsx';
+export { RiskSquare } from './RiskSquare.tsx';
+export type {
+  UsePredictionsOptions,
+  UsePredictionsResult,
+} from './usePredictions.ts';
+export { usePredictions } from './usePredictions.ts';

package/src/osiris/ui/usePredictions.ts

@@ -0,0 +1,194 @@
+/**
+ * The prediction pool, handed to a page.
+ *
+ * The only React in the domain. Results arrive one at a time and are kept in a
+ * map the page reads by row key, so a table draws every row immediately and
+ * fills each one in as its worker answers — nothing waits for the set.
+ *
+ * The two maps are created once and mutated, and a counter beside them changes
+ * to say so. Building a new map per answer would copy a growing map once per
+ * molecule, which on a set of two thousand costs more than the predictions do.
+ */
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import type { WorkerLike } from '../../worker/core/messages.ts';
+import type {
+  PredictionInput,
+  PredictionPool,
+  PredictionProgress,
+} from '../core/poolTypes.ts';
+import { createPredictionPool } from '../core/predictionPool.ts';
+import type { ResourceSource } from '../core/predictors.ts';
+import type { OsirisProperties, RiskDetail, RiskType } from '../core/types.ts';
+
+/** What a page gives the hook. */
+export interface UsePredictionsOptions {
+  /**
+   * The molecules to predict. One already answered is never asked for again,
+   * so a page may pass its whole set on every render — though memoising it
+   * saves the filtering pass.
+   */
+  molecules: readonly PredictionInput[];
+  /**
+   * The keys of the rows the reader can see, most wanted first. They are
+   * answered before the rest.
+   * @default undefined — the reading order is kept
+   */
+  visibleKeys?: readonly string[];
+  /**
+   * Whether to predict at all. Off while a file is still being read, so the
+   * pool is not asked for half a set.
+   * @default true
+   */
+  enabled?: boolean;
+  /**
+   * Where the workers register OpenChemLib's resources from: the absolute URL
+   * of the site's own `openchemlib-resources.json`, resolved on the main thread
+   * — a worker has no `document` to read the deployment's mount path off, and
+   * a relative address would resolve against its hashed chunk.
+   */
+  resources: ResourceSource;
+  /**
+   * Makes one prediction worker: a module worker of the site's own, serving
+   * `runPredictionJob` for the requests `isPredictRequest` accepts. It may be
+   * a new function on every render — it is read only when a worker is made.
+   */
+  createWorker: () => WorkerLike;
+  /**
+   * How many workers to run.
+   * @default one fewer than the machine's cores, clamped to 1 to 8
+   */
+  size?: number;
+}
+
+/** What the hook gives a page back. */
+export interface UsePredictionsResult {
+  /** What each answered row was predicted to be, by row key. */
+  results: ReadonlyMap<string, OsirisProperties>;
+  /** Why each refused row was refused, by row key. */
+  failures: ReadonlyMap<string, string>;
+  /** How far the pool has got. */
+  progress: PredictionProgress;
+  /** Why no prediction can be made at all, or `null`. */
+  error: string | null;
+  /** Drop everything still queued. */
+  cancel: () => void;
+  /**
+   * Why one risk came back as it did.
+   * @param idCode - The molecule, coordinates included or not.
+   * @param risk - Which of the four risks to explain.
+   * @returns The findings, with the matched atoms and bonds of every fragment.
+   */
+  riskDetail: (idCode: string, risk: RiskType) => Promise<RiskDetail>;
+}
+
+const IDLE: PredictionProgress = {
+  done: 0,
+  total: 0,
+  pending: 0,
+  running: false,
+};
+
+interface Answered {
+  results: Map<string, OsirisProperties>;
+  failures: Map<string, string>;
+}
+
+interface PoolView {
+  progress: PredictionProgress;
+  error: string | null;
+  answers: number;
+}
+
+/**
+ * Predict a set of molecules on a pool of workers, streaming the answers back.
+ * @param options - See {@link UsePredictionsOptions}.
+ * @returns The answers so far, the progress, and the controls.
+ */
+export function usePredictions(
+  options: UsePredictionsOptions,
+): UsePredictionsResult {
+  const { molecules, visibleKeys, enabled = true, size } = options;
+  const { resources, createWorker } = options;
+  // Read when the pool and its workers are made rather than listed as a
+  // dependency: a factory written inline is a new function on every render,
+  // and the progress the pool reports causes one.
+  const source = useRef({ resources, createWorker });
+  useEffect(() => {
+    source.current = { resources, createWorker };
+  }, [resources, createWorker]);
+
+  const [answered] = useState<Answered>(() => ({
+    results: new Map(),
+    failures: new Map(),
+  }));
+  const [view, setView] = useState<PoolView>({
+    progress: IDLE,
+    error: null,
+    answers: 0,
+  });
+  const pool = useRef<PredictionPool | null>(null);
+
+  const open = useCallback((): PredictionPool => {
+    pool.current ??= createPredictionPool({
+      resources: source.current.resources,
+      createWorker: () => source.current.createWorker(),
+      ...(size === undefined ? {} : { size }),
+      onResult(outcome) {
+        if (outcome.ok) answered.results.set(outcome.key, outcome.properties);
+        else answered.failures.set(outcome.key, outcome.message);
+        setView((previous) => ({ ...previous, answers: previous.answers + 1 }));
+      },
+      onProgress(progress) {
+        setView((previous) => ({ ...previous, progress }));
+      },
+      onUnavailable(message) {
+        setView((previous) => ({ ...previous, error: message }));
+      },
+    });
+    return pool.current;
+  }, [answered, size]);
+
+  const unavailable = view.error;
+  useEffect(() => {
+    if (!enabled || unavailable !== null) return;
+    const waiting: PredictionInput[] = [];
+    for (const molecule of molecules) {
+      if (answered.results.has(molecule.key)) continue;
+      if (answered.failures.has(molecule.key)) continue;
+      waiting.push(molecule);
+    }
+    if (waiting.length > 0) open().submit(waiting);
+  }, [answered, molecules, enabled, open, unavailable]);
+
+  useEffect(() => {
+    if (visibleKeys !== undefined) pool.current?.prioritize(visibleKeys);
+  }, [visibleKeys]);
+
+  useEffect(
+    () => () => {
+      pool.current?.terminate();
+      pool.current = null;
+    },
+    [],
+  );
+
+  const cancel = useCallback(() => {
+    pool.current?.cancel();
+  }, []);
+
+  const riskDetail = useCallback(
+    (idCode: string, risk: RiskType) => open().riskDetail(idCode, risk),
+    [open],
+  );
+
+  return {
+    results: answered.results,
+    failures: answered.failures,
+    progress: view.progress,
+    error: view.error,
+    cancel,
+    riskDetail,
+  };
+}

package/src/osiris-ui.ts

@@ -0,0 +1,11 @@
+/**
+ * The OSIRIS property panel — the four risk squares, the ten bars and the
+ * explanation a square opens — and `usePredictions`, which drives a pool of
+ * prediction workers from a page.
+ *
+ * Kept apart from `react-cheminfo/osiris` so the worker that predicts loads no
+ * React and no Blueprint; everything the panel draws from is imported from
+ * there. The stylesheet is `react-cheminfo/styles/osiris.css`.
+ */
+
+export * from './osiris/ui/index.ts';

package/src/osiris.ts

@@ -0,0 +1,17 @@
+/**
+ * What OSIRIS predicts about a molecule — the four toxicity risks, cLogP,
+ * solubility, drug-likeness and the drug score — and the pool of workers that
+ * predicts a whole set of them.
+ *
+ * Framework-free on purpose, and its own door for two reasons. A prediction
+ * worker imports `runPredictionJob` and `isPredictRequest` from here, and a dev
+ * server hands a worker its dependencies unbundled, so anything React-shaped
+ * behind this door would be evaluated in every worker. And a server answering
+ * predictions over an API loads it in Node, where nothing is tree-shaken.
+ * `openchemlib` is imported on the first prediction, never on import.
+ *
+ * The panel that draws the answer, and the hook that drives the pool from a
+ * page, are `react-cheminfo/osiris-ui`.
+ */
+
+export * from './osiris/core/index.ts';

package/src/panel/ui/FilterInput.tsx

@@ -1,5 +1,7 @@
 import { InputGroup } from '@blueprintjs/core';
 
+import { useChromeT } from '../../i18n/ui/useT.ts';
+
 import { ClearButton } from './ClearButton.tsx';
 
 export interface FilterInputProps {
@@ -34,6 +36,7 @@ export interface FilterInputProps {
  */
 export function FilterInput(props: FilterInputProps) {
   const { value, onValueChange, placeholder, autoFocus = false } = props;
+  const t = useChromeT();
 
   return (
     <InputGroup
@@ -49,7 +52,7 @@ export function FilterInput(props: FilterInputProps) {
       rightElement={
         value.length > 0 ? (
           <ClearButton
-            label="Clear the filter"
+            label={t('panel.clearFilter')}
             onClick={() => onValueChange('')}
           />
         ) : undefined