react-cheminfo 0.10.0 → 0.12.0

package/src/molecule3d/core/gestures.ts

@@ -0,0 +1,35 @@
+/**
+ * What the mouse and the keyboard do on the molecule canvas: molstar's default
+ * trackball and focus bindings, which the viewer keeps.
+ */
+
+/** A key, drawn as a key cap. */
+export interface Molecule3DGestureKey {
+  key: string;
+}
+
+/** One gesture and what it does. */
+export interface Molecule3DGesture {
+  /** Keys, and plain text for the mouse part; unique within one gesture. */
+  input: ReadonlyArray<string | Molecule3DGestureKey>;
+  action: string;
+}
+
+/** The gestures, in the order the help popover lists them. */
+export const MOLECULE_3D_GESTURES: readonly Molecule3DGesture[] = [
+  { input: ['Drag'], action: 'Rotate' },
+  {
+    input: [{ key: 'Shift' }, '+', { key: 'Ctrl' }, '+ drag'],
+    action: 'Rotate in the plane of the screen',
+  },
+  {
+    input: [{ key: 'Q' }, 'or', { key: 'E' }],
+    action: 'Rotate in the plane, while held',
+  },
+  { input: ['Right-drag'], action: 'Move' },
+  { input: [{ key: 'Ctrl' }, '+ drag'], action: 'Move' },
+  { input: ['Scroll'], action: 'Zoom' },
+  { input: [{ key: 'Shift' }, '+ scroll'], action: 'Clip around the centre' },
+  { input: ['Click an atom'], action: 'Centre on it' },
+  { input: ['Click the background'], action: 'Centre on the molecule' },
+];

package/src/molecule3d/core/index.ts

@@ -0,0 +1,35 @@
+export type { ImageSize } from './exportImage.ts';
+export { dataUriBytes, rasterSvgMarkup } from './exportImage.ts';
+export type { Molecule3DGesture, Molecule3DGestureKey } from './gestures.ts';
+export { MOLECULE_3D_GESTURES } from './gestures.ts';
+export type {
+  AtomReference,
+  Measurement,
+  MeasurementKind,
+} from './measurement.ts';
+export {
+  MEASUREMENT_ATOM_COUNTS,
+  MEASUREMENT_KINDS,
+  MEASUREMENT_LABELS,
+} from './measurement.ts';
+export type {
+  Molecule3DFile,
+  Molecule3DSettings,
+  Molecule3DTools,
+  RepresentationId,
+  SurfaceColoringId,
+} from './settings.ts';
+export {
+  DEFAULT_MOLECULE_3D_SETTINGS,
+  DEFAULT_MOLECULE_3D_TOOLS,
+  MOLECULE_3D_RANGES,
+  REPRESENTATIONS,
+  REPRESENTATION_LABELS,
+  SURFACE_CHARGE_COLORS,
+  SURFACE_COLORINGS,
+  SURFACE_COLORING_LABELS,
+  isRepresentationId,
+  isSurfaceColoringId,
+  normalizeMolecule3DSettings,
+  resolveMolecule3DTools,
+} from './settings.ts';

package/src/molecule3d/core/measurement.ts

@@ -0,0 +1,43 @@
+/**
+ * What a measurement on a 3D molecule is, without React and without molstar,
+ * so a site can store, persist or share measurements on its own.
+ *
+ * Atoms are named by position rather than by molstar loci, so a measurement
+ * taken on one conformer lands on the same atoms of every other conformer of
+ * the same molecule — which is what lets a reader watch a dihedral change down
+ * a list of conformers.
+ */
+
+/** The three geometric measurements, in the order the toolbar offers them. */
+export const MEASUREMENT_KINDS = ['distance', 'angle', 'dihedral'] as const;
+
+/** One of {@link MEASUREMENT_KINDS}. */
+export type MeasurementKind = (typeof MEASUREMENT_KINDS)[number];
+
+/** How many atoms each kind is measured between. */
+export const MEASUREMENT_ATOM_COUNTS: Record<MeasurementKind, number> = {
+  distance: 2,
+  angle: 3,
+  dihedral: 4,
+};
+
+/** What the toolbar calls each kind. */
+export const MEASUREMENT_LABELS: Record<MeasurementKind, string> = {
+  distance: 'Distance',
+  angle: 'Angle',
+  dihedral: 'Dihedral angle',
+};
+
+/** One atom of the displayed structure, by position. */
+export interface AtomReference {
+  /** Index of the unit in molstar's `structure.units`; 0 for a molfile. */
+  unit: number;
+  /** Index of the atom inside that unit. */
+  element: number;
+}
+
+/** One measurement, with its atoms in the order they were picked. */
+export interface Measurement {
+  kind: MeasurementKind;
+  atoms: readonly AtomReference[];
+}

