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

package/src/dia/GraphLayer.mjs

@@ -0,0 +1,53 @@
+import { Model } from '../mvc/index.mjs';
+import { CellCollection } from './CellCollection.mjs';
+import { GRAPH_LAYER_MARKER } from './symbols.mjs';
+
+export const DEFAULT_GRAPH_LAYER_TYPE = 'GraphLayer';
+
+/**
+ * @class GraphLayer
+ * @description A GraphLayer is a model representing a single layer in a dia.Graph.
+ */
+export class GraphLayer extends Model {
+
+    [GRAPH_LAYER_MARKER] = true;
+
+    preinitialize() {
+        // This allows for propagating events from the inner `cellCollection` collection
+        // without any prefix and therefore distinguish them from the events
+        // fired by the GraphLayer model itself.
+        this.eventPrefix = 'layer:';
+    }
+
+    defaults() {
+        return {
+            type: DEFAULT_GRAPH_LAYER_TYPE
+        };
+    }
+
+    initialize(attrs, options = {}) {
+        super.initialize(attrs, options);
+
+        this.cellCollection = new CellCollection([], {
+            layer: this
+        });
+
+        // Forward all events from the inner `cellCollection` collection
+        this.cellCollection.on('all', this.trigger, this);
+        // Listen to cell changes to manage z-index sorting
+        this.cellCollection.on('change', this.onCellChange, this);
+    }
+
+    onCellChange(cell, opt) {
+        if (opt.sort === false || !cell.hasChanged('z')) return;
+        this.cellCollection.sort();
+    }
+
+    /**
+     * @public
+     * @description Returns all cells in this layer.
+     */
+    getCells() {
+        return this.cellCollection.toArray();
+    }
+}

package/src/dia/GraphLayerCollection.mjs

