feat: enhance text cursor positioning in blocks

- Added offset calculation for cursor position within block's inline content.
- Updated `setTextCursorPosition` to accept numeric offsets, allowing precise cursor placement.
- Improved handling of blocks with no inline content and wrapper nodes.
- Documented new functionality in relevant areas.

Author: must

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

@@ -46,19 +46,75 @@ export function getTextCursorPosition<
     }
   }
 
+  // Compute the offset of the cursor within the block’s inline content.  We do
+  // this by determining the type of content the block holds and then
+  // calculating the difference between the selection’s anchor position and the
+  // start of the block’s content.
+  let offset = 0;
+  try {
+    const info = getBlockInfoFromTransaction(tr);
+    const pmSchemaForOffset = getPmSchema(tr.doc);
+    const schema = getBlockNoteSchema(pmSchemaForOffset);
+    const contentType = schema.blockSchema[info.blockNoteType]!.content;
+    let basePos: number | undefined;
+    if (info.isBlockContainer) {
+      const blockContent = info.blockContent;
+      if (contentType === "inline") {
+        // Inline content starts immediately after the opening of the blockContent
+        basePos = blockContent.beforePos + 1;
+      } else if (contentType === "table") {
+        // Table content starts a few positions after blockContent to skip table wrappers
+        basePos = blockContent.beforePos + 4;
+      } else if (contentType === "none") {
+        // Blocks with no inline content have the cursor anchored at the blockContent itself
+        basePos = blockContent.beforePos;
+      }
+    } else {
+      // For wrapper nodes (e.g. columns) there is no meaningful inline offset;
+      // use the childContainer as a reference if available.
+      // ChildContainer holds the block’s children; we assume the first child’s
+      // content starts one position after the container.
+      const childContainer = (info as any).childContainer;
+      if (childContainer && childContainer.beforePos !== undefined) {
+        basePos = childContainer.beforePos + 1;
+      }
+    }
+    if (basePos !== undefined) {
+      offset = tr.selection.anchor - basePos;
+      if (offset < 0) {
+        offset = 0;
+      }
+    }
+  } catch (e) {
+    // In case of any unexpected errors during offset computation, default to 0.
+    offset = 0;
+  }
+
   return {
     block: nodeToBlock(bnBlock.node, pmSchema),
     prevBlock: prevNode === null ? undefined : nodeToBlock(prevNode, pmSchema),
     nextBlock: nextNode === null ? undefined : nodeToBlock(nextNode, pmSchema),
     parentBlock:
       parentNode === undefined ? undefined : nodeToBlock(parentNode, pmSchema),
+    offset,
   };
 }
 
