experiment(): Add snapping for create connetions

Author: draedful

.cursor/plans/port_magnetic_snapping_95725e35.plan.md

@@ -117,6 +117,18 @@ export class GraphComponent<
     return this.ports.get(id);
   }
 
+  /**
+   * Update port position and metadata
+   * @param id Port identifier
+   * @param x New X coordinate (optional)
+   * @param y New Y coordinate (optional)
+   * @param meta Port metadata (optional)
+   */
+  public updatePort<T = unknown>(id: TPortId, x?: number, y?: number, meta?: T): void {
+    const port = this.getPort(id);
+    port.updatePortWithMeta(x, y, meta);
+  }
+
   protected setAffectsUsableRect(affectsUsableRect: boolean) {
     this.setProps({ affectsUsableRect });
     this.setContext({ affectsUsableRect });

src/components/canvas/GraphComponent/index.tsx

@@ -59,7 +59,7 @@ export class Anchor<T extends TAnchorProps = TAnchorProps> extends GraphComponen
   }
 
   protected willMount(): void {
-    this.props.port.addObserver(this);
+    this.props.port.setOwner(this);
     this.subscribeSignal(this.connectedState.$selected, (selected) => {
       this.setState({ selected });
     });
@@ -111,7 +111,7 @@ export class Anchor<T extends TAnchorProps = TAnchorProps> extends GraphComponen
   }
 
   protected unmount() {
-    this.props.port.removeObserver(this);
+    this.props.port.setOwner(this.connectedState.block.getViewComponent());
     super.unmount();
   }
 

src/components/canvas/anchors/index.ts

@@ -1,15 +1,62 @@
+import RBush from "rbush";
+
 import { GraphMouseEvent, extractNativeGraphMouseEvent } from "../../../../graphEvents";
 import { Layer, LayerContext, LayerProps } from "../../../../services/Layer";
 import { ESelectionStrategy } from "../../../../services/selection/types";
 import { AnchorState } from "../../../../store/anchor/Anchor";
 import { BlockState, TBlockId } from "../../../../store/block/Block";
+import { PortState } from "../../../../store/connection/port/Port";
+import { createAnchorPortId, createBlockPointPortId } from "../../../../store/connection/port/utils";
 import { isBlock, isShiftKeyEvent } from "../../../../utils/functions";
 import { render } from "../../../../utils/renderers/render";
 import { renderSVG } from "../../../../utils/renderers/svgPath";
 import { Point, TPoint } from "../../../../utils/types/shapes";
 import { Anchor } from "../../../canvas/anchors";
 import { Block } from "../../../canvas/blocks/Block";
 
