pict-section-flow 0.0.16 → 0.0.18

package/source/services/PictService-Flow-Layout.js

@@ -1,5 +1,63 @@
 const libFableServiceProviderBase = require('fable-serviceproviderbase');
 
+const libLayoutCustom           = require('../providers/layouts/Layout-Custom.js');
+const libLayoutLayered          = require('../providers/layouts/Layout-Layered.js');
+const libLayoutForcedFromCenter = require('../providers/layouts/Layout-ForcedFromCenter.js');
+const libLayoutGrid             = require('../providers/layouts/Layout-Grid.js');
+const libLayoutCircular         = require('../providers/layouts/Layout-Circular.js');
+const libLayoutTabular          = require('../providers/layouts/Layout-Tabular.js');
+const libLayoutColumnar         = require('../providers/layouts/Layout-Columnar.js');
+
+const libEdgeBezier              = require('../providers/edges/Edge-Bezier.js');
+const libEdgeOrthogonal          = require('../providers/edges/Edge-Orthogonal.js');
+const libEdgeStraight            = require('../providers/edges/Edge-Straight.js');
+const libEdgeOrthogonalSnap      = require('../providers/edges/Edge-OrthogonalSnap.js');
+const libEdgePerimeter           = require('../providers/edges/Edge-Perimeter.js');
+const libEdgePerimeterLinear     = require('../providers/edges/Edge-Perimeter-Linear.js');
+const libEdgePerimeterOrthogonal = require('../providers/edges/Edge-Perimeter-Orthogonal.js');
+
+const _BUILTIN_ALGORITHMS =
+[
+	libLayoutCustom,
+	libLayoutLayered,
+	libLayoutForcedFromCenter,
+	libLayoutGrid,
+	libLayoutCircular,
+	libLayoutTabular,
+	libLayoutColumnar
+];
+
+const _BUILTIN_EDGE_THEMES =
+[
+	libEdgeBezier,
+	libEdgeOrthogonal,
+	libEdgeStraight,
+	libEdgeOrthogonalSnap,
+	libEdgePerimeter,
+	libEdgePerimeterLinear,
+	libEdgePerimeterOrthogonal
+];
+
+const _LEGACY_ALGORITHM  = 'Layered';
+const _DEFAULT_EDGE_THEME = 'Bezier';
+
+/**
+ * PictServiceFlowLayout
+ *
+ * Layout-algorithm registry and dispatcher. Holds plain descriptor
+ * objects (`{ Name, Label, Apply, DefaultParameters, ParameterSchema }`)
+ * for every registered layout algorithm, plus the small helpers
+ * `snapToGrid` and `centerNodes` and the special-case `autoLayoutSubset`.
+ *
+ * Algorithms are pure functions over `(nodes, connections, parameters)`
+ * that mutate node X/Y in place. Third parties extend the registry via
+ * `registerAlgorithm(pDescriptor)`.
+ *
+ * Note: `_LayoutProvider` (PictProvider-Flow-Layouts.js) is a different
+ * concept — it manages **saved layout snapshots** (named position
+ * captures the user can restore later). Don't confuse "layouts" (saved
+ * snapshots) with "layout algorithms" (procedural arrangement).
+ */
 class PictServiceFlowLayout extends libFableServiceProviderBase
 {
 	constructor(pFable, pOptions, pServiceHash)
@@ -10,173 +68,301 @@ class PictServiceFlowLayout extends libFableServiceProviderBase
 
 		this._FlowView = (pOptions && pOptions.FlowView) ? pOptions.FlowView : null;
 
-		// Layout configuration
+		// Legacy spacing fields kept for `autoLayoutSubset` and any
+		// external consumer that read them. The Layered algorithm itself
+		// pulls spacing from its DefaultParameters.
 		this._HorizontalSpacing = 250;
 		this._VerticalSpacing = 120;
 		this._StartX = 100;
 		this._StartY = 100;
+
+		// Algorithm registry: Name → descriptor
+		this._Algorithms = {};
+
+		// Edge-theme registry: Name → descriptor
+		this._EdgeThemes = {};
+
+		for (let i = 0; i < _BUILTIN_ALGORITHMS.length; i++)
+		{
+			this.registerAlgorithm(_BUILTIN_ALGORITHMS[i]);
+		}
+		for (let i = 0; i < _BUILTIN_EDGE_THEMES.length; i++)
+		{
+			this.registerEdgeTheme(_BUILTIN_EDGE_THEMES[i]);
+		}
 	}
 
