feat(onchange): callback now accepts custom event

docs/CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+### 2.23.0
+
+- `Improvement` — The `onChange` callback now accepts two arguments: EditorJS API and the CustomEvent with `type` and `detail` allowing to determine what happened with a Block
+
 ### 2.22.3
 
 - `Fix` — Tool config is passed to `prepare` method [editor-js/embed#68](https://github.com/editor-js/embed/issues/68)

docs/installation.md

@@ -192,8 +192,9 @@ var editor = new EditorJS({
 
    /**
     * onChange callback
+    * Accepts CustomEvent describing what happened
     */
-   onChange: (editorAPI, affectedBlockAPI) => {console.log('Now I know that Editor\'s content changed!')}
+   onChange: (editorAPI, event) => {console.log('Now I know that Editor\'s content changed!')}
 });
 ```
 

example/example-dev.html

@@ -318,8 +318,8 @@
       onReady: function(){
         saveButton.click();
       },
-      onChange: function(api, block) {
-        console.log('something changed', block);
+      onChange: function(api, event) {
+        console.log('something changed', event);
       },
     });
 

example/example.html

@@ -281,8 +281,8 @@
       onReady: function(){
         saveButton.click();
       },
-      onChange: function(api, block) {
-        console.log('something changed', block);
+      onChange: function(api, event) {
+        console.log('something changed', event);
       }
     });
 

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@editorjs/editorjs",
-  "version": "2.22.3",
+  "version": "2.23.0",
   "description": "Editor.js — Native JS, based on API and Open Source",
   "main": "dist/editor.js",
   "types": "./types/index.d.ts",
@@ -29,7 +29,8 @@
     "_tools:build": "git submodule foreach yarn build",
     "_tools:make": "yarn _tools:yarn && yarn _tools:build",
     "tools:update": "yarn _tools:checkout && yarn _tools:pull && yarn _tools:make",
-    "test:e2e": "yarn build && cypress run"
+    "test:e2e": "yarn build && cypress run",
+    "test:e2e:open": "yarn build && cypress open"
   },
   "author": "CodeX",
   "license": "Apache-2.0",

src/components/modules/blockManager.ts

@@ -14,6 +14,7 @@ import Blocks from '../blocks';
 import { BlockToolData, PasteEvent } from '../../../types';
 import { BlockTuneData } from '../../../types/block-tunes/block-tune-data';
 import BlockAPI from '../block/api';
+import { BlockMutationType } from '../../../types/events/block/mutation-type';
 
 /**
  * @typedef {BlockManager} BlockManager
@@ -289,12 +290,24 @@ export default class BlockManager extends Module {
       tunes,
     });
 
+    /**
+     * In case of block replacing (Converting OR from Toolbox or Shortcut on empty block OR on-paste to empty block)
+     * we need to dispatch the 'block-removing' event for the replacing block
+     */
+    if (replace) {
+      this.blockDidMutated(BlockMutationType.Removed, this.getBlockByIndex(newIndex), {
+        index: newIndex,
+      });
+    }
+
     this._blocks.insert(newIndex, block, replace);
 
     /**
      * Force call of didMutated event on Block insertion
      */
-    this.blockDidMutated(block);
+    this.blockDidMutated(BlockMutationType.Added, block, {
+      index: newIndex,
+    });
 
     if (needToFocus) {
       this.currentBlockIndex = newIndex;
@@ -370,7 +383,9 @@ export default class BlockManager extends Module {
     /**
      * Force call of didMutated event on Block insertion
      */
-    this.blockDidMutated(block);
+    this.blockDidMutated(BlockMutationType.Added, block, {
+      index,
+    });
 
     if (needToFocus) {
       this.currentBlockIndex = index;
@@ -445,7 +460,9 @@ export default class BlockManager extends Module {
     /**
      * Force call of didMutated event on Block removal
      */
-    this.blockDidMutated(blockToRemove);
+    this.blockDidMutated(BlockMutationType.Removed, blockToRemove, {
+      index,
+    });
 
     if (this.currentBlockIndex >= index) {
       this.currentBlockIndex--;
@@ -721,7 +738,10 @@ export default class BlockManager extends Module {
     /**
      * Force call of didMutated event on Block movement
      */
-    this.blockDidMutated(this.currentBlock);
+    this.blockDidMutated(BlockMutationType.Moved, this.currentBlock, {
+      fromIndex,
+      toIndex,
+    });
   }
 
   /**
@@ -788,7 +808,11 @@ export default class BlockManager extends Module {
       BlockEvents.dragLeave(event);
     });
 
-    block.on('didMutated', (affectedBlock: Block) => this.blockDidMutated(affectedBlock));
+    block.on('didMutated', (affectedBlock: Block) => {
+      return this.blockDidMutated(BlockMutationType.Changed, affectedBlock, {
+        index: this.getBlockIndex(affectedBlock),
+      });
+    });
   }
 
   /**
@@ -828,10 +852,19 @@ export default class BlockManager extends Module {
   /**
    * Block mutation callback
    *
+   * @param mutationType - what happened with block
    * @param block - mutated block
-   */
-  private blockDidMutated(block: Block): Block {
-    this.Editor.ModificationsObserver.onChange(new BlockAPI(block));
+   * @param details - additional data to pass with change event
+   */
+  private blockDidMutated(mutationType: BlockMutationType, block: Block, details: Record<string, unknown> = {}): Block {
+    const event = new CustomEvent(mutationType, {
+      detail: {
+        target: new BlockAPI(block),
+        ...details,
+      },
+    });
+
+    this.Editor.ModificationsObserver.onChange(event);
 
     return block;
   }

src/components/modules/modificationsObserver.ts

@@ -1,5 +1,4 @@
 import Module from '../__module';
-import { BlockAPI } from '../../../types';
 import * as _ from '../utils';
 
 /**
@@ -28,13 +27,13 @@ export default class ModificationsObserver extends Module {
   /**
    * Call onChange event passed to Editor.js configuration
    *
-   * @param block - changed Block
+   * @param event - some of our custom change events
    */
-  public onChange(block: BlockAPI): void {
+  public onChange(event: CustomEvent): void {
     if (this.disabled || !_.isFunction(this.config.onChange)) {
       return;
     }
 
-    this.config.onChange(this.Editor.API.methods, block);
+    this.config.onChange(this.Editor.API.methods, event);
   }
 }