@blocknote/core 0.30.1 → 0.31.0

package/src/editor/BlockNoteExtension.ts

@@ -0,0 +1,26 @@
+import { Plugin } from "prosemirror-state";
+import { EventEmitter } from "../util/EventEmitter.js";
+
+export abstract class BlockNoteExtension<
+  TEvent extends Record<string, any> = any,
+> extends EventEmitter<TEvent> {
+  public static name(): string {
+    throw new Error("You must implement the name method in your extension");
+  }
+
+  protected addProsemirrorPlugin(plugin: Plugin) {
+    this.plugins.push(plugin);
+  }
+
+  public readonly plugins: Plugin[] = [];
+  public get priority(): number | undefined {
+    return undefined;
+  }
+
+  // eslint-disable-next-line
+  constructor(..._args: any[]) {
+    super();
+    // Allow subclasses to have constructors with parameters
+    // without this, we can't easily implement BlockNoteEditor.extension(MyExtension) pattern
+  }
+}

package/src/editor/BlockNoteExtensions.ts

@@ -9,13 +9,13 @@ import * as Y from "yjs";
 import { createDropFileExtension } from "../api/clipboard/fromClipboard/fileDropExtension.js";
 import { createPasteFromClipboardExtension } from "../api/clipboard/fromClipboard/pasteExtension.js";
 import { createCopyToClipboardExtension } from "../api/clipboard/toClipboard/copyExtension.js";
+import type { ThreadStore } from "../comments/index.js";
 import { BackgroundColorExtension } from "../extensions/BackgroundColor/BackgroundColorExtension.js";
 import { CursorPlugin } from "../extensions/Collaboration/CursorPlugin.js";
-import { UndoPlugin } from "../extensions/Collaboration/UndoPlugin.js";
 import { SyncPlugin } from "../extensions/Collaboration/SyncPlugin.js";
+import { UndoPlugin } from "../extensions/Collaboration/UndoPlugin.js";
 import { CommentMark } from "../extensions/Comments/CommentMark.js";
 import { CommentsPlugin } from "../extensions/Comments/CommentsPlugin.js";
-import type { ThreadStore } from "../comments/index.js";
 import { FilePanelProsemirrorPlugin } from "../extensions/FilePanel/FilePanelPlugin.js";
 import { FormattingToolbarProsemirrorPlugin } from "../extensions/FormattingToolbar/FormattingToolbarPlugin.js";
 import { HardBreak } from "../extensions/HardBreak/HardBreak.js";
@@ -31,6 +31,11 @@ import { PreviousBlockTypePlugin } from "../extensions/PreviousBlockType/Previou
 import { ShowSelectionPlugin } from "../extensions/ShowSelection/ShowSelectionPlugin.js";
 import { SideMenuProsemirrorPlugin } from "../extensions/SideMenu/SideMenuPlugin.js";
 import { SuggestionMenuProseMirrorPlugin } from "../extensions/SuggestionMenu/SuggestionPlugin.js";
+import {
+  SuggestionAddMark,
+  SuggestionDeleteMark,
+  SuggestionModificationMark,
+} from "../extensions/Suggestions/SuggestionMarks.js";
 import { TableHandlesProsemirrorPlugin } from "../extensions/TableHandles/TableHandlesPlugin.js";
 import { TextAlignmentExtension } from "../extensions/TextAlignment/TextAlignmentExtension.js";
 import { TextColorExtension } from "../extensions/TextColor/TextColorExtension.js";
