react-cheminfo 0.10.0 → 0.12.0

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

package/src/molecule3d/ui/Molecule3DToolbar.tsx

@@ -0,0 +1,190 @@
+/**
+ * The toolbars floating over the molecule canvas: the view — reset, spin,
+ * surface, and the options, export and help popovers — in one vertical
+ * react-science `Toolbar`, and the measuring tools with their own clear button
+ * in a second one under it.
+ */
+
+import { Card } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+import { Toolbar } from 'react-science/ui';
+
+import type { MeasurementKind } from '../core/measurement.ts';
+import {
+  MEASUREMENT_ATOM_COUNTS,
+  MEASUREMENT_KINDS,
+  MEASUREMENT_LABELS,
+} from '../core/measurement.ts';
+import type { Molecule3DTools } from '../core/settings.ts';
+
+import { Molecule3DHelp } from './Molecule3DHelp.tsx';
+import {
+  ClearMeasurementsIcon,
+  MeasureIcon,
+  SurfaceIcon,
+} from './molecule3dIcons.tsx';
+
+/** Props of {@link Molecule3DToolbar}. */
+export interface Molecule3DToolbarProps {
+  tools: Molecule3DTools;
+  measureKind: MeasurementKind | null;
+  onMeasureKindChange: (kind: MeasurementKind | null) => void;
+  measurementCount: number;
+  onClearMeasurements: () => void;
+  spinning: boolean;
+  onSpinningChange: (spinning: boolean) => void;
+  showSurface: boolean;
+  onShowSurfaceChange: (showSurface: boolean) => void;
+  onResetView: () => void;
+  /** Content of the options popover. */
+  options: ReactElement;
+  /** Content of the export popover. */
+  exportPanel: ReactElement;
+}
+
+/**
+ * The two toolbars; either is left out when none of its tools is on.
+ * @param props - See {@link Molecule3DToolbarProps}.
+ * @returns The toolbars, stacked.
+ */
+export function Molecule3DToolbar(props: Molecule3DToolbarProps): ReactElement {
+  const {
+    tools,
+    measureKind,
+    onMeasureKindChange,
+    measurementCount,
+    onClearMeasurements,
+    spinning,
+    onSpinningChange,
+    showSurface,
+    onShowSurfaceChange,
+    onResetView,
+    options,
+    exportPanel,
+  } = props;
+  const hasView =
+    tools.spin ||
+    tools.surface ||
+    tools.reset ||
+    tools.options ||
+    tools.export ||
+    tools.help;
+
+  return (
+    <div style={COLUMN_STYLE}>
+      {hasView && (
+        <Card elevation={1} style={CARD_STYLE}>
+          <Toolbar vertical aria-label="View">
+            {tools.reset && (
+              <Toolbar.Item
+                icon="zoom-to-fit"
+                aria-label="Reset view"
+                tooltip="Reset view"
+                tooltipProps={TOOLTIP_PROPS}
+                onClick={onResetView}
+              />
+            )}
+            {tools.spin && (
+              <Toolbar.Item
+                icon="refresh"
+                active={spinning}
+                aria-label="Spin"
+                tooltip="Spin"
+                tooltipProps={TOOLTIP_PROPS}
+                onClick={() => {
+                  onSpinningChange(!spinning);
+                }}
+              />
+            )}
+            {tools.surface && (
+              <Toolbar.Item
+                icon={<SurfaceIcon />}
+                active={showSurface}
+                aria-label="Surface"
+                tooltip="Molecular surface"
+                tooltipProps={TOOLTIP_PROPS}
+                onClick={() => {
+                  onShowSurfaceChange(!showSurface);
+                }}
+              />
+            )}
+            {tools.options && (
+              <Toolbar.PopoverItem
+                placement="right-start"
+                content={options}
+                itemProps={{
+                  icon: 'cog',
+                  'aria-label': 'Display options',
+                  tooltip: 'Display options',
+                  tooltipProps: TOOLTIP_PROPS,
+                }}
+              />
+            )}
+            {tools.export && (
+              <Toolbar.PopoverItem
+                placement="right-start"
+                content={exportPanel}
+                itemProps={{
+                  icon: 'download',
+                  'aria-label': 'Export image',
+                  tooltip: 'Export image',
+                  tooltipProps: TOOLTIP_PROPS,
+                }}
+              />
+            )}
+            {tools.help && (
+              <Toolbar.PopoverItem
+                placement="right-start"
+                content={<Molecule3DHelp />}
+                itemProps={{
+                  icon: 'help',
+                  'aria-label': 'Mouse and keyboard',
+                  tooltip: 'Mouse and keyboard',
+                  tooltipProps: TOOLTIP_PROPS,
+                }}
+              />
+            )}
+          </Toolbar>
+        </Card>
+      )}
+      {tools.measure && (
+        <Card elevation={1} style={CARD_STYLE}>
+          <Toolbar vertical aria-label="Measure">
+            {MEASUREMENT_KINDS.map((kind) => (
+              <Toolbar.Item
+                key={kind}
+                icon={<MeasureIcon kind={kind} />}
+                active={measureKind === kind}
+                aria-label={MEASUREMENT_LABELS[kind]}
+                tooltip={`${MEASUREMENT_LABELS[kind]}: click ${MEASUREMENT_ATOM_COUNTS[kind]} atoms`}
+                tooltipProps={TOOLTIP_PROPS}
+                onClick={() => {
+                  onMeasureKindChange(measureKind === kind ? null : kind);
+                }}
+              />
+            ))}
+            <Toolbar.Item
+              icon={<ClearMeasurementsIcon />}
+              disabled={measurementCount === 0}
+              aria-label="Remove all measurements"
+              tooltip="Remove all measurements"
+              tooltipProps={TOOLTIP_PROPS}
+              onClick={onClearMeasurements}
+            />
+          </Toolbar>
+        </Card>
+      )}
+    </div>
+  );
+}
+
+const TOOLTIP_PROPS = { placement: 'right' } as const;
+
+const COLUMN_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+  pointerEvents: 'auto',
+};
+
+const CARD_STYLE: CSSProperties = { padding: 0 };

