react-cheminfo 0.28.0 → 0.30.0

package/src/panel/ui/useConfirmOnEnter.ts

@@ -0,0 +1,68 @@
+/**
+ * Enter as the answer to whatever a dialog is asking.
+ */
+
+import { useEffect, useLayoutEffect, useRef } from 'react';
+
+/**
+ * Run a dialog's primary action when Enter is pressed while it is open.
+ *
+ * On the document rather than on the dialog's own subtree, because an open
+ * overlay holds the focus on a container above the content, so a press never
+ * reaches a handler put on the body. Esc needs nothing of the sort: Blueprint
+ * closes an overlay on it already.
+ *
+ * A press that something else has a use for is left alone — a button under the
+ * focus is activated by Enter on its own, and a newline typed into a text area
+ * is a newline — so the shortcut never fires twice or eats what was typed.
+ * @param isOpen - Whether the dialog is showing.
+ * @param onConfirm - Its primary action, the one the footer button runs.
+ */
+export function useConfirmOnEnter(
+  isOpen: boolean,
+  onConfirm: () => void,
+): void {
+  // Held in a ref so a caller passing a fresh closure on every render does not
+  // have the listener taken down and put back up.
+  const current = useRef(onConfirm);
+  useLayoutEffect(() => {
+    current.current = onConfirm;
+  });
+
+  useEffect(() => {
+    if (!isOpen) return;
+
+    function handleKeyDown(event: KeyboardEvent) {
+      if (event.key !== 'Enter' || event.defaultPrevented) return;
+      if (event.shiftKey || event.altKey || event.ctrlKey || event.metaKey) {
+        return;
+      }
+      if (activatesOnEnter(event.target) || takesNewlines(event.target)) return;
+      event.preventDefault();
+      current.current();
+    }
+
+    document.addEventListener('keydown', handleKeyDown);
+    return () => document.removeEventListener('keydown', handleKeyDown);
+  }, [isOpen]);
+}
+
+/**
+ * Whether Enter is already the way to work what the press was delivered to.
+ * @param target - What the event was delivered to.
+ * @returns Whether it runs itself on Enter.
+ */
+function activatesOnEnter(target: EventTarget | null): boolean {
+  if (!(target instanceof Element)) return false;
+  return target.closest('a[href], button, summary, [role="button"]') !== null;
+}
+
+/**
+ * Whether the press is a newline being typed rather than an answer.
+ * @param target - What the event was delivered to.
+ * @returns Whether it should be left alone.
+ */
+function takesNewlines(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  return target.isContentEditable || target.tagName === 'TEXTAREA';
+}

package/src/panel/ui/useFilterBox.ts

@@ -0,0 +1,35 @@
+import { useState } from 'react';
+
+/** The filter box of a panel, and the toolbar item that reveals it. */
+export interface FilterBox {
+  /** What the user typed, empty while nothing is filtered out. */
+  filter: string;
+  /** Called with what the user typed. */
+  setFilter: (filter: string) => void;
+  /** Whether the box is showing. */
+  showFilter: boolean;
+  /** Reveals the box, or hides it and drops what was typed. */
+  toggleFilter: () => void;
+}
+
+/**
+ * A filter box that is out of the way until it is asked for.
+ *
+ * Closing it drops what was typed, because a box that is out of sight can no
+ * longer explain why half the list is missing — which is the one rule every
+ * panel offering a filter has to keep, so it is kept here rather than in each
+ * of them.
+ * @param defaultShowFilter - Whether the box is open to begin with.
+ * @returns The state of the box, and the toggle a toolbar item calls.
+ */
+export function useFilterBox(defaultShowFilter = false): FilterBox {
+  const [filter, setFilter] = useState('');
+  const [showFilter, setShowFilter] = useState(defaultShowFilter);
+
+  function toggleFilter() {
+    if (showFilter) setFilter('');
+    setShowFilter(!showFilter);
+  }
+
+  return { filter, setFilter, showFilter, toggleFilter };
+}

