power-link 2.0.5 → 2.1.0

package/README.md

@@ -21,6 +21,8 @@ visit [online demo](https://tem-man.github.io/power-link)
 - 📦 **Zero Dependencies** - Pure JavaScript, no framework required
 - 🎭 **Multiple Connection Points** - Support for left and right connection dots
 - 🔌 **Event Callbacks** - Listen to connection and disconnection events
+- 🖱️ **Context Menu Hooks** - `onNodeContextMenu` and `onCanvasContextMenu` for custom right-click menus
+- 📐 **Coordinate Conversion** - `clientToCanvas()` for converting viewport coordinates to canvas space
 
 ## 📦 Installation
 
@@ -145,6 +147,8 @@ connector.registerNode("node2", node2, {
 | `onNodeMove`       | Function    | `() => {}`   | Callback when a node is dragged (receives `{ id, x, y }`) |
 | `onNodeSelect`     | Function    | `() => {}`   | Callback when a node is selected/deselected (receives node info or `null`) |
 | `onNodeDelete`     | Function    | `() => {}`   | Callback when a node is deleted (receives `{ id, info }`) |
+| `onNodeContextMenu` | Function   | -            | Callback when right-clicking a node (receives `{ id, info, clientX, clientY }`). Library auto prevents default menu. |
+| `onCanvasContextMenu` | Function | -            | Callback when right-clicking empty canvas (receives `{ clientX, clientY, canvasX, canvasY }`). `canvasX/Y` are pre-converted coordinates. |
 
 ### Methods
 
@@ -338,6 +342,37 @@ const viewState = connector.getViewState();
 console.log(viewState); // { scale: 1, translateX: 0, translateY: 0 }
 ```
 
+#### `clientToCanvas(clientX, clientY)`
+
+Convert viewport (client) coordinates to canvas (contentWrapper) coordinates. Automatically accounts for current zoom and pan.
+
+Useful for: pasting nodes at cursor position, positioning tooltips, handling external drag-and-drop, etc.
+
+**Parameters:**
+
+- `clientX` (Number): X coordinate in viewport (e.g. `MouseEvent.clientX`)
+- `clientY` (Number): Y coordinate in viewport (e.g. `MouseEvent.clientY`)
+
+**Returns:** `{ x, y }` - Canvas coordinates
+
+**Example:**
+
+```javascript
+// Paste node at mouse cursor position
+canvas.addEventListener('click', (e) => {
+  const pos = connector.clientToCanvas(e.clientX, e.clientY);
+  addNodeAt(pos.x, pos.y);
+});
+
+// Or with Ctrl+V paste
+document.addEventListener('keydown', (e) => {
+  if (e.ctrlKey && e.key === 'v') {
+    const pos = connector.clientToCanvas(lastMouseX, lastMouseY);
+    pasteNode(pos.x, pos.y);
+  }
+});
+```
+
 #### `setZoom(scale)`
 
 Set the zoom level (centered on canvas).
@@ -914,6 +949,20 @@ const connector = new Connector({
     // Remove node from your state management
     // In Vue: nodes.value = nodes.value.filter(n => n.id !== id);
     // In React: setNodes(nodes.filter(n => n.id !== id));
+  },
+
+  // Right-click on a node - show custom context menu
+  onNodeContextMenu: ({ id, info, clientX, clientY }) => {
+    console.log("Node right-clicked:", id, "at", clientX, clientY);
+    // Show your custom menu at (clientX, clientY)
+    // e.g. showContextMenu(clientX, clientY, { id, info });
+  },
+
+  // Right-click on empty canvas - e.g. paste menu
+  onCanvasContextMenu: ({ clientX, clientY, canvasX, canvasY }) => {
+    console.log("Canvas right-clicked at", clientX, clientY, "→ canvas", canvasX, canvasY);
+    // canvasX/Y are pre-converted for paste position, tooltip placement, etc.
+    // e.g. showPasteMenu(clientX, clientY, { x: canvasX, y: canvasY });
   }
 });
 ```

package/dist/index.d.mts

@@ -91,6 +91,28 @@ interface NodeDeleteInfo {
     id: string;
     info?: Record<string, unknown>;
 }
+/** 节点右键菜单信息 */
+interface NodeContextMenuInfo {
+    /** 被右键的节点 id */
+    id: string;
+    /** 节点附加信息 */
+    info?: Record<string, unknown>;
+    /** 鼠标在视口中的 X 坐标 */
+    clientX: number;
+    /** 鼠标在视口中的 Y 坐标 */
+    clientY: number;
+}
+/** 画布空白区域右键菜单信息 */
+interface CanvasContextMenuInfo {
+    /** 鼠标在视口中的 X 坐标 */
+    clientX: number;
+    /** 鼠标在视口中的 Y 坐标 */
+    clientY: number;
+    /** 鼠标对应的画布（contentWrapper）X 坐标（已换算缩放/平移） */
+    canvasX: number;
+    /** 鼠标对应的画布（contentWrapper）Y 坐标（已换算缩放/平移） */
+    canvasY: number;
+}
 /** 构造函数选项 */
 interface ConnectorOptions extends Partial<ConnectorConfig> {
     container: HTMLElement;
@@ -102,6 +124,16 @@ interface ConnectorOptions extends Partial<ConnectorConfig> {
     onNodeSelect?: (info: NodeSelectInfo | null) => void;
     /** 节点被删除时触发 */
     onNodeDelete?: (info: NodeDeleteInfo) => void;
+    /**
+     * 右键单击某个节点时触发。
+     * 库会自动 preventDefault + stopPropagation，用户只需响应回调渲染自定义菜单。
+     */
+    onNodeContextMenu?: (info: NodeContextMenuInfo) => void;
+    /**
+     * 右键单击画布空白区域时触发（节点上的右键不会冒泡到此）。
+     * info 中同时提供视口坐标（clientX/Y）和已换算的画布坐标（canvasX/Y）。
+     */
+    onCanvasContextMenu?: (info: CanvasContextMenuInfo) => void;
     config?: Partial<ConnectorConfig>;
 }
 /** 节点注册选项 */
@@ -259,6 +291,26 @@ declare class Connector {
      * @param nodeFactory 可选，原生 JS 场景下的节点元素工厂
      */
     import(data: ExportData, nodeFactory?: NodeFactory): Promise<void>;
+    /**
+     * 将视口（client）坐标转换为画布（contentWrapper）坐标
+     *
+     * 已自动计算当前缩放比例与平移量，可在任何需要把屏幕位置映射到画布的场景中使用：
+     * 粘贴节点、从外部拖入元素、定位自定义 tooltip 等。
+     *
+     * @param clientX - 鼠标/触点在视口中的 X 坐标（如 MouseEvent.clientX）
+     * @param clientY - 鼠标/触点在视口中的 Y 坐标（如 MouseEvent.clientY）
+     * @returns 对应的画布坐标 `{ x, y }`
+     *
+     * @example
+     * canvas.addEventListener('click', (e) => {
+     *   const pos = connector.clientToCanvas(e.clientX, e.clientY);
+     *   console.log('Canvas position:', pos.x, pos.y);
+     * });
+     */
+    clientToCanvas(clientX: number, clientY: number): {
+        x: number;
+        y: number;
+    };
     /**
      * 设置缩放比例（以画布中心为基准）
      */
@@ -299,4 +351,4 @@ declare class Connector {
  * @description 导出 Connector 类及相关类型定义
  */
 
-export { type Connection, type ConnectionInfo, Connector, type ConnectorConfig, type ConnectorNode, type ConnectorOptions, type Dot, type DotPosition, type ExportConnectionData, type ExportData, type ExportNodeData, type NodeDeleteInfo, type NodeFactory, type NodeMoveInfo, type NodeSelectInfo, type Point, type RegisterNodeOptions, type SilentOptions, type ViewState, Connector as default };
+export { type CanvasContextMenuInfo, type Connection, type ConnectionInfo, Connector, type ConnectorConfig, type ConnectorNode, type ConnectorOptions, type Dot, type DotPosition, type ExportConnectionData, type ExportData, type ExportNodeData, type NodeContextMenuInfo, type NodeDeleteInfo, type NodeFactory, type NodeMoveInfo, type NodeSelectInfo, type Point, type RegisterNodeOptions, type SilentOptions, type ViewState, Connector as default };

package/dist/index.d.ts

@@ -91,6 +91,28 @@ interface NodeDeleteInfo {
     id: string;
     info?: Record<string, unknown>;
 }
+/** 节点右键菜单信息 */
+interface NodeContextMenuInfo {
+    /** 被右键的节点 id */
+    id: string;
+    /** 节点附加信息 */
+    info?: Record<string, unknown>;
+    /** 鼠标在视口中的 X 坐标 */
+    clientX: number;
+    /** 鼠标在视口中的 Y 坐标 */
+    clientY: number;
+}
+/** 画布空白区域右键菜单信息 */
+interface CanvasContextMenuInfo {
+    /** 鼠标在视口中的 X 坐标 */
+    clientX: number;
+    /** 鼠标在视口中的 Y 坐标 */
+    clientY: number;
+    /** 鼠标对应的画布（contentWrapper）X 坐标（已换算缩放/平移） */
+    canvasX: number;
+    /** 鼠标对应的画布（contentWrapper）Y 坐标（已换算缩放/平移） */
+    canvasY: number;
+}
 /** 构造函数选项 */
 interface ConnectorOptions extends Partial<ConnectorConfig> {
     container: HTMLElement;
@@ -102,6 +124,16 @@ interface ConnectorOptions extends Partial<ConnectorConfig> {
     onNodeSelect?: (info: NodeSelectInfo | null) => void;
     /** 节点被删除时触发 */
     onNodeDelete?: (info: NodeDeleteInfo) => void;
+    /**
+     * 右键单击某个节点时触发。
+     * 库会自动 preventDefault + stopPropagation，用户只需响应回调渲染自定义菜单。
+     */
+    onNodeContextMenu?: (info: NodeContextMenuInfo) => void;
+    /**
+     * 右键单击画布空白区域时触发（节点上的右键不会冒泡到此）。
+     * info 中同时提供视口坐标（clientX/Y）和已换算的画布坐标（canvasX/Y）。
+     */
+    onCanvasContextMenu?: (info: CanvasContextMenuInfo) => void;
     config?: Partial<ConnectorConfig>;
 }
 /** 节点注册选项 */
@@ -259,6 +291,26 @@ declare class Connector {
      * @param nodeFactory 可选，原生 JS 场景下的节点元素工厂
      */
     import(data: ExportData, nodeFactory?: NodeFactory): Promise<void>;
+    /**
+     * 将视口（client）坐标转换为画布（contentWrapper）坐标
+     *
+     * 已自动计算当前缩放比例与平移量，可在任何需要把屏幕位置映射到画布的场景中使用：
+     * 粘贴节点、从外部拖入元素、定位自定义 tooltip 等。
+     *
+     * @param clientX - 鼠标/触点在视口中的 X 坐标（如 MouseEvent.clientX）
+     * @param clientY - 鼠标/触点在视口中的 Y 坐标（如 MouseEvent.clientY）
+     * @returns 对应的画布坐标 `{ x, y }`
+     *
+     * @example
+     * canvas.addEventListener('click', (e) => {
+     *   const pos = connector.clientToCanvas(e.clientX, e.clientY);
+     *   console.log('Canvas position:', pos.x, pos.y);
+     * });
+     */
+    clientToCanvas(clientX: number, clientY: number): {
+        x: number;
+        y: number;
+    };
     /**
      * 设置缩放比例（以画布中心为基准）
      */
@@ -299,4 +351,4 @@ declare class Connector {
  * @description 导出 Connector 类及相关类型定义
  */
 
-export { type Connection, type ConnectionInfo, Connector, type ConnectorConfig, type ConnectorNode, type ConnectorOptions, type Dot, type DotPosition, type ExportConnectionData, type ExportData, type ExportNodeData, type NodeDeleteInfo, type NodeFactory, type NodeMoveInfo, type NodeSelectInfo, type Point, type RegisterNodeOptions, type SilentOptions, type ViewState, Connector as default };
+export { type CanvasContextMenuInfo, type Connection, type ConnectionInfo, Connector, type ConnectorConfig, type ConnectorNode, type ConnectorOptions, type Dot, type DotPosition, type ExportConnectionData, type ExportData, type ExportNodeData, type NodeContextMenuInfo, type NodeDeleteInfo, type NodeFactory, type NodeMoveInfo, type NodeSelectInfo, type Point, type RegisterNodeOptions, type SilentOptions, type ViewState, Connector as default };

package/dist/index.global.js

@@ -388,6 +388,23 @@ var PowerLink = (function (exports) {
         if (target.closest && target.closest(".connector-delete-btn")) return;
         this.deselectNode();
       }, "handleContainerMouseDown");
+      /**
+       * 画布空白区域右键：节点的 contextmenu 会 stopPropagation，
+       * 因此只有点击空白处时此处才会触发
+       */
+      this.handleContainerContextMenu = /* @__PURE__ */ __name((e) => {
+        if (!this.ctx.onCanvasContextMenu) return;
+        e.preventDefault();
+        const rect = this.ctx.container.getBoundingClientRect();
+        const { scale, translateX, translateY } = this.ctx.viewState;
+        const info = {
+          clientX: e.clientX,
+          clientY: e.clientY,
+          canvasX: (e.clientX - rect.left - translateX) / scale,
+          canvasY: (e.clientY - rect.top - translateY) / scale
+        };
+        this.ctx.onCanvasContextMenu(info);
+      }, "handleContainerContextMenu");
       this.ctx = ctx;
       this.positionHelper = positionHelper;
     }
@@ -406,6 +423,7 @@ var PowerLink = (function (exports) {
     init() {
       document.addEventListener("keydown", this.handleKeyDown);
       this.ctx.container.addEventListener("mousedown", this.handleContainerMouseDown);
+      this.ctx.container.addEventListener("contextmenu", this.handleContainerContextMenu);
     }
     // ==================== 节点注册 ====================
     /**
@@ -465,6 +483,7 @@ var PowerLink = (function (exports) {
       } else {
         this.bindNodeClickEvents(node);
       }
+      this.bindNodeContextMenuEvents(node);
       return node;
     }
     // ==================== 触点 ====================
@@ -519,6 +538,24 @@ var PowerLink = (function (exports) {
         document.addEventListener("mouseup", this.handleMouseUp);
       });
     }
+    /**
+     * 绑定节点右键菜单事件
+     * 仅在用户提供 onNodeContextMenu 回调时拦截事件，否则不干预浏览器默认行为
+     */
+    bindNodeContextMenuEvents(node) {
+      node.element.addEventListener("contextmenu", (e) => {
+        if (!this.ctx.onNodeContextMenu) return;
+        e.preventDefault();
+        e.stopPropagation();
+        const info = {
+          id: node.id,
+          info: node.info,
+          clientX: e.clientX,
+          clientY: e.clientY
+        };
+        this.ctx.onNodeContextMenu(info);
+      });
+    }
     /**
      * 绑定节点拖拽事件（同时包含点击选中逻辑）
      */
@@ -685,6 +722,7 @@ var PowerLink = (function (exports) {
     destroy() {
       document.removeEventListener("keydown", this.handleKeyDown);
       this.ctx.container.removeEventListener("mousedown", this.handleContainerMouseDown);
+      this.ctx.container.removeEventListener("contextmenu", this.handleContainerContextMenu);
       this.ctx.nodes.forEach((node) => {
         if (node.dots) {
           Object.values(node.dots).forEach((dot) => {
@@ -1206,7 +1244,9 @@ var PowerLink = (function (exports) {
         onNodeSelect: options.onNodeSelect || (() => {
         }),
         onNodeDelete: options.onNodeDelete || (() => {
-        })
+        }),
+        onNodeContextMenu: options.onNodeContextMenu,
+        onCanvasContextMenu: options.onCanvasContextMenu
       };
       this.positionHelper = new PositionHelper(this.ctx);
       this.viewManager = new ViewManager(this.ctx, this.positionHelper);
@@ -1447,6 +1487,31 @@ var PowerLink = (function (exports) {
         this.setViewState(data.viewState);
       }
     }
+    // ==================== 坐标工具 API ====================
+    /**
+     * 将视口（client）坐标转换为画布（contentWrapper）坐标
+     *
+     * 已自动计算当前缩放比例与平移量，可在任何需要把屏幕位置映射到画布的场景中使用：
+     * 粘贴节点、从外部拖入元素、定位自定义 tooltip 等。
+     *
+     * @param clientX - 鼠标/触点在视口中的 X 坐标（如 MouseEvent.clientX）
+     * @param clientY - 鼠标/触点在视口中的 Y 坐标（如 MouseEvent.clientY）
+     * @returns 对应的画布坐标 `{ x, y }`
+     *
+     * @example
+     * canvas.addEventListener('click', (e) => {
+     *   const pos = connector.clientToCanvas(e.clientX, e.clientY);
+     *   console.log('Canvas position:', pos.x, pos.y);
+     * });
+     */
+    clientToCanvas(clientX, clientY) {
+      const rect = this.ctx.container.getBoundingClientRect();
+      const { scale, translateX, translateY } = this.ctx.viewState;
+      return {
+        x: (clientX - rect.left - translateX) / scale,
+        y: (clientY - rect.top - translateY) / scale
+      };
+    }
     // ==================== 视图 API ====================
     /**
      * 设置缩放比例（以画布中心为基准）

package/dist/index.js

@@ -389,6 +389,23 @@ var _NodeManager = class _NodeManager {
       if (target.closest && target.closest(".connector-delete-btn")) return;
       this.deselectNode();
     }, "handleContainerMouseDown");
+    /**
+     * 画布空白区域右键：节点的 contextmenu 会 stopPropagation，
+     * 因此只有点击空白处时此处才会触发
+     */
+    this.handleContainerContextMenu = /* @__PURE__ */ __name((e) => {
+      if (!this.ctx.onCanvasContextMenu) return;
+      e.preventDefault();
+      const rect = this.ctx.container.getBoundingClientRect();
+      const { scale, translateX, translateY } = this.ctx.viewState;
+      const info = {
+        clientX: e.clientX,
+        clientY: e.clientY,
+        canvasX: (e.clientX - rect.left - translateX) / scale,
+        canvasY: (e.clientY - rect.top - translateY) / scale
+      };
+      this.ctx.onCanvasContextMenu(info);
+    }, "handleContainerContextMenu");
     this.ctx = ctx;
     this.positionHelper = positionHelper;
   }
@@ -407,6 +424,7 @@ var _NodeManager = class _NodeManager {
   init() {
     document.addEventListener("keydown", this.handleKeyDown);
     this.ctx.container.addEventListener("mousedown", this.handleContainerMouseDown);
+    this.ctx.container.addEventListener("contextmenu", this.handleContainerContextMenu);
   }
   // ==================== 节点注册 ====================
   /**
@@ -466,6 +484,7 @@ var _NodeManager = class _NodeManager {
     } else {
       this.bindNodeClickEvents(node);
     }
+    this.bindNodeContextMenuEvents(node);
     return node;
   }
   // ==================== 触点 ====================
@@ -520,6 +539,24 @@ var _NodeManager = class _NodeManager {
       document.addEventListener("mouseup", this.handleMouseUp);
     });
   }
+  /**
+   * 绑定节点右键菜单事件
+   * 仅在用户提供 onNodeContextMenu 回调时拦截事件，否则不干预浏览器默认行为
+   */
+  bindNodeContextMenuEvents(node) {
+    node.element.addEventListener("contextmenu", (e) => {
+      if (!this.ctx.onNodeContextMenu) return;
+      e.preventDefault();
+      e.stopPropagation();
+      const info = {
+        id: node.id,
+        info: node.info,
+        clientX: e.clientX,
+        clientY: e.clientY
+      };
+      this.ctx.onNodeContextMenu(info);
+    });
+  }
   /**
    * 绑定节点拖拽事件（同时包含点击选中逻辑）
    */
@@ -686,6 +723,7 @@ var _NodeManager = class _NodeManager {
   destroy() {
     document.removeEventListener("keydown", this.handleKeyDown);
     this.ctx.container.removeEventListener("mousedown", this.handleContainerMouseDown);
+    this.ctx.container.removeEventListener("contextmenu", this.handleContainerContextMenu);
     this.ctx.nodes.forEach((node) => {
       if (node.dots) {
         Object.values(node.dots).forEach((dot) => {
@@ -1207,7 +1245,9 @@ var _Connector = class _Connector {
       onNodeSelect: options.onNodeSelect || (() => {
       }),
       onNodeDelete: options.onNodeDelete || (() => {
-      })
+      }),
+      onNodeContextMenu: options.onNodeContextMenu,
+      onCanvasContextMenu: options.onCanvasContextMenu
     };
     this.positionHelper = new PositionHelper(this.ctx);
     this.viewManager = new ViewManager(this.ctx, this.positionHelper);
@@ -1448,6 +1488,31 @@ var _Connector = class _Connector {
       this.setViewState(data.viewState);
     }
   }
+  // ==================== 坐标工具 API ====================
+  /**
+   * 将视口（client）坐标转换为画布（contentWrapper）坐标
+   *
+   * 已自动计算当前缩放比例与平移量，可在任何需要把屏幕位置映射到画布的场景中使用：
+   * 粘贴节点、从外部拖入元素、定位自定义 tooltip 等。
+   *
+   * @param clientX - 鼠标/触点在视口中的 X 坐标（如 MouseEvent.clientX）
+   * @param clientY - 鼠标/触点在视口中的 Y 坐标（如 MouseEvent.clientY）
+   * @returns 对应的画布坐标 `{ x, y }`
+   *
+   * @example
+   * canvas.addEventListener('click', (e) => {
+   *   const pos = connector.clientToCanvas(e.clientX, e.clientY);
+   *   console.log('Canvas position:', pos.x, pos.y);
+   * });
+   */
+  clientToCanvas(clientX, clientY) {
+    const rect = this.ctx.container.getBoundingClientRect();
+    const { scale, translateX, translateY } = this.ctx.viewState;
+    return {
+      x: (clientX - rect.left - translateX) / scale,
+      y: (clientY - rect.top - translateY) / scale
+    };
+  }
   // ==================== 视图 API ====================
   /**
    * 设置缩放比例（以画布中心为基准）

package/dist/index.mjs

@@ -385,6 +385,23 @@ var _NodeManager = class _NodeManager {
       if (target.closest && target.closest(".connector-delete-btn")) return;
       this.deselectNode();
     }, "handleContainerMouseDown");
+    /**
+     * 画布空白区域右键：节点的 contextmenu 会 stopPropagation，
+     * 因此只有点击空白处时此处才会触发
+     */
+    this.handleContainerContextMenu = /* @__PURE__ */ __name((e) => {
+      if (!this.ctx.onCanvasContextMenu) return;
+      e.preventDefault();
+      const rect = this.ctx.container.getBoundingClientRect();
+      const { scale, translateX, translateY } = this.ctx.viewState;
+      const info = {
+        clientX: e.clientX,
+        clientY: e.clientY,
+        canvasX: (e.clientX - rect.left - translateX) / scale,
+        canvasY: (e.clientY - rect.top - translateY) / scale
+      };
+      this.ctx.onCanvasContextMenu(info);
+    }, "handleContainerContextMenu");
     this.ctx = ctx;
     this.positionHelper = positionHelper;
   }
@@ -403,6 +420,7 @@ var _NodeManager = class _NodeManager {
   init() {
     document.addEventListener("keydown", this.handleKeyDown);
     this.ctx.container.addEventListener("mousedown", this.handleContainerMouseDown);
+    this.ctx.container.addEventListener("contextmenu", this.handleContainerContextMenu);
   }
   // ==================== 节点注册 ====================
   /**
@@ -462,6 +480,7 @@ var _NodeManager = class _NodeManager {
     } else {
       this.bindNodeClickEvents(node);
     }
+    this.bindNodeContextMenuEvents(node);
     return node;
   }
   // ==================== 触点 ====================
@@ -516,6 +535,24 @@ var _NodeManager = class _NodeManager {
       document.addEventListener("mouseup", this.handleMouseUp);
     });
   }
+  /**
+   * 绑定节点右键菜单事件
+   * 仅在用户提供 onNodeContextMenu 回调时拦截事件，否则不干预浏览器默认行为
+   */
+  bindNodeContextMenuEvents(node) {
+    node.element.addEventListener("contextmenu", (e) => {
+      if (!this.ctx.onNodeContextMenu) return;
+      e.preventDefault();
+      e.stopPropagation();
+      const info = {
+        id: node.id,
+        info: node.info,
+        clientX: e.clientX,
+        clientY: e.clientY
+      };
+      this.ctx.onNodeContextMenu(info);
+    });
+  }
   /**
    * 绑定节点拖拽事件（同时包含点击选中逻辑）
    */
@@ -682,6 +719,7 @@ var _NodeManager = class _NodeManager {
   destroy() {
     document.removeEventListener("keydown", this.handleKeyDown);
     this.ctx.container.removeEventListener("mousedown", this.handleContainerMouseDown);
+    this.ctx.container.removeEventListener("contextmenu", this.handleContainerContextMenu);
     this.ctx.nodes.forEach((node) => {
       if (node.dots) {
         Object.values(node.dots).forEach((dot) => {
@@ -1203,7 +1241,9 @@ var _Connector = class _Connector {
       onNodeSelect: options.onNodeSelect || (() => {
       }),
       onNodeDelete: options.onNodeDelete || (() => {
-      })
+      }),
+      onNodeContextMenu: options.onNodeContextMenu,
+      onCanvasContextMenu: options.onCanvasContextMenu
     };
     this.positionHelper = new PositionHelper(this.ctx);
     this.viewManager = new ViewManager(this.ctx, this.positionHelper);
@@ -1444,6 +1484,31 @@ var _Connector = class _Connector {
       this.setViewState(data.viewState);
     }
   }
+  // ==================== 坐标工具 API ====================
+  /**
+   * 将视口（client）坐标转换为画布（contentWrapper）坐标
+   *
+   * 已自动计算当前缩放比例与平移量，可在任何需要把屏幕位置映射到画布的场景中使用：
+   * 粘贴节点、从外部拖入元素、定位自定义 tooltip 等。
+   *
+   * @param clientX - 鼠标/触点在视口中的 X 坐标（如 MouseEvent.clientX）
+   * @param clientY - 鼠标/触点在视口中的 Y 坐标（如 MouseEvent.clientY）
+   * @returns 对应的画布坐标 `{ x, y }`
+   *
+   * @example
+   * canvas.addEventListener('click', (e) => {
+   *   const pos = connector.clientToCanvas(e.clientX, e.clientY);
+   *   console.log('Canvas position:', pos.x, pos.y);
+   * });
+   */
+  clientToCanvas(clientX, clientY) {
+    const rect = this.ctx.container.getBoundingClientRect();
+    const { scale, translateX, translateY } = this.ctx.viewState;
+    return {
+      x: (clientX - rect.left - translateX) / scale,
+      y: (clientY - rect.top - translateY) / scale
+    };
+  }
   // ==================== 视图 API ====================
   /**
    * 设置缩放比例（以画布中心为基准）

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "power-link",
-  "version": "2.0.5",
+  "version": "2.1.0",
   "description": "A pure TypeScript visual node connector for creating draggable connections between nodes. Framework-agnostic and easy to use",
   "author": {
     "name": "Lin Ji Man",