@@ -0,0 +1,313 @@
+import { Collection } from '../mvc/index.mjs';
+import { DEFAULT_GRAPH_LAYER_TYPE, GraphLayer } from './GraphLayer.mjs';
+import { CELL_MARKER, GRAPH_LAYER_MARKER, GRAPH_LAYER_COLLECTION_MARKER } from './symbols.mjs';
+import * as util from '../util/index.mjs';
+
+/**
+ * @class GraphLayerCollection
+ * @description A collection of layers used in dia.Graph. It facilitates creating layers from JSON using layerNamespace.
+ */
+export const GraphLayerCollection = Collection.extend({
+
+    defaultLayerNamespace: {
+        GraphLayer
+    },
+
+    /**
+     * @override
+     * @description Initializes the collection and sets up the layer and cell namespaces.
+     */
+    initialize: function(_models, options = {}) {
+        const { layerNamespace, cellNamespace, graph } = options;
+
+        // Initialize the namespace that holds all available layer classes.
+        // Custom namespaces are merged with the default ones.
+        this.layerNamespace = util.assign({}, this.defaultLayerNamespace, layerNamespace);
+
+        // Initialize the namespace for all cell model classes, if provided.
+        if (cellNamespace) {
+            this.cellNamespace = cellNamespace;
+        } else {
+            /* eslint-disable no-undef */
+            this.cellNamespace = typeof joint !== 'undefined' && util.has(joint, 'shapes') ? joint.shapes : null;
+            /* eslint-enable no-undef */
+        }
+
+        this.graph = graph;
+    },
+
+    /**
+     * @override
+     * @description Overrides the default `model` method
+     * to create layer models based on their `type` attribute.
+     */
+    model: function(attrs, opt) {
+
+        const collection = opt.collection;
+        const namespace = collection.layerNamespace;
+        const { type } = attrs;
+
+        // Find the model class based on the `type` attribute in the cell namespace
+        const GraphLayerClass = util.getByPath(namespace, type, '.');
+        if (!GraphLayerClass) {
+            throw new Error(`dia.Graph: Could not find layer constructor for type: '${type}'. Make sure to add the constructor to 'layerNamespace'.`);
+        }
+
+        return new GraphLayerClass(attrs, opt);
+    },
+
+    // Override to set graph reference
+    _addReference(layer, options) {
+        Collection.prototype._addReference.call(this, layer, options);
+
+        // assign graph and cellNamespace references
+        // to the added layer
+        layer.graph = this.graph;
+        layer.cellCollection.cellNamespace = this.cellNamespace;
+    },
+
+    // Override to remove graph reference
+    _removeReference(layer, options) {
+        Collection.prototype._removeReference.call(this, layer, options);
+
+        // remove graph and cellNamespace references
+        // from the removed layer
+        layer.graph = null;
+        layer.cellCollection.cellNamespace = null;
+    },
+
+    /**
+     * @override
+     * @description Overrides the default `_prepareModel` method
+     * to set default layer type if missing.
+     */
+    _prepareModel: function(attrs, options) {
+        if (!attrs[GRAPH_LAYER_MARKER]) {
+            // Add a mandatory `type` attribute if missing
+            if (!attrs.type) {
+                const preparedAttributes = util.clone(attrs);
+                preparedAttributes.type = DEFAULT_GRAPH_LAYER_TYPE;
+                arguments[0] = preparedAttributes;
+            }
+        }
+
+        return Collection.prototype._prepareModel.apply(this, arguments);
+    },
+
+    /**
+     * @override
+     * @description Add an assertion to prevent direct resetting of the collection.
+     */
+    reset(models, options) {
+        this._assertInternalCall(options);
+        return Collection.prototype.reset.apply(this, arguments);
+    },
+
+    /**
+     * @override
+     * @description Add an assertion to prevent direct addition of layers.
+     */
+    add(models, options) {
+        this._assertInternalCall(options);
+        return Collection.prototype.add.apply(this, arguments);
+    },
+
+    /**
+     * @override
+     * @description Add an assertion to prevent direct removal of layers.
+     */
+    remove(models, options){
+        this._assertInternalCall(options);
+        return Collection.prototype.remove.apply(this, arguments);
+    },
+
+    /**
+     * @override
+     * @description Overrides the default `_onModelEvent` method
+     * to distinguish between events coming from different model types.
+     */
+    _onModelEvent(_, model) {
+        if (model && model[CELL_MARKER]) {
+            // Do not filter cell `add` and `remove` events
+            // See `mvc.Collection` for more details
+            this.trigger.apply(this, arguments);
+            return;
+        }
+
+        // For other events, use the default behavior
+        Collection.prototype._onModelEvent.apply(this, arguments);
+    },
+
+    /**
+     * @protected
+     * @description Asserts that the collection manipulation
+     * is done via internal graph methods. Otherwise, it throws an error.
+     * This is a temporary measure until layers API is stabilized.
+     */
+    _assertInternalCall(options) {
+        if (options && !options.graph && !options.silent) {
+            throw new Error('dia.GraphLayerCollection: direct manipulation of the collection is not supported, use graph methods instead.');
+        }
+    },
+
+    /**
+     * @public
+     * @description Inserts a layer before another layer or at the end if `beforeLayerId` is null.
+     */
+    insert(layerInit, beforeLayerId = null, options = {}) {
+
+        const id = layerInit.id;
+        if (id === beforeLayerId) {
+            // Inserting before itself is a no-op
+            return;
+        }
+
+        if (beforeLayerId && !this.has(beforeLayerId)) {
+            throw new Error(`dia.GraphLayerCollection: Layer "${beforeLayerId}" does not exist`);
+        }
+
+        // See if the layer is already in the collection
+        let currentIndex = -1;
+        if (this.has(id)) {
+            currentIndex = this.findIndex(l => l.id === id);
+            if ((currentIndex === this.length - 1) && !beforeLayerId) {
+                // The layer is already at the end
+                return;
+            }
+            // Remove the layer from its current position
+            this.remove(id, { silent: true });
+        }
+
+        // At what index to insert the layer?
+        let insertAt;
+        if (!beforeLayerId) {
+            insertAt = this.length;
+        } else {
+            insertAt = this.findIndex(l => l.id === beforeLayerId);
+        }
+
+        if (currentIndex !== -1) {
+            // Re-insert the layer at the new position.
+            this.add(layerInit, {
+                at: insertAt,
+                silent: true
+            });
+            // Trigger `sort` event manually
+            // since we are not using collection sorting workflow
+            this.trigger('sort', this, options);
+        } else {
+            // Add to the collection and trigger an event
+            // when new layer has been added
+            this.add(layerInit, {
+                ...options,
+                at: insertAt,
+            });
+        }
+    },
+
+    /**
+     * @public
+     * @description Finds and returns a cell by its id from all layers.
+     */
+    getCell(cellRef) {
+        // TODO: should we create a map of cells for faster lookup?
+        for (const layer of this.models) {
+            const cell = layer.cellCollection.get(cellRef);
+            if (cell) {
+                return cell;
+            }
+        }
+        // Backward compatibility: return undefined if cell is not found
+        return undefined;
+    },
+
+    /**
+     * @public
+     * @description Returns all cells in all layers in the correct order.
+     */
+    getCells() {
+        const layers = this.models;
+        if (layers.length === 1) {
+            // Single layer:
+            // Fast path, just return the copy of the only layer's cells
+            return layers[0].getCells();
+        }
+        // Multiple layers:
+        // Each layer has its models sorted already, so we can just concatenate
+        // them in the order of layers.
+        const cells = [];
+        for (const layer of layers) {
+            Array.prototype.push.apply(cells, layer.cellCollection.models);
+        }
+        return cells;
+    },
+
+    /**
+     * @public
+     * @description Removes a cell from its current layer.
+     */
+    removeCell(cell, options = {}) {
+        const cellCollection = cell.collection?.layer?.cellCollection;
+        if (!cellCollection) return;
+        cellCollection.remove(cell, options);
+    },
+
+    /**
+     * @public
+     * @description Move a cell from its current layer to a target layer.
+     */
+    moveCellBetweenLayers(cell, targetLayerId, options = {}) {
+
+        const sourceLayer = cell.collection?.layer;
+        if (!sourceLayer) {
+            throw new Error('dia.GraphLayerCollection: cannot move a cell that is not part of any layer.');
+        }
+
+        const targetLayer = this.get(targetLayerId);
+        if (!targetLayer) {
+            throw new Error(`dia.GraphLayerCollection: cannot move cell to layer '${targetLayerId}' because such layer does not exist.`);
+        }
+
+        if (sourceLayer === targetLayer) {
+            // 1. The provided cell is already in the target layer
+            // 2. Implicit default layer vs. explicit default (or vice versa)
+            // No follow-up action needed
+            return;
+        }
+
+        const moveOptions = {
+            ...options,
+            fromLayer: sourceLayer.id,
+            toLayer: targetLayer.id
+        };
+        // Move the cell between the two layer collections
+        sourceLayer.cellCollection.remove(cell, moveOptions);
+        targetLayer.cellCollection.add(cell, moveOptions);
+        // Trigger a single `move` event to ease distinguishing layer moves
+        // from add/remove operations
+        cell.trigger('move', cell, moveOptions);
+    },
+
+    /**
+     * @public
+     * @description Adds a cell to the specified layer.
+     */
+    addCellToLayer(cell, layerId, options = {}) {
+        const targetLayer = this.get(layerId);
+        if (!targetLayer) {
+            throw new Error(`dia.GraphLayerCollection: layer "${layerId}" does not exist.`);
+        }
+
+        const addOptions = {
+            ...options,
+            toLayer: targetLayer.id
+        };
+        // Add the cell to the target layer collection
+        targetLayer.cellCollection.add(cell, addOptions);
+    }
+
+});
+
+Object.defineProperty(GraphLayerCollection.prototype, GRAPH_LAYER_COLLECTION_MARKER, {
+    value: true,
+});

