react-cheminfo 0.17.0 → 0.18.0

package/lib/structure/ui/index.d.ts

@@ -9,11 +9,13 @@
  * 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 { StructureEditorChange, StructureEditorMode, 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';
 //# sourceMappingURL=index.d.ts.map

package/lib/structure/ui/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/structure/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,YAAY,EACV,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/structure/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,YAAY,EACV,qBAAqB,EACrB,mBAAmB,EACnB,6BAA6B,EAC7B,6BAA6B,GAC9B,MAAM,mBAAmB,CAAC;AAC3B,YAAY,EAAE,eAAe,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACvE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5C,YAAY,EAAE,oBAAoB,EAAE,MAAM,uBAAuB,CAAC;AAClE,OAAO,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAC;AACxD,YAAY,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAC1E,OAAO,EAAE,mBAAmB,EAAE,MAAM,2BAA2B,CAAC;AAChE,YAAY,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAChE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}

package/lib/structure/ui/index.js

@@ -11,5 +11,6 @@
  */
 export { Structure } from "./Structure.js";
 export { StructureEditor } from "./StructureEditor.js";
+export { StructureEditorHelp } from "./StructureEditorHelp.js";
 export { useToolbarFloor } from "./useToolbarFloor.js";
 //# sourceMappingURL=index.js.map

package/lib/structure/ui/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/structure/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAOH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAiB,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAuB,CAAC;AAExD,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/structure/ui/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AASH,OAAO,EAAE,SAAS,EAAE,MAAM,gBAAiB,CAAC;AAE5C,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAuB,CAAC;AAExD,OAAO,EAAE,mBAAmB,EAAE,MAAM,0BAA2B,CAAC;AAEhE,OAAO,EAAE,eAAe,EAAE,MAAM,sBAAsB,CAAC"}

