react-cheminfo 0.24.0 → 0.26.0

package/src/structure/core/editorToolbar.ts

@@ -16,7 +16,9 @@ export type EditorToolbarAvailability = 'always' | 'reaction' | 'never';
 
 /** One button of the toolbar. */
 export interface EditorToolbarButton {
-  /** What the button is called. */
+  /** How the toolbar's catalog names the button. */
+  id: string;
+  /** What the button is called, in English. */
   name: string;
   /** What it does, in a sentence or two. */
   description: string;
@@ -38,62 +40,76 @@ export interface EditorToolbarButton {
  * then down the second.
  */
 export const EDITOR_TOOLBAR_BUTTONS: readonly EditorToolbarButton[] = [
-  { name: 'Clear', description: 'Erase the whole drawing.' },
+  { id: 'clear', name: 'Clear', description: 'Erase the whole drawing.' },
   {
+    id: 'cleanUp',
     name: 'Clean up',
     description:
       'Redraw the structure with fresh 2D coordinates. With part of it selected, the rest keeps its layout.',
   },
   {
+    id: 'select',
     name: 'Select',
     description:
       'Drag around atoms to select them: hold Alt for a rectangle, Shift to add to the selection. Drag a selection to move it, Shift-drag to copy it.',
     keys: ['Space'],
   },
   {
+    id: 'unknownConfiguration',
     name: 'Unknown configuration',
     description:
       'Click a stereocentre to mark its configuration as unknown; click again to undo it.',
   },
   {
+    id: 'delete',
     name: 'Delete',
     description: 'Click an atom or a bond to delete it.',
     keys: ['0'],
   },
   {
+    id: 'singleBond',
     name: 'Single bond',
     description:
       'Click empty space for a new bond, or drag from an atom. Clicking a bond again makes it double, then triple.',
     keys: ['1'],
   },
   {
+    id: 'upBond',
     name: 'Up bond',
     description:
       'Wedged stereo bond, pointing toward the viewer. Its narrow end goes on the stereocentre.',
     keys: ['u'],
   },
-  ring('3-membered ring', '3'),
-  ring('5-membered ring', '5'),
-  ring('7-membered ring', '7'),
+  ring('ring3', '3-membered ring', '3'),
+  ring('ring5', '5-membered ring', '5'),
+  ring('ring7', '7-membered ring', '7'),
   {
+    id: 'positiveCharge',
     name: 'Positive charge',
     description: 'Click an atom to raise its charge by one.',
     keys: ['+'],
   },
-  atom('Carbon', 'C', 'c'),
-  atom('Nitrogen', 'N', 'n'),
-  atom('Oxygen', 'O', 'o'),
-  atom('Fluorine', 'F', 'f'),
-  atom('Bromine', 'Br', 'b'),
-  atom('Hydrogen', 'H'),
-  { name: 'Undo', description: 'Revert the last change.', keys: ['Mod', 'Z'] },
+  atom('carbon', 'Carbon', 'C', 'c'),
+  atom('nitrogen', 'Nitrogen', 'N', 'n'),
+  atom('oxygen', 'Oxygen', 'O', 'o'),
+  atom('fluorine', 'Fluorine', 'F', 'f'),
+  atom('bromine', 'Bromine', 'Br', 'b'),
+  atom('hydrogen', 'Hydrogen', 'H'),
   {
+    id: 'undo',
+    name: 'Undo',
+    description: 'Revert the last change.',
+    keys: ['Mod', 'Z'],
+  },
+  {
+    id: 'zoomAndRotate',
     name: 'Zoom and rotate',
     description:
       'Press where the centre should be, then drag up or down to zoom and sideways to rotate. With a selection, only that part moves.',
     keys: ['z'],
   },
   {
+    id: 'atomMapping',
     name: 'Atom mapping',
     description:
       'Drag from a reactant atom to the same atom in a product: both get the same number. Click a mapped atom to unmap it.',
@@ -101,41 +117,47 @@ export const EDITOR_TOOLBAR_BUTTONS: readonly EditorToolbarButton[] = [
     availability: 'reaction',
   },
   {
+    id: 'enhancedStereo',
     name: 'Enhanced stereo',
     description:
       'Click a stereo bond to say what its centre means: abs, this enantiomer; &, both (racemic); or, one of the two. Press the button again to switch between the three.',
   },
   {
+    id: 'text',
     name: 'Text',
     description: 'Place a text label in the drawing.',
     availability: 'never',
   },
   {
+    id: 'chain',
     name: 'Chain',
     description:
       'Drag from empty space or from an atom to draw a zigzag carbon chain.',
     keys: ['2'],
   },
   {
+    id: 'downBond',
     name: 'Down bond',
     description:
       'Hashed stereo bond, pointing away from the viewer. Its narrow end goes on the stereocentre.',
     keys: ['d'],
   },
-  ring('4-membered ring', '4'),
-  ring('6-membered ring', '6'),
-  ring('Benzene ring', 'a'),
+  ring('ring4', '4-membered ring', '4'),
+  ring('ring6', '6-membered ring', '6'),
+  ring('benzene', 'Benzene ring', 'a'),
   {
+    id: 'negativeCharge',
     name: 'Negative charge',
     description: 'Click an atom to lower its charge by one.',
     keys: ['-'],
   },
-  atom('Silicon', 'Si'),
-  atom('Phosphorus', 'P', 'p'),
-  atom('Sulfur', 'S', 's'),
-  atom('Chlorine', 'Cl', 'l'),
-  atom('Iodine', 'I', 'i'),
+  atom('silicon', 'Silicon', 'Si'),
+  atom('phosphorus', 'Phosphorus', 'P', 'p'),
+  atom('sulfur', 'Sulfur', 'S', 's'),
+  atom('chlorine', 'Chlorine', 'Cl', 'l'),
+  atom('iodine', 'Iodine', 'I', 'i'),
   {
+    id: 'anyAtom',
     name: 'Any atom',
     description:
       'Pick any element, isotope, valence or radical in a dialog, then click to place it or to change an atom. Alt-click an atom to edit its own properties.',
@@ -158,8 +180,9 @@ export function isEditorToolbarButtonAvailable(
   return availability === 'reaction' && mode === 'reaction';
 }
 
-function ring(name: string, key: string): EditorToolbarButton {
+function ring(id: string, name: string, key: string): EditorToolbarButton {
   return {
+    id,
     name,
     description:
       'Click empty space for a new ring, a bond to fuse one onto it, or an atom for a spiro ring.',
@@ -167,9 +190,14 @@ function ring(name: string, key: string): EditorToolbarButton {
   };
 }
 
-function atom(name: string, symbol: string, key?: string): EditorToolbarButton {
+function atom(
+  id: string,
+  name: string,
+  symbol: string,
+  key?: string,
+): EditorToolbarButton {
   const description = `Click empty space for a new ${symbol} atom, or an atom to turn it into ${symbol}.`;
   return key === undefined
-    ? { name, description }
-    : { name, description, keys: [key] };
+    ? { id, name, description }
+    : { id, name, description, keys: [key] };
 }

package/src/structure/ui/EditorHelpButton.tsx

@@ -2,6 +2,8 @@ import { Button, PopoverNext, Tooltip } from '@blueprintjs/core';
 import type { CSSProperties, ReactElement, RefObject } from 'react';
 import { useEffect, useState } from 'react';
 
+import { useChromeT } from '../../i18n/ui/useT.ts';
+
 import { StructureEditorHelp } from './StructureEditorHelp.tsx';
 import type { StructureEditorMode } from './editorChange.ts';
 
@@ -26,6 +28,7 @@ export interface EditorHelpButtonProps {
  */
 export function EditorHelpButton(props: EditorHelpButtonProps): ReactElement {
   const { containerRef, mode, fragment } = props;
+  const t = useChromeT();
   const [isOpen, setIsOpen] = useState(false);
 
   useEffect(() => {
@@ -48,12 +51,16 @@ export function EditorHelpButton(props: EditorHelpButtonProps): ReactElement {
         placement="left-start"
         content={<StructureEditorHelp mode={mode} fragment={fragment} />}
       >
-        <Tooltip content={LABEL} placement="left" disabled={isOpen}>
+        <Tooltip
+          content={t('structure.mouseAndKeyboard')}
+          placement="left"
+          disabled={isOpen}
+        >
           <Button
             variant="minimal"
             size="small"
             icon="help"
-            aria-label={LABEL}
+            aria-label={t('structure.mouseAndKeyboard')}
           />
         </Tooltip>
       </PopoverNext>
@@ -61,8 +68,6 @@ export function EditorHelpButton(props: EditorHelpButtonProps): ReactElement {
   );
 }
 
-const LABEL = 'Mouse and keyboard';
-
 const CORNER_STYLE: CSSProperties = {
   position: 'absolute',
   top: 4,

package/src/structure/ui/StructureEditor.tsx

@@ -18,6 +18,7 @@ import {
 } from 'react';
 import type { CanvasEditorInputFormat } from 'react-ocl';
 
+import { useChromeT } from '../../i18n/ui/useT.ts';
 import { TOKEN } from '../../tokens/core/familyTokens.ts';
 import { createPendingCall } from '../core/pendingCall.ts';
 
@@ -126,6 +127,7 @@ export function StructureEditor(props: StructureEditorProps): ReactElement {
     style,
   } = props;
 
+  const t = useChromeT();
   const containerRef = useToolbarFloor({ minHeight, revision });
   const handleChange = useDebounced(onChange, debounce, revision);
 
@@ -135,7 +137,11 @@ export function StructureEditor(props: StructureEditorProps): ReactElement {
       className={className}
       style={{ ...ROOT_STYLE, minHeight, ...style }}
     >
-      <Suspense fallback={<div style={LOADING_STYLE}>Loading the editor…</div>}>
+      <Suspense
+        fallback={
+          <div style={LOADING_STYLE}>{t('structure.loadingEditor')}</div>
+        }
+      >
         <EditorCanvas
           key={revision}
           onChange={handleChange}

package/src/structure/ui/StructureEditorHelp.tsx

@@ -6,11 +6,15 @@
 import { Classes } from '@blueprintjs/core';
 import type { CSSProperties, ReactElement } from 'react';
 
+import type { ChromeKey } from '../../i18n/core/chromeCatalog.ts';
+import type { Translate } from '../../i18n/ui/useT.ts';
+import { useChromeT } from '../../i18n/ui/useT.ts';
 import { TOKEN } from '../../tokens/core/familyTokens.ts';
 import type { EditorGesture, EditorGuideOptions } from '../core/editorGuide.ts';
 import {
   STRUCTURE_EDITOR_DOCS,
   editorGuideSections,
+  editorInputWordId,
 } from '../core/editorGuide.ts';
 
 import { KeyCaps } from './KeyCaps.tsx';
@@ -29,39 +33,47 @@ export type StructureEditorHelpProps = EditorGuideOptions;
 export function StructureEditorHelp(
   props: StructureEditorHelpProps,
 ): ReactElement {
+  const t = useChromeT();
   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.
+        {t('structure.help.hoverToolbar')}
       </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 key={section.id} style={ROW_STYLE}>
+            <h4 style={HEADING_STYLE}>
+              {t.or(`structure.guide.${section.id}.title`, section.title)}
+            </h4>
             {section.gestures.map((gesture) => (
               <div key={gestureKey(gesture)} style={ROW_STYLE}>
-                <GestureInput input={gesture.input} />
-                <span>{gesture.action}</span>
+                <GestureInput input={gesture.input} t={t} />
+                <span>
+                  {t.or(
+                    `structure.guide.${section.id}.${gesture.id}`,
+                    gesture.action,
+                  )}
+                </span>
               </div>
             ))}
             {section.note === undefined ? null : (
               <p className={Classes.TEXT_MUTED} style={NOTE_STYLE}>
-                {section.note}
+                {t.or(`structure.guide.${section.id}.note`, section.note)}
               </p>
             )}
           </section>
         ))}
       </div>
       <p style={PARAGRAPH_STYLE}>
-        Learn more:{' '}
+        {t('structure.help.learnMore')}{' '}
         {STRUCTURE_EDITOR_DOCS.map((link, index) => (
           <span key={link.url}>
             {index === 0 ? null : ' · '}
             <a href={link.url} target="_blank" rel="noopener noreferrer">
-              {link.title}
+              {t.or(`structure.docs.${link.id}`, link.title)}
             </a>
           </span>
         ))}
@@ -70,12 +82,16 @@ export function StructureEditorHelp(
   );
 }
 
-function GestureInput(props: { input: EditorGesture['input'] }): ReactElement {
+function GestureInput(props: {
+  input: EditorGesture['input'];
+  t: Translate<ChromeKey>;
+}): ReactElement {
+  const { input, t } = props;
   return (
     <span style={INPUT_STYLE}>
-      {props.input.map((part) =>
+      {input.map((part) =>
         typeof part === 'string' ? (
-          <span key={part}>{part}</span>
+          <span key={part}>{word(part, t)}</span>
         ) : (
           <KeyCaps key={part.key} keys={[part.key]} />
         ),
@@ -84,6 +100,13 @@ function GestureInput(props: { input: EditorGesture['input'] }): ReactElement {
   );
 }
 
+// A word between two key caps is one catalog entry, shared by every gesture
+// that writes it; punctuation such as `…` is left exactly as it is.
+function word(text: string, t: Translate<ChromeKey>): string {
+  const id = editorInputWordId(text);
+  return id === undefined ? text : t.or(`structure.input.${id}`, text);
+}
+
 function gestureKey(gesture: EditorGesture): string {
   const input = gesture.input
     .map((part) => (typeof part === 'string' ? part : part.key))

package/src/structure/ui/ToolbarTooltip.tsx

@@ -1,6 +1,7 @@
 import { Classes, Tooltip } from '@blueprintjs/core';
 import type { CSSProperties, ReactElement, RefObject } from 'react';
 
+import { useChromeT } from '../../i18n/ui/useT.ts';
 import type { EditorToolbarButton } from '../core/editorToolbar.ts';
 import {
   EDITOR_TOOLBAR_BUTTONS,
@@ -54,20 +55,23 @@ function ButtonTip(props: {
   mode: StructureEditorMode;
 }): ReactElement {
   const { button, mode } = props;
+  const t = useChromeT();
   const available = isEditorToolbarButtonAvailable(button, mode);
 
   return (
     <div style={TIP_STYLE} data-testid="structure-editor-tooltip">
       <div style={HEAD_STYLE}>
-        <strong>{button.name}</strong>
+        <strong>{t.or(`structure.tool.${button.id}.name`, button.name)}</strong>
         {button.keys === undefined ? null : <KeyCaps keys={button.keys} />}
       </div>
-      <div>{button.description}</div>
+      <div>
+        {t.or(`structure.tool.${button.id}.description`, button.description)}
+      </div>
       {available ? null : (
         <div className={Classes.TEXT_MUTED}>
           {button.availability === 'reaction'
-            ? 'Only when drawing a reaction.'
-            : 'Not available in this editor.'}
+            ? t('structure.tool.reactionOnly')
+            : t('structure.tool.unavailable')}
         </div>
       )}
     </div>

package/src/translate/core/index.ts

@@ -47,7 +47,7 @@ export type {
   TranslateSessionOptions,
 } from './session.ts';
 export { BRIDGE_GLOBAL, BRIDGE_PROTOCOL, TranslateSession } from './session.ts';
-export type { StartTranslatingOptions } from './start.ts';
+export type { LoadOverlayOptions, StartTranslatingOptions } from './start.ts';
 export {
   TRANSLATE_ORIGIN,
   TRANSLATE_PARAM,

package/src/translate/core/start.ts

@@ -63,6 +63,21 @@ export interface StartTranslatingOptions {
    * @default globalThis.document
    */
   document?: Document;
+  /**
+   * Told when the overlay cannot be fetched — translate.cheminfo.org down, a
+   * network that blocks it, an address typed wrong. The site is expected to
+   * stop formatting through the session, so a page nobody can edit goes back
+   * to being an ordinary page rather than staying marked with no editor.
+   * @default undefined
+   */
+  onUnavailable?: () => void;
+  /**
+   * How long to wait for the overlay before giving up on it, in ms. A server
+   * that accepts the connection and then says nothing never fails the script,
+   * so waiting for `error` alone would wait for ever.
+   * @default 10000
+   */
+  timeout?: number;
 }
 
 /**
@@ -85,6 +100,8 @@ export function startTranslating(
     tables = [],
     origin = TRANSLATE_ORIGIN,
     document: target = globalThis.document,
+    onUnavailable,
+    timeout = OVERLAY_TIMEOUT,
   } = options;
 
   const session = new TranslateSession({
@@ -95,27 +112,72 @@ export function startTranslating(
     marked: true,
   });
   Object.assign(globalThis, { [BRIDGE_GLOBAL]: session });
-  loadOverlay(origin, target);
+  loadOverlay(origin, { document: target, onUnavailable, timeout });
   return session;
 }
 
+/** How long the overlay has to arrive before the page gives up on it. */
+const OVERLAY_TIMEOUT = 10_000;
+
+/** How the overlay script is added, and what happens when it does not come. */
+export interface LoadOverlayOptions {
+  /**
+   * The document to add it to.
+   * @default globalThis.document
+   */
+  document?: Document;
+  /**
+   * Told when it cannot be fetched, or does not arrive in time.
+   * @default undefined
+   */
+  onUnavailable?: () => void;
+  /**
+   * How long to wait, in ms.
+   * @default 10000
+   */
+  timeout?: number;
+}
+
 /**
  * Add the overlay script to the page, once.
  * @param origin - Where the overlay is served from.
- * @param target - The document to add it to.
+ * @param options - See {@link LoadOverlayOptions}.
  */
 export function loadOverlay(
   origin: string,
-  target = globalThis.document,
+  options: LoadOverlayOptions = {},
 ): void {
+  const {
+    document: target = globalThis.document,
+    onUnavailable,
+    timeout = OVERLAY_TIMEOUT,
+  } = options;
   if (target === undefined) return;
   const src = `${origin.replace(/\/$/, '')}/overlay.js`;
   for (const loaded of target.querySelectorAll('script')) {
     if (loaded.src === src) return;
   }
+
   const script = target.createElement('script');
   script.type = 'module';
   script.src = src;
   script.async = true;
+
+  // The page is only worth marking while there is an editor to use the marks,
+  // so a script that never arrives takes translate mode down with it.
+  let settled = false;
+  const giveUp = () => {
+    if (settled) return;
+    settled = true;
+    script.remove();
+    onUnavailable?.();
+  };
+  const timer = globalThis.setTimeout(giveUp, timeout);
+  script.addEventListener('error', giveUp);
+  script.addEventListener('load', () => {
+    settled = true;
+    globalThis.clearTimeout(timer);
+  });
+
   target.head.append(script);
 }

package/src/ui.ts

@@ -14,6 +14,7 @@ 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 './i18n/ui/index.ts';
 export * from './language/ui/index.ts';
 export * from './overlay/ui/index.ts';
 export * from './parallel/ui/index.ts';