refactor(core): simplify the BlockInfo API into a single vocabulary for block plumbing

docs/content/docs/reference/editor/manipulating-content.mdx

@@ -141,11 +141,11 @@ editor.forEachBlock((block) => {
 insertBlocks(
   blocksToInsert: PartialBlock[],
   referenceBlock: BlockIdentifier,
-  placement: "before" | "after" = "before"
+  placement: "before" | "after" | "first-child" | "last-child" = "before"
 ): void
 ```
 
-Inserts new blocks relative to an existing block.
+Inserts new blocks relative to an existing block. `"before"` and `"after"` make the new blocks siblings of the reference block; `"first-child"` and `"last-child"` nest them inside it.
 
 ```typescript
 // Insert a paragraph before an existing block
@@ -164,6 +164,13 @@ editor.insertBlocks(
   "existing-block-id",
   "after",
 );
+
+// Insert a paragraph as the last child of an existing block
+editor.insertBlocks(
+  [{ type: "paragraph", content: "Nested paragraph" }],
+  "existing-block-id",
+  "last-child",
+);
 ```
 
 ### Updating Blocks

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

@@ -1,4 +1,4 @@
-import { Fragment, Slice } from "prosemirror-model";
+import { Fragment, Node, NodeType, Slice } from "prosemirror-model";
 import type { Transaction } from "prosemirror-state";
 import { ReplaceStep } from "prosemirror-transform";
 import { Block, PartialBlock } from "../../../../blocks/defaultBlocks.js";
@@ -8,11 +8,122 @@ import {
   InlineContentSchema,
   StyleSchema,
 } from "../../../../schema/index.js";
+import {
+  BlockInfo,
+  getBlockInfoFromNode,
+} from "../../../getBlockInfoFromPos.js";
 import { blockToNode } from "../../../nodeConversions/blockToNode.js";
 import { nodeToBlock } from "../../../nodeConversions/nodeToBlock.js";
 import { getNodeById } from "../../../nodeUtil.js";
 import { getPmSchema } from "../../../pmUtil.js";
 
+/**
+ * Where blocks go relative to a reference block. `"before"`/`"after"` make
+ * them siblings of it; `"first-child"`/`"last-child"` nest them inside it.
+ *
+ * The nested placements also cover blocks that have no children to point at:
+ * a regular block's `blockGroup` is lazy (`blockContent blockGroup?`), so a
+ * block without children has no child block to insert before or after.
+ */
+export type BlockPlacement = "before" | "after" | "first-child" | "last-child";
+
+/**
+ * Walks one edge of a block's children, descending through nested
+ * child-holding wrapper blocks (e.g. a Column inside a ColumnList), to the
+ * deepest position where `nodeType` fits. `edge` picks the trailing edge
+ * (where a new last child goes) or the leading edge.
+ */
+function descendToInsertionPos(
+  info: BlockInfo,
+  nodeType: NodeType,
+  edge: "first" | "last",
+): { pos: number } | { pos?: undefined; blockedBy: "schema" } {
+  const children = info.children;
+  if (!children) {
+    return { blockedBy: "schema" };
+  }
+
+  const last = edge === "last";
+  const index = last ? children.node.childCount : 0;
+  // `canReplaceWith` rather than a bare content match: the children already
+  // after the position have to still fit once the new node is spliced in.
+  if (children.node.canReplaceWith(index, index, nodeType)) {
+    return { pos: last ? children.childrenEnd : children.childrenStart };
+  }
+
+  const child = last ? children.node.lastChild : children.node.firstChild;
+  if (
+    !child ||
+    !(child.type.isInGroup("bnBlock") && child.type.isInGroup("childContainer"))
+  ) {
+    return { blockedBy: "schema" };
+  }
+  return descendToInsertionPos(
+    getBlockInfoFromNode(
+      child,
+      last ? children.childrenEnd - child.nodeSize : children.childrenStart,
+    ),
+    nodeType,
+    edge,
+  );
+}
+
+/**
+ * Resolves a `placement` against a reference block into the document position
+ * a node of `nodeType` should be inserted at, or `null` when the reference
+ * block cannot take it there.
+ *
+ * Shared by `insertBlocks` and the move commands, so "does this block fit
+ * here?" is answered in one place. The answer comes from the schema's content
+ * matches rather than from a hand-written rule.
+ *
+ * `wrapIn` is set when the position only becomes valid once the nodes are
+ * wrapped: a regular block with no children yet has no `blockGroup` for them
+ * to go in, so one is created around them.
+ */
+export function getInsertionPos(
+  doc: Node,
+  reference: { node: Node; posBeforeNode: number },
+  placement: BlockPlacement,
+  nodeType: NodeType,
+): { pos: number; wrapIn?: NodeType } | null {
+  const { node, posBeforeNode } = reference;
+
+  if (placement === "before" || placement === "after") {
+    const pos =
+      placement === "before" ? posBeforeNode : posBeforeNode + node.nodeSize;
+    const $pos = doc.resolve(pos);
+
+    // `canReplaceWith` rather than a bare content match: the nodes already
+    // after the position have to still fit once the new one is spliced in.
+    return $pos.parent.canReplaceWith($pos.index(), $pos.index(), nodeType)
+      ? { pos }
+      : null;
+  }
+
+  const info = getBlockInfoFromNode(node, posBeforeNode);
+
+  if (info.children) {
+    const { pos } = descendToInsertionPos(
+      info,
+      nodeType,
+      placement === "first-child" ? "first" : "last",
+    );
+
+    return pos === undefined ? null : { pos };
+  }
+
+  // No children holder implies a `blockContainer` with no children yet: its
+  // `blockGroup` is lazy (`blockContent blockGroup?`), so the position after
+  // the content node only becomes valid once the nodes are wrapped in a new
+  // group.
+  const blockGroupType = nodeType.schema.nodes["blockGroup"];
+
+  return info.hasContent && blockGroupType?.contentMatch.matchType(nodeType)
+    ? { pos: info.content.afterPos, wrapIn: blockGroupType }
+    : null;
+}
+
 export function insertBlocks<
   BSchema extends BlockSchema,
   I extends InlineContentSchema,
@@ -21,7 +132,7 @@ export function insertBlocks<
   tr: Transaction,
   blocksToInsert: PartialBlock<BSchema, I, S>[],
   referenceBlock: BlockIdentifier,
-  placement: "before" | "after" = "before",
+  placement: BlockPlacement = "before",
 ): Block<BSchema, I, S>[] {
   const id =
     typeof referenceBlock === "string" ? referenceBlock : referenceBlock.id;
@@ -37,14 +148,47 @@ export function insertBlocks<
     throw new Error(`Block with ID ${id} not found`);
   }
 
-  let pos = posInfo.posBeforeNode;
-  if (placement === "after") {
-    pos += posInfo.node.nodeSize;
+  if (nodesToInsert.length === 0) {
+    return [];
   }
 
-  tr.step(
-    new ReplaceStep(pos, pos, new Slice(Fragment.from(nodesToInsert), 0, 0)),
+  const target = getInsertionPos(
+    tr.doc,
+    posInfo,
+    placement,
+    nodesToInsert[0].type,
   );
+  if (!target) {
+    throw new Error(
+      `Cannot insert blocks at "${placement}" of block "${id}": no valid position for them`,
+    );
+  }
+
+  // `getInsertionPos` can only answer for the first node's type: the fragment
+  // doesn't exist yet when it runs. The whole fragment still has to fit, so it
+  // is checked here, where the nodes are known, rather than left to `tr.step`
+  // to reject with a ProseMirror-level message.
+  if (
+    target.wrapIn &&
+    !target.wrapIn.validContent(Fragment.from(nodesToInsert))
+  ) {
+    throw new Error(
+      `Cannot insert blocks at "${placement}" of block "${id}": a "${target.wrapIn.name}" doesn't accept them`,
+    );
+  }
+
+  const fragment = target.wrapIn
+    ? Fragment.from(target.wrapIn.create(null, nodesToInsert))
+    : Fragment.from(nodesToInsert);
+
+  const $target = tr.doc.resolve(target.pos);
+  if (!$target.parent.canReplace($target.index(), $target.index(), fragment)) {
+    throw new Error(
+      `Cannot insert blocks at "${placement}" of block "${id}": a "${$target.parent.type.name}" doesn't accept them`,
+    );
+  }
+
+  tr.step(new ReplaceStep(target.pos, target.pos, new Slice(fragment, 0, 0)));
 
   // Now that the `PartialBlock`s have been converted to nodes, we can
   // re-convert them into full `Block`s.

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

