@blocknote/core 0.40.0 → 0.41.0

package/src/editor/BlockNoteExtensions.ts

@@ -9,7 +9,7 @@ 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 type { ThreadStore, User } 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";
@@ -96,6 +96,7 @@ type ExtensionOptions<
   comments?: {
     schema?: BlockNoteSchema<any, any, any>;
     threadStore: ThreadStore;
+    resolveUsers?: (userIds: string[]) => Promise<User[]>;
   };
   pasteHandler: BlockNoteEditorOptions<any, any, any>["pasteHandler"];
 };
@@ -162,6 +163,7 @@ export const getBlockNoteExtensions = <
       opts.editor,
       opts.comments.threadStore,
       CommentMark.name,
+      opts.comments.resolveUsers,
       opts.comments.schema,
     );
   }

package/src/editor/managers/BlockManager.ts

@@ -0,0 +1,251 @@
+import { insertBlocks } from "../../api/blockManipulation/commands/insertBlocks/insertBlocks.js";
+import {
+  moveBlocksDown,
+  moveBlocksUp,
+} from "../../api/blockManipulation/commands/moveBlocks/moveBlocks.js";
+import {
+  canNestBlock,
+  canUnnestBlock,
+  nestBlock,
+  unnestBlock,
+} from "../../api/blockManipulation/commands/nestBlock/nestBlock.js";
+import { removeAndInsertBlocks } from "../../api/blockManipulation/commands/replaceBlocks/replaceBlocks.js";
+import { updateBlock } from "../../api/blockManipulation/commands/updateBlock/updateBlock.js";
+import {
+  getBlock,
+  getNextBlock,
+  getParentBlock,
+  getPrevBlock,
+} from "../../api/blockManipulation/getBlock/getBlock.js";
+import { docToBlocks } from "../../api/nodeConversions/nodeToBlock.js";
+import {
+  Block,
+  DefaultBlockSchema,
+  DefaultInlineContentSchema,
+  DefaultStyleSchema,
+  PartialBlock,
+} from "../../blocks/defaultBlocks.js";
+import {
+  BlockIdentifier,
+  BlockSchema,
+  InlineContentSchema,
+  StyleSchema,
+} from "../../schema/index.js";
+import { BlockNoteEditor } from "../BlockNoteEditor.js";
+
+export class BlockManager<
+  BSchema extends BlockSchema = DefaultBlockSchema,
+  ISchema extends InlineContentSchema = DefaultInlineContentSchema,
+  SSchema extends StyleSchema = DefaultStyleSchema,
+> {
+  constructor(private editor: BlockNoteEditor<BSchema, ISchema, SSchema>) {}
+
+  /**
+   * Gets a snapshot of all top-level (non-nested) blocks in the editor.
+   * @returns A snapshot of all top-level (non-nested) blocks in the editor.
+   */
+  public get document(): Block<BSchema, ISchema, SSchema>[] {
+    return this.editor.transact((tr) => {
+      return docToBlocks(tr.doc, this.editor.pmSchema);
+    });
+  }
+
+  /**
+   * Gets a snapshot of an existing block from the editor.
+   * @param blockIdentifier The identifier of an existing block that should be
+   * retrieved.
+   * @returns The block that matches the identifier, or `undefined` if no
+   * matching block was found.
+   */
+  public getBlock(
+    blockIdentifier: BlockIdentifier,
+  ): Block<BSchema, ISchema, SSchema> | undefined {
+    return this.editor.transact((tr) => getBlock(tr.doc, blockIdentifier));
+  }
+
+  /**
+   * Gets a snapshot of the previous sibling of an existing block from the
+   * editor.
+   * @param blockIdentifier The identifier of an existing block for which the
+   * previous sibling should be retrieved.
+   * @returns The previous sibling of the block that matches the identifier.
+   * `undefined` if no matching block was found, or it's the first child/block
+   * in the document.
+   */
+  public getPrevBlock(
+    blockIdentifier: BlockIdentifier,
+  ): Block<BSchema, ISchema, SSchema> | undefined {
+    return this.editor.transact((tr) => getPrevBlock(tr.doc, blockIdentifier));
+  }
+
+  /**
+   * Gets a snapshot of the next sibling of an existing block from the editor.
+   * @param blockIdentifier The identifier of an existing block for which the
+   * next sibling should be retrieved.
+   * @returns The next sibling of the block that matches the identifier.
+   * `undefined` if no matching block was found, or it's the last child/block in
+   * the document.
+   */
+  public getNextBlock(
+    blockIdentifier: BlockIdentifier,
+  ): Block<BSchema, ISchema, SSchema> | undefined {
+    return this.editor.transact((tr) => getNextBlock(tr.doc, blockIdentifier));
+  }
+
+  /**
+   * Gets a snapshot of the parent of an existing block from the editor.
+   * @param blockIdentifier The identifier of an existing block for which the
+   * parent should be retrieved.
+   * @returns The parent of the block that matches the identifier. `undefined`
+   * if no matching block was found, or the block isn't nested.
+   */
+  public getParentBlock(
+    blockIdentifier: BlockIdentifier,
+  ): Block<BSchema, ISchema, SSchema> | undefined {
+    return this.editor.transact((tr) =>
+      getParentBlock(tr.doc, blockIdentifier),
+    );
+  }
+
+  /**
+   * Traverses all blocks in the editor depth-first, and executes a callback for each.
+   * @param callback The callback to execute for each block. Returning `false` stops the traversal.
+   * @param reverse Whether the blocks should be traversed in reverse order.
+   */
+  public forEachBlock(
+    callback: (block: Block<BSchema, ISchema, SSchema>) => boolean,
+    reverse = false,
+  ): void {
+    const blocks = this.document.slice();
+
+    if (reverse) {
+      blocks.reverse();
+    }
+
+    function traverseBlockArray(
+      blockArray: Block<BSchema, ISchema, SSchema>[],
+    ): boolean {
+      for (const block of blockArray) {
+        if (callback(block) === false) {
+          return false;
+        }
+
+        const children = reverse
+          ? block.children.slice().reverse()
+          : block.children;
+
+        if (!traverseBlockArray(children)) {
+          return false;
+        }
+      }
+
+      return true;
+    }
+
+    traverseBlockArray(blocks);
+  }
+
+  /**
+   * Inserts new blocks into the editor. If a block's `id` is undefined, BlockNote generates one automatically. Throws an
+   * error if the reference block could not be found.
+   * @param blocksToInsert An array of partial blocks that should be inserted.
+   * @param referenceBlock An identifier for an existing block, at which the new blocks should be inserted.
+   * @param placement Whether the blocks should be inserted just before, just after, or nested inside the
+   * `referenceBlock`.
+   */
+  public insertBlocks(
+    blocksToInsert: PartialBlock<BSchema, ISchema, SSchema>[],
+    referenceBlock: BlockIdentifier,
+    placement: "before" | "after" = "before",
+  ) {
+    return this.editor.transact((tr) =>
+      insertBlocks(tr, blocksToInsert, referenceBlock, placement),
+    );
+  }
+
+  /**
+   * Updates an existing block in the editor. Since updatedBlock is a PartialBlock object, some fields might not be
+   * defined. These undefined fields are kept as-is from the existing block. Throws an error if the block to update could
+   * not be found.
+   * @param blockToUpdate The block that should be updated.
+   * @param update A partial block which defines how the existing block should be changed.
+   */
+  public updateBlock(
+    blockToUpdate: BlockIdentifier,
+    update: PartialBlock<BSchema, ISchema, SSchema>,
+  ) {
+    return this.editor.transact((tr) => updateBlock(tr, blockToUpdate, update));
+  }
+
+  /**
+   * Removes existing blocks from the editor. Throws an error if any of the blocks could not be found.
+   * @param blocksToRemove An array of identifiers for existing blocks that should be removed.
+   */
+  public removeBlocks(blocksToRemove: BlockIdentifier[]) {
+    return this.editor.transact(
+      (tr) => removeAndInsertBlocks(tr, blocksToRemove, []).removedBlocks,
+    );
+  }
+
+  /**
+   * Replaces existing blocks in the editor with new blocks. If the blocks that should be removed are not adjacent or
+   * are at different nesting levels, `blocksToInsert` will be inserted at the position of the first block in
+   * `blocksToRemove`. Throws an error if any of the blocks to remove could not be found.
+   * @param blocksToRemove An array of blocks that should be replaced.
+   * @param blocksToInsert An array of partial blocks to replace the old ones with.
+   */
+  public replaceBlocks(
+    blocksToRemove: BlockIdentifier[],
+    blocksToInsert: PartialBlock<BSchema, ISchema, SSchema>[],
+  ) {
+    return this.editor.transact((tr) =>
+      removeAndInsertBlocks(tr, blocksToRemove, blocksToInsert),
+    );
+  }
+
+  /**
+   * Checks if the block containing the text cursor can be nested.
+   */
+  public canNestBlock() {
+    return canNestBlock(this.editor);
+  }
+
+  /**
+   * Nests the block containing the text cursor into the block above it.
+   */
+  public nestBlock() {
+    nestBlock(this.editor);
+  }
+
+  /**
+   * Checks if the block containing the text cursor is nested.
+   */
+  public canUnnestBlock() {
+    return canUnnestBlock(this.editor);
+  }
+
+  /**
+   * Lifts the block containing the text cursor out of its parent.
+   */
+  public unnestBlock() {
+    unnestBlock(this.editor);
+  }
+
+  /**
+   * Moves the selected blocks up. If the previous block has children, moves
+   * them to the end of its children. If there is no previous block, but the
+   * current blocks share a common parent, moves them out of & before it.
+   */
+  public moveBlocksUp() {
+    return moveBlocksUp(this.editor);
+  }
+
+  /**
+   * Moves the selected blocks down. If the next block has children, moves
+   * them to the start of its children. If there is no next block, but the
+   * current blocks share a common parent, moves them out of & after it.
+   */
+  public moveBlocksDown() {
+    return moveBlocksDown(this.editor);
+  }
+}