package/src/panel/ui/useVirtualRows.ts

@@ -0,0 +1,82 @@
+import { useVirtualizer } from '@tanstack/react-virtual';
+import type { RefObject } from 'react';
+
+import type { RowSpacers } from '../core/rowSpacers.ts';
+import { rowSpacers } from '../core/rowSpacers.ts';
+
+/** Which rows a scrolled table draws, and the empty room around them. */
+export interface VirtualRows extends RowSpacers {
+  /** The indices of the rows to draw, in the order they are listed. */
+  indices: number[];
+  /**
+   * What a drawn row reports its height through, as its `ref`. A row also has
+   * to carry `data-index`, which is how the measurement finds its way back to
+   * the row it was taken from.
+   *
+   * Any element, not a `<tr>`: a peak table's rows are table rows, while a
+   * fragment list's are `<div>`s carrying a drawing, and both are measured the
+   * same way.
+   */
+  measure: (node: HTMLElement | null) => void;
+}
+
+/**
+ * Draw only the rows the scroll region is showing, however long the list is.
+ *
+ * A peak table is a few hundred rows at rest and several thousand once the
+ * window is opened onto the whole spectrum, and every one of those rows is four
+ * cells the browser lays out, styles and keeps — a cost paid on the sort, on the
+ * filter, and on every zoom, for rows nobody is looking at. Drawing the twenty
+ * or so in view and standing two empty rows in for the rest makes that cost the
+ * size of the panel rather than the size of the spectrum.
+ *
+ * The rows are measured rather than assumed: a row is a line of text, so its
+ * height follows the font the page is rendered at and a hard-coded one would
+ * put the end of a five thousand row list several screens away from the bottom
+ * of the scrollbar. `estimatedRowHeight` is only what the list is worth before
+ * a single row has been drawn.
+ *
+ * The table header scrolls inside the same region and is not part of the list,
+ * so the rows really sit one header lower than this reckons. It is left that
+ * way deliberately: the overscan already draws more rows than are in view, on
+ * both sides, and it absorbs a header's worth of offset without the extra
+ * measurement — and without the render that measuring it would cost on the way
+ * to the same picture.
+ * @param scrollRef - The region the rows scroll in.
+ * @param count - How many rows the list holds.
+ * @param estimatedRowHeight - What one row is worth until one has been drawn.
+ * @returns The rows to draw and the spacers standing in for the others.
+ */
+export function useVirtualRows(
+  scrollRef: RefObject<HTMLDivElement | null>,
+  count: number,
+  estimatedRowHeight: number,
+): VirtualRows {
+  const virtualizer = useVirtualizer({
+    count,
+    getScrollElement: () => scrollRef.current,
+    estimateSize: () => estimatedRowHeight,
+    overscan: OVERSCAN,
+  });
+
+  const drawn = virtualizer.getVirtualItems();
+  const indices = new Array<number>(drawn.length);
+  for (let position = 0; position < drawn.length; position++) {
+    indices[position] = (drawn[position] as { index: number }).index;
+  }
+
+  return {
+    indices,
+    ...rowSpacers(drawn, virtualizer.getTotalSize()),
+    measure: virtualizer.measureElement,
+  };
+}
+
+/**
+ * How many rows are drawn beyond each end of the region.
+ *
+ * Enough that a wheel gesture or a drag of the scrollbar never reaches the edge
+ * of what was drawn before the next render has run, and enough to cover the
+ * header the list is offset by.
+ */
+const OVERSCAN = 12;

package/src/panel/ui/useVirtualWindowRows.ts

