feat: introduce location based apis

nperez0111 · nperez0111 · commit daf8d98bb92d · 2025-09-29T16:10:42.000+02:00
diff --git a/packages/core/src/api/blockManipulation/commands/replaceBlocks/replaceBlocks.ts b/packages/core/src/api/blockManipulation/commands/replaceBlocks/replaceBlocks.ts
@@ -2,22 +2,23 @@ import type { Node } from "prosemirror-model";
 import type { Transaction } from "prosemirror-state";
 import type { Block, PartialBlock } from "../../../../blocks/defaultBlocks.js";
 import type {
-  BlockIdentifier,
   BlockSchema,
   InlineContentSchema,
   StyleSchema,
 } from "../../../../schema/index.js";
 import { blockToNode } from "../../../nodeConversions/blockToNode.js";
 import { nodeToBlock } from "../../../nodeConversions/nodeToBlock.js";
 import { getPmSchema } from "../../../pmUtil.js";
+import { Location } from "../../../../locations/types.js";
+import { getBlockRange } from "../../../../locations/utils.js";
 
 export function removeAndInsertBlocks<
   BSchema extends BlockSchema,
   I extends InlineContentSchema,
   S extends StyleSchema,
 >(
   tr: Transaction,
-  blocksToRemove: BlockIdentifier[],
+  blocksToRemove: Location[],
   blocksToInsert: PartialBlock<BSchema, I, S>[],
 ): {
   insertedBlocks: Block<BSchema, I, S>[];
@@ -30,17 +31,12 @@ export function removeAndInsertBlocks<
     blockToNode(block, pmSchema),
   );
 
+  const [insertionBlockId] = getBlockRange(blocksToRemove[0]);
   const idsOfBlocksToRemove = new Set<string>(
-    blocksToRemove.map((block) =>
-      typeof block === "string" ? block : block.id,
-    ),
+    blocksToRemove.flatMap((block) => getBlockRange(block)),
   );
   const removedBlocks: Block<BSchema, I, S>[] = [];
 
