From 9716b26a6c4d6a3927c0c2d59c021f96559b668c Mon Sep 17 00:00:00 2001
From: tpoisseau <22891227+tpoisseau@users.noreply.github.com>
Date: Thu, 17 Oct 2024 17:51:14 +0200
Subject: [PATCH] feat: sync webcomponent props with attributes (#234)

Refs: https://github.com/cheminfo/openchemlib-js/issues/229

feat: add options to `ReactionEncoder.decode` and `ReactionEncoder.decode`
---
 .run/Build java.run.xml                       |   2 +-
 __tests__/ReactionEncoder.test.js             |   8 +
 __tests__/__snapshots__/library.js.snap       |  12 +
 examples/generic_editor/demo.html             |  72 +++++-
 examples/generic_editor/demo/demo.ts          |  55 ++++-
 examples/generic_editor/web_component.html    |  12 +
 lib/canvas_editor/events.js                   |  11 +-
 .../init/canvas_editor_element.js             | 210 ++++++++++++++++--
 .../research/gwt/core/JSReactionEncoder.java  |  83 ++++++-
 types.d.ts                                    |  95 +++++++-
 10 files changed, 523 insertions(+), 37 deletions(-)

diff --git a/.run/Build java.run.xml b/.run/Build java.run.xml
index a5d0699c..d0e8654f 100644
--- a/.run/Build java.run.xml	
+++ b/.run/Build java.run.xml	
@@ -1,6 +1,6 @@
 <component name="ProjectRunConfigurationManager">
   <configuration default="false" name="Build java" type="ShConfigurationType">
-    <option name="SCRIPT_TEXT" value="npm run build-full-pretty" />
+    <option name="SCRIPT_TEXT" value="npm run build-full-pretty -- --verbose" />
     <option name="INDEPENDENT_SCRIPT_PATH" value="true" />
     <option name="SCRIPT_PATH" value="" />
     <option name="SCRIPT_OPTIONS" value="" />
diff --git a/__tests__/ReactionEncoder.test.js b/__tests__/ReactionEncoder.test.js
index 0b7181f5..dc79d421 100644
--- a/__tests__/ReactionEncoder.test.js
+++ b/__tests__/ReactionEncoder.test.js
@@ -13,4 +13,12 @@ describe('ReactionEncoder class', () => {
     expect(newReaction.getReactants()).toBe(2);
     expect(newReaction.getProducts()).toBe(1);
   });
+
+  it('should be able to decode using string from idcodeexplorer', () => {
+    const idcode =
+      'gOp@DjWkB@@@ gOp@DjWkB@@@ gOp@DjWkB@@@!fhy@@@LdbbbTQQRYhTg^@@``@`@@@##!RbGwW_Wx@_c}~O}]}v`@@ !Rb@KW@gx?_`A~@M\\Bv`@@ !R|Gq~_{]||Owp?Wy?v`@@ !R_c~H?M_|uwvH_Xa}_`CW_]_|_c~H?M_|uwwW_]_|u?sZ@@@##';
+    const reaction = ReactionEncoder.decode(idcode);
+    expect(reaction.getReactants()).toBe(3);
+    expect(reaction.getProducts()).toBe(1);
+  });
 });