package/src/molecule3d/core/settings.ts

@@ -0,0 +1,214 @@
+/**
+ * The display settings of the 3D molecule viewer and the toolbar it carries,
+ * free of React and molstar so a site can persist and validate them.
+ */
+
+/** A molfile for the viewer, with the parser molstar has to read it with. */
+export interface Molecule3DFile {
+  /** molstar's format id: `mol` reads V2000, `sdf` reads V2000 and V3000. */
+  format: 'mol' | 'sdf';
+  /** The molfile text. It must carry 3D coordinates. */
+  data: string;
+}
+
+/** Ways the model can be drawn, in the order the picker offers them. */
+export const REPRESENTATIONS = [
+  'ball-and-stick',
+  'spacefill',
+  'stick',
+] as const;
+
+/** One of {@link REPRESENTATIONS}. */
+export type RepresentationId = (typeof REPRESENTATIONS)[number];
+
+/** Human names for the representation picker. */
+export const REPRESENTATION_LABELS: Record<RepresentationId, string> = {
+  'ball-and-stick': 'Ball and stick',
+  spacefill: 'Spacefill',
+  stick: 'Sticks',
+};
+
+/** Ways the surface can be coloured, in the order the picker offers them. */
+export const SURFACE_COLORINGS = ['uniform', 'element', 'polarity'] as const;
+
+/** One of {@link SURFACE_COLORINGS}. */
+export type SurfaceColoringId = (typeof SURFACE_COLORINGS)[number];
+
+/** Human names for the surface colouring picker. */
+export const SURFACE_COLORING_LABELS: Record<SurfaceColoringId, string> = {
+  uniform: 'Uniform',
+  element: 'Element',
+  polarity: 'Polarity',
+};
+
+/** How the model and its surface are drawn. */
+export interface Molecule3DSettings {
+  representation: RepresentationId;
+  /** Radius multiplier; 1 is the size each representation picks for itself. */
+  sizeFactor: number;
+  /** Whether the translucent molecular surface is drawn over the model. */
+  showSurface: boolean;
+  /** Surface opacity; below 1 the model stays visible inside it. */
+  surfaceAlpha: number;
+  /** Radius of the solvent probe rolled over the atoms, ångström. */
+  probeRadius: number;
+  /**
+   * `uniform` paints the surface in `surfaceColor`, `element` in the colour of
+   * the nearest atom, `polarity` in the fixed {@link SURFACE_CHARGE_COLORS}.
+   */
+  surfaceColoring: SurfaceColoringId;
+  /** Surface colour in `uniform` mode, `#rrggbb`. */
+  surfaceColor: string;
+}
+
+/**
+ * The colours of `polarity` mode. Positive: cations, and hydrogens bonded to
+ * nitrogen or oxygen. Negative: anions, nitrogen and oxygen. Neutral: the rest.
+ * Scene colours: WebGL cannot read a CSS custom property.
+ */
+export const SURFACE_CHARGE_COLORS = {
+  positive: '#dc2626', // tokens-ok
+  negative: '#2563eb', // tokens-ok
+  neutral: '#9ca3af', // tokens-ok
+} as const;
+
+/** What the viewer draws when a site does not say. */
+export const DEFAULT_MOLECULE_3D_SETTINGS: Molecule3DSettings = {
+  representation: 'ball-and-stick',
+  sizeFactor: 1,
+  showSurface: false,
+  surfaceAlpha: 0.5,
+  probeRadius: 1.4,
+  surfaceColoring: 'uniform',
+  // A scene colour: WebGL cannot read a CSS custom property.
+  surfaceColor: '#94a3b8', // tokens-ok
+};
+
+/** The span, and the slider step, of every numeric setting. */
+export const MOLECULE_3D_RANGES = {
+  sizeFactor: { minimum: 0.2, maximum: 2, step: 0.1 },
+  surfaceAlpha: { minimum: 0.1, maximum: 1, step: 0.05 },
+  probeRadius: { minimum: 1, maximum: 3, step: 0.1 },
+} as const;
+
+/** Which buttons the toolbar over the canvas shows. */
+export interface Molecule3DTools {
+  /** Distance, angle and dihedral tools, and a button removing them all. */
+  measure: boolean;
+  /** A popover with the representation, the size and the surface sliders. */
+  options: boolean;
+  /** A toggle turning the model on its own. */
+  spin: boolean;
+  /** A toggle drawing the molecular surface. */
+  surface: boolean;
+  /** A button framing the model again. */
+  reset: boolean;
+  /** A popover saving the picture as a PNG or an SVG. */
+  export: boolean;
+  /** A popover listing what the mouse and the keyboard do on the canvas. */
+  help: boolean;
+}
+
+/** Every tool on. */
+export const DEFAULT_MOLECULE_3D_TOOLS: Molecule3DTools = {
+  measure: true,
+  options: true,
+  spin: true,
+  surface: true,
+  reset: true,
+  export: true,
+  help: true,
+};
+
+/**
+ * Narrow an arbitrary string — a stored preference, a picker's value — to a
+ * representation.
+ * @param value - Candidate representation id.
+ * @returns True when it is one of {@link REPRESENTATIONS}.
+ */
+export function isRepresentationId(value: string): value is RepresentationId {
+  for (const representation of REPRESENTATIONS) {
+    if (representation === value) return true;
+  }
+  return false;
+}
+
+/**
+ * Narrow an arbitrary string to a surface colouring.
+ * @param value - Candidate colouring id.
+ * @returns True when it is one of {@link SURFACE_COLORINGS}.
+ */
+export function isSurfaceColoringId(value: string): value is SurfaceColoringId {
+  for (const coloring of SURFACE_COLORINGS) {
+    if (coloring === value) return true;
+  }
+  return false;
+}
+
+/**
+ * Complete and repair settings from any source: missing fields take their
+ * default, numbers are clamped into {@link MOLECULE_3D_RANGES}, an unknown
+ * representation or colouring falls back to the default one, and a colour that
+ * is not `#rrggbb` to its default.
+ * @param settings - Whatever a site has, possibly read back from storage.
+ * @returns Settings the viewer can draw.
+ */
+export function normalizeMolecule3DSettings(
+  settings: Partial<Molecule3DSettings> = {},
+): Molecule3DSettings {
+  const defaults = DEFAULT_MOLECULE_3D_SETTINGS;
+  const {
+    representation,
+    sizeFactor,
+    showSurface,
+    surfaceAlpha,
+    probeRadius,
+    surfaceColoring,
+    surfaceColor,
+  } = settings;
+  return {
+    representation:
+      typeof representation === 'string' && isRepresentationId(representation)
+        ? representation
+        : defaults.representation,
+    sizeFactor: clamp(sizeFactor, 'sizeFactor'),
+    showSurface:
+      typeof showSurface === 'boolean' ? showSurface : defaults.showSurface,
+    surfaceAlpha: clamp(surfaceAlpha, 'surfaceAlpha'),
+    probeRadius: clamp(probeRadius, 'probeRadius'),
+    surfaceColoring:
+      typeof surfaceColoring === 'string' &&
+      isSurfaceColoringId(surfaceColoring)
+        ? surfaceColoring
+        : defaults.surfaceColoring,
+    surfaceColor: hexColor(surfaceColor, defaults.surfaceColor),
+  };
+}
+
+/**
+ * Complete a partial tool selection.
+ * @param tools - The tools a site switched on or off.
+ * @returns Every tool, those not named left on.
+ */
+export function resolveMolecule3DTools(
+  tools: Partial<Molecule3DTools> = {},
+): Molecule3DTools {
+  return { ...DEFAULT_MOLECULE_3D_TOOLS, ...tools };
+}
+
+function hexColor(value: string | undefined, fallback: string): string {
+  return typeof value === 'string' && /^#[\da-f]{6}$/i.test(value)
+    ? value.toLowerCase()
+    : fallback;
+}
+
+function clamp(
+  value: number | undefined,
+  key: keyof typeof MOLECULE_3D_RANGES,
+): number {
+  if (typeof value !== 'number' || !Number.isFinite(value)) {
+    return DEFAULT_MOLECULE_3D_SETTINGS[key];
+  }
+  const { minimum, maximum } = MOLECULE_3D_RANGES[key];
+  return Math.min(Math.max(value, minimum), maximum);
+}

