react-cheminfo 0.3.0 → 0.4.0

package/src/structure/ui/Structure.tsx

@@ -0,0 +1,183 @@
+/**
+ * A read-only depiction of a structure, whichever notation the caller has.
+ *
+ * Which notation is drawn, and what is shown when there is nothing to draw, is
+ * decided here; the drawing itself sits behind `React.lazy`, so a page that
+ * never renders a structure never downloads react-ocl and openchemlib for one.
+ * That is also what lets `react-cheminfo/structure` be imported at all when
+ * those optional peers are not installed.
+ */
+
+import type { ReactElement, ReactNode } from 'react';
+import { Suspense, lazy } from 'react';
+
+import { structureSource } from '../core/structureSource.ts';
+
+import { StructurePlaceholder } from './StructurePlaceholder.tsx';
+
+const StructureSvg = lazy(async () => {
+  const module = await import('./StructureSvg.tsx');
+  return { default: module.StructureSvg };
+});
+
+/** What is written on a depiction besides the atoms and the bonds. */
+export interface StructureLabels {
+  /**
+   * Write the index of every atom next to it.
+   * @default false
+   */
+  atoms?: boolean;
+  /**
+   * Write the index of every bond next to it.
+   * @default false
+   */
+  bonds?: boolean;
+  /**
+   * Write the reaction mapping number of every mapped atom.
+   * @default false
+   */
+  mapping?: boolean;
+  /**
+   * A caption drawn inside the picture, under the structure.
+   * @default undefined
+   */
+  caption?: string;
+}
+
+export interface StructureProps {
+  /**
+   * A canonical openchemlib idCode, coordinates included or not. The most
+   * exact notation, so it is drawn in preference to the others.
+   * @default undefined
+   */
+  idCode?: string;
+  /**
+   * Encoded 2D coordinates, when they did not travel with the idCode.
+   * @default undefined
+   */
+  coordinates?: string;
+  /**
+   * A molfile, V2000 or V3000, drawn when there is no usable idCode.
+   * @default undefined
+   */
+  molfile?: string;
+  /**
+   * A SMILES, drawn when there is neither an idCode nor a molfile. The layout
+   * is invented, so two depictions of the same molecule may differ.
+   * @default undefined
+   */
+  smiles?: string;
+  /**
+   * Width of the picture, in pixels.
+   * @default 200
+   */
+  width?: number;
+  /**
+   * Height of the picture, in pixels.
+   * @default 140
+   */
+  height?: number;
+  /**
+   * What is written on the picture besides the structure itself.
+   * @default {}
+   */
+  labels?: StructureLabels;
+  /**
+   * Crop the picture to the atoms rather than centring them in the box.
+   * @default true
+   */
+  autoCrop?: boolean;
+  /**
+   * Blank space kept around the structure when it is cropped, in pixels.
+   * @default 4
+   */
+  autoCropMargin?: number;
+  /**
+   * Atoms to paint, which is how a substructure match is shown.
+   * @default undefined
+   */
+  atomHighlight?: number[];
+  /**
+   * The colour the highlighted atoms are painted.
+   * @default '#a5d8ff'
+   */
+  atomHighlightColor?: string;
+  /**
+   * Bonds to paint.
+   * @default undefined
+   */
+  bondHighlight?: number[];
+  /**
+   * The colour the highlighted bonds are painted.
+   * @default '#ffd8a8'
+   */
+  bondHighlightColor?: string;
+  /**
+   * What is shown when there is no structure, or when the one supplied cannot
+   * be read. An em dash rather than a red box: a missing structure is a row of
+   * a table far more often than it is a bug worth shouting about.
+   * @default '—'
+   */
+  fallback?: ReactNode;
+}
+
+/**
+ * Draw a structure, from whichever notation the caller has.
+ *
+ * Nothing here throws and nothing renders a broken box: a blank value, a
+ * molfile with an empty atom block and a SMILES with a typo in it all come out
+ * as the same quiet placeholder, sized like the picture that would have been
+ * drawn so a list of structures keeps its rhythm. The box the renderers load
+ * into is that same placeholder, so nothing moves once they arrive.
+ * @param props - The structure, its size and what is written on it.
+ * @returns The picture, or the placeholder.
+ */
+export function Structure(props: StructureProps): ReactElement {
+  const {
+    idCode,
+    coordinates,
+    molfile,
+    smiles,
+    width = 200,
+    height = 140,
+    labels = {},
+    autoCrop = true,
+    autoCropMargin = 4,
+    atomHighlight,
+    atomHighlightColor = '#a5d8ff',
+    bondHighlight,
+    bondHighlightColor = '#ffd8a8',
+    fallback = '—',
+  } = props;
+
+  const source = structureSource({ idCode, coordinates, molfile, smiles });
+
+  if (source.kind === 'empty') {
+    return (
+      <StructurePlaceholder width={width} height={height}>
+        {fallback}
+      </StructurePlaceholder>
+    );
+  }
+
+  return (
+    <Suspense fallback={<StructurePlaceholder width={width} height={height} />}>
+      <StructureSvg
+        source={source}
+        width={width}
+        height={height}
+        autoCrop={autoCrop}
+        autoCropMargin={autoCropMargin}
+        atomHighlight={atomHighlight}
+        atomHighlightColor={atomHighlightColor}
+        bondHighlight={bondHighlight}
+        bondHighlightColor={bondHighlightColor}
+        showAtomNumber={labels.atoms ?? false}
+        showBondNumber={labels.bonds ?? false}
+        showMapping={labels.mapping ?? false}
+        label={labels.caption}
+        fallback={fallback}
+      />
+    </Suspense>
+  );
+}