+	// ── Algorithm Registry ────────────────────────────────────────────────
+
 	/**
-	 * Snap a coordinate to the nearest grid point
-	 * @param {number} pValue - The coordinate value
-	 * @param {number} pGridSize - The grid size
-	 * @returns {number}
+	 * Register a layout algorithm.
+	 * @param {Object} pDescriptor - { Name, Label, Apply, DefaultParameters, ParameterSchema }
+	 * @returns {boolean} true if registered, false if invalid
 	 */
-	snapToGrid(pValue, pGridSize)
+	registerAlgorithm(pDescriptor)
 	{
-		if (!pGridSize || pGridSize <= 0) return pValue;
-		return Math.round(pValue / pGridSize) * pGridSize;
+		if (!pDescriptor || typeof pDescriptor !== 'object')
+		{
+			this.log.warn('PictServiceFlowLayout registerAlgorithm: descriptor must be an object');
+			return false;
+		}
+		if (typeof pDescriptor.Name !== 'string' || pDescriptor.Name === '')
+		{
+			this.log.warn('PictServiceFlowLayout registerAlgorithm: descriptor.Name is required');
+			return false;
+		}
+		if (typeof pDescriptor.Apply !== 'function')
+		{
+			this.log.warn(`PictServiceFlowLayout registerAlgorithm: descriptor.Apply for '${pDescriptor.Name}' must be a function`);
+			return false;
+		}
+
+		this._Algorithms[pDescriptor.Name] = pDescriptor;
+		return true;
 	}
 
 	/**
-	 * Auto-layout nodes using a simple left-to-right topological approach
-	 * @param {Array} pNodes - Array of node data objects
-	 * @param {Array} pConnections - Array of connection data objects
+	 * Look up a registered algorithm by name.
+	 * @param {string} pName
+	 * @returns {Object|null}
 	 */
-	autoLayout(pNodes, pConnections)
+	getAlgorithm(pName)
 	{
-		if (!pNodes || pNodes.length === 0) return;
+		return this._Algorithms[pName] || null;
+	}
 
-		// Build adjacency information
-		let tmpNodeMap = {};
-		let tmpInDegree = {};
-		let tmpOutEdges = {};
+	/**
+	 * List all registered algorithm names in registration order.
+	 * @returns {string[]}
+	 */
+	getAlgorithmNames()
+	{
+		return Object.keys(this._Algorithms);
+	}
 
-		for (let i = 0; i < pNodes.length; i++)
+	/**
+	 * List all registered algorithm descriptors.
+	 * @returns {Object[]}
+	 */
+	listAlgorithms()
+	{
+		let tmpKeys = Object.keys(this._Algorithms);
+		let tmpResult = [];
+		for (let i = 0; i < tmpKeys.length; i++)
 		{
-			let tmpNode = pNodes[i];
-			tmpNodeMap[tmpNode.Hash] = tmpNode;
-			tmpInDegree[tmpNode.Hash] = 0;
-			tmpOutEdges[tmpNode.Hash] = [];
+			tmpResult.push(this._Algorithms[tmpKeys[i]]);
 		}
+		return tmpResult;
+	}
 
-		for (let i = 0; i < pConnections.length; i++)
-		{
-			let tmpConn = pConnections[i];
-			if (tmpInDegree.hasOwnProperty(tmpConn.TargetNodeHash))
-			{
-				tmpInDegree[tmpConn.TargetNodeHash]++;
-			}
-			if (tmpOutEdges.hasOwnProperty(tmpConn.SourceNodeHash))
-			{
-				tmpOutEdges[tmpConn.SourceNodeHash].push(tmpConn.TargetNodeHash);
-			}
-		}
+	/**
+	 * Build the merged parameter set for an algorithm: default values
+	 * with caller-supplied overrides on top.
+	 * @param {string} pName
+	 * @param {Object} [pOverrides]
+	 * @returns {Object}
+	 */
+	getMergedParameters(pName, pOverrides)
+	{
+		let tmpAlgo = this.getAlgorithm(pName);
+		if (!tmpAlgo) return Object.assign({}, pOverrides || {});
+		return Object.assign({}, tmpAlgo.DefaultParameters || {}, pOverrides || {});
+	}
 