package/src/molecule3d/ui/Molecule3DExport.tsx

@@ -0,0 +1,65 @@
+/**
+ * The export popover of the molecule viewer: the family's figure-saving panel,
+ * fed by a render of the WebGL scene rather than by the SVG on the page.
+ */
+
+import type { ReactElement } from 'react';
+import { useState } from 'react';
+
+import type { FigureFormat } from '../../download/core/downloadFigure.ts';
+import type { FigurePixels } from '../../download/core/figureScale.ts';
+import {
+  DEFAULT_FIGURE_SCALE,
+  FIGURE_SCALES,
+} from '../../download/core/figureScale.ts';
+import { FigureDownloadPanel } from '../../download/ui/FigureDownloadPanel.tsx';
+
+/** Props of {@link Molecule3DExport}. */
+export interface Molecule3DExportProps {
+  /** Reads the size of the canvas on screen, when the popover opens. */
+  getSize: () => FigurePixels | null;
+  /** Writes the file. */
+  onExport: (format: FigureFormat, scale: number) => Promise<void>;
+}
+
+/**
+ * The export panel.
+ * @param props - See {@link Molecule3DExportProps}.
+ * @returns The panel.
+ */
+export function Molecule3DExport(props: Molecule3DExportProps): ReactElement {
+  const { getSize, onExport } = props;
+  const [size] = useState(getSize);
+  const [format, setFormat] = useState<FigureFormat>('png');
+  const [scale, setScale] = useState(DEFAULT_FIGURE_SCALE);
+  const [failure, setFailure] = useState<string | null>(null);
+  const [saving, setSaving] = useState(false);
+
+  async function save(): Promise<void> {
+    setSaving(true);
+    try {
+      await onExport(format, scale);
+      setFailure(null);
+    } catch (error) {
+      setFailure(error instanceof Error ? error.message : String(error));
+    } finally {
+      setSaving(false);
+    }
+  }
+
+  return (
+    <FigureDownloadPanel
+      title="Export image"
+      format={format}
+      scale={scale}
+      scales={FIGURE_SCALES}
+      size={size}
+      failure={failure}
+      saving={saving}
+      rasterSvg
+      onFormatChange={setFormat}
+      onScaleChange={setScale}
+      onSave={() => void save()}
+    />
+  );
+}