package/src/structure/ui/StructureEditor.tsx

@@ -0,0 +1,196 @@
+/**
+ * The canvas structure editor and the box it is drawn in.
+ *
+ * The canvas itself sits behind `React.lazy`: it is the half that imports
+ * react-ocl, so a page that never opens an editor never downloads openchemlib,
+ * and `react-cheminfo/structure` stays importable when those optional peers
+ * are absent.
+ */
+
+import type { CSSProperties, ReactElement } from 'react';
+import { Suspense, lazy, useCallback, useEffect, useRef } from 'react';
+import type { CanvasEditorInputFormat } from 'react-ocl';
+
+import type {
+  StructureEditorChange,
+  StructureEditorMode,
+} from './EditorCanvas.tsx';
+import { useToolbarFloor } from './useToolbarFloor.ts';
+
+const EditorCanvas = lazy(async () => {
+  const module = await import('./EditorCanvas.tsx');
+  return { default: module.EditorCanvas };
+});
+
+export interface StructureEditorProps {
+  /**
+   * Called after every edit, once the drawing has been still for `debounce`
+   * milliseconds, with every notation read out of the editor.
+   */
+  onChange: (change: StructureEditorChange) => void;
+  /**
+   * Draw a query fragment rather than a whole structure, which is what a
+   * substructure filter needs.
+   * @default false
+   */
+  fragment?: boolean;
+  /**
+   * How `value` is written.
+   * @default 'idcode'
+   */
+  inputFormat?: CanvasEditorInputFormat;
+  /**
+   * What the canvas holds. Read once, when the editor appears and again on
+   * every change of `revision`: the editor is uncontrolled, so feeding the
+   * drawing back into it would replace the structure and reset every
+   * coordinate under the pen.
+   * @default ''
+   */
+  value?: string;
+  /**
+   * Bumped by the caller to load `value` into the canvas again, which is what
+   * an example, a share link or a Clear button does. Changing it discards
+   * whatever was being drawn.
+   * @default 0
+   */
+  revision?: number;
+  /**
+   * How long the drawing has to be still before `onChange` is called, in
+   * milliseconds. Long enough that drawing a ring does not publish six
+   * structures; `0` reports every stroke.
+   * @default 300
+   */
+  debounce?: number;
+  /**
+   * Smallest height of the drawing area, in pixels. Raised to whatever the
+   * toolbar needs, which is usually more.
+   * @default 320
+   */
+  minHeight?: number;
+  /**
+   * Whether the editor draws one structure or a reaction. A reaction canvas
+   * has its own toolbar and its own arrow.
+   * @default 'molecule'
+   */
+  mode?: StructureEditorMode;
+  /** Class the container carries, so a site can reach it from its stylesheet. */
+  className?: string;
+  /** Extra style for the container, merged over the packaged one. */
+  style?: CSSProperties;
+}
+
+/**
+ * The canvas structure editor, sized to fill its container and never to hide
+ * part of its toolbar.
+ * @param props - What to draw, when to reload it, and where to send it.
+ * @returns The editor.
+ */
+export function StructureEditor(props: StructureEditorProps): ReactElement {
+  const {
+    onChange,
+    fragment = false,
+    inputFormat = 'idcode',
+    value = '',
+    revision = 0,
+    debounce = 300,
+    minHeight = 320,
+    mode = 'molecule',
+    className,
+    style,
+  } = props;
+
+  const containerRef = useToolbarFloor({ minHeight, revision });
+  const handleChange = useDebounced(onChange, debounce, revision);
+
+  return (
+    <div
+      ref={containerRef}
+      className={className}
+      style={{ ...ROOT_STYLE, minHeight, ...style }}
+    >
+      <Suspense fallback={<div style={LOADING_STYLE}>Loading the editor…</div>}>
+        <EditorCanvas
+          key={revision}
+          onChange={handleChange}
+          fragment={fragment}
+          inputFormat={inputFormat}
+          value={value}
+          mode={mode}
+        />
+      </Suspense>
+    </div>
+  );
+}
+
+/**
+ * Report the last edit of a burst rather than every one of them.
+ *
+ * The editor's own event is read out before the wait starts, so what arrives
+ * late is a plain object rather than a handle on an editor that has moved on.
+ * @param onChange - What the caller wants told.
+ * @param delay - How long the drawing has to be still, in milliseconds.
+ * @param resetKey - Dropped edits: a burst still waiting when the caller
+ * replaces the structure describes a canvas that no longer exists.
+ * @returns The handler to give the canvas.
+ */
+function useDebounced(
+  onChange: (change: StructureEditorChange) => void,
+  delay: number,
+  resetKey: number,
+): (change: StructureEditorChange) => void {
+  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const onChangeRef = useRef(onChange);
+  useEffect(() => {
+    onChangeRef.current = onChange;
+  });
+  useEffect(() => {
+    return () => {
+      if (timerRef.current !== null) {
+        clearTimeout(timerRef.current);
+        timerRef.current = null;
+      }
+    };
+  }, [resetKey]);
+
+  return useCallback(
+    (change: StructureEditorChange) => {
+      if (timerRef.current !== null) clearTimeout(timerRef.current);
+      if (delay <= 0) {
+        onChangeRef.current(change);
+        return;
+      }
+      timerRef.current = setTimeout(() => {
+        timerRef.current = null;
+        onChangeRef.current(change);
+      }, delay);
+    },
+    [delay],
+  );
+}
+
+/**
+ * The canvas is positioned out of the height computation, so the container's
+ * own height is what the measured toolbar floor writes on it. The `minHeight`
+ * prop is applied on top of this at first render: without a height before the
+ * toolbar has been measured, the editor is built at zero size and never paints
+ * the structure it was given.
+ */
+const ROOT_STYLE: CSSProperties = {
+  position: 'relative',
+  overflow: 'hidden',
+  boxSizing: 'border-box',
+  border: '1px solid #d3d8de',
+  borderRadius: 6,
+  background: '#fff',
+};
+
+/** The box the canvas will fill, so its arrival moves nothing. */
+const LOADING_STYLE: CSSProperties = {
+  position: 'absolute',
+  inset: 0,
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  color: '#8a96a3',
+  fontSize: 13,
+};