package/src/dia/GraphLayerView.mjs

@@ -0,0 +1,128 @@
+import { LayerView } from './LayerView.mjs';
+import { sortElements } from '../util/index.mjs';
+import { addClassNamePrefix } from '../util/util.mjs';
+import { sortingTypes } from './Paper.mjs';
+import { GRAPH_LAYER_VIEW_MARKER } from './symbols.mjs';
+
+/**
+ * @class GraphLayerView
+ * @description A GraphLayerView is responsible for managing the rendering of cell views inside a layer.
+ * It listens to the corresponding GraphLayer model and updates the DOM accordingly.
+ * It uses dia.Paper sorting options to sort cell views in the DOM based on their `z` attribute.
+ */
+export const GraphLayerView = LayerView.extend({
+
+    SORT_DELAYING_BATCHES: ['add', 'to-front', 'to-back'],
+
+    style: {
+        webkitUserSelect: 'none',
+        userSelect: 'none'
+    },
+
+    graph: null,
+
+    init() {
+        LayerView.prototype.init.apply(this, arguments);
+        this.graph = this.model.graph;
+    },
+
+    className: function() {
+        const { id } = this.options;
+        return [
+            addClassNamePrefix(`${id}-layer`),
+            addClassNamePrefix('cells')
+        ].join(' ');
+    },
+
+    afterPaperReferenceSet(paper) {
+        this.listenTo(this.model, 'sort', this.onCellCollectionSort);
+        this.listenTo(this.model, 'change', this.onCellChange);
+        this.listenTo(this.model, 'move', this.onCellMove);
+        this.listenTo(this.graph, 'batch:stop', this.onGraphBatchStop);
+    },
+
+    beforePaperReferenceUnset() {
+        this.stopListening(this.model);
+        this.stopListening(this.graph);
+    },
+
+    onCellCollectionSort() {
+        if (this.graph.hasActiveBatch(this.SORT_DELAYING_BATCHES)) return;
+        this.sort();
+    },
+
+    onCellMove(cell, opt = {}) {
+        // When a cell is moved from one layer to another,
+        // request insertion of its view in the new layer.
+        this.paper.requestCellViewInsertion(cell, opt);
+    },
+
+    onCellChange(cell, opt) {
+        if (!cell.hasChanged('z')) return;
+        // Re-insert the cell view to maintain correct z-ordering
+        if (this.paper.options.sorting === sortingTypes.APPROX) {
+            this.paper.requestCellViewInsertion(cell, opt);
+        }
+    },
+
+    onGraphBatchStop(data) {
+        const name = data && data.batchName;
+        const sortDelayingBatches = this.SORT_DELAYING_BATCHES;
+        // After certain batches, sorting may be required
+        if (sortDelayingBatches.includes(name) && !this.graph.hasActiveBatch(sortDelayingBatches)) {
+            this.sort();
+        }
+    },
+
+    sort() {
+        this.assertPaperReference();
+        const { paper } = this;
+
+        if (!paper.isExactSorting()) {
+            // noop
+            return;
+        }
+        if (paper.isFrozen()) {
+            // sort views once unfrozen
+            paper._updates.sort = true;
+            return;
+        }
+        this.sortExact();
+    },
+
+    sortExact() {
+        // Run insertion sort algorithm in order to efficiently sort DOM elements according to their
+        // associated model `z` attribute.
+        const cellNodes = Array.from(this.el.children).filter(node => node.getAttribute('model-id'));
+        const cellCollection = this.model.cellCollection;
+
+        sortElements(cellNodes, function(a, b) {
+            const cellA = cellCollection.get(a.getAttribute('model-id'));
+            const cellB = cellCollection.get(b.getAttribute('model-id'));
+            const zA = cellA.attributes.z || 0;
+            const zB = cellB.attributes.z || 0;
+            return (zA === zB) ? 0 : (zA < zB) ? -1 : 1;
+        });
+    },
+
+    insertCellView(cellView) {
+        this.assertPaperReference();
+        const { paper } = this;
+        const { el, model } = cellView;
+
+        switch (paper.options.sorting) {
+            case sortingTypes.APPROX:
+                this.insertSortedNode(el, model.get('z'));
+                break;
+            case sortingTypes.EXACT:
+            default:
+                this.insertNode(el);
+                break;
+        }
+    },
+
+});
+
+Object.defineProperty(GraphLayerView.prototype, GRAPH_LAYER_VIEW_MARKER, {
+    value: true,
+});