package/src/molecule3d/ui/Molecule3DHelp.tsx

@@ -0,0 +1,77 @@
+/**
+ * What the mouse and the keyboard do on the molecule canvas, shown in the
+ * toolbar's help popover.
+ */
+
+import { Classes } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+
+import type { Molecule3DGesture } from '../core/gestures.ts';
+import { MOLECULE_3D_GESTURES } from '../core/gestures.ts';
+
+/**
+ * The help panel.
+ * @returns The panel.
+ */
+export function Molecule3DHelp(): ReactElement {
+  return (
+    <div style={PANEL_STYLE} data-testid="molecule3d-help">
+      <div style={GRID_STYLE}>
+        {MOLECULE_3D_GESTURES.map(({ input, action }) => (
+          <div key={`${inputText(input)} ${action}`} style={ROW_STYLE}>
+            <span style={INPUT_STYLE}>
+              {input.map((part) =>
+                typeof part === 'string' ? (
+                  <span key={part}>{part}</span>
+                ) : (
+                  <kbd key={part.key} className={Classes.KEY}>
+                    {part.key}
+                  </kbd>
+                ),
+              )}
+            </span>
+            <span>{action}</span>
+          </div>
+        ))}
+      </div>
+      <p className={Classes.TEXT_MUTED} style={NOTE_STYLE}>
+        Keys act while the pointer is over the molecule. On a Mac, Ctrl is the
+        Control key, not ⌘. With a measuring tool on, a click picks an atom.
+      </p>
+    </div>
+  );
+}
+
+function inputText(input: Molecule3DGesture['input']): string {
+  return input
+    .map((part) => (typeof part === 'string' ? part : part.key))
+    .join(' ');
+}
+
+const PANEL_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 10,
+  width: 360,
+  padding: 12,
+  fontSize: 12,
+};
+
+const GRID_STYLE: CSSProperties = {
+  display: 'grid',
+  gridTemplateColumns: 'max-content minmax(0, 1fr)',
+  alignItems: 'center',
+  columnGap: 12,
+  rowGap: 6,
+};
+
+const ROW_STYLE: CSSProperties = { display: 'contents' };
+
+const INPUT_STYLE: CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 4,
+  whiteSpace: 'nowrap',
+};
+
+const NOTE_STYLE: CSSProperties = { margin: 0 };

package/src/molecule3d/ui/Molecule3DOptions.tsx

