feat: add locations to getTextCursorPosition API

Author: nperez0111

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

@@ -2,7 +2,7 @@ import { Fragment, Slice } from "prosemirror-model";
 import type { Transaction } from "prosemirror-state";
 import { ReplaceStep } from "prosemirror-transform";
 import { Block, PartialBlock } from "../../../../blocks/defaultBlocks.js";
-import { resolveLocation } from "../../../../locations/location.js";
+import { resolveLocationToPM } from "../../../../locations/location.js";
 import { Location } from "../../../../locations/types.js";
 import {
   BlockSchema,
@@ -28,7 +28,7 @@ export function insertBlocks<
     blockToNode(block, pmSchema),
   );
 
-  const resolved = resolveLocation(tr.doc, referenceBlock);
+  const resolved = resolveLocationToPM(tr.doc, referenceBlock);
   const pos = placement === "after" ? resolved.head + 1 : resolved.anchor;
 
   tr.step(

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

@@ -6,7 +6,7 @@ import { insertContentAt } from "./insertContentAt.js";
 import { BlockNoteEditor } from "../../editor/BlockNoteEditor.js";
 import { inlineContentToNodes } from "../nodeConversions/blockToNode.js";
 import { getPmSchema } from "../pmUtil.js";
-import { resolveLocation } from "../../locations/location.js";
+import { resolveLocationToPM } from "../../locations/location.js";
 import type { Location } from "../../locations/types.js";
 
 const getEditor = setupTestEnv();
@@ -41,7 +41,7 @@ function insertContentAtLocation(
         ? [pmSchema.text(content)]
         : inlineContentToNodes(content, pmSchema);
 
-    const range = resolveLocation(tr.doc, location);
+    const range = resolveLocationToPM(tr.doc, location);
 
     return insertContentAt(
       tr,
@@ -461,7 +461,10 @@ describe("Test insertContentAt with Location types", () => {
     expect(
       editor.transact((tr) => {
         const pmSchema = getPmSchema(tr);
-        const range = resolveLocation(tr.doc, { id: "paragraph-0", offset: 5 });
+        const range = resolveLocationToPM(tr.doc, {
+          id: "paragraph-0",
+          offset: 5,
+        });
         const paragraphNode = pmSchema.nodes.paragraph.createChecked({}, [
           pmSchema.text("New paragraph"),
         ]);

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

@@ -26,7 +26,6 @@ export function getSelection<
 >(tr: Transaction): Selection<BSchema, I, S> | undefined {
   // Return undefined if the selection is collapsed or a node is selected.
   if (tr.selection.empty || "node" in tr.selection) {
-    // TODO do we really want this?
     return undefined;
   }
 

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

@@ -5,8 +5,10 @@ import {
   type Transaction,
 } from "prosemirror-state";
 import type { TextCursorPosition } from "../../../editor/cursorPositionTypes.js";
+import { resolvePMToLocation } from "../../../locations/location.js";
+import { Location } from "../../../locations/types.js";
+import { getBlockId, normalizeToRange } from "../../../locations/utils.js";
 import type {
-  BlockIdentifier,
   BlockSchema,
   InlineContentSchema,
   StyleSchema,
@@ -26,7 +28,6 @@ export function getTextCursorPosition<
   S extends StyleSchema,
 >(tr: Transaction): TextCursorPosition<BSchema, I, S> {
   const { bnBlock } = getBlockInfoFromTransaction(tr);
-  const pmSchema = getPmSchema(tr.doc);
 
   const resolvedPos = tr.doc.resolve(bnBlock.beforePos);
   // Gets previous blockContainer node at the same nesting level, if the current node isn't the first child.
@@ -46,21 +47,27 @@ export function getTextCursorPosition<
     }
   }
 
+  const location = resolvePMToLocation(tr.doc, {
+    anchor: tr.selection.anchor,
+    head: tr.selection.head,
+  });
+
   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),
+    meta: { location },
+    range: normalizeToRange(location),
+    block: nodeToBlock(bnBlock.node),
+    prevBlock: prevNode === null ? undefined : nodeToBlock(prevNode),
+    nextBlock: nextNode === null ? undefined : nodeToBlock(nextNode),
+    parentBlock: parentNode === undefined ? undefined : nodeToBlock(parentNode),
   };
 }
 
 export function setTextCursorPosition(
   tr: Transaction,
-  targetBlock: BlockIdentifier,
+  location: Location,
   placement: "start" | "end" = "start",
 ) {
-  const id = typeof targetBlock === "string" ? targetBlock : targetBlock.id;
+  const id = getBlockId(location);
   const pmSchema = getPmSchema(tr.doc);
   const schema = getBlockNoteSchema(pmSchema);
 

packages/core/src/editor/cursorPositionTypes.ts

@@ -1,4 +1,5 @@
 import { Block } from "../blocks/defaultBlocks.js";
+import { Point, Range } from "../locations/types.js";
 import {
   BlockSchema,
   InlineContentSchema,
@@ -10,8 +11,37 @@ export type TextCursorPosition<
   I extends InlineContentSchema,
   S extends StyleSchema,
 > = {
+  /**
+   * Meta information about the current selection.
+   */
+  meta: {
+    /**
+     * The underlying location of the current selection.
+     *
+     * If the selection is a single cursor, this will be a {@link Point}.
+     * If the selection is a selection range, this will be a {@link Range}.
+     */
+    location: Point | Range;
+  };
+  /**
+   * The range of the current selection.
+   * @note This is the same as the {@link meta.location} but normalized to a {@link Range}.
+   */
+  range: Range;
+  /**
+   * The block that the current text cursor is in.
+   */
   block: Block<BSchema, I, S>;
+  /**
+   * The previous block at the same nesting level.
+   */
   prevBlock: Block<BSchema, I, S> | undefined;
+  /**
+   * The next block at the same nesting level.
+   */
   nextBlock: Block<BSchema, I, S> | undefined;
+  /**
+   * The parent block of the current text cursor.
+   */
   parentBlock: Block<BSchema, I, S> | undefined;
 };

packages/core/src/editor/managers/StyleManager.ts

@@ -6,7 +6,7 @@ import {
   DefaultInlineContentSchema,
   DefaultStyleSchema,
 } from "../../blocks/defaultBlocks.js";
-import { resolveLocation } from "../../locations/location.js";
+import { resolveLocationToPM } from "../../locations/location.js";
 import { Location } from "../../locations/types.js";
 import {
   BlockSchema,
@@ -41,7 +41,7 @@ export class StyleManager<
 
     this.editor.transact((tr) => {
       const range = location
-        ? resolveLocation(tr.doc, location)
+        ? resolveLocationToPM(tr.doc, location)
         : {
             anchor: tr.selection.from,
             head: tr.selection.to,

packages/core/src/locations/location.test.ts

@@ -1,7 +1,7 @@
 import { describe, expect, it, beforeEach, afterEach } from "vitest";
 import { BlockNoteEditor } from "../editor/BlockNoteEditor.js";
 import {
-  resolveLocation,
+  resolveLocationToPM,
   resolveBlockToPM,
   resolvePointToPM,
   resolveRangeToPM,
@@ -61,7 +61,7 @@ describe("Location Resolution", () => {
 
   describe("resolveLocation", () => {
     it("should resolve BlockId to PMLocation", () => {
-      const result = resolveLocation(doc, "block1");
+      const result = resolveLocationToPM(doc, "block1");
 
       expect(result).toMatchInlineSnapshot(`
         {
@@ -72,7 +72,7 @@ describe("Location Resolution", () => {
     });
 
     it("should resolve BlockIdentifier object to PMLocation", () => {
-      const result = resolveLocation(doc, { id: "block2" });
+      const result = resolveLocationToPM(doc, { id: "block2" });
 
       expect(result).toMatchInlineSnapshot(`
         {
@@ -84,7 +84,7 @@ describe("Location Resolution", () => {
 
     it("should resolve Point to PMLocation", () => {
       const point: Point = { id: "block1", offset: 5 };
-      const result = resolveLocation(doc, point);
+      const result = resolveLocationToPM(doc, point);
 
       expect(result).toMatchInlineSnapshot(`
         {
@@ -99,7 +99,7 @@ describe("Location Resolution", () => {
         anchor: { id: "block1", offset: 0 },
         head: { id: "block3", offset: 10 },
       };
-      const result = resolveLocation(doc, range);
+      const result = resolveLocationToPM(doc, range);
 
       expect(result).toMatchInlineSnapshot(`
         {
@@ -111,7 +111,7 @@ describe("Location Resolution", () => {
 
     it("should throw error for invalid location type", () => {
       expect(() => {
-        resolveLocation(doc, "invalid-location-type" as any);
+        resolveLocationToPM(doc, "invalid-location-type" as any);
       }).toThrow("Block with ID invalid-location-type not found");
     });
   });
@@ -1501,12 +1501,12 @@ describe("Location Resolution", () => {
       const complexDoc = complexEditor._tiptapEditor.state.doc;
 
       // Test resolving different types of locations
-      const blockResult = resolveLocation(complexDoc, "title");
-      const pointResult = resolveLocation(complexDoc, {
+      const blockResult = resolveLocationToPM(complexDoc, "title");
+      const pointResult = resolveLocationToPM(complexDoc, {
         id: "intro",
         offset: 10,
       });
-      const rangeResult = resolveLocation(complexDoc, {
+      const rangeResult = resolveLocationToPM(complexDoc, {
         anchor: { id: "list1", offset: 0 },
         head: { id: "list2", offset: -1 },
       });
@@ -1536,8 +1536,8 @@ describe("Location Resolution", () => {
     it("should maintain consistency across multiple calls", () => {
       const point: Point = { id: "block1", offset: 5 };
 
-      const result1 = resolveLocation(doc, point);
-      const result2 = resolveLocation(doc, point);
+      const result1 = resolveLocationToPM(doc, point);
+      const result2 = resolveLocationToPM(doc, point);
 
       expect(result1).toMatchInlineSnapshot(`
         {

packages/core/src/locations/location.ts

@@ -20,7 +20,7 @@ import { Block } from "../blocks/index.js";
 /**
  * Resolves a {@link Location} to a {@link PMLocation}.
  */
-export function resolveLocation(doc: Node, location: Location): PMLocation {
+export function resolveLocationToPM(doc: Node, location: Location): PMLocation {
   if (isBlockId(location)) {
     return resolveBlockToPM(doc, location);
   }
@@ -288,6 +288,6 @@ export function getSelectionLocation(tr: Transaction): {
 }
 
 export function setSelectionLocation(tr: Transaction, location: Location) {
-  const resolved = resolveLocation(tr.doc, location);
+  const resolved = resolveLocationToPM(tr.doc, location);
   tr.setSelection(TextSelection.create(tr.doc, resolved.anchor, resolved.head));
 }

packages/xl-multi-column/src/test/commands/__snapshots__/textCursorPosition.test.ts.snap

@@ -19,6 +19,12 @@ exports[`Test getTextCursorPosition & setTextCursorPosition > Column 1`] = `
     },
     "type": "paragraph",
   },
+  "meta": {
+    "location": {
+      "id": "column-paragraph-0",
+      "offset": 0,
+    },
+  },
   "nextBlock": {
     "children": [],
     "content": [
@@ -81,6 +87,16 @@ exports[`Test getTextCursorPosition & setTextCursorPosition > Column 1`] = `
     "type": "column",
   },
   "prevBlock": undefined,
+  "range": {
+    "anchor": {
+      "id": "column-paragraph-0",
+      "offset": 0,
+    },
+    "head": {
+      "id": "column-paragraph-0",
+      "offset": 0,
+    },
+  },
 }
 `;
 
@@ -103,6 +119,12 @@ exports[`Test getTextCursorPosition & setTextCursorPosition > Column list 1`] =
     },
     "type": "paragraph",
   },
+  "meta": {
+    "location": {
+      "id": "column-paragraph-0",
+      "offset": 0,
+    },
+  },
   "nextBlock": {
     "children": [],
     "content": [
@@ -165,5 +187,15 @@ exports[`Test getTextCursorPosition & setTextCursorPosition > Column list 1`] =
     "type": "column",
   },
   "prevBlock": undefined,
+  "range": {
+    "anchor": {
+      "id": "column-paragraph-0",
+      "offset": 0,
+    },
+    "head": {
+      "id": "column-paragraph-0",
+      "offset": 0,
+    },
+  },
 }
 `;

tests/src/unit/core/selection/textCursorPosition/__snapshots__/basic.json

@@ -16,6 +16,12 @@
     },
     "type": "paragraph",
   },
+  "meta": {
+    "location": {
+      "id": "target",
+      "offset": 0,
+    },
+  },
   "nextBlock": {
     "children": [],
     "content": [
@@ -51,4 +57,14 @@
     },
     "type": "paragraph",
   },
+  "range": {
+    "anchor": {
+      "id": "target",
+      "offset": 0,
+    },
+    "head": {
+      "id": "target",
+      "offset": 0,
+    },
+  },
 }