package/src/editor/managers/CollaborationManager.ts

@@ -0,0 +1,212 @@
+import * as Y from "yjs";
+import { redoCommand, undoCommand } from "y-prosemirror";
+import { CommentsPlugin } from "../../extensions/Comments/CommentsPlugin.js";
+import { CommentMark } from "../../extensions/Comments/CommentMark.js";
+import { ForkYDocPlugin } from "../../extensions/Collaboration/ForkYDocPlugin.js";
+import { SyncPlugin } from "../../extensions/Collaboration/SyncPlugin.js";
+import { UndoPlugin } from "../../extensions/Collaboration/UndoPlugin.js";
+import { CursorPlugin } from "../../extensions/Collaboration/CursorPlugin.js";
+import type { ThreadStore, User } from "../../comments/index.js";
+import type { BlockNoteEditor } from "../BlockNoteEditor.js";
+import { CustomBlockNoteSchema } from "../../schema/schema.js";
+
+export interface CollaborationOptions {
+  /**
+   * The Yjs XML fragment that's used for collaboration.
+   */
+  fragment: Y.XmlFragment;
+  /**
+   * The user info for the current user that's shown to other collaborators.
+   */
+  user: {
+    name: string;
+    color: string;
+  };
+  /**
+   * A Yjs provider (used for awareness / cursor information)
+   * Can be null for comments-only mode
+   */
+  provider: any;
+  /**
+   * Optional function to customize how cursors of users are rendered
+   */
+  renderCursor?: (user: any) => HTMLElement;
+  /**
+   * Optional flag to set when the user label should be shown with the default
+   * collaboration cursor. Setting to "always" will always show the label,
+   * while "activity" will only show the label when the user moves the cursor
+   * or types. Defaults to "activity".
+   */
+  showCursorLabels?: "always" | "activity";
+  /**
+   * Comments configuration - can be used with or without collaboration
+   */
+  comments?: {
+    schema?: CustomBlockNoteSchema<any, any, any>;
+    threadStore: ThreadStore;
+  };
+  /**
+   * Function to resolve user IDs to user objects - required for comments
+   */
+  resolveUsers?: (userIds: string[]) => Promise<User[]>;
+}
+
+/**
+ * CollaborationManager handles all collaboration-related functionality
+ * This manager is completely optional and can be tree-shaken if not used
+ */
+export class CollaborationManager {
+  private editor: BlockNoteEditor;
+  private options: CollaborationOptions;
+  private _commentsPlugin?: CommentsPlugin;
+  private _forkYDocPlugin?: ForkYDocPlugin;
+  private _syncPlugin?: SyncPlugin;
+  private _undoPlugin?: UndoPlugin;
+  private _cursorPlugin?: CursorPlugin;
+
+  constructor(editor: BlockNoteEditor, options: CollaborationOptions) {
+    this.editor = editor;
+    this.options = options;
+  }
+
+  /**
+   * Get the sync plugin instance
+   */
+  public get syncPlugin(): SyncPlugin | undefined {
+    return this._syncPlugin;
+  }
+
+  /**
+   * Get the undo plugin instance
+   */
+  public get undoPlugin(): UndoPlugin | undefined {
+    return this._undoPlugin;
+  }
+
+  /**
+   * Get the cursor plugin instance
+   */
+  public get cursorPlugin(): CursorPlugin | undefined {
+    return this._cursorPlugin;
+  }
+
+  /**
+   * Get the fork YDoc plugin instance
+   */
+  public get forkYDocPlugin(): ForkYDocPlugin | undefined {
+    return this._forkYDocPlugin;
+  }
+
+  // Initialize collaboration plugins
+  public initExtensions(): Record<string, unknown> {
+    // Only create collaboration plugins when real-time collaboration is enabled
+    const extensions: Record<string, unknown> = {};
+
+    // Initialize sync plugin
+    this._syncPlugin = new SyncPlugin(this.options.fragment);
+    extensions.ySyncPlugin = this._syncPlugin;
+
+    // Initialize undo plugin
+    this._undoPlugin = new UndoPlugin({ editor: this.editor });
+    extensions.yUndoPlugin = this._undoPlugin;
+
+    // Initialize cursor plugin if provider has awareness
+    if (this.options.provider?.awareness) {
+      this._cursorPlugin = new CursorPlugin(this.options);
+      extensions.yCursorPlugin = this._cursorPlugin;
+    }
+
+    // Initialize fork YDoc plugin
+    this._forkYDocPlugin = new ForkYDocPlugin({
+      editor: this.editor,
+      collaboration: this.options,
+    });
+    extensions.forkYDocPlugin = this._forkYDocPlugin;
+
+    if (this.options.comments) {
+      if (!this.options.resolveUsers) {
+        throw new Error("resolveUsers is required when using comments");
+      }
+
+      // Create CommentsPlugin instance and add it to editor extensions
+      this._commentsPlugin = new CommentsPlugin(
+        this.editor,
+        this.options.comments.threadStore,
+        CommentMark.name,
+        this.options.resolveUsers,
+        this.options.comments.schema,
+      );
+
+      // Add the comments plugin to the editor's extensions
+      extensions.comments = this._commentsPlugin;
+      extensions.commentMark = CommentMark;
+    }
+    return extensions;
+  }
+
+  /**
+   * Update the user info for the current user that's shown to other collaborators
+   */
+  public updateUserInfo(user: { name: string; color: string }) {
+    const cursor = this.cursorPlugin;
+    if (!cursor) {
+      throw new Error(
+        "Cannot update collaboration user info when collaboration is disabled.",
+      );
+    }
+    cursor.updateUser(user);
+  }
+
+  /**
+   * Get the collaboration undo command
+   */
+  public getUndoCommand() {
+    return undoCommand;
+  }
+
+  /**
+   * Get the collaboration redo command
+   */
+  public getRedoCommand() {
+    return redoCommand;
+  }
+
+  /**
+   * Check if initial content should be avoided due to collaboration
+   */
+  public shouldAvoidInitialContent(): boolean {
+    // Only avoid initial content when real-time collaboration is enabled
+    // (i.e., when we have a provider)
+    return !!this.options.provider;
+  }
+
+  /**
+   * Get the collaboration options
+   */
+  public getOptions(): CollaborationOptions {
+    return this.options;
+  }
+
+  /**
+   * Get the comments plugin if available
+   */
+  public get comments(): CommentsPlugin | undefined {
+    return this._commentsPlugin;
+  }
+
+  /**
+   * Check if comments are enabled
+   */
+  public get hasComments(): boolean {
+    return !!this.options.comments;
+  }
+
+  /**
+   * Get the resolveUsers function
+   */
+  public get resolveUsers():
+    | ((userIds: string[]) => Promise<User[]>)
+    | undefined {
+    return this.options.resolveUsers;
+  }
+}

