feat: Better selections and moving multiple blocks

docs/pages/docs/editor-api/cursor-selections.mdx

@@ -87,6 +87,23 @@ const selection = editor.getSelection();
 
 `returns:` A snapshot of the current selection, or `undefined` if no selection is active.
 
+### Setting Selection
+
+You update the selection to span from one block to another using the following call:
+
+```typescript
+setSelection(startBlock: BlockIdentifier, endBlock: BlockIdentifier): void;
+
+// Usage
+editor.setSelection(startBlockIdentifier, endBlockIdentifier);
+```
+
+`startBlock:` The [identifier](/docs/editor-api/manipulating-blocks#block-identifiers) of the block where the selection should start.
+
+`endBlock:` The [identifier](/docs/editor-api/manipulating-blocks#block-identifiers) of the block where the selection should end.
+
+Both `startBlock` and `endBlock` must point to a block with content. The updated selection will span from the start of the first block to the end of the last block.
+
 ## Getting Selected Blocks
 
 The demo below displays the blocks in the current [selection](/docs/editor-api/cursor-selections#selections) as JSON below the editor. If a selection isn't active, it displays the block containing the [text cursor](/docs/editor-api/cursor-selections#text-cursor) instead.

docs/pages/docs/editor-api/manipulating-blocks.mdx

@@ -10,12 +10,17 @@ path: /docs/manipulating-blocks
 Below, we explain the methods on `editor` you can use to read Blocks from the editor, and how to create / remove / update Blocks:
 
 - [`get document`](/docs/editor-api/manipulating-blocks#getting-the-document)
-- [`getBlock`](/docs/editor-api/manipulating-blocks#getting-a-specific-block)
+- [`getBlock`](/docs/editor-api/manipulating-blocks#single-specific-block)
+- [`getPrevBlock`](/docs/editor-api/manipulating-blocks#previous-block)
+- [`getNextBlock`](/docs/editor-api/manipulating-blocks#next-block)
+- [`getParentBlock`](/docs/editor-api/manipulating-blocks#parent-block)
 - [`forEachBlock`](/docs/editor-api/manipulating-blocks#traversing-all-blocks)
 - [`insertBlocks`](/docs/editor-api/manipulating-blocks#inserting-new-blocks)
 - [`updateBlock`](/docs/editor-api/manipulating-blocks#updating-blocks)
 - [`removeBlocks`](/docs/editor-api/manipulating-blocks#removing-blocks)
 - [`replaceBlocks`](/docs/editor-api/manipulating-blocks#replacing-blocks)
+- [`moveBlocksUp`](/docs/editor-api/manipulating-blocks#moving-up)
+- [`moveBlocksDown`](/docs/editor-api/manipulating-blocks#moving-down)
 - [`canNestBlock`](/docs/editor-api/manipulating-blocks#nesting-blocks)
 - [`nestBlock`](/docs/editor-api/manipulating-blocks#nesting-blocks)
 - [`canUnnestBlock`](/docs/editor-api/manipulating-blocks#un-nesting-blocks)
@@ -70,7 +75,9 @@ const blocks = editor.document;
 
 We already used this for the [Document JSON](/docs/editor-basics/document-structure#document-json) demo.
 
-### Getting a Specific Block
+### Getting Specific Blocks
+
+#### Single Specific Block
 
 Use `getBlock` to retrieve a snapshot of a specific block in the editor:
 
@@ -85,6 +92,51 @@ const block = editor.getBlock(blockIdentifier);
 
 `returns:` The block that matches the identifier, or `undefined` if no matching block was found.
 
+#### Previous Block
+
+Use `getPrevBlock` to retrieve a snapshot of a block's previous sibling in the editor:
+
+```typescript
+getPrevBlock(blockIdentifier: BlockIdentifier): Block | undefined;
+
+// Usage
+const prevBlock = editor.getPrevBlock(blockIdentifier);
+```
+
+`blockIdentifier:` The [identifier](/docs/editor-api/manipulating-blocks#block-identifiers) of an existing block for which the previous sibling should be retrieved.
+
+`returns:` The previous sibling of the block that matches the identifier, or `undefined` if no matching block was found. Also `undefined` when the matching block is the first in the document, or the first child of a parent block.
+
+#### Next Block
+
+Use `getNextBlock` to retrieve a snapshot of a block's next sibling in the editor:
+
+```typescript
+getNextBlock(blockIdentifier: BlockIdentifier): Block | undefined;
+
+// Usage
+const nextBlock = editor.getNextBlock(blockIdentifier);
+```
+
+`blockIdentifier:` The [identifier](/docs/editor-api/manipulating-blocks#block-identifiers) of an existing block for which the next sibling should be retrieved.
+
+`returns:` The next sibling of the block that matches the identifier, or `undefined` if no matching block was found. Also `undefined` when the matching block is the last in the document, or the last child of a parent block.
+
+#### Parent Block
+
+Use `getParentBlock` to retrieve a snapshot of a block's parent in the editor:
+
+```typescript
+getParentBlock(blockIdentifier: BlockIdentifier): Block | undefined;
+
+// Usage
+const parentBlock = editor.getParentBlock(blockIdentifier);
+```
+
+`blockIdentifier:` The [identifier](/docs/editor-api/manipulating-blocks#block-identifiers) of an existing block for which the parent should be retrieved.
+
+`returns:` The parent of the block that matches the identifier, or `undefined` if no matching block was found. Also `undefined` when the matching block is not nested in a parent block.
+
 ### Traversing All Blocks
 
 Use `forEachBlock` to traverse all blocks in the editor depth-first, and execute a callback for each block:
@@ -193,6 +245,30 @@ If the blocks that should be removed are not adjacent or are at different nestin
 
 Throws an error if any of the blocks to remove could not be found.
 
+## Moving Blocks Up/Down
+
+### Moving Up
+
+Use `moveBlocksUp` to move the selected blocks up:
+
+```typescript
+moveBlocksUp(): void;
+
+// Usage
+editor.moveBlocksUp();
+```
+
+### Moving Down
+
+Use `moveBlocksDown` to move the selected blocks down:
+
+```typescript
+moveBlocksDown(): void;
+
+// Usage
+editor.moveBlocksDown();
+```
+
 ## Nesting & Un-nesting Blocks
 
 BlockNote also provides functions to nest & un-nest the block containing the [Text Cursor](/docs/editor-api/cursor-selections#text-cursor).

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

@@ -32,23 +32,23 @@ export function insertBlocks<
     );
   }
 
-  const { node, posBeforeNode } = getNodeById(
-    id,
-    editor._tiptapEditor.state.doc
-  );
+  const posInfo = getNodeById(id, editor._tiptapEditor.state.doc);
+  if (!posInfo) {
+    throw new Error(`Block with ID ${id} not found`);
+  }
 
   // TODO: we might want to use the ReplaceStep directly here instead of insert,
   // because the fitting algorithm should not be necessary and might even cause unexpected behavior
   if (placement === "before") {
     editor.dispatch(
-      editor._tiptapEditor.state.tr.insert(posBeforeNode, nodesToInsert)
+      editor._tiptapEditor.state.tr.insert(posInfo.posBeforeNode, nodesToInsert)
     );
   }
 
   if (placement === "after") {
     editor.dispatch(
       editor._tiptapEditor.state.tr.insert(
-        posBeforeNode + node.nodeSize,
+        posInfo.posBeforeNode + posInfo.node.nodeSize,
         nodesToInsert
       )
     );