summary nodes move event (#185)

* feat: add fMoveNodes event emitter and FMoveNodesEvent class for node movement handling

* docs: enhance drag-handle example with fMoveNodes event and position change handling

Author: siarheihuzarevich

projects/f-examples/nodes/drag-handle/drag-handle.component.html

@@ -1,26 +1,26 @@
-<f-flow fDraggable (fLoaded)="onLoaded()">
+<f-flow fDraggable (fLoaded)="onLoaded()" (fMoveNodes)="onMoveNodes($event)">
   <f-canvas>
     <div fNode fDragHandle
-         [fNodePosition]="{ x: 0, y: 0 }">
+         [fNodePosition]="{ x: 0, y: 0 }" (fNodePositionChange)="onNodePositionChange($event)">
       Node is the drag handle
     </div>
 
     <div fNode
-         [fNodePosition]="{ x: 120, y: 100 }" class="drag-handle-inside">
+         [fNodePosition]="{ x: 120, y: 100 }" class="drag-handle-inside" (fNodePositionChange)="onNodePositionChange($event)">
       <span fDragHandle class="f-icon f-drag-handle-icon"></span>
       Only the icon is the drag handle
     </div>
 
     <div fNode
-         [fNodePosition]="{ x: 350, y: 0 }" class="drag-handle-outside">
+         [fNodePosition]="{ x: 350, y: 0 }" class="drag-handle-outside" (fNodePositionChange)="onNodePositionChange($event)">
       <div fDragHandle>
         <span class="f-icon f-drag-handle-icon"></span>
       </div>
       Only the icon is the drag handle
     </div>
 
     <div fNode
-         [fNodePosition]="{ x: 130, y: 200 }">
+         [fNodePosition]="{ x: 130, y: 200 }" (fNodePositionChange)="onNodePositionChange($event)">
       Only the image is the drag handle
       <div fDragHandle>
         <img src="https://material.angular.io/assets/img/examples/shiba2.jpg">

projects/f-examples/nodes/drag-handle/drag-handle.component.ts

@@ -1,8 +1,9 @@
 import { ChangeDetectionStrategy, Component, viewChild } from '@angular/core';
 import {
   FCanvasComponent,
-  FFlowModule
+  FFlowModule, FMoveNodesEvent
 } from '@foblex/flow';
+import {IPoint} from "@foblex/2d";
 
 @Component({
   selector: 'drag-handle',
@@ -17,7 +18,30 @@ import {
 export class DragHandleComponent {
   protected readonly fCanvas = viewChild(FCanvasComponent);
 
+  /**
+   * Triggered after the <f-flow> component is fully loaded.
+   * Resets the canvas scale and centers the view without animation.
+   */
   protected onLoaded(): void {
     this.fCanvas()?.resetScaleAndCenter(false);
   }
+
+  /**
+   * Called when one or more nodes are moved.
+   * Can be used to track movements or persist state.
+   *
+   * @param event - Node movement event containing affected nodes and delta.
+   */
+  protected onMoveNodes(event: FMoveNodesEvent): void {
+    // Handle node movement.
+  }
+
+  /**
+   * Called when a single node's position changes.
+   *
+   * @param position - The new position of the node.
+   */
+  protected onNodePositionChange(position: IPoint): void {
+    // Handle node position change.
+  }
 }

projects/f-flow/src/f-draggable/f-draggable-base.ts

@@ -5,6 +5,7 @@ import { FCreateNodeEvent } from '../f-external-item';
 import { FDragStartedEvent, FNodeIntersectedWithConnections } from './domain';
 import { FDropToGroupEvent } from './f-drop-to-group';
 import {DragAndDropBase, ICanRunOutsideAngular} from "../drag-toolkit";
+import {FMoveNodesEvent} from "./f-node-move";
 
 @Directive()
 export abstract class FDraggableBase extends DragAndDropBase  {
@@ -17,6 +18,8 @@ export abstract class FDraggableBase extends DragAndDropBase  {
 
   public abstract fCreateNode: EventEmitter<FCreateNodeEvent>;
 
+  public abstract fMoveNodes: EventEmitter<FMoveNodesEvent>;
+
   public abstract fReassignConnection: EventEmitter<FReassignConnectionEvent>;
 
   public abstract fCreateConnection: EventEmitter<FCreateConnectionEvent>;

projects/f-flow/src/f-draggable/f-draggable.directive.ts

@@ -10,6 +10,7 @@ import {
 } from "@angular/core";
 import { FDraggableBase } from './f-draggable-base';
 import {
+  FMoveNodesEvent,
   FNodeMoveFinalizeRequest,
   FNodeMovePreparationRequest
 } from './f-node-move';
@@ -161,6 +162,9 @@ export class FDraggableDirective extends FDraggableBase implements OnInit, After
   @Output()
   public override fCreateNode = new EventEmitter<FCreateNodeEvent>();
 
+  @Output()
+  public override fMoveNodes = new EventEmitter<FMoveNodesEvent>();
+
   @Output()
   public override fReassignConnection = new EventEmitter<FReassignConnectionEvent>();
 

projects/f-flow/src/f-draggable/f-node-move/f-move-nodes.event.ts

@@ -0,0 +1,9 @@
+import {IPoint} from '@foblex/2d';
+
+export class FMoveNodesEvent {
+
+  constructor(
+    public fNodes: { id: string; position: IPoint }[],
+  ) {
+  }
+}

projects/f-flow/src/f-draggable/f-node-move/index.ts

@@ -10,6 +10,8 @@ export * from './move-finalize';
 
 export * from './f-line-alignment.drag-handler';
 
+export * from './f-move-nodes.event';
+
 export * from './f-node-move.drag-handler';
 
 export * from './point-bounds-limiter';

projects/f-flow/src/f-draggable/f-node-move/move-finalize/f-node-move-finalize.execution.ts

@@ -1,18 +1,19 @@
-import { inject, Injectable } from '@angular/core';
-import { FNodeMoveFinalizeRequest } from './f-node-move-finalize.request';
-import { IPoint, Point } from '@foblex/2d';
-import { FExecutionRegister, FMediator, IExecution } from '@foblex/mediator';
-import { FComponentsStore } from '../../../f-storage';
-import { FDraggableDataContext } from '../../f-draggable-data-context';
+import {inject, Injectable} from '@angular/core';
+import {FNodeMoveFinalizeRequest} from './f-node-move-finalize.request';
+import {IPoint, Point} from '@foblex/2d';
+import {FExecutionRegister, FMediator, IExecution} from '@foblex/mediator';
+import {FComponentsStore} from '../../../f-storage';
+import {FDraggableDataContext} from '../../f-draggable-data-context';
 import {
   IsConnectionUnderNodeRequest
 } from '../../domain';
-import { IFDragHandler } from '../../f-drag-handler';
-import { FNodeDropToGroupDragHandler } from '../../f-drop-to-group';
-import { ILineAlignmentResult, INearestCoordinateResult } from '../../../f-line-alignment';
-import { FLineAlignmentDragHandler } from '../f-line-alignment.drag-handler';
-import { FSummaryNodeMoveDragHandler } from '../f-summary-node-move.drag-handler';
-import { FNodeBase } from '../../../f-node';
+import {IFDragHandler} from '../../f-drag-handler';
+import {FNodeDropToGroupDragHandler} from '../../f-drop-to-group';
+import {ILineAlignmentResult, INearestCoordinateResult} from '../../../f-line-alignment';
+import {FLineAlignmentDragHandler} from '../f-line-alignment.drag-handler';
+import {FSummaryNodeMoveDragHandler} from '../f-summary-node-move.drag-handler';
+import {FNodeBase} from '../../../f-node';
+import {FMoveNodesEvent} from "../f-move-nodes.event";
 
 @Injectable()
 @FExecutionRegister(FNodeMoveFinalizeRequest)
@@ -48,9 +49,19 @@ export class FNodeMoveFinalizeExecution implements IExecution<FNodeMoveFinalizeR
 
   private _finalizeMove(difference: IPoint): void {
     this._getItems().forEach((x) => {
-      x.onPointerMove({ ...difference });
+      x.onPointerMove({...difference});
       x.onPointerUp?.();
     });
+
+    if (this._getItems().length) {
+      const event = this._getItems()[0].fData.fNodeIds.map((id: string) => {
+        return {
+          id,
+          position: this._fComponentsStore.fNodes.find(x => x.fId === id)!.position,
+        }
+      });
+      this._fComponentsStore.fDraggable?.fMoveNodes.emit(new FMoveNodesEvent(event));
+    }
   }
 
   private _getItems(): IFDragHandler[] {
@@ -99,10 +110,10 @@ export class FNodeMoveFinalizeExecution implements IExecution<FNodeMoveFinalizeR
   }
 
   private _isDraggedJustOneNode(): boolean {
-    return (this._fDraggableDataContext.draggableItems[ 0 ] as FSummaryNodeMoveDragHandler).fHandlers.length === 1;
+    return (this._fDraggableDataContext.draggableItems[0] as FSummaryNodeMoveDragHandler).fHandlers.length === 1;
   }
 
   private _getFirstNodeOrGroup(): FNodeBase {
-    return (this._fDraggableDataContext.draggableItems[ 0 ] as FSummaryNodeMoveDragHandler).fHandlers[ 0 ].fNode;
+    return (this._fDraggableDataContext.draggableItems[0] as FSummaryNodeMoveDragHandler).fHandlers[0].fNode;
   }
 }

public/markdown/examples/drag-handle.md

@@ -4,6 +4,27 @@
 
 This example showcases how to add a [DragHandle](./docs/f-drag-handle-directive) for nodes, allowing users to move them easily within Angular and Foblex Flow.
 
+The `fDragHandle` directive can be applied to any HTML element inside a node `fNode`. It defines which part of the node should respond to drag gestures. This enables you to:
+-	Make the entire node draggable
+-	Limit dragging to a specific element like an icon, header, or image
+-	Build flexible and intuitive drag behavior for custom UIs
+
+#### How to Handle Position Changes
+
+To track and persist node positions, you should handle the `fNodePositionChange` event emitted by each node. This event returns a new position of the node `{ x: number, y: number }` whenever it is moved.
+
+You can use this event to:
+-	Save the new position to a model or store
+-	Sync changes to a backend or local storage
+-	Trigger layout adjustments or constraints
+
+In addition, the `fMoveNodes` event emitted by `<f-flow>` is triggered whenever one or more nodes are moved, including single-node moves.
+It provides an array of updated nodes, each with its new position, making it ideal for:
+
+-	Tracking bulk movements (e.g., group drag)
+-	Implementing `undo/redo` systems
+-	Managing external logic like snapping or alignment
+
 ## Example
 
 ::: ng-component <drag-handle></drag-handle> [height]="600"

src/app/examples.config.ts

@@ -154,7 +154,11 @@ function nodesGroup() {
     image_width: 795,
     image_height: 600,
     image_type: 'image/png',
-    date: new Date('2024-10-02 16:04:08')
+    date: new Date('2025-19-07 13:00:22'),
+    badge: {
+      text: 'Updated',
+      type: 'warning'
+    },
   }, {
     link: 'node-selection',
     text: 'Node Selection',