package/src/molecule3d/ui/MoleculeCanvas3D.tsx

@@ -0,0 +1,235 @@
+/**
+ * The molstar canvas of `MoleculeViewer3D`, with its toolbars over it.
+ *
+ * Reached through `React.lazy`, so a page that never shows a molecule never
+ * downloads molstar.
+ */
+
+import type { CSSProperties, ReactElement } from 'react';
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+import type { Measurement, MeasurementKind } from '../core/measurement.ts';
+import type { Molecule3DFile } from '../core/settings.ts';
+import {
+  normalizeMolecule3DSettings,
+  resolveMolecule3DTools,
+} from '../core/settings.ts';
+
+import { Molecule3DExport } from './Molecule3DExport.tsx';
+import { Molecule3DOptions } from './Molecule3DOptions.tsx';
+import { Molecule3DToolbar } from './Molecule3DToolbar.tsx';
+import { DEFAULT_SPIN_SPEED } from './camera.ts';
+import { drawScene } from './drawScene.ts';
+import type { MoleculeViewer3DProps } from './moleculeViewer3DProps.ts';
+import { useControlledState } from './useControlledState.ts';
+import { useImageExport } from './useImageExport.ts';
+import { usePolarSurfaceArea } from './usePolarSurfaceArea.ts';
+import type { Molecule3DViewer } from './viewer.ts';
+import { createMolecule3DViewer } from './viewer.ts';
+
+/** Props of {@link MoleculeCanvas3D}. */
+export interface MoleculeCanvas3DProps extends Omit<
+  MoleculeViewer3DProps,
+  'fallback' | 'renderUnsupported'
+> {
+  /** Called with a drawing failure, and with `null` once a draw succeeds. */
+  onFailureChange: (message: string | null) => void;
+}
+
+/**
+ * Mount one molstar canvas and keep it showing what the props describe.
+ * @param props - See {@link MoleculeCanvas3DProps}.
+ * @returns The canvas with its toolbars.
+ */
+export function MoleculeCanvas3D(props: MoleculeCanvas3DProps): ReactElement {
+  const {
+    molfile,
+    tools: toolsProp,
+    settings: settingsProp,
+    defaultSettings,
+    onSettingsChange,
+    spinning: spinningProp,
+    defaultSpinning = false,
+    onSpinningChange,
+    spinSpeed = DEFAULT_SPIN_SPEED,
+    measurements: measurementsProp,
+    onMeasurementsChange,
+    fileName = 'molecule',
+    background,
+    minHeight = 320,
+    onFailureChange,
+  } = props;
+  const tools = resolveMolecule3DTools(toolsProp);
+  const [settings, setSettings] = useControlledState(
+    settingsProp,
+    () => normalizeMolecule3DSettings(defaultSettings),
+    onSettingsChange,
+  );
+  const [spinning, setSpinning] = useControlledState(
+    spinningProp,
+    defaultSpinning,
+    onSpinningChange,
+  );
+  const [measurements, setMeasurements] = useControlledState<
+    readonly Measurement[]
+  >(measurementsProp, NO_MEASUREMENTS, onMeasurementsChange);
+  const [measureKind, setMeasureKind] = useState<MeasurementKind | null>(null);
+  const polarSurfaceArea = usePolarSurfaceArea(
+    molfile,
+    settings.surfaceColoring === 'polarity',
+  );
+
+  // A callback ref: the element arriving is what creates the viewer, and every
+  // effect keyed on it runs again, in order, after the viewer exists.
+  const [container, setContainer] = useState<HTMLDivElement | null>(null);
+  const viewerRef = useRef<Molecule3DViewer | null>(null);
+  const framedRef = useRef<{
+    molfile: Molecule3DFile;
+    viewer: Molecule3DViewer;
+  } | null>(null);
+
+  // The viewer is created once, so what its callbacks read is kept fresh here.
+  const latest = useRef({
+    measurements,
+    setMeasurements,
+    onFailureChange,
+    background,
+  });
+  useEffect(() => {
+    latest.current = {
+      measurements,
+      setMeasurements,
+      onFailureChange,
+      background,
+    };
+  });
+
+  useEffect(() => {
+    if (container === null) return;
+    const viewer = createMolecule3DViewer(container, {
+      background: latest.current.background,
+      onMeasure: (measurement) => {
+        const current = latest.current;
+        current.setMeasurements([...current.measurements, measurement]);
+      },
+    });
+    viewerRef.current = viewer;
+    const observer = new ResizeObserver(() => {
+      viewer.handleResize();
+    });
+    observer.observe(container);
+    return () => {
+      observer.disconnect();
+      viewerRef.current = null;
+      viewer.dispose();
+    };
+  }, [container]);
+
+  // One animation frame of coalescing, so dragging a slider costs one rebuild.
+  useEffect(() => {
+    const viewer = viewerRef.current;
+    if (container === null || viewer === null) return;
+    let cancelled = false;
+    const frame = requestAnimationFrame(() => {
+      // Framed on a new molecule or a new viewer, never on a restyle: a slider
+      // that snapped the camera back would undo the reader's orientation.
+      const framed = framedRef.current;
+      const frameCamera =
+        molfile !== null &&
+        (framed?.molfile !== molfile || framed.viewer !== viewer);
+      framedRef.current = molfile === null ? null : { molfile, viewer };
+      void drawScene(viewer, molfile, settings, measurements, frameCamera)
+        .then(() => {
+          if (!cancelled) latest.current.onFailureChange(null);
+        })
+        .catch((error: unknown) => {
+          if (cancelled) return;
+          latest.current.onFailureChange(
+            error instanceof Error ? error.message : String(error),
+          );
+        });
+    });
+    return () => {
+      cancelled = true;
+      cancelAnimationFrame(frame);
+    };
+  }, [container, molfile, settings, measurements]);
+
+  useEffect(() => {
+    void viewerRef.current?.setSpin(spinning, spinSpeed);
+  }, [container, spinning, spinSpeed]);
+
+  useEffect(() => {
+    void viewerRef.current?.setMeasureKind(measureKind);
+  }, [container, measureKind]);
+
+  const resetView = useCallback(() => {
+    void viewerRef.current?.resetCamera();
+  }, []);
+
+  const { canvasSize, exportImage } = useImageExport(
+    container,
+    viewerRef,
+    fileName,
+  );
+
+  return (
+    <div style={{ ...STAGE_STYLE, minHeight }}>
+      <div ref={setContainer} style={CANVAS_STYLE} data-testid="molecule3d" />
+      {molfile !== null && (
+        <div style={OVERLAY_STYLE}>
+          <Molecule3DToolbar
+            tools={tools}
+            measureKind={measureKind}
+            onMeasureKindChange={setMeasureKind}
+            measurementCount={measurements.length}
+            onClearMeasurements={() => {
+              setMeasurements(NO_MEASUREMENTS);
+            }}
+            spinning={spinning}
+            onSpinningChange={setSpinning}
+            showSurface={settings.showSurface}
+            onShowSurfaceChange={(showSurface) => {
+              setSettings({ ...settings, showSurface });
+            }}
+            onResetView={resetView}
+            options={
+              <Molecule3DOptions
+                settings={settings}
+                onChange={setSettings}
+                polarSurfaceArea={polarSurfaceArea}
+              />
+            }
+            exportPanel={
+              <Molecule3DExport getSize={canvasSize} onExport={exportImage} />
+            }
+          />
+        </div>
+      )}
+    </div>
+  );
+}
+
+const NO_MEASUREMENTS: readonly Measurement[] = [];
+
+const STAGE_STYLE: CSSProperties = {
+  position: 'relative',
+  flex: '1 0 auto',
+  width: '100%',
+  borderRadius: 3,
+  overflow: 'hidden',
+};
+
+/** molstar inserts its canvas here, which therefore has a size of its own. */
+const CANVAS_STYLE: CSSProperties = { position: 'absolute', inset: 0 };
+
+const OVERLAY_STYLE: CSSProperties = {
+  position: 'absolute',
+  top: 8,
+  left: 8,
+  zIndex: 2,
+  display: 'flex',
+  alignItems: 'flex-start',
+  gap: 8,
+  pointerEvents: 'none',
+};

