react-cheminfo 0.76.0 → 0.78.0

package/src/osiris/ui/PropertyPanel.tsx

@@ -0,0 +1,227 @@
+/**
+ * Everything OSIRIS predicts about one molecule: the four toxicity risks, then
+ * the ten numbers, in the order the original panel showed them.
+ *
+ * One panel wherever a molecule is predicted — beside an editor's canvas, for
+ * the row of a table the reader focused, beside a drawing — because a second
+ * panel would be a second place for the same ten rows to drift apart.
+ *
+ * The sections stand whether or not there is anything in them. A prediction
+ * costs a fifth of a second, and a panel that appeared only once it was ready
+ * would move the page under the reader's eye every time they drew a bond.
+ *
+ * Which explanation is open is the caller's state — it belongs to the page, and
+ * on the explorer it is what a click on a square changes — but *fetching* it is
+ * the panel's own business, so no page repeats the dance.
+ */
+
+import { Callout, H5 } from '@blueprintjs/core';
+import type { ReactElement, ReactNode } from 'react';
+import { useEffect, useState } from 'react';
+import { MF } from 'react-mf';
+
+import { errorMessage } from '../../error/core/toError.ts';
+import { PagePart } from '../../share/ui/PagePart.tsx';
+import type { PropertyKey } from '../core/propertyKeys.ts';
+import { PROPERTY_KEYS } from '../core/propertyKeys.ts';
+import type { OsirisProperties, RiskDetail, RiskType } from '../core/types.ts';
+
+import { PropertyRows } from './PropertyRows.tsx';
+import { RiskFindings } from './RiskFindings.tsx';
+import { RiskPanel } from './RiskPanel.tsx';
+
+/** What {@link PropertyPanel} needs. */
+export interface PropertyPanelProps {
+  /**
+   * What was predicted, or `null` when there is nothing to show yet.
+   * @default null
+   */
+  properties?: OsirisProperties | null;
+  /**
+   * The atom layout to draw the molecule with, in an explanation. Empty leaves
+   * openchemlib to invent one.
+   * @default ''
+   */
+  coordinates?: string;
+  /**
+   * Whether a prediction is running for the molecule the panel is showing.
+   * @default false
+   */
+  pending?: boolean;
+  /**
+   * What went wrong with this structure, in one sentence, or `null`.
+   * @default null
+   */
+  problem?: string | null;
+  /**
+   * Whether to open on the molecule's formula and name. Off for a host that
+   * already shows the formula beside the panel, such as a structure editor's
+   * side panel.
+   * @default true
+   */
+  head?: boolean;
+  /**
+   * Whether to draw the four risks, and the explanation a square opens. Off
+   * for a page answering a question about the numbers alone.
+   * @default true
+   */
+  risks?: boolean;
+  /**
+   * The property rows to draw, in the panel's order whatever order they are
+   * given in. Empty leaves the section out, for a page answering a question
+   * about the risks alone.
+   * @default PROPERTY_KEYS
+   */
+  rows?: readonly PropertyKey[];
+  /**
+   * What is said when there is nothing predicted and nothing running.
+   * @default 'Nothing to predict yet.'
+   */
+  emptyMessage?: ReactNode;
+  /**
+   * Which risk has its explanation open.
+   * @default null
+   */
+  openRisk?: RiskType | null;
+  /**
+   * Called with the risk to open, or `null` to close it. Without it the squares
+   * are not clickable.
+   * @default undefined
+   */
+  onOpenRisk?: (risk: RiskType | null) => void;
+  /**
+   * Why a risk came back as it did. Without it no explanation is offered.
+   * @default undefined
+   */
+  loadDetail?: (structure: string, risk: RiskType) => Promise<RiskDetail>;
+}
+
+/** One fetched explanation, and the request it answers. */
+interface DetailAnswer {
+  key: string;
+  detail: RiskDetail | null;
+  error: string | null;
+}
+
+/**
+ * The risks and the properties of one molecule.
+ * @param props - See {@link PropertyPanelProps}.
+ * @returns The two panels, and the open explanation between them.
+ */
+export function PropertyPanel(props: PropertyPanelProps): ReactElement {
+  const {
+    properties = null,
+    coordinates = '',
+    pending = false,
+    problem = null,
+    head = true,
+    risks = true,
+    rows = PROPERTY_KEYS,
+    emptyMessage = 'Nothing to predict yet.',
+    openRisk = null,
+    onOpenRisk,
+    loadDetail,
+  } = props;
+
+  const structure =
+    properties === null
+      ? ''
+      : coordinates === ''
+        ? properties.idCode
+        : `${properties.idCode} ${coordinates}`;
+  const answer = useRiskDetail(structure, openRisk, loadDetail);
+
+  return (
+    <div className="property-panel">
+      {problem === null ? null : (
+        <Callout intent="warning" compact>
+          {problem}
+        </Callout>
+      )}
+
+      {properties === null ? (
+        <p className="osiris-note">{pending ? 'Predicting…' : emptyMessage}</p>
+      ) : head ? (
+        <header className="property-panel__head">
+          <MF mf={properties.molecularFormula} />
+          <span className="property-panel__label">{properties.label}</span>
+        </header>
+      ) : null}
+
+      {risks ? (
+        <PagePart part="risks">
+          <RiskPanel
+            risks={properties?.risks ?? null}
+            pending={pending}
+            openRisk={openRisk}
+            onOpenRisk={onOpenRisk}
+          />
+        </PagePart>
+      ) : null}
+
+      {!risks ||
+      openRisk === null ||
+      structure === '' ||
+      loadDetail === undefined ? null : (
+        <PagePart part="detail">
+          <RiskFindings
+            risk={openRisk}
+            structure={structure}
+            detail={answer?.detail ?? null}
+            error={answer?.error ?? null}
+          />
+        </PagePart>
+      )}
+
+      {rows.length === 0 ? null : (
+        <PagePart part="properties">
+          <section className="property-section">
+            <H5>Predicted properties</H5>
+            <PropertyRows properties={properties} keys={rows} />
+          </section>
+        </PagePart>
+      )}
+    </div>
+  );
+}
+
+/**
+ * Fetch the open risk's explanation, and answer only about the request that is
+ * open now.
+ *
+ * The answer carries the request it belongs to rather than being cleared when a
+ * new one starts: clearing would mean writing state from inside the effect, and
+ * comparing keys says the same thing without the extra render.
+ * @param structure - The molecule: an idCode, with its coordinates after a space.
+ * @param openRisk - Which risk is open, or `null`.
+ * @param loadDetail - What answers the question, or `undefined` when nothing does.
+ * @returns The answer to the open request, or `null` while it is being worked out.
+ */
+function useRiskDetail(
+  structure: string,
+  openRisk: RiskType | null,
+  loadDetail:
+    ((structure: string, risk: RiskType) => Promise<RiskDetail>) | undefined,
+): DetailAnswer | null {
+  const key =
+    openRisk === null || structure === '' ? '' : `${structure} ${openRisk}`;
+  const [answer, setAnswer] = useState<DetailAnswer | null>(null);
+
+  useEffect(() => {
+    if (key === '' || openRisk === null || loadDetail === undefined) return;
+    let live = true;
+    loadDetail(structure, openRisk).then(
+      (detail) => {
+        if (live) setAnswer({ key, detail, error: null });
+      },
+      (error: unknown) => {
+        if (live) setAnswer({ key, detail: null, error: errorMessage(error) });
+      },
+    );
+    return () => {
+      live = false;
+    };
+  }, [key, structure, openRisk, loadDetail]);
+
+  return answer !== null && answer.key === key ? answer : null;
+}

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';