-		// Topological sort (Kahn's algorithm)
-		let tmpLayers = [];
-		let tmpQueue = [];
-		let tmpAssigned = {};
+	// ── Edge-Theme Registry ──────────────────────────────────────────────
 
-		// Start with nodes that have no incoming edges
-		for (let tmpHash in tmpInDegree)
+	/**
+	 * Register an edge theme.
+	 * @param {Object} pDescriptor - { Name, Label, Description, GeneratePath, AdjustLayout?, DefaultParameters?, ParameterSchema? }
+	 * @returns {boolean} true if registered, false if invalid
+	 */
+	registerEdgeTheme(pDescriptor)
+	{
+		if (!pDescriptor || typeof pDescriptor !== 'object')
 		{
-			if (tmpInDegree[tmpHash] === 0)
-			{
-				tmpQueue.push(tmpHash);
-			}
+			this.log.warn('PictServiceFlowLayout registerEdgeTheme: descriptor must be an object');
+			return false;
 		}
-
-		while (tmpQueue.length > 0)
+		if (typeof pDescriptor.Name !== 'string' || pDescriptor.Name === '')
 		{
-			let tmpCurrentLayer = [];
+			this.log.warn('PictServiceFlowLayout registerEdgeTheme: descriptor.Name is required');
+			return false;
+		}
+		if (typeof pDescriptor.GeneratePath !== 'function')
+		{
+			this.log.warn(`PictServiceFlowLayout registerEdgeTheme: descriptor.GeneratePath for '${pDescriptor.Name}' must be a function`);
+			return false;
+		}
+		this._EdgeThemes[pDescriptor.Name] = pDescriptor;
+		return true;
+	}
 
-			let tmpNextQueue = [];
-			for (let i = 0; i < tmpQueue.length; i++)
-			{
-				let tmpNodeHash = tmpQueue[i];
-				if (tmpAssigned[tmpNodeHash]) continue;
+	/**
+	 * Look up a registered edge theme by name.
+	 * @param {string} pName
+	 * @returns {Object|null}
+	 */
+	getEdgeTheme(pName)
+	{
+		return this._EdgeThemes[pName] || null;
+	}
 
-				tmpAssigned[tmpNodeHash] = true;
-				tmpCurrentLayer.push(tmpNodeHash);
+	/**
+	 * List all registered edge-theme names in registration order.
+	 * @returns {string[]}
+	 */
+	getEdgeThemeNames()
+	{
+		return Object.keys(this._EdgeThemes);
+	}
 
-				// Process outgoing edges
-				let tmpEdges = tmpOutEdges[tmpNodeHash] || [];
-				for (let j = 0; j < tmpEdges.length; j++)
-				{
-					let tmpTargetHash = tmpEdges[j];
-					tmpInDegree[tmpTargetHash]--;
-					if (tmpInDegree[tmpTargetHash] <= 0 && !tmpAssigned[tmpTargetHash])
-					{
-						tmpNextQueue.push(tmpTargetHash);
-					}
-				}
-			}
+	/**
+	 * List all registered edge-theme descriptors.
+	 * @returns {Object[]}
+	 */
+	listEdgeThemes()
+	{
+		let tmpKeys = Object.keys(this._EdgeThemes);
+		let tmpResult = [];
+		for (let i = 0; i < tmpKeys.length; i++)
+		{
+			tmpResult.push(this._EdgeThemes[tmpKeys[i]]);
+		}
+		return tmpResult;
+	}
 
