react-cheminfo 0.17.0 → 0.19.0

package/src/structure/ui/StructureEditorHelp.tsx

@@ -0,0 +1,136 @@
+/**
+ * What the keyboard and the mouse do in the structure editor, shown in the
+ * editor's help popover, and usable by a site on a page of its own.
+ */
+
+import { Classes } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+
+import { TOKEN } from '../../tokens/core/familyTokens.ts';
+import type { EditorGesture, EditorGuideOptions } from '../core/editorGuide.ts';
+import {
+  STRUCTURE_EDITOR_DOCS,
+  editorGuideSections,
+} from '../core/editorGuide.ts';
+
+import { KeyCaps } from './KeyCaps.tsx';
+
+/** What {@link StructureEditorHelp} is written for. */
+export type StructureEditorHelpProps = EditorGuideOptions;
+
+/**
+ * The guide to the structure editor: the keys that change the atom or bond
+ * under the pointer, the selection gestures, the stereo conventions, and links
+ * to the full documentation. Gestures that do nothing in the given editor are
+ * left out.
+ * @param props - See {@link StructureEditorHelpProps}.
+ * @returns The guide.
+ */
+export function StructureEditorHelp(
+  props: StructureEditorHelpProps,
+): ReactElement {
+  const sections = editorGuideSections(props);
+
+  return (
+    <div style={PANEL_STYLE} data-testid="structure-editor-help">
+      <p className={Classes.TEXT_MUTED} style={PARAGRAPH_STYLE}>
+        Hover a toolbar button to see what it does and its key.
+      </p>
+      {/* One grid for every section, so all the actions start on one edge. */}
+      <div style={GRID_STYLE}>
+        {sections.map((section) => (
+          <section key={section.title} style={ROW_STYLE}>
+            <h4 style={HEADING_STYLE}>{section.title}</h4>
+            {section.gestures.map((gesture) => (
+              <div key={gestureKey(gesture)} style={ROW_STYLE}>
+                <GestureInput input={gesture.input} />
+                <span>{gesture.action}</span>
+              </div>
+            ))}
+            {section.note === undefined ? null : (
+              <p className={Classes.TEXT_MUTED} style={NOTE_STYLE}>
+                {section.note}
+              </p>
+            )}
+          </section>
+        ))}
+      </div>
+      <p style={PARAGRAPH_STYLE}>
+        Learn more:{' '}
+        {STRUCTURE_EDITOR_DOCS.map((link, index) => (
+          <span key={link.url}>
+            {index === 0 ? null : ' · '}
+            <a href={link.url} target="_blank" rel="noopener noreferrer">
+              {link.title}
+            </a>
+          </span>
+        ))}
+      </p>
+    </div>
+  );
+}
+
+function GestureInput(props: { input: EditorGesture['input'] }): ReactElement {
+  return (
+    <span style={INPUT_STYLE}>
+      {props.input.map((part) =>
+        typeof part === 'string' ? (
+          <span key={part}>{part}</span>
+        ) : (
+          <KeyCaps key={part.key} keys={[part.key]} />
+        ),
+      )}
+    </span>
+  );
+}
+
+function gestureKey(gesture: EditorGesture): string {
+  const input = gesture.input
+    .map((part) => (typeof part === 'string' ? part : part.key))
+    .join(' ');
+  return `${input} ${gesture.action}`;
+}
+
+const PANEL_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 10,
+  width: 400,
+  maxHeight: 'min(70vh, 36rem)',
+  overflowY: 'auto',
+  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 HEADING_STYLE: CSSProperties = {
+  gridColumn: '1 / -1',
+  margin: '8px 0 0',
+  paddingBottom: 3,
+  borderBottom: `1px solid ${TOKEN.border}`,
+  color: TOKEN.textMuted,
+  fontSize: 11,
+  fontWeight: 700,
+  letterSpacing: '0.04em',
+  textTransform: 'uppercase',
+};
+
+const INPUT_STYLE: CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  gap: 4,
+  whiteSpace: 'nowrap',
+};
+
+const PARAGRAPH_STYLE: CSSProperties = { margin: 0, lineHeight: 1.45 };
+
+const NOTE_STYLE: CSSProperties = { ...PARAGRAPH_STYLE, gridColumn: '1 / -1' };

