react-cheminfo 0.76.0 → 0.77.0

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

package/src/panel/ui/SidePanelItem.tsx

@@ -0,0 +1,162 @@
+import type { CSSProperties, ReactNode } from 'react';
+import { useCallback, useRef, useState } from 'react';
+import { Accordion, Button } from 'react-science/ui';
+
+import type { Language } from '../../i18n/core/languages.ts';
+import { useLanguage } from '../../i18n/ui/useLanguage.ts';
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import { FullscreenStage } from '../../shared/ui/FullscreenStage.tsx';
+import { canFillScreen } from '../../shared/ui/canFillScreen.ts';
+import { TOKEN } from '../../tokens/core/familyTokens.ts';
+import { panelStyle, panelToolbarStyle } from '../core/panelStyles.ts';
+
+/** Props of {@link SidePanelItem}. */
+export interface SidePanelItemProps {
+  /** Identity of the panel in the stack. */
+  id: string;
+  /** What the header says. */
+  title: string;
+  /** Whether the panel shows its body. */
+  isOpen: boolean;
+  /**
+   * Called when the chevron, the header or a shift-click on another header
+   * folds or unfolds the panel.
+   * @param isOpen - Whether it shows its body.
+   */
+  onOpenChange: (isOpen: boolean) => void;
+  /**
+   * Whether the panel is the one in focus, and the toggle; `undefined` while it
+   * is alone in the stack, where there is nothing to fold.
+   */
+  focus: { active: boolean; toggle: () => void } | undefined;
+  /** Called when the close cross is pressed. */
+  onClose: () => void;
+  /** The body. */
+  children: ReactNode;
+}
+
+/**
+ * One panel of the stack: the header with the shell's gestures, and the body,
+ * which is also the box that fills the screen.
+ *
+ * The header is not part of what fills the screen, so a body that does carries
+ * a bar of its own with the title and the way back.
+ * @param props - See {@link SidePanelItemProps}.
+ * @returns The accordion item.
+ */
+export function SidePanelItem(props: SidePanelItemProps) {
+  const { id, title, isOpen, onOpenChange, focus, onClose, children } = props;
+  const t = useChromeT();
+  const panel = inSentence(title, useLanguage());
+  const [canFill] = useState(canFillScreen);
+  const body = useRef<HTMLDivElement | null>(null);
+  const onStage = useCallback((element: HTMLDivElement | null) => {
+    body.current = element;
+  }, []);
+
+  function fillScreen(): void {
+    if (!isOpen) onOpenChange(true);
+    void body.current?.requestFullscreen().catch(() => undefined);
+  }
+
+  return (
+    <Accordion.Item
+      id={id}
+      title={title}
+      open={isOpen}
+      onOpenChange={onOpenChange}
+      renderToolbar={() => (
+        <>
+          {focus !== undefined && (
+            <Button
+              variant="minimal"
+              icon={focus.active ? 'expand-all' : 'collapse-all'}
+              aria-pressed={focus.active}
+              aria-label={t('panel.focus', { panel })}
+              tooltipProps={{
+                content: focus.active
+                  ? t('panel.unfocusTooltip')
+                  : t('panel.focusTooltip'),
+              }}
+              onClick={focus.toggle}
+            />
+          )}
+          {canFill && (
+            <Button
+              variant="minimal"
+              icon="fullscreen"
+              aria-label={t('panel.fillScreen', { panel })}
+              tooltipProps={{ content: t('panel.fillScreenTooltip') }}
+              onClick={fillScreen}
+            />
+          )}
+          <Button
+            variant="minimal"
+            icon={isOpen ? 'chevron-down' : 'chevron-right'}
+            data-panel-open={isOpen}
+            aria-expanded={isOpen}
+            aria-label={t(isOpen ? 'panel.fold' : 'panel.unfold', { panel })}
+            tooltipProps={{
+              content: t(isOpen ? 'panel.foldTooltip' : 'panel.unfoldTooltip'),
+            }}
+            onClick={() => onOpenChange(!isOpen)}
+          />
+          <Button
+            variant="minimal"
+            icon="cross"
+            tooltipProps={{ content: t('panel.closeTooltip') }}
+            aria-label={t('panel.close', { panel })}
+            onClick={onClose}
+          />
+        </>
+      )}
+    >
+      <FullscreenStage style={bodyStyle} onStage={onStage}>
+        {(fullscreen) => (
+          <>
+            {fullscreen?.active === true && (
+              <div style={fullscreenBarStyle}>
+                <span style={fullscreenTitleStyle}>{title}</span>
+                <Button
+                  variant="minimal"
+                  icon="minimize"
+                  aria-label={t('panel.leaveFullScreen')}
+                  tooltipProps={{ content: t('panel.leaveFullScreenTooltip') }}
+                  onClick={fullscreen.toggle}
+                />
+              </div>
+            )}
+            {children}
+          </>
+        )}
+      </FullscreenStage>
+    </Accordion.Item>
+  );
+}
+
+/**
+ * The title as it reads inside a sentence: lowercased, except in German, where
+ * every noun keeps its capital.
+ * @param title - The panel's title.
+ * @param language - The language of the sentence.
+ * @returns The title to write into it.
+ */
+function inSentence(title: string, language: Language): string {
+  return language === 'de' ? title : title.toLocaleLowerCase(language);
+}
+
+/** A box filling the screen shows the backdrop through it unless painted. */
+const filledStyle: CSSProperties = { ...panelStyle, background: TOKEN.surface };
+
+function bodyStyle(fillsScreen: boolean): CSSProperties {
+  return fillsScreen ? filledStyle : panelStyle;
+}
+
+const fullscreenBarStyle: CSSProperties = {
+  ...panelToolbarStyle,
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  paddingLeft: 12,
+};
+
+const fullscreenTitleStyle: CSSProperties = { fontWeight: 'bold' };