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

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,

package/src/dia/Cell.mjs

@@ -32,7 +32,7 @@ import { Model } from '../mvc/Model.mjs';
 import { cloneCells } from '../util/cloneCells.mjs';
 import { attributes } from './attributes/index.mjs';
 import * as g from '../g/index.mjs';
-
+import { config } from '../config/index.mjs';
 
 // Cell base model.
 // --------------------------
@@ -78,12 +78,20 @@ export const Cell = Model.extend({
         if ((defaults = result(this, 'defaults'))) {
             //<custom code>
             // Replaced the call to _.defaults with util.merge.
-            const customizer = (options && options.mergeArrays === true) ? false : attributesMerger;
+            const customizer = (options && options.mergeArrays === true)
+                ? false
+                : config.cellDefaultsMergeStrategy || attributesMerger;
             attrs = merge({}, defaults, attrs, customizer);
             //</custom code>
         }
         this.set(attrs, options);
         this.changed = {};
+        if (options && options.portLayoutNamespace) {
+            this.portLayoutNamespace = options.portLayoutNamespace;
+        }
+        if (options && options.portLabelLayoutNamespace) {
+            this.portLabelLayoutNamespace = options.portLabelLayoutNamespace;
+        }
         this.initialize.apply(this, arguments);
     },
 
@@ -543,7 +551,11 @@ export const Cell = Model.extend({
         if (!opt.deep) {
             // Shallow cloning.
 
-            var clone = Model.prototype.clone.apply(this, arguments);
+            // Preserve the original's `portLayoutNamespace` and `portLabelLayoutNamespace`.
+            const clone = new this.constructor(this.attributes, {
+                portLayoutNamespace: this.portLayoutNamespace,
+                portLabelLayoutNamespace: this.portLabelLayoutNamespace
+            });
             // We don't want the clone to have the same ID as the original.
             clone.set(this.getIdAttribute(), this.generateId());
             // A shallow cloned element does not carry over the original embeds.
@@ -557,7 +569,7 @@ export const Cell = Model.extend({
         } else {
             // Deep cloning.
 
-            // For a deep clone, simply call `graph.cloneCells()` with the cell and all its embedded cells.
+            // For a deep clone, simply call `util.cloneCells()` with the cell and all its embedded cells.
             return toArray(cloneCells([this].concat(this.getEmbeddedCells({ deep: true }))));
         }
     },
@@ -630,7 +642,7 @@ export const Cell = Model.extend({
                 options.rewrite && unsetByPath(baseAttributes, path, '/');
 
                 // Merge update with the model attributes.
-                var attributes = merge(baseAttributes, update);
+                var attributes = merge(baseAttributes, update, config.cellMergeStrategy);
                 // Finally, set the property to the updated attributes.
                 return this.set(property, attributes[property], options);
 
@@ -653,7 +665,11 @@ export const Cell = Model.extend({
         const changedAttributes = {};
         for (const key in props) {
             // Merging the values of changed attributes with the current ones.
-            const { changedValue } = merge({}, { changedValue: this.attributes[key] }, { changedValue: props[key] });
+            const { changedValue } = merge(
+                merge({}, { changedValue: this.attributes[key] }),
+                { changedValue: props[key] },
+                config.cellMergeStrategy
+            );
             changedAttributes[key] = changedValue;
         }
 
@@ -952,9 +968,10 @@ export const Cell = Model.extend({
 
     getAttributeDefinition: function(attrName) {
 
-        var defNS = this.attributes;
-        var globalDefNS = attributes;
-        return (defNS && defNS[attrName]) || globalDefNS[attrName];
+        const defNS = this.attributes;
+        const globalDefNS = attributes;
+        const definition = (defNS && defNS[attrName]) || globalDefNS[attrName];
+        return definition !== undefined ? definition : null;
     },
 
     define: function(type, defaults, protoProps, staticProps) {
@@ -973,4 +990,3 @@ export const Cell = Model.extend({
         return Cell;
     }
 });
-

package/src/dia/CellView.mjs

@@ -1393,4 +1393,11 @@ Object.defineProperty(CellView.prototype, 'useCSSSelectors', {
     }
 });
 
+// Internal tag to identify this object as a cell view instance.
+// Used instead of `instanceof` for performance and cross-frame safety.
 
+export const CELL_VIEW_MARKER = Symbol('joint.cellViewMarker');
+
+Object.defineProperty(CellView.prototype, CELL_VIEW_MARKER, {
+    value: true,
+});

package/src/dia/Element.mjs

@@ -421,8 +421,10 @@ export const Element = Cell.extend({
 
         let minBBox = null;
         if (opt.minRect) {
-            // Coerce `opt.minRect` to g.Rect (missing properties = 0).
-            minBBox = new Rect(opt.minRect);
+            // Coerce `opt.minRect` to g.Rect
+            // (missing properties are taken from this element's current bbox).
+            const minRect = assign(this.getBBox(), opt.minRect);
+            minBBox = new Rect(minRect);
         }
 
         const elementsBBox = this.graph.getCellsBBox(opt.elements);

package/src/dia/ElementView.mjs

@@ -389,7 +389,8 @@ export const ElementView = CellView.extend({
             parent.unembed(element, { ui: true });
             data.initialParentId = parentId;
         } else {
-            data.initialParentId = null;
+            // `data.initialParentId` can be explicitly set to a dummy value to enable validation of unembedding.
+            data.initialParentId = data.initialParentId || null;
         }
     },
 

package/src/dia/HighlighterView.mjs

@@ -262,6 +262,28 @@ export const HighlighterView = mvc.View.extend({
         }
     },
 
+    // Check if the cellView has a highlighter with the given `id`.
+    // If no `id` is provided, it checks if the cellView has any highlighter.
+    has(cellView, id = null) {
+        const { cid } = cellView;
+        const { _views } = this;
+        const refs = _views[cid];
+        if (!refs) return false;
+        if (id === null) {
+            // any highlighter
+            for (let hid in refs) {
+                if (refs[hid] instanceof this) return true;
+            }
+            return false;
+        } else {
+            // single highlighter
+            if (id in refs) {
+                if (refs[id] instanceof this) return true;
+            }
+            return false;
+        }
+    },
+
     add(cellView, nodeSelector, id, opt = {}) {
         if (!id) throw new Error('dia.HighlighterView: An ID required.');
         // Search the existing view amongst all the highlighters