@xyflow/system 0.0.11 → 0.0.13

package/dist/esm/index.mjs

@@ -1,4 +1,3 @@
-"use client"
 import { drag } from 'd3-drag';
 import { select, pointer } from 'd3-selection';
 import { zoom, zoomIdentity, zoomTransform } from 'd3-zoom';
@@ -64,9 +63,71 @@ var Position;
     Position["Bottom"] = "bottom";
 })(Position || (Position = {}));
 
+/**
+ * @internal
+ */
+function areConnectionMapsEqual(a, b) {
+    if (!a && !b) {
+        return true;
+    }
+    if (!a || !b || a.size !== b.size) {
+        return false;
+    }
+    if (!a.size && !b.size) {
+        return true;
+    }
+    for (const key of a.keys()) {
+        if (!b.has(key)) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * We call the callback for all connections in a that are not in b
+ *
+ * @internal
+ */
+function handleConnectionChange(a, b, cb) {
+    if (!cb) {
+        return;
+    }
+    const diff = [];
+    a.forEach((connection, key) => {
+        if (!b?.has(key)) {
+            diff.push(connection);
+        }
+    });
+    if (diff.length) {
+        cb(diff);
+    }
+}
+
 /* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * Test whether an object is useable as an Edge
+ * @public
+ * @remarks In TypeScript this is a type guard that will narrow the type of whatever you pass in to Edge if it returns true
+ * @param element - The element to test
+ * @returns A boolean indicating whether the element is an Edge
+ */
 const isEdgeBase = (element) => 'id' in element && 'source' in element && 'target' in element;
+/**
+ * Test whether an object is useable as a Node
+ * @public
+ * @remarks In TypeScript this is a type guard that will narrow the type of whatever you pass in to Node if it returns true
+ * @param element - The element to test
+ * @returns A boolean indicating whether the element is an Node
+ */
 const isNodeBase = (element) => 'id' in element && !('source' in element) && !('target' in element);
+/**
+ * Pass in a node, and get connected nodes where edge.source === node.id
+ * @public
+ * @param node - The node to get the connected nodes from
+ * @param nodes - The array of all nodes
+ * @param edges - The array of all edges
+ * @returns An array of nodes that are connected over eges where the source is the given node
+ */
 const getOutgoersBase = (node, nodes, edges) => {
     if (!node.id) {
         return [];
@@ -79,6 +140,14 @@ const getOutgoersBase = (node, nodes, edges) => {
     });
     return nodes.filter((n) => outgoerIds.has(n.id));
 };
+/**
+ * Pass in a node, and get connected nodes where edge.target === node.id
+ * @public
+ * @param node - The node to get the connected nodes from
+ * @param nodes - The array of all nodes
+ * @param edges - The array of all edges
+ * @returns An array of nodes that are connected over eges where the target is the given node
+ */
 const getIncomersBase = (node, nodes, edges) => {
     if (!node.id) {
         return [];
@@ -118,6 +187,14 @@ const getNodePositionWithOrigin = (node, nodeOrigin = [0, 0]) => {
             : position,
     };
 };
+/**
+ * Determines a bounding box that contains all given nodes in an array
+ * @public
+ * @remarks Useful when combined with {@link getViewportForBounds} to calculate the correct transform to fit the given nodes in a viewport.
+ * @param nodes - Nodes to calculate the bounds for
+ * @param nodeOrigin - Origin of the nodes: [0, 0] - top left, [0.5, 0.5] - center
+ * @returns Bounding box enclosing all nodes
+ */
 const getNodesBounds = (nodes, nodeOrigin = [0, 0]) => {
     if (nodes.length === 0) {
         return { x: 0, y: 0, width: 0, height: 0 };
@@ -160,6 +237,12 @@ excludeNonSelectableNodes = false, nodeOrigin = [0, 0]) => {
     }, []);
     return visibleNodes;
 };
+/**
+ * Get all connecting edges for a given set of nodes
+ * @param nodes - Nodes you want to get the connected edges for
+ * @param edges - All edges
+ * @returns Array of edges that connect any of the given nodes with each other
+ */
 const getConnectedEdgesBase = (nodes, edges) => {
     const nodeIds = new Set();
     nodes.forEach((node) => {
@@ -238,33 +321,53 @@ function calcNextPosition(node, nextPosition, nodes, nodeExtent, nodeOrigin = [0
         positionAbsolute,
     };
 }
-// helper function to get arrays of nodes and edges that can be deleted
-// you can pass in a list of nodes and edges that should be deleted
-// and the function only returns elements that are deletable and also handles connected nodes and child nodes
-function getElementsToRemove({ nodesToRemove, edgesToRemove, nodes, edges, }) {
+/**
+ * Pass in nodes & edges to delete, get arrays of nodes and edges that actually can be deleted
+ * @internal
+ * @param param.nodesToRemove - The nodes to remove
+ * @param param.edgesToRemove - The edges to remove
+ * @param param.nodes - All nodes
+ * @param param.edges - All edges
+ * @param param.onBeforeDelete - Callback to check which nodes and edges can be deleted
+ * @returns nodes: nodes that can be deleted, edges: edges that can be deleted
+ */
+async function getElementsToRemove({ nodesToRemove = [], edgesToRemove = [], nodes, edges, onBeforeDelete, }) {
     const nodeIds = nodesToRemove.map((node) => node.id);
-    const edgeIds = edgesToRemove.map((edge) => edge.id);
-    const matchingNodes = nodes.reduce((res, node) => {
-        const parentHit = !nodeIds.includes(node.id) && node.parentNode && res.find((n) => n.id === node.parentNode);
-        const deletable = typeof node.deletable === 'boolean' ? node.deletable : true;
-        if (deletable && (nodeIds.includes(node.id) || parentHit)) {
-            res.push(node);
+    const matchingNodes = [];
+    for (const node of nodes) {
+        if (node.deletable === false) {
+            continue;
         }
-        return res;
-    }, []);
-    const deletableEdges = edges.filter((e) => (typeof e.deletable === 'boolean' ? e.deletable : true));
-    const initialHitEdges = deletableEdges.filter((e) => edgeIds.includes(e.id));
+        const isIncluded = nodeIds.includes(node.id);
+        const parentHit = !isIncluded && node.parentNode && matchingNodes.find((n) => n.id === node.parentNode);
+        if (isIncluded || parentHit) {
+            matchingNodes.push(node);
+        }
+    }
+    const edgeIds = edgesToRemove.map((edge) => edge.id);
+    const deletableEdges = edges.filter((edge) => edge.deletable !== false);
     const connectedEdges = getConnectedEdgesBase(matchingNodes, deletableEdges);
-    const matchingEdges = connectedEdges.reduce((res, edge) => {
-        if (!res.find((e) => e.id === edge.id)) {
-            res.push(edge);
+    const matchingEdges = connectedEdges;
+    for (const edge of deletableEdges) {
+        const isIncluded = edgeIds.includes(edge.id);
+        if (isIncluded && !matchingEdges.find((e) => e.id === edge.id)) {
+            matchingEdges.push(edge);
         }
-        return res;
-    }, initialHitEdges);
-    return {
-        matchingEdges,
-        matchingNodes,
-    };
+    }
+    if (!onBeforeDelete) {
+        return {
+            edges: matchingEdges,
+            nodes: matchingNodes,
+        };
+    }
+    const onBeforeDeleteResult = await onBeforeDelete({
+        nodes: matchingNodes,
+        edges: matchingEdges,
+    });
+    if (typeof onBeforeDeleteResult === 'boolean') {
+        return onBeforeDeleteResult ? { edges: matchingEdges, nodes: matchingNodes } : { edges: [], nodes: [] };
+    }
+    return onBeforeDeleteResult;
 }
 
 const clamp = (val, min = 0, max = 1) => Math.min(Math.max(val, min), max);
@@ -272,8 +375,14 @@ const clampPosition = (position = { x: 0, y: 0 }, extent) => ({
     x: clamp(position.x, extent[0][0], extent[1][0]),
     y: clamp(position.y, extent[0][1], extent[1][1]),
 });
-// returns a number between 0 and 1 that represents the velocity of the movement
-// when the mouse is close to the edge of the canvas
+/**
+ * Calculates the velocity of panning when the mouse is close to the edge of the canvas
+ * @internal
+ * @param value - One dimensional poition of the mouse (x or y)
+ * @param min - Minimal position on canvas before panning starts
+ * @param max - Maximal position on canvas before panning starts
+ * @returns - A number between 0 and 1 that represents the velocity of panning
+ */
 const calcAutoPanVelocity = (value, min, max) => {
     if (value < min) {
         return clamp(Math.abs(value - min), 1, 50) / 50;
@@ -347,12 +456,12 @@ const getPositionWithOrigin = ({ x, y, width, height, origin = [0, 0], }) => {
         y: y - height * origin[1],
     };
 };
-function snapPosition(position, snapGrid = [1, 1]) {
+const snapPosition = (position, snapGrid = [1, 1]) => {
     return {
         x: snapGrid[0] * Math.round(position.x / snapGrid[0]),
         y: snapGrid[1] * Math.round(position.y / snapGrid[1]),
     };
-}
+};
 const pointToRendererPoint = ({ x, y }, [tx, ty, tScale], snapToGrid = false, snapGrid = [1, 1]) => {
     const position = {
         x: (x - tx) / tScale,
@@ -366,6 +475,22 @@ const rendererPointToPoint = ({ x, y }, [tx, ty, tScale]) => {
         y: y * tScale + ty,
     };
 };
+/**
+ * Returns a viewport that encloses the given bounds with optional padding.
+ * @public
+ * @remarks You can determine bounds of nodes with {@link getNodesBounds} and {@link getBoundsOfRects}
+ * @param bounds - Bounds to fit inside viewport
+ * @param width - Width of the viewport
+ * @param height  - Height of the viewport
+ * @param minZoom - Minimum zoom level of the resulting viewport
+ * @param maxZoom - Maximum zoom level of the resulting viewport
+ * @param padding - Optional padding around the bounds
+ * @returns A transforned {@link Viewport} that encloses the given bounds which you can pass to e.g. {@link setViewport}
+ * @example
+ * const { x, y, zoom } = getViewportForBounds(
+  { x: 0, y: 0, width: 100, height: 100},
+  1200, 800, 0.5, 2);
+ */
 const getViewportForBounds = (bounds, width, height, minZoom, maxZoom, padding) => {
     const xZoom = width / (bounds.width * (1 + padding));
     const yZoom = height / (bounds.height * (1 + padding));
@@ -469,6 +594,29 @@ function getControlWithCurvature({ pos, x1, y1, x2, y2, c }) {
             return [x1, y1 + calculateControlOffset(y2 - y1, c)];
     }
 }
+/**
+ * Get a bezier path from source to target handle
+ * @param params.sourceX - The x position of the source handle
+ * @param params.sourceY - The y position of the source handle
+ * @param params.sourcePosition - The position of the source handle (default: Position.Bottom)
+ * @param params.targetX - The x position of the target handle
+ * @param params.targetY - The y position of the target handle
+ * @param params.targetPosition - The position of the target handle (default: Position.Top)
+ * @param params.curvature - The curvature of the bezier edge
+ * @returns A path string you can use in an SVG, the labelX and labelY position (center of path) and offsetX, offsetY between source handle and label
+ * @example
+ *  const source = { x: 0, y: 20 };
+    const target = { x: 150, y: 100 };
+    
+    const [path, labelX, labelY, offsetX, offsetY] = getBezierPath({
+      sourceX: source.x,
+      sourceY: source.y,
+      sourcePosition: Position.Right,
+      targetX: target.x,
+      targetY: target.y,
+      targetPosition: Position.Left,
+});
+ */
 function getBezierPath({ sourceX, sourceY, sourcePosition = Position.Bottom, targetX, targetY, targetPosition = Position.Top, curvature = 0.25, }) {
     const [sourceControlX, sourceControlY] = getControlWithCurvature({
         pos: sourcePosition,
@@ -513,40 +661,13 @@ function getEdgeCenter({ sourceX, sourceY, targetX, targetY, }) {
     const centerY = targetY < sourceY ? targetY + yOffset : targetY - yOffset;
     return [centerX, centerY, xOffset, yOffset];
 }
-const defaultEdgeTree = [{ level: 0, isMaxLevel: true, edges: [] }];
-function groupEdgesByZLevel(edges, nodeLookup, elevateEdgesOnSelect = false) {
-    let maxLevel = -1;
-    const levelLookup = edges.reduce((tree, edge) => {
-        const hasZIndex = isNumeric(edge.zIndex);
-        let z = hasZIndex ? edge.zIndex : 0;
-        if (elevateEdgesOnSelect) {
-            const targetNode = nodeLookup.get(edge.target);
-            const sourceNode = nodeLookup.get(edge.source);
-            const edgeOrConnectedNodeSelected = edge.selected || targetNode?.selected || sourceNode?.selected;
-            const selectedZIndex = Math.max(sourceNode?.[internalsSymbol]?.z || 0, targetNode?.[internalsSymbol]?.z || 0, 1000);
-            z = (hasZIndex ? edge.zIndex : 0) + (edgeOrConnectedNodeSelected ? selectedZIndex : 0);
-        }
-        if (tree[z]) {
-            tree[z].push(edge);
-        }
-        else {
-            tree[z] = [edge];
-        }
-        maxLevel = z > maxLevel ? z : maxLevel;
-        return tree;
-    }, {});
-    const edgeTree = Object.entries(levelLookup).map(([key, edges]) => {
-        const level = +key;
-        return {
-            edges,
-            level,
-            isMaxLevel: level === maxLevel,
-        };
-    });
-    if (edgeTree.length === 0) {
-        return defaultEdgeTree;
+function getElevatedEdgeZIndex({ sourceNode, targetNode, selected = false, zIndex = 0, elevateOnSelect = false, }) {
+    if (!elevateOnSelect) {
+        return zIndex;
     }
-    return edgeTree;
+    const edgeOrConnectedNodeSelected = selected || targetNode.selected || sourceNode.selected;
+    const selectedZIndex = Math.max(sourceNode[internalsSymbol]?.z || 0, targetNode[internalsSymbol]?.z || 0, 1000);
+    return zIndex + (edgeOrConnectedNodeSelected ? selectedZIndex : 0);
 }
 function isEdgeVisible({ sourceNode, targetNode, width, height, transform }) {
     const edgeBox = getBoundsOfBoxes(nodeToBox(sourceNode), nodeToBox(targetNode));
@@ -564,13 +685,21 @@ function isEdgeVisible({ sourceNode, targetNode, width, height, transform }) {
     };
     return getOverlappingArea(viewRect, boxToRect(edgeBox)) > 0;
 }
-const getEdgeId = ({ source, sourceHandle, target, targetHandle }) => `xyflow__edge-${source}${sourceHandle || ''}-${target}${targetHandle || ''}`;
+const getEdgeId = ({ source, sourceHandle, target, targetHandle }) => `xy-edge__${source}${sourceHandle || ''}-${target}${targetHandle || ''}`;
 const connectionExists = (edge, edges) => {
     return edges.some((el) => el.source === edge.source &&
         el.target === edge.target &&
         (el.sourceHandle === edge.sourceHandle || (!el.sourceHandle && !edge.sourceHandle)) &&
         (el.targetHandle === edge.targetHandle || (!el.targetHandle && !edge.targetHandle)));
 };
+/**
+ * This util is a convenience function to add a new Edge to an array of edges
+ * @remarks It also performs some validation to make sure you don't add an invalid edge or duplicate an existing one.
+ * @public
+ * @param edgeParams - Either an Edge or a Connection you want to add
+ * @param edges -  The array of all current edges
+ * @returns A new array of edges with the new edge added
+ */
 const addEdgeBase = (edgeParams, edges) => {
     if (!edgeParams.source || !edgeParams.target) {
         devWarn('006', errorMessages['error006']());
@@ -589,8 +718,22 @@ const addEdgeBase = (edgeParams, edges) => {
     if (connectionExists(edge, edges)) {
         return edges;
     }
+    if (edge.sourceHandle === null) {
+        delete edge.sourceHandle;
+    }
+    if (edge.targetHandle === null) {
+        delete edge.targetHandle;
+    }
     return edges.concat(edge);
 };
+/**
+ * A handy utility to update an existing Edge with new properties
+ * @param oldEdge - The edge you want to update
+ * @param newConnection - The new connection you want to update the edge with
+ * @param edges - The array of all current edges
+ * @param options.shouldReplaceId - should the id of the old edge be replaced with the new connection id
+ * @returns the updated edges array
+ */
 const updateEdgeBase = (oldEdge, newConnection, edges, options = { shouldReplaceId: true }) => {
     const { id: oldEdgeId, ...rest } = oldEdge;
     if (!newConnection.source || !newConnection.target) {
@@ -614,6 +757,26 @@ const updateEdgeBase = (oldEdge, newConnection, edges, options = { shouldReplace
     return edges.filter((e) => e.id !== oldEdgeId).concat(edge);
 };
 
+/**
+ * Get a straight path from source to target handle
+ * @param params.sourceX - The x position of the source handle
+ * @param params.sourceY - The y position of the source handle
+ * @param params.targetX - The x position of the target handle
+ * @param params.targetY - The y position of the target handle
+ * @returns A path string you can use in an SVG, the labelX and labelY position (center of path) and offsetX, offsetY between source handle and label
+ * @example
+ *  const source = { x: 0, y: 20 };
+    const target = { x: 150, y: 100 };
+    
+    const [path, labelX, labelY, offsetX, offsetY] = getStraightPath({
+      sourceX: source.x,
+      sourceY: source.y,
+      sourcePosition: Position.Right,
+      targetX: target.x,
+      targetY: target.y,
+      targetPosition: Position.Left,
+    });
+ */
 function getStraightPath({ sourceX, sourceY, targetX, targetY, }) {
     const [labelX, labelY, offsetX, offsetY] = getEdgeCenter({
         sourceX,
@@ -762,6 +925,28 @@ function getBend(a, b, c, size) {
     const yDir = a.y < c.y ? -1 : 1;
     return `L ${x},${y + bendSize * yDir}Q ${x},${y} ${x + bendSize * xDir},${y}`;
 }
+/**
+ * Get a smooth step path from source to target handle
+ * @param params.sourceX - The x position of the source handle
+ * @param params.sourceY - The y position of the source handle
+ * @param params.sourcePosition - The position of the source handle (default: Position.Bottom)
+ * @param params.targetX - The x position of the target handle
+ * @param params.targetY - The y position of the target handle
+ * @param params.targetPosition - The position of the target handle (default: Position.Top)
+ * @returns A path string you can use in an SVG, the labelX and labelY position (center of path) and offsetX, offsetY between source handle and label
+ * @example
+ *  const source = { x: 0, y: 20 };
+    const target = { x: 150, y: 100 };
+    
+    const [path, labelX, labelY, offsetX, offsetY] = getSmoothStepPath({
+      sourceX: source.x,
+      sourceY: source.y,
+      sourcePosition: Position.Right,
+      targetX: target.x,
+      targetY: target.y,
+      targetPosition: Position.Left,
+    });
+ */
 function getSmoothStepPath({ sourceX, sourceY, sourcePosition = Position.Bottom, targetX, targetY, targetPosition = Position.Top, borderRadius = 5, centerX, centerY, offset = 20, }) {
     const [points, labelX, labelY, offsetX, offsetY] = getPoints({
         source: { x: sourceX, y: sourceY },
@@ -785,18 +970,22 @@ function getSmoothStepPath({ sourceX, sourceY, sourcePosition = Position.Bottom,
     return [path, labelX, labelY, offsetX, offsetY];
 }
 
+function isNodeInitialized(node) {
+    return !!(node?.[internalsSymbol]?.handleBounds || node?.handles?.length) && !!(node?.computed?.width || node?.width);
+}
 function getEdgePosition(params) {
-    const [sourceNodeRect, sourceHandleBounds, isSourceValid] = getHandleDataByNode(params.sourceNode);
-    const [targetNodeRect, targetHandleBounds, isTargetValid] = getHandleDataByNode(params.targetNode);
-    if (!isSourceValid || !isTargetValid) {
+    const { sourceNode, targetNode } = params;
+    if (!isNodeInitialized(sourceNode) || !isNodeInitialized(targetNode)) {
         return null;
     }
+    const sourceHandleBounds = sourceNode[internalsSymbol]?.handleBounds || toHandleBounds(sourceNode.handles);
+    const targetHandleBounds = targetNode[internalsSymbol]?.handleBounds || toHandleBounds(targetNode.handles);
+    const sourceHandle = getHandle(sourceHandleBounds?.source ?? [], params.sourceHandle);
+    const targetHandle = getHandle(
     // when connection type is loose we can define all handles as sources and connect source -> source
-    const targetNodeHandles = params.connectionMode === ConnectionMode.Strict
-        ? targetHandleBounds.target
-        : (targetHandleBounds.target ?? []).concat(targetHandleBounds.source ?? []);
-    const sourceHandle = getHandle(sourceHandleBounds.source, params.sourceHandle);
-    const targetHandle = getHandle(targetNodeHandles, params.targetHandle);
+    params.connectionMode === ConnectionMode.Strict
+        ? targetHandleBounds?.target ?? []
+        : (targetHandleBounds?.target ?? []).concat(targetHandleBounds?.source ?? []), params.targetHandle);
     const sourcePosition = sourceHandle?.position || Position.Bottom;
     const targetPosition = targetHandle?.position || Position.Top;
     if (!sourceHandle || !targetHandle) {
@@ -807,8 +996,8 @@ function getEdgePosition(params) {
         }));
         return null;
     }
-    const { x: sourceX, y: sourceY } = getHandlePosition(sourcePosition, sourceNodeRect, sourceHandle);
-    const { x: targetX, y: targetY } = getHandlePosition(targetPosition, targetNodeRect, targetHandle);
+    const [sourceX, sourceY] = getHandlePosition(sourcePosition, sourceNode, sourceHandle);
+    const [targetX, targetY] = getHandlePosition(targetPosition, targetNode, targetHandle);
     return {
         sourceX,
         sourceY,
@@ -822,67 +1011,37 @@ function toHandleBounds(handles) {
     if (!handles) {
         return null;
     }
-    return handles.reduce((res, item) => {
-        item.width = item.width || 1;
-        item.height = item.height || 1;
-        if (item.type === 'source') {
-            res.source?.push(item);
+    const source = [];
+    const target = [];
+    for (const handle of handles) {
+        handle.width = handle.width || 1;
+        handle.height = handle.height || 1;
+        if (handle.type === 'source') {
+            source.push(handle);
         }
-        if (item.type === 'target') {
-            res.target?.push(item);
+        else if (handle.type === 'target') {
+            target.push(handle);
         }
-        return res;
-    }, {
-        source: [],
-        target: [],
-    });
-}
-function getHandleDataByNode(node) {
-    const handleBounds = node?.[internalsSymbol]?.handleBounds || toHandleBounds(node?.handles) || null;
-    const nodeWidth = node?.computed?.width || node?.width;
-    const nodeHeight = node?.computed?.height || node?.height;
-    const isValid = handleBounds &&
-        nodeWidth &&
-        nodeHeight &&
-        typeof node?.computed?.positionAbsolute?.x !== 'undefined' &&
-        typeof node?.computed?.positionAbsolute?.y !== 'undefined';
-    return [
-        {
-            x: node?.computed?.positionAbsolute?.x || 0,
-            y: node?.computed?.positionAbsolute?.y || 0,
-            width: nodeWidth || 0,
-            height: nodeHeight || 0,
-        },
-        handleBounds,
-        !!isValid,
-    ];
+    }
+    return {
+        source,
+        target,
+    };
 }
-function getHandlePosition(position, nodeRect, handle = null) {
-    const x = (handle?.x || 0) + nodeRect.x;
-    const y = (handle?.y || 0) + nodeRect.y;
-    const width = handle?.width || nodeRect.width;
-    const height = handle?.height || nodeRect.height;
+function getHandlePosition(position, node, handle = null) {
+    const x = (handle?.x ?? 0) + (node.computed?.positionAbsolute?.x ?? 0);
+    const y = (handle?.y ?? 0) + (node.computed?.positionAbsolute?.y ?? 0);
+    const width = handle?.width || (node?.computed?.width ?? node?.width ?? 0);
+    const height = handle?.height || (node?.computed?.height ?? node?.height ?? 0);
     switch (position) {
         case Position.Top:
-            return {
-                x: x + width / 2,
-                y,
-            };
+            return [x + width / 2, y];
         case Position.Right:
-            return {
-                x: x + width,
-                y: y + height / 2,
-            };
+            return [x + width, y + height / 2];
         case Position.Bottom:
-            return {
-                x: x + width / 2,
-                y: y + height,
-            };
+            return [x + width / 2, y + height];
         case Position.Left:
-            return {
-                x,
-                y: y + height / 2,
-            };
+            return [x, y + height / 2];
     }
 }
 function getHandle(bounds, handleId) {
@@ -979,10 +1138,13 @@ function updateAbsolutePositions(nodes, nodeLookup, nodeOrigin = [0, 0], parentN
                 ...node.position,
                 z: node[internalsSymbol]?.z ?? 0,
             }, parentNode?.origin || nodeOrigin);
-            node.computed.positionAbsolute = {
-                x,
-                y,
-            };
+            const positionChanged = x !== node.computed?.positionAbsolute?.x || y !== node.computed?.positionAbsolute?.y;
+            node.computed.positionAbsolute = positionChanged
+                ? {
+                    x,
+                    y,
+                }
+                : node.computed?.positionAbsolute;
             node[internalsSymbol].z = z;
             if (parentNodes?.[node.id]) {
                 node[internalsSymbol].isParent = true;
@@ -991,15 +1153,21 @@ function updateAbsolutePositions(nodes, nodeLookup, nodeOrigin = [0, 0], parentN
         return node;
     });
 }
-function updateNodes(nodes, nodeLookup, options = {
+function adoptUserProvidedNodes(nodes, nodeLookup, options = {
     nodeOrigin: [0, 0],
     elevateNodesOnSelect: true,
     defaults: {},
 }) {
+    const tmpLookup = new Map(nodeLookup);
+    nodeLookup.clear();
     const parentNodes = {};
     const selectedNodeZ = options?.elevateNodesOnSelect ? 1000 : 0;
     const nextNodes = nodes.map((n) => {
-        const currentStoreNode = nodeLookup.get(n.id);
+        const currentStoreNode = tmpLookup.get(n.id);
+        if (n === currentStoreNode?.[internalsSymbol]?.userProvidedNode) {
+            nodeLookup.set(n.id, currentStoreNode);
+            return currentStoreNode;
+        }
         const node = {
             ...options.defaults,
             ...n,
@@ -1019,6 +1187,7 @@ function updateNodes(nodes, nodeLookup, options = {
             value: {
                 handleBounds: currInternals?.handleBounds,
                 z,
+                userProvidedNode: n,
             },
         });
         nodeLookup.set(node.id, node);
@@ -1093,6 +1262,21 @@ function panBy({ delta, panZoom, transform, translateExtent, width, height, }) {
         (nextViewport.x !== transform[0] || nextViewport.y !== transform[1] || nextViewport.k !== transform[2]);
     return transformChanged;
 }
+function updateConnectionLookup(connectionLookup, edgeLookup, edges) {
+    connectionLookup.clear();
+    edgeLookup.clear();
+    for (const edge of edges) {
+        const { source, target, sourceHandle = null, targetHandle = null } = edge;
+        const sourceKey = `${source}-source-${sourceHandle}`;
+        const targetKey = `${target}-target-${targetHandle}`;
+        const prevSource = connectionLookup.get(sourceKey) || new Map();
+        const prevTarget = connectionLookup.get(targetKey) || new Map();
+        const connection = { source, target, sourceHandle, targetHandle };
+        edgeLookup.set(edge.id, edge);
+        connectionLookup.set(sourceKey, prevSource.set(`${target}-${targetHandle}`, connection));
+        connectionLookup.set(targetKey, prevTarget.set(`${source}-${sourceHandle}`, connection));
+    }
+}
 
 function wrapSelectionDragFunc(selectionFunc) {
     return (event, _, nodes) => selectionFunc?.(event, nodes);
@@ -1424,7 +1608,6 @@ function getConnectionStatus(isInsideConnectionRadius, isHandleValid) {
     return connectionStatus;
 }
 
-const nullConnection = { source: null, target: null, sourceHandle: null, targetHandle: null };
 const alwaysValid = () => true;
 let connectionStartHandle = null;
 function onPointerDown(event, { connectionMode, connectionRadius, handleId, nodeId, edgeUpdaterType, isTarget, domNode, nodes, lib, autoPanOnConnect, panBy, cancelConnection, onConnectStart, onConnect, onConnectEnd, isValidConnection = alwaysValid, onEdgeUpdateEnd, updateConnection, getTransform, }) {
@@ -1509,7 +1692,7 @@ function onPointerDown(event, { connectionMode, connectionRadius, handleId, node
         if (!closestHandle && !isValid && !handleDomNode) {
             return resetRecentHandle(prevActiveHandle, lib);
         }
-        if (connection.source !== connection.target && handleDomNode) {
+        if (connection?.source !== connection?.target && handleDomNode) {
             resetRecentHandle(prevActiveHandle, lib);
             prevActiveHandle = handleDomNode;
             handleDomNode.classList.add('connecting', `${lib}-flow__handle-connecting`);
@@ -1557,7 +1740,7 @@ function isValidHandle(event, { handle, connectionMode, fromNodeId, fromHandleId
     const result = {
         handleDomNode: handleToCheck,
         isValid: false,
-        connection: nullConnection,
+        connection: null,
         endHandle: null,
     };
     if (handleToCheck) {
@@ -1566,6 +1749,9 @@ function isValidHandle(event, { handle, connectionMode, fromNodeId, fromHandleId
         const handleId = handleToCheck.getAttribute('data-handleid');
         const connectable = handleToCheck.classList.contains('connectable');
         const connectableEnd = handleToCheck.classList.contains('connectableend');
+        if (!handleNodeId) {
+            return result;
+        }
         const connection = {
             source: isTarget ? handleNodeId : fromNodeId,
             sourceHandle: isTarget ? handleId : fromHandleId,
@@ -1614,8 +1800,7 @@ function XYMinimap({ domNode, panZoom, getTransform, getViewScale }) {
             if (event.sourceEvent.type !== 'mousemove' || !panZoom) {
                 return;
             }
-            // @TODO: how to calculate the correct next position? Math.max(1, transform[2]) is a workaround.
-            const moveScale = getViewScale() * Math.max(1, transform[2]) * (inversePan ? -1 : 1);
+            const moveScale = getViewScale() * Math.max(transform[2], Math.log(transform[2])) * (inversePan ? -1 : 1);
             const position = {
                 x: transform[0] - event.sourceEvent.movementX * moveScale,
                 y: transform[1] - event.sourceEvent.movementY * moveScale,
@@ -1988,4 +2173,4 @@ function XYPanZoom({ domNode, minZoom, maxZoom, translateExtent, viewport, onPan
     };
 }
 
-export { ConnectionLineType, ConnectionMode, MarkerType, PanOnScrollMode, Position, SelectionMode, XYDrag, XYHandle, XYMinimap, XYPanZoom, addEdgeBase, boxToRect, calcAutoPan, calcNextPosition, clamp, clampPosition, createMarkerIds, devWarn, elementSelectionKeys, errorMessages, fitView, getBezierEdgeCenter, getBezierPath, getBoundsOfBoxes, getBoundsOfRects, getConnectedEdgesBase, getDimensions, getEdgeCenter, getEdgePosition, getElementsToRemove, getEventPosition, getHandleBounds, getHostForElement, getIncomersBase, getMarkerId, getNodePositionWithOrigin, getNodeToolbarTransform, getNodesBounds, getNodesInside, getOutgoersBase, getOverlappingArea, getPointerPosition, getPositionWithOrigin, getSmoothStepPath, getStraightPath, getViewportForBounds, groupEdgesByZLevel, infiniteExtent, internalsSymbol, isEdgeBase, isEdgeVisible, isInputDOMNode, isMacOs, isMouseEvent, isNodeBase, isNumeric, isRectObject, nodeToBox, nodeToRect, panBy, pointToRendererPoint, rectToBox, rendererPointToPoint, snapPosition, updateAbsolutePositions, updateEdgeBase, updateNodeDimensions, updateNodes };
+export { ConnectionLineType, ConnectionMode, MarkerType, PanOnScrollMode, Position, SelectionMode, XYDrag, XYHandle, XYMinimap, XYPanZoom, addEdgeBase, adoptUserProvidedNodes, areConnectionMapsEqual, boxToRect, calcAutoPan, calcNextPosition, clamp, clampPosition, createMarkerIds, devWarn, elementSelectionKeys, errorMessages, fitView, getBezierEdgeCenter, getBezierPath, getBoundsOfBoxes, getBoundsOfRects, getConnectedEdgesBase, getDimensions, getEdgeCenter, getEdgePosition, getElementsToRemove, getElevatedEdgeZIndex, getEventPosition, getHandleBounds, getHostForElement, getIncomersBase, getMarkerId, getNodePositionWithOrigin, getNodeToolbarTransform, getNodesBounds, getNodesInside, getOutgoersBase, getOverlappingArea, getPointerPosition, getPositionWithOrigin, getSmoothStepPath, getStraightPath, getViewportForBounds, handleConnectionChange, infiniteExtent, internalsSymbol, isEdgeBase, isEdgeVisible, isInputDOMNode, isMacOs, isMouseEvent, isNodeBase, isNumeric, isRectObject, nodeToBox, nodeToRect, panBy, pointToRendererPoint, rectToBox, rendererPointToPoint, snapPosition, updateAbsolutePositions, updateConnectionLookup, updateEdgeBase, updateNodeDimensions };