pict-section-flow 1.0.1 → 1.1.0

package/example_applications/simple_cards/package.json

@@ -3,6 +3,14 @@
 	"version": "0.0.1",
 	"description": "Pict Section Flow - Simple Cards Example Application",
 	"main": "source/Pict-Application-FlowExample.js",
+	"retold": {
+		"ExampleApplication": {
+			"Stage": true,
+			"Title": "Simple Cards",
+			"Summary": "Twelve custom PictFlowCard subclasses across six categories — every panel type (Markdown / Template / Form / View), every BodyContent renderer (SVG / HTML / Canvas), wrapped in a multi-page Pict shell with router-driven navigation and a curated sample-graph catalog.",
+			"Complexity": "Basic"
+		}
+	},
 	"scripts": {
 		"start": "node source/Pict-Application-FlowExample.js",
 		"prebuild": "node ../../scripts/generate-card-help.js",
@@ -19,7 +27,7 @@
 		"pict-provider": "^1.0.3",
 		"pict-section-content": "^0.0.6",
 		"pict-section-form": "^1.0.192",
-		"pict-section-flow": "file:../../"
+		"pict-section-flow": "^1.0.1"
 	},
 	"devDependencies": {
 		"quackage": "^1.0.58"

package/example_applications/simple_cards/source/views/PictView-FlowExample-BottomBar.js

@@ -44,8 +44,8 @@ const _ViewConfiguration =
 <div class="flowexample-bottombar">
 	<span>Pict Section Flow Example &copy; 2025</span>
 	<div class="flowexample-bottombar-links">
-		<a href="https://github.com/stevenvelozo/pict" target="_blank">Pict</a>
-		<a href="https://github.com/stevenvelozo/fable" target="_blank">Fable</a>
+		<a href="https://github.com/fable-retold/pict" target="_blank">Pict</a>
+		<a href="https://github.com/fable-retold/fable" target="_blank">Fable</a>
 		<a onclick="{~P~}.PictApplication.navigateTo('/About')">About</a>
 	</div>
 </div>

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "pict-section-flow",
-    "version": "1.0.1",
+    "version": "1.1.0",
     "description": "Pict Section Flow Diagram",
     "main": "source/Pict-Section-Flow.js",
     "scripts": {
@@ -15,15 +15,15 @@
     "dependencies": {
         "fable-serviceproviderbase": "^3.0.19",
         "pict-provider": "^1.0.13",
-        "pict-section-form": "^1.0.196",
+        "pict-section-form": "^1.0.199",
         "pict-view": "^1.0.68"
     },
     "devDependencies": {
         "chai": "^6.2.2",
         "mocha": "^11.7.5",
-        "pict": "^1.0.369",
-        "pict-docuserve": "^1.3.2",
+        "pict": "^1.0.372",
+        "pict-docuserve": "^1.4.4",
         "pict-router": "^1.0.10",
-        "quackage": "^1.2.3"
+        "quackage": "^1.3.0"
     }
 }

package/source/providers/PictProvider-Flow-PanelChrome.js

@@ -40,7 +40,8 @@ class PictProviderFlowPanelChrome extends libFableServiceProviderBase
 		let tmpFO = tmpSVGHelper.createSVGElement('foreignObject');
 		tmpFO.setAttribute('class', 'pict-flow-panel-foreign-object');
 		tmpFO.setAttribute('data-panel-hash', pPanelData.Hash);
-		tmpFO.setAttribute('data-node-hash', pPanelData.NodeHash);
+		tmpFO.setAttribute('data-node-hash', pPanelData.NodeHash || '');
+		if (pPanelData.ConnectionHash) { tmpFO.setAttribute('data-connection-hash', pPanelData.ConnectionHash); }
 		tmpFO.setAttribute('x', String(pPanelData.X));
 		tmpFO.setAttribute('y', String(pPanelData.Y));
 		tmpFO.setAttribute('width', String(pPanelData.Width));

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

@@ -328,6 +328,12 @@ class PictServiceFlowDataManager extends libFableServiceProviderBase
 
 		let tmpRemovedConnection = this._FlowView._FlowData.Connections.splice(tmpConnectionIndex, 1)[0];
 
+		// Close any properties panel open for this connection.
+		if (typeof this._FlowView.closePanelForConnection === 'function')
+		{
+			this._FlowView.closePanelForConnection(pConnectionHash);
+		}
+
 		if (this._FlowView._FlowData.ViewState.SelectedConnectionHash === pConnectionHash)
 		{
 			this._FlowView._FlowData.ViewState.SelectedConnectionHash = null;

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

@@ -322,7 +322,16 @@ class PictServiceFlowInteractionManager extends libFableServiceProviderBase
 				{
 					this._LastConnectionClickTime = 0;
 					this._LastConnectionClickHash = null;
-					this._addBezierHandle(tmpTarget, pEvent);
+					// When the host configured a connection properties panel, double-click opens it;
+					// otherwise keep the default behavior of adding a bezier handle.
+					if (this._FlowView.options.ConnectionPropertiesPanel && tmpConnectionHash)
+					{
+						this._FlowView.toggleConnectionPanel(tmpConnectionHash);
+					}
+					else
+					{
+						this._addBezierHandle(tmpTarget, pEvent);
+					}
 				}
 				else
 				{

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

@@ -152,6 +152,98 @@ class PictServiceFlowPanelManager extends libFableServiceProviderBase
 		return this.openPanel(pNodeHash);
 	}
 
+	/**
+	 * Open a properties panel for a connection (edge). The panel config comes from the FlowView's
+	 * ConnectionPropertiesPanel option (connections are not typed, so one config serves them all);
+	 * the panel is placed near the connection's midpoint and tethers to it. Returns false when no
+	 * ConnectionPropertiesPanel is configured, so a host that has not opted in keeps the default
+	 * edge behavior (double-click adds a bezier handle).
+	 * @param {string} pConnectionHash
+	 * @returns {Object|false} The panel data, or false
+	 */
+	openConnectionPanel(pConnectionHash)
+	{
+		let tmpConnection = this._FlowView.getConnection(pConnectionHash);
+		if (!tmpConnection) return false;
+
+		let tmpPanelConfig = this._FlowView.options.ConnectionPropertiesPanel;
+		if (!tmpPanelConfig) return false;
+
+		let tmpExisting = this._FlowView._FlowData.OpenPanels.find((pPanel) => pPanel.ConnectionHash === pConnectionHash);
+		if (tmpExisting) return tmpExisting;
+
+		let tmpMidpoint = this._FlowView.getConnectionMidpoint(pConnectionHash) || { x: 0, y: 0 };
+		let tmpWidth = tmpPanelConfig.DefaultWidth || 300;
+		let tmpHeight = tmpPanelConfig.DefaultHeight || 200;
+
+		let tmpPanelData =
+		{
+			Hash: `panel-${this.fable.getUUID()}`,
+			ConnectionHash: pConnectionHash,
+			NodeHash: null,
+			PanelType: tmpPanelConfig.PanelType || 'Base',
+			Title: tmpPanelConfig.Title || 'Connection',
+			X: tmpMidpoint.x + 40,
+			Y: tmpMidpoint.y + 20,
+			Width: tmpWidth,
+			Height: tmpHeight
+		};
+
+		this._FlowView._FlowData.OpenPanels.push(tmpPanelData);
+		this._FlowView.renderFlow();
+		this._FlowView.marshalFromView();
+
+		if (this._FlowView._EventHandlerProvider)
+		{
+			this._FlowView._EventHandlerProvider.fireEvent('onPanelOpened', tmpPanelData);
+			this._FlowView._EventHandlerProvider.fireEvent('onFlowChanged', this._FlowView._FlowData);
+		}
+
+		return tmpPanelData;
+	}
+
+	/**
+	 * Toggle a properties panel for a connection (open if closed, close if open).
+	 * @param {string} pConnectionHash
+	 * @returns {Object|false}
+	 */
+	toggleConnectionPanel(pConnectionHash)
+	{
+		let tmpExisting = this._FlowView._FlowData.OpenPanels.find((pPanel) => pPanel.ConnectionHash === pConnectionHash);
+		if (tmpExisting)
+		{
+			this.closePanel(tmpExisting.Hash);
+			return false;
+		}
+		return this.openConnectionPanel(pConnectionHash);
+	}
+
+	/**
+	 * Close all panels for a given connection.
+	 * @param {string} pConnectionHash
+	 * @returns {boolean}
+	 */
+	closePanelForConnection(pConnectionHash)
+	{
+		let tmpPanelsToClose = this._FlowView._FlowData.OpenPanels.filter((pPanel) => pPanel.ConnectionHash === pConnectionHash);
+		if (tmpPanelsToClose.length === 0) return false;
+
+		for (let i = 0; i < tmpPanelsToClose.length; i++)
+		{
+			let tmpIndex = this._FlowView._FlowData.OpenPanels.indexOf(tmpPanelsToClose[i]);
+			if (tmpIndex >= 0)
+			{
+				this._FlowView._FlowData.OpenPanels.splice(tmpIndex, 1);
+			}
+			if (this._FlowView._PropertiesPanelView)
+			{
+				this._FlowView._PropertiesPanelView.destroyPanel(tmpPanelsToClose[i].Hash);
+			}
+		}
+
+		return true;
+	}
+
 	/**
 	 * Update a panel's position (for drag).
 	 * @param {string} pPanelHash
@@ -180,8 +272,20 @@ class PictServiceFlowPanelManager extends libFableServiceProviderBase
 			}
 		}
 
-		// Update the tether for this panel
-		this._FlowView._renderTethersForNode(tmpPanel.NodeHash);
+		// Update the tether for this panel. A node panel refreshes just its node's tethers; a
+		// connection panel has no node, so reconcile the panels layer (redraws all tethers, which
+		// is where the connection-midpoint tether is recomputed).
+		if (tmpPanel.ConnectionHash)
+		{
+			if (this._FlowView._PropertiesPanelView && this._FlowView._PanelsLayer && this._FlowView._TethersLayer)
+			{
+				this._FlowView._PropertiesPanelView.renderPanels(this._FlowView._FlowData.OpenPanels, this._FlowView._PanelsLayer, this._FlowView._TethersLayer, this._FlowView._FlowData.ViewState.SelectedTetherHash);
+			}
+		}
+		else
+		{
+			this._FlowView._renderTethersForNode(tmpPanel.NodeHash);
+		}
 	}
 }
 

package/source/views/PictView-Flow-PropertiesPanel.js

@@ -242,6 +242,13 @@ class PictViewFlowPropertiesPanel extends libPictView
 	 */
 	_renderPanelContent(pPanelData, pBodyContainer)
 	{
+		// Connection (edge) panels resolve their config and data differently from node panels.
+		if (pPanelData.ConnectionHash)
+		{
+			this._renderConnectionPanelContent(pPanelData, pBodyContainer);
+			return;
+		}
+
 		let tmpNodeData = this._FlowView.getNode(pPanelData.NodeHash);
 		if (!tmpNodeData) return;
 
@@ -298,6 +305,54 @@ class PictViewFlowPropertiesPanel extends libPictView
 		this._renderPortSummary(pBodyContainer, tmpNodeTypeConfig);
 	}
 
+	/**
+	 * Render the content of a connection (edge) panel. The config is the FlowView's single
+	 * ConnectionPropertiesPanel (connections are not typed); the panel-type instance renders
+	 * against the connection object, so a Form panel edits Connection.Data.* and a Template panel
+	 * renders against the connection.
+	 *
+	 * @param {Object} pPanelData
+	 * @param {HTMLDivElement} pBodyContainer
+	 */
+	_renderConnectionPanelContent(pPanelData, pBodyContainer)
+	{
+		let tmpConnectionData = this._FlowView.getConnection(pPanelData.ConnectionHash);
+		if (!tmpConnectionData) return;
+
+		let tmpPanelConfig = this._FlowView.options.ConnectionPropertiesPanel;
+		if (!tmpPanelConfig)
+		{
+			pBodyContainer.innerHTML = '<em>No connection properties panel configured.</em>';
+			return;
+		}
+
+		let tmpPanelType = tmpPanelConfig.PanelType || 'Base';
+		let tmpServiceName = `PictFlowCardPropertiesPanel-${tmpPanelType}`;
+		let tmpInstance = this._PanelInstances[pPanelData.Hash];
+
+		if (!tmpInstance)
+		{
+			if (this.fable.servicesMap.hasOwnProperty(tmpServiceName))
+			{
+				tmpInstance = this.fable.instantiateServiceProviderWithoutRegistration(tmpServiceName, tmpPanelConfig);
+			}
+			else if (this.fable.servicesMap.hasOwnProperty('PictFlowCardPropertiesPanel'))
+			{
+				tmpInstance = this.fable.instantiateServiceProviderWithoutRegistration('PictFlowCardPropertiesPanel', tmpPanelConfig);
+			}
+			if (tmpInstance)
+			{
+				tmpInstance._FlowView = this._FlowView;
+				this._PanelInstances[pPanelData.Hash] = tmpInstance;
+			}
+		}
+
+		if (tmpInstance)
+		{
+			tmpInstance.render(pBodyContainer, tmpConnectionData);
+		}
+	}
+
 	/**
 	 * Render an auto-generated info panel for nodes without a configured PropertiesPanel.
 	 * Shows the node type, description, and a summary of input/output ports with
@@ -716,11 +771,23 @@ class PictViewFlowPropertiesPanel extends libPictView
 		let tmpTetherService = this._FlowView._TetherService;
 		if (!tmpTetherService) return;
 
-		let tmpNodeData = this._FlowView.getNode(pPanelData.NodeHash);
-		if (!tmpNodeData) return;
+		// A connection panel tethers to the edge midpoint; model it as a zero-size anchor at that
+		// point so the same tether geometry applies. A node panel tethers to its node.
+		let tmpAnchorData;
+		if (pPanelData.ConnectionHash)
+		{
+			let tmpMidpoint = this._FlowView.getConnectionMidpoint(pPanelData.ConnectionHash);
+			if (!tmpMidpoint) return;
+			tmpAnchorData = { X: tmpMidpoint.x, Y: tmpMidpoint.y, Width: 0, Height: 0 };
+		}
+		else
+		{
+			tmpAnchorData = this._FlowView.getNode(pPanelData.NodeHash);
+			if (!tmpAnchorData) return;
+		}
 
 		let tmpViewIdentifier = this._FlowView.options.ViewIdentifier;
-		tmpTetherService.renderTether(pPanelData, tmpNodeData, pTethersLayer, pIsSelected, tmpViewIdentifier);
+		tmpTetherService.renderTether(pPanelData, tmpAnchorData, pTethersLayer, pIsSelected, tmpViewIdentifier);
 	}
 
 	/**

package/source/views/PictView-Flow.js

@@ -71,6 +71,11 @@ const _DefaultConfiguration =
 	DefaultNodeWidth: 180,
 	DefaultNodeHeight: 80,
 
+	// Properties panel for connections (edges). Connections are not typed, so one config serves
+	// them all: { PanelType, DefaultWidth, DefaultHeight, Title, Configuration }. When set, a
+	// double-click on a connection opens this panel; when false, double-click adds a bezier handle.
+	ConnectionPropertiesPanel: false,
+
 	// Layout-algorithm subsystem defaults
 	DefaultLayoutAlgorithm: 'Custom',
 	DefaultLayoutParameters: {},
@@ -1328,6 +1333,54 @@ class PictViewFlow extends libPictView
 		return this._PanelManager.togglePanel(pNodeHash);
 	}
 
+	/**
+	 * Open a properties panel for a connection (edge). Requires the ConnectionPropertiesPanel
+	 * option; returns false otherwise.
+	 * @param {string} pConnectionHash
+	 * @returns {Object|false}
+	 */
+	openConnectionPanel(pConnectionHash)
+	{
+		return this._PanelManager.openConnectionPanel(pConnectionHash);
+	}
+
+	/**
+	 * Toggle a properties panel for a connection.
+	 * @param {string} pConnectionHash
+	 * @returns {Object|false}
+	 */
+	toggleConnectionPanel(pConnectionHash)
+	{
+		return this._PanelManager.toggleConnectionPanel(pConnectionHash);
+	}
+
+	/**
+	 * Close all panels for a given connection.
+	 * @param {string} pConnectionHash
+	 * @returns {boolean}
+	 */
+	closePanelForConnection(pConnectionHash)
+	{
+		return this._PanelManager.closePanelForConnection(pConnectionHash);
+	}
+
+	/**
+	 * The midpoint of a connection in SVG coordinates, averaged from its two endpoint ports. Used
+	 * to place and tether a connection's properties panel. Returns null if the connection or
+	 * either port can not be resolved.
+	 * @param {string} pConnectionHash
+	 * @returns {{x: number, y: number}|null}
+	 */
+	getConnectionMidpoint(pConnectionHash)
+	{
+		let tmpConnection = this.getConnection(pConnectionHash);
+		if (!tmpConnection) return null;
+		let tmpSource = this.getPortPosition(tmpConnection.SourceNodeHash, tmpConnection.SourcePortHash);
+		let tmpTarget = this.getPortPosition(tmpConnection.TargetNodeHash, tmpConnection.TargetPortHash);
+		if (!tmpSource || !tmpTarget) return null;
+		return { x: (tmpSource.x + tmpTarget.x) / 2, y: (tmpSource.y + tmpTarget.y) / 2 };
+	}
+
 	/**
 	 * Update a panel's position (for drag).
 	 * @param {string} pPanelHash

package/test/PanelManager_tests.js

@@ -0,0 +1,172 @@
+const libFable = require('fable');
+const libChai = require('chai');
+const libExpect = libChai.expect;
+
+const libPanelManager = require('../source/services/PictService-Flow-PanelManager.js');
+
+/**
+ * Connection (edge) properties panels. The node-panel path is well covered through the view; these
+ * focus on the connection additions: gating on ConnectionPropertiesPanel, placement near the edge
+ * midpoint, the open/toggle/close lifecycle, and that node panels are not disturbed.
+ */
+suite
+(
+	'PictService-Flow-PanelManager (connection panels)',
+	function ()
+	{
+		let _Fable;
+		let _PanelManager;
+		let _MockFlowView;
+
+		setup
+		(
+			function ()
+			{
+				_Fable = new libFable({});
+
+				_MockFlowView =
+				{
+					fable: _Fable,
+					log: _Fable.log,
+					options:
+					{
+						ViewIdentifier: 'Test-Flow',
+						ConnectionPropertiesPanel: false
+					},
+					_FlowData:
+					{
+						Nodes:
+						[
+							{ Hash: 'n1', Type: 'state', X: 0, Y: 0, Width: 100, Height: 60, Ports: [ { Hash: 'n1-out', Direction: 'output' } ] },
+							{ Hash: 'n2', Type: 'state', X: 300, Y: 0, Width: 100, Height: 60, Ports: [ { Hash: 'n2-in', Direction: 'input' } ] }
+						],
+						Connections:
+						[
+							{ Hash: 'c1', SourceNodeHash: 'n1', SourcePortHash: 'n1-out', TargetNodeHash: 'n2', TargetPortHash: 'n2-in', Data: {} }
+						],
+						OpenPanels: [],
+						ViewState: { SelectedTetherHash: null }
+					},
+					getConnection: function (pHash) { return this._FlowData.Connections.find((pConn) => pConn.Hash === pHash) || null; },
+					getNode: function (pHash) { return this._FlowData.Nodes.find((pNode) => pNode.Hash === pHash) || null; },
+					getConnectionMidpoint: function (pHash) { return this.getConnection(pHash) ? { x: 200, y: 30 } : null; },
+					_NodeTypeProvider:
+					{
+						getNodeType: function () { return { Label: 'State', PropertiesPanel: { PanelType: 'Form', DefaultWidth: 300, DefaultHeight: 220, Title: 'State' } }; }
+					},
+					renderFlow: function () {},
+					marshalFromView: function () {},
+					_PropertiesPanelView: { destroyPanel: function () {} },
+					_EventHandlerProvider: { fireEvent: function () {} }
+				};
+
+				_PanelManager = new libPanelManager(_Fable, { FlowView: _MockFlowView }, 'PM-Test');
+			}
+		);
+
+		test
+		(
+			'openConnectionPanel returns false when no ConnectionPropertiesPanel is configured',
+			function ()
+			{
+				let tmpResult = _PanelManager.openConnectionPanel('c1');
+				libExpect(tmpResult).to.equal(false);
+				libExpect(_MockFlowView._FlowData.OpenPanels.length).to.equal(0);
+			}
+		);
+
+		test
+		(
+			'openConnectionPanel returns false for an unknown connection',
+			function ()
+			{
+				_MockFlowView.options.ConnectionPropertiesPanel = { PanelType: 'Form' };
+				let tmpResult = _PanelManager.openConnectionPanel('no-such-connection');
+				libExpect(tmpResult).to.equal(false);
+			}
+		);
+
+		test
+		(
+			'openConnectionPanel opens a panel carrying the ConnectionHash, placed near the midpoint',
+			function ()
+			{
+				_MockFlowView.options.ConnectionPropertiesPanel = { PanelType: 'Form', DefaultWidth: 320, DefaultHeight: 240, Title: 'Transition' };
+				let tmpPanel = _PanelManager.openConnectionPanel('c1');
+
+				libExpect(tmpPanel).to.be.an('object');
+				libExpect(tmpPanel.ConnectionHash).to.equal('c1');
+				libExpect(tmpPanel.NodeHash).to.equal(null);
+				libExpect(tmpPanel.Title).to.equal('Transition');
+				libExpect(tmpPanel.Width).to.equal(320);
+				libExpect(tmpPanel.Height).to.equal(240);
+				// Midpoint is (200, 30); the panel is offset from it.
+				libExpect(tmpPanel.X).to.equal(240);
+				libExpect(tmpPanel.Y).to.equal(50);
+				libExpect(_MockFlowView._FlowData.OpenPanels.length).to.equal(1);
+			}
+		);
+
+		test
+		(
+			'openConnectionPanel is idempotent: a second open returns the same panel',
+			function ()
+			{
+				_MockFlowView.options.ConnectionPropertiesPanel = { PanelType: 'Form' };
+				let tmpFirst = _PanelManager.openConnectionPanel('c1');
+				let tmpSecond = _PanelManager.openConnectionPanel('c1');
+				libExpect(tmpSecond.Hash).to.equal(tmpFirst.Hash);
+				libExpect(_MockFlowView._FlowData.OpenPanels.length).to.equal(1);
+			}
+		);
+
+		test
+		(
+			'toggleConnectionPanel opens then closes',
+			function ()
+			{
+				_MockFlowView.options.ConnectionPropertiesPanel = { PanelType: 'Form' };
+				let tmpOpened = _PanelManager.toggleConnectionPanel('c1');
+				libExpect(tmpOpened).to.be.an('object');
+				libExpect(_MockFlowView._FlowData.OpenPanels.length).to.equal(1);
+
+				let tmpClosed = _PanelManager.toggleConnectionPanel('c1');
+				libExpect(tmpClosed).to.equal(false);
+				libExpect(_MockFlowView._FlowData.OpenPanels.length).to.equal(0);
+			}
+		);
+
+		test
+		(
+			'closePanelForConnection removes the connection panel',
+			function ()
+			{
+				_MockFlowView.options.ConnectionPropertiesPanel = { PanelType: 'Form' };
+				_PanelManager.openConnectionPanel('c1');
+				let tmpRemoved = _PanelManager.closePanelForConnection('c1');
+				libExpect(tmpRemoved).to.equal(true);
+				libExpect(_MockFlowView._FlowData.OpenPanels.length).to.equal(0);
+			}
+		);
+
+		test
+		(
+			'node panels still open alongside connection panels, keyed separately',
+			function ()
+			{
+				_MockFlowView.options.ConnectionPropertiesPanel = { PanelType: 'Form' };
+				let tmpNodePanel = _PanelManager.openPanel('n1');
+				let tmpConnPanel = _PanelManager.openConnectionPanel('c1');
+
+				libExpect(tmpNodePanel.NodeHash).to.equal('n1');
+				libExpect(tmpConnPanel.ConnectionHash).to.equal('c1');
+				libExpect(_MockFlowView._FlowData.OpenPanels.length).to.equal(2);
+
+				// Closing the connection panel leaves the node panel intact.
+				_PanelManager.closePanelForConnection('c1');
+				libExpect(_MockFlowView._FlowData.OpenPanels.length).to.equal(1);
+				libExpect(_MockFlowView._FlowData.OpenPanels[0].NodeHash).to.equal('n1');
+			}
+		);
+	}
+);