@joint/core 4.2.0-alpha.0 → 4.2.0-beta.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@joint/core",
   "title": "JointJS",
-  "version": "4.2.0-alpha.0",
+  "version": "4.2.0-beta.1",
   "description": "JavaScript diagramming library",
   "sideEffects": false,
   "main": "./dist/joint.min.js",
@@ -50,7 +50,7 @@
     "build-bundles": "grunt build:bundles",
     "test-e2e": "grunt test:e2e",
     "test-e2e-all": "grunt test:e2e:all",
-    "lint": "eslint src --ext .mjs,.js",
+    "lint": "eslint .",
     "lint-fix": "yarn run lint --fix",
     "dist": "grunt dist"
   },
@@ -66,17 +66,17 @@
   "devDependencies": {
     "@babel/core": "7.26.10",
     "@babel/preset-env": "7.26.9",
-    "@eslint/eslintrc": "3.3.1",
-    "@eslint/js": "9.23.0",
-    "@microsoft/api-extractor": "7.33.7",
+    "@eslint/js": "9.38.0",
+    "@microsoft/api-extractor": "7.52.10",
     "@rollup/plugin-babel": "^6.0.4",
-    "@typescript-eslint/eslint-plugin": "8.28.0",
-    "@typescript-eslint/parser": "8.27.0",
+    "@stylistic/eslint-plugin": "5.5.0",
+    "@typescript-eslint/eslint-plugin": "8.46.2",
+    "@typescript-eslint/parser": "8.46.2",
     "async": "2.6.1",
     "chai": "4.2.0",
     "core-js": "~3.8.3",
     "es-module-shims": "0.2.4",
-    "eslint": "9.23.0",
+    "eslint": "9.38.0",
     "express": "4.21.2",
     "globals": "16.0.0",
     "grunt": "1.6.1",
@@ -84,7 +84,7 @@
     "grunt-contrib-clean": "2.0.0",
     "grunt-contrib-concat": "1.0.1",
     "grunt-contrib-copy": "1.0.0",
-    "grunt-contrib-qunit": "3.1.0",
+    "grunt-contrib-qunit": "7.0.1",
     "grunt-contrib-uglify": "4.0.1",
     "grunt-contrib-watch": "1.1.0",
     "grunt-env": "0.4.4",
@@ -100,13 +100,13 @@
     "karma": "6.4.4",
     "karma-chrome-launcher": "3.2.0",
     "karma-coverage": "2.2.1",
-    "karma-qunit": "2.1.0",
+    "karma-qunit": "4.2.1",
     "karma-sinon": "1.0.5",
-    "load-grunt-config": "0.19.2",
+    "load-grunt-config": "4.0.1",
     "lodash": "~4.17.21",
     "mocha": "11.1.0",
-    "puppeteer": "24.4.0",
-    "qunit": "2.8.0",
+    "puppeteer": "24.22.0",
+    "qunit": "2.24.1",
     "requirejs": "2.3.6",
     "rollup": "4.36.0",
     "rollup-plugin-commonjs": "10.1.0",

package/src/V/index.mjs

@@ -118,8 +118,11 @@ const V = (function() {
     });
 
     /**
-     * @param {SVGGElement} toElem
-     * @returns {SVGMatrix}
+     * Calculates the transformation matrix from this element to the target element.
+     * @param {SVGElement|V} target - The target element.
+     * @param {Object} [opt] - Options object for transformation calculation.
+     * @param {boolean} [opt.safe] - Use a safe traversal method to compute the matrix.
+     * @returns {DOMMatrix} The transformation matrix from this element to the target element.
      */
     VPrototype.getTransformToElement = function(target, opt) {
         const node = this.node;
@@ -485,10 +488,19 @@ const V = (function() {
 
         if (content && typeof content !== 'string') throw new Error('Vectorizer: text() expects the first argument to be a string.');
 
-        // Replace all spaces with the Unicode No-break space (http://www.fileformat.info/info/unicode/char/a0/index.htm).
-        // IE would otherwise collapse all spaces into one.
-        content = V.sanitizeText(content);
         opt || (opt = {});
+
+        // Backwards-compatibility: if no content was provided, treat it as an
+        // empty string so that subsequent string operations (e.g. split) do
+        // not throw and behaviour matches the previous implementation that
+        // always sanitised the input.
+        if (content == null) content = '';
+
+        if (opt.useNoBreakSpace) {
+            // Replace all spaces with the Unicode No-break space (http://www.fileformat.info/info/unicode/char/a0/index.htm).
+            // IE would otherwise collapse all spaces into one.
+            content = V.sanitizeText(content);
+        }
         // Should we allow the text to be selected?
         var displayEmpty = opt.displayEmpty;
         // End of Line character
@@ -1332,6 +1344,9 @@ const V = (function() {
     // also exposed so that the programmer can use it in case he needs to. This is useful e.g. in tests
     // when you want to compare the actual DOM text content without having to add the unicode character in
     // the place of all spaces.
+    /**
+     * @deprecated Use regular spaces and rely on xml:space="preserve" instead.
+     */
     V.sanitizeText = function(text) {
 
         return (text || '').replace(/ /g, '\u00A0');

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/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.getCenter();
+                    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,36 +73,58 @@ 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.getCenter(), -angle);
         bbox.inflate(padding);

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,
@@ -8,5 +16,7 @@ export const config = {
     defaultTheme: 'default',
     // The maximum delay required for two consecutive touchend events to be interpreted
     // as a double-tap.
-    doubleTapInterval: 300
+    doubleTapInterval: 300,
+    // Name of the attribute used to store the layer id on the cell model.
+    layerAttribute: 'layer',
 };