@grafloria/element 0.3.18 → 0.3.20

package/src/libs/engine/src/layout/algorithms/ForceDirectedLayoutAlgorithm.js

@@ -0,0 +1,317 @@
+"use strict";
+// ForceDirectedLayoutAlgorithm - Physics-based layout using force simulation
+// Based on Fruchterman-Reingold algorithm
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ForceDirectedLayoutAlgorithm = void 0;
+const ILayoutAlgorithm_1 = require("../ILayoutAlgorithm");
+const ViewportTransform_1 = require("../ViewportTransform");
+const SmartSpacingCalculator_1 = require("../SmartSpacingCalculator");
+/**
+ * ForceDirectedLayoutAlgorithm
+ *
+ * Physics-based layout where:
+ * - Nodes repel each other (like magnets with same poles)
+ * - Connected nodes attract each other (like springs)
+ * - System settles into equilibrium over iterations
+ *
+ * Best for:
+ * - Network diagrams
+ * - Social graphs
+ * - Relationship visualizations
+ * - Organic, natural-looking layouts
+ */
+class ForceDirectedLayoutAlgorithm extends ILayoutAlgorithm_1.BaseLayoutAlgorithm {
+    constructor(options) {
+        super();
+        this.forceOptions = Object.assign({ iterations: 50, repulsionStrength: 1.0, attractionStrength: 0.05, damping: 0.85, temperature: 10, coolingFactor: 0.95, minDistance: 50, maxDistance: 500, centerGravity: 0.05 }, options);
+    }
+    getName() {
+        return 'Force-Directed Layout';
+    }
+    getType() {
+        return 'force-directed';
+    }
+    configure(config) {
+        if (config.options) {
+            this.forceOptions = Object.assign(Object.assign({}, this.forceOptions), config.options);
+        }
+    }
+    getConfiguration() {
+        return {
+            type: 'force-directed',
+            options: this.forceOptions,
+        };
+    }
+    canApply(diagram) {
+        const nodes = diagram.getNodes();
+        if (nodes.length === 0) {
+            return { valid: false, reason: 'No nodes to layout' };
+        }
+        if (nodes.length > 200) {
+            return {
+                valid: true,
+                reason: 'Warning: Force-directed layout may be slow with many nodes. Consider using Grid or Hierarchical layout.'
+            };
+        }
+        return { valid: true };
+    }
+    calculatePlacement(options) {
+        var _a, _b, _c, _d, _e, _f;
+        const { node, viewport, existingNodes, preferredPosition, spacing = 100 } = options;
+        // If there are no existing nodes, place in center
+        if (existingNodes.length === 0) {
+            const centerX = viewport.x + viewport.width / 2 - (((_a = node.size) === null || _a === void 0 ? void 0 : _a.width) || 200) / 2;
+            const centerY = viewport.y + viewport.height / 2 - (((_b = node.size) === null || _b === void 0 ? void 0 : _b.height) || 100) / 2;
+            return {
+                position: { x: centerX, y: centerY },
+                success: true,
+                metadata: { reason: 'First node placed in center' },
+            };
+        }
+        // If preferred position provided and no collision, use it
+        if (preferredPosition) {
+            const hasCol = this.hasCollision(preferredPosition, { width: ((_c = node.size) === null || _c === void 0 ? void 0 : _c.width) || 200, height: ((_d = node.size) === null || _d === void 0 ? void 0 : _d.height) || 100 }, existingNodes, spacing);
+            if (!hasCol) {
+                return {
+                    position: preferredPosition,
+                    success: true,
+                    metadata: { reason: 'Preferred position used' },
+                };
+            }
+        }
+        // Calculate center of mass of existing nodes
+        let centerX = 0;
+        let centerY = 0;
+        existingNodes.forEach((n) => {
+            var _a, _b;
+            centerX += n.position.x + (((_a = n.size) === null || _a === void 0 ? void 0 : _a.width) || 200) / 2;
+            centerY += n.position.y + (((_b = n.size) === null || _b === void 0 ? void 0 : _b.height) || 100) / 2;
+        });
+        centerX /= existingNodes.length;
+        centerY /= existingNodes.length;
+        // Place new node near center of mass, avoiding collisions
+        const nodeWidth = ((_e = node.size) === null || _e === void 0 ? void 0 : _e.width) || 200;
+        const nodeHeight = ((_f = node.size) === null || _f === void 0 ? void 0 : _f.height) || 100;
+        // Try positions in a spiral pattern around center of mass
+        const maxAttempts = 50;
+        const angleStep = (Math.PI * 2) / 12; // 12 positions per ring
+        let distance = spacing * 1.5;
+        for (let attempt = 0; attempt < maxAttempts; attempt++) {
+            const ring = Math.floor(attempt / 12);
+            const angleIndex = attempt % 12;
+            const angle = angleIndex * angleStep + (ring * angleStep / 2); // Offset each ring
+            const testX = centerX + Math.cos(angle) * distance - nodeWidth / 2;
+            const testY = centerY + Math.sin(angle) * distance - nodeHeight / 2;
+            const hasCol = this.hasCollision({ x: testX, y: testY }, { width: nodeWidth, height: nodeHeight }, existingNodes, spacing);
+            if (!hasCol) {
+                return {
+                    position: { x: testX, y: testY },
+                    success: true,
+                    metadata: {
+                        reason: 'Placed near center of mass',
+                        attempt: attempt + 1,
+                    },
+                };
+            }
+            // Increase distance for next ring
+            if ((attempt + 1) % 12 === 0) {
+                distance += spacing;
+            }
+        }
+        // Fallback: place to the right of rightmost node
+        const rightmost = existingNodes.reduce((max, n) => { var _a; return Math.max(max, n.position.x + (((_a = n.size) === null || _a === void 0 ? void 0 : _a.width) || 200)); }, 0);
+        return {
+            position: { x: rightmost + spacing, y: centerY - nodeHeight / 2 },
+            success: true,
+            metadata: { reason: 'Fallback position used' },
+        };
+    }
+    reLayout(diagram, config) {
+        if (config) {
+            this.configure(config);
+        }
+        const nodes = diagram.getNodes();
+        const links = diagram.getLinks();
+        const positions = new Map();
+        if (nodes.length === 0) {
+            return positions;
+        }
+        // Initialize node forces with current or random positions
+        const nodeForces = nodes.map((node) => {
+            // Use existing position if available, otherwise random
+            const hasPosition = node.position && (node.position.x !== 0 || node.position.y !== 0);
+            const position = hasPosition
+                ? { x: node.position.x, y: node.position.y }
+                : {
+                    x: Math.random() * 1000,
+                    y: Math.random() * 800,
+                };
+            return {
+                node,
+                position,
+                velocity: { x: 0, y: 0 },
+                force: { x: 0, y: 0 },
+            };
+        });
+        // Build adjacency map for quick lookup
+        const adjacency = new Map();
+        links.forEach((link) => {
+            if (link.sourceNodeId && link.targetNodeId) {
+                if (!adjacency.has(link.sourceNodeId)) {
+                    adjacency.set(link.sourceNodeId, new Set());
+                }
+                if (!adjacency.has(link.targetNodeId)) {
+                    adjacency.set(link.targetNodeId, new Set());
+                }
+                adjacency.get(link.sourceNodeId).add(link.targetNodeId);
+                adjacency.get(link.targetNodeId).add(link.sourceNodeId);
+            }
+        });
+        // Phase 0.5: Use viewport from config if provided, otherwise fallback to default
+        const viewport = (config === null || config === void 0 ? void 0 : config.viewport) || { x: 0, y: 0, width: 1200, height: 800 };
+        // Calculate smart spacing for force-directed layout
+        const smartSpacing = (0, SmartSpacingCalculator_1.calculateForceDirectedSmartSpacing)({
+            viewport,
+            nodeCount: nodes.length,
+            zoom: viewport.zoom || 1.0, // Zoom might be on viewport from config
+        });
+        // Calculate optimal k (ideal spring length) based on smart spacing
+        // k represents the ideal distance between connected nodes
+        const area = viewport.width * viewport.height;
+        const baseK = Math.sqrt(area / nodes.length);
+        const k = baseK * (smartSpacing.horizontal / 36); // Scale by spacing factor
+        console.log(`🧲 Force-Directed: ${nodes.length} nodes, k=${k.toFixed(2)}, area=${area}, spacing=${smartSpacing.horizontal}px`);
+        // Simulation parameters
+        let temperature = this.forceOptions.temperature || 100;
+        const coolingFactor = this.forceOptions.coolingFactor || 0.95;
+        const iterations = this.forceOptions.iterations || 100;
+        // Run force-directed simulation
+        for (let iter = 0; iter < iterations; iter++) {
+            // Reset forces
+            nodeForces.forEach((nf) => {
+                nf.force.x = 0;
+                nf.force.y = 0;
+            });
+            // Calculate repulsive forces (all pairs)
+            for (let i = 0; i < nodeForces.length; i++) {
+                for (let j = i + 1; j < nodeForces.length; j++) {
+                    const nf1 = nodeForces[i];
+                    const nf2 = nodeForces[j];
+                    const dx = nf2.position.x - nf1.position.x;
+                    const dy = nf2.position.y - nf1.position.y;
+                    const distance = Math.sqrt(dx * dx + dy * dy) || 1; // Avoid division by zero
+                    // Fruchterman-Reingold repulsion: fr(d) = k^2 / d
+                    // Scale k by repulsionStrength for tuning
+                    const kScaled = k * (this.forceOptions.repulsionStrength || 1.0);
+                    const repulsionForce = (kScaled * kScaled) / distance;
+                    const fx = (dx / distance) * repulsionForce;
+                    const fy = (dy / distance) * repulsionForce;
+                    nf1.force.x -= fx;
+                    nf1.force.y -= fy;
+                    nf2.force.x += fx;
+                    nf2.force.y += fy;
+                }
+            }
+            // Calculate attractive forces (connected nodes)
+            links.forEach((link) => {
+                if (!link.sourceNodeId || !link.targetNodeId)
+                    return;
+                const nf1 = nodeForces.find((nf) => nf.node.id === link.sourceNodeId);
+                const nf2 = nodeForces.find((nf) => nf.node.id === link.targetNodeId);
+                if (!nf1 || !nf2)
+                    return;
+                const dx = nf2.position.x - nf1.position.x;
+                const dy = nf2.position.y - nf1.position.y;
+                const distance = Math.sqrt(dx * dx + dy * dy) || 1;
+                // Fruchterman-Reingold attraction: fa(d) = d^2 / k
+                // Scale by attractionStrength for tuning
+                const kAttr = k / (this.forceOptions.attractionStrength || 1.0);
+                const attractionForce = (distance * distance) / kAttr;
+                const fx = (dx / distance) * attractionForce;
+                const fy = (dy / distance) * attractionForce;
+                nf1.force.x += fx;
+                nf1.force.y += fy;
+                nf2.force.x -= fx;
+                nf2.force.y -= fy;
+            });
+            // Apply center gravity (keep nodes from drifting too far)
+            const centerGravity = this.forceOptions.centerGravity || 0.1;
+            const centerX = viewport.width / 2;
+            const centerY = viewport.height / 2;
+            nodeForces.forEach((nf) => {
+                const dx = centerX - nf.position.x;
+                const dy = centerY - nf.position.y;
+                nf.force.x += dx * centerGravity;
+                nf.force.y += dy * centerGravity;
+            });
+            // Update positions using velocity Verlet integration
+            const damping = this.forceOptions.damping || 0.9;
+            nodeForces.forEach((nf) => {
+                // Limit force magnitude to temperature
+                const forceMag = Math.sqrt(nf.force.x * nf.force.x + nf.force.y * nf.force.y);
+                if (forceMag > temperature) {
+                    nf.force.x = (nf.force.x / forceMag) * temperature;
+                    nf.force.y = (nf.force.y / forceMag) * temperature;
+                }
+                // Update velocity with damping
+                nf.velocity.x = (nf.velocity.x + nf.force.x) * damping;
+                nf.velocity.y = (nf.velocity.y + nf.force.y) * damping;
+                // Update position
+                nf.position.x += nf.velocity.x;
+                nf.position.y += nf.velocity.y;
+                // Prevent positions from exploding - clamp to reasonable bounds
+                const maxCoord = 10000;
+                nf.position.x = Math.max(-maxCoord, Math.min(maxCoord, nf.position.x));
+                nf.position.y = Math.max(-maxCoord, Math.min(maxCoord, nf.position.y));
+            });
+            // Cool down temperature
+            temperature *= coolingFactor;
+        }
+        // Extract final positions in relative space
+        const relativePositions = nodeForces.map((nf) => ({
+            node: nf.node,
+            position: { x: nf.position.x, y: nf.position.y }
+        }));
+        // Phase 0.5: Apply viewport transform if viewport is provided
+        if (config === null || config === void 0 ? void 0 : config.viewport) {
+            // Calculate bounding box of force-directed layout
+            const layoutBounds = (0, ViewportTransform_1.calculateNodeBounds)(relativePositions.map(({ node, position }) => ({
+                position,
+                size: node.size || { width: 200, height: 100 }
+            })));
+            // Calculate transform to fit in viewport
+            const transform = (0, ViewportTransform_1.calculateViewportTransform)(layoutBounds, config.viewport, config.margins || 50);
+            // Apply transform to all positions
+            relativePositions.forEach(({ node, position }) => {
+                const transformedPos = (0, ViewportTransform_1.applyTransform)(position, transform);
+                positions.set(node.id, transformedPos);
+            });
+            console.log(`🧲 Force-Directed layout: ${nodes.length} nodes fit in viewport (scale: ${transform.scale.toFixed(2)})`);
+        }
+        else {
+            // No viewport - normalize to positive coordinates with padding (backward compatibility)
+            let minX = Infinity;
+            let minY = Infinity;
+            relativePositions.forEach(({ position }) => {
+                minX = Math.min(minX, position.x);
+                minY = Math.min(minY, position.y);
+            });
+            const padding = 100;
+            relativePositions.forEach(({ node, position }) => {
+                positions.set(node.id, {
+                    x: position.x - minX + padding,
+                    y: position.y - minY + padding,
+                });
+            });
+        }
+        return positions;
+    }
+    onActivate() {
+        console.log('🧲 Force-Directed layout activated');
+    }
+    onDeactivate() {
+        console.log('🧲 Force-Directed layout deactivated');
+    }
+}
+exports.ForceDirectedLayoutAlgorithm = ForceDirectedLayoutAlgorithm;
+//# sourceMappingURL=ForceDirectedLayoutAlgorithm.js.map

