react-cheminfo 0.76.0 → 0.78.0

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

package/src/panel/ui/SidePanelStack.tsx

@@ -1,6 +1,9 @@
 import type { ReactNode } from 'react';
 import type { ActivityBarItemProps } from 'react-science/ui';
-import { Accordion, AccordionProvider, Button } from 'react-science/ui';
+import { Accordion, AccordionProvider } from 'react-science/ui';
+
+import { SidePanelItem } from './SidePanelItem.tsx';
+import { usePanelFolds } from './usePanelFolds.ts';
 
 /** What a rail reads about one panel, wherever that rail is drawn. */
 export interface PanelDescriptor {
@@ -44,21 +47,22 @@ export interface SidePanelStackProps<TPanel extends PanelDescriptor> {
  * They are drawn in the order the rail stacks their icons rather than the order
  * they were switched on, so a panel always comes back where it was.
  *
- * The header carries the shell's own two gestures and nothing about what the
- * panel holds: the chevron that folds it away and the cross that closes it.
- * What a panel switches on and off is a toolbar at the top of its own body, so
- * it travels with the panel when it is folded, reordered or lent to another
- * editor, and every header in every editor reads the same — which is the reason
- * this is one component rather than one per editor.
+ * The header carries the shell's own gestures and nothing about what the panel
+ * holds: focus, which folds every other panel away and unfolds them again;
+ * filling the screen with the panel, where the browser can; the chevron that
+ * folds it away; and the cross that closes it. What a panel switches on and off
+ * is a toolbar at the top of its own body, so it travels with the panel when it
+ * is folded, reordered or lent to another editor, and every header in every
+ * editor reads the same — which is the reason this is one component rather
+ * than one per editor.
  *
  * The chevron is there because nothing else says which panels are folded. The
  * accordion draws every header identically and hides only the body, so a side
  * of four closed panels and a side of four open ones differ by white space, and
  * a reader looking for a panel that is already open reaches for its icon and
- * closes it. It is a real button rather than a glyph because the header's own
- * click never reaches the toolbar — clicks there are stopped so the close cross
- * does not also fold the panel — so a chevron that did nothing when pressed
- * would be an affordance that lies.
+ * closes it. Focus is a button as well as a shift-click because a modifier on a
+ * header is a gesture nobody finds, and it undoes itself, which a shift-click
+ * does not.
  * @param props - Component props.
  * @returns The stack.
  */
@@ -67,41 +71,30 @@ export function SidePanelStack<TPanel extends PanelDescriptor>(
 ) {
   const { panels, openPanelIds, onClose, children } = props;
   const open = panels.filter((panel) => openPanelIds.includes(panel.id));
+  const folds = usePanelFolds(open.map((panel) => panel.id));
 
   return (
     <AccordionProvider>
       <Accordion>
         {open.map((panel) => (
-          <Accordion.Item
+          <SidePanelItem
             key={panel.id}
             id={panel.id}
             title={panel.title}
-            defaultOpen
-            renderToolbar={({ isOpen, controls }) => (
-              <>
-                <Button
-                  variant="minimal"
-                  icon={isOpen ? 'chevron-down' : 'chevron-right'}
-                  data-panel-open={isOpen}
-                  aria-expanded={isOpen}
-                  aria-label={`${isOpen ? 'Fold' : 'Unfold'} the ${panel.title.toLowerCase()} panel`}
-                  tooltipProps={{
-                    content: isOpen ? 'Fold this panel away' : 'Unfold it',
-                  }}
-                  onClick={() => controls.toggle()}
-                />
-                <Button
-                  variant="minimal"
-                  icon="cross"
-                  tooltipProps={{ content: 'Close this panel' }}
-                  aria-label={`Close the ${panel.title.toLowerCase()} panel`}
-                  onClick={() => onClose(panel.id)}
-                />
-              </>
-            )}
+            isOpen={folds.isOpen(panel.id)}
+            onOpenChange={(isOpen) => folds.setOpen(panel.id, isOpen)}
+            focus={
+              open.length > 1
+                ? {
+                    active: folds.focused === panel.id,
+                    toggle: () => folds.toggleFocus(panel.id),
+                  }
+                : undefined
+            }
+            onClose={() => onClose(panel.id)}
           >
             {children(panel)}
-          </Accordion.Item>
+          </SidePanelItem>
         ))}
       </Accordion>
     </AccordionProvider>

package/src/panel/ui/SpectrumColorSwatch.tsx

@@ -5,6 +5,7 @@ import {
   EXTRA_SPECTRUM_COLORS,
   SPECTRUM_COLORS,
 } from '../../chart/core/spectrumColor.ts';
+import { useChromeT } from '../../i18n/ui/useT.ts';
 
 export interface SpectrumColorSwatchProps {
   /** The colour the spectrum is drawn in. */
@@ -41,6 +42,7 @@ export interface SpectrumColorSwatchProps {
 export function SpectrumColorSwatch(props: SpectrumColorSwatchProps) {
   const { color, name, onPick } = props;
   const [isOpen, setIsOpen] = useState(false);
+  const t = useChromeT();
 
   function offer(offered: string) {
     return (
@@ -48,7 +50,7 @@ export function SpectrumColorSwatch(props: SpectrumColorSwatchProps) {
         key={offered}
         type="button"
         title={offered}
-        aria-label={`Draw ${name} in ${offered}`}
+        aria-label={t('panel.drawIn', { name, color: offered })}
         style={{
           ...(offered === color ? activeSwatchStyle : swatchStyle),
           background: offered,
@@ -78,8 +80,8 @@ export function SpectrumColorSwatch(props: SpectrumColorSwatchProps) {
     >
       <button
         type="button"
-        title="Draw this spectrum in another colour"
-        aria-label={`Colour of ${name}`}
+        title={t('panel.changeColour')}
+        aria-label={t('panel.colourOf', { name })}
         style={{ ...swatchStyle, background: color }}
       />
     </PopoverNext>

package/src/panel/ui/usePanelFolds.ts

@@ -0,0 +1,103 @@
+import { useState } from 'react';
+
+/** Which panels of a stack are folded, and the gestures that change that. */
+export interface PanelFolds {
+  /**
+   * Whether a panel shows its body.
+   * @param id - The panel.
+   * @returns False while it is folded away.
+   */
+  isOpen: (id: string) => boolean;
+  /**
+   * Fold a panel away, or unfold it.
+   * @param id - The panel.
+   * @param open - Whether it shows its body.
+   */
+  setOpen: (id: string, open: boolean) => void;
+  /** The one panel left unfolded among several, or null. */
+  focused: string | null;
+  /**
+   * Focus on a panel: unfold it and fold every other one, or, when it is
+   * already in focus, unfold them all again.
+   * @param id - The panel.
+   */
+  toggleFocus: (id: string) => void;
+}
+
+const NOTHING_FOLDED: ReadonlySet<string> = new Set();
+
+/**
+ * The folds of a stack of panels, kept by the stack rather than by each panel
+ * so that one panel can be focused — every other one folded — and the focus
+ * undone.
+ *
+ * A panel closed while folded comes back unfolded when it is opened again: a
+ * reader reopening a panel from the rail is asking to see it.
+ * @param openIds - The panels in the stack, in the order they are drawn.
+ * @returns The folds.
+ */
+export function usePanelFolds(openIds: readonly string[]): PanelFolds {
+  const [folded, setFolded] = useState(NOTHING_FOLDED);
+
+  const kept = keepOnly(folded, openIds);
+  if (kept !== folded) setFolded(kept);
+
+  return {
+    isOpen: (id) => !kept.has(id),
+    setOpen: (id, open) => {
+      setFolded((previous) => {
+        if (previous.has(id) !== open) return previous;
+        const next = new Set(previous);
+        if (open) next.delete(id);
+        else next.add(id);
+        return next;
+      });
+    },
+    focused: focusedPanel(openIds, kept),
+    toggleFocus: (id) => {
+      setFolded(
+        focusedPanel(openIds, kept) === id
+          ? NOTHING_FOLDED
+          : new Set(openIds.filter((other) => other !== id)),
+      );
+    },
+  };
+}
+
+/**
+ * The folds of the panels still in the stack.
+ * @param folded - The panels folded.
+ * @param openIds - The panels in the stack.
+ * @returns `folded` itself when every one of them is still in the stack.
+ */
+function keepOnly(
+  folded: ReadonlySet<string>,
+  openIds: readonly string[],
+): ReadonlySet<string> {
+  for (const id of folded) {
+    if (!openIds.includes(id)) {
+      return new Set(openIds.filter((open) => folded.has(open)));
+    }
+  }
+  return folded;
+}
+
+/**
+ * The panel in focus: the only one unfolded, when there is another to fold.
+ * @param openIds - The panels in the stack.
+ * @param folded - The panels folded.
+ * @returns The panel, or null.
+ */
+function focusedPanel(
+  openIds: readonly string[],
+  folded: ReadonlySet<string>,
+): string | null {
+  if (openIds.length < 2) return null;
+  let unfolded: string | null = null;
+  for (const id of openIds) {
+    if (folded.has(id)) continue;
+    if (unfolded !== null) return null;
+    unfolded = id;
+  }
+  return unfolded;
+}