@@ -0,0 +1,86 @@
+/**
+ * Drawing only the rows the page is showing, for a list that scrolls with it.
+ *
+ * `useVirtualRows` measures a scroll region of its own, which is what a panel
+ * beside a chart has. A table filling a tab has none: it flows down the document
+ * and the browser window is what scrolls it, so giving the list its own
+ * `overflow` would grow a second scrollbar inside the first and cap the table at
+ * whatever height it was handed — a layout change made to serve the virtualiser
+ * rather than the reader.
+ */
+
+import { useWindowVirtualizer } from '@tanstack/react-virtual';
+import { useCallback, useState } from 'react';
+
+import { rowSpacers } from '../core/rowSpacers.ts';
+
+import type { VirtualRows } from './useVirtualRows.ts';
+
+/** The rows to draw, and what the list reports its own position through. */
+export interface VirtualWindowRows extends VirtualRows {
+  /**
+   * What the element holding the rows reports its position through, as its
+   * `ref`. Without it every offset is reckoned from the top of the document and
+   * the wrong rows are drawn, by however tall whatever sits above the list is.
+   */
+  measureList: (node: HTMLElement | null) => void;
+}
+
+/**
+ * Draw only the rows the page is showing, however long the list is.
+ *
+ * The rows are measured against the window, so the list only has to say how far
+ * down the page it begins — which is what the virtualiser calls its scroll
+ * margin, and what `measureList` reports.
+ *
+ * That position is read in a ref callback rather than in an effect, which is
+ * how `useChartSize` reads a box for the same reason: the node is the only
+ * thing the measurement needs, so it is taken the moment React has one and
+ * taken again whenever it hands over another. A filter that cuts a thousand
+ * rows to fifty changes how tall the list is and not where it starts, so there
+ * is nothing to remeasure when the count moves.
+ * @param count - How many rows the list holds.
+ * @param estimatedRowHeight - What one row is worth until one has been drawn.
+ * @returns The rows to draw, the spacers standing in for the others, and the
+ * ref the list reports its position through.
+ */
+export function useVirtualWindowRows(
+  count: number,
+  estimatedRowHeight: number,
+): VirtualWindowRows {
+  const [scrollMargin, setScrollMargin] = useState(0);
+
+  const measureList = useCallback((node: HTMLElement | null) => {
+    if (node === null) return;
+    setScrollMargin(node.getBoundingClientRect().top + window.scrollY);
+  }, []);
+
+  const virtualizer = useWindowVirtualizer({
+    count,
+    estimateSize: () => estimatedRowHeight,
+    overscan: OVERSCAN,
+    scrollMargin,
+  });
+
+  const drawn = virtualizer.getVirtualItems();
+  const indices = new Array<number>(drawn.length);
+  for (let position = 0; position < drawn.length; position++) {
+    indices[position] = (drawn[position] as { index: number }).index;
+  }
+
+  return {
+    indices,
+    ...rowSpacers(drawn, virtualizer.getTotalSize()),
+    measure: virtualizer.measureElement,
+    measureList,
+  };
+}
+
+/**
+ * How many rows are drawn beyond each end of the window.
+ *
+ * The same reasoning as `useVirtualRows`, and the same number: enough that a
+ * wheel gesture never reaches the edge of what was drawn before the next render
+ * has run.
+ */
+const OVERSCAN = 12;

package/src/structure/core/conformerBoltzmann.ts