package/src/editor/managers/EventManager.ts

@@ -0,0 +1,134 @@
+import type { BlockNoteEditor } from "../BlockNoteEditor.js";
+import {
+  getBlocksChangedByTransaction,
+  type BlocksChanged,
+} from "../../api/getBlocksChangedByTransaction.js";
+import { Transaction } from "prosemirror-state";
+import { EventEmitter } from "../../util/EventEmitter.js";
+
+/**
+ * A function that can be used to unsubscribe from an event.
+ */
+export type Unsubscribe = () => void;
+
+/**
+ * EventManager is a class which manages the events of the editor
+ */
+export class EventManager<Editor extends BlockNoteEditor> extends EventEmitter<{
+  onChange: [
+    editor: Editor,
+    ctx: {
+      getChanges(): BlocksChanged<
+        Editor["schema"]["blockSchema"],
+        Editor["schema"]["inlineContentSchema"],
+        Editor["schema"]["styleSchema"]
+      >;
+    },
+  ];
+  onSelectionChange: [ctx: { editor: Editor; transaction: Transaction }];
+  onMount: [ctx: { editor: Editor }];
+  onUnmount: [ctx: { editor: Editor }];
+}> {
+  constructor(private editor: Editor) {
+    super();
+    // We register tiptap events only once the editor is finished initializing
+    // otherwise we would be trying to register events on a tiptap editor which does not exist yet
+    editor.onCreate(() => {
+      editor._tiptapEditor.on(
+        "update",
+        ({ transaction, appendedTransactions }) => {
+          this.emit("onChange", editor, {
+            getChanges() {
+              return getBlocksChangedByTransaction(
+                transaction,
+                appendedTransactions,
+              );
+            },
+          });
+        },
+      );
+      editor._tiptapEditor.on("selectionUpdate", ({ transaction }) => {
+        this.emit("onSelectionChange", { editor, transaction });
+      });
+      editor._tiptapEditor.on("mount", () => {
+        this.emit("onMount", { editor });
+      });
+      editor._tiptapEditor.on("unmount", () => {
+        this.emit("onUnmount", { editor });
+      });
+    });
+  }
+
+  /**
+   * Register a callback that will be called when the editor changes.
+   */
+  public onChange(
+    callback: (
+      editor: Editor,
+      ctx: {
+        getChanges(): BlocksChanged<
+          Editor["schema"]["blockSchema"],
+          Editor["schema"]["inlineContentSchema"],
+          Editor["schema"]["styleSchema"]
+        >;
+      },
+    ) => void,
+  ): Unsubscribe {
+    this.on("onChange", callback);
+
+    return () => {
+      this.off("onChange", callback);
+    };
+  }
+
+  /**
+   * Register a callback that will be called when the selection changes.
+   */
+  public onSelectionChange(
+    callback: (editor: Editor) => void,
+    /**
+     * If true, the callback will be triggered when the selection changes due to a yjs sync (i.e.: other user was typing)
+     */
+    includeSelectionChangedByRemote = false,
+  ): Unsubscribe {
+    const cb = (e: { transaction: Transaction }) => {
+      if (
+        e.transaction.getMeta("$y-sync") &&
+        !includeSelectionChangedByRemote
+      ) {
+        // selection changed because of a yjs sync (i.e.: other user was typing)
+        // we don't want to trigger the callback in this case
+        return;
+      }
+      callback(this.editor);
+    };
+
+    this.on("onSelectionChange", cb);
+
+    return () => {
+      this.off("onSelectionChange", cb);
+    };
+  }
+
+  /**
+   * Register a callback that will be called when the editor is mounted.
+   */
+  public onMount(callback: (ctx: { editor: Editor }) => void): Unsubscribe {
+    this.on("onMount", callback);
+
+    return () => {
+      this.off("onMount", callback);
+    };
+  }
+
+  /**
+   * Register a callback that will be called when the editor is unmounted.
+   */
+  public onUnmount(callback: (ctx: { editor: Editor }) => void): Unsubscribe {
+    this.on("onUnmount", callback);
+
+    return () => {
+      this.off("onUnmount", callback);
+    };
+  }
+}