Block lifecycle hooks

docs/tools.md

@@ -462,3 +462,17 @@ class ListTool {
   }
 }
 ```
+
+## Block Lifecycle hooks
+
+### `rendered()`
+
+Called after Block contents is added to the page
+
+### `updated()`
+
+Called each time Block contents is updated
+
+### `removed()`
+
+Called after Block contents is removed from the page but before Block instance deleted

src/components/block.ts

@@ -28,6 +28,21 @@ import DeleteTune from './block-tunes/block-tune-delete';
 import MoveDownTune from './block-tunes/block-tune-move-down';
 import SelectionUtils from './selection';
 
+/**
+ * Available Block Tool API methods
+ */
+export enum BlockToolAPI {
+  /**
+   * @todo remove method in 3.0.0
+   * @deprecated — use 'rendered' hook instead
+   */
+  APPEND_CALLBACK = 'appendCallback',
+  RENDERED = 'rendered',
+  UPDATED = 'updated',
+  REMOVED = 'removed',
+  ON_PASTE = 'onPaste',
+}
+
 /**
  * @classdesc Abstract Block class that contains Block information, Tool name and Tool class instance
  *
@@ -337,6 +352,29 @@ export default class Block {
    */
   private mutationObserver: MutationObserver;
 
+  /**
+   * Debounce Timer
+   * @type {number}
+   */
+  private readonly modificationDebounceTimer = 450;
+
+  /**
+   * Is fired when DOM mutation has been happened
+   */
+  private didMutated = _.debounce((): void => {
+    /**
+     * Drop cache
+     */
+    this.cachedInputs = [];
+
+    /**
+     * Update current input
+     */
+    this.updateCurrentInput();
+
+    this.call(BlockToolAPI.UPDATED);
+  }, this.modificationDebounceTimer);
+
   /**
    * @constructor
    * @param {String} toolName - Tool name that passed on initialization
@@ -375,12 +413,16 @@ export default class Block {
    * @param {String} methodName
    * @param {Object} params
    */
-  public call(methodName: string, params: object) {
+  public call(methodName: string, params?: object) {
     /**
      * call Tool's method with the instance context
      */
     if (this.tool[methodName] && this.tool[methodName] instanceof Function) {
-      this.tool[methodName].call(this.tool, params);
+      try {
+        this.tool[methodName].call(this.tool, params);
+      } catch (e) {
+        _.log(`Error during '${methodName}' call: ${e.message}`, 'error');
+      }
     }
   }
 
@@ -485,7 +527,15 @@ export default class Block {
     /**
      * Observe DOM mutations to update Block inputs
      */
-    this.mutationObserver.observe(this.holder, {childList: true, subtree: true});
+    this.mutationObserver.observe(
+      this.holder.firstElementChild,
+      {
+        childList: true,
+        subtree: true,
+        characterData: true,
+        attributes: true,
+      },
+    );
   }
 
   /**
@@ -495,21 +545,6 @@ export default class Block {
     this.mutationObserver.disconnect();
   }
 
-  /**
-   * Is fired when DOM mutation has been happened
-   */
-  private didMutated = (): void => {
-    /**
-     * Drop cache
-     */
-    this.cachedInputs = [];
-
-    /**
-     * Update current input
-     */
-    this.updateCurrentInput();
-  }
-
   /**
    * Make default Block wrappers and put Tool`s content there
    * @returns {HTMLDivElement}

src/components/blocks.ts

@@ -1,6 +1,6 @@
 import _ from './utils';
 import $ from './dom';