@@ -0,0 +1,102 @@
+/**
+ * How a set of conformers divides itself between its minima at a temperature.
+ *
+ * Each conformer in the list is one minimum of the surface, so the share of
+ * molecules sitting in it is its Boltzmann factor over the sum of them all.
+ * Mirror-image conformers are separate entries and therefore counted twice,
+ * which is right: they are two distinct microstates, and that is what makes
+ * butane two-thirds gauche at room temperature rather than one-half.
+ *
+ * What this is not: a free energy. The weights come from a single energy per
+ * conformer, with no vibrational entropy, no zero-point energy and no solvent,
+ * so a share is the shape of the answer rather than the answer. It is also only
+ * as good as the energies handed to it — see {@link boltzmannConfidence}, which
+ * is what a table showing these shares says out loud.
+ */
+
+/** Room temperature, in kelvin, and what a share is quoted at unless asked otherwise. */
+export const ROOM_TEMPERATURE = 300;
+
+/**
+ * The gas constant in kcal/(mol·K), matching MMFF94's own energy unit.
+ *
+ * At {@link ROOM_TEMPERATURE} this makes RT 0.596 kcal/mol, so a conformer one
+ * kcal/mol up is populated about a fifth as much as the lowest.
+ */
+export const GAS_CONSTANT = 0.001_987_204_259;
+
+/**
+ * The share of molecules in each conformer at thermal equilibrium.
+ *
+ * The energies are taken relative to whichever is lowest, so they may be
+ * absolute or already relative. A conformer whose energy is unknown takes no
+ * share and is left out of the sum: it cannot be placed on the surface, and
+ * spreading the remainder over the others is a smaller lie than inventing a
+ * weight for it.
+ * @param energies - One energy per conformer in kcal/mol, `null` where unknown.
+ * @param temperature - Temperature in kelvin.
+ * @default ROOM_TEMPERATURE
+ * @returns One share per conformer, from 0 to 1 and summing to 1 over the ones
+ * that have an energy; `null` wherever the energy was `null`.
+ */
+export function boltzmannShares(
+  energies: ReadonlyArray<number | null>,
+  temperature: number = ROOM_TEMPERATURE,
+): Array<number | null> {
+  const shares: Array<number | null> = new Array(energies.length).fill(null);
+  if (energies.length === 0) return shares;
+
+  let lowest = Number.POSITIVE_INFINITY;
+  for (const energy of energies) {
+    if (energy !== null && Number.isFinite(energy) && energy < lowest) {
+      lowest = energy;
+    }
+  }
+  if (lowest === Number.POSITIVE_INFINITY) return shares;
+
+  // Measured from the lowest, so every exponent is at most zero and the sum
+  // cannot overflow however far apart the energies are.
+  const rt = GAS_CONSTANT * temperature;
+  if (!(rt > 0)) return shares;
+
+  const factors: Array<number | null> = new Array(energies.length).fill(null);
+  let total = 0;
+  for (let index = 0; index < energies.length; index++) {
+    const energy = energies[index] ?? null;
+    if (energy === null || !Number.isFinite(energy)) continue;
+    const factor = Math.exp(-(energy - lowest) / rt);
+    factors[index] = factor;
+    total += factor;
+  }
+  if (total === 0) return shares;
+
+  for (let index = 0; index < factors.length; index++) {
+    const factor = factors[index] ?? null;
+    if (factor !== null) shares[index] = factor / total;
+  }
+  return shares;
+}
+
+/**
+ * The factor a share is uncertain by, given how well the energies behind it are
+ * known.
+ *
+ * A population is exponential in the energy gap, so an error in a relative
+ * energy is an error in a share by `exp(error / RT)` — and RT is 0.596 kcal/mol
+ * at {@link ROOM_TEMPERATURE}. A force field that ranks conformers to within
+ * about 1.5 kcal/mol therefore places a population to within a factor of
+ * roughly twelve, which is why a share read off one is a shape and not a
+ * number.
+ * @param energyError - The typical error of a relative energy, kcal/mol.
+ * @param temperature - Temperature in kelvin.
+ * @default ROOM_TEMPERATURE
+ * @returns The multiplicative factor, at least 1.
+ */
+export function boltzmannConfidence(
+  energyError: number,
+  temperature: number = ROOM_TEMPERATURE,
+): number {
+  const rt = GAS_CONSTANT * temperature;
+  if (!(rt > 0) || !Number.isFinite(energyError) || energyError <= 0) return 1;
+  return Math.exp(energyError / rt);
+}

package/src/structure/core/conformerEnergy.ts