package/src/molecule3d/ui/MoleculeViewer3D.tsx

@@ -0,0 +1,84 @@
+/**
+ * A molecule in three dimensions, with a toolbar to measure it, turn it, wrap
+ * it in its surface and restyle it — and what to say when there cannot be one.
+ *
+ * The WebGL probe runs before molstar is touched, so a machine without WebGL
+ * gets an explanation instead of a blank rectangle, and the canvas sits behind
+ * `React.lazy`, so a page that never reaches it never downloads molstar.
+ *
+ * ```tsx
+ * import { MoleculeViewer3D } from 'react-cheminfo/molecule3d';
+ *
+ * <MoleculeViewer3D
+ *   molfile={{ format: 'mol', data: molfile }}
+ *   tools={{ measure: false }}
+ * />;
+ * ```
+ */
+
+import { Callout } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+import { Suspense, lazy, useState } from 'react';
+
+// Deep import on purpose: `capability.ts` imports nothing, while the canvas
+// pulls molstar in — which is exactly what this probe exists to avoid.
+import { probeViewerCapability } from '../../orbital/ui/capability.ts';
+
+import type { MoleculeViewer3DProps } from './moleculeViewer3DProps.ts';
+
+const MoleculeCanvas3D = lazy(async () => {
+  const module = await import('./MoleculeCanvas3D.tsx');
+  return { default: module.MoleculeCanvas3D };
+});
+
+/**
+ * The 3D molecule viewer.
+ * @param props - See {@link MoleculeViewer3DProps}.
+ * @returns The viewer, or an explanation of why this machine cannot show one.
+ */
+export function MoleculeViewer3D(props: MoleculeViewer3DProps): ReactElement {
+  const {
+    fallback = 'Loading the 3D viewer…',
+    renderUnsupported,
+    ...canvas
+  } = props;
+  const [capability] = useState(probeViewerCapability);
+  const [failure, setFailure] = useState<string | null>(null);
+
+  if (!capability.supported) {
+    return (
+      <Callout intent="warning" compact>
+        {renderUnsupported?.(capability) ?? capability.message}
+      </Callout>
+    );
+  }
+
+  return (
+    <div style={ROOT_STYLE}>
+      <Suspense fallback={<div style={NOTE_STYLE}>{fallback}</div>}>
+        <MoleculeCanvas3D {...canvas} onFailureChange={setFailure} />
+      </Suspense>
+      {failure !== null && (
+        <Callout intent="danger" compact title="The viewer could not draw this">
+          {failure}
+        </Callout>
+      )}
+    </div>
+  );
+}
+
+const ROOT_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 6,
+  flex: '1 0 auto',
+  minWidth: 0,
+};
+
+const NOTE_STYLE: CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  minHeight: 320,
+  fontSize: 13,
+};