-import Block from './block';
+import Block, {BlockToolAPI} from './block';
 
 /**
  * @class Blocks
@@ -12,7 +12,6 @@ import Block from './block';
  *
  */
 export default class Blocks {
-
   /**
    * Get length of Block instances array
    *
@@ -47,16 +46,27 @@ export default class Blocks {
    * blocks[0] = new Block(...)
    *
    * @param {Blocks} instance — Blocks instance
-   * @param {Number|String} index — block index
-   * @param {Block} block — Block to set
+   * @param {Number|String} property — block index or any Blocks class property to set
+   * @param {Block} value — value to set
    * @returns {Boolean}
    */
-  public static set(instance: Blocks, index: number, block: Block) {
-    if (isNaN(Number(index))) {
-      return false;
+  public static set(instance: Blocks, property: number | string, value: Block | any) {
+
+    /**
+     * If property name is not a number (method or other property, access it via reflect
+     */
+    if (isNaN(Number(property))) {
+      Reflect.set(instance, property, value);
+      return true;
     }
 
-    instance.insert(+index, block);
+    /**
+     * If property is number, call insert method to emulate array behaviour
+     *
+     * @example
+     * blocks[0] = new Block();
+     */
+    instance.insert(+property, value);
 
     return true;
   }
@@ -65,15 +75,22 @@ export default class Blocks {
    * Proxy trap to implement array-like getter
    *
    * @param {Blocks} instance — Blocks instance
-   * @param {Number|String} index — Block index
+   * @param {Number|String} property — Blocks class property
    * @returns {Block|*}
    */
-  public static get(instance: Blocks, index: number) {
-    if (isNaN(Number(index))) {
-      return instance[index];
+  public static get(instance: Blocks, property: any | number) {
+
+    /**
+     * If property is not a number, get it via Reflect object
+     */
+    if (isNaN(Number(property))) {
+      return Reflect.get(instance, property);
     }
 
-    return instance.get(+index);
+    /**
+     * If property is a number (Block index) return Block by passed index
+     */
+    return instance.get(+property);
   }
 
   /**
@@ -103,7 +120,7 @@ export default class Blocks {
    */
   public push(block: Block): void {
     this.blocks.push(block);
-    this.workingArea.appendChild(block.holder);
+    this.insertToDOM(block);
   }
 
   /**
@@ -145,6 +162,7 @@ export default class Blocks {
 
     if (replace) {
       this.blocks[index].holder.remove();
+      this.blocks[index].call(BlockToolAPI.REMOVED);
     }
 
     const deleteCount = replace ? 1 : 0;
@@ -154,14 +172,14 @@ export default class Blocks {
     if (index > 0) {
       const previousBlock = this.blocks[index - 1];
 
-      previousBlock.holder.insertAdjacentElement('afterend', block.holder);
+      this.insertToDOM(block, 'afterend', previousBlock);
     } else {
       const nextBlock = this.blocks[index + 1];
 
       if (nextBlock) {
-        nextBlock.holder.insertAdjacentElement('beforebegin', block.holder);
+        this.insertToDOM(block, 'beforebegin', nextBlock);
       } else {
-        this.workingArea.appendChild(block.holder);
+        this.insertToDOM(block);
       }
     }
   }
@@ -176,6 +194,9 @@ export default class Blocks {
     }
 
     this.blocks[index].holder.remove();
+
+    this.blocks[index].call(BlockToolAPI.REMOVED);
+
     this.blocks.splice(index, 1);
   }
 
@@ -184,6 +205,9 @@ export default class Blocks {
    */
   public removeAll(): void {
     this.workingArea.innerHTML = '';
+
+    this.blocks.forEach((block) => block.call(BlockToolAPI.REMOVED));
+
     this.blocks.length = 0;
   }
 
@@ -220,4 +244,21 @@ export default class Blocks {
   public indexOf(block: Block): number {
     return this.blocks.indexOf(block);
   }
+
+  /**
+   * Insert new Block into DOM
+   *
+   * @param {Block} block - Block to insert
+   * @param {InsertPosition} position — insert position (if set, will use insertAdjacentElement)
+   * @param {Block} target — Block related to position
+   */
+  private insertToDOM(block: Block, position?: InsertPosition, target?: Block): void {
+    if (position) {
+      target.holder.insertAdjacentElement(position, block.holder);
+    } else {
+      this.workingArea.appendChild(block.holder);
+    }
+
+    block.call(BlockToolAPI.RENDERED);
+  }
 }

src/components/core.ts

@@ -77,7 +77,9 @@ export default class Core {
 
         _.log('I\'m ready! (ﾉ◕ヮ◕)ﾉ*:･ﾟ✧', 'log', '', 'color: #E24A75');
 
-        setTimeout(() => {
+        setTimeout(async () => {
+          await this.render();
+
           if ((this.configuration as EditorConfig).autofocus) {
             const {BlockManager, Caret} = this.moduleInstances;
 
@@ -268,16 +270,27 @@ export default class Core {
       }),
       Promise.resolve(),
     );
+  }
 
+  /**
+   * Render initial data
+   */
+  private render(): Promise<void> {
     return this.moduleInstances.Renderer.render(this.config.data.blocks);
   }
 
   /**
    * Make modules instances and save it to the @property this.moduleInstances
    */
   private constructModules(): void {
-    modules.forEach( (Module) => {
+    modules.forEach( (module) => {
+      /**
+       * If module has non-default exports, passed object contains them all and default export as 'default' property
+       */
+      const Module = typeof module === 'function' ? module : module.default;
+
       try {
+
         /**
          * We use class name provided by displayName property
          *

src/components/dom.ts

@@ -100,7 +100,10 @@ export default class Dom {
    * @param  {Element|DocumentFragment} parent    - where to append
    * @param  {Element|Element[]|Text|Text[]} elements - element or elements list
    */
-  public static append(parent: Element|DocumentFragment, elements: Element|Element[]|DocumentFragment|Text|Text[]): void {
+  public static append(
+    parent: Element|DocumentFragment,
+    elements: Element|Element[]|DocumentFragment|Text|Text[],
+  ): void {
     if ( Array.isArray(elements) ) {
       elements.forEach( (el) => parent.appendChild(el) );
     } else {

src/components/modules/blockManager.ts

@@ -6,7 +6,7 @@
  *
  * @version 2.0.0
  */
-import Block from '../block';
+import Block, {BlockToolAPI} from '../block';
 import Module from '../__module';
 import $ from '../dom';
 import _ from '../utils';
@@ -267,7 +267,7 @@ export default class BlockManager extends Module {
     }
 
     try {
-      block.call('onPaste', pasteEvent);
+      block.call(BlockToolAPI.ON_PASTE, pasteEvent);
     } catch (e) {
       _.log(`${toolName}: onPaste callback call is failed`, 'error', e);
     }

src/components/modules/events.ts

@@ -36,6 +36,33 @@ export default class Events extends Module {
     this.subscribers[eventName].push(callback);
   }
 
+  /**
+   * Subscribe any event on callback. Callback will be called once and be removed from subscribers array after call.
+   *
+   * @param {String} eventName - event name
+   * @param {Function} callback - subscriber
+   */
+  public once(eventName: string, callback: (data: any) => any) {
+    if (!(eventName in this.subscribers)) {
+      this.subscribers[eventName] = [];
+    }
+
+    const wrappedCallback = (data: any) => {
+      const result = callback(data);
+
+      const indexOfHandler = this.subscribers[eventName].indexOf(wrappedCallback);
+
+      if (indexOfHandler !== -1) {
+        this.subscribers[eventName].splice(indexOfHandler, 1);
+      }
+
+      return result;
+    };
+
+    // group by events
+    this.subscribers[eventName].push(wrappedCallback);
+  }
+
   /**
    * Emit callbacks with passed data
    *