package/src/libs/engine/src/layout/algorithms/GridLayoutAlgorithm.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Grid Layout Algorithm
+ *
+ * Places nodes in a grid pattern with smart column calculation based on viewport width.
+ * This is the fastest and most predictable layout algorithm, ideal for:
+ * - General-purpose diagrams where structure is unknown
+ * - Incremental node addition
+ * - When users will manually arrange nodes later
+ *
+ * Features:
+ * - Auto-calculates optimal number of columns based on viewport width
+ * - Guarantees collision-free placement
+ * - Maintains existing positions when re-layouting
+ * - Viewport-aware (keeps nodes visible)
+ */
+import { DiagramModel } from '../../models/DiagramModel';
+import { Point } from '../../types';
+import { BaseLayoutAlgorithm } from '../ILayoutAlgorithm';
+import { PlacementOptions, PlacementResult, LayoutConfiguration } from '../types';
+export declare class GridLayoutAlgorithm extends BaseLayoutAlgorithm {
+    private gridOptions;
+    constructor(config?: LayoutConfiguration);
+    getName(): string;
+    getType(): 'grid';
+    /**
+     * Calculate placement for a single new node
+     */
+    calculatePlacement(options: PlacementOptions): PlacementResult;
+    /**
+     * Re-layout all nodes in grid pattern (Phase 0.5 - Viewport-aware)
+     */
+    reLayout(diagram: DiagramModel, config?: LayoutConfiguration): Map<string, Point>;
+    /**
+     * Calculate optimal number of columns for grid layout
+     */
+    private calculateOptimalColumns;
+    /**
+     * Calculate optimal grid parameters based on viewport and node dimensions
+     */
+    private calculateGridParameters;
+    /**
+     * Find next available grid position that doesn't collide with existing nodes
+     */
+    private findNextGridPosition;
+    /**
+     * Configure grid-specific options
+     */
+    configure(config: LayoutConfiguration): void;
+    /**
+     * Grid layout can always be applied
+     */
+    canApply(diagram: DiagramModel): {
+        valid: boolean;
+        reason?: string;
+    };
+}

