@peter.prib/renderengine 0.14.0 → 0.15.0

package/src/charting/modelTree/NavigatorModel.js

@@ -0,0 +1,410 @@
+import { treeLayerOf } from './ModelTreePanel.js';
+
+/**
+ * NavigatorModel — pure, DOM-free graph traversal and navigation engine for an ArchiMate model.
+ *
+ * Allows exploring relationships step-by-step from any focused root element to arbitrary depth,
+ * with cycle detection, navigation history (back/forward), direction filters, path-finding
+ * between elements, and transitive impact analysis.
+ */
+export class NavigatorModel {
+    /**
+     * @param {ArchimateModel} model
+     * @param {Object} [options]
+     * @param {string} [options.rootId] - Initial focused element id
+     * @param {'both'|'outgoing'|'incoming'} [options.direction='both']
+     * @param {Iterable<string>} [options.allowedKinds] - Optional relationship kinds to include
+     */
+    constructor(model, { rootId = null, direction = 'both', allowedKinds = null } = {}) {
+        this.model = model;
+        this.direction = direction;
+        this.allowedKinds = allowedKinds ? new Set(allowedKinds) : null;
+        this.pinned = false;
+
+        this.history = [];
+        this.historyIndex = -1;
+        this.currentId = null;
+
+        this.expandedPaths = new Set();
+        this._listeners = new Set();
+
+        if (rootId && model.getElement(rootId)) {
+            this.focus(rootId);
+        }
+    }
+
+    /** Register a listener called on state changes (focus, history, expansion, pin). */
+    onChange(listener) {
+        this._listeners.add(listener);
+        return () => this._listeners.delete(listener);
+    }
+
+    _notify() {
+        for (const listener of this._listeners) {
+            try {
+                listener(this);
+            } catch (err) {
+                console.warn('NavigatorModel listener error:', err);
+            }
+        }
+    }
+
+    // ── Navigation & History ──
+
+    /** Whether back navigation is available. */
+    get canBack() {
+        return this.historyIndex > 0;
+    }
+
+    /** Whether forward navigation is available. */
+    get canForward() {
+        return this.historyIndex < this.history.length - 1;
+    }
+
+    /**
+     * Focus on an element as the new root of the navigator.
+     * Pushes to history unless currently pinned or already focused.
+     * @param {string} elementId
+     * @param {Object} [options]
+     * @param {boolean} [options.force=false] - Ignore pinned state
+     * @returns {boolean} whether focus changed
+     */
+    focus(elementId, { force = false } = {}) {
+        if (!force && this.pinned && this.currentId) return false;
+        if (!elementId || elementId === this.currentId) return false;
+        const element = this.model.getElement(elementId);
+        if (!element) return false;
+
+        // Truncate forward history if we navigated from mid-stack
+        if (this.historyIndex < this.history.length - 1) {
+            this.history = this.history.slice(0, this.historyIndex + 1);
+        }
+
+        this.history.push(elementId);
+        this.historyIndex = this.history.length - 1;
+        this.currentId = elementId;
+        this.expandedPaths.clear();
+        this.expandedPaths.add(elementId); // root is expanded by default
+
+        this._notify();
+        return true;
+    }
+
+    /** Navigate back in history. */
+    back() {
+        if (!this.canBack) return false;
+        this.historyIndex--;
+        this.currentId = this.history[this.historyIndex];
+        this.expandedPaths.clear();
+        this.expandedPaths.add(this.currentId);
+        this._notify();
+        return true;
+    }
+
+    /** Navigate forward in history. */
+    forward() {
+        if (!this.canForward) return false;
+        this.historyIndex++;
+        this.currentId = this.history[this.historyIndex];
+        this.expandedPaths.clear();
+        this.expandedPaths.add(this.currentId);
+        this._notify();
+        return true;
+    }
+
+    /** Toggle pin state. When pinned, canvas selection changes won't re-root the navigator. */
+    togglePin() {
+        this.pinned = !this.pinned;
+        this._notify();
+        return this.pinned;
+    }
+
+    setDirection(direction) {
+        if (direction !== 'both' && direction !== 'outgoing' && direction !== 'incoming') return;
+        this.direction = direction;
+        this._notify();
+    }
+
+    setAllowedKinds(kinds) {
+        this.allowedKinds = kinds ? new Set(kinds) : null;
+        this._notify();
+    }
+
+    // ── Expansion State ──
+
+    isExpanded(pathKey) {
+        return this.expandedPaths.has(pathKey);
+    }
+
+    toggleExpand(pathKey) {
+        if (this.expandedPaths.has(pathKey)) {
+            this.expandedPaths.delete(pathKey);
+        } else {
+            this.expandedPaths.add(pathKey);
+        }
+        this._notify();
+    }
+
+    expand(pathKey) {
+        if (!this.expandedPaths.has(pathKey)) {
+            this.expandedPaths.add(pathKey);
+            this._notify();
+        }
+    }
+
+    collapse(pathKey) {
+        if (this.expandedPaths.has(pathKey)) {
+            this.expandedPaths.delete(pathKey);
+            this._notify();
+        }
+    }
+
+    collapseAll() {
+        this.expandedPaths.clear();
+        if (this.currentId) this.expandedPaths.add(this.currentId);
+        this._notify();
+    }
+
+    // ── Tree Construction ──
+
+    /**
+     * Build the multi-step navigation tree from the focused element,
+     * following expanded branches with cycle detection.
+     *
+     * @param {string} [rootId=this.currentId]
+     * @returns {Object|null}
+     */
+    buildTree(rootId = this.currentId) {
+        if (!rootId) return null;
+        const element = this.model.getElement(rootId);
+        if (!element) return null;
+
+        return this._buildNode(element, {
+            pathKey: rootId,
+            visitedInPath: new Set([rootId]),
+        });
+    }
+
+    /** @private */
+    _buildNode(element, { pathKey, visitedInPath }) {
+        const { incoming, outgoing } = this.neighbors(element.id);
+
+        const buildBranch = (rel, otherElement, dir) => {
+            const relKey = `${pathKey}:${dir}:${rel.id}:${otherElement.id}`;
+            const cycle = visitedInPath.has(otherElement.id);
+            const expanded = !cycle && this.isExpanded(relKey);
+
+            let children = null;
+            if (expanded) {
+                const nextVisited = new Set(visitedInPath);
+                nextVisited.add(otherElement.id);
+                children = this._buildNode(otherElement, {
+                    pathKey: relKey,
+                    visitedInPath: nextVisited,
+                });
+            }
+
+            return {
+                pathKey: relKey,
+                direction: dir,
+                relationship: rel,
+                element: otherElement,
+                layer: treeLayerOf(otherElement),
+                cycle,
+                expanded,
+                children,
+            };
+        };
+
+        const incomingBranches = (this.direction === 'both' || this.direction === 'incoming')
+            ? incoming.map(({ relationship, element: source }) => buildBranch(relationship, source, 'incoming'))
+            : [];
+
+        const outgoingBranches = (this.direction === 'both' || this.direction === 'outgoing')
+            ? outgoing.map(({ relationship, element: target }) => buildBranch(relationship, target, 'outgoing'))
+            : [];
+
+        return {
+            pathKey,
+            element,
+            layer: treeLayerOf(element),
+            views: this.model.viewsContaining(element.id),
+            incoming: incomingBranches,
+            outgoing: outgoingBranches,
+        };
+    }
+
+    /**
+     * Get immediate connected elements and relationships for an element.
+     * @param {string} elementId
+     * @returns {{ incoming: Array<{relationship: Object, element: Object}>, outgoing: Array<{relationship: Object, element: Object}> }}
+     */
+    neighbors(elementId) {
+        const { incoming, outgoing } = this.model.relationshipsFor(elementId);
+        const matchKind = (r) => !this.allowedKinds || this.allowedKinds.has(r.kind);
+
+        const inItems = incoming.filter(matchKind).map(rel => {
+            const source = this.model.getElement(rel.source);
+            return source ? { relationship: rel, element: source } : null;
+        }).filter(Boolean);
+
+        const outItems = outgoing.filter(matchKind).map(rel => {
+            const target = this.model.getElement(rel.target);
+            return target ? { relationship: rel, element: target } : null;
+        }).filter(Boolean);
+
+        return { incoming: inItems, outgoing: outItems };
+    }
+
+    // ── Graph Analysis: Path Finding & Impact Analysis ──
+
+    /**
+     * Find all simple paths between startId and endId up to maxDepth.
+     *
+     * @param {string} startId
+     * @param {string} endId
+     * @param {Object} [options]
+     * @param {number} [options.maxDepth=5]
+     * @param {'outgoing'|'both'|'incoming'} [options.direction='both']
+     * @param {Iterable<string>} [options.allowedKinds]
+     * @returns {Array<{ elements: Array<Object>, relationships: Array<Object>, length: number }>}
+     */
+    findPaths(startId, endId, { maxDepth = 5, direction = 'both', allowedKinds = null } = {}) {
+        const paths = [];
+        const start = this.model.getElement(startId);
+        const target = this.model.getElement(endId);
+        if (!start || !target || startId === endId) return paths;
+
+        const kinds = allowedKinds ? new Set(allowedKinds) : this.allowedKinds;
+        const matchKind = (r) => !kinds || kinds.has(r.kind);
+
+        const search = (currentId, currentElements, currentRels, visited) => {
+            if (currentElements.length - 1 > maxDepth) return;
+            if (currentId === endId) {
+                paths.push({
+                    elements: [...currentElements],
+                    relationships: [...currentRels],
+                    length: currentRels.length,
+                });
+                return;
+            }
+
+            const { incoming, outgoing } = this.model.relationshipsFor(currentId);
+
+            if (direction === 'both' || direction === 'outgoing') {
+                for (const rel of outgoing) {
+                    if (!matchKind(rel)) continue;
+                    const nextId = rel.target;
+                    if (!visited.has(nextId)) {
+                        const nextElem = this.model.getElement(nextId);
+                        if (!nextElem) continue;
+                        visited.add(nextId);
+                        currentElements.push(nextElem);
+                        currentRels.push(rel);
+                        search(nextId, currentElements, currentRels, visited);
+                        currentRels.pop();
+                        currentElements.pop();
+                        visited.delete(nextId);
+                    }
+                }
+            }
+
+            if (direction === 'both' || direction === 'incoming') {
+                for (const rel of incoming) {
+                    if (!matchKind(rel)) continue;
+                    const nextId = rel.source;
+                    if (!visited.has(nextId)) {
+                        const nextElem = this.model.getElement(nextId);
+                        if (!nextElem) continue;
+                        visited.add(nextId);
+                        currentElements.push(nextElem);
+                        currentRels.push(rel);
+                        search(nextId, currentElements, currentRels, visited);
+                        currentRels.pop();
+                        currentElements.pop();
+                        visited.delete(nextId);
+                    }
+                }
+            }
+        };
+
+        const visited = new Set([startId]);
+        search(startId, [start], [], visited);
+
+        // Sort by path length ascending
+        return paths.sort((a, b) => a.length - b.length);
+    }
+
+    /**
+     * Compute transitive impact or dependencies from an element.
+     *
+     * @param {string} elementId
+     * @param {Object} [options]
+     * @param {'outgoing'|'incoming'|'both'} [options.direction='outgoing']
+     * @param {number} [options.maxDepth=10]
+     * @param {Iterable<string>} [options.allowedKinds]
+     * @returns {{ root: Object, elements: Array<Object>, relationships: Array<Object>, depths: Map<string, number>, layers: Set<string> }}
+     */
+    traceImpact(elementId, { direction = 'outgoing', maxDepth = 10, allowedKinds = null } = {}) {
+        const root = this.model.getElement(elementId);
+        if (!root) return { root: null, elements: [], relationships: [], depths: new Map(), layers: new Set() };
+
+        const kinds = allowedKinds ? new Set(allowedKinds) : this.allowedKinds;
+        const matchKind = (r) => !kinds || kinds.has(r.kind);
+
+        const depths = new Map([[elementId, 0]]);
+        const elementsMap = new Map();
+        const relsMap = new Map();
+        const layers = new Set([treeLayerOf(root)]);
+
+        const queue = [{ id: elementId, depth: 0 }];
+
+        while (queue.length) {
+            const { id: currId, depth } = queue.shift();
+            if (depth >= maxDepth) continue;
+
+            const { incoming, outgoing } = this.model.relationshipsFor(currId);
+            const nextDepth = depth + 1;
+
+            if (direction === 'both' || direction === 'outgoing') {
+                for (const rel of outgoing) {
+                    if (!matchKind(rel)) continue;
+                    const target = this.model.getElement(rel.target);
+                    if (!target) continue;
+
+                    relsMap.set(rel.id, rel);
+                    if (!depths.has(target.id)) {
+                        depths.set(target.id, nextDepth);
+                        elementsMap.set(target.id, target);
+                        layers.add(treeLayerOf(target));
+                        queue.push({ id: target.id, depth: nextDepth });
+                    }
+                }
+            }
+
+            if (direction === 'both' || direction === 'incoming') {
+                for (const rel of incoming) {
+                    if (!matchKind(rel)) continue;
+                    const source = this.model.getElement(rel.source);
+                    if (!source) continue;
+
+                    relsMap.set(rel.id, rel);
+                    if (!depths.has(source.id)) {
+                        depths.set(source.id, nextDepth);
+                        elementsMap.set(source.id, source);
+                        layers.add(treeLayerOf(source));
+                        queue.push({ id: source.id, depth: nextDepth });
+                    }
+                }
+            }
+        }
+
+        return {
+            root,
+            elements: [...elementsMap.values()],
+            relationships: [...relsMap.values()],
+            depths,
+            layers,
+        };
+    }
+}