package/src/structure/ui/StructurePlaceholder.tsx

@@ -0,0 +1,48 @@
+/**
+ * The box a depiction leaves behind when there is no picture in it — nothing
+ * to draw, a notation that cannot be read, or the moment before the renderers
+ * have been downloaded.
+ *
+ * It is kept apart from the renderers on purpose: it pulls nothing in, so both
+ * sides of the `React.lazy` boundary in `Structure` can use it.
+ */
+
+import type { CSSProperties, ReactElement, ReactNode } from 'react';
+
+/** Props of {@link StructurePlaceholder}. */
+export interface StructurePlaceholderProps {
+  /** Width of the box, in pixels: the width the picture would have had. */
+  width: number;
+  /** Height of the box, in pixels. */
+  height: number;
+  /**
+   * What is written in the middle of the box.
+   * @default undefined
+   */
+  children?: ReactNode;
+}
+
+/**
+ * A box the size of the picture that is not there, holding whatever the caller
+ * wants said instead.
+ * @param props - See {@link StructurePlaceholderProps}.
+ * @returns The placeholder.
+ */
+export function StructurePlaceholder(
+  props: StructurePlaceholderProps,
+): ReactElement {
+  const { width, height, children } = props;
+  return (
+    <span style={{ ...PLACEHOLDER_STYLE, width, height }} aria-hidden="true">
+      {children}
+    </span>
+  );
+}
+
+const PLACEHOLDER_STYLE: CSSProperties = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  justifyContent: 'center',
+  color: '#8a96a3',
+  fontSize: '0.75rem',
+};