package/src/libs/engine/src/layout/algorithms/GridLayoutAlgorithm.js

@@ -0,0 +1,223 @@
+"use strict";
+/**
+ * Grid Layout Algorithm
+ *
+ * Places nodes in a grid pattern with smart column calculation based on viewport width.
+ * This is the fastest and most predictable layout algorithm, ideal for:
+ * - General-purpose diagrams where structure is unknown
+ * - Incremental node addition
+ * - When users will manually arrange nodes later
+ *
+ * Features:
+ * - Auto-calculates optimal number of columns based on viewport width
+ * - Guarantees collision-free placement
+ * - Maintains existing positions when re-layouting
+ * - Viewport-aware (keeps nodes visible)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.GridLayoutAlgorithm = void 0;
+const ILayoutAlgorithm_1 = require("../ILayoutAlgorithm");
+const ViewportTransform_1 = require("../ViewportTransform");
+const SmartSpacingCalculator_1 = require("../SmartSpacingCalculator");
+class GridLayoutAlgorithm extends ILayoutAlgorithm_1.BaseLayoutAlgorithm {
+    constructor(config) {
+        super(config);
+        this.gridOptions = (config === null || config === void 0 ? void 0 : config.options) || {};
+    }
+    getName() {
+        return 'Grid Layout';
+    }
+    getType() {
+        return 'grid';
+    }
+    /**
+     * Calculate placement for a single new node
+     */
+    calculatePlacement(options) {
+        var _a, _b, _c, _d;
+        const { node, viewport, existingNodes, spacing = this.gridOptions.horizontalSpacing || 20, padding = 100, } = options;
+        // Get node dimensions
+        const nodeWidth = ((_a = node.size) === null || _a === void 0 ? void 0 : _a.width) || ((_b = this.gridOptions.nodeSize) === null || _b === void 0 ? void 0 : _b.width) || 200;
+        const nodeHeight = ((_c = node.size) === null || _c === void 0 ? void 0 : _c.height) || ((_d = this.gridOptions.nodeSize) === null || _d === void 0 ? void 0 : _d.height) || 100;
+        // Calculate grid parameters
+        const gridParams = this.calculateGridParameters(viewport, nodeWidth, nodeHeight, spacing, padding);
+        // Find next available position in grid
+        const position = this.findNextGridPosition(existingNodes, gridParams, nodeWidth, nodeHeight, spacing);
+        return {
+            position,
+            success: true,
+            metadata: {
+                gridPosition: {
+                    row: Math.floor((position.y - gridParams.startY) / gridParams.rowHeight),
+                    column: Math.floor((position.x - gridParams.startX) / gridParams.columnWidth),
+                },
+                detectedPattern: 'grid',
+                reason: `Placed in grid at row ${Math.floor((position.y - gridParams.startY) / gridParams.rowHeight)}, column ${Math.floor((position.x - gridParams.startX) / gridParams.columnWidth)}`,
+            },
+        };
+    }
+    /**
+     * Re-layout all nodes in grid pattern (Phase 0.5 - Viewport-aware)
+     */
+    reLayout(diagram, config) {
+        var _a, _b, _c, _d;
+        if (config) {
+            this.configure(config);
+        }
+        const nodes = diagram.getNodes();
+        const positions = new Map();
+        if (nodes.length === 0) {
+            return positions;
+        }
+        // Get node dimensions (use first node as reference)
+        const referenceNode = nodes[0];
+        const nodeWidth = ((_a = referenceNode.size) === null || _a === void 0 ? void 0 : _a.width) || ((_b = this.gridOptions.nodeSize) === null || _b === void 0 ? void 0 : _b.width) || 200;
+        const nodeHeight = ((_c = referenceNode.size) === null || _c === void 0 ? void 0 : _c.height) || ((_d = this.gridOptions.nodeSize) === null || _d === void 0 ? void 0 : _d.height) || 100;
+        // Use viewport from config if provided (Phase 0.5), otherwise fallback to default
+        const viewport = (config === null || config === void 0 ? void 0 : config.viewport) || { x: 0, y: 0, width: 1200, height: 800 };
+        // Calculate initial columns for smart spacing calculation
+        const initialColumns = this.calculateOptimalColumns(viewport, nodeWidth, 20, 100);
+        // Calculate smart spacing based on viewport, node count, and zoom
+        const smartSpacing = (0, SmartSpacingCalculator_1.calculateGridSmartSpacing)({
+            viewport,
+            nodeCount: nodes.length,
+            zoom: viewport.zoom || 1.0, // Zoom might be on viewport from config
+            averageNodeSize: { width: nodeWidth, height: nodeHeight }
+        }, initialColumns);
+        // Use smart spacing (fallback to manual config if provided)
+        const spacing = this.gridOptions.horizontalSpacing || smartSpacing.horizontal;
+        const padding = smartSpacing.padding;
+        // Calculate grid parameters based on viewport
+        const gridParams = this.calculateGridParameters(viewport, nodeWidth, nodeHeight, spacing, padding);
+        // Calculate grid positions in relative space (starting from 0,0)
+        const relativePositions = [];
+        nodes.forEach((node, index) => {
+            const row = Math.floor(index / gridParams.columns);
+            const col = index % gridParams.columns;
+            const relativePos = {
+                x: col * gridParams.columnWidth,
+                y: row * gridParams.rowHeight,
+            };
+            relativePositions.push({ node, position: relativePos });
+        });
+        // Phase 0.5: Apply viewport transform if viewport is provided
+        if (config === null || config === void 0 ? void 0 : config.viewport) {
+            // Calculate bounding box of grid layout
+            const layoutBounds = (0, ViewportTransform_1.calculateNodeBounds)(relativePositions.map(({ node, position }) => ({
+                position,
+                size: node.size || { width: nodeWidth, height: nodeHeight }
+            })));
+            // Calculate transform to fit in viewport
+            const transform = (0, ViewportTransform_1.calculateViewportTransform)(layoutBounds, config.viewport, config.margins || 50);
+            // Apply transform to all positions
+            relativePositions.forEach(({ node, position }) => {
+                const transformedPos = (0, ViewportTransform_1.applyTransform)(position, transform);
+                positions.set(node.id, transformedPos);
+            });
+            console.log(`📐 Grid layout: ${nodes.length} nodes in ${gridParams.columns} columns, fit in viewport (scale: ${transform.scale.toFixed(2)}, spacing: ${spacing}px)`);
+        }
+        else {
+            // No viewport - use relative positions with padding offset (backward compatibility)
+            relativePositions.forEach(({ node, position }) => {
+                positions.set(node.id, {
+                    x: position.x + padding,
+                    y: position.y + padding
+                });
+            });
+        }
+        return positions;
+    }
+    /**
+     * Calculate optimal number of columns for grid layout
+     */
+    calculateOptimalColumns(viewport, nodeWidth, spacing, padding) {
+        if (this.gridOptions.columns !== 'auto' && this.gridOptions.columns !== undefined) {
+            return this.gridOptions.columns;
+        }
+        const columnWidth = nodeWidth + spacing;
+        const availableWidth = viewport.width - padding * 2;
+        const maxColumns = Math.floor(availableWidth / columnWidth);
+        // Use at least 2 columns, at most what fits in viewport
+        let columns = Math.max(2, Math.min(maxColumns, 5)); // Cap at 5 for readability
+        // If viewport is very wide, use more columns
+        if (viewport.width > 2000) {
+            columns = Math.min(maxColumns, 6);
+        }
+        return columns;
+    }
+    /**
+     * Calculate optimal grid parameters based on viewport and node dimensions
+     */
+    calculateGridParameters(viewport, nodeWidth, nodeHeight, spacing, padding) {
+        var _a, _b;
+        // Start position with padding from viewport edges
+        const startX = ((_a = this.gridOptions.startPosition) === null || _a === void 0 ? void 0 : _a.x) || padding;
+        const startY = ((_b = this.gridOptions.startPosition) === null || _b === void 0 ? void 0 : _b.y) || padding;
+        // Calculate column and row dimensions
+        const columnWidth = nodeWidth + spacing;
+        const rowHeight = nodeHeight + spacing;
+        // Calculate optimal number of columns
+        let columns;
+        if (this.gridOptions.columns === 'auto' || this.gridOptions.columns === undefined) {
+            // Smart calculation: fit as many columns as possible in viewport
+            const availableWidth = viewport.width - padding * 2;
+            const maxColumns = Math.floor(availableWidth / columnWidth);
+            // Use at least 2 columns, at most what fits in viewport
+            columns = Math.max(2, Math.min(maxColumns, 5)); // Cap at 5 for readability
+            // If viewport is very wide, use more columns
+            if (viewport.width > 2000) {
+                columns = Math.min(maxColumns, 6);
+            }
+        }
+        else {
+            columns = this.gridOptions.columns;
+        }
+        return {
+            columns,
+            startX,
+            startY,
+            columnWidth,
+            rowHeight,
+        };
+    }
+    /**
+     * Find next available grid position that doesn't collide with existing nodes
+     */
+    findNextGridPosition(existingNodes, gridParams, nodeWidth, nodeHeight, spacing) {
+        // Try grid positions systematically
+        for (let row = 0; row < 1000; row++) {
+            // Support up to 1000 rows
+            for (let col = 0; col < gridParams.columns; col++) {
+                const candidate = {
+                    x: gridParams.startX + col * gridParams.columnWidth,
+                    y: gridParams.startY + row * gridParams.rowHeight,
+                };
+                if (!this.hasCollision(candidate, { width: nodeWidth, height: nodeHeight }, existingNodes, spacing)) {
+                    return candidate;
+                }
+            }
+        }
+        // Fallback (should never reach here with proper grid)
+        return {
+            x: gridParams.startX,
+            y: gridParams.startY + existingNodes.length * gridParams.rowHeight,
+        };
+    }
+    /**
+     * Configure grid-specific options
+     */
+    configure(config) {
+        super.configure(config);
+        if (config.options) {
+            this.gridOptions = Object.assign(Object.assign({}, this.gridOptions), config.options);
+        }
+    }
+    /**
+     * Grid layout can always be applied
+     */
+    canApply(diagram) {
+        return { valid: true };
+    }
+}
+exports.GridLayoutAlgorithm = GridLayoutAlgorithm;
+//# sourceMappingURL=GridLayoutAlgorithm.js.map

