react-cheminfo 0.73.0 → 0.74.0

package/src/structure/core/structureSearch.ts

@@ -0,0 +1,68 @@
+/** How a drawn structure is matched against a collection. */
+export type StructureSearchMode =
+  | 'substructure'
+  | 'similarity'
+  | 'exact'
+  | 'exactNoStereo'
+  | 'exactNoStereoTautomer';
+
+/**
+ * Every mode, in the order a dialog offers them: the two broad scans, then
+ * exact and its two relaxations.
+ */
+export const STRUCTURE_SEARCH_MODES: readonly StructureSearchMode[] = [
+  'substructure',
+  'similarity',
+  'exact',
+  'exactNoStereo',
+  'exactNoStereoTautomer',
+];
+
+/** A structure question: what is drawn, and how it is matched. */
+export interface StructureSearchQuery {
+  /**
+   * The drawing as an idCode, with the coordinates the editor laid out written
+   * after a space; empty when nothing is drawn.
+   */
+  idCode: string;
+  /** How the drawing is matched. */
+  mode: StructureSearchMode;
+  /** The least Tanimoto similarity a hit reaches, from 0 to 1. */
+  threshold: number;
+}
+
+/** A fragment a drawing can start from. */
+export interface StructureSearchExample {
+  /** What the button says. */
+  label: string;
+  /** The fragment, as a SMILES. */
+  smiles: string;
+  /**
+   * One line on what the fragment finds.
+   * @default undefined
+   */
+  help?: string;
+}
+
+/**
+ * The least similarities offered, as Tanimoto coefficients, in steps of 5 %.
+ */
+export const SIMILARITY_THRESHOLDS: readonly number[] = [
+  0.5, 0.55, 0.6, 0.65, 0.7, 0.75, 0.8, 0.85, 0.9, 0.95,
+];
+
+/**
+ * The thresholds to offer when one is already chosen: the usual steps, plus the
+ * chosen one when it is none of them, so a link asking for 0.42 still finds it
+ * in the list.
+ * @param current - The threshold in force.
+ * @returns The thresholds, ascending.
+ */
+export function similarityThresholds(current: number): number[] {
+  if (SIMILARITY_THRESHOLDS.includes(current) || !Number.isFinite(current)) {
+    return [...SIMILARITY_THRESHOLDS];
+  }
+  return [...SIMILARITY_THRESHOLDS, current].toSorted(
+    (left, right) => left - right,
+  );
+}

package/src/structure/core/substructureMatch.ts

@@ -0,0 +1,85 @@
+/**
+ * Where a query fragment sits in a molecule, as the atoms and bonds to paint.
+ *
+ * **Not exported from `core/index.ts`**: it value-imports `openchemlib`, so a
+ * barrel carrying it would pull the whole library into every site that imports
+ * `react-cheminfo/core`. Only the lazily loaded depiction calls it.
+ */
+
+import { Molecule, SSSearcher } from 'openchemlib';
+
+import { isEmptyIdCode, splitIdCode } from './editorValue.ts';
+
+/** The atoms and bonds of a molecule that a query covers. */
+export interface SubstructureMatch {
+  /** Atom indices, ascending, as openchemlib counts atoms from 0. */
+  atoms: number[];
+  /** Bond indices, ascending, as openchemlib counts bonds from 0. */
+  bonds: number[];
+}
+
+/**
+ * Find every match of a query in a molecule, merged into one set of atoms and
+ * bonds.
+ *
+ * Every match is painted, not only the first: a query for a phenyl ring that a
+ * molecule carries twice is shown twice. A bond is painted only when it is a
+ * bond of the query, so a ring closing between two matched atoms that the
+ * query leaves open stays unpainted. The query is read as a fragment whether
+ * or not it was drawn as one — a molecule not flagged as a fragment only ever
+ * matches itself, which is never what a substructure search asked.
+ * @param molecule - The molecule the depiction draws; its atom order is the
+ * one the indices refer to.
+ * @param query - The query as an openchemlib idCode, coordinates included or
+ * not.
+ * @returns The covered atoms and bonds, both empty when nothing matches.
+ */
+export function substructureMatch(
+  molecule: Molecule,
+  query: string,
+): SubstructureMatch {
+  if (isEmptyIdCode(query)) return { atoms: [], bonds: [] };
+  const fragment = Molecule.fromIDCode(splitIdCode(query).idCode);
+  fragment.setFragment(true);
+
+  const searcher = new SSSearcher();
+  searcher.setMol(fragment, molecule);
+  if (searcher.findFragmentInMolecule({ countMode: 'overlapping' }) === 0) {
+    return { atoms: [], bonds: [] };
+  }
+
+  const atomCovered = new Uint8Array(molecule.getAllAtoms());
+  const bondCovered = new Uint8Array(molecule.getAllBonds());
+  const fragmentBonds = fragment.getAllBonds();
+  for (const match of searcher.getMatchList()) {
+    for (const target of match) {
+      // An exclude group of the query maps onto nothing.
+      if (target >= 0) atomCovered[target] = 1;
+    }
+    for (let bond = 0; bond < fragmentBonds; bond++) {
+      const first = match[fragment.getBondAtom(0, bond)] ?? -1;
+      const second = match[fragment.getBondAtom(1, bond)] ?? -1;
+      if (first < 0 || second < 0) continue;
+      const target = molecule.getBond(first, second);
+      if (target >= 0) bondCovered[target] = 1;
+    }
+  }
+
+  return {
+    atoms: coveredIndices(atomCovered),
+    bonds: coveredIndices(bondCovered),
+  };
+}
+
+/**
+ * The positions of a flag array that are set, in ascending order.
+ * @param flags - One flag per atom or bond.
+ * @returns The indices whose flag is set.
+ */
+function coveredIndices(flags: Uint8Array): number[] {
+  const indices: number[] = [];
+  for (let index = 0; index < flags.length; index++) {
+    if (flags[index] === 1) indices.push(index);
+  }
+  return indices;
+}