+const DEFAULT_MAGNET_WIDTH = 40;
+const DEFAULT_MAGNET_HEIGHT = 40;
+
+/**
+ * Magnet condition function type
+ * Used by ConnectionLayer to determine if a port can snap to another port
+ * Note: sourceComponent and targetComponent can be accessed via sourcePort.component and targetPort.component
+ */
+export type TPortMagnetCondition = (context: {
+  sourcePort: PortState;
+  targetPort: PortState;
+  cursorPosition: TPoint;
+  distance: number;
+}) => boolean;
+
+/**
+ * Optional metadata structure for magnetic ports
+ * ConnectionLayer interprets this structure for port snapping
+ *
+ * @example
+ * ```typescript
+ * const magnetMeta: IPortMagnetMeta = {
+ *   magnetWidthArea: 50,
+ *   magnetHeightArea: 50,
+ *   magnetCondition: (ctx) => {
+ *     // Access components via ports
+ *     const sourceComponent = ctx.sourcePort.component;
+ *     const targetComponent = ctx.targetPort.component;
+ *     // Custom validation logic
+ *     return true;
+ *   }
+ * };
+ * ```
+ */
+export interface IPortMagnetMeta {
+  /** Width of the magnet area (default 40) */
+  magnetWidthArea?: number;
+  /** Height of the magnet area (default 40) */
+  magnetHeightArea?: number;
+  /** Custom condition for snapping - access components via sourcePort.component and targetPort.component */
+  magnetCondition?: TPortMagnetCondition;
+}
+
 type TIcon = {
   path: string;
   fill?: string;
@@ -27,6 +74,14 @@ type LineStyle = {
 
 type DrawLineFunction = (start: TPoint, end: TPoint) => { path: Path2D; style: LineStyle };
 
+type MagneticPortBox = {
+  minX: number;
+  minY: number;
+  maxX: number;
+  maxY: number;
+  port: PortState;
+};
+
 type ConnectionLayerProps = LayerProps & {
   createIcon?: TIcon;
   point?: TIcon;
@@ -122,6 +177,11 @@ export class ConnectionLayer extends Layer<
   protected enabled: boolean;
   private declare eventAborter: AbortController;
 
+  // Magnetic ports support
+  private magneticPortsTree: RBush<MagneticPortBox> | null = null;
+  private isMagneticTreeOutdated = true;
+  private portsUnsubscribe?: () => void;
+
   constructor(props: ConnectionLayerProps) {
     super({
       canvas: {
@@ -161,6 +221,16 @@ export class ConnectionLayer extends Layer<
       capture: true,
     });
 
+    // Subscribe to ports changes to mark magnetic tree as outdated
+    // We'll mark the tree as outdated when ports change by polling
+    // Note: Direct subscription to internal signal requires access to connectionsList.ports
+    const checkPortsChanged = () => {
+      this.isMagneticTreeOutdated = true;
+    };
+
+    // Subscribe through the Layer's onSignal helper which handles cleanup
+    this.portsUnsubscribe = this.onSignal(this.context.graph.rootStore.connectionsList.ports.$ports, checkPortsChanged);
+
     // Call parent afterInit to ensure proper initialization
     super.afterInit();
   }
@@ -328,10 +398,26 @@ export class ConnectionLayer extends Layer<
       return;
     }
 
-    const newTargetComponent = this.context.graph.getElementOverPoint(point, [Block, Anchor]);
+    // Get source port
+    const sourcePort = this.getSourcePort(this.sourceComponent);
+
+    // Try to snap to magnetic port first
+    const magnetResult = this.findNearestMagneticPort(point, sourcePort);
+
+    let actualEndPoint = point;
+    let newTargetComponent: Block | Anchor;
+
+    if (magnetResult) {
+      // Snap to magnetic port
+      actualEndPoint = new Point(magnetResult.snapPoint.x, magnetResult.snapPoint.y);
+      newTargetComponent = this.getComponentByPort(magnetResult.port);
+    } else {
+      // Use existing logic - find element over point
+      newTargetComponent = this.context.graph.getElementOverPoint(point, [Block, Anchor]);
+    }
 
     // Use world coordinates from point instead of screen coordinates
-    this.endState = new Point(point.x, point.y);
+    this.endState = new Point(actualEndPoint.x, actualEndPoint.y);
     this.performRender();
 
     if (!newTargetComponent || !newTargetComponent.connectedState) {
@@ -430,4 +516,190 @@ export class ConnectionLayer extends Layer<
       () => {}
     );
   }
+
+  /**
+   * Get the source port from a component (block or anchor)
+   * @param component Block or Anchor component
+   * @returns Port state or undefined
+   */
+  private getSourcePort(component: BlockState | AnchorState): PortState | undefined {
+    const connectionsList = this.context.graph.rootStore.connectionsList;
+
+    if (component instanceof AnchorState) {
+      return connectionsList.getPort(createAnchorPortId(component.blockId, component.id));
+    }
+
+    // For block, use output port
+    return connectionsList.getPort(createBlockPointPortId(component.id, false));
+  }
+
+  /**
+   * Get the component (Block or Anchor) that owns a port
+   * @param port Port state
+   * @returns Block or Anchor component
+   */
+  private getComponentByPort(port: PortState): Block | Anchor | undefined {
+    const component = port.component;
+    if (!component) {
+      return undefined;
+    }
+
+    // Check if component is Block or Anchor by checking instance
+    if (component instanceof Block || component instanceof Anchor) {
+      return component;
+    }
+
+    return undefined;
+  }
+
+  /**
+   * Create a magnetic port bounding box for RBush spatial indexing
+   * @param port Port to create bounding box for
+   * @returns MagneticPortBox or null if port is not magnetic
+   */
+  private createMagneticPortBox(port: PortState): MagneticPortBox | null {
+    const meta = port.meta as IPortMagnetMeta | undefined;
+
+    // Check if port has magnetic metadata
+    if (!meta?.magnetWidthArea && !meta?.magnetHeightArea) {
+      return null; // Port is not magnetic
+    }
+
+    const widthArea = meta.magnetWidthArea ?? DEFAULT_MAGNET_WIDTH;
+    const heightArea = meta.magnetHeightArea ?? DEFAULT_MAGNET_HEIGHT;
+
+    return {
+      minX: port.x - widthArea / 2,
+      minY: port.y - heightArea / 2,
+      maxX: port.x + widthArea / 2,
+      maxY: port.y + heightArea / 2,
+      port: port,
+    };
+  }
+
+  /**
+   * Find the nearest magnetic port to a given point
+   * @param point Point to search from
+   * @param sourcePort Source port to exclude from search
+   * @returns Nearest magnetic port and snap point, or null if none found
+   */
+  private findNearestMagneticPort(
+    point: TPoint,
+    sourcePort?: PortState
+  ): { port: PortState; snapPoint: TPoint } | null {
+    // Rebuild RBush if outdated
+    this.rebuildMagneticTree();
+
+    if (!this.magneticPortsTree) {
+      return null;
+    }
+
+    // Search for ports in the area around cursor
+    const searchRadius = 100; // Search radius in pixels
+    const candidates = this.magneticPortsTree.search({
+      minX: point.x - searchRadius,
+      minY: point.y - searchRadius,
+      maxX: point.x + searchRadius,
+      maxY: point.y + searchRadius,
+    });
+
+    if (candidates.length === 0) {
+      return null;
+    }
+
+    // Find the nearest port by vector distance
+    let nearestPort: PortState | null = null;
+    let nearestDistance = Infinity;
+
+    for (const candidate of candidates) {
+      const port = candidate.port;
+
+      // Skip source port
+      if (sourcePort && port.id === sourcePort.id) {
+        continue;
+      }
+
+      // Calculate vector distance
+      const dx = port.x - point.x;
+      const dy = port.y - point.y;
+      const distance = Math.sqrt(dx * dx + dy * dy);
+
+      // Check if point is inside magnetic area
+      const meta = port.meta as IPortMagnetMeta | undefined;
+      const widthArea = meta?.magnetWidthArea ?? DEFAULT_MAGNET_WIDTH;
+      const heightArea = meta?.magnetHeightArea ?? DEFAULT_MAGNET_HEIGHT;
+
+      if (Math.abs(dx) > widthArea / 2 || Math.abs(dy) > heightArea / 2) {
+        continue; // Outside magnetic area
+      }
+
+      // Check custom condition if provided
+      if (meta?.magnetCondition && sourcePort) {
+        const canSnap = meta.magnetCondition({
+          sourcePort: sourcePort,
+          targetPort: port,
+          cursorPosition: point,
+          distance,
+        });
+
+        if (!canSnap) {
+          continue;
+        }
+      }
+
+      // Update nearest port
+      if (distance < nearestDistance) {
+        nearestDistance = distance;
+        nearestPort = port;
+      }
+    }
+
+    if (!nearestPort) {
+      return null;
+    }
+
+    return {
+      port: nearestPort,
+      snapPoint: { x: nearestPort.x, y: nearestPort.y },
+    };
+  }
+
+  /**
+   * Rebuild the RBush spatial index for magnetic ports (lazy rebuild)
+   */
+  private rebuildMagneticTree(): void {
+    if (!this.isMagneticTreeOutdated) {
+      return;
+    }
+
+    const magneticBoxes: MagneticPortBox[] = [];
+    const connectionsList = this.context.graph.rootStore.connectionsList;
+
+    // Get all ports from connectionsList
+    const allPorts = connectionsList.getAllPorts();
+    for (const port of allPorts) {
+      const box = this.createMagneticPortBox(port);
+      if (box) {
+        magneticBoxes.push(box);
+      }
+    }
+
+    this.magneticPortsTree = new RBush<MagneticPortBox>(9);
+    if (magneticBoxes.length > 0) {
+      this.magneticPortsTree.load(magneticBoxes);
+    }
+
+    this.isMagneticTreeOutdated = false;
+  }
+
+  public override unmount(): void {
+    // Cleanup ports subscription
+    if (this.portsUnsubscribe) {
+      this.portsUnsubscribe();
+      this.portsUnsubscribe = undefined;
+    }
+    // Clear magnetic tree
+    this.magneticPortsTree = null;
+    super.unmount();
+  }
 }

src/components/canvas/layers/connectionLayer/ConnectionLayer.ts

@@ -13,6 +13,9 @@ export { EAnchorType } from "./store/anchor/Anchor";
 export type { BlockState, TBlockId } from "./store/block/Block";
 export type { ConnectionState, TConnection, TConnectionId } from "./store/connection/ConnectionState";
 export type { AnchorState } from "./store/anchor/Anchor";
+export type { TPort, TPortId } from "./store/connection/port/Port";
+export { createAnchorPortId, createBlockPointPortId, createPortId } from "./store/connection/port/utils";
+export type { IPortMagnetMeta, TPortMagnetCondition } from "./components/canvas/layers/connectionLayer/ConnectionLayer";
 export { ECanChangeBlockGeometry, ECanDrag } from "./store/settings";
 export { type TMeasureTextOptions, type TWrapText } from "./utils/functions/text";
 export { ESchedulerPriority } from "./lib/Scheduler";