Added BlockIdentifier & small changes (#112)

* Added BlockIdentifier & small changes

* `getBlocks()` now returns undefined when the block isn't found.

* Fixed build error

---------

Co-authored-by: Matthew Lipski <[email protected]>

Author: YousefED

examples/vanilla/src/main.tsx

@@ -18,7 +18,7 @@ const editor = new BlockNoteEditor({
     blockSideMenuFactory,
   },
   onUpdate: () => {
-    console.log(editor.allBlocks);
+    console.log(editor.topLevelBlocks);
   },
   editorDOMAttributes: {
     class: "editor",

packages/core/src/api/Editor.ts

@@ -1,7 +1,11 @@
 import { Editor as TiptapEditor } from "@tiptap/core";
 import { Node } from "prosemirror-model";
 import { getBlockInfoFromPos } from "../extensions/Blocks/helpers/getBlockInfoFromPos";
-import { Block, PartialBlock } from "../extensions/Blocks/api/blockTypes";
+import {
+  Block,
+  BlockIdentifier,
+  PartialBlock,
+} from "../extensions/Blocks/api/blockTypes";
 import { TextCursorPosition } from "../extensions/Blocks/api/cursorPositionTypes";
 import { nodeToBlock } from "./nodeConversions/nodeConversions";
 import {
@@ -24,7 +28,8 @@ export class Editor {
   ) {}
 
   /**
-   * Gets a list of all top-level blocks that are in the editor.
+   * Gets a snapshot of all top-level blocks that are in the editor.
+   * @returns An array containing a snapshot of all top-level (non-nested) blocks in the editor.
    */
   public get topLevelBlocks(): Block[] {
     const blocks: Block[] = [];
@@ -38,26 +43,73 @@ export class Editor {
     return blocks;
   }
 
+  /**
+   * Retrieves a snapshot of an existing block from the editor.
+   * @param block 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(block: BlockIdentifier): Block | undefined {
+    const id = typeof block === "string" ? block : block.id;
+    let newBlock: Block | undefined = undefined;
+
+    this.tiptapEditor.state.doc.firstChild!.descendants((node) => {
+      if (typeof newBlock !== "undefined") {
+        return false;
+      }
+
+      if (node.type.name !== "blockContainer" || node.attrs.id !== id) {
+        return true;
+      }
+
+      newBlock = nodeToBlock(node, this.blockCache);
+
+      return false;
+    });
+
+    return newBlock;
+  }
+
   /**
    * Traverses all blocks in the editor, including all nested blocks, and executes a callback for each. The traversal is
-   * depth-first, which is the same order as blocks appear in the editor by y-coordinate.
+   * depth-first, which is the same order as blocks appear in the editor by y-coordinate. Stops traversal if the callback
+   * returns false;
    * @param callback The callback to execute for each block.
    * @param reverse Whether the blocks should be traversed in reverse order.
    */
-  public allBlocks(
-    callback: (block: Block) => void,
+  public forEachBlock(
+    callback: (block: Block) => boolean,
     reverse: boolean = false
   ): void {
+    let stop = false;
+
     function helper(blocks: Block[]) {
       if (reverse) {
         for (const block of blocks.reverse()) {
           helper(block.children);
-          callback(block);
+
+          if (stop) {
+            return;
+          }
+
+          stop = !callback(block);
+
+          if (stop) {
+            return;
+          }
         }
       } else {
         for (const block of blocks) {
-          callback(block);
+          stop = !callback(block);
+
+          if (stop) {
+            return;
+          }
+
           helper(block.children);
+
+          if (stop) {
+            return;
+          }
         }
       }
     }
@@ -66,7 +118,8 @@ export class Editor {
   }
 
   /**
-   * Gets information regarding the position of the text cursor in the editor.
+   * Gets a snapshot of the text cursor position within the editor.
+   * @returns A snapshot of the text cursor position.
    */
   public get textCursorPosition(): TextCursorPosition {
     const { node } = getBlockInfoFromPos(
@@ -124,7 +177,7 @@ export class Editor {
   }
 
   /**
-   * Executes a callback function whenever the editor's content changes.
+   * Executes a callback function whenever the editor's contents change.
    * @param callback The callback function to execute.
    */
   public onContentChange(callback: () => void) {
@@ -136,6 +189,7 @@ export class Editor {
    * is simplified in order to better conform to HTML standards. Block structuring elements are removed, children of
    * blocks which aren't list items are lifted out of them, and list items blocks are wrapped in `ul`/`ol` tags.
    * @param blocks The list of blocks to serialize into HTML.
+   * @returns An HTML representation of the blocks.
    */
   public async blocksToHTML(blocks: Block[]): Promise<string> {
     return blocksToHTML(blocks, this.tiptapEditor.schema);
@@ -144,6 +198,7 @@ export class Editor {
   /**
    * Creates a list of blocks from an HTML string.
    * @param htmlString The HTML string to create a list of blocks from.
+   * @returns A list of blocks parsed from the HTML string.
    */
   public async HTMLToBlocks(htmlString: string): Promise<Block[]> {
     return HTMLToBlocks(htmlString, this.tiptapEditor.schema);
@@ -152,8 +207,9 @@ export class Editor {
   /**
    * Serializes a list of blocks into a Markdown string. The output is simplified as Markdown does not support all
    * features of BlockNote. Block structuring elements are removed, children of blocks which aren't list items are
-   * lifted out of them, and certain styles are removed.
+   * un-nested, and certain styles are removed.
    * @param blocks The list of blocks to serialize into Markdown.
+   * @returns A Markdown representation of the blocks.
    */
   public async blocksToMarkdown(blocks: Block[]): Promise<string> {
     return blocksToMarkdown(blocks, this.tiptapEditor.schema);
@@ -162,6 +218,7 @@ export class Editor {
   /**
    * Creates a list of blocks from a Markdown string.
    * @param markdownString The Markdown string to create a list of blocks from.
+   * @returns A list of blocks parsed from the Markdown string.
    */
   public async markdownToBlocks(markdownString: string): Promise<Block[]> {
     return markdownToBlocks(markdownString, this.tiptapEditor.schema);

packages/core/src/api/blockManipulation/blockManipulation.ts

@@ -1,26 +1,29 @@
 import { Editor } from "@tiptap/core";
 import { Node } from "prosemirror-model";
-import { Block, PartialBlock } from "../../extensions/Blocks/api/blockTypes";
+import {
+  BlockIdentifier,
+  PartialBlock,
+} from "../../extensions/Blocks/api/blockTypes";
 import { blockToNode } from "../nodeConversions/nodeConversions";
 import { getNodeById } from "../util/nodeUtil";
 
 export function insertBlocks(
   blocksToInsert: PartialBlock[],
-  blockToInsertAt: Block,
+  referenceBlock: BlockIdentifier,
   placement: "before" | "after" | "nested" = "before",
   editor: Editor
 ): void {
+  const id =
+    typeof referenceBlock === "string" ? referenceBlock : referenceBlock.id;
+
   const nodesToInsert: Node[] = [];
   for (const blockSpec of blocksToInsert) {
     nodesToInsert.push(blockToNode(blockSpec, editor.schema));
   }
 
   let insertionPos = -1;
 
-  const { node, posBeforeNode } = getNodeById(
-    blockToInsertAt.id,
-    editor.state.doc
-  );
+  const { node, posBeforeNode } = getNodeById(id, editor.state.doc);
 
   if (placement === "before") {
     insertionPos = posBeforeNode;
@@ -54,18 +57,25 @@ export function insertBlocks(
 }
 
 export function updateBlock(
-  blockToUpdate: Block,
-  updatedBlock: PartialBlock,
+  blockToUpdate: BlockIdentifier,
+  update: PartialBlock,
   editor: Editor
 ) {
-  const { posBeforeNode } = getNodeById(blockToUpdate.id, editor.state.doc);
+  const id =
+    typeof blockToUpdate === "string" ? blockToUpdate : blockToUpdate.id;
+  const { posBeforeNode } = getNodeById(id, editor.state.doc);
 
-  editor.commands.BNUpdateBlock(posBeforeNode + 1, updatedBlock);
+  editor.commands.BNUpdateBlock(posBeforeNode + 1, update);
 }
 
-export function removeBlocks(blocksToRemove: Block[], editor: Editor) {
+export function removeBlocks(
+  blocksToRemove: BlockIdentifier[],
+  editor: Editor
+) {
   const idsOfBlocksToRemove = new Set<string>(
-    blocksToRemove.map((block) => block.id)
+    blocksToRemove.map((block) =>
+      typeof block === "string" ? block : block.id
+    )
   );
 
   let removedSize = 0;
@@ -106,7 +116,7 @@ export function removeBlocks(blocksToRemove: Block[], editor: Editor) {
 }
 
 export function replaceBlocks(
-  blocksToRemove: Block[],
+  blocksToRemove: BlockIdentifier[],
   blocksToInsert: PartialBlock[],
   editor: Editor
 ) {

packages/core/src/extensions/Blocks/api/blockTypes.ts

@@ -45,6 +45,8 @@ export type Block =
   | BulletListItemBlock
   | NumberedListItemBlock;
 
+export type BlockIdentifier = string | Block;
+
 /** Define "Partial Blocks", these are for updating or creating blocks */
 export type PartialBlockTemplate<B extends Block> = B extends Block
   ? Partial<Omit<B, "props" | "children" | "content" | "type">> & {