@blocknote/core 0.42.3 → 0.44.0

package/src/extensions/Collaboration/{ForkYDocPlugin.test.ts → ForkYDoc.test.ts}

@@ -2,6 +2,7 @@ import { expect, it } from "vitest";
 import * as Y from "yjs";
 import { Awareness } from "y-protocols/awareness";
 import { BlockNoteEditor } from "../../index.js";
+import { ForkYDocExtension } from "./ForkYDoc.js";
 
 /**
  * @vitest-environment jsdom
@@ -36,7 +37,7 @@ it("can fork a document", async () => {
     "__snapshots__/fork-yjs-snap-editor.json",
   );
 
-  editor.forkYDocPlugin!.fork();
+  editor.getExtension(ForkYDocExtension)!.fork();
 
   editor.replaceBlocks(editor.document, [
     {
@@ -83,7 +84,7 @@ it("can merge a document", async () => {
     "__snapshots__/fork-yjs-snap-editor.json",
   );
 
-  editor.forkYDocPlugin!.fork();
+  editor.getExtension(ForkYDocExtension)!.fork();
 
   editor.replaceBlocks(editor.document, [
     {
@@ -99,7 +100,7 @@ it("can merge a document", async () => {
     "__snapshots__/fork-yjs-snap-editor-forked.json",
   );
 
-  editor.forkYDocPlugin!.merge({ keepChanges: false });
+  editor.getExtension(ForkYDocExtension)!.merge({ keepChanges: false });
 
   await expect(fragment.toJSON()).toMatchFileSnapshot(
     "__snapshots__/fork-yjs-snap.html",
@@ -139,7 +140,7 @@ it("can fork an keep the changes to the original document", async () => {
     "__snapshots__/fork-yjs-snap-editor.json",
   );
 
-  editor.forkYDocPlugin!.fork();
+  editor.getExtension(ForkYDocExtension)!.fork();
 
   editor.replaceBlocks(editor.document, [
     {
@@ -155,7 +156,7 @@ it("can fork an keep the changes to the original document", async () => {
     "__snapshots__/fork-yjs-snap-editor-forked.json",
   );
 
-  editor.forkYDocPlugin!.merge({ keepChanges: true });
+  editor.getExtension(ForkYDocExtension)!.merge({ keepChanges: true });
 
   await expect(fragment.toJSON()).toMatchFileSnapshot(
     "__snapshots__/fork-yjs-snap-forked.html",

package/src/extensions/Collaboration/ForkYDoc.ts

@@ -0,0 +1,158 @@
+import { yUndoPluginKey } from "y-prosemirror";
+import * as Y from "yjs";
+import {
+  createExtension,
+  createStore,
+  ExtensionOptions,
+} from "../../editor/BlockNoteExtension.js";
+import { YCursorExtension } from "./YCursorPlugin.js";
+import { YSyncExtension } from "./YSync.js";
+import { YUndoExtension } from "./YUndo.js";
+import { BlockNoteEditorOptions } from "../../editor/BlockNoteEditor.js";
+
+/**
+ * To find a fragment in another ydoc, we need to search for it.
+ */
+function 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;
+  }
+}
+
+export const ForkYDocExtension = createExtension(
+  ({
+    editor,
+    options,
+  }: ExtensionOptions<
+    NonNullable<BlockNoteEditorOptions<any, any, any>["collaboration"]>
+  >) => {
+    let forkedState:
+      | {
+          originalFragment: Y.XmlFragment;
+          undoStack: Y.UndoManager["undoStack"];
+          forkedFragment: Y.XmlFragment;
+        }
+      | undefined = undefined;
+
+    const store = createStore({ isForked: false });
+
+    return {
+      key: "yForkDoc",
+      store,
+      /**
+       * 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.
+       */
+      fork() {
+        if (forkedState) {
+          return;
+        }
+
+        const originalFragment = options.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 = findTypeInOtherYdoc(originalFragment, doc);
+
+        forkedState = {
+          undoStack: yUndoPluginKey.getState(editor.prosemirrorState)!
+            .undoManager.undoStack,
+          originalFragment,
+          forkedFragment,
+        };
+
+        // Need to reset all the yjs plugins
+        editor.unregisterExtension([
+          YUndoExtension,
+          YCursorExtension,
+          YSyncExtension,
+        ]);
+        const newOptions = {
+          ...options,
+          fragment: forkedFragment,
+        };
+        // Register them again, based on the new forked fragment
+        editor.registerExtension([
+          YSyncExtension(newOptions),
+          // No need to register the cursor plugin again, it's a local fork
+          YUndoExtension({}),
+        ]);
+
+        // Tell the store that the editor is now forked
+        store.setState({ isForked: 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.
+       */
+      merge({ keepChanges }: { keepChanges: boolean }) {
+        if (!forkedState) {
+          return;
+        }
+        // Remove the forked fragment's plugins
+        editor.unregisterExtension(["ySync", "yCursor", "yUndo"]);
+
+        const { originalFragment, forkedFragment, undoStack } = forkedState;
+        // Register the plugins again, based on the original fragment (which is still in the original options)
+        editor.registerExtension([
+          YSyncExtension(options),
+          YCursorExtension(options),
+          YUndoExtension({}),
+        ]);
+
+        // Reset the undo stack to the original undo stack
+        yUndoPluginKey.getState(
+          editor.prosemirrorState,
+        )!.undoManager.undoStack = undoStack;
+
+        if (keepChanges) {
+          // Apply any changes that have been made to the fork, onto the original doc
+          const update = Y.encodeStateAsUpdate(
+            forkedFragment.doc!,
+            Y.encodeStateVector(originalFragment.doc!),
+          );
+          // Applying this change will add to the undo stack, allowing it to be undone normally
+          Y.applyUpdate(originalFragment.doc!, update, editor);
+        }
+        // Reset the forked state
+        forkedState = undefined;
+        // Tell the store that the editor is no longer forked
+        store.setState({ isForked: false });
+      },
+    } as const;
+  },
+);

package/src/extensions/Collaboration/YCursorPlugin.ts

@@ -0,0 +1,183 @@
+import { defaultSelectionBuilder, yCursorPlugin } from "y-prosemirror";
+import {
+  createExtension,
+  ExtensionOptions,
+} from "../../editor/BlockNoteExtension.js";
+import { BlockNoteEditorOptions } from "../../editor/BlockNoteEditor.js";
+
+export type CollaborationUser = {
+  name: string;
+  color: string;
+  [key: string]: string;
+};
+
+/**
+ * Determine whether the foreground color should be white or black based on a provided background color
+ * Inspired by: https://stackoverflow.com/a/3943023
+ */
+function isDarkColor(bgColor: string): boolean {
+  const color = bgColor.charAt(0) === "#" ? bgColor.substring(1, 7) : bgColor;
+  const r = parseInt(color.substring(0, 2), 16); // hexToR
+  const g = parseInt(color.substring(2, 4), 16); // hexToG
+  const b = parseInt(color.substring(4, 6), 16); // hexToB
+  const uicolors = [r / 255, g / 255, b / 255];
+  const c = uicolors.map((col) => {
+    if (col <= 0.03928) {
+      return col / 12.92;
+    }
+    return Math.pow((col + 0.055) / 1.055, 2.4);
+  });
+  const L = 0.2126 * c[0] + 0.7152 * c[1] + 0.0722 * c[2];
+  return L <= 0.179;
+}
+
+function defaultCursorRender(user: CollaborationUser) {
+  const cursorElement = document.createElement("span");
+
+  cursorElement.classList.add("bn-collaboration-cursor__base");
+
+  const caretElement = document.createElement("span");
+  caretElement.setAttribute("contentedEditable", "false");
+  caretElement.classList.add("bn-collaboration-cursor__caret");
+  caretElement.setAttribute(
+    "style",
+    `background-color: ${user.color}; color: ${
+      isDarkColor(user.color) ? "white" : "black"
+    }`,
+  );
+
+  const labelElement = document.createElement("span");
+
+  labelElement.classList.add("bn-collaboration-cursor__label");
+  labelElement.setAttribute(
+    "style",
+    `background-color: ${user.color}; color: ${
+      isDarkColor(user.color) ? "white" : "black"
+    }`,
+  );
+  labelElement.insertBefore(document.createTextNode(user.name), null);
+
+  caretElement.insertBefore(labelElement, null);
+
+  cursorElement.insertBefore(document.createTextNode("\u2060"), null); // Non-breaking space
+  cursorElement.insertBefore(caretElement, null);
+  cursorElement.insertBefore(document.createTextNode("\u2060"), null); // Non-breaking space
+
+  return cursorElement;
+}
+
+export const YCursorExtension = createExtension(
+  ({
+    options,
+  }: ExtensionOptions<
+    NonNullable<BlockNoteEditorOptions<any, any, any>["collaboration"]>
+  >) => {
+    const recentlyUpdatedCursors = new Map();
+
+    if (
+      options.provider &&
+      "awareness" in options.provider &&
+      typeof options.provider.awareness === "object"
+    ) {
+      if (
+        "setLocalStateField" in options.provider.awareness &&
+        typeof options.provider.awareness.setLocalStateField === "function"
+      ) {
+        options.provider.awareness.setLocalStateField("user", options.user);
+      }
+      if (
+        "on" in options.provider.awareness &&
+        typeof options.provider.awareness.on === "function"
+      ) {
+        if (options.showCursorLabels !== "always") {
+          options.provider.awareness.on(
+            "change",
+            ({
+              updated,
+            }: {
+              added: Array<number>;
+              updated: Array<number>;
+              removed: Array<number>;
+            }) => {
+              for (const clientID of updated) {
+                const cursor = recentlyUpdatedCursors.get(clientID);
+
+                if (cursor) {
+                  cursor.element.setAttribute("data-active", "");
+
+                  if (cursor.hideTimeout) {
+                    clearTimeout(cursor.hideTimeout);
+                  }
+
+                  recentlyUpdatedCursors.set(clientID, {
+                    element: cursor.element,
+                    hideTimeout: setTimeout(() => {
+                      cursor.element.removeAttribute("data-active");
+                    }, 2000),
+                  });
+                }
+              }
+            },
+          );
+        }
+      }
+    }
+
+    return {
+      key: "yCursor",
+      prosemirrorPlugins: [
+        yCursorPlugin(options.provider.awareness, {
+          selectionBuilder: defaultSelectionBuilder,
+          cursorBuilder(user: CollaborationUser, clientID: number) {
+            let cursorData = recentlyUpdatedCursors.get(clientID);
+
+            if (!cursorData) {
+              const cursorElement = (
+                options.renderCursor ?? defaultCursorRender
+              )(user);
+
+              if (options.showCursorLabels !== "always") {
+                cursorElement.addEventListener("mouseenter", () => {
+                  const cursor = recentlyUpdatedCursors.get(clientID)!;
+                  cursor.element.setAttribute("data-active", "");
+
+                  if (cursor.hideTimeout) {
+                    clearTimeout(cursor.hideTimeout);
+                    recentlyUpdatedCursors.set(clientID, {
+                      element: cursor.element,
+                      hideTimeout: undefined,
+                    });
+                  }
+                });
+
+                cursorElement.addEventListener("mouseleave", () => {
+                  const cursor = recentlyUpdatedCursors.get(clientID)!;
+
+                  recentlyUpdatedCursors.set(clientID, {
+                    element: cursor.element,
+                    hideTimeout: setTimeout(() => {
+                      cursor.element.removeAttribute("data-active");
+                    }, 2000),
+                  });
+                });
+              }
+
+              cursorData = {
+                element: cursorElement,
+                hideTimeout: undefined,
+              };
+
+              recentlyUpdatedCursors.set(clientID, cursorData);
+            }
+
+            return cursorData.element;
+          },
+        }),
+      ],
+      dependsOn: ["ySync"],
+      updateUser(user: { name: string; color: string; [key: string]: string }) {
+        options.provider.awareness.setLocalStateField("user", user);
+      },
+    } as const;
+  },
+);

package/src/extensions/Collaboration/YSync.ts

@@ -0,0 +1,16 @@
+import { ySyncPlugin } from "y-prosemirror";
+import { XmlFragment } from "yjs";
+import {
+  ExtensionOptions,
+  createExtension,
+} from "../../editor/BlockNoteExtension.js";
+
+export const YSyncExtension = createExtension(
+  ({ options }: ExtensionOptions<{ fragment: XmlFragment }>) => {
+    return {
+      key: "ySync",
+      prosemirrorPlugins: [ySyncPlugin(options.fragment)],
+      runsBefore: ["default"],
+    } as const;
+  },
+);

package/src/extensions/Collaboration/YUndo.ts

@@ -0,0 +1,12 @@
+import { redoCommand, undoCommand, yUndoPlugin } from "y-prosemirror";
+import { createExtension } from "../../editor/BlockNoteExtension.js";
+
+export const YUndoExtension = createExtension(({ editor }) => {
+  return {
+    key: "yUndo",
+    prosemirrorPlugins: [yUndoPlugin({ trackedOrigins: [editor] })],
+    dependsOn: ["yCursor", "ySync"],
+    undoCommand: undoCommand,
+    redoCommand: redoCommand,
+  } as const;
+});

package/src/extensions/Collaboration/schemaMigration/SchemaMigration.ts

@@ -0,0 +1,59 @@
+import { Plugin, PluginKey } from "@tiptap/pm/state";
+import * as Y from "yjs";
+
+import {
+  createExtension,
+  ExtensionOptions,
+} from "../../../editor/BlockNoteExtension.js";
+import migrationRules from "./migrationRules/index.js";
+
+// This plugin allows us to update collaboration YDocs whenever BlockNote's
+// underlying ProseMirror schema changes. The plugin reads the current Yjs
+// fragment and dispatches additional transactions to the ProseMirror state, in
+// case things are found in the fragment that don't adhere to the editor schema
+// and need to be fixed. These fixes are defined as `MigrationRule`s within the
+// `migrationRules` directory.
+export const SchemaMigration = createExtension(
+  ({ options }: ExtensionOptions<{ fragment: Y.XmlFragment }>) => {
+    let migrationDone = false;
+    const pluginKey = new PluginKey("schemaMigration");
+
+    return {
+      key: "schemaMigration",
+      prosemirrorPlugins: [
+        new Plugin({
+          key: pluginKey,
+          appendTransaction: (transactions, _oldState, newState) => {
+            if (migrationDone) {
+              return undefined;
+            }
+
+            if (
+              // If any of the transactions are not due to a yjs sync, we don't need to run the migration
+              !transactions.some((tr) => tr.getMeta("y-sync$")) ||
+              // If none of the transactions result in a document change, we don't need to run the migration
+              transactions.every((tr) => !tr.docChanged) ||
+              // If the fragment is still empty, we can't run the migration (since it has not yet been applied to the Y.Doc)
+              !options.fragment.firstChild
+            ) {
+              return undefined;
+            }
+
+            const tr = newState.tr;
+            for (const migrationRule of migrationRules) {
+              migrationRule(options.fragment, tr);
+            }
+
+            migrationDone = true;
+
+            if (!tr.docChanged) {
+              return undefined;
+            }
+
+            return tr;
+          },
+        }),
+      ],
+    } as const;
+  },
+);

package/src/extensions/DropCursor/DropCursor.ts

@@ -0,0 +1,26 @@
+import { dropCursor } from "prosemirror-dropcursor";
+import {
+  createExtension,
+  ExtensionOptions,
+} from "../../editor/BlockNoteExtension.js";
+import { BlockNoteEditorOptions } from "../../editor/BlockNoteEditor.js";
+
+export const DropCursorExtension = createExtension(
+  ({
+    editor,
+    options,
+  }: ExtensionOptions<
+    Pick<BlockNoteEditorOptions<any, any, any>, "dropCursor">
+  >) => {
+    return {
+      key: "dropCursor",
+      prosemirrorPlugins: [
+        (options.dropCursor ?? dropCursor)({
+          width: 5,
+          color: "#ddeeff",
+          editor: editor,
+        }),
+      ],
+    } as const;
+  },
+);

package/src/extensions/FilePanel/FilePanel.ts

@@ -0,0 +1,41 @@
+import {
+  createExtension,
+  createStore,
+} from "../../editor/BlockNoteExtension.js";
+
+export const FilePanelExtension = createExtension(({ editor }) => {
+  const store = createStore<string | undefined>(undefined);
+
+  function closeMenu() {
+    store.setState(undefined);
+  }
+
+  return {
+    key: "filePanel",
+    store,
+    mount({ signal }) {
+      // Reset the menu when the document changes.
+      const unsubscribeOnChange = editor.onChange(
+        closeMenu,
+        // Don't trigger if the changes are caused by a remote user.
+        false,
+      );
+
+      // reset the menu when the selection changes
+      const unsubscribeOnSelectionChange = editor.onSelectionChange(
+        closeMenu,
+        // Don't trigger if the changes are caused by a remote user.
+        false,
+      );
+
+      signal.addEventListener("abort", () => {
+        unsubscribeOnChange();
+        unsubscribeOnSelectionChange();
+      });
+    },
+    closeMenu,
+    showMenu(blockId: string) {
+      store.setState(blockId);
+    },
+  } as const;
+});

package/src/extensions/FormattingToolbar/FormattingToolbar.ts

@@ -0,0 +1,119 @@
+import { NodeSelection, TextSelection } from "prosemirror-state";
+
+import {
+  createExtension,
+  createStore,
+} from "../../editor/BlockNoteExtension.js";
+
+export const FormattingToolbarExtension = createExtension(({ editor }) => {
+  const store = createStore(false);
+
+  const shouldShow = () => {
+    return editor.transact((tr) => {
+      // Don't show if the selection is empty, or is a text selection with no
+      // text.
+      if (tr.selection.empty) {
+        return false;
+      }
+
+      // Don't show if a block with inline content is selected.
+      if (
+        tr.selection instanceof NodeSelection &&
+        (tr.selection.node.type.spec.content === "inline*" ||
+          tr.selection.node.firstChild?.type.spec.content === "inline*")
+      ) {
+        return false;
+      }
+
+      // Don't show if the selection is a text selection but contains no text.
+      if (
+        tr.selection instanceof TextSelection &&
+        tr.doc.textBetween(tr.selection.from, tr.selection.to).length === 0
+      ) {
+        return false;
+      }
+
+      // Searches the content of the selection to see if it spans a node with a
+      // code spec.
+      let spansCode = false;
+      tr.selection.content().content.descendants((node) => {
+        if (node.type.spec.code) {
+          spansCode = true;
+        }
+        return !spansCode; // keep descending if we haven't found a code block
+      });
+
+      // Don't show if the selection spans a code block.
+      if (spansCode) {
+        return false;
+      }
+
+      // Show toolbar otherwise.
+      return true;
+    });
+  };
+
+  return {
+    key: "formattingToolbar",
+    store,
+    mount({ dom, signal }) {
+      /**
+       * We want to mimic the Notion behavior of not showing the toolbar while the user is holding down the mouse button (to create a selection)
+       */
+      let preventShowWhileMouseDown = false;
+
+      const unsubscribeOnChange = editor.onChange(() => {
+        if (preventShowWhileMouseDown) {
+          return;
+        }
+        // re-evaluate whether the toolbar should be shown
+        store.setState(shouldShow());
+      });
+      const unsubscribeOnSelectionChange = editor.onSelectionChange(() => {
+        if (preventShowWhileMouseDown) {
+          return;
+        }
+        // re-evaluate whether the toolbar should be shown
+        store.setState(shouldShow());
+      });
+
+      // To mimic Notion's behavior, we listen to the mouse down event to set the `preventShowWhileMouseDown` flag
+      dom.addEventListener(
+        "pointerdown",
+        () => {
+          preventShowWhileMouseDown = true;
+          store.setState(false);
+        },
+        { signal },
+      );
+      // To mimic Notion's behavior, we listen to the mouse up event to reset the `preventShowWhileMouseDown` flag and show the toolbar (if it should)
+      editor.prosemirrorView.root.addEventListener(
+        "pointerup",
+        () => {
+          preventShowWhileMouseDown = false;
+          // We only want to re-show the toolbar if the mouse made the selection
+          if (editor.isFocused()) {
+            store.setState(shouldShow());
+          }
+        },
+        { signal, capture: true },
+      );
+      // If the pointer gets cancelled, we don't want to be stuck in the `preventShowWhileMouseDown` state
+      dom.addEventListener(
+        "pointercancel",
+        () => {
+          preventShowWhileMouseDown = false;
+        },
+        {
+          signal,
+          capture: true,
+        },
+      );
+
+      signal.addEventListener("abort", () => {
+        unsubscribeOnChange();
+        unsubscribeOnSelectionChange();
+      });
+    },
+  } as const;
+});

package/src/extensions/History/History.ts

@@ -0,0 +1,11 @@
+import { history, redo, undo } from "@tiptap/pm/history";
+import { createExtension } from "../../editor/BlockNoteExtension.js";
+
+export const HistoryExtension = createExtension(() => {
+  return {
+    key: "history",
+    prosemirrorPlugins: [history()],
+    undoCommand: undo,
+    redoCommand: redo,
+  } as const;
+});