@@ -0,0 +1,97 @@
+/**
+ * Which energy of a conformer a reader is being shown.
+ *
+ * A refined conformer carries two of everything — what the force field said and
+ * what the better method said afterwards — and a table that mixes them is a
+ * ranking of nothing. So every column reads through one of these, and they all
+ * take the same ranking.
+ */
+
+// Type-only, so nothing here pulls the generator — or openchemlib — into
+// `react-cheminfo/core`, which every page loads.
+import type { ConformerRanking } from './conformers.ts';
+
+/**
+ * What a refinement has to say for an energy column to read it.
+ *
+ * The structural minimum rather than the whole `ConformerRefinement`, so a site
+ * that carries its conformers in a shape of its own — positions instead of a
+ * molfile, say — can still be read by the same helpers and drawn by the same
+ * table.
+ */
+export interface ConformerRowRefinement {
+  /** The rank this conformer held before the refinement reordered the set. */
+  forceFieldId: number;
+  /** Total energy at the relaxed geometry, kcal/mol. */
+  energy: number;
+  /** Energy above the most stable refined conformer, kcal/mol. */
+  relativeEnergy: number;
+}
+
+/**
+ * The least a conformer must carry to be ranked and drawn.
+ *
+ * `Conformer` from `react-cheminfo/conformers` satisfies it, and so does any
+ * per-site record that keeps the same three numbers.
+ */
+export interface ConformerRow {
+  /** 1-based rank in the set, most stable first. */
+  id: number;
+  /** Total force-field energy in kcal/mol, `null` when not computed. */
+  energy: number | null;
+  /** Energy above the most stable conformer, `null` without an energy. */
+  relativeEnergy: number | null;
+  /**
+   * What a better method said, once the set has been refined.
+   * @default null
+   */
+  refinement?: ConformerRowRefinement | null;
+}
+
+/**
+ * The energy above the most stable conformer, in the ranking asked for.
+ * @param conformer - The conformer to read.
+ * @param ranking - Which method's energies to read.
+ * @default 'force-field'
+ * @returns kcal/mol above the lowest, or `null` when that method produced none.
+ */
+export function relativeEnergyOf(
+  conformer: ConformerRow,
+  ranking: ConformerRanking = 'force-field',
+): number | null {
+  return ranking === 'refined'
+    ? (conformer.refinement?.relativeEnergy ?? null)
+    : conformer.relativeEnergy;
+}
+
+/**
+ * The total energy, in the ranking asked for, so the two columns of a row
+ * describe one method.
+ * @param conformer - The conformer to read.
+ * @param ranking - Which method's energies to read.
+ * @default 'force-field'
+ * @returns kcal/mol, or `null` when that method produced none.
+ */
+export function totalEnergyOf(
+  conformer: ConformerRow,
+  ranking: ConformerRanking = 'force-field',
+): number | null {
+  return ranking === 'refined'
+    ? (conformer.refinement?.energy ?? null)
+    : conformer.energy;
+}
+
+/**
+ * The ranking a set should be read in: refined once anything has been refined,
+ * the force field's until then.
+ * @param conformers - The set to inspect.
+ * @returns `'refined'` when at least one conformer carries a refinement.
+ */
+export function bestRanking(
+  conformers: readonly ConformerRow[],
+): ConformerRanking {
+  for (const conformer of conformers) {
+    if (conformer.refinement != null) return 'refined';
+  }
+  return 'force-field';
+}

package/src/structure/core/index.ts

@@ -1,5 +1,20 @@
 export type { AtomLabelPlacement, LabelledMolecule } from './atomLabels.ts';
 export { applyAtomLabels, customAtomLabel } from './atomLabels.ts';
+export {
+  GAS_CONSTANT,
+  ROOM_TEMPERATURE,
+  boltzmannConfidence,
+  boltzmannShares,
+} from './conformerBoltzmann.ts';
+export type {
+  ConformerRow,
+  ConformerRowRefinement,
+} from './conformerEnergy.ts';
+export {
+  bestRanking,
+  relativeEnergyOf,
+  totalEnergyOf,
+} from './conformerEnergy.ts';
 export type {
   EditorGesture,
   EditorGuideKey,