@@ -0,0 +1,113 @@
+// @vitest-environment node
+import {
+  afterAll,
+  beforeAll,
+  beforeEach,
+  describe,
+  expect,
+  it,
+} from "vite-plus/test";
+
+import { BlockNoteEditor } from "../../../../editor/BlockNoteEditor.js";
+
+let editor: BlockNoteEditor<any, any, any>;
+
+beforeAll(() => {
+  editor = BlockNoteEditor.create() as any;
+});
+
+afterAll(() => {
+  editor._tiptapEditor.destroy();
+  editor = undefined as any;
+});
+
+beforeEach(() => {
+  editor.replaceBlocks(editor.document, [
+    { id: "p-0", type: "paragraph", content: "Paragraph 0" },
+  ]);
+});
+
+describe('insertBlocks "first-child" / "last-child"', () => {
+  it("nests under a childless block, creating the blockGroup", () => {
+    expect(editor.getBlock("p-0")!.children).toHaveLength(0);
+
+    editor.insertBlocks(
+      [{ id: "first", type: "paragraph" }],
+      "p-0",
+      "first-child",
+    );
+    editor.insertBlocks(
+      [{ id: "last", type: "paragraph" }],
+      "p-0",
+      "last-child",
+    );
+
+    expect(editor.getBlock("p-0")!.children.map((child) => child.id)).toEqual([
+      "first",
+      "last",
+    ]);
+  });
+
+  it("prepends and appends around existing children", () => {
+    editor.replaceBlocks(editor.document, [
+      {
+        id: "p-0",
+        type: "paragraph",
+        content: "Paragraph 0",
+        children: [{ id: "existing", type: "paragraph", content: "Existing" }],
+      },
+    ]);
+
+    editor.insertBlocks(
+      [{ id: "first", type: "paragraph" }],
+      "p-0",
+      "first-child",
+    );
+    editor.insertBlocks(
+      [{ id: "last", type: "paragraph" }],
+      "p-0",
+      "last-child",
+    );
+
+    expect(editor.getBlock("p-0")!.children.map((child) => child.id)).toEqual([
+      "first",
+      "existing",
+      "last",
+    ]);
+  });
+
+  it("still inserts siblings with the default and explicit placements", () => {
+    editor.insertBlocks([{ id: "after", type: "paragraph" }], "p-0");
+    editor.insertBlocks([{ id: "before", type: "paragraph" }], "p-0", "before");
+    editor.insertBlocks([{ id: "sibling", type: "paragraph" }], "p-0", "after");
+
+    expect(editor.document.map((block) => block.id)).toEqual([
+      "after",
+      "before",
+      "p-0",
+      "sibling",
+    ]);
+  });
+
+  it("still inserts a batch that fits in full", () => {
+    editor.insertBlocks(
+      [
+        { id: "one", type: "paragraph" },
+        { id: "two", type: "paragraph" },
+      ],
+      "p-0",
+      "last-child",
+    );
+
+    expect(editor.getBlock("p-0")!.children.map((child) => child.id)).toEqual([
+      "one",
+      "two",
+    ]);
+  });
+
+  it("throws when the reference block does not exist", () => {
+    expect(() =>
+      editor.insertBlocks([{ type: "paragraph" }], "missing-id", "last-child"),
+    ).toThrow(/Block with ID missing-id not found/);
+  });
+});

packages/core/src/api/blockManipulation/commands/mergeBlocks/mergeBlocks.test.ts

@@ -2,7 +2,8 @@ import { describe, expect, it } from "vite-plus/test";
 
 import { getBlockInfoFromSelection } from "../../../getBlockInfoFromPos.js";
 import { setupTestEnv } from "../../setupTestEnv.js";
-import { getParentBlockInfo, mergeBlocksCommand } from "./mergeBlocks.js";
+import { getParentBlockInfo } from "../../../getBlockInfoFromPos.js";
+import { mergeBlocksCommand } from "./mergeBlocks.js";
 
 const getEditor = setupTestEnv();
 
@@ -14,7 +15,7 @@ function mergeBlocks(posBetweenBlocks: number) {
 
 function getPosBeforeSelectedBlock() {
   return getEditor().transact(
-    (tr) => getBlockInfoFromSelection(tr).bnBlock.beforePos,
+    (tr) => getBlockInfoFromSelection(tr).block.beforePos,
   );
 }