package/src/structure/ui/Structure.tsx

@@ -133,6 +133,24 @@ export interface StructureProps {
    * @default '#ffd8a8'
    */
   bondHighlightColor?: string;
+  /**
+   * A query fragment, as an openchemlib idCode, whose every match is painted —
+   * atoms and bonds alike, so the hit reads as one shape. When set, it takes
+   * the place of `atomHighlight` and `bondHighlight`.
+   * @default undefined
+   */
+  substructure?: string;
+  /**
+   * The colour the `substructure` match is painted.
+   * @default '#ffd500'
+   */
+  substructureColor?: string;
+  /**
+   * How opaque the `substructure` match is painted, from 0 to 1. Light, so the
+   * bonds and the atom labels under it stay legible.
+   * @default 0.15
+   */
+  substructureOpacity?: number;
   /**
    * Called with the index of the atom that was clicked, counted from 0 as
    * openchemlib counts atoms.
@@ -181,6 +199,9 @@ export function Structure(props: StructureProps): ReactElement {
     atomHighlightColor = '#a5d8ff',
     bondHighlight,
     bondHighlightColor = '#ffd8a8',
+    substructure,
+    substructureColor = '#ffd500',
+    substructureOpacity = 0.15,
     onAtomClick,
     onBondClick,
     fallback = '—',
@@ -208,6 +229,9 @@ export function Structure(props: StructureProps): ReactElement {
         atomHighlightColor={atomHighlightColor}
         bondHighlight={bondHighlight}
         bondHighlightColor={bondHighlightColor}
+        substructure={substructure}
+        substructureColor={substructureColor}
+        substructureOpacity={substructureOpacity}
         showAtomNumber={labels.atoms ?? false}
         showBondNumber={labels.bonds ?? false}
         showMapping={labels.mapping ?? false}

package/src/structure/ui/StructureSearchDialog.tsx

@@ -0,0 +1,218 @@
+/**
+ * The dialog a structure search is drawn in, shared by every site that
+ * filters a collection by structure.
+ *
+ * This file stays free of `openchemlib`: the editor loads it behind its own
+ * `React.lazy`, and an example is read only once it is clicked.
+ */
+
+import {
+  Button,
+  Dialog,
+  DialogBody,
+  DialogFooter,
+  HTMLSelect,
+} from '@blueprintjs/core';
+import type { ReactElement, ReactNode } from 'react';
+import { useState } from 'react';
+
+import { formatPercent } from '../../format/core/numbers.ts';
+import type { ChromeKey } from '../../i18n/core/chromeCatalog.ts';
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import { isEmptyIdCode } from '../core/editorValue.ts';
+import type {
+  StructureSearchExample,
+  StructureSearchMode,
+  StructureSearchQuery,
+} from '../core/structureSearch.ts';
+import {
+  STRUCTURE_SEARCH_MODES,
+  similarityThresholds,
+} from '../core/structureSearch.ts';
+
+import { StructureEditor } from './StructureEditor.tsx';
+import { useStructureDraft } from './useStructureDraft.ts';
+import { useStructureSearchModes } from './useStructureSearchModes.ts';
+
+/** What {@link StructureSearchDialog} needs. */
+export interface StructureSearchDialogProps {
+  /** Whether the dialog is on screen. */
+  isOpen: boolean;
+  /** The question the dialog opens on; its drawing is loaded into the canvas. */
+  value: StructureSearchQuery;
+  /**
+   * Called when the dialog closes — by Apply, by Escape or by its × alike —
+   * with what it then holds, so no drawing is lost to a stray Escape. The
+   * idCode is empty when the canvas was cleared.
+   */
+  onClose: (query: StructureSearchQuery) => void;
+  /**
+   * The modes offered, in order.
+   * @default STRUCTURE_SEARCH_MODES
+   */
+  modes?: readonly StructureSearchMode[];
+  /**
+   * The fragments offered under the canvas.
+   * @default benzene, pyridine, amide, sulfonamide and trifluoromethyl
+   */
+  examples?: readonly StructureSearchExample[];
+  /**
+   * More controls beside the similarity threshold, such as the fingerprint a
+   * site compares.
+   * @default undefined
+   */
+  similarityControls?: ReactNode;
+  /**
+   * Whether the dialog is rendered through a portal on `document.body`.
+   * @default true
+   */
+  usePortal?: boolean;
+}
+
+const DEFAULT_EXAMPLES: ReadonlyArray<{ key: ChromeKey; smiles: string }> = [
+  { key: 'structure.search.exampleBenzene', smiles: 'c1ccccc1' },
+  { key: 'structure.search.examplePyridine', smiles: 'c1ccncc1' },
+  { key: 'structure.search.exampleAmide', smiles: 'CC(=O)N' },
+  { key: 'structure.search.exampleSulfonamide', smiles: 'S(=O)(=O)N' },
+  { key: 'structure.search.exampleTrifluoromethyl', smiles: 'FC(F)F' },
+];
+
+/**
+ * Draw a structure and say how it is matched: contained, similar, or the same
+ * compound with or without its stereochemistry and tautomerism.
+ *
+ * What is drawn stays a draft until the dialog closes, and the canvas is never
+ * reloaded under the pen: only opening the dialog and clicking an example put
+ * a structure in it.
+ * @param props - See {@link StructureSearchDialogProps}.
+ * @returns The dialog.
+ */
+export function StructureSearchDialog(
+  props: StructureSearchDialogProps,
+): ReactElement {
+  const {
+    isOpen,
+    value,
+    onClose,
+    modes = STRUCTURE_SEARCH_MODES,
+    examples,
+    similarityControls,
+    usePortal = true,
+  } = props;
+  const t = useChromeT();
+  const modeLabels = useStructureSearchModes(modes);
+  const draft = useStructureDraft(value.idCode);
+  const [mode, setMode] = useState(value.mode);
+  const [threshold, setThreshold] = useState(value.threshold);
+  // An example is read by a lazily loaded module: until it is in the canvas,
+  // Apply would hand back the drawing it replaces.
+  const [loading, setLoading] = useState(false);
+  const offered: readonly StructureSearchExample[] =
+    examples ??
+    DEFAULT_EXAMPLES.map((example) => ({
+      label: t(example.key),
+      smiles: example.smiles,
+    }));
+
+  function close(): void {
+    const idCode = isEmptyIdCode(draft.value) ? '' : draft.value;
+    onClose({ idCode, mode, threshold });
+  }
+
+  async function loadExample(smiles: string): Promise<void> {
+    setLoading(true);
+    try {
+      const { fragmentIdCode } = await import('../core/fragmentIdCode.ts');
+      const idCode = fragmentIdCode(smiles);
+      if (idCode !== '') draft.load(idCode);
+    } finally {
+      setLoading(false);
+    }
+  }
+
+  return (
+    <Dialog
+      isOpen={isOpen}
+      onOpening={() => {
+        draft.load(value.idCode);
+        setMode(modes.includes(value.mode) ? value.mode : (modes[0] ?? mode));
+        setThreshold(value.threshold);
+      }}
+      onClose={close}
+      usePortal={usePortal}
+      title={t('structure.search.title')}
+      className="structure-search"
+    >
+      <DialogBody>
+        <div className="structure-search__row">
+          {modeLabels.map((option) => (
+            <Button
+              key={option.mode}
+              size="small"
+              active={mode === option.mode}
+              intent={mode === option.mode ? 'primary' : 'none'}
+              text={option.label}
+              title={option.help}
+              onClick={() => setMode(option.mode)}
+            />
+          ))}
+        </div>
+        {mode === 'similarity' && (
+          <div className="structure-search__row">
+            <span className="structure-search__label">
+              {t('structure.search.similarityLabel')}
+            </span>
+            <HTMLSelect
+              minimal
+              value={threshold}
+              aria-label={t('structure.search.threshold')}
+              title={t('structure.search.thresholdHelp')}
+              options={similarityThresholds(threshold).map((option) => ({
+                value: option,
+                label: t('structure.search.thresholdOption', {
+                  percent: formatPercent(option, 0),
+                }),
+              }))}
+              onChange={(event) =>
+                setThreshold(Number(event.currentTarget.value))
+              }
+            />
+            {similarityControls}
+          </div>
+        )}
+        <StructureEditor
+          fragment
+          value={draft.value}
+          revision={draft.revision}
+          onChange={(change) => draft.update(change.idCode)}
+        />
+        <div className="structure-search__row structure-search__examples">
+          <span className="structure-search__label">
+            {t('structure.search.examples')}
+          </span>
+          {offered.map((example) => (
+            <Button
+              key={example.label}
+              variant="minimal"
+              size="small"
+              text={example.label}
+              title={example.help}
+              onClick={() => void loadExample(example.smiles)}
+            />
+          ))}
+        </div>
+      </DialogBody>
+      <DialogFooter
+        actions={
+          <Button
+            intent="primary"
+            icon="search"
+            text={t('structure.search.apply')}
+            loading={loading}
+            onClick={close}
+          />
+        }
+      />
+    </Dialog>
+  );
+}

package/src/structure/ui/StructureSvg.tsx

@@ -17,6 +17,7 @@ import type { AtomLabelPlacement } from '../core/atomLabels.ts';
 import { applyAtomLabels } from '../core/atomLabels.ts';
 import { sourceMolecule } from '../core/sourceMolecule.ts';
 import type { StructureSource } from '../core/structureSource.ts';
+import { substructureMatch } from '../core/substructureMatch.ts';
 
 import { StructurePlaceholder } from './StructurePlaceholder.tsx';
 
@@ -46,6 +47,15 @@ interface StructureSvgProps {
   bondHighlight?: number[];
   /** The colour the highlighted bonds are painted. */
   bondHighlightColor: string;
+  /**
+   * A query idCode whose matches are painted in place of the highlights.
+   * @default undefined
+   */
+  substructure?: string;
+  /** The colour the substructure match is painted. */
+  substructureColor: string;
+  /** How opaque the substructure match is painted, from 0 to 1. */
+  substructureOpacity: number;
   /** Write the index of every atom next to it. */
   showAtomNumber: boolean;
   /** Write the index of every bond next to it. */
@@ -94,6 +104,13 @@ export function StructureSvg(props: StructureSvgProps): ReactElement {
     onAtomClick,
     onBondClick,
     showCIPParity,
+    atomHighlight,
+    atomHighlightColor,
+    bondHighlight,
+    bondHighlightColor,
+    substructure,
+    substructureColor,
+    substructureOpacity,
     ...rest
   } = props;
   const { kind, value, coordinates } = source;
@@ -106,6 +123,14 @@ export function StructureSvg(props: StructureSvgProps): ReactElement {
     () => readDrawing(kind, value, coordinates, labelsKey, atomLabelPlacement),
     [kind, value, coordinates, labelsKey, atomLabelPlacement],
   );
+  // Matched on the very molecule drawn, so the indices are the drawn atoms.
+  const match = useMemo(
+    () =>
+      drawing === null || substructure === undefined
+        ? null
+        : substructureMatch(drawing.molecule, substructure),
+    [drawing, substructure],
+  );
 
   if (drawing === null) {
     return (
@@ -118,6 +143,16 @@ export function StructureSvg(props: StructureSvgProps): ReactElement {
   return (
     <SvgRenderer
       {...rest}
+      atomHighlight={match === null ? atomHighlight : match.atoms}
+      atomHighlightColor={
+        match === null ? atomHighlightColor : substructureColor
+      }
+      bondHighlight={match === null ? bondHighlight : match.bonds}
+      bondHighlightColor={
+        match === null ? bondHighlightColor : substructureColor
+      }
+      atomHighlightOpacity={match === null ? undefined : substructureOpacity}
+      bondHighlightOpacity={match === null ? undefined : substructureOpacity}
       molecule={drawing.molecule}
       noCarbonLabelWithCustomLabel={drawing.labelled}
       suppressCIPParity={!showCIPParity}

package/src/structure/ui/index.ts

@@ -25,6 +25,10 @@ export type { StructureDropProps } from './StructureDrop.tsx';
 export { StructureDrop } from './StructureDrop.tsx';
 export type { StructureEditorHelpProps } from './StructureEditorHelp.tsx';
 export { StructureEditorHelp } from './StructureEditorHelp.tsx';
+export type { StructureSearchDialogProps } from './StructureSearchDialog.tsx';
+export { StructureSearchDialog } from './StructureSearchDialog.tsx';
+export type { StructureSearchModeLabel } from './useStructureSearchModes.ts';
+export { useStructureSearchModes } from './useStructureSearchModes.ts';
 export type { StructureExportDialogProps } from './StructureExportDialog.tsx';
 export { StructureExportDialog } from './StructureExportDialog.tsx';
 export type { StructureExportButtonProps } from './StructureExportButton.tsx';

package/src/structure/ui/useStructureSearchModes.ts

@@ -0,0 +1,51 @@
+import type { ChromeKey } from '../../i18n/core/chromeCatalog.ts';
+import { useChromeT } from '../../i18n/ui/useT.ts';
+import type { StructureSearchMode } from '../core/structureSearch.ts';
+import { STRUCTURE_SEARCH_MODES } from '../core/structureSearch.ts';
+
+/** A mode, with what a button says and what its tooltip adds. */
+export interface StructureSearchModeLabel {
+  /** The mode. */
+  mode: StructureSearchMode;
+  /** What the button says. */
+  label: string;
+  /** One line on what the mode finds. */
+  help: string;
+}
+
+const MODE_KEYS: Record<StructureSearchMode, [ChromeKey, ChromeKey]> = {
+  substructure: [
+    'structure.search.substructure',
+    'structure.search.substructureHelp',
+  ],
+  similarity: [
+    'structure.search.similarity',
+    'structure.search.similarityHelp',
+  ],
+  exact: ['structure.search.exact', 'structure.search.exactHelp'],
+  exactNoStereo: [
+    'structure.search.exactNoStereo',
+    'structure.search.exactNoStereoHelp',
+  ],
+  exactNoStereoTautomer: [
+    'structure.search.exactNoStereoTautomer',
+    'structure.search.exactNoStereoTautomerHelp',
+  ],
+};
+
+/**
+ * The modes in the reader's language, for a site that shows the mode in force
+ * beside the drawing.
+ * @param modes - The modes, in order.
+ * @returns Each mode with its label and its one-line help.
+ */
+export function useStructureSearchModes(
+  modes: readonly StructureSearchMode[] = STRUCTURE_SEARCH_MODES,
+): StructureSearchModeLabel[] {
+  const t = useChromeT();
+  return modes.map((mode) => ({
+    mode,
+    label: t(MODE_KEYS[mode][0]),
+    help: t(MODE_KEYS[mode][1]),
+  }));
+}

package/styles/chrome.css

@@ -889,6 +889,37 @@ a.source-badge:hover {
   }
 }
 
+/* The structure search dialog: the modes above the canvas, the fragments to
+   start from under it. A drag on the canvas that leaves it would otherwise
+   select the labels. */
+.structure-search {
+  width: min(56rem, calc(100vw - 2rem));
+  user-select: none;
+}
+
+.structure-search :is(input, textarea) {
+  user-select: text;
+}
+
+.structure-search__row {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  margin-bottom: 0.6rem;
+  gap: 0.35rem;
+}
+
+.structure-search__examples {
+  margin-top: 0.6rem;
+  margin-bottom: 0;
+}
+
+.structure-search__label {
+  margin-right: 0.25rem;
+  color: var(--text-muted);
+  font-size: 0.8125rem;
+}
+
 /* ── Tokens for molecules.cheminfo.org ─────────────────────────────────────── */
 
 /* The heading, when the tokens were checked, and the button asking again, on