feat(GraphComponent)!: provide absolute diff from drag start in onDrag callback (#194)

BREAKING CHANGE: `diffX`/`diffY` in `onDragUpdate` callback now represent
absolute displacement from drag start position instead of incremental
frame-to-frame values.

Changes:
- `diffX`/`diffY` now calculated as `currentCoords - startCoords`
- Added `startCoords` - initial position when drag started
- Added `deltaX`/`deltaY` - incremental change since previous frame
- Removed integer truncation (`| 0`) for better precision with slow movements

Author: draedful

docs/components/canvas-graph-component.md

@@ -139,8 +139,13 @@ this.onDrag({
     this.setState({ dragging: true });
     this.context.graph.emit('element-drag-start', { element: this });
   },
-  onDragUpdate: ({ diffX, diffY }, event) => {
-    this.updatePosition(this.state.x - diffX, this.state.y - diffY);
+  onDragUpdate: ({ startCoords, diffX, diffY, deltaX, deltaY }, event) => {
+    // diffX/diffY - absolute displacement from drag start position
+    // deltaX/deltaY - incremental change since previous frame
+    // Use diffX/diffY for absolute positioning from initial position
+    this.updatePosition(this.initialX + diffX, this.initialY + diffY);
+    // Or use deltaX/deltaY for incremental updates
+    // this.updatePosition(this.state.x + deltaX, this.state.y + deltaY);
   },
   onDrop: () => {
     this.setState({ dragging: false });
@@ -163,6 +168,25 @@ this.onDrag({
 - `mouseenter`, `mouseleave` - Mouse pointer entering or leaving the component
 - Specialized `onDrag` system with precise coordinate handling
 
+**The `onDrag` callback structure:**
+
+```typescript
+onDragUpdate: (diff: {
+  startCoords: [number, number];    // Initial position when drag started
+  prevCoords: [number, number];     // Position on previous frame
+  currentCoords: [number, number];  // Current mouse position
+  
+  diffX: number;    // Absolute X displacement from start (currentCoords.x - startCoords.x)
+  diffY: number;    // Absolute Y displacement from start (currentCoords.y - startCoords.y)
+  
+  deltaX: number;   // Incremental X change since last frame (currentCoords.x - prevCoords.x)
+  deltaY: number;   // Incremental Y change since last frame (currentCoords.y - prevCoords.y)
+}, event: MouseEvent) => void;
+```
+
+- Use `diffX`/`diffY` when you need to calculate position relative to drag start (e.g., `initialPosition + diffX`)
+- Use `deltaX`/`deltaY` when you need frame-to-frame movement (e.g., `currentPosition + deltaX`)
+
 ### 4. Reactive Data with Signal Subscriptions
 
 GraphComponent enables reactive programming with a simple subscription system:
@@ -461,13 +485,14 @@ class BadgeComponent extends GraphComponent<BadgeComponentProps, BadgeComponentS
       }
     });
 
-    // Make it draggable
+    // Make it draggable using incremental delta values
     this.onDrag({
       isDraggable: () => !this.props.locked,
-      onDragUpdate: ({ diffX, diffY }) => {
+      onDragUpdate: ({ deltaX, deltaY }) => {
+        // deltaX/deltaY provide frame-to-frame movement
         this.setState({
-          x: this.state.x - diffX,
-          y: this.state.y - diffY
+          x: this.state.x + deltaX,
+          y: this.state.y + deltaY
         });
         this.updateHitBox();
       }
@@ -953,13 +978,14 @@ class EditorNode extends GraphComponent {
   constructor(props, parent) {
     super(props, parent);
 
-    // Make node draggable
+    // Make node draggable using incremental delta values
     this.onDrag({
       isDraggable: () => this.context.editMode === 'move',
-      onDragUpdate: ({ diffX, diffY }) => {
+      onDragUpdate: ({ deltaX, deltaY }) => {
+        // deltaX/deltaY provide frame-to-frame movement
         this.setState({
-          x: this.state.x - diffX,
-          y: this.state.y - diffY
+          x: this.state.x + deltaX,
+          y: this.state.y + deltaY
         });
       }
     });

src/components/canvas/GraphComponent/index.tsx

@@ -117,10 +117,13 @@ export class GraphComponent<
     onDragStart?: (_event: MouseEvent) => void | boolean;
     onDragUpdate?: (
       diff: {
+        startCoords: [number, number];
         prevCoords: [number, number];
         currentCoords: [number, number];
         diffX: number;
         diffY: number;
+        deltaX: number;
+        deltaY: number;
       },
       _event: MouseEvent
     ) => void;
@@ -129,7 +132,8 @@ export class GraphComponent<
     autopanning?: boolean;
     dragCursor?: CursorLayerCursorTypes;
   }) {
-    let startDragCoords: [number, number];
+    let startCoords: [number, number];
+    let prevCoords: [number, number];
     return this.addEventListener("mousedown", (event: MouseEvent) => {
       if (!isDraggable?.(event)) {
         return;
@@ -146,22 +150,29 @@ export class GraphComponent<
             return;
           }
           const xy = getXY(this.context.canvas, event);
-          startDragCoords = this.context.camera.applyToPoint(xy[0], xy[1]);
+          startCoords = this.context.camera.applyToPoint(xy[0], xy[1]);
+          prevCoords = startCoords;
         })
         .on(EVENTS.DRAG_UPDATE, (event: MouseEvent) => {
-          if (!startDragCoords.length) return;
+          if (!startCoords?.length) return;
 
           const [canvasX, canvasY] = getXY(this.context.canvas, event);
           const currentCoords = this.context.camera.applyToPoint(canvasX, canvasY);
 
-          const diffX = (startDragCoords[0] - currentCoords[0]) | 0;
-          const diffY = (startDragCoords[1] - currentCoords[1]) | 0;
+          // Absolute diff from drag start
+          const diffX = currentCoords[0] - startCoords[0];
+          const diffY = currentCoords[1] - startCoords[1];
 
-          onDragUpdate?.({ prevCoords: startDragCoords, currentCoords, diffX, diffY }, event);
-          startDragCoords = currentCoords;
+          // Incremental diff from previous frame
+          const deltaX = currentCoords[0] - prevCoords[0];
+          const deltaY = currentCoords[1] - prevCoords[1];
+
+          onDragUpdate?.({ startCoords, prevCoords, currentCoords, diffX, diffY, deltaX, deltaY }, event);
+          prevCoords = currentCoords;
         })
         .on(EVENTS.DRAG_END, (_event: MouseEvent) => {
-          startDragCoords = undefined;
+          startCoords = undefined;
+          prevCoords = undefined;
           onDrop?.(_event);
         });
     });

src/components/canvas/groups/BlockGroups.ts

@@ -111,12 +111,12 @@ export class BlockGroups<P extends BlockGroupsProps = BlockGroupsProps> extends
     return this.props.graph.getGraphLayer().$.camera as CoreComponent;
   }
 
-  public updateBlocks = (groupId: TGroupId, { diffX, diffY }: { diffX: number; diffY: number }) => {
+  public updateBlocks = (groupId: TGroupId, { deltaX, deltaY }: { deltaX: number; deltaY: number }) => {
     if ((this.props as BlockGroupsProps & { updateBlocksOnDrag?: boolean }).updateBlocksOnDrag) {
       const blocks = this.$groupsBlocksMap.value[groupId];
       if (blocks) {
         blocks.forEach((block) => {
-          block.updateXY(block.x - diffX, block.y - diffY, true);
+          block.updateXY(block.x + deltaX, block.y + deltaY, true);
         });
       }
     }

src/components/canvas/groups/Group.ts

@@ -26,7 +26,7 @@ export type TGroupGeometry = {
 
 export type TGroupProps = {
   id: TGroupId;
-  onDragUpdate: (groupId: string, diff: { diffX: number; diffY: number }) => void;
+  onDragUpdate: (groupId: string, diff: { deltaX: number; deltaY: number }) => void;
   style?: Partial<TGroupStyle>;
   geometry?: Partial<TGroupGeometry>;
   draggable?: boolean;
@@ -114,18 +114,18 @@ export class Group<T extends TGroup = TGroup> extends GraphComponent<TGroupProps
         this.context.graph.cameraService.enableAutoPanning();
         this.context.graph.lockCursor("grabbing");
       },
-      onDragUpdate: ({ diffX, diffY }) => {
+      onDragUpdate: ({ deltaX, deltaY }) => {
         const rect = {
-          x: this.state.rect.x - diffX,
-          y: this.state.rect.y - diffY,
+          x: this.state.rect.x + deltaX,
+          y: this.state.rect.y + deltaY,
           width: this.state.rect.width,
           height: this.state.rect.height,
         };
         this.setState({
           rect,
         });
         this.updateHitBox(rect);
-        this.props.onDragUpdate(this.props.id, { diffX, diffY });
+        this.props.onDragUpdate(this.props.id, { deltaX, deltaY });
       },
       onDrop: () => {
         this.context.graph.cameraService.disableAutoPanning();