diff --git a/__tests__/__snapshots__/library.js.snap b/__tests__/__snapshots__/library.js.snap
index 62a01d5b..3d792cb8 100644
--- a/__tests__/__snapshots__/library.js.snap
+++ b/__tests__/__snapshots__/library.js.snap
@@ -711,6 +711,18 @@ exports[`static properties of MoleculeProperties 1`] = `[]`;
 
 exports[`static properties of ReactionEncoder 1`] = `
 [
+  "CATALYST_DELIMITER",
+  "INCLUDE_ALL",
+  "INCLUDE_CATALYSTS",
+  "INCLUDE_COORDS",
+  "INCLUDE_DEFAULT",
+  "INCLUDE_DRAWING_OBJECTS",
+  "INCLUDE_MAPPING",
+  "INCLUDE_RXN_CODE_ONLY",
+  "MOLECULE_DELIMITER",
+  "OBJECT_DELIMITER",
+  "PRODUCT_IDENTIFIER",
+  "RETAIN_REACTANT_AND_PRODUCT_ORDER",
   "decode",
   "encode",
 ]
diff --git a/examples/generic_editor/demo.html b/examples/generic_editor/demo.html
index 0332a558..1d097bab 100644
--- a/examples/generic_editor/demo.html
+++ b/examples/generic_editor/demo.html
@@ -16,7 +16,7 @@ <h1>Generic editor - CanvasEditor demo</h1>
         grid-template-areas:
           '.            top-actions .     '
           'left-actions editor      result'
-          '.            .           result';
+          'id-code      id-code     result';
       "
     >
       <div class="flex flex-row gap-4" style="grid-area: top-actions">
@@ -56,6 +56,76 @@ <h1>Generic editor - CanvasEditor demo</h1>
         <label for="molfilev3">Molfile or RXN v3</label>
         <textarea class="font-mono p-2" rows="12" id="molfilev3"></textarea>
       </div>
+
+      <form id="idcodeForm" style="grid-area: id-code">
+        <h3>ID-Code loader parametrized</h3>
+
+        <label for="idcodeInput">ID Code</label>
+        <input
+          type="text"
+          id="idcodeInput"
+          name="idcode"
+          class="w-full"
+          placeholder="Enter an ID code"
+        />
+
+        <fieldset>
+          <legend>Type</legend>
+
+          <label>
+            <input type="radio" name="type" value="molecule" checked />
+            Molecule
+          </label>
+
+          <label>
+            <input type="radio" name="type" value="reaction" />
+            Reaction
+          </label>
+        </fieldset>
+
+        <input
+          type="checkbox"
+          name="ensureCoordinates"
+          id="idcodeEnsureCoordinates"
+          checked
+        />
+        <label for="idcodeEnsureCoordinates">
+          ensure2DCoordinates for <code>Molecules.fromIDCode</code>,
+          <br />
+          ensureCoordinates for <code>ReactionEncoder.decode</code>
+        </label>
+
+        <label class="block" for="idcodeDecodeOptions"
+          >decode options (reaction only)</label
+        >
+        <label class="block">
+          <input type="checkbox" name="options-type" id="idcodeDecodeOptions" />
+          Not checked: ensureCoordinates, Checked: mode
+        </label>
+
+        <fieldset>
+          <legend>Mode</legend>
+
+          <label class="block">
+            <input type="checkbox" name="INCLUDE_MAPPING" checked />
+            INCLUDE_MAPPING
+          </label>
+          <label class="block">
+            <input type="checkbox" name="INCLUDE_COORDS" checked />
+            INCLUDE_COORDS
+          </label>
+          <label class="block">
+            <input type="checkbox" name="INCLUDE_DRAWING_OBJECTS" checked />
+            INCLUDE_DRAWING_OBJECTS
+          </label>
+          <label class="block">
+            <input type="checkbox" name="INCLUDE_CATALYSTS" checked />
+            INCLUDE_CATALYSTS
+          </label>
+        </fieldset>
+
+        <button class="block" type="submit">Load</button>
+      </form>
     </section>
   </body>
 </html>
diff --git a/examples/generic_editor/demo/demo.ts b/examples/generic_editor/demo/demo.ts
index fb42451c..8ba29486 100644
--- a/examples/generic_editor/demo/demo.ts
+++ b/examples/generic_editor/demo/demo.ts
@@ -3,7 +3,7 @@ import { getEditor, resetEditor } from './editor.ts';
 import rxn from './seeds/rxn.ts';
 import molfile from './seeds/molfile.ts';
 
-const { Molecule, Reaction } = OCL;
+const { Molecule, Reaction, ReactionEncoder } = OCL;
 
 resetEditor();
 
@@ -50,3 +50,56 @@ loadReactionFragment.onclick = () => {
   reaction.setFragment(true);
   getEditor().setReaction(reaction);
 };
+
+const idcodeForm = document.getElementById('idcodeForm') as HTMLFormElement;
+idcodeForm.onsubmit = (event) => {
+  event.preventDefault();
+  event.stopPropagation();
+
+  const formData = new FormData(idcodeForm);
+  const idcode = formData.get('idcode') as string;
+  const type = formData.get('type') as string;
+  const ensureCoordinates = formData.has('ensureCoordinates');
+
+  if (type === 'molecule') {
+    const molecule = Molecule.fromIDCode(idcode, ensureCoordinates);
+    getEditor().setMolecule(molecule);
+    return;
+  }
+
+  if (type === 'reaction') {
+    const useMode = formData.has('options-type');
+
+    function getMode() {
+      const mapping = formData.has('INCLUDE_MAPPING')
+        ? ReactionEncoder.INCLUDE_MAPPING
+        : 0;
+      const coords = formData.has('INCLUDE_COORDS')
+        ? ReactionEncoder.INCLUDE_COORDS
+        : 0;
+      const draw = formData.has('INCLUDE_DRAWING_OBJECTS')
+        ? ReactionEncoder.INCLUDE_DRAWING_OBJECTS
+        : 0;
+      const catalysts = formData.has('INCLUDE_CATALYSTS')
+        ? ReactionEncoder.INCLUDE_CATALYSTS
+        : 0;
+
+      return mapping | coords | draw | catalysts;
+    }
+
+    const reaction = useMode
+      ? ReactionEncoder.decode(idcode, {
+          mode: getMode(),
+        })
+      : ReactionEncoder.decode(idcode, {
+          ensureCoordinates: ensureCoordinates,
+        });
+
+    if (!reaction) {
+      window.alert('Invalid reaction');
+      return;
+    }
+
+    getEditor().setReaction(reaction);
+  }
+};
diff --git a/examples/generic_editor/web_component.html b/examples/generic_editor/web_component.html
index ce3f34ba..0c3bc152 100644
--- a/examples/generic_editor/web_component.html
+++ b/examples/generic_editor/web_component.html
@@ -71,5 +71,17 @@ <h1>Generic editor - &lt;openchemlib-editor> (Web Component) demo</h1>
       mode="reaction"
       readonly
     ></openchemlib-editor>
+
+    <p>
+      Reaction from idcodeexplorer
+      <code
+        >gOp@DjWkjj`@ gOp@DjWkjj`@!gOp@DjWkjj`@##!BbOvw?_x@?g?~_{_}
+        !Bb@Jw@oy??`C~@K\B !Bb@K~_{\BbOvH?_y?##</code
+      >
+      <openchemlib-editor
+        idcode="gOp@DjWkjj`@ gOp@DjWkjj`@!gOp@DjWkjj`@##!BbOvw?_x@?g?~_{_} !Bb@Jw@oy??`C~@K\B !Bb@K~_{\BbOvH?_y?##"
+        mode="reaction"
+      ></openchemlib-editor>
+    </p>
   </body>
 </html>