-  const idOfFirstBlock =
-    typeof blocksToRemove[0] === "string"
-      ? blocksToRemove[0]
-      : blocksToRemove[0].id;
   let removedSize = 0;
 
   tr.doc.descendants((node, pos) => {
@@ -61,7 +57,7 @@ export function removeAndInsertBlocks<
     removedBlocks.push(nodeToBlock(node, pmSchema));
     idsOfBlocksToRemove.delete(node.attrs.id);
 
-    if (blocksToInsert.length > 0 && node.attrs.id === idOfFirstBlock) {
+    if (blocksToInsert.length > 0 && node.attrs.id === insertionBlockId) {
       const oldDocSize = tr.doc.nodeSize;
       tr.insert(pos, nodesToInsert);
       const newDocSize = tr.doc.nodeSize;
diff --git a/packages/core/src/api/blockManipulation/commands/updateBlock/updateBlock.ts b/packages/core/src/api/blockManipulation/commands/updateBlock/updateBlock.ts
@@ -9,24 +9,23 @@ import { TableMap } from "prosemirror-tables";
 import { ReplaceStep, Transform } from "prosemirror-transform";
 
 import type { Block, PartialBlock } from "../../../../blocks/defaultBlocks.js";
-import type {
-  BlockIdentifier,
-  BlockSchema,
-} from "../../../../schema/blocks/types.js";
+import { getBlockStartPos } from "../../../../locations/location.js";
+import { Location } from "../../../../locations/types.js";
+import type { BlockSchema } from "../../../../schema/blocks/types.js";
 import type { InlineContentSchema } from "../../../../schema/inlineContent/types.js";
 import type { StyleSchema } from "../../../../schema/styles/types.js";
 import { UnreachableCaseError } from "../../../../util/typescript.js";
 import {
   type BlockInfo,
   getBlockInfoFromResolvedPos,
+  getNearestBlockPos,
 } from "../../../getBlockInfoFromPos.js";
 import {
   blockToNode,
   inlineContentToNodes,
   tableContentToNodes,
 } from "../../../nodeConversions/blockToNode.js";
 import { nodeToBlock } from "../../../nodeConversions/nodeToBlock.js";
-import { getNodeById } from "../../../nodeUtil.js";
 import { getPmSchema } from "../../../pmUtil.js";
 
 // for compatibility with tiptap. TODO: remove as we want to remove dependency on tiptap command interface
@@ -127,7 +126,7 @@ export function updateBlockTr<
     // currently, we calculate the new node and replace the entire node with the desired new node.
     // for this, we do a nodeToBlock on the existing block to get the children.
     // it would be cleaner to use a ReplaceAroundStep, but this is a bit simpler and it's quite an edge case
-    const existingBlock = nodeToBlock(blockInfo.bnBlock.node, pmSchema);
+    const existingBlock = nodeToBlock(blockInfo.bnBlock.node);
     tr.replaceWith(
       blockInfo.bnBlock.beforePos,
       blockInfo.bnBlock.afterPos,
@@ -312,32 +311,18 @@ export function updateBlock<
   S extends StyleSchema = any,
 >(
   tr: Transform,
-  blockToUpdate: BlockIdentifier,
+  blockToUpdate: Location,
   update: PartialBlock<BSchema, I, S>,
   replaceFromPos?: number,
   replaceToPos?: number,
 ): Block<BSchema, I, S> {
-  const id =
-    typeof blockToUpdate === "string" ? blockToUpdate : blockToUpdate.id;
-  const posInfo = getNodeById(id, tr.doc);
-  if (!posInfo) {
-    throw new Error(`Block with ID ${id} not found`);
-  }
+  const blockStartPos = getBlockStartPos(tr.doc, blockToUpdate);
 
-  updateBlockTr(
-    tr,
-    posInfo.posBeforeNode,
-    update,
-    replaceFromPos,
-    replaceToPos,
-  );
+  updateBlockTr(tr, blockStartPos, update, replaceFromPos, replaceToPos);
 
-  const blockContainerNode = tr.doc
-    .resolve(posInfo.posBeforeNode + 1) // TODO: clean?
-    .node();
+  const { node } = getNearestBlockPos(tr.doc, blockStartPos);
 
-  const pmSchema = getPmSchema(tr);
-  return nodeToBlock(blockContainerNode, pmSchema);
+  return nodeToBlock(node);
 }
 
 type CellAnchor = { row: number; col: number; offset: number };
diff --git a/packages/core/src/editor/managers/BlockManager.ts b/packages/core/src/editor/managers/BlockManager.ts
@@ -25,8 +25,9 @@ import {
   DefaultStyleSchema,
   PartialBlock,
 } from "../../blocks/defaultBlocks.js";
-import {
-  BlockIdentifier,
+import { Location } from "../../locations/types.js";
+import { getBlockId } from "../../locations/utils.js";
+import type {
   BlockSchema,
   InlineContentSchema,
   StyleSchema,
@@ -58,9 +59,11 @@ export class BlockManager<
    * matching block was found.
    */
   public getBlock(
-    blockIdentifier: BlockIdentifier,
+    blockIdentifier: Location,
   ): Block<BSchema, ISchema, SSchema> | undefined {
-    return this.editor.transact((tr) => getBlock(tr.doc, blockIdentifier));
+    return this.editor.transact((tr) =>
+      getBlock(tr.doc, getBlockId(blockIdentifier)),
+    );
   }
 
   /**
@@ -73,9 +76,11 @@ export class BlockManager<
    * in the document.
    */
   public getPrevBlock(
-    blockIdentifier: BlockIdentifier,
+    blockIdentifier: Location,
   ): Block<BSchema, ISchema, SSchema> | undefined {
-    return this.editor.transact((tr) => getPrevBlock(tr.doc, blockIdentifier));
+    return this.editor.transact((tr) =>
+      getPrevBlock(tr.doc, getBlockId(blockIdentifier)),
+    );
   }
 
   /**
@@ -87,9 +92,11 @@ export class BlockManager<
    * the document.
    */
   public getNextBlock(
-    blockIdentifier: BlockIdentifier,
+    blockIdentifier: Location,
   ): Block<BSchema, ISchema, SSchema> | undefined {
-    return this.editor.transact((tr) => getNextBlock(tr.doc, blockIdentifier));
+    return this.editor.transact((tr) =>
+      getNextBlock(tr.doc, getBlockId(blockIdentifier)),
+    );
   }
 
   /**
@@ -100,10 +107,10 @@ export class BlockManager<
    * if no matching block was found, or the block isn't nested.
    */
   public getParentBlock(
-    blockIdentifier: BlockIdentifier,
+    blockIdentifier: Location,
   ): Block<BSchema, ISchema, SSchema> | undefined {
     return this.editor.transact((tr) =>
-      getParentBlock(tr.doc, blockIdentifier),
+      getParentBlock(tr.doc, getBlockId(blockIdentifier)),
     );
   }
 
@@ -155,7 +162,7 @@ export class BlockManager<
    */
   public insertBlocks(
     blocksToInsert: PartialBlock<BSchema, ISchema, SSchema>[],
-    referenceBlock: BlockIdentifier,
+    referenceBlock: Location,
     placement: "before" | "after" = "before",
   ) {
     return this.editor.transact((tr) =>
@@ -171,7 +178,7 @@ export class BlockManager<
    * @param update A partial block which defines how the existing block should be changed.
    */
   public updateBlock(
-    blockToUpdate: BlockIdentifier,
+    blockToUpdate: Location,
     update: PartialBlock<BSchema, ISchema, SSchema>,
   ) {
     return this.editor.transact((tr) => updateBlock(tr, blockToUpdate, update));
@@ -181,7 +188,7 @@ export class BlockManager<
    * 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[]) {
+  public removeBlocks(blocksToRemove: Location[]) {
     return this.editor.transact(
       (tr) => removeAndInsertBlocks(tr, blocksToRemove, []).removedBlocks,
     );
@@ -195,7 +202,7 @@ export class BlockManager<
    * @param blocksToInsert An array of partial blocks to replace the old ones with.
    */
   public replaceBlocks(
-    blocksToRemove: BlockIdentifier[],
+    blocksToRemove: Location[],
     blocksToInsert: PartialBlock<BSchema, ISchema, SSchema>[],
   ) {
     return this.editor.transact((tr) =>
diff --git a/packages/core/src/locations/utils.ts b/packages/core/src/locations/utils.ts
@@ -161,3 +161,17 @@ export function isLocationEqual(
     range1.head.offset === range2.head.offset
   );
 }
+
+/**
+ * Gets the block id from a location.
+ * @throws if the location is not a single block.
+ */
+export function getBlockId(location: Location): BlockId {
+  const range = normalizeToRange(location);
+  if (range.anchor.id !== range.head.id) {
+    throw new Error("Invalid location, must be a single block", {
+      cause: { location },
+    });
+  }
+  return range.anchor.id;
+}
