react-cheminfo 0.16.0 → 0.18.0

package/src/structure/ui/EditorHelpButton.tsx

@@ -0,0 +1,70 @@
+import { Button, PopoverNext, Tooltip } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement, RefObject } from 'react';
+import { useEffect, useState } from 'react';
+
+import { StructureEditorHelp } from './StructureEditorHelp.tsx';
+import type { StructureEditorMode } from './editorChange.ts';
+
+/** What {@link EditorHelpButton} needs. */
+export interface EditorHelpButtonProps {
+  /** The element wrapping the editor, which F1 is listened for on. */
+  containerRef: RefObject<HTMLElement | null>;
+  /** Which editor the guide is written for. */
+  mode: StructureEditorMode;
+  /** Whether the editor draws a query fragment. */
+  fragment: boolean;
+}
+
+/**
+ * The editor's help button, in the corner of the drawing, opening the guide to
+ * the mouse and the keyboard.
+ *
+ * F1 opens it too: openchemlib binds that key to a help dialog it does not
+ * implement on the web.
+ * @param props - See {@link EditorHelpButtonProps}.
+ * @returns The button and its popover.
+ */
+export function EditorHelpButton(props: EditorHelpButtonProps): ReactElement {
+  const { containerRef, mode, fragment } = props;
+  const [isOpen, setIsOpen] = useState(false);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (container === null) return;
+    const onKeyDown = (event: KeyboardEvent): void => {
+      if (event.key !== 'F1') return;
+      event.preventDefault();
+      setIsOpen(true);
+    };
+    container.addEventListener('keydown', onKeyDown);
+    return () => container.removeEventListener('keydown', onKeyDown);
+  }, [containerRef]);
+
+  return (
+    <div style={CORNER_STYLE}>
+      <PopoverNext
+        isOpen={isOpen}
+        onInteraction={setIsOpen}
+        placement="left-start"
+        content={<StructureEditorHelp mode={mode} fragment={fragment} />}
+      >
+        <Tooltip content={LABEL} placement="left" disabled={isOpen}>
+          <Button
+            variant="minimal"
+            size="small"
+            icon="help"
+            aria-label={LABEL}
+          />
+        </Tooltip>
+      </PopoverNext>
+    </div>
+  );
+}
+
+const LABEL = 'Mouse and keyboard';
+
+const CORNER_STYLE: CSSProperties = {
+  position: 'absolute',
+  top: 4,
+  right: 4,
+};

package/src/structure/ui/KeyCaps.tsx

@@ -0,0 +1,40 @@
+import { Classes } from '@blueprintjs/core';
+import type { CSSProperties, ReactElement } from 'react';
+
+import { editorKeyLabel } from '../core/editorGuide.ts';
+
+/**
+ * Keys pressed together, each drawn as a key cap, `Mod` as the modifier the
+ * editor listens to on this platform.
+ * @param props - The keys.
+ * @param props.keys - The keys, unique within the list.
+ * @returns The key caps.
+ */
+export function KeyCaps(props: { keys: readonly string[] }): ReactElement {
+  const isMac = isMacPlatform();
+  return (
+    <span style={KEYS_STYLE}>
+      {props.keys.map((key) => (
+        <kbd key={key} className={Classes.KEY}>
+          {editorKeyLabel(key, isMac)}
+        </kbd>
+      ))}
+    </span>
+  );
+}
+
+/**
+ * Whether the page runs on a Mac, decided as openchemlib decides it, so the
+ * cap shown is the modifier the editor actually reads: ⌘ there, Ctrl elsewhere.
+ * @returns True on a Mac.
+ */
+function isMacPlatform(): boolean {
+  return typeof navigator !== 'undefined' && navigator.platform === 'MacIntel';
+}
+
+const KEYS_STYLE: CSSProperties = {
+  display: 'inline-flex',
+  alignItems: 'center',
+  gap: 3,
+  whiteSpace: 'nowrap',
+};

package/src/structure/ui/StructureEditor.tsx

@@ -8,15 +8,25 @@
  */
 
 import type { CSSProperties, ReactElement } from 'react';
-import { Suspense, lazy, useCallback, useEffect, useRef } from 'react';
+import {
+  Suspense,
+  lazy,
+  useCallback,
+  useEffect,
+  useRef,
+  useState,
+} from 'react';
 import type { CanvasEditorInputFormat } from 'react-ocl';
 
 import { TOKEN } from '../../tokens/core/familyTokens.ts';
+import { createPendingCall } from '../core/pendingCall.ts';
 
+import { EditorHelpButton } from './EditorHelpButton.tsx';
+import { ToolbarTooltip } from './ToolbarTooltip.tsx';
 import type {
   StructureEditorChange,
   StructureEditorMode,
-} from './EditorCanvas.tsx';
+} from './editorChange.ts';
 import { useToolbarFloor } from './useToolbarFloor.ts';
 
 const EditorCanvas = lazy(async () => {
@@ -76,6 +86,12 @@ export interface StructureEditorProps {
    * @default 'molecule'
    */
   mode?: StructureEditorMode;
+  /**
+   * Explain each toolbar button in a tooltip, and put a button in the corner
+   * that opens a guide to the mouse and the keyboard, which F1 opens too.
+   * @default true
+   */
+  help?: boolean;
   /**
    * Class the container carries, so a site can reach it from its stylesheet.
    * @default undefined
@@ -90,7 +106,8 @@ export interface StructureEditorProps {
 
 /**
  * The canvas structure editor, sized to fill its container and never to hide
- * part of its toolbar.
+ * part of its toolbar, with a tooltip on every toolbar button and a guide to
+ * the keys.
  * @param props - What to draw, when to reload it, and where to send it.
  * @returns The editor.
  */
@@ -104,6 +121,7 @@ export function StructureEditor(props: StructureEditorProps): ReactElement {
     debounce = 300,
     minHeight = 320,
     mode = 'molecule',
+    help = true,
     className,
     style,
   } = props;
@@ -126,6 +144,16 @@ export function StructureEditor(props: StructureEditorProps): ReactElement {
           value={value}
           mode={mode}
         />
+        {help ? (
+          <>
+            <ToolbarTooltip containerRef={containerRef} mode={mode} />
+            <EditorHelpButton
+              containerRef={containerRef}
+              mode={mode}
+              fragment={fragment}
+            />
+          </>
+        ) : null}
       </Suspense>
     </div>
   );
@@ -136,6 +164,8 @@ export function StructureEditor(props: StructureEditorProps): ReactElement {
  *
  * 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.
+ * An editor removed mid-burst — a tab switched, a card folded — still reports
+ * its last edit, which would otherwise be lost with the timer.
  * @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
@@ -147,33 +177,21 @@ function useDebounced(
   delay: number,
   resetKey: number,
 ): (change: StructureEditorChange) => void {
-  const timerRef = useRef<ReturnType<typeof setTimeout> | null>(null);
+  const [pending] = useState(createPendingCall<StructureEditorChange>);
   const onChangeRef = useRef(onChange);
   useEffect(() => {
     onChangeRef.current = onChange;
   });
   useEffect(() => {
-    return () => {
-      if (timerRef.current !== null) {
-        clearTimeout(timerRef.current);
-        timerRef.current = null;
-      }
-    };
-  }, [resetKey]);
+    pending.drop();
+  }, [pending, resetKey]);
+  useEffect(() => () => pending.flush(), [pending]);
 
   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);
+      pending.push(change, delay, (value) => onChangeRef.current(value));
     },
-    [delay],
+    [pending, delay],
   );
 }
 

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