package/lib/structure/ui/useToolbarFloor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useToolbarFloor.d.ts","sourceRoot":"","sources":["../../../src/structure/ui/useToolbarFloor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAKvC,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,OAAO,GAAE,mBAAwB,GAChC,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAiDlC"}
+{"version":3,"file":"useToolbarFloor.d.ts","sourceRoot":"","sources":["../../../src/structure/ui/useToolbarFloor.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAOvC,0CAA0C;AAC1C,MAAM,WAAW,mBAAmB;IAClC;;;;OAIG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAC7B,OAAO,GAAE,mBAAwB,GAChC,SAAS,CAAC,cAAc,GAAG,IAAI,CAAC,CAyBlC"}

package/lib/structure/ui/useToolbarFloor.js

@@ -1,5 +1,6 @@
 import { useLayoutEffect, useRef } from 'react';
 import { toolbarFloorHeight } from "../core/toolbarFloor.js";
+import { watchToolbar } from "./watchToolbar.js";
 /**
  * Give an editor's container a minimum height that shows the whole toolbar.
  *
@@ -16,18 +17,11 @@ export function useToolbarFloor(options = {}) {
         const container = containerRef.current;
         if (container === null)
             return;
-        let toolbar = null;
-        let size = null;
-        const attach = () => {
-            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.
@@ -35,43 +29,10 @@ export function useToolbarFloor(options = {}) {
                     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) {
-    for (const element of container.querySelectorAll('*')) {
-        for (const child of element.shadowRoot?.children ?? []) {
-            if (child instanceof HTMLCanvasElement)
-                return child;
-        }
-    }
-    return null;
-}
 //# sourceMappingURL=useToolbarFloor.js.map

package/lib/structure/ui/useToolbarFloor.js.map

@@ -1 +1 @@
-{"version":3,"file":"useToolbarFloor.js","sourceRoot":"","sources":["../../../src/structure/ui/useToolbarFloor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAEhD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAkB7D;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,UAA+B,EAAE;IAEjC,MAAM,EAAE,SAAS,GAAG,GAAG,EAAE,QAAQ,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC;IAClD,MAAM,YAAY,GAAG,MAAM,CAAiB,IAAI,CAAC,CAAC;IAElD,eAAe,CAAC,GAAG,EAAE;QACnB,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC;QACvC,IAAI,SAAS,KAAK,IAAI;YAAE,OAAO;QAE/B,IAAI,OAAO,GAA6B,IAAI,CAAC;QAC7C,IAAI,IAAI,GAA0B,IAAI,CAAC;QAEvC,MAAM,MAAM,GAAG,GAAS,EAAE;YACxB,MAAM,KAAK,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;YACrC,IAAI,KAAK,KAAK,IAAI;gBAAE,OAAO;YAC3B,IAAI,EAAE,UAAU,EAAE,CAAC;YACnB,OAAO,GAAG,KAAK,CAAC;YAChB,IAAI,GAAG,IAAI,cAAc,CAAC,GAAG,EAAE;gBAC7B,uEAAuE;gBACvE,8DAA8D;gBAC9D,MAAM,MAAM,GAAG,KAAK,CAAC,YAAY,CAAC;gBAClC,iEAAiE;gBACjE,uEAAuE;gBACvE,+CAA+C;gBAC/C,IAAI,MAAM,KAAK,CAAC;oBAAE,OAAO;gBACzB,SAAS,CAAC,KAAK,CAAC,SAAS,GAAG,GAAG,kBAAkB,CAAC,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC;YAC3E,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC,CAAC;QAEF,2EAA2E;QAC3E,wEAAwE;QACxE,0EAA0E;QAC1E,qEAAqE;QACrE,oEAAoE;QACpE,gCAAgC;QAChC,MAAM,QAAQ,GAAG,IAAI,gBAAgB,CAAC,GAAG,EAAE;YACzC,IAAI,OAAO,EAAE,WAAW,KAAK,IAAI;gBAAE,OAAO;YAC1C,MAAM,EAAE,CAAC;QACX,CAAC,CAAC,CAAC;QACH,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;QAChE,MAAM,EAAE,CAAC;QAET,OAAO,GAAG,EAAE;YACV,QAAQ,CAAC,UAAU,EAAE,CAAC;YACtB,IAAI,EAAE,UAAU,EAAE,CAAC;QACrB,CAAC,CAAC;IACJ,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;IAE1B,OAAO,YAAY,CAAC;AACtB,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,WAAW,CAAC,SAAsB;IACzC,KAAK,MAAM,OAAO,IAAI,SAAS,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;QACtD,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,UAAU,EAAE,QAAQ,IAAI,EAAE,EAAE,CAAC;YACvD,IAAI,KAAK,YAAY,iBAAiB;gBAAE,OAAO,KAAK,CAAC;QACvD,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}
+{"version":3,"file":"useToolbarFloor.js","sourceRoot":"","sources":["../../../src/structure/ui/useToolbarFloor.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,MAAM,OAAO,CAAC;AAEhD,OAAO,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAE7D,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AAkBjD;;;;;;;;GAQG;AACH,MAAM,UAAU,eAAe,CAC7B,UAA+B,EAAE;IAEjC,MAAM,EAAE,SAAS,GAAG,GAAG,EAAE,QAAQ,GAAG,CAAC,EAAE,GAAG,OAAO,CAAC;IAClD,MAAM,YAAY,GAAG,MAAM,CAAiB,IAAI,CAAC,CAAC;IAElD,eAAe,CAAC,GAAG,EAAE;QACnB,MAAM,SAAS,GAAG,YAAY,CAAC,OAAO,CAAC;QACvC,IAAI,SAAS,KAAK,IAAI;YAAE,OAAO;QAE/B,OAAO,YAAY,CAAC,SAAS,EAAE,CAAC,OAAO,EAAE,EAAE;YACzC,MAAM,IAAI,GAAG,IAAI,cAAc,CAAC,GAAG,EAAE;gBACnC,uEAAuE;gBACvE,8DAA8D;gBAC9D,MAAM,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;gBACpC,iEAAiE;gBACjE,uEAAuE;gBACvE,+CAA+C;gBAC/C,IAAI,MAAM,KAAK,CAAC;oBAAE,OAAO;gBACzB,SAAS,CAAC,KAAK,CAAC,SAAS,GAAG,GAAG,kBAAkB,CAAC,MAAM,EAAE,SAAS,CAAC,IAAI,CAAC;YAC3E,CAAC,CAAC,CAAC;YACH,IAAI,CAAC,OAAO,CAAC,OAAO,CAAC,CAAC;YACtB,OAAO,GAAG,EAAE,CAAC,IAAI,CAAC,UAAU,EAAE,CAAC;QACjC,CAAC,CAAC,CAAC;IACL,CAAC,EAAE,CAAC,SAAS,EAAE,QAAQ,CAAC,CAAC,CAAC;IAE1B,OAAO,YAAY,CAAC;AACtB,CAAC"}

package/lib/structure/ui/useToolbarHover.d.ts

@@ -0,0 +1,28 @@
+import type { RefObject } from 'react';
+import type { EditorToolbarButtonBox } from '../core/editorToolbarGeometry.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 declare function useToolbarHover(containerRef: RefObject<HTMLElement | null>): ToolbarHover | null;
+//# sourceMappingURL=useToolbarHover.d.ts.map

package/lib/structure/ui/useToolbarHover.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useToolbarHover.d.ts","sourceRoot":"","sources":["../../../src/structure/ui/useToolbarHover.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAGvC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,kCAAkC,CAAC;AAQ/E,kEAAkE;AAClE,MAAM,WAAW,YAAY;IAC3B,sDAAsD;IACtD,MAAM,EAAE,MAAM,CAAC;IACf,0EAA0E;IAC1E,GAAG,EAAE,sBAAsB,CAAC;IAC5B;;;OAGG;IACH,IAAI,EAAE,OAAO,CAAC;CACf;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,GAC1C,YAAY,GAAG,IAAI,CA4ErB"}

package/lib/structure/ui/useToolbarHover.js

@@ -0,0 +1,96 @@
+import { useEffect, useState } from 'react';
+import { editorToolbarButtonAt, editorToolbarButtonBox, } from "../core/editorToolbarGeometry.js";
+import { watchToolbar } from "./watchToolbar.js";
+/**
+ * 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) {
+    const [hover, setHover] = useState(null);
+    useEffect(() => {
+        const container = containerRef.current;
+        if (container === null)
+            return;
+        let timer;
+        let current = -1;
+        let pressed = -1;
+        let open = false;
+        const show = (toolbar, button) => {
+            open = true;
+            setHover({ button, box: boxIn(container, toolbar, button), open });
+        };
+        const hide = () => {
+            clearTimeout(timer);
+            if (!open)
+                return;
+            open = false;
+            setHover((previous) => previous === null ? null : { ...previous, open: false });
+        };
+        const onLeave = () => {
+            current = -1;
+            pressed = -1;
+            hide();
+        };
+        const onDown = () => {
+            pressed = current;
+            hide();
+        };
+        const stop = watchToolbar(container, (toolbar) => {
+            const onMove = (event) => {
+                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, toolbar, button) {
+    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,
+    };
+}
+//# sourceMappingURL=useToolbarHover.js.map

package/lib/structure/ui/useToolbarHover.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useToolbarHover.js","sourceRoot":"","sources":["../../../src/structure/ui/useToolbarHover.ts"],"names":[],"mappings":"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"}

package/lib/structure/ui/watchToolbar.d.ts

@@ -0,0 +1,17 @@
+/**
+ * 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 declare function watchToolbar(container: HTMLElement, onToolbar: (toolbar: HTMLCanvasElement) => () => void): () => void;
+//# sourceMappingURL=watchToolbar.d.ts.map

package/lib/structure/ui/watchToolbar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchToolbar.d.ts","sourceRoot":"","sources":["../../../src/structure/ui/watchToolbar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,YAAY,CAC1B,SAAS,EAAE,WAAW,EACtB,SAAS,EAAE,CAAC,OAAO,EAAE,iBAAiB,KAAK,MAAM,IAAI,GACpD,MAAM,IAAI,CAuBZ"}

package/lib/structure/ui/watchToolbar.js

@@ -0,0 +1,56 @@
+/**
+ * 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, onToolbar) {
+    let toolbar = null;
+    let release = null;
+    const attach = () => {
+        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) {
+    for (const element of container.querySelectorAll('*')) {
+        for (const child of element.shadowRoot?.children ?? []) {
+            if (child instanceof HTMLCanvasElement)
+                return child;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=watchToolbar.js.map

package/lib/structure/ui/watchToolbar.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"watchToolbar.js","sourceRoot":"","sources":["../../../src/structure/ui/watchToolbar.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,YAAY,CAC1B,SAAsB,EACtB,SAAqD;IAErD,IAAI,OAAO,GAA6B,IAAI,CAAC;IAC7C,IAAI,OAAO,GAAwB,IAAI,CAAC;IAExC,MAAM,MAAM,GAAG,GAAS,EAAE;QACxB,MAAM,KAAK,GAAG,WAAW,CAAC,SAAS,CAAC,CAAC;QACrC,IAAI,KAAK,KAAK,IAAI;YAAE,OAAO;QAC3B,OAAO,EAAE,EAAE,CAAC;QACZ,OAAO,GAAG,KAAK,CAAC;QAChB,OAAO,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC;IAC7B,CAAC,CAAC;IAEF,MAAM,QAAQ,GAAG,IAAI,gBAAgB,CAAC,GAAG,EAAE;QACzC,IAAI,OAAO,EAAE,WAAW,KAAK,IAAI;YAAE,OAAO;QAC1C,MAAM,EAAE,CAAC;IACX,CAAC,CAAC,CAAC;IACH,QAAQ,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC;IAChE,MAAM,EAAE,CAAC;IAET,OAAO,GAAG,EAAE;QACV,QAAQ,CAAC,UAAU,EAAE,CAAC;QACtB,OAAO,EAAE,EAAE,CAAC;IACd,CAAC,CAAC;AACJ,CAAC;AAED;;;;;;;GAOG;AACH,SAAS,WAAW,CAAC,SAAsB;IACzC,KAAK,MAAM,OAAO,IAAI,SAAS,CAAC,gBAAgB,CAAC,GAAG,CAAC,EAAE,CAAC;QACtD,KAAK,MAAM,KAAK,IAAI,OAAO,CAAC,UAAU,EAAE,QAAQ,IAAI,EAAE,EAAE,CAAC;YACvD,IAAI,KAAK,YAAY,iBAAiB;gBAAE,OAAO,KAAK,CAAC;QACvD,CAAC;IACH,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "react-cheminfo",
-  "version": "0.17.0",
+  "version": "0.18.0",
   "license": "MIT",
   "description": "React components, hooks and framework-free helpers shared by the cheminfo sites: site chrome, citations, sharing, routing, pedagogy, charts, and the structure, orbital and 3D molecule viewers",
   "author": "Luc Patiny",

package/src/structure/core/editorGuide.ts

@@ -0,0 +1,221 @@
+/**
+ * What the keyboard and the mouse do in the openchemlib canvas editor, beyond
+ * what its toolbar shows: the keys that change the atom or the bond under the
+ * pointer, the selection gestures and the stereo conventions.
+ */
+
+/** A key, drawn as a key cap. `Mod` is ⌘ on a Mac and Ctrl elsewhere. */
+export interface EditorGuideKey {
+  key: string;
+}
+
+/** Which editors a gesture applies to. */
+export type EditorGuideScope = 'fragment' | 'molecule' | 'reaction';
+
+/** One gesture and what it does. */
+export interface EditorGesture {
+  /** Keys, and plain text for the mouse part; unique within one gesture. */
+  input: ReadonlyArray<string | EditorGuideKey>;
+  action: string;
+  /**
+   * The only editor the gesture works in.
+   * @default undefined — every editor
+   */
+  only?: EditorGuideScope;
+}
+
+/** Gestures that share a context, such as the pointer resting on an atom. */
+export interface EditorGuideSection {
+  title: string;
+  gestures: readonly EditorGesture[];
+  /**
+   * A sentence read after the gestures.
+   * @default undefined
+   */
+  note?: string;
+}
+
+/** A page of the full documentation. */
+export interface EditorGuideLink {
+  title: string;
+  url: string;
+}
+
+/** The sections, in the order the guide lists them. */
+export const STRUCTURE_EDITOR_GUIDE: readonly EditorGuideSection[] = [
+  {
+    title: 'Pointer on an atom',
+    gestures: [
+      { input: ['Type', { key: 'n' }, { key: 'a' }], action: 'Make it Na' },
+      {
+        input: ['Type', { key: 'p' }, { key: 'h' }],
+        action: 'Attach a phenyl; Me, Et, Boc, TMS… work too',
+      },
+      {
+        input: [{ key: 'Enter' }, 'or', { key: 'Esc' }],
+        action: 'Apply or forget what was typed',
+      },
+      {
+        input: [{ key: '1' }, '…', { key: '9' }],
+        action: 'Attach a chain of that many carbons',
+      },
+      {
+        input: [{ key: '+' }, 'or', { key: '-' }],
+        action: 'Raise or lower the charge',
+      },
+      { input: [{ key: '.' }], action: 'Add or remove a radical' },
+      { input: [{ key: ':' }], action: 'Make it a triplet, then a singlet' },
+      { input: [{ key: '?' }], action: 'Make it a connection point' },
+      {
+        input: [{ key: 'q' }],
+        action: 'Edit its query features',
+        only: 'fragment',
+      },
+      { input: [{ key: 'x' }], action: 'Accept any halogen', only: 'fragment' },
+      { input: [{ key: 'Delete' }], action: 'Delete it' },
+    ],
+    note: 'What is typed shows black for an element, blue for a group, grey while incomplete and red when unknown.',
+  },
+  {
+    title: 'Pointer on a bond',
+    gestures: [
+      {
+        input: [{ key: '1' }, { key: '2' }, { key: '3' }],
+        action: 'Single, double or triple',
+      },
+      { input: [{ key: '0' }], action: 'Zero-order (metal–ligand) bond' },
+      {
+        input: [{ key: 'u' }, 'or', { key: 'd' }],
+        action: 'Up or down stereo bond',
+      },
+      { input: [{ key: 'c' }], action: 'Double bond of unknown geometry' },
+      { input: [{ key: 'v' }], action: 'Fuse a 3-membered ring' },
+      {
+        input: [{ key: '4' }, '…', { key: '7' }],
+        action: 'Fuse a ring of that size',
+      },
+      {
+        input: [{ key: 'a' }, 'or', { key: 'b' }],
+        action: 'Fuse a benzene ring',
+      },
+      {
+        input: [{ key: 'q' }],
+        action: 'Edit its query features',
+        only: 'fragment',
+      },
+      { input: [{ key: 'Delete' }], action: 'Delete it' },
+    ],
+  },
+  {
+    title: 'Anywhere',
+    gestures: [
+      { input: [{ key: 'Mod' }, { key: 'Z' }], action: 'Undo' },
+      { input: [{ key: 'Mod' }, { key: 'C' }], action: 'Copy the structure' },
+      {
+        input: [{ key: 'Mod' }, { key: 'V' }],
+        action: 'Paste a molfile, a SMILES or an idCode',
+      },
+      { input: [{ key: 'Delete' }], action: 'Delete the selection' },
+      {
+        input: [{ key: 'h' }, 'or', { key: 'v' }],
+        action: 'Flip horizontally or vertically',
+        only: 'molecule',
+      },
+      { input: [{ key: 'F1' }], action: 'Open this guide' },
+    ],
+    note: 'Keys act once the drawing has been clicked. On empty canvas, a key picks the tool whose tooltip shows it.',
+  },
+  {
+    title: 'Selecting',
+    gestures: [
+      { input: ['Drag'], action: 'Select what the lasso encloses' },
+      { input: [{ key: 'Alt' }, '+ drag'], action: 'Select a rectangle' },
+      { input: [{ key: 'Shift' }, '+ drag'], action: 'Add to the selection' },
+      { input: ['Drag the selection'], action: 'Move it' },
+      {
+        input: [{ key: 'Shift' }, '+ drag the selection'],
+        action: 'Copy it',
+      },
+      {
+        input: ['Double-click'],
+        action: 'Edit the query features of an atom, a bond or the selection',
+        only: 'fragment',
+      },
+    ],
+    note: 'These need the Select tool, which Space picks.',
+  },
+  {
+    title: 'Stereochemistry',
+    gestures: [],
+    note: 'Pink bonds flag a stereocentre with too little or too much information. Draw an up or down bond with its narrow end on the centre, then use the enhanced stereo tool to say whether the drawing is this enantiomer (abs), both of them (&) or one of the two (or).',
+  },
+];
+
+/** The documentation this guide summarises. */
+export const STRUCTURE_EDITOR_DOCS: readonly EditorGuideLink[] = [
+  { title: 'Tools and keys', url: 'https://docs.nmrium.org/help/ocl/' },
+  {
+    title: 'Atom properties',
+    url: 'https://docs.nmrium.org/chemical_structure/ocl/atom-properties/',
+  },
+  {
+    title: 'Stereochemistry',
+    url: 'https://docs.nmrium.org/ocl/stereochemistry/',
+  },
+];
+
+/** The editor a guide is written for. */
+export interface EditorGuideOptions {
+  /**
+   * Whether the editor draws one structure or a reaction.
+   * @default 'molecule'
+   */
+  mode?: 'molecule' | 'reaction';
+  /**
+   * Whether the editor draws a query fragment.
+   * @default false
+   */
+  fragment?: boolean;
+}
+
+/**
+ * The guide for one editor: gestures that do nothing there are left out, and so
+ * is a section left with nothing to say.
+ * @param options - The editor the guide is for.
+ * @returns The sections to show.
+ */
+export function editorGuideSections(
+  options: EditorGuideOptions = {},
+): EditorGuideSection[] {
+  const { mode = 'molecule', fragment = false } = options;
+  const sections: EditorGuideSection[] = [];
+  for (const section of STRUCTURE_EDITOR_GUIDE) {
+    const gestures = section.gestures.filter(({ only }) =>
+      appliesTo(only, mode, fragment),
+    );
+    if (gestures.length === 0 && section.note === undefined) continue;
+    sections.push({ ...section, gestures });
+  }
+  return sections;
+}
+
+function appliesTo(
+  only: EditorGuideScope | undefined,
+  mode: 'molecule' | 'reaction',
+  fragment: boolean,
+): boolean {
+  if (only === undefined) return true;
+  if (only === 'fragment') return fragment;
+  return only === mode;
+}
+
+/**
+ * The text of a key cap.
+ * @param key - The key, `Mod` standing for the platform's shortcut modifier.
+ * @param isMac - Whether the page runs on a Mac.
+ * @returns What the cap shows.
+ */
+export function editorKeyLabel(key: string, isMac: boolean): string {
+  if (key !== 'Mod') return key;
+  return isMac ? '⌘' : 'Ctrl';
+}