@joint/core 4.1.3 → 4.2.0-alpha.1

package/src/V/traverse.mjs

@@ -0,0 +1,16 @@
+/**
+ * @param {SVGElement} node1
+ * @param {SVGElement} node2
+ * @returns {SVGElement|null}
+ * @description Finds the common ancestor node of two nodes.
+ */
+export function getCommonAncestor(node1, node2) {
+    // Find the common ancestor node of two nodes.
+    let parent = node1;
+    do {
+        if (parent.contains(node2)) return parent;
+        parent = parent.parentNode;
+    } while (parent);
+    return null;
+}
+

package/src/alg/Deque.mjs

@@ -0,0 +1,126 @@
+/**
+ * Deque implementation for managing a double-ended queue.
+ * This implementation uses a doubly linked list for efficient operations.
+ * It supports operations like push, pop, move to head, and delete.
+ * The deque maintains a map for O(1) access to nodes by key.
+ */
+export class Deque {
+    constructor() {
+        this.head = null;
+        this.tail = null;
+        this.map = new Map(); // key -> node
+    }
+
+    // Return an array of keys in the deque
+    keys() {
+        let current = this.head;
+        const keys = [];
+        while (current) {
+            keys.push(current.key);
+            current = current.next;
+        }
+        return keys;
+    }
+
+    // Return the first node and remove it from the deque
+    popHead() {
+        if (!this.head) return null;
+        const node = this.head;
+        this.map.delete(node.key);
+        this.head = node.next;
+        if (this.head) {
+            this.head.prev = null;
+        } else {
+            this.tail = null;
+        }
+        return node;
+    }
+
+    // Add a new node to the back of the deque
+    pushTail(key, value) {
+        if (this.map.has(key)) {
+            throw new Error(`Key "${key}" already exists in the deque.`);
+        }
+        const node = {
+            key,
+            value,
+            prev: null,
+            next: null
+        };
+        this.map.set(key, node);
+        if (!this.tail) {
+            this.head = this.tail = node;
+        } else {
+            this.tail.next = node;
+            node.prev = this.tail;
+            this.tail = node;
+        }
+    }
+
+    // Move a node from the deque to the head
+    moveToHead(key) {
+        const node = this.map.get(key);
+        if (!node) return;
+        if (node === this.head) return; // already at head
+        // Remove node from its current position
+        if (node.prev) node.prev.next = node.next;
+        if (node.next) node.next.prev = node.prev;
+        if (node === this.tail) this.tail = node.prev; // if it's the tail
+        if (node === this.head) this.head = node.next; // if it's the head
+        // Move node to head
+        node.prev = null;
+        node.next = this.head;
+        if (this.head) {
+            this.head.prev = node; // link old head back to new head
+        }
+        this.head = node; // update head to be the moved node
+        if (!this.tail) {
+            this.tail = node; // if it was the only node, set tail as well
+        }
+    }
+
+    // Return the first node without removing it
+    peekHead() {
+        return this.head || null;
+    }
+
+    // Move the head node to the back of the deque
+    rotate() {
+        if (!this.head || !this.head.next) return;
+        this.tail.next = this.head; // link tail to head
+        this.head.prev = this.tail; // link head back to tail
+        this.tail = this.head; // update tail to be the old head
+        this.head = this.head.next; // move head to the next node
+        this.tail.next = null; // set new tail's next to null
+        this.head.prev = null; // set new head's prev to null
+    }
+
+    // Remove a node from the deque
+    delete(key) {
+        const node = this.map.get(key);
+        if (!node) return;
+
+        if (node.prev) node.prev.next = node.next;
+        else this.head = node.next;
+
+        if (node.next) node.next.prev = node.prev;
+        else this.tail = node.prev;
+
+        this.map.delete(key);
+    }
+
+    // Does the deque contain a node with the given key?
+    has(key) {
+        return this.map.has(key);
+    }
+
+    // Get the node with the given key
+    get(key) {
+        return this.map.get(key) || null;
+    }
+
+    // Number of nodes in the deque
+    get length() {
+        return this.map.size;
+    }
+}

package/src/anchors/index.mjs