+/**
+ * Places the text cursor within a block. By default you can specify
+ * "start" or "end" to move the cursor to the beginning or end of the block.
+ * Alternatively, pass a numeric offset to place the cursor that many
+ * characters into the block’s inline content. Offsets beyond the block’s
+ * length will be clamped to the end of the block.
+ *
+ * @param tr The ProseMirror transaction.
+ * @param targetBlock Identifier of the block to move the cursor into.
+ * @param placementOrOffset Either "start", "end", or a zero‑based offset.
+ */
 export function setTextCursorPosition(
   tr: Transaction,
   targetBlock: BlockIdentifier,
-  placement: "start" | "end" = "start",
+  placementOrOffset: "start" | "end" | number = "start",
 ) {
   const id = typeof targetBlock === "string" ? targetBlock : targetBlock.id;
   const pmSchema = getPmSchema(tr.doc);
@@ -76,43 +132,54 @@ export function setTextCursorPosition(
 
   if (info.isBlockContainer) {
     const blockContent = info.blockContent;
+    // Handle blocks that have no inline content
     if (contentType === "none") {
       tr.setSelection(NodeSelection.create(tr.doc, blockContent.beforePos));
       return;
     }
 
+    // Determine base position for inline or table content
+    let basePos: number;
     if (contentType === "inline") {
-      if (placement === "start") {
-        tr.setSelection(
-          TextSelection.create(tr.doc, blockContent.beforePos + 1),
-        );
-      } else {
-        tr.setSelection(
-          TextSelection.create(tr.doc, blockContent.afterPos - 1),
-        );
-      }
+      basePos = blockContent.beforePos + 1;
     } else if (contentType === "table") {
-      if (placement === "start") {
-        // Need to offset the position as we have to get through the `tableRow`
-        // and `tableCell` nodes to get to the `tableParagraph` node we want to
-        // set the selection in.
-        tr.setSelection(
-          TextSelection.create(tr.doc, blockContent.beforePos + 4),
-        );
-      } else {
-        tr.setSelection(
-          TextSelection.create(tr.doc, blockContent.afterPos - 4),
-        );
-      }
+      basePos = blockContent.beforePos + 4;
     } else {
       throw new UnreachableCaseError(contentType);
     }
-  } else {
-    const child =
-      placement === "start"
-        ? info.childContainer.node.firstChild!
-        : info.childContainer.node.lastChild!;
 
-    setTextCursorPosition(tr, child.attrs.id, placement);
+    // Determine target position
+    let targetPos: number;
+    if (typeof placementOrOffset === "number") {
+      // Clamp the offset to the range of the block’s content
+      const maxOffset = blockContent.afterPos - basePos - 1;
+      const offset = Math.max(0, Math.min(placementOrOffset, maxOffset));
+      targetPos = basePos + offset;
+    } else if (placementOrOffset === "start") {
+      targetPos = basePos;
+    } else {
+      // end
+      if (contentType === "inline") {
+        targetPos = blockContent.afterPos - 1;
+      } else if (contentType === "table") {
+        targetPos = blockContent.afterPos - 4;
+      } else {
+        throw new UnreachableCaseError(contentType);
+      }
+    }
+    tr.setSelection(TextSelection.create(tr.doc, targetPos));
+  } else {
+    // For wrapper nodes, delegate to the first or last child when using start/end.
+    const isNumberPlacement = typeof placementOrOffset === "number";
+    const child = !isNumberPlacement && placementOrOffset === "end"
+      ? info.childContainer.node.lastChild!
+      : info.childContainer.node.firstChild!;
+    if (isNumberPlacement) {
+      // For numeric offsets inside wrapper nodes, we cannot determine a meaningful
+      // character position at this level, so recurse into the first child with the same offset.
+      setTextCursorPosition(tr, child.attrs.id, placementOrOffset);
+    } else {
+      setTextCursorPosition(tr, child.attrs.id, placementOrOffset);
+    }
   }
 }

packages/core/src/editor/BlockNoteEditor.ts

@@ -1219,12 +1219,18 @@ export class BlockNoteEditor<
    * @param targetBlock The identifier of an existing block that the text cursor should be moved to.
    * @param placement Whether the text cursor should be placed at the start or end of the block.
    */
+  /**
+   * Sets the text cursor position within a block. Pass "start" or "end" to
+   * move the cursor to the start or end of the block, or a numeric offset to
+   * place the cursor that many characters into the block’s inline content.
+   * Offsets beyond the block’s length are clamped to the block’s end.
+   */
   public setTextCursorPosition(
     targetBlock: BlockIdentifier,
-    placement: "start" | "end" = "start",
+    placementOrOffset: "start" | "end" | number = "start",
   ) {
     return this.transact((tr) =>
-      setTextCursorPosition(tr, targetBlock, placement),
+      setTextCursorPosition(tr, targetBlock, placementOrOffset),
     );
   }
 

packages/core/src/editor/cursorPositionTypes.ts

@@ -14,4 +14,13 @@ export type TextCursorPosition<
   prevBlock: Block<BSchema, I, S> | undefined;
   nextBlock: Block<BSchema, I, S> | undefined;
   parentBlock: Block<BSchema, I, S> | undefined;
+  /**
+   * Offset from the start of the block’s inline content to the current cursor position.
+   *
+   * For inline blocks this value is the number of characters from the start of the
+   * block’s content (i.e. `0` when the cursor is at the very beginning). For block
+   * types that do not contain inline content (e.g. empty blocks or structural
+   * wrappers) this value will be `0`.
+   */
+  offset: number;
 };