-			if (tmpCurrentLayer.length > 0)
-			{
-				tmpLayers.push(tmpCurrentLayer);
-			}
+	/**
+	 * Resolve which edge theme should render a given connection. Order:
+	 *   1. `Connection.Data.EdgeTheme` (per-connection override)
+	 *   2. Per-connection `Connection.Data.LineMode === 'orthogonal'`
+	 *      → 'Orthogonal' (back-compat for the existing line-mode flag)
+	 *   3. `_FlowData.EdgeTheme` (flow-level)
+	 *   4. Active layout's `DefaultEdgeTheme`
+	 *   5. The hard fallback ('Bezier')
+	 *
+	 * Returns null only if even the fallback isn't registered, in which
+	 * case the renderer should use its built-in path generators.
+	 *
+	 * @param {Object} pConnection
+	 * @returns {Object|null}
+	 */
+	resolveActiveEdgeTheme(pConnection)
+	{
+		let tmpData = (pConnection && pConnection.Data) || {};
+		let tmpFlowView = this._FlowView;
+		let tmpFlowData = tmpFlowView ? tmpFlowView._FlowData : null;
 
-			tmpQueue = tmpNextQueue;
+		if (tmpData.EdgeTheme)
+		{
+			let tmpTheme = this.getEdgeTheme(tmpData.EdgeTheme);
+			if (tmpTheme) return tmpTheme;
 		}
-
-		// Handle any remaining unassigned nodes (cycles or disconnected)
-		let tmpRemainingNodes = [];
-		for (let i = 0; i < pNodes.length; i++)
+		if (tmpData.LineMode === 'orthogonal' && !tmpData.EdgeTheme)
 		{
-			if (!tmpAssigned[pNodes[i].Hash])
-			{
-				tmpRemainingNodes.push(pNodes[i].Hash);
-			}
+			let tmpTheme = this.getEdgeTheme('Orthogonal');
+			if (tmpTheme) return tmpTheme;
 		}
-		if (tmpRemainingNodes.length > 0)
+		if (tmpFlowData && tmpFlowData.EdgeTheme)
 		{
-			tmpLayers.push(tmpRemainingNodes);
+			let tmpTheme = this.getEdgeTheme(tmpFlowData.EdgeTheme);
+			if (tmpTheme) return tmpTheme;
 		}
-
-		// Assign positions based on layers
-		let tmpCurrentX = this._StartX;
-
-		for (let tmpLayerIndex = 0; tmpLayerIndex < tmpLayers.length; tmpLayerIndex++)
+		if (tmpFlowData && tmpFlowData.LayoutAlgorithm)
 		{
-			let tmpLayer = tmpLayers[tmpLayerIndex];
-			let tmpMaxWidth = 0;
-
-			// Calculate the total height for this layer to center vertically
-			let tmpTotalHeight = 0;
-			for (let i = 0; i < tmpLayer.length; i++)
+			let tmpAlgo = this.getAlgorithm(tmpFlowData.LayoutAlgorithm);
+			if (tmpAlgo && tmpAlgo.DefaultEdgeTheme)
 			{
-				let tmpNode = tmpNodeMap[tmpLayer[i]];
-				if (tmpNode)
-				{
-					tmpTotalHeight += tmpNode.Height || 80;
-					if (i < tmpLayer.length - 1)
-					{
-						tmpTotalHeight += this._VerticalSpacing;
-					}
-				}
+				let tmpTheme = this.getEdgeTheme(tmpAlgo.DefaultEdgeTheme);
+				if (tmpTheme) return tmpTheme;
 			}
+		}
+		return this.getEdgeTheme(_DEFAULT_EDGE_THEME);
+	}
 
-			let tmpCurrentY = this._StartY;
+	/**
+	 * Build the merged parameter set for an edge theme.
+	 * @param {string} pName
+	 * @param {Object} [pOverrides]
+	 * @returns {Object}
+	 */
+	getMergedEdgeThemeParameters(pName, pOverrides)
+	{
+		let tmpTheme = this.getEdgeTheme(pName);
+		if (!tmpTheme) return Object.assign({}, pOverrides || {});
+		return Object.assign({}, tmpTheme.DefaultParameters || {}, pOverrides || {});
+	}
 