package/src/libs/engine/src/layout/algorithms/HierarchicalLayoutAlgorithm.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Hierarchical Layout Algorithm
+ *
+ * Uses Dagre library to create hierarchical/layered layouts for directed graphs.
+ * Perfect for:
+ * - Flowcharts
+ * - Process diagrams
+ * - Decision trees
+ * - Organizational charts
+ * - Any directed acyclic graph (DAG)
+ *
+ * Features:
+ * - Respects edge direction (parent → child flow)
+ * - Minimizes edge crossings
+ * - Clear visual hierarchy
+ * - Configurable direction (TB, BT, LR, RL)
+ * - Professional appearance
+ */
+import { DiagramModel } from '../../models/DiagramModel';
+import { Point } from '../../types';
+import { BaseLayoutAlgorithm } from '../ILayoutAlgorithm';
+import { PlacementOptions, PlacementResult, LayoutConfiguration } from '../types';
+export declare class HierarchicalLayoutAlgorithm extends BaseLayoutAlgorithm {
+    private hierarchicalOptions;
+    constructor(config?: LayoutConfiguration);
+    getName(): string;
+    getType(): 'hierarchical';
+    /**
+     * Calculate placement for a single new node
+     * For hierarchical layout, we'll place it near connected nodes
+     */
+    calculatePlacement(options: PlacementOptions): PlacementResult;
+    /**
+     * Re-layout all nodes using Dagre
+     */
+    reLayout(diagram: DiagramModel, config?: LayoutConfiguration): Map<string, Point>;
+    /**
+     * Configure hierarchical-specific options
+     */
+    configure(config: LayoutConfiguration): void;
+    /**
+     * Hierarchical layout works best on DAGs but can handle any graph
+     */
+    canApply(diagram: DiagramModel): {
+        valid: boolean;
+        reason?: string;
+    };
+    /**
+     * Find nodes that are connected to the given node
+     */
+    private findConnectedNodes;
+    /**
+     * Calculate average position of nodes
+     */
+    private calculateAveragePosition;
+    /**
+     * Detect cycles in the graph (simplified DFS approach)
+     */
+    private detectCycles;
+}