diff --git a/lib/canvas_editor/events.js b/lib/canvas_editor/events.js
index daa4df4a..7f5053e2 100644
--- a/lib/canvas_editor/events.js
+++ b/lib/canvas_editor/events.js
@@ -72,23 +72,28 @@ function addPointerListeners(canvasElement, drawArea, JavaEditorArea) {
 function addKeyboardListeners(canvasElement, editorArea, JavaEditorArea) {
   const isMac =
     typeof navigator !== 'undefined' && navigator.platform === 'MacIntel';
+  const isMenuKey = (ev) => (isMac && ev.metaKey) || (!isMac && ev.ctrlKey);
 
   function fireKeyEvent(what, ev) {
     const key = getKeyFromEvent(ev, JavaEditorArea);
     if (key === null) return;
-    ev.stopPropagation();
-    ev.preventDefault();
+
     editorArea.fireKeyEvent(
       what,
       key,
       ev.altKey,
       ev.ctrlKey,
       ev.shiftKey,
-      (isMac && ev.metaKey) || (!isMac && ev.ctrlKey),
+      isMenuKey(ev),
     );
   }
 
   canvasElement.addEventListener('keydown', (ev) => {
+    // copy-paste is handled by the clipboard event
+    // java ctrl-c / ctrl-v events can't work and could throw error
+    if (isMenuKey(ev) && ev.key === 'c') return;
+    if (isMenuKey(ev) && ev.key === 'v') return;
+
     fireKeyEvent(JavaEditorArea.KEY_EVENT_PRESSED, ev);
   });
   canvasElement.addEventListener('keyup', (ev) => {
diff --git a/lib/canvas_editor/init/canvas_editor_element.js b/lib/canvas_editor/init/canvas_editor_element.js
index e8c8c86b..1d1f0794 100644
--- a/lib/canvas_editor/init/canvas_editor_element.js
+++ b/lib/canvas_editor/init/canvas_editor_element.js
@@ -16,26 +16,70 @@ function initCanvasEditorElement(CanvasEditor, Molecule, ReactionEncoder) {
       'readonly',
     ]);
 
-    /* --- custom element attributes --- */
-    /** @type {string} */ idcode = '';
-    /** @type {boolean} */ fragment = false;
-    /** @type {'molecule' | 'reaction'} */ mode =
-      CanvasEditorElement.MODE.MOLECULE;
-    /** @type {boolean} */ readonly = false;
+    /**
+     * @type {{mode: 'molecule' | 'reaction', fragment: boolean, idcode: string, readonly: boolean}}
+     */
+    #state;
+
+    get idcode() {
+      return this.#state.idcode;
+    }
+
+    set idcode(value) {
+      this.#state.idcode = String(value);
+      this.setAttribute('idcode', this.#state.idcode);
+    }
+
+    get fragment() {
+      return this.#state.fragment;
+    }
+
+    set fragment(value) {
+      this.#state.fragment = Boolean(value);
+      if (this.#state.fragment) {
+        this.setAttribute('fragment', '');
+      } else {
+        this.removeAttribute('fragment');
+      }
+    }
+
+    get mode() {
+      return this.#state.mode;
+    }
+
+    set mode(value) {
+      this.#state.mode = String(value);
+      this.setAttribute('mode', this.#state.mode);
+    }
+
+    get readonly() {
+      return this.#state.readonly;
+    }
+
+    set readonly(value) {
+      this.#state.readonly = Boolean(value);
+      if (this.#state.readonly) {
+        this.setAttribute('readonly', '');
+      } else {
+        this.removeAttribute('readonly');
+      }
+    }
 
     /* --- custom element api --- */
     /**
      * @param {Molecule} molecule
+     * @this {CanvasEditorElement}
      */
     setMolecule(molecule) {
       this.fragment = molecule.isFragment();
-      this.idcode = molecule.getIDCode();
+      this.idcode = `${molecule.getIDCode()} ${molecule.getIDCoordinates()}`;
 
       this.#editor.setMolecule(molecule);
     }
 
     /**
      * @return {Molecule}
+     * @this {CanvasEditorElement}
      */
     getMolecule() {
       return this.#editor.getMolecule();
@@ -43,21 +87,32 @@ function initCanvasEditorElement(CanvasEditor, Molecule, ReactionEncoder) {
 
     /**
      * @param {Reaction} reaction
+     * @this {CanvasEditorElement}
      */
     setReaction(reaction) {
       this.fragment = reaction.isFragment();
-      this.idcode = ReactionEncoder.encode(reaction);
+      this.idcode = ReactionEncoder.encode(reaction, {
+        keepAbsoluteCoordinates: true,
+        mode:
+          ReactionEncoder.INCLUDE_MAPPING |
+          ReactionEncoder.INCLUDE_COORDS |
+          ReactionEncoder.RETAIN_REACTANT_AND_PRODUCT_ORDER,
+      });
 
       this.#editor.setReaction(reaction);
     }
 
     /**
      * @return {Reaction}
+     * @this {CanvasEditorElement}
      */
     getReaction() {
       return this.#editor.getReaction();
     }
 
+    /**
+     * @this {CanvasEditorElement}
+     */
     clearAll() {
       this.#editor.clearAll();
       this.idcode = '';
@@ -66,6 +121,9 @@ function initCanvasEditorElement(CanvasEditor, Molecule, ReactionEncoder) {
     /* --- internals --- */
     /** @type {CanvasEditor} */ #editor;
 
+    /**
+     * @this {CanvasEditorElement}
+     */
     #initEditor() {
       if (this.#editor) return;
 
@@ -78,12 +136,15 @@ function initCanvasEditorElement(CanvasEditor, Molecule, ReactionEncoder) {
       requestIdleCallback(() => this.#initIdCode());
     }
 
+    /**
+     * @this {CanvasEditorElement}
+     */
     #initIdCode() {
       switch (this.mode) {
-        case this.constructor.MODE.MOLECULE: {
+        case CanvasEditorElement.MODE.MOLECULE: {
           return this.#initMolecule();
         }
-        case this.constructor.MODE.REACTION: {
+        case CanvasEditorElement.MODE.REACTION: {
           return this.#initReaction();
         }
         default:
@@ -91,26 +152,121 @@ function initCanvasEditorElement(CanvasEditor, Molecule, ReactionEncoder) {
       }
     }
 
+    /**
+     * @param {string} idcodeAndCoordinates
+     */
+    #moleculeFromIdCode(idcodeAndCoordinates) {
+      const index = idcodeAndCoordinates.indexOf(' ');
+
+      if (index === -1) {
+        return Molecule.fromIDCode(idcodeAndCoordinates);
+      }
+
+      const idcode = idcodeAndCoordinates.slice(0, index);
+      const coordinates = idcodeAndCoordinates.slice(index + 1);
+
+      return Molecule.fromIDCode(idcode, coordinates);
+    }
+
+    /**
+     * @this {CanvasEditorElement}
+     */
     #initMolecule() {
-      const molecule = Molecule.fromIDCode(this.idcode);
+      const molecule = this.#moleculeFromIdCode(this.idcode);
       molecule.setFragment(this.fragment);
 
       this.#editor.setMolecule(molecule);
     }
 
+    /**
+     * @this {CanvasEditorElement}
+     */
     #initReaction() {
-      const reaction = ReactionEncoder.decode(this.idcode);
+      const reaction = ReactionEncoder.decode(this.idcode, {
+        ensureCoordinates: true,
+      });
       reaction.setFragment(this.fragment);
 
       this.#editor.setReaction(reaction);
     }
 
+    #ignoreAttributeChange = false;
+    /**
+     * @param {() => void} fn
+     * @this {CanvasEditorElement}
+     */
+    #wrapIgnoreAttributeChange(fn) {
+      this.#ignoreAttributeChange = true;
+
+      try {
+        fn();
+      } finally {
+        this.#ignoreAttributeChange = false;
+      }
+    }
+
+    /**
+     * @param {{
+     *  type: 'molecule' | 'selection' | 'highlight-atom' | 'highlight-bond';
+     *  isUserEvent: boolean;
+     * }} editorEventOnChange
+     */
     #handleChange = (editorEventOnChange) => {
+      const idcode = this.idcode;
+      const fragment = this.fragment;
+
+      // update internal state from editor change
+      this.#wrapIgnoreAttributeChange(() => {
+        if (editorEventOnChange.type !== 'molecule') return;
+
+        switch (this.mode) {
+          case CanvasEditorElement.MODE.MOLECULE: {
+            const molecule = this.getMolecule();
+            this.idcode = `${molecule.getIDCode()} ${molecule.getIDCoordinates()}`;
+            this.fragment = molecule.isFragment();
+            break;
+          }
+          case CanvasEditorElement.MODE.REACTION: {
+            const reaction = this.getReaction();
+            this.idcode = ReactionEncoder.encode(reaction, {
+              keepAbsoluteCoordinates: true,
+              mode:
+                ReactionEncoder.INCLUDE_MAPPING |
+                ReactionEncoder.INCLUDE_COORDS |
+                ReactionEncoder.RETAIN_REACTANT_AND_PRODUCT_ORDER,
+            });
+            this.fragment = reaction.isFragment();
+            break;
+          }
+          default:
+            throw new Error(`Unsupported mode ${this.mode}`);
+        }
+      });
+
+      // propagate editor changes to parent
       const domEvent = new CustomEvent('change', {
         detail: editorEventOnChange,
-        composed: true,
+        bubbles: true,
       });
       this.dispatchEvent(domEvent);
+
+      if (editorEventOnChange.mode !== 'molecule') return;
+
+      // propagate vaadin events
+      if (this.idcode !== idcode) {
+        const idcodeChangeEvent = new CustomEvent('idcode-changed', {
+          detail: this.idcode,
+          bubbles: true,
+        });
+        this.dispatchEvent(idcodeChangeEvent);
+      }
+      if (this.fragment !== fragment) {
+        const fragmentChangeEvent = new CustomEvent('fragment-changed', {
+          detail: this.fragment,
+          bubbles: true,
+        });
+        this.dispatchEvent(fragmentChangeEvent);
+      }
     };
 
     #destroyEditor() {
@@ -130,6 +286,13 @@ function initCanvasEditorElement(CanvasEditor, Molecule, ReactionEncoder) {
      * Custom element added to page.
      */
     connectedCallback() {
+      this.#state = {
+        idcode: this.getAttribute('idcode') || '',
+        fragment: this.hasAttribute('fragment'),
+        mode: this.getAttribute('mode') || CanvasEditorElement.MODE.MOLECULE,
+        readonly: this.hasAttribute('readonly'),
+      };
+
       this.#initEditor();
     }
 
@@ -143,37 +306,42 @@ function initCanvasEditorElement(CanvasEditor, Molecule, ReactionEncoder) {
     /**
      * Custom element moved to new page.
      */
-    // eslint-disable-next-line no-empty-function
-    adoptedCallback() {}
+    adoptedCallback() {
+      this.connectedCallback();
+    }
 
     /**
      * Attribute ${name} has changed from ${oldValue} to ${newValue}
+     *
+     * Sync attribute changes to internal state.
+     * propagate changes to editor.
      */
     attributeChangedCallback(name, oldValue, newValue) {
+      if (!this.#editor) return;
+      if (this.#ignoreAttributeChange) return;
+
       const mutatorHandler = (() => {
         switch (name) {
           case 'idcode': {
-            this.idcode = String(newValue);
+            this.#state.idcode = String(newValue);
             return () => this.#initIdCode();
           }
           case 'fragment': {
-            this.fragment = newValue !== null;
+            this.#state.fragment = newValue !== null;
             return () => this.#initIdCode();
           }
           case 'mode': {
-            this.mode = String(newValue);
+            this.#state.mode = String(newValue);
             return () => this.#resetEditor();
           }
           case 'readonly': {
-            this.readonly = newValue !== null;
+            this.#state.readonly = newValue !== null;
             return () => this.#resetEditor();
           }
           default:
             throw new Error('unsupported attribute change');
         }
       })();
-
-      if (!this.#editor) return;
       mutatorHandler();
     }
   }
diff --git a/src/com/actelion/research/gwt/core/JSReactionEncoder.java b/src/com/actelion/research/gwt/core/JSReactionEncoder.java
index 0525547c..13245c2e 100644
--- a/src/com/actelion/research/gwt/core/JSReactionEncoder.java
+++ b/src/com/actelion/research/gwt/core/JSReactionEncoder.java
@@ -1,20 +1,89 @@
 package com.actelion.research.gwt.core;
 
-import com.actelion.research.chem.*;
-import com.actelion.research.chem.io.*;
-import com.actelion.research.chem.reaction.*;
+import com.actelion.research.chem.reaction.Reaction;
+import com.actelion.research.chem.reaction.ReactionEncoder;
 import com.actelion.research.gwt.minimal.JSReaction;
+import com.google.gwt.core.client.JavaScriptObject;
 import jsinterop.annotations.*;
 
 @JsType(name = "ReactionEncoder")
 public class JSReactionEncoder {
+  public static final int INCLUDE_MAPPING = ReactionEncoder.INCLUDE_MAPPING;
+  public static final int INCLUDE_COORDS = ReactionEncoder.INCLUDE_COORDS;
+  public static final int INCLUDE_DRAWING_OBJECTS = ReactionEncoder.INCLUDE_DRAWING_OBJECTS;
+  public static final int INCLUDE_CATALYSTS = ReactionEncoder.INCLUDE_CATALYSTS;
+  public static final int RETAIN_REACTANT_AND_PRODUCT_ORDER = ReactionEncoder.RETAIN_REACTANT_AND_PRODUCT_ORDER;
 
-  public static String encode(JSReaction reaction) {
-    return ReactionEncoder.encode(reaction.getReaction(), false, 0);
+  public static final int INCLUDE_ALL = ReactionEncoder.INCLUDE_ALL;
+  public static final int INCLUDE_RXN_CODE_ONLY = ReactionEncoder.INCLUDE_RXN_CODE_ONLY;
+  public static final int INCLUDE_DEFAULT = ReactionEncoder.INCLUDE_DEFAULT;
+
+  public static final String MOLECULE_DELIMITER = ReactionEncoder.MOLECULE_DELIMITER_STRING;
+  public static final String OBJECT_DELIMITER = ReactionEncoder.OBJECT_DELIMITER_STRING;
+  public static final String PRODUCT_IDENTIFIER = String.valueOf(ReactionEncoder.PRODUCT_IDENTIFIER);
+  public static final String CATALYST_DELIMITER = String.valueOf(ReactionEncoder.CATALYST_DELIMITER);
+
+  public static native String encode(JSReaction reaction, JavaScriptObject options) /*-{
+    if (!options) options = {keepAbsoluteCoordinates: false, mode: @com.actelion.research.gwt.core.JSReactionEncoder::INCLUDE_DEFAULT};
+    options = Object.assign({}, options);
+    options.keepAbsoluteCoordinates = Boolean(options.keepAbsoluteCoordinates);
+
+    if ('sortByIDCode' in options) {
+      options.sortByIDCode = Boolean(options.sortByIDCode);
+
+      return @com.actelion.research.gwt.core.JSReactionEncoder::encodeSort(Lcom/actelion/research/gwt/minimal/JSReaction;ZZ)(reaction, options.keepAbsoluteCoordinates, options.sortByIDCode)
+    }
+
+    if (typeof options.mode !== 'number') options.mode = @com.actelion.research.gwt.core.JSReactionEncoder::INCLUDE_DEFAULT;
+    options.mode = Math.trunc(options.mode);
+    return @com.actelion.research.gwt.core.JSReactionEncoder::encodeMode(Lcom/actelion/research/gwt/minimal/JSReaction;ZI)(reaction, options.keepAbsoluteCoordinates, options.mode);
+  }-*/;
+
+  private static String encodeSort(JSReaction reaction, boolean keepAbsoluteCoordinates, boolean sortByIDCode) {
+    return String.join(
+            OBJECT_DELIMITER,
+            ReactionEncoder.encode(
+                    reaction.getReaction(),
+                    keepAbsoluteCoordinates,
+                    sortByIDCode
+            )
+    );
+  }
+
+  private static String encodeMode(JSReaction reaction, boolean keepAbsoluteCoordinates, int mode) {
+    return ReactionEncoder.encode(
+            reaction.getReaction(),
+            keepAbsoluteCoordinates,
+            mode
+    );
   }
 
-  public static JSReaction decode(String s) {
-    return new JSReaction(ReactionEncoder.decode(s, true, null));
+  public static native JSReaction decode(String reaction, JavaScriptObject options) /*-{
+    if (!options) options = {mode: @com.actelion.research.gwt.core.JSReactionEncoder::INCLUDE_DEFAULT};
+    options = Object.assign({}, options);
+
+    if ('ensureCoordinates' in options) {
+      options.ensureCoordinates = Boolean(options.ensureCoordinates);
+      return @com.actelion.research.gwt.core.JSReactionEncoder::decodeCoords(Ljava/lang/String;Z)(reaction, options.ensureCoordinates);
+    }
+
+    if (typeof options.mode !== 'number') options.mode = @com.actelion.research.gwt.core.JSReactionEncoder::INCLUDE_DEFAULT;
+    options.mode = Math.trunc(options.mode);
+    return @com.actelion.research.gwt.core.JSReactionEncoder::decodeMode(Ljava/lang/String;I)(reaction, options.mode);
+  }-*/;
+
+  private static JSReaction decodeCoords(String strReaction, boolean ensureCoordinates) {
+    Reaction reaction = ReactionEncoder.decode(strReaction, ensureCoordinates, null);
+    if (reaction == null) return null;
+
+    return new JSReaction(reaction);
+  }
+
+  private static JSReaction decodeMode(String strReaction, int mode) {
+    Reaction reaction = ReactionEncoder.decode(strReaction, mode, null);
+    if (reaction == null) return null;
+
+    return new JSReaction(reaction);
   }
 
 }
diff --git a/types.d.ts b/types.d.ts
index 65d401da..4f85a124 100644
--- a/types.d.ts
+++ b/types.d.ts
@@ -3089,10 +3089,99 @@ export declare class Reaction {
   getMergedCopy(): Reaction;
 }
 
-// eslint-disable-next-line @typescript-eslint/no-extraneous-class,unicorn/no-static-only-class
+interface ReactionEncoderEncodeOptionsBase {
+  /**
+   * @default false
+   */
+  keepAbsoluteCoordinates?: boolean;
+}
+
+/**
+ * Bound to Java ReactionEncoder `String[] encode(Reaction reaction, boolean keepAbsoluteCoordinates, boolean sortByIDCode)`
+ * result will be joined with Java `ReactionEncoder.OBJECT_DELIMITER`
+ */
+export interface ReactionEncoderEncodeOptionsSort
+  extends ReactionEncoderEncodeOptionsBase {
+  /**
+   * @default false
+   */
+  sortByIDCode?: boolean;
+}
+
+/**
+ * Bound to Java ReactionEncoder `String encode(Reaction reaction, boolean keepAbsoluteCoordinates, int mode)`
+ */
+export interface ReactionEncoderEncodeOptionsMode
+  extends ReactionEncoderEncodeOptionsBase {
+  /**
+   * @default ReactionEncoder.INCLUDE_DEFAULT
+   * @see ReactionEncoder.INCLUDE_DEFAULT
+   */
+  mode?: number;
+}
+
+export type ReactionEncoderEncodeOptions =
+  | ReactionEncoderEncodeOptionsSort
+  | ReactionEncoderEncodeOptionsMode;
+
+export interface ReactionEncoderDecodeOptionsCoordinates {
+  /**
+   * @default false
+   */
+  ensureCoordinates?: boolean;
+}
+
+export interface ReactionEncoderDecodeOptionsMode {
+  /**
+   * @default ReactionEncoder.INCLUDE_DEFAULT
+   * @see ReactionEncoder.INCLUDE_DEFAULT
+   */
+  mode?: number;
+}
+
+export type ReactionEncoderDecodeOptions =
+  | ReactionEncoderDecodeOptionsCoordinates
+  | ReactionEncoderDecodeOptionsMode;
+
+// eslint-disable-next-line @typescript-eslint/no-extraneous-class
 export declare class ReactionEncoder {
-  static encode(reaction: Reaction): string | null;
-  static decode(reaction: string): Reaction;
+  static readonly INCLUDE_MAPPING = 0b00001;
+  static readonly INCLUDE_COORDS = 0b00010;
+  static readonly INCLUDE_DRAWING_OBJECTS = 0b00100;
+  static readonly INCLUDE_CATALYSTS = 0b01000;
+  static readonly RETAIN_REACTANT_AND_PRODUCT_ORDER = 0b10000;
+
+  static readonly INCLUDE_ALL =
+    ReactionEncoder.INCLUDE_MAPPING |
+    ReactionEncoder.INCLUDE_COORDS |
+    ReactionEncoder.INCLUDE_DRAWING_OBJECTS |
+    ReactionEncoder.INCLUDE_CATALYSTS;
+  static readonly INCLUDE_RXN_CODE_ONLY = 0b00000;
+  static readonly INCLUDE_DEFAULT =
+    ReactionEncoder.INCLUDE_MAPPING | ReactionEncoder.INCLUDE_COORDS;
+
+  static readonly MOLECULE_DELIMITER: string;
+  static readonly OBJECT_DELIMITER: string;
+  static readonly PRODUCT_IDENTIFIER: string;
+  static readonly CATALYST_DELIMITER: string;
+
+  /**
+   * @param reaction
+   * @param options - @default {keepAbsoluteCoordinates: false, mode: ReactionEncoder.INCLUDE_DEFAULT}
+   */
+  static encode(
+    reaction: Reaction,
+    options?: ReactionEncoderEncodeOptions,
+  ): string | null;
+
+  /**
+   * @param reaction
+   * @param options - @default {mode: ReactionEncoder.INCLUDE_DEFAULT}
+   */
+  static decode(
+    reaction: string,
+    options?: ReactionEncoderDecodeOptions,
+  ): Reaction | null;
 }
 
 export declare class Reactor {