@@ -2,20 +2,112 @@ import * as util from '../util/index.mjs';
 import { toRad } from '../g/index.mjs';
 import { resolveRef } from '../linkAnchors/index.mjs';
 
+const Side = {
+    LEFT: 'left',
+    RIGHT: 'right',
+    TOP: 'top',
+    BOTTOM: 'bottom',
+};
+
+const SideMode = {
+    PREFER_HORIZONTAL: 'prefer-horizontal',
+    PREFER_VERTICAL: 'prefer-vertical',
+    HORIZONTAL: 'horizontal',
+    VERTICAL: 'vertical',
+    AUTO: 'auto',
+};
+
+function getModelBBoxFromConnectedLink(element, link, endType, rotate) {
+
+    const portId = link.get(endType).port;
+    if (element.hasPort(portId)) {
+        return element.getPortBBox(portId, { rotate });
+    }
+
+    return element.getBBox({ rotate });
+}
+
+function getMiddleSide(rect, point, opt) {
+
+    const { preferenceThreshold = 0, mode } = opt;
+    const { x, y } = point;
+    const { x: left , y: top, width, height } = rect;
+
+    switch (mode) {
+
+        case SideMode.PREFER_VERTICAL: {
+            const {
+                top: topThreshold,
+                bottom: bottomThreshold
+            } = util.normalizeSides(preferenceThreshold);
+            const bottom = top + height;
+            if (y > top - topThreshold && y < bottom + bottomThreshold) {
+                const cx = left + width / 2;
+                return (x < cx) ? Side.LEFT : Side.RIGHT;
+            }
+        }
+        // eslint-disable-next-line no-fallthrough
+        case SideMode.VERTICAL: {
+            const cy = top + height / 2;
+            return (y < cy) ? Side.TOP : Side.BOTTOM;
+        }
+
+        case SideMode.PREFER_HORIZONTAL: {
+            const {
+                left: leftThreshold,
+                right: rightThreshold
+            } = util.normalizeSides(preferenceThreshold);
+            const right = left + width;
+            if (x > left - leftThreshold && x < right + rightThreshold) {
+                const cy = top + height / 2;
+                return (y < cy) ? Side.TOP : Side.BOTTOM;
+            }
+        }
+        // eslint-disable-next-line no-fallthrough
+        case SideMode.HORIZONTAL: {
+            const cx = left + width / 2;
+            return (x < cx) ? Side.LEFT : Side.RIGHT;
+        }
+
+        case SideMode.AUTO:
+        default: {
+            return rect.sideNearestToPoint(point);
+        }
+    }
+}
+
 function bboxWrapper(method) {
 
-    return function(view, magnet, ref, opt) {
+    return function(elementView, magnet, ref, opt, endType, linkView) {
+
+        const rotate = !!opt.rotate;
+        const element = elementView.model;
+        const link = linkView.model;
+        const angle = element.angle();
+
+        let bbox, center;
+        if (opt.useModelGeometry) {
+            bbox = getModelBBoxFromConnectedLink(element, link, endType, !rotate);
+            center = bbox.center();
+        } else {
+            center = element.getCenter();
+            bbox = (rotate) ? elementView.getNodeUnrotatedBBox(magnet) : elementView.getNodeBBox(magnet);
+        }
 
-        var rotate = !!opt.rotate;
-        var bbox = (rotate) ? view.getNodeUnrotatedBBox(magnet) : view.getNodeBBox(magnet);
-        var anchor = bbox[method]();
+        const anchor = bbox[method]();
 
-        var dx = opt.dx;
+        let dx = opt.dx;
         if (dx) {
-            var dxPercentage = util.isPercentage(dx);
-            dx = parseFloat(dx);
+            const isDxPercentage = util.isPercentage(dx);
+            if (!isDxPercentage && util.isCalcExpression(dx)) {
+                // calc expression
+                dx = Number(util.evalCalcExpression(dx, bbox));
+            } else {
+                // percentage or a number
+                dx = parseFloat(dx);
+            }
             if (isFinite(dx)) {
-                if (dxPercentage) {
+                if (isDxPercentage) {
                     dx /= 100;
                     dx *= bbox.width;
                 }
@@ -23,12 +115,18 @@ function bboxWrapper(method) {
             }
         }
 
-        var dy = opt.dy;
+        let dy = opt.dy;
         if (dy) {
-            var dyPercentage = util.isPercentage(dy);
-            dy = parseFloat(dy);
+            const isDyPercentage = util.isPercentage(dy);
+            if (!isDyPercentage && util.isCalcExpression(dy)) {
+                // calc expression
+                dy = Number(util.evalCalcExpression(dy, bbox));
+            } else {
+                // percentage or a number
+                dy = parseFloat(dy);
+            }
             if (isFinite(dy)) {
-                if (dyPercentage) {
+                if (isDyPercentage) {
                     dy /= 100;
                     dy *= bbox.height;
                 }
@@ -36,19 +134,27 @@ function bboxWrapper(method) {
             }
         }
 
-        return (rotate) ? anchor.rotate(view.model.getBBox().center(), -view.model.angle()) : anchor;
+        return (rotate) ? anchor.rotate(center, -angle) : anchor;
     };
 }
 
-function _perpendicular(view, magnet, refPoint, opt) {
+function _perpendicular(elementView, magnet, refPoint, opt, endType, linkView) {
 
-    var angle = view.model.angle();
-    var bbox = view.getNodeBBox(magnet);
-    var anchor = bbox.center();
-    var topLeft = bbox.origin();
-    var bottomRight = bbox.corner();
+    const element = elementView.model;
+    const angle = element.angle();
 
-    var padding = opt.padding;
+    let bbox;
+    if (opt.useModelGeometry) {
+        bbox = getModelBBoxFromConnectedLink(element, linkView.model, endType, true);
+    } else {
+        bbox = elementView.getNodeBBox(magnet);
+    }
+
+    const anchor = bbox.center();
+    const topLeft = bbox.origin();
+    const bottomRight = bbox.corner();
+
+    let padding = opt.padding;
     if (!isFinite(padding)) padding = 0;
 
     if ((topLeft.y + padding) <= refPoint.y && refPoint.y <= (bottomRight.y - padding)) {
@@ -64,16 +170,17 @@ function _perpendicular(view, magnet, refPoint, opt) {
     return anchor;
 }
 
-function _midSide(view, magnet, refPoint, opt) {
-
+function _midSide(view, magnet, refPoint, opt, endType, linkView) {
     var rotate = !!opt.rotate;
-    var bbox, angle, center;
-    if (rotate) {
-        bbox = view.getNodeUnrotatedBBox(magnet);
-        center = view.model.getBBox().center();
-        angle = view.model.angle();
+    var angle = view.model.angle();
+    var center = view.model.getCenter();
+
+    var bbox;
+    if (opt.useModelGeometry) {
+        bbox = getModelBBoxFromConnectedLink(view.model, linkView.model, endType, !rotate);
+        center = bbox.center();
     } else {
-        bbox = view.getNodeBBox(magnet);
+        bbox =  rotate ? view.getNodeUnrotatedBBox(magnet) : view.getNodeBBox(magnet);
     }
 
     var padding = opt.padding;
@@ -81,19 +188,19 @@ function _midSide(view, magnet, refPoint, opt) {
 
     if (rotate) refPoint.rotate(center, angle);
 
-    var side = bbox.sideNearestToPoint(refPoint);
+    var side = getMiddleSide(bbox, refPoint, opt);
     var anchor;
     switch (side) {
-        case 'left':
+        case Side.LEFT:
             anchor = bbox.leftMiddle();
             break;
-        case 'right':
+        case Side.RIGHT:
             anchor = bbox.rightMiddle();
             break;
-        case 'top':
+        case Side.TOP:
             anchor = bbox.topMiddle();
             break;
-        case 'bottom':
+        case Side.BOTTOM:
             anchor = bbox.bottomMiddle();
             break;
     }

package/src/cellTools/Boundary.mjs

@@ -1,7 +1,7 @@
 
 import * as util from '../util/index.mjs';
 import { ToolView } from '../dia/ToolView.mjs';
-import { getViewBBox } from './helpers.mjs';
+import { getToolOptions, getViewBBox } from './helpers.mjs';
 
 export const Boundary = ToolView.extend({
     name: 'boundary',
@@ -21,21 +21,23 @@ export const Boundary = ToolView.extend({
         this.update();
     },
     update: function() {
-        const { relatedView: view, options, vel } = this;
-        const { useModelGeometry, rotate } = options;
-        const padding = util.normalizeSides(options.padding);
-        let bbox = getViewBBox(view, useModelGeometry).moveAndExpand({
-            x: -padding.left,
-            y: -padding.top,
-            width: padding.left + padding.right,
-            height: padding.top + padding.bottom
+        const { relatedView: view, vel } = this;
+        const { useModelGeometry, rotate, relative, padding } = getToolOptions(this);
+        const normalizedPadding = util.normalizeSides(padding);
+        let bbox = getViewBBox(view, { useModelGeometry, relative }).moveAndExpand({
+            x: -normalizedPadding.left,
+            y: -normalizedPadding.top,
+            width: normalizedPadding.left + normalizedPadding.right,
+            height: normalizedPadding.top + normalizedPadding.bottom
         });
-        var model = view.model;
-        if (model.isElement()) {
-            var angle = model.angle();
+        const model = view.model;
+        // With relative positioning, rotation is implicit
+        // (the tool rotates along with the element).
+        if (model.isElement() && !relative) {
+            const angle = model.angle();
             if (angle) {
                 if (rotate) {
-                    var origin = model.getBBox().center();
+                    const origin = model.getCenter();
                     vel.rotate(angle, origin.x, origin.y, { absolute: true });
                 } else {
                     bbox = bbox.bbox(angle);

package/src/cellTools/Button.mjs

@@ -1,5 +1,5 @@
 import { ToolView } from '../dia/ToolView.mjs';
-import { getViewBBox } from './helpers.mjs';
+import { getToolOptions, getViewBBox } from './helpers.mjs';
 import * as util from '../util/index.mjs';
 import * as g from '../g/index.mjs';
 import V from '../V/index.mjs';
@@ -32,9 +32,9 @@ export const Button = ToolView.extend({
         return this.relatedView.model.isLink() ? this.getLinkMatrix() : this.getElementMatrix();
     },
     getElementMatrix() {
-        const { relatedView: view, options } = this;
-        let { x = 0, y = 0, offset = {}, useModelGeometry, rotate, scale } = options;
-        let bbox = getViewBBox(view, useModelGeometry);
+        const { relatedView: view } = this;
+        let { x = 0, y = 0, offset = {}, useModelGeometry, rotate, scale, relative } = getToolOptions(this);
+        let bbox = getViewBBox(view, { useModelGeometry, relative });
         const angle = view.model.angle();
         if (!rotate) bbox = bbox.bbox(angle);
         const { x: offsetX = 0, y: offsetY = 0 } = offset;
@@ -49,7 +49,9 @@ export const Button = ToolView.extend({
             y = Number(util.evalCalcExpression(y, bbox));
         }
         let matrix = V.createSVGMatrix().translate(bbox.x + bbox.width / 2, bbox.y + bbox.height / 2);
-        if (rotate) matrix = matrix.rotate(angle);
+        // With relative positioning, rotation is implicit
+        // (the tool rotates along with the element).
+        if (rotate && !relative) matrix = matrix.rotate(angle);
         matrix = matrix.translate(x + offsetX - bbox.width / 2, y + offsetY - bbox.height / 2);
         if (scale) matrix = matrix.scale(scale);
         return matrix;

package/src/cellTools/Control.mjs

@@ -1,5 +1,6 @@
 import { ToolView } from '../dia/ToolView.mjs';
 import * as util from '../util/index.mjs';
+import { getToolOptions, getViewBBox } from './helpers.mjs';
 
 export const Control = ToolView.extend({
     tagName: 'g',
@@ -72,38 +73,60 @@ export const Control = ToolView.extend({
         return this;
     },
     updateHandle: function(handleNode) {
+        const { options: { handleAttributes }} = this;
+        handleNode.setAttribute('transform', this.getHandleTransformString());
+        if (handleAttributes) {
+            for (let attrName in handleAttributes) {
+                handleNode.setAttribute(attrName, handleAttributes[attrName]);
+            }
+        }
+    },
+    getHandleTransformString() {
         const { relatedView, options } = this;
+        const { scale } = options;
         const { model } = relatedView;
         const relativePos = this.getPosition(relatedView, this);
-        const absolutePos = model.getAbsolutePointFromRelative(relativePos);
-        const { handleAttributes, scale } = options;
-        let transformString =  `translate(${absolutePos.x},${absolutePos.y})`;
+        const translate = this.isOverlay()
+            // The tool is rendered in the coordinate system of the paper
+            ? model.getAbsolutePointFromRelative(relativePos)
+            // The tool is rendered in the coordinate system of the relatedView
+            : relativePos;
+        let transformString =  `translate(${translate.x},${translate.y})`;
         if (scale) {
             transformString += ` scale(${scale})`;
         }
-        handleNode.setAttribute('transform', transformString);
-        if (handleAttributes) {
-            for (let attrName in handleAttributes) {
-                handleNode.setAttribute(attrName, handleAttributes[attrName]);
-            }
-        }
+        return transformString;
     },
     updateExtras: function(extrasNode) {
         const { relatedView, options } = this;
-        const { selector } = this.options;
+        const { selector, relative, useModelGeometry } = getToolOptions(this);
         if (!selector) {
+            // Hide the extras if no selector is given.
             this.toggleExtras(false);
             return;
         }
-        const magnet = relatedView.findNode(selector);
-        if (!magnet) throw new Error('Control: invalid selector.');
+        // Get the size for the extras rectangle and update it.
+        let bbox;
+        if (useModelGeometry) {
+            if (selector !== 'root') {
+                // A selector other than null or `root` was provided.
+                console.warn('Control: selector will be ignored when `useModelGeometry` is used.');
+            }
+            bbox = getViewBBox(relatedView, { useModelGeometry, relative });
+        } else {
+            // The reference node for calculating the bounding box of the extras.
+            const el = relatedView.findNode(selector);
+            if (!el) throw new Error('Control: invalid selector.');
+            bbox = getViewBBox(relatedView, { el });
+        }
         let padding = options.padding;
         if (!isFinite(padding)) padding = 0;
-        const bbox = relatedView.getNodeUnrotatedBBox(magnet);
         const model = relatedView.model;
-        const angle = model.angle();
+        // With relative positioning, rotation is implicit
+        // (the tool rotates along with the element).
+        const angle = relative ? 0 : model.angle();
         const center = bbox.center();
-        if (angle) center.rotate(model.getBBox().center(), -angle);
+        if (angle) center.rotate(model.getCenter(), -angle);
         bbox.inflate(padding);
         extrasNode.setAttribute('x', -bbox.width / 2);
         extrasNode.setAttribute('y', -bbox.height / 2);

package/src/cellTools/HoverConnect.mjs

@@ -121,10 +121,14 @@ export const HoverConnect = Connect.extend({
         return V.createSVGMatrix();
     },
 
+    getTrackMatrixAbsolute() {
+        return this.getTrackMatrix();
+    },
+
     getTrackRatioFromEvent(evt) {
         const { relatedView, trackPath } = this;
         const localPoint = relatedView.paper.clientToLocalPoint(evt.clientX, evt.clientY);
-        const trackPoint = V.transformPoint(localPoint, this.getTrackMatrix().inverse());
+        const trackPoint = V.transformPoint(localPoint, this.getTrackMatrixAbsolute().inverse());
         return trackPath.closestPointLength(trackPoint);
     },
 

package/src/cellTools/helpers.mjs

@@ -1,9 +1,50 @@
 import * as connectionStrategies from '../connectionStrategies/index.mjs';
 
-export function getViewBBox(view, useModelGeometry) {
+/**
+ * Common helper for getting a cell view’s bounding box,
+ * configurable with `useModelGeometry`, `relative`, and `el`.
+ */
+export function getViewBBox(view, {
+    useModelGeometry = false,
+    relative = false,
+    el = view.el
+} = {}) {
     const { model } = view;
-    if (useModelGeometry) return model.getBBox();
-    return (model.isLink()) ? view.getConnection().bbox() : view.getNodeUnrotatedBBox(view.el);
+    let bbox;
+    if (useModelGeometry) {
+        // cell model bbox
+        bbox = model.getBBox();
+    } else if (model.isLink()) {
+        // link view bbox
+        bbox = view.getConnection().bbox();
+    } else {
+        // element view bbox
+        bbox = view.getNodeUnrotatedBBox(el);
+    }
+    if (relative) {
+        // Relative to the element position.
+        const position = model.position();
+        bbox.x -= position.x;
+        bbox.y -= position.y;
+    }
+    return bbox;
+}
+
+/**
+ * Retrieves the tool options.
+ * Automatically overrides `useModelGeometry` and `rotate`
+ * if the tool is positioned relative to the element.
+ */
+export function getToolOptions(toolView) {
+    // Positioning is relative if the tool is drawn within the element view.
+    const relative = !toolView.isOverlay();
+    const { useModelGeometry, rotate, ...otherOptions } = toolView.options;
+    return {
+        ...otherOptions,
+        useModelGeometry: useModelGeometry || relative,
+        rotate: rotate || relative,
+        relative,
+    };
 }
 
 export function getAnchor(coords, view, magnet) {

package/src/config/index.mjs

@@ -1,4 +1,12 @@
 export const config = {
+    // How the cell attributes are merged when `cell.prop()` is called.
+    // DEFAULT: the arrays are merged into the source array.
+    cellMergeStrategy: null,
+    // How the cell default attributes are merged with the attributes provided
+    // in the cell constructor.
+    // DEFAULT: the arrays are merged by replacing the source array
+    // with the destination array.
+    cellDefaultsMergeStrategy: null,
     // When set to `true` the cell selectors could be defined as CSS selectors.
     // If not, only JSON Markup selectors are taken into account.
     useCSSSelectors: false,

package/src/connectionPoints/index.mjs

@@ -78,10 +78,12 @@ function anchorConnectionPoint(line, _view, _magnet, opt) {
 
 function bboxIntersection(line, view, magnet, opt) {
 
-    var bbox = view.getNodeBBox(magnet);
+    const bbox = (opt.useModelGeometry)
+        ? getNodeModelBBox(view, magnet, true)
+        : view.getNodeBBox(magnet);
     if (opt.stroke) bbox.inflate(stroke(magnet) / 2);
-    var intersections = line.intersect(bbox);
-    var cp = (intersections)
+    const intersections = line.intersect(bbox);
+    const cp = (intersections)
         ? line.start.chooseClosest(intersections)
         : line.end;
     return offsetPoint(cp, line.start, opt.offset);
@@ -89,22 +91,35 @@ function bboxIntersection(line, view, magnet, opt) {
 
 function rectangleIntersection(line, view, magnet, opt) {
 
-    var angle = view.model.angle();
+    const angle = view.model.angle();
     if (angle === 0) {
         return bboxIntersection(line, view, magnet, opt);
     }
 
-    var bboxWORotation = view.getNodeUnrotatedBBox(magnet);
+    const bboxWORotation = (opt.useModelGeometry)
+        ? getNodeModelBBox(view, magnet, false)
+        : view.getNodeUnrotatedBBox(magnet);
     if (opt.stroke) bboxWORotation.inflate(stroke(magnet) / 2);
-    var center = bboxWORotation.center();
-    var lineWORotation = line.clone().rotate(center, angle);
-    var intersections = lineWORotation.setLength(1e6).intersect(bboxWORotation);
-    var cp = (intersections)
+    const center = bboxWORotation.center();
+    const lineWORotation = line.clone().rotate(center, angle);
+    const intersections = lineWORotation.setLength(1e6).intersect(bboxWORotation);
+    const cp = (intersections)
         ? lineWORotation.start.chooseClosest(intersections).rotate(center, -angle)
         : line.end;
     return offsetPoint(cp, line.start, opt.offset);
 }
 
+function getNodeModelBBox(elementView, magnet, rotate) {
+    const element = elementView.model;
+
+    const portId = elementView.findAttribute('port', magnet);
+    if (element.hasPort(portId)) {
+        return element.getPortBBox(portId, { rotate });
+    }
+
+    return element.getBBox({ rotate });
+}
+
 function findShapeNode(magnet) {
     if (!magnet) return null;
     var node = magnet;