package/src/structure/ui/ToolbarTooltip.tsx

@@ -0,0 +1,95 @@
+import { Classes, Tooltip } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement, RefObject } from 'react';
+
+import type { EditorToolbarButton } from '../core/editorToolbar.ts';
+import {
+  EDITOR_TOOLBAR_BUTTONS,
+  isEditorToolbarButtonAvailable,
+} from '../core/editorToolbar.ts';
+
+import { KeyCaps } from './KeyCaps.tsx';
+import type { StructureEditorMode } from './editorChange.ts';
+import { useToolbarHover } from './useToolbarHover.ts';
+
+/** What {@link ToolbarTooltip} needs. */
+export interface ToolbarTooltipProps {
+  /** The positioned element wrapping the editor. */
+  containerRef: RefObject<HTMLElement | null>;
+  /** Which editor the toolbar belongs to, since some buttons are greyed. */
+  mode: StructureEditorMode;
+}
+
+/**
+ * The name, key and purpose of the toolbar button under the pointer.
+ *
+ * The toolbar is a canvas, so the tooltip is anchored to an invisible box laid
+ * over the button rather than to the button itself; the box lets the pointer
+ * through, so the editor still sees every hover and click.
+ * @param props - See {@link ToolbarTooltipProps}.
+ * @returns The tooltip, or nothing before a button has been hovered.
+ */
+export function ToolbarTooltip(
+  props: ToolbarTooltipProps,
+): ReactElement | null {
+  const { containerRef, mode } = props;
+  const hover = useToolbarHover(containerRef);
+  if (hover === null) return null;
+  const button = EDITOR_TOOLBAR_BUTTONS[hover.button];
+  if (button === undefined) return null;
+
+  return (
+    <Tooltip
+      isOpen={hover.open}
+      placement="right"
+      content={<ButtonTip button={button} mode={mode} />}
+      renderTarget={({ ref }) => (
+        <span ref={ref} aria-hidden style={{ ...TARGET_STYLE, ...hover.box }} />
+      )}
+    />
+  );
+}
+
+function ButtonTip(props: {
+  button: EditorToolbarButton;
+  mode: StructureEditorMode;
+}): ReactElement {
+  const { button, mode } = props;
+  const available = isEditorToolbarButtonAvailable(button, mode);
+
+  return (
+    <div style={TIP_STYLE} data-testid="structure-editor-tooltip">
+      <div style={HEAD_STYLE}>
+        <strong>{button.name}</strong>
+        {button.keys === undefined ? null : <KeyCaps keys={button.keys} />}
+      </div>
+      <div>{button.description}</div>
+      {available ? null : (
+        <div className={Classes.TEXT_MUTED}>
+          {button.availability === 'reaction'
+            ? 'Only when drawing a reaction.'
+            : 'Not available in this editor.'}
+        </div>
+      )}
+    </div>
+  );
+}
+
+const TARGET_STYLE: CSSProperties = {
+  position: 'absolute',
+  pointerEvents: 'none',
+};
+
+const TIP_STYLE: CSSProperties = {
+  display: 'flex',
+  flexDirection: 'column',
+  gap: 4,
+  maxWidth: 260,
+  lineHeight: 1.4,
+};
+
+const HEAD_STYLE: CSSProperties = {
+  display: 'flex',
+  alignItems: 'center',
+  justifyContent: 'space-between',
+  gap: 12,
+};

package/src/structure/ui/editorChange.ts