package/src/structure/ui/StructureSvg.tsx

@@ -0,0 +1,110 @@
+/**
+ * The react-ocl depiction of a structure whose notation has already been
+ * picked.
+ *
+ * `Structure` holds it behind `React.lazy`, and the barrel deliberately does
+ * not export it: this is the file that value-imports react-ocl, so
+ * anything able to reach it statically drags openchemlib into every bundle,
+ * including the ones that only ever wanted the Tools menu.
+ */
+
+import type { ComponentType, ReactElement, ReactNode } from 'react';
+import { useMemo } from 'react';
+import type { ErrorComponentProps } from 'react-ocl';
+import {
+  IdcodeSvgRenderer,
+  MolfileSvgRenderer,
+  SmilesSvgRenderer,
+} from 'react-ocl';
+
+import type { StructureSource } from '../core/structureSource.ts';
+
+import { StructurePlaceholder } from './StructurePlaceholder.tsx';
+
+/** Props of {@link StructureSvg}. */
+export interface StructureSvgProps {
+  /** The notation to draw, as `structureSource` picked it. */
+  source: StructureSource;
+  /** Width of the picture, in pixels. */
+  width: number;
+  /** Height of the picture, in pixels. */
+  height: number;
+  /** Crop the picture to the atoms rather than centring them in the box. */
+  autoCrop: boolean;
+  /** Blank space kept around the structure when it is cropped, in pixels. */
+  autoCropMargin: number;
+  /**
+   * Atoms to paint, which is how a substructure match is shown.
+   * @default undefined
+   */
+  atomHighlight?: number[];
+  /** The colour the highlighted atoms are painted. */
+  atomHighlightColor: string;
+  /**
+   * Bonds to paint.
+   * @default undefined
+   */
+  bondHighlight?: number[];
+  /** The colour the highlighted bonds are painted. */
+  bondHighlightColor: string;
+  /** Write the index of every atom next to it. */
+  showAtomNumber: boolean;
+  /** Write the index of every bond next to it. */
+  showBondNumber: boolean;
+  /** Write the reaction mapping number of every mapped atom. */
+  showMapping: boolean;
+  /**
+   * A caption drawn inside the picture, under the structure.
+   * @default undefined
+   */
+  label?: string;
+  /** What is shown in place of a structure react-ocl refuses to read. */
+  fallback: ReactNode;
+}
+
+/**
+ * Draw the picture with the renderer the notation calls for.
+ * @param props - See {@link StructureSvgProps}.
+ * @returns The svg, or the placeholder when the notation cannot be read.
+ */
+export function StructureSvg(props: StructureSvgProps): ReactElement {
+  const { source, fallback, ...rest } = props;
+
+  const ErrorComponent = useMemo(
+    () => createFallbackRenderer(fallback),
+    [fallback],
+  );
+  const shared = { ...rest, ErrorComponent };
+
+  if (source.kind === 'idcode') {
+    return (
+      <IdcodeSvgRenderer
+        idcode={source.value}
+        coordinates={source.coordinates}
+        {...shared}
+      />
+    );
+  }
+  if (source.kind === 'molfile') {
+    return <MolfileSvgRenderer molfile={source.value} {...shared} />;
+  }
+  return <SmilesSvgRenderer smiles={source.value} {...shared} />;
+}
+
+/**
+ * Build the renderer react-ocl falls back to, so a structure it refuses looks
+ * like one that was never supplied rather than like an error.
+ * @param fallback - What the caller wants shown instead of the structure.
+ * @returns The component react-ocl renders in place of the picture.
+ */
+function createFallbackRenderer(
+  fallback: ReactNode,
+): ComponentType<ErrorComponentProps> {
+  return function StructureFallback(props: ErrorComponentProps): ReactElement {
+    return (
+      <StructurePlaceholder width={props.width} height={props.height}>
+        {fallback}
+      </StructurePlaceholder>
+    );
+  };
+}