-			for (let i = 0; i < tmpLayer.length; i++)
-			{
-				let tmpNode = tmpNodeMap[tmpLayer[i]];
-				if (!tmpNode) continue;
+	// ── Dispatch ──────────────────────────────────────────────────────────
 
-				tmpNode.X = tmpCurrentX;
-				tmpNode.Y = tmpCurrentY;
+	/**
+	 * Apply a registered layout algorithm. Mutates node X/Y in place.
+	 * @param {Array} pNodes
+	 * @param {Array} pConnections
+	 * @param {string} pAlgorithmName
+	 * @param {Object} [pParameters]
+	 */
+	applyLayout(pNodes, pConnections, pAlgorithmName, pParameters)
+	{
+		let tmpAlgo = this.getAlgorithm(pAlgorithmName);
+		if (!tmpAlgo)
+		{
+			this.log.warn(`PictServiceFlowLayout applyLayout: unknown algorithm '${pAlgorithmName}', falling back to '${_LEGACY_ALGORITHM}'`);
+			tmpAlgo = this.getAlgorithm(_LEGACY_ALGORITHM);
+			if (!tmpAlgo) return;
+		}
+		let tmpMerged = Object.assign({}, tmpAlgo.DefaultParameters || {}, pParameters || {});
+		tmpAlgo.Apply(pNodes, pConnections, tmpMerged);
+	}
 
-				let tmpWidth = tmpNode.Width || 180;
-				let tmpHeight = tmpNode.Height || 80;
+	/**
+	 * Auto-layout entry point.
+	 *
+	 * - Legacy 2-arg form `autoLayout(nodes, connections)` dispatches to
+	 *   the Layered algorithm and is byte-for-byte identical to the
+	 *   pre-subsystem behavior.
+	 * - 3- or 4-arg form `autoLayout(nodes, connections, name, params)`
+	 *   dispatches to the named algorithm.
+	 *
+	 * @param {Array} pNodes
+	 * @param {Array} pConnections
+	 * @param {string} [pAlgorithmName] - defaults to the Layered algorithm
+	 * @param {Object} [pParameters]
+	 */
+	autoLayout(pNodes, pConnections, pAlgorithmName, pParameters)
+	{
+		if (!pNodes || pNodes.length === 0) return;
+		let tmpName = (typeof pAlgorithmName === 'string' && pAlgorithmName !== '') ? pAlgorithmName : _LEGACY_ALGORITHM;
+		this.applyLayout(pNodes, pConnections, tmpName, pParameters);
+	}
 
-				tmpMaxWidth = Math.max(tmpMaxWidth, tmpWidth);
-				tmpCurrentY += tmpHeight + this._VerticalSpacing;
-			}
+	// ── Helpers ──────────────────────────────────────────────────────────
 
-			tmpCurrentX += tmpMaxWidth + this._HorizontalSpacing;
-		}
+	/**
+	 * Snap a coordinate to the nearest grid point.
+	 * @param {number} pValue
+	 * @param {number} pGridSize
+	 * @returns {number}
+	 */
+	snapToGrid(pValue, pGridSize)
+	{
+		if (!pGridSize || pGridSize <= 0) return pValue;
+		return Math.round(pValue / pGridSize) * pGridSize;
 	}
 
 	/**
 	 * Auto-layout a subset of nodes, positioning them to the right of
 	 * any fixed (already-positioned) nodes.
 	 *
-	 * Uses the same topological sort approach as autoLayout, but only
-	 * repositions the nodes in pNodesToLayout. The pFixedNodes are used
-	 * to compute a bounding box that the new layout avoids.
+	 * Used by the saved-layout restore flow (`PictProvider-Flow-Layouts`)
+	 * to position nodes that exist in the current flow but were absent
+	 * from the saved snapshot.
+	 *
+	 * **Always runs the Layered algorithm**, regardless of the flow's
+	 * configured `LayoutAlgorithm`. Running ForcedFromCenter or another
+	 * algorithm on a partial node set would jitter the matched nodes
+	 * (which are intentionally fixed). The contract here is "place the
+	 * orphans in a sensible default arrangement," not "obey the user's
+	 * full-graph algorithm."
 	 *
 	 * @param {Array} pNodesToLayout - Nodes that need new positions
 	 * @param {Array} pFixedNodes - Nodes that already have positions (read-only)
@@ -203,7 +389,6 @@ class PictServiceFlowLayout extends libFableServiceProviderBase
 				}
 			}
 
-			// Place unmatched nodes to the right of all fixed nodes
 			tmpStartX = tmpMaxX + this._HorizontalSpacing;
 		}
 
@@ -227,7 +412,6 @@ class PictServiceFlowLayout extends libFableServiceProviderBase
 			tmpOutEdges[tmpNode.Hash] = [];
 		}
 
-		// Only count edges between nodes in the subset
 		for (let i = 0; i < pConnections.length; i++)
 		{
 			let tmpConn = pConnections[i];
@@ -330,7 +514,7 @@ class PictServiceFlowLayout extends libFableServiceProviderBase
 	}
 
 	/**
-	 * Center all nodes around a given point
+	 * Center all nodes around a given point.
 	 * @param {Array} pNodes
 	 * @param {number} pCenterX
 	 * @param {number} pCenterY