@@ -0,0 +1,81 @@
+/**
+ * What the structure editor reports after an edit.
+ *
+ * Only types are imported from react-ocl and openchemlib, so this module can be
+ * reached from the `react-cheminfo/structure` barrel without pulling either in.
+ */
+
+import type { Molecule } from 'openchemlib';
+import type {
+  CanvasEditorOnChangeMolecule,
+  CanvasEditorOnChangeReaction,
+} from 'react-ocl';
+
+/** What the editor draws: one structure, or a reaction with its arrow. */
+export type StructureEditorMode = 'molecule' | 'reaction';
+
+/** The notations every change carries, whichever the editor. */
+interface StructureEditorNotations {
+  /**
+   * The idCode, with the coordinates the editor laid out written after a
+   * space. `splitIdCode` takes the two apart.
+   */
+  idCode: string;
+  /** The V2000 molfile of a molecule, or the RXN file of a reaction. */
+  molfile: string;
+  /** The SMILES of a molecule, or the reaction SMILES. */
+  smiles: string;
+}
+
+/** What a molecule editor holds at the moment it changed. */
+export interface StructureEditorMoleculeChange extends StructureEditorNotations {
+  mode: 'molecule';
+  /**
+   * A copy of the drawn molecule, with its coordinates. It is taken when the
+   * edit happens, so it still describes that edit when it arrives after the
+   * debounce, and the caller may modify it without touching the canvas.
+   */
+  molecule: Molecule;
+}
+
+/** What a reaction editor holds at the moment it changed. */
+export interface StructureEditorReactionChange extends StructureEditorNotations {
+  mode: 'reaction';
+}
+
+/** Everything the editor holds at the moment it changed. */
+export type StructureEditorChange =
+  StructureEditorMoleculeChange | StructureEditorReactionChange;
+
+/**
+ * Read a molecule editor's event out, while it still describes the edit.
+ * @param event - The event react-ocl passes to its callback.
+ * @returns The change, independent of the editor from then on.
+ */
+export function moleculeChange(
+  event: CanvasEditorOnChangeMolecule,
+): StructureEditorMoleculeChange {
+  return {
+    mode: 'molecule',
+    idCode: event.getIdcode(),
+    molfile: event.getMolfile(),
+    smiles: event.getSmiles(),
+    molecule: event.getMolecule(),
+  };
+}
+
+/**
+ * Read a reaction editor's event out, while it still describes the edit.
+ * @param event - The event react-ocl passes to its callback.
+ * @returns The change, independent of the editor from then on.
+ */
+export function reactionChange(
+  event: CanvasEditorOnChangeReaction,
+): StructureEditorReactionChange {
+  return {
+    mode: 'reaction',
+    idCode: event.getIdcode(),
+    molfile: event.getRxn(),
+    smiles: event.getSmiles(),
+  };
+}

package/src/structure/ui/index.ts

@@ -13,10 +13,14 @@
 export type {
   StructureEditorChange,
   StructureEditorMode,
-} from './EditorCanvas.tsx';
+  StructureEditorMoleculeChange,
+  StructureEditorReactionChange,
+} from './editorChange.ts';
 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 { StructureEditorHelpProps } from './StructureEditorHelp.tsx';
+export { StructureEditorHelp } from './StructureEditorHelp.tsx';
 export type { ToolbarFloorOptions } from './useToolbarFloor.ts';
 export { useToolbarFloor } from './useToolbarFloor.ts';

package/src/structure/ui/useToolbarFloor.ts

@@ -3,6 +3,8 @@ import { useLayoutEffect, useRef } from 'react';
 
 import { toolbarFloorHeight } from '../core/toolbarFloor.ts';
 