@@ -49,8 +54,9 @@ import {
 import type {
   BlockNoteEditor,
   BlockNoteEditorOptions,
-  BlockNoteExtension,
+  SupportedExtension,
 } from "./BlockNoteEditor.js";
+import { ForkYDocPlugin } from "../extensions/Collaboration/ForkYDocPlugin.js";
 
 type ExtensionOptions<
   BSchema extends BlockSchema,
@@ -101,7 +107,7 @@ export const getBlockNoteExtensions = <
 >(
   opts: ExtensionOptions<BSchema, I, S>,
 ) => {
-  const ret: Record<string, BlockNoteExtension> = {};
+  const ret: Record<string, SupportedExtension> = {};
   const tiptapExtensions = getTipTapExtensions(opts);
 
   for (const ext of tiptapExtensions) {
@@ -115,6 +121,10 @@ export const getBlockNoteExtensions = <
     if (opts.collaboration.provider?.awareness) {
       ret["yCursorPlugin"] = new CursorPlugin(opts.collaboration);
     }
+    ret["forkYDocPlugin"] = new ForkYDocPlugin({
+      editor: opts.editor,
+      collaboration: opts.collaboration,
+    });
   }
 
   // Note: this is pretty hardcoded and will break when user provides plugins with same keys.
@@ -139,14 +149,6 @@ export const getBlockNoteExtensions = <
     ret["tableHandles"] = new TableHandlesProsemirrorPlugin(opts.editor as any);
   }
 
-  ret["dropCursor"] = {
-    plugin: opts.dropCursor({
-      width: 5,
-      color: "#ddeeff",
-      editor: opts.editor,
-    }),
-  };
-
   ret["nodeSelectionKeyboard"] = new NodeSelectionKeyboardPlugin();
 
   ret["showSelection"] = new ShowSelectionPlugin(opts.editor);
@@ -190,6 +192,17 @@ const getTipTapExtensions = <
     Gapcursor,
 
     // DropCursor,
+    Extension.create({
+      name: "dropCursor",
+      addProseMirrorPlugins: () => [
+        opts.dropCursor({
+          width: 5,
+          color: "#ddeeff",
+          editor: opts.editor,
+        }),
+      ],
+    }),
+
     UniqueID.configure({
       // everything from bnBlock group (nodes that represent a BlockNote block should have an id)
       types: ["blockContainer", "columnList", "column"],
@@ -202,6 +215,9 @@ const getTipTapExtensions = <
     Text,
 
     // marks:
+    SuggestionAddMark,
+    SuggestionDeleteMark,
+    SuggestionModificationMark,
     Link.extend({
       inclusive: false,
     }).configure({

package/src/editor/BlockNoteTipTapEditor.ts

@@ -1,5 +1,9 @@
-import { Editor, EditorOptions, createDocument } from "@tiptap/core";
-import { Editor as TiptapEditor } from "@tiptap/core";
+import {
+  Editor,
+  EditorOptions,
+  Editor as TiptapEditor,
+  createDocument,
+} from "@tiptap/core";
 
 import { Node } from "@tiptap/pm/model";
 
@@ -141,6 +145,10 @@ export class BlockNoteTipTapEditor extends TiptapEditor {
     if (!this.view) {
       // before view has been initialized
       this._state = this.state.apply(transaction);
+      this.emit("transaction", {
+        editor: this,
+        transaction,
+      });
       return;
     }
     // This is a verbatim copy of the default dispatch method, but with the following changes:
@@ -216,6 +224,19 @@ export class BlockNoteTipTapEditor extends TiptapEditor {
     });
   }
 
+  // a helper method that can enable plugins before the view has been initialized
+  // currently only used for testing
+  forceEnablePlugins() {
+    if (this.view) {
+      throw new Error(
+        "forcePluginsEnabled called after view has been initialized",
+      );
+    }
+    this._state = this.state.reconfigure({
+      plugins: this.extensionManager.plugins,
+    });
+  }
+
   /**
    * Replace the default `createView` method with a custom one - which we call on mount
    */

package/src/extensions/Collaboration/CursorPlugin.ts

@@ -1,7 +1,7 @@
-import { Plugin } from "prosemirror-state";
 import { defaultSelectionBuilder, yCursorPlugin } from "y-prosemirror";
 import { Awareness } from "y-protocols/awareness.js";
 import * as Y from "yjs";
+import { BlockNoteExtension } from "../../editor/BlockNoteExtension.js";
 
 export type CollaborationUser = {
   name: string;
@@ -9,8 +9,11 @@ export type CollaborationUser = {
   [key: string]: string;
 };
 
-export class CursorPlugin {
-  public plugin: Plugin;
+export class CursorPlugin extends BlockNoteExtension {
+  public static name() {
+    return "yCursorPlugin";
+  }
+
   private provider: { awareness: Awareness };
   private recentlyUpdatedCursors: Map<
     number,
@@ -25,6 +28,7 @@ export class CursorPlugin {
       showCursorLabels?: "always" | "activity";
     },
   ) {
+    super();
     this.provider = collaboration.provider;
     this.recentlyUpdatedCursors = new Map();
 
@@ -62,10 +66,12 @@ export class CursorPlugin {
       );
     }
 
-    this.plugin = yCursorPlugin(this.provider.awareness, {
-      selectionBuilder: defaultSelectionBuilder,
-      cursorBuilder: this.renderCursor,
-    });
+    this.addProsemirrorPlugin(
+      yCursorPlugin(this.provider.awareness, {
+        selectionBuilder: defaultSelectionBuilder,
+        cursorBuilder: this.renderCursor,
+      }),
+    );
   }
 
   public get priority() {

package/src/extensions/Collaboration/ForkYDocPlugin.test.ts

@@ -0,0 +1,166 @@
+import { expect, it } from "vitest";
+import * as Y from "yjs";
+import { Awareness } from "y-protocols/awareness";
+import { BlockNoteEditor } from "../../index.js";
+
+/**
+ * @vitest-environment jsdom
+ */
+it("can fork a document", async () => {
+  const doc = new Y.Doc();
+  const fragment = doc.getXmlFragment("doc");
+  const editor = BlockNoteEditor.create({
+    collaboration: {
+      fragment,
+      user: { name: "Hello", color: "#FFFFFF" },
+      provider: {
+        awareness: new Awareness(doc),
+      },
+    },
+  });
+
+  const div = document.createElement("div");
+  editor.mount(div);
+
+  editor.replaceBlocks(editor.document, [
+    {
+      type: "paragraph",
+      content: [{ text: "Hello", styles: {}, type: "text" }],
+    },
+  ]);
+
+  await expect(fragment.toJSON()).toMatchFileSnapshot(
+    "__snapshots__/fork-yjs-snap.html",
+  );
+  await expect(editor.document).toMatchFileSnapshot(
+    "__snapshots__/fork-yjs-snap-editor.json",
+  );
+
+  editor.forkYDocPlugin!.fork();
+
+  editor.replaceBlocks(editor.document, [
+    {
+      type: "paragraph",
+      content: [{ text: "Hello World", styles: {}, type: "text" }],
+    },
+  ]);
+
+  await expect(fragment.toJSON()).toMatchFileSnapshot(
+    "__snapshots__/fork-yjs-snap.html",
+  );
+  await expect(editor.document).toMatchFileSnapshot(
+    "__snapshots__/fork-yjs-snap-editor-forked.json",
+  );
+});
+
+it("can merge a document", async () => {
+  const doc = new Y.Doc();
+  const fragment = doc.getXmlFragment("doc");
+  const editor = BlockNoteEditor.create({
+    collaboration: {
+      fragment,
+      user: { name: "Hello", color: "#FFFFFF" },
+      provider: {
+        awareness: new Awareness(doc),
+      },
+    },
+  });
+
+  const div = document.createElement("div");
+  editor.mount(div);
+
+  editor.replaceBlocks(editor.document, [
+    {
+      type: "paragraph",
+      content: [{ text: "Hello", styles: {}, type: "text" }],
+    },
+  ]);
+
+  await expect(fragment.toJSON()).toMatchFileSnapshot(
+    "__snapshots__/fork-yjs-snap.html",
+  );
+  await expect(editor.document).toMatchFileSnapshot(
+    "__snapshots__/fork-yjs-snap-editor.json",
+  );
+
+  editor.forkYDocPlugin!.fork();
+
+  editor.replaceBlocks(editor.document, [
+    {
+      type: "paragraph",
+      content: [{ text: "Hello World", styles: {}, type: "text" }],
+    },
+  ]);
+
+  await expect(fragment.toJSON()).toMatchFileSnapshot(
+    "__snapshots__/fork-yjs-snap.html",
+  );
+  await expect(editor.document).toMatchFileSnapshot(
+    "__snapshots__/fork-yjs-snap-editor-forked.json",
+  );
+
+  editor.forkYDocPlugin!.merge({ keepChanges: false });
+
+  await expect(fragment.toJSON()).toMatchFileSnapshot(
+    "__snapshots__/fork-yjs-snap.html",
+  );
+  await expect(editor.document).toMatchFileSnapshot(
+    "__snapshots__/fork-yjs-snap-editor.json",
+  );
+});
+
+it("can fork an keep the changes to the original document", async () => {
+  const doc = new Y.Doc();
+  const fragment = doc.getXmlFragment("doc");
+  const editor = BlockNoteEditor.create({
+    collaboration: {
+      fragment,
+      user: { name: "Hello", color: "#FFFFFF" },
+      provider: {
+        awareness: new Awareness(doc),
+      },
+    },
+  });
+
+  const div = document.createElement("div");
+  editor.mount(div);
+
+  editor.replaceBlocks(editor.document, [
+    {
+      type: "paragraph",
+      content: [{ text: "Hello", styles: {}, type: "text" }],
+    },
+  ]);
+
+  await expect(fragment.toJSON()).toMatchFileSnapshot(
+    "__snapshots__/fork-yjs-snap.html",
+  );
+  await expect(editor.document).toMatchFileSnapshot(
+    "__snapshots__/fork-yjs-snap-editor.json",
+  );
+
+  editor.forkYDocPlugin!.fork();
+
+  editor.replaceBlocks(editor.document, [
+    {
+      type: "paragraph",
+      content: [{ text: "Hello World", styles: {}, type: "text" }],
+    },
+  ]);
+
+  await expect(fragment.toJSON()).toMatchFileSnapshot(
+    "__snapshots__/fork-yjs-snap.html",
+  );
+  await expect(editor.document).toMatchFileSnapshot(
+    "__snapshots__/fork-yjs-snap-editor-forked.json",
+  );
+
+  editor.forkYDocPlugin!.merge({ keepChanges: true });
+
+  await expect(fragment.toJSON()).toMatchFileSnapshot(
+    "__snapshots__/fork-yjs-snap-forked.html",
+  );
+  await expect(editor.document).toMatchFileSnapshot(
+    "__snapshots__/fork-yjs-snap-editor-forked.json",
+  );
+});

package/src/extensions/Collaboration/ForkYDocPlugin.ts

@@ -0,0 +1,174 @@
+import * as Y from "yjs";
+
+import {
+  yCursorPluginKey,
+  ySyncPluginKey,
+  yUndoPluginKey,
+} from "y-prosemirror";
+import { CursorPlugin } from "./CursorPlugin.js";
+import { SyncPlugin } from "./SyncPlugin.js";
+import { UndoPlugin } from "./UndoPlugin.js";
+
+import {
+  BlockNoteEditor,
+  BlockNoteEditorOptions,
+} from "../../editor/BlockNoteEditor.js";
+import { BlockNoteExtension } from "../../editor/BlockNoteExtension.js";
+
+export class ForkYDocPlugin extends BlockNoteExtension<{
+  forked: boolean;
+}> {
+  public static name() {
+    return "ForkYDocPlugin";
+  }
+
+  private editor: BlockNoteEditor<any, any, any>;
+  private collaboration: BlockNoteEditorOptions<any, any, any>["collaboration"];
+
+  constructor({
+    editor,
+    collaboration,
+  }: {
+    editor: BlockNoteEditor<any, any, any>;
+    collaboration: BlockNoteEditorOptions<any, any, any>["collaboration"];
+  }) {
+    super(editor);
+    this.editor = editor;
+    this.collaboration = collaboration;
+  }
+
+  /**
+   * To find a fragment in another ydoc, we need to search for it.
+   */
+  private findTypeInOtherYdoc<T extends Y.AbstractType<any>>(
+    ytype: T,
+    otherYdoc: Y.Doc,
+  ): T {
+    const ydoc = ytype.doc!;
+    if (ytype._item === null) {
+      /**
+       * If is a root type, we need to find the root key in the original ydoc
+       * and use it to get the type in the other ydoc.
+       */
+      const rootKey = Array.from(ydoc.share.keys()).find(
+        (key) => ydoc.share.get(key) === ytype,
+      );
+      if (rootKey == null) {
+        throw new Error("type does not exist in other ydoc");
+      }
+      return otherYdoc.get(rootKey, ytype.constructor as new () => T) as T;
+    } else {
+      /**
+       * If it is a sub type, we use the item id to find the history type.
+       */
+      const ytypeItem = ytype._item;
+      const otherStructs =
+        otherYdoc.store.clients.get(ytypeItem.id.client) ?? [];
+      const itemIndex = Y.findIndexSS(otherStructs, ytypeItem.id.clock);
+      const otherItem = otherStructs[itemIndex] as Y.Item;
+      const otherContent = otherItem.content as Y.ContentType;
+      return otherContent.type as T;
+    }
+  }
+
+  /**
+   * Whether the editor is editing a forked document,
+   * preserving a reference to the original document and the forked document.
+   */
+  public get isForkedFromRemote() {
+    return this.forkedState !== undefined;
+  }
+
+  /**
+   * Stores whether the editor is editing a forked document,
+   * preserving a reference to the original document and the forked document.
+   */
+  private forkedState:
+    | {
+        originalFragment: Y.XmlFragment;
+        forkedFragment: Y.XmlFragment;
+      }
+    | undefined;
+
+  /**
+   * Fork the Y.js document from syncing to the remote,
+   * allowing modifications to the document without affecting the remote.
+   * These changes can later be rolled back or applied to the remote.
+   */
+  public fork() {
+    if (this.isForkedFromRemote) {
+      return;
+    }
+
+    const originalFragment = this.collaboration.fragment;
+
+    if (!originalFragment) {
+      throw new Error("No fragment to fork from");
+    }
+
+    const doc = new Y.Doc();
+    // Copy the original document to a new Yjs document
+    Y.applyUpdate(doc, Y.encodeStateAsUpdate(originalFragment.doc!));
+
+    // Find the forked fragment in the new Yjs document
+    const forkedFragment = this.findTypeInOtherYdoc(originalFragment, doc);
+
+    this.forkedState = {
+      originalFragment,
+      forkedFragment,
+    };
+
+    // Need to reset all the yjs plugins
+    this.editor._tiptapEditor.unregisterPlugin([
+      yCursorPluginKey,
+      yUndoPluginKey,
+      ySyncPluginKey,
+    ]);
+    // Register them again, based on the new forked fragment
+    this.editor._tiptapEditor.registerPlugin(
+      new SyncPlugin(forkedFragment).plugins[0],
+    );
+    this.editor._tiptapEditor.registerPlugin(new UndoPlugin().plugins[0]);
+    // No need to register the cursor plugin again, it's a local fork
+    this.emit("forked", true);
+  }
+
+  /**
+   * Resume syncing the Y.js document to the remote
+   * If `keepChanges` is true, any changes that have been made to the forked document will be applied to the original document.
+   * Otherwise, the original document will be restored and the changes will be discarded.
+   */
+  public merge({ keepChanges }: { keepChanges: boolean }) {
+    if (!this.forkedState) {
+      return;
+    }
+    // Remove the forked fragment's plugins
+    this.editor._tiptapEditor.unregisterPlugin(ySyncPluginKey);
+    this.editor._tiptapEditor.unregisterPlugin(yUndoPluginKey);
+
+    const { originalFragment, forkedFragment } = this.forkedState;
+    if (keepChanges) {
+      // Apply any changes that have been made to the fork, onto the original doc
+      const update = Y.encodeStateAsUpdate(forkedFragment.doc!);
+      Y.applyUpdate(originalFragment.doc!, update);
+    }
+    this.editor.extensions["ySyncPlugin"] = new SyncPlugin(originalFragment);
+    this.editor.extensions["yCursorPlugin"] = new CursorPlugin(
+      this.collaboration!,
+    );
+    this.editor.extensions["yUndoPlugin"] = new UndoPlugin();
+    // Register the plugins again, based on the original fragment
+    this.editor._tiptapEditor.registerPlugin(
+      this.editor.extensions["ySyncPlugin"].plugins[0],
+    );
+    this.editor._tiptapEditor.registerPlugin(
+      this.editor.extensions["yCursorPlugin"].plugins[0],
+    );
+    this.editor._tiptapEditor.registerPlugin(
+      this.editor.extensions["yUndoPlugin"].plugins[0],
+    );
+    // Reset the forked state
+    this.forkedState = undefined;
+    this.emit("forked", false);
+  }
+}

package/src/extensions/Collaboration/SyncPlugin.ts

@@ -1,12 +1,15 @@
-import { Plugin } from "prosemirror-state";
 import { ySyncPlugin } from "y-prosemirror";
 import type * as Y from "yjs";
+import { BlockNoteExtension } from "../../editor/BlockNoteExtension.js";
 
-export class SyncPlugin {
-  public plugin: Plugin;
+export class SyncPlugin extends BlockNoteExtension {
+  public static name() {
+    return "ySyncPlugin";
+  }
 
   constructor(fragment: Y.XmlFragment) {
-    this.plugin = ySyncPlugin(fragment);
+    super();
+    this.addProsemirrorPlugin(ySyncPlugin(fragment));
   }
 
   public get priority() {

package/src/extensions/Collaboration/UndoPlugin.ts

@@ -1,11 +1,14 @@
-import { Plugin } from "prosemirror-state";
 import { yUndoPlugin } from "y-prosemirror";
+import { BlockNoteExtension } from "../../editor/BlockNoteExtension.js";
 
-export class UndoPlugin {
-  public plugin: Plugin;
+export class UndoPlugin extends BlockNoteExtension {
+  public static name() {
+    return "yUndoPlugin";
+  }
 
   constructor() {
-    this.plugin = yUndoPlugin();
+    super();
+    this.addProsemirrorPlugin(yUndoPlugin());
   }
 
   public get priority() {

package/src/extensions/Collaboration/__snapshots__/fork-yjs-snap-editor-forked.json

@@ -0,0 +1,30 @@
+[
+  {
+    "children": [],
+    "content": [
+      {
+        "styles": {},
+        "text": "Hello World",
+        "type": "text",
+      },
+    ],
+    "id": "2",
+    "props": {
+      "backgroundColor": "default",
+      "textAlignment": "left",
+      "textColor": "default",
+    },
+    "type": "paragraph",
+  },
+  {
+    "children": [],
+    "content": [],
+    "id": "3",
+    "props": {
+      "backgroundColor": "default",
+      "textAlignment": "left",
+      "textColor": "default",
+    },
+    "type": "paragraph",
+  },
+]

package/src/extensions/Collaboration/__snapshots__/fork-yjs-snap-editor.json

@@ -0,0 +1,30 @@
+[
+  {
+    "children": [],
+    "content": [
+      {
+        "styles": {},
+        "text": "Hello",
+        "type": "text",
+      },
+    ],
+    "id": "0",
+    "props": {
+      "backgroundColor": "default",
+      "textAlignment": "left",
+      "textColor": "default",
+    },
+    "type": "paragraph",
+  },
+  {
+    "children": [],
+    "content": [],
+    "id": "1",
+    "props": {
+      "backgroundColor": "default",
+      "textAlignment": "left",
+      "textColor": "default",
+    },
+    "type": "paragraph",
+  },
+]

package/src/extensions/Collaboration/__snapshots__/fork-yjs-snap-forked.html

@@ -0,0 +1 @@
+<blockgroup><blockcontainer backgroundColor="default" id="2" textColor="default"><paragraph textAlignment="left">Hello World</paragraph></blockcontainer><blockcontainer backgroundColor="default" id="3" textColor="default"><paragraph textAlignment="left"></paragraph></blockcontainer></blockgroup>

package/src/extensions/Collaboration/__snapshots__/fork-yjs-snap.html

@@ -0,0 +1 @@
+<blockgroup><blockcontainer backgroundColor="default" id="0" textColor="default"><paragraph textAlignment="left">Hello</paragraph></blockcontainer><blockcontainer backgroundColor="default" id="1" textColor="default"><paragraph textAlignment="left"></paragraph></blockcontainer></blockgroup>