@@ -0,0 +1,168 @@
+/**
+ * The display options of the molecule viewer, shown in the toolbar's popover:
+ * the representation, the size, and the surface's opacity, solvent probe and
+ * colours.
+ */
+
+import { SegmentedControl, Slider } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+
+import { formatDecimal } from '../../format/core/numbers.ts';
+import type { Molecule3DSettings } from '../core/settings.ts';
+import {
+  MOLECULE_3D_RANGES,
+  REPRESENTATIONS,
+  REPRESENTATION_LABELS,
+  isRepresentationId,
+} from '../core/settings.ts';
+
+import { Molecule3DSurfaceColors } from './Molecule3DSurfaceColors.tsx';
+
+/** Props of {@link Molecule3DOptions}. */
+export interface Molecule3DOptionsProps {
+  settings: Molecule3DSettings;
+  onChange: (settings: Molecule3DSettings) => void;
+  /** Topological polar surface area in Ų, or `null` when unknown. */
+  polarSurfaceArea: number | null;
+}
+
+/**
+ * The options panel.
+ * @param props - See {@link Molecule3DOptionsProps}.
+ * @returns The panel.
+ */
+export function Molecule3DOptions(props: Molecule3DOptionsProps): ReactElement {
+  const { settings, onChange, polarSurfaceArea } = props;
+
+  return (
+    <div style={PANEL_STYLE}>
+      <SegmentedControl
+        fill
+        size="small"
+        intent="primary"
+        options={REPRESENTATION_OPTIONS}
+        value={settings.representation}
+        onValueChange={(value) => {
+          if (isRepresentationId(value)) {
+            onChange({ ...settings, representation: value });
+          }
+        }}
+      />
+      <div style={GRID_STYLE}>
+        <SliderRow
+          label="Size"
+          range={MOLECULE_3D_RANGES.sizeFactor}
+          digits={1}
+          value={settings.sizeFactor}
+          testId="molecule3d-size-value"
+          onChange={(sizeFactor) => {
+            onChange({ ...settings, sizeFactor });
+          }}
+        />
+        <SliderRow
+          label="Surface opacity"
+          range={MOLECULE_3D_RANGES.surfaceAlpha}
+          digits={2}
+          value={settings.surfaceAlpha}
+          disabled={!settings.showSurface}
+          testId="molecule3d-opacity-value"
+          onChange={(surfaceAlpha) => {
+            onChange({ ...settings, surfaceAlpha });
+          }}
+        />
+        <SliderRow
+          label="Solvent probe [Å]"
+          title={PROBE_HELP}
+          range={MOLECULE_3D_RANGES.probeRadius}
+          digits={1}
+          value={settings.probeRadius}
+          disabled={!settings.showSurface}
+          testId="molecule3d-probe-value"
+          onChange={(probeRadius) => {
+            onChange({ ...settings, probeRadius });
+          }}
+        />
+      </div>
+      <Molecule3DSurfaceColors
+        settings={settings}
+        onChange={onChange}
+        polarSurfaceArea={polarSurfaceArea}
+      />
+    </div>
+  );
+}
+
+interface SliderRowProps {
+  label: string;
+  title?: string;
+  range: { minimum: number; maximum: number; step: number };
+  digits: number;
+  value: number;
+  disabled?: boolean;
+  testId: string;
+  onChange: (value: number) => void;
+}
+
+/**
+ * Label, slider and value as three grid cells; tick labels would collide.
+ * @param props - See {@link SliderRowProps}.
+ * @returns The three cells.
+ */
+function SliderRow(props: SliderRowProps): ReactElement {
+  return (
+    <>
+      <span style={LABEL_STYLE} title={props.title}>
+        {props.label}
+      </span>
+      <span style={SLIDER_STYLE}>
+        <Slider
+          min={props.range.minimum}
+          max={props.range.maximum}
+          stepSize={props.range.step}
+          labelRenderer={false}
+          disabled={props.disabled}
+          value={props.value}
+          onChange={props.onChange}
+        />
+      </span>
+      <span style={VALUE_STYLE} data-testid={props.testId}>
+        {formatDecimal(props.value, props.digits)}
+      </span>
+    </>
+  );
+}
+
+const REPRESENTATION_OPTIONS = REPRESENTATIONS.map((representation) => ({
+  value: representation,
+  label: REPRESENTATION_LABELS[representation],
+}));
+
+const PROBE_HELP =
+  'Radius of the solvent sphere rolled over the atoms. 1.4 Å is a water molecule; a larger probe smooths the surface and closes the narrow pockets.';
+
+const PANEL_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 10,
+  width: 300,
+  padding: 12,
+};
+
+const GRID_STYLE: CSSProperties = {
+  display: 'grid',
+  gridTemplateColumns: 'max-content minmax(0, 1fr) 3em',
+  alignItems: 'center',
+  columnGap: 10,
+  rowGap: 6,
+};
+
+const LABEL_STYLE: CSSProperties = { fontSize: 12 };
+
+/** Room on both sides, so the handle is never clipped at either end. */
+const SLIDER_STYLE: CSSProperties = { display: 'block', paddingInline: 8 };
+
+const VALUE_STYLE: CSSProperties = {
+  fontSize: 12,
+  fontVariantNumeric: 'tabular-nums',
+  textAlign: 'right',
+};