+import { watchToolbar } from './watchToolbar.ts';
+
 /** What {@link useToolbarFloor} needs. */
 export interface ToolbarFloorOptions {
   /**
@@ -38,62 +40,21 @@ export function useToolbarFloor(
     const container = containerRef.current;
     if (container === null) return;
 
-    let toolbar: HTMLCanvasElement | null = null;
-    let size: ResizeObserver | null = null;
-
-    const attach = (): void => {
-      const found = findToolbar(container);
-      if (found === null) return;
-      size?.disconnect();
-      toolbar = found;
-      size = new ResizeObserver(() => {
+    return watchToolbar(container, (toolbar) => {
+      const size = new ResizeObserver(() => {
         // offsetHeight, because a dialog opens under a scaling transform and a
         // measured rectangle would be that of the half drawn toolbar.
-        const height = found.offsetHeight;
+        const height = toolbar.offsetHeight;
         // Zero is a toolbar being torn down or not yet laid out, never a
         // toolbar that needs no room: writing the fallback for it would undo a
         // correct floor and leave the palette cut off.
         if (height === 0) return;
         container.style.minHeight = `${toolbarFloorHeight(height, minHeight)}px`;
       });
-      size.observe(found);
-    };
-
-    // The editor is imported lazily and builds itself asynchronously, so it is
-    // almost never there on the first look, and how long it takes is a cold
-    // module graph and a network away from anything this code can predict. So
-    // the arrival is watched for rather than waited out: a deadline that
-    // expires leaves the toolbar cut off for the life of the page, with
-    // nothing on screen to say why.
-    const arrivals = new MutationObserver(() => {
-      if (toolbar?.isConnected === true) return;
-      attach();
+      size.observe(toolbar);
+      return () => size.disconnect();
     });
-    arrivals.observe(container, { childList: true, subtree: true });
-    attach();
-
-    return () => {
-      arrivals.disconnect();
-      size?.disconnect();
-    };
   }, [minHeight, revision]);
 
   return containerRef;
 }
-
-/**
- * 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/ui/useToolbarHover.ts

@@ -0,0 +1,134 @@
+import type { RefObject } from 'react';
+import { useEffect, useState } from 'react';
+
+import type { EditorToolbarButtonBox } from '../core/editorToolbarGeometry.ts';
+import {
+  editorToolbarButtonAt,
+  editorToolbarButtonBox,
+} from '../core/editorToolbarGeometry.ts';
+
+import { watchToolbar } from './watchToolbar.ts';
+
+/** The toolbar button the pointer rests on, or last rested on. */
+export interface ToolbarHover {
+  /** The button's index in `EDITOR_TOOLBAR_BUTTONS`. */
+  button: number;
+  /** Where the button is drawn, relative to the container's padding box. */
+  box: EditorToolbarButtonBox;
+  /**
+   * Whether its tooltip is showing. The last button is kept after the pointer
+   * leaves, so a closing tooltip fades out with its text rather than empty.
+   */
+  open: boolean;
+}
+
+/**
+ * Follow the pointer over the editor's toolbar.
+ *
+ * The first button waits for the pointer to rest, so crossing the toolbar on
+ * the way to the drawing opens nothing; once one is showing, the next follows
+ * at once. Pressing a button hides its tooltip until the pointer moves on,
+ * since whoever pressed it no longer needs telling. Touch is ignored: a finger
+ * has no hover, and a tooltip opened by a tap would cover the canvas.
+ * @param containerRef - The element wrapping the editor, positioned so the
+ * returned box can be laid over the button.
+ * @returns The button under the pointer, or null before any has been hovered.
+ */
+export function useToolbarHover(
+  containerRef: RefObject<HTMLElement | null>,
+): ToolbarHover | null {
+  const [hover, setHover] = useState<ToolbarHover | null>(null);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (container === null) return;
+
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    let current = -1;
+    let pressed = -1;
+    let open = false;
+
+    const show = (toolbar: HTMLCanvasElement, button: number): void => {
+      open = true;
+      setHover({ button, box: boxIn(container, toolbar, button), open });
+    };
+    const hide = (): void => {
+      clearTimeout(timer);
+      if (!open) return;
+      open = false;
+      setHover((previous) =>
+        previous === null ? null : { ...previous, open: false },
+      );
+    };
+
+    const onLeave = (): void => {
+      current = -1;
+      pressed = -1;
+      hide();
+    };
+    const onDown = (): void => {
+      pressed = current;
+      hide();
+    };
+
+    const stop = watchToolbar(container, (toolbar) => {
+      const onMove = (event: PointerEvent): void => {
+        if (event.pointerType === 'touch') return;
+        const button = editorToolbarButtonAt(
+          event.offsetX,
+          event.offsetY,
+          toolbar.offsetHeight,
+        );
+        if (button === current) return;
+        current = button;
+        if (button !== pressed) pressed = -1;
+        if (button === -1 || button === pressed) {
+          hide();
+          return;
+        }
+        clearTimeout(timer);
+        if (open) {
+          show(toolbar, button);
+          return;
+        }
+        timer = setTimeout(() => show(toolbar, button), OPEN_DELAY);
+      };
+
+      toolbar.addEventListener('pointermove', onMove);
+      toolbar.addEventListener('pointerleave', onLeave);
+      toolbar.addEventListener('pointerdown', onDown);
+      return () => {
+        toolbar.removeEventListener('pointermove', onMove);
+        toolbar.removeEventListener('pointerleave', onLeave);
+        toolbar.removeEventListener('pointerdown', onDown);
+        onLeave();
+      };
+    });
+
+    return () => {
+      stop();
+      clearTimeout(timer);
+    };
+  }, [containerRef]);
+
+  return hover;
+}
+
+// Long enough that sweeping the pointer across the toolbar opens nothing.
+const OPEN_DELAY = 250;
+
+function boxIn(
+  container: HTMLElement,
+  toolbar: HTMLCanvasElement,
+  button: number,
+): EditorToolbarButtonBox {
+  const box = editorToolbarButtonBox(button, toolbar.offsetHeight);
+  const toolbarRect = toolbar.getBoundingClientRect();
+  const containerRect = container.getBoundingClientRect();
+  return {
+    ...box,
+    left:
+      toolbarRect.left - containerRect.left - container.clientLeft + box.left,
+    top: toolbarRect.top - containerRect.top - container.clientTop + box.top,
+  };
+}

