react-cheminfo 0.11.0 → 0.13.0

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

package/src/molecule3d/ui/Molecule3DSurfaceColors.tsx

@@ -0,0 +1,150 @@
+/**
+ * The colour section of the options popover: how the surface is coloured, its
+ * colour in uniform mode, and the legend and polar surface area in polarity
+ * mode.
+ */
+
+import { SegmentedControl } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+import { ColorPickerDropdown } from 'react-science/ui';
+
+import { formatDecimal } from '../../format/core/numbers.ts';
+import type { Molecule3DSettings } from '../core/settings.ts';
+import {
+  SURFACE_CHARGE_COLORS,
+  SURFACE_COLORINGS,
+  SURFACE_COLORING_LABELS,
+  isSurfaceColoringId,
+} from '../core/settings.ts';
+
+/** Props of {@link Molecule3DSurfaceColors}. */
+export interface Molecule3DSurfaceColorsProps {
+  settings: Molecule3DSettings;
+  onChange: (settings: Molecule3DSettings) => void;
+  /** Topological polar surface area in Ų, or `null` when unknown. */
+  polarSurfaceArea: number | null;
+}
+
+/**
+ * The surface colour controls.
+ * @param props - See {@link Molecule3DSurfaceColorsProps}.
+ * @returns The section.
+ */
+export function Molecule3DSurfaceColors(
+  props: Molecule3DSurfaceColorsProps,
+): ReactElement {
+  const { settings, onChange, polarSurfaceArea } = props;
+  const disabled = !settings.showSurface;
+  const { surfaceColoring, surfaceColor } = settings;
+
+  return (
+    <div style={SECTION_STYLE}>
+      <span style={LABEL_STYLE}>Surface colour</span>
+      <SegmentedControl
+        fill
+        size="small"
+        disabled={disabled}
+        options={COLORING_OPTIONS}
+        value={surfaceColoring}
+        onValueChange={(value) => {
+          if (isSurfaceColoringId(value)) {
+            onChange({ ...settings, surfaceColoring: value });
+          }
+        }}
+      />
+      {surfaceColoring === 'uniform' && (
+        <span style={ROW_STYLE}>
+          <span style={LABEL_STYLE}>Colour</span>
+          {disabled ? (
+            <span style={{ ...SWATCH_STYLE, background: surfaceColor }} />
+          ) : (
+            // The dropdown's button fills its parent; the span gives it a size.
+            <span style={PICKER_STYLE} data-testid="molecule3d-surface-color">
+              <ColorPickerDropdown
+                color={{ hex: surfaceColor }}
+                disableAlpha
+                onChange={(result) => {
+                  onChange({ ...settings, surfaceColor: result.hex });
+                }}
+              />
+            </span>
+          )}
+        </span>
+      )}
+      {surfaceColoring === 'polarity' && (
+        <>
+          <span style={ROW_STYLE} data-testid="molecule3d-polarity-legend">
+            <LegendItem color={SURFACE_CHARGE_COLORS.positive} label="δ+" />
+            <LegendItem color={SURFACE_CHARGE_COLORS.negative} label="δ−" />
+            <LegendItem color={SURFACE_CHARGE_COLORS.neutral} label="neutral" />
+          </span>
+          <span
+            style={LABEL_STYLE}
+            title={TPSA_HELP}
+            data-testid="molecule3d-tpsa-value"
+          >
+            TPSA:{' '}
+            {polarSurfaceArea === null
+              ? '—'
+              : `${formatDecimal(polarSurfaceArea, 1)} Ų`}
+          </span>
+        </>
+      )}
+    </div>
+  );
+}
+
+function LegendItem(props: { color: string; label: string }): ReactElement {
+  return (
+    <span style={LEGEND_ITEM_STYLE}>
+      <span style={{ ...LEGEND_SWATCH_STYLE, background: props.color }} />
+      <span style={LABEL_STYLE}>{props.label}</span>
+    </span>
+  );
+}
+
+const COLORING_OPTIONS = SURFACE_COLORINGS.map((coloring) => ({
+  value: coloring,
+  label: SURFACE_COLORING_LABELS[coloring],
+}));
+
+const TPSA_HELP =
+  'Topological polar surface area (Ertl): the area contributed by nitrogen, oxygen and their hydrogens, computed from the structure by openchemlib. It does not depend on the conformer or the probe.';
+
+const SECTION_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+};
+
+const ROW_STYLE: CSSProperties = {
+  display: 'flex',
+  flexWrap: 'wrap',
+  alignItems: 'center',
+  gap: 12,
+};
+
+const LABEL_STYLE: CSSProperties = { fontSize: 12 };
+
+const PICKER_STYLE: CSSProperties = { display: 'inline-block', width: 40 };
+
+const SWATCH_STYLE: CSSProperties = {
+  display: 'inline-block',
+  width: 40,
+  height: 30,
+  borderRadius: 3,
+  opacity: 0.5,
+};
+
+const LEGEND_ITEM_STYLE: CSSProperties = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  gap: 4,
+};
+
+const LEGEND_SWATCH_STYLE: CSSProperties = {
+  display: 'inline-block',
+  width: 12,
+  height: 12,
+  borderRadius: 2,
+};