package/src/structure/ui/index.ts

@@ -0,0 +1,22 @@
+/**
+ * What a site imports to show or to draw a structure.
+ *
+ * **Nothing exported here may pull react-ocl or openchemlib in statically.**
+ * `StructureSvg` and `EditorCanvas` are deliberately absent: re-exporting
+ * either would make react-ocl reachable from this barrel, the `React.lazy`
+ * boundaries inside `Structure` and `StructureEditor` would be defeated, and
+ * `react-cheminfo/structure` would stop being importable at all when those
+ * optional peers are not installed — which is what a site wanting only the
+ * Tools menu does. Type-only re-exports are erased and so are safe.
+ */
+
+export type {
+  StructureEditorChange,
+  StructureEditorMode,
+} from './EditorCanvas.tsx';
+export type { StructureLabels, StructureProps } from './Structure.tsx';
+export { Structure } from './Structure.tsx';
+export type { StructureEditorProps } from './StructureEditor.tsx';
+export { StructureEditor } from './StructureEditor.tsx';
+export type { ToolbarFloorOptions } from './useToolbarFloor.ts';
+export { useToolbarFloor } from './useToolbarFloor.ts';

package/src/structure/ui/useToolbarFloor.ts

@@ -0,0 +1,93 @@
+import type { RefObject } from 'react';
+import { useLayoutEffect, useRef } from 'react';
+
+import { toolbarFloorHeight } from '../core/toolbarFloor.ts';
+
+export interface ToolbarFloorOptions {
+  /**
+   * Smallest height of the drawing area, in pixels. Raised to whatever the
+   * toolbar needs, which is usually more.
+   * @default 320
+   */
+  minHeight?: number;
+  /**
+   * Bumped to look for the toolbar again, which a caller does after the editor
+   * has been remounted and the previous toolbar element has gone.
+   * @default 0
+   */
+  revision?: number;
+}
+
+/**
+ * Give an editor's container a minimum height that shows the whole toolbar.
+ *
+ * The height is measured rather than written down, so a different button count
+ * — a fragment editor, a reaction editor, a future release — keeps working
+ * instead of clipping its last buttons behind whatever follows the editor.
+ * @param options - The height the caller asked for, and when to look again.
+ * @returns The ref to put on the element wrapping the editor.
+ */
+export function useToolbarFloor(
+  options: ToolbarFloorOptions = {},
+): RefObject<HTMLDivElement | null> {
+  const { minHeight = 320, revision = 0 } = options;
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useLayoutEffect(() => {
+    const container = containerRef.current;
+    if (container === null) return;
+
+    let observer: ResizeObserver | null = null;
+    let frame = 0;
+    let attempts = 0;
+
+    // The editor builds itself asynchronously, so the toolbar is usually not
+    // there yet on the first look; watching for it is what keeps a slow first
+    // paint from leaving the container at its unmeasured height for good.
+    const attach = (): void => {
+      const toolbar = findToolbar(container);
+      if (toolbar === null) {
+        attempts++;
+        if (attempts > MAX_ATTEMPTS) return;
+        frame = globalThis.requestAnimationFrame(attach);
+        return;
+      }
+      observer = new ResizeObserver(() => {
+        // offsetHeight, because a dialog opens under a scaling transform and a
+        // measured rectangle would be that of the half drawn toolbar.
+        const floor = toolbarFloorHeight(toolbar.offsetHeight, minHeight);
+        container.style.minHeight = `${floor}px`;
+      });
+      observer.observe(toolbar);
+    };
+
+    attach();
+
+    return () => {
+      if (frame !== 0) globalThis.cancelAnimationFrame(frame);
+      observer?.disconnect();
+    };
+  }, [minHeight, revision]);
+
+  return containerRef;
+}
+
+/** Roughly two seconds of frames, after which the editor is not coming. */
+const MAX_ATTEMPTS = 120;
+
+/**
+ * Find the toolbar canvas of the editor.
+ *
+ * The editor builds itself inside a shadow root and puts the toolbar there as
+ * a direct child, the drawing canvas being nested deeper.
+ * @param container - The element wrapping the editor.
+ * @returns The toolbar canvas, or null while the editor has not drawn one.
+ */
+function findToolbar(container: HTMLElement): HTMLCanvasElement | null {
+  for (const element of container.querySelectorAll('*')) {
+    for (const child of element.shadowRoot?.children ?? []) {
+      if (child instanceof HTMLCanvasElement) return child;
+    }
+  }
+  return null;
+}