package/src/structure/ui/watchToolbar.ts

@@ -0,0 +1,59 @@
+/**
+ * Run something against the editor's toolbar canvas as soon as it exists, and
+ * again against each new one the editor builds.
+ *
+ * The editor is imported lazily and builds itself asynchronously, so the
+ * toolbar is almost never there on the first look, and how long it takes is a
+ * cold module graph and a network away from anything this code can predict.
+ * So its arrival is watched for rather than waited out: a deadline that
+ * expires leaves whatever depends on the toolbar missing for the life of the
+ * page, with nothing on screen to say why.
+ * @param container - The element wrapping the editor.
+ * @param onToolbar - Called with each toolbar found; what it returns is called
+ * when that toolbar is replaced or the watch ends.
+ * @returns A function ending the watch.
+ */
+export function watchToolbar(
+  container: HTMLElement,
+  onToolbar: (toolbar: HTMLCanvasElement) => () => void,
+): () => void {
+  let toolbar: HTMLCanvasElement | null = null;
+  let release: (() => void) | null = null;
+
+  const attach = (): void => {
+    const found = findToolbar(container);
+    if (found === null) return;
+    release?.();
+    toolbar = found;
+    release = onToolbar(found);
+  };
+
+  const arrivals = new MutationObserver(() => {
+    if (toolbar?.isConnected === true) return;
+    attach();
+  });
+  arrivals.observe(container, { childList: true, subtree: true });
+  attach();
+
+  return () => {
+    arrivals.disconnect();
+    release?.();
+  };
+}
+
+/**
+ * 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;
+}