feat(block-change): adds a new API for blocking changes to editor state, by filtering transactions (#1750)

Author: nperez0111

packages/core/src/editor/BlockNoteEditor.ts

@@ -120,6 +120,7 @@ import { EventEmitter } from "../util/EventEmitter.js";
 import { BlockNoteExtension } from "./BlockNoteExtension.js";
 
 import "../style.css";
+import { BlockChangePlugin } from "../extensions/BlockChange/BlockChangePlugin.js";
 
 /**
  * A factory function that returns a BlockNoteExtension
@@ -1596,6 +1597,32 @@ export class BlockNoteEditor<
     (this.extensions["yCursorPlugin"] as CursorPlugin).updateUser(user);
   }
 
+  /**
+   * Registers a callback which will be called before any change is applied to the editor, allowing you to cancel the change.
+   */
+  public beforeChange(
+    /**
+     * If the callback returns `false`, the change will be canceled & not applied to the editor.
+     */
+    callback: (
+      editor: BlockNoteEditor<BSchema, ISchema, SSchema>,
+      context: {
+        getChanges: () => BlocksChanged<BSchema, ISchema, SSchema>;
+        tr: Transaction;
+      },
+    ) => boolean | void,
+  ): () => void {
+    if (this.headless) {
+      return () => {
+        // noop
+      };
+    }
+
+    return (this.extensions["blockChange"] as BlockChangePlugin).subscribe(
+      (context) => callback(this, context),
+    );
+  }
+
   /**
    * A callback function that runs whenever the editor's contents change.
    *

packages/core/src/editor/BlockNoteExtensions.ts

@@ -11,6 +11,7 @@ import { createPasteFromClipboardExtension } from "../api/clipboard/fromClipboar
 import { createCopyToClipboardExtension } from "../api/clipboard/toClipboard/copyExtension.js";
 import type { ThreadStore } from "../comments/index.js";
 import { BackgroundColorExtension } from "../extensions/BackgroundColor/BackgroundColorExtension.js";
+import { BlockChangePlugin } from "../extensions/BlockChange/BlockChangePlugin.js";
 import { CursorPlugin } from "../extensions/Collaboration/CursorPlugin.js";
 import { SyncPlugin } from "../extensions/Collaboration/SyncPlugin.js";
 import { UndoPlugin } from "../extensions/Collaboration/UndoPlugin.js";
@@ -146,6 +147,7 @@ export const getBlockNoteExtensions = <
   }
 
   ret["nodeSelectionKeyboard"] = new NodeSelectionKeyboardPlugin();
+  ret["blockChange"] = new BlockChangePlugin();
 
   ret["showSelection"] = new ShowSelectionPlugin(opts.editor);
 

packages/core/src/extensions/BlockChange/BlockChangePlugin.ts

@@ -0,0 +1,66 @@
+import { Plugin, Transaction } from "prosemirror-state";
+import { getBlocksChangedByTransaction } from "../../api/nodeUtil.js";
+import { BlockNoteExtension } from "../../editor/BlockNoteExtension.js";
+import { BlocksChanged } from "../../index.js";
+
+/**
+ * This plugin can filter transactions before they are applied to the editor, but with a higher-level API than `filterTransaction` from prosemirror.
+ */
+export class BlockChangePlugin extends BlockNoteExtension {
+  public static key() {
+    return "blockChange";
+  }
+
+  private beforeChangeCallbacks: ((context: {
+    getChanges: () => BlocksChanged<any, any, any>;
+    tr: Transaction;
+  }) => boolean | void)[] = [];
+
+  constructor() {
+    super();
+
+    this.addProsemirrorPlugin(
+      new Plugin({
+        filterTransaction: (tr) => {
+          let changes:
+            | ReturnType<typeof getBlocksChangedByTransaction>
+            | undefined = undefined;
+
+          return this.beforeChangeCallbacks.reduce((acc, cb) => {
+            if (acc === false) {
+              // We only care that we hit a `false` result, so we can stop iterating.
+              return acc;
+            }
+            return (
+              cb({
+                getChanges() {
+                  if (changes) {
+                    return changes;
+                  }
+                  changes = getBlocksChangedByTransaction(tr);
+                  return changes;
+                },
+                tr,
+              }) !== false
+            );
+          }, true);
+        },
+      }),
+    );
+  }
+
+  public subscribe(
+    callback: (context: {
+      getChanges: () => BlocksChanged<any, any, any>;
+      tr: Transaction;
+    }) => boolean | void,
+  ) {
+    this.beforeChangeCallbacks.push(callback);
+
+    return () => {
+      this.beforeChangeCallbacks = this.beforeChangeCallbacks.filter(
+        (cb) => cb !== callback,
+      );
+    };
+  }
+}