package/src/dia/GraphLayersController.mjs

@@ -0,0 +1,166 @@
+import { Listener } from '../mvc/Listener.mjs';
+import { config } from '../config/index.mjs';
+import { CELL_MARKER, CELL_COLLECTION_MARKER, GRAPH_LAYER_MARKER, GRAPH_LAYER_COLLECTION_MARKER } from './symbols.mjs';
+
+/**
+ * @class GraphLayersController
+ * @description Coordinates interactions between the graph and its layers.
+ * Automatically moves cells between layers when the layer attribute changes.
+ */
+export class GraphLayersController extends Listener {
+
+    constructor(options) {
+        super(options);
+
+        // Make sure there are no arguments passed to the callbacks.
+        // See the `mvc.Listener` documentation for more details.
+        this.callbackArguments = [];
+
+        const graph = options.graph;
+        if (!graph) {
+            throw new Error('GraphLayersController: "graph" option is required.');
+        }
+
+        this.graph = graph;
+        this.layerCollection = graph.layerCollection;
+
+        this.startListening();
+    }
+
+    startListening() {
+        // Handle all events from the layer collection and its inner cell collections.
+        this.listenTo(this.layerCollection, 'all', this.onLayerCollectionEvent);
+    }
+
+    /**
+     * @description When a cell changes its layer attribute,
+     * move the cell to the target layer.
+     */
+    onCellChange(cell, options) {
+        if (!cell.hasChanged(config.layerAttribute)) return;
+        // Move the cell to the appropriate layer
+        const targetLayerId = this.graph.getCellLayerId(cell);
+        this.layerCollection.moveCellBetweenLayers(cell, targetLayerId, options);
+    }
+
+    /**
+     * @description When a cell is removed from a layer,
+     * also remove its embeds and connected links from the graph.
+     * Note: an embedded cell might come from a different layer,
+     * so we can not use the layer's cell collection to remove it.
+     */
+    onCellRemove(cell, options) {
+        // If the cell is being moved from one layer to another,
+        // no further action is needed.
+        if (options.fromLayer) return;
+
+        // When replacing a cell, we do not want to remove its embeds or
+        // unembed it from its parent.
+        if (options.replace) return;
+
+        // First, unembed this cell from its parent cell if there is one.
+        const parentCell = cell.getParentCell();
+        if (parentCell) {
+            parentCell.unembed(cell, options);
+        }
+
+        // Remove also all the cells, which were embedded into this cell
+        const embeddedCells = cell.getEmbeddedCells();
+        for (let i = 0, n = embeddedCells.length; i < n; i++) {
+            const embed = embeddedCells[i];
+            if (embed) {
+                this.layerCollection.removeCell(embed, options);
+            }
+        }
+
+        // When not clearing the whole graph or replacing the cell,
+        // we don't want to remove the connected links.
+        if (!options.clear) {
+
+            // Applications might provide a `disconnectLinks` option set to `true` in order to
+            // disconnect links when a cell is removed rather then removing them. The default
+            // is to remove all the associated links.
+            if (options.disconnectLinks) {
+                this.graph.disconnectLinks(cell, options);
+            } else {
+                this.graph.removeLinks(cell, options);
+            }
+        }
+    }
+
+    onLayerCollectionEvent(eventName, model) {
+        if (!model) return;
+
+        if (model[CELL_MARKER]) {
+            // First handle cell-specific cases that require custom processing,
+            // then forward the event to the graph.
+            // For example, when a cell is removed from a layer, its embeds and
+            // connected links must be removed as well. Listeners on the graph
+            // should receive removal notifications in the following order:
+            // embeds → links → cell.
+            switch (eventName) {
+                case 'change': /* ('change', cell, options) */
+                    this.onCellChange.call(this, model, arguments[2]);
+                    break;
+                case 'remove': /* ('remove', cell, collection, options) */
+                    // When a cell is removed from a layer,
+                    // ensure it is also removed from the graph.
+                    this.onCellRemove.call(this, model, arguments[3]);
+                    break;
+            }
+            // Notify the graph about cell events.
+            this.forwardCellEvent.apply(this, arguments);
+            return;
+        }
+
+        if (model[CELL_COLLECTION_MARKER]) {
+            this.forwardCellCollectionEvent.apply(this, arguments);
+            return;
+        }
+
+        if (model[GRAPH_LAYER_MARKER]) {
+            this.forwardLayerEvent.apply(this, arguments);
+            return;
+        }
+
+        if (model[GRAPH_LAYER_COLLECTION_MARKER]) {
+            this.forwardLayerCollectionEvent.apply(this, arguments);
+            return;
+        }
+    }
+
+    forwardLayerEvent() {
+        // Note: the layer event prefix is `layer:`
+        this.graph.trigger.apply(this.graph, arguments);
+    }
+
+    forwardCellEvent(eventName, cell) {
+        // Moving a cell from one layer to another is an internal operation
+        // that should not be exposed at the graph level.
+        // The single `move` event is triggered instead.
+        if ((eventName === 'remove' || eventName === 'add') && arguments[3]?.fromLayer) return;
+
+        this.graph.trigger.apply(this.graph, arguments);
+    }
+
+    forwardCellCollectionEvent(eventName) {
+        // Do not forward `layer:remove` or `layer:sort` events to the graph
+        if (eventName !== 'sort') return;
+        // Backwards compatibility:
+        // Trigger 'sort' event for cell collection 'sort' events
+        this.graph.trigger.apply(this.graph, arguments);
+    }
+
+    forwardLayerCollectionEvent(eventName) {
+        if (eventName === 'reset') {
+            // Currently, there is no need to forward `layers:reset` event.
+            // The graph `fromJSON()` triggers a single `reset` event after
+            // resetting cells, layers and attributes.
+            return;
+        }
+        // Forward layer collection events with `layers:` prefix.
+        // For example `layers:reset` event when the layer collection is reset
+        arguments[0] = 'layers:' + arguments[0];
+        this.graph.trigger.apply(this.graph, arguments);
+    }
+}