package/src/structure.ts

@@ -0,0 +1,2 @@
+export * from './structure/core/index.ts';
+export * from './structure/ui/index.ts';

package/src/ui.ts

@@ -1,3 +1,16 @@
+export * from './capsule/ui/index.ts';
+export * from './chrome/ui/index.ts';
 export * from './citation/ui/index.ts';
+export * from './clipboard/ui/index.ts';
+export * from './color/ui/index.ts';
+export * from './credits/ui/index.ts';
+export * from './delimited/ui/index.ts';
+export * from './disclosure/ui/index.ts';
 export * from './ecosystem/ui/index.ts';
+export * from './error/ui/index.ts';
+export * from './help/ui/index.ts';
+export * from './hooks/ui/index.ts';
+export * from './pedagogy/ui/index.ts';
+export * from './share/ui/index.ts';
 export * from './shared/ui/index.ts';
+export * from './state/ui/index.ts';

package/src/worker/core/errors.ts

@@ -0,0 +1,15 @@
+/**
+ * Rejection of a request nobody is waiting for any more: its signal was
+ * aborted, or the channel it was posted on was terminated.
+ *
+ * It is the normal outcome of dragging a slider or clicking through a list, so
+ * a caller catches it and draws nothing rather than reporting a failure.
+ */
+export class CancelledRequestError extends Error {
+  override name = 'CancelledRequestError';
+}
+
+/** Rejection of a request that outlived its budget and was given up on. */
+export class RequestTimeoutError extends Error {
+  override name = 'RequestTimeoutError';
+}

package/src/worker/core/index.ts

@@ -0,0 +1,8 @@
+export { CancelledRequestError, RequestTimeoutError } from './errors.ts';
+export type { WorkerLike } from './messages.ts';
+export type {
+  WorkerChannel,
+  WorkerChannelOptions,
+  WorkerRequestOptions,
+} from './workerChannel.ts';
+export { createWorkerChannel } from './workerChannel.ts';