pict-section-flow 0.0.1 → 0.0.2

package/source/panels/FlowCardPropertiesPanel-Template.js

@@ -0,0 +1,88 @@
+const libPictFlowCardPropertiesPanel = require('../PictFlowCardPropertiesPanel.js');
+
+/**
+ * FlowCardPropertiesPanel-Template
+ *
+ * Renders pict templates into the panel body.
+ *
+ * Configuration:
+ *   {
+ *     PanelType: 'Template',
+ *     Configuration: {
+ *       Templates: [
+ *         { Hash: 'my-template', Template: '<div>{~D:Record.Data.SomeValue~}</div>' }
+ *       ],
+ *       TemplateHash: 'my-template'
+ *     }
+ *   }
+ */
+class FlowCardPropertiesPanelTemplate extends libPictFlowCardPropertiesPanel
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.serviceType = 'PictFlowCardPropertiesPanel-Template';
+
+		this._TemplatesRegistered = false;
+	}
+
+	/**
+	 * Register templates with the pict template provider and render.
+	 */
+	render(pContainer, pNodeData)
+	{
+		super.render(pContainer, pNodeData);
+
+		if (!this._Configuration || !this._Configuration.Templates) return;
+
+		// Register templates with pict (only once)
+		if (!this._TemplatesRegistered)
+		{
+			let tmpTemplates = this._Configuration.Templates;
+			for (let i = 0; i < tmpTemplates.length; i++)
+			{
+				if (tmpTemplates[i].Hash && tmpTemplates[i].Template)
+				{
+					this.fable.TemplateProvider.addTemplate(tmpTemplates[i].Hash, tmpTemplates[i].Template);
+				}
+			}
+			this._TemplatesRegistered = true;
+		}
+
+		this._renderTemplate();
+	}
+
+	marshalToPanel(pNodeData)
+	{
+		super.marshalToPanel(pNodeData);
+		this._renderTemplate();
+	}
+
+	_renderTemplate()
+	{
+		if (!this._ContentContainer || !this._NodeData) return;
+
+		let tmpTemplateHash = this._Configuration.TemplateHash;
+		if (!tmpTemplateHash) return;
+
+		let tmpRecord = this._NodeData;
+		let tmpHTML = this.fable.parseTemplate(tmpTemplateHash, tmpRecord, null, [tmpRecord]);
+		this._ContentContainer.innerHTML = tmpHTML;
+	}
+}
+
+module.exports = FlowCardPropertiesPanelTemplate;
+
+module.exports.default_configuration = Object.assign(
+	{},
+	libPictFlowCardPropertiesPanel.default_configuration,
+	{
+		PanelType: 'Template',
+		Configuration:
+		{
+			Templates: [],
+			TemplateHash: ''
+		}
+	}
+);

package/source/panels/FlowCardPropertiesPanel-View.js

@@ -0,0 +1,114 @@
+const libPictFlowCardPropertiesPanel = require('../PictFlowCardPropertiesPanel.js');
+
+/**
+ * FlowCardPropertiesPanel-View
+ *
+ * Renders an existing registered pict-view into the panel body.
+ * The view's destination is temporarily overridden to render inside
+ * the panel container.
+ *
+ * Configuration:
+ *   {
+ *     PanelType: 'View',
+ *     Configuration: {
+ *       ViewHash: 'MyCustomViewIdentifier'
+ *     }
+ *   }
+ */
+class FlowCardPropertiesPanelView extends libPictFlowCardPropertiesPanel
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.serviceType = 'PictFlowCardPropertiesPanel-View';
+
+		this._OriginalDestination = null;
+		this._ViewInstance = null;
+	}
+
+	/**
+	 * Render the referenced pict-view into the panel body.
+	 */
+	render(pContainer, pNodeData)
+	{
+		super.render(pContainer, pNodeData);
+
+		if (!this._Configuration || !this._Configuration.ViewHash)
+		{
+			pContainer.innerHTML = '<em>No ViewHash configured</em>';
+			return;
+		}
+
+		let tmpViewHash = this._Configuration.ViewHash;
+
+		// Create a unique container ID
+		let tmpContainerID = `pict-flow-panel-view-${pNodeData.Hash}`;
+		pContainer.innerHTML = `<div id="${tmpContainerID}"></div>`;
+
+		try
+		{
+			// Look up the view in the pict instance
+			let tmpPict = this.pict || this.fable;
+			if (tmpPict.views && tmpPict.views[tmpViewHash])
+			{
+				this._ViewInstance = tmpPict.views[tmpViewHash];
+
+				// Save original destination
+				this._OriginalDestination = this._ViewInstance.options.DefaultDestinationAddress;
+
+				// Override destination to our panel container
+				this._ViewInstance.options.DefaultDestinationAddress = `#${tmpContainerID}`;
+
+				if (typeof this._ViewInstance.render === 'function')
+				{
+					this._ViewInstance.render();
+				}
+			}
+			else
+			{
+				pContainer.innerHTML = `<em>View "${tmpViewHash}" not found</em>`;
+			}
+		}
+		catch (pError)
+		{
+			this.log.warn(`FlowCardPropertiesPanel-View render error: ${pError.message}`);
+			pContainer.innerHTML = `<em>View render error: ${pError.message}</em>`;
+		}
+	}
+
+	marshalFromPanel(pNodeData)
+	{
+		if (this._ViewInstance && typeof this._ViewInstance.marshalFromView === 'function')
+		{
+			this._ViewInstance.marshalFromView();
+		}
+	}
+
+	destroy()
+	{
+		// Restore original destination
+		if (this._ViewInstance && this._OriginalDestination)
+		{
+			this._ViewInstance.options.DefaultDestinationAddress = this._OriginalDestination;
+		}
+
+		this._ViewInstance = null;
+		this._OriginalDestination = null;
+		super.destroy();
+	}
+}
+
+module.exports = FlowCardPropertiesPanelView;
+
+module.exports.default_configuration = Object.assign(
+	{},
+	libPictFlowCardPropertiesPanel.default_configuration,
+	{
+		PanelType: 'View',
+		Configuration:
+		{
+			ViewHash: ''
+		}
+	}
+);

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

@@ -11,14 +11,25 @@ const _ProviderConfiguration =
  * for flow events like node selection, movement, connection creation, etc.
  *
  * Supported events:
- * - onNodeSelected(node)       - A node was selected (or null for deselection)
- * - onNodeAdded(node)          - A new node was added
- * - onNodeRemoved(node)        - A node was removed
- * - onNodeMoved(node)          - A node was moved to a new position
- * - onConnectionSelected(conn) - A connection was selected
- * - onConnectionCreated(conn)  - A new connection was created
- * - onConnectionRemoved(conn)  - A connection was removed
- * - onFlowChanged(flowData)    - The flow data changed (catch-all)
+ * - onNodeSelected(node)              - A node was selected (or null for deselection)
+ * - onNodeAdded(node)                 - A new node was added
+ * - onNodeRemoved(node)               - A node was removed
+ * - onNodeMoved(node)                 - A node was moved to a new position
+ * - onConnectionSelected(conn)        - A connection was selected
+ * - onConnectionCreated(conn)         - A new connection was created
+ * - onConnectionRemoved(conn)         - A connection was removed
+ * - onConnectionHandleMoved(conn)     - A connection's drag handle was repositioned
+ * - onConnectionModeChanged(conn)     - A connection's line mode was toggled (bezier/orthogonal)
+ * - onPanelOpened(panelData)          - A properties panel was opened
+ * - onPanelClosed(panelData)          - A properties panel was closed
+ * - onPanelMoved(panelData)           - A properties panel was moved
+ * - onTetherSelected(panelData)       - A tether line was selected (or null for deselection)
+ * - onTetherHandleMoved(panelData)    - A tether's drag handle was repositioned
+ * - onTetherModeChanged(panelData)    - A tether's line mode was toggled (bezier/orthogonal)
+ * - onLayoutSaved(layoutData)         - A layout snapshot was saved
+ * - onLayoutRestored(layoutData)      - A saved layout was restored
+ * - onLayoutDeleted(layoutData)       - A saved layout was deleted
+ * - onFlowChanged(flowData)           - The flow data changed (catch-all)
  */
 class PictProviderFlowEventHandler extends libPictProvider
 {

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

@@ -0,0 +1,64 @@
+const libFableServiceProviderBase = require('fable-serviceproviderbase');
+
+/**
+ * PictProvider-Flow-Geometry
+ *
+ * Shared geometry utilities for the flow diagram.
+ * Provides direction vectors and edge center calculations used by
+ * connections, tethers, and other flow components.
+ */
+class PictProviderFlowGeometry extends libFableServiceProviderBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.serviceType = 'PictProviderFlowGeometry';
+	}
+
+	/**
+	 * Get the outward unit direction vector for a given side.
+	 *
+	 * @param {string} pSide - 'left', 'right', 'top', or 'bottom'
+	 * @returns {{dx: number, dy: number}}
+	 */
+	sideDirection(pSide)
+	{
+		switch (pSide)
+		{
+			case 'left':   return { dx: -1, dy: 0 };
+			case 'right':  return { dx: 1, dy: 0 };
+			case 'top':    return { dx: 0, dy: -1 };
+			case 'bottom': return { dx: 0, dy: 1 };
+			default:       return { dx: 1, dy: 0 };
+		}
+	}
+
+	/**
+	 * Get the center point of a rectangle's edge.
+	 * Works for any object with X, Y, Width, Height properties
+	 * (nodes, panels, or any rectangular element).
+	 *
+	 * @param {Object} pRectData - Object with X, Y, Width, Height
+	 * @param {string} pSide - 'left', 'right', 'top', 'bottom'
+	 * @returns {{x: number, y: number}}
+	 */
+	getEdgeCenter(pRectData, pSide)
+	{
+		switch (pSide)
+		{
+			case 'left':
+				return { x: pRectData.X, y: pRectData.Y + pRectData.Height / 2 };
+			case 'right':
+				return { x: pRectData.X + pRectData.Width, y: pRectData.Y + pRectData.Height / 2 };
+			case 'top':
+				return { x: pRectData.X + pRectData.Width / 2, y: pRectData.Y };
+			case 'bottom':
+				return { x: pRectData.X + pRectData.Width / 2, y: pRectData.Y + pRectData.Height };
+			default:
+				return { x: pRectData.X + pRectData.Width, y: pRectData.Y + pRectData.Height / 2 };
+		}
+	}
+}
+
+module.exports = PictProviderFlowGeometry;

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

@@ -0,0 +1,284 @@
+const libPictProvider = require('pict-provider');
+
+const _ProviderConfiguration =
+{
+	ProviderIdentifier: 'PictProviderFlowLayouts'
+};
+
+/**
+ * Provider for managing saved flow diagram layouts.
+ *
+ * Layouts capture the spatial arrangement of nodes and panels on the canvas
+ * without storing any card content. When a layout is restored, nodes that
+ * still exist are placed at their saved positions and any new nodes are
+ * auto-laid-out to the right.
+ *
+ * Saved layout data structure:
+ * {
+ *     Hash: "layout-<UUID>",
+ *     Name: "My Layout",
+ *     CreatedAt: "2026-02-26T12:00:00.000Z",
+ *     NodePositions: { "node-hash": { X, Y, Width, Height } },
+ *     PanelPositions: { "node-hash": { X, Y, Width, Height } },
+ *     ViewState: { PanX, PanY, Zoom }
+ * }
+ */
+class PictProviderFlowLayouts extends libPictProvider
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		let tmpOptions = Object.assign({}, _ProviderConfiguration, pOptions);
+		super(pFable, tmpOptions, pServiceHash);
+
+		this.serviceType = 'PictProviderFlowLayouts';
+
+		this._FlowView = (pOptions && pOptions.FlowView) ? pOptions.FlowView : null;
+	}
+
+	/**
+	 * Save the current node and panel positions as a named layout.
+	 * @param {string} pName - The display name for this layout
+	 * @returns {Object} The saved layout entry
+	 */
+	saveLayout(pName)
+	{
+		if (!this._FlowView)
+		{
+			this.log.warn('PictProviderFlowLayouts saveLayout: no FlowView reference');
+			return null;
+		}
+
+		let tmpFlowData = this._FlowView._FlowData;
+		let tmpLayoutHash = `layout-${this.fable.getUUID()}`;
+		let tmpNodePositions = {};
+		let tmpPanelPositions = {};
+
+		// Capture node positions (arrangement only, no content)
+		for (let i = 0; i < tmpFlowData.Nodes.length; i++)
+		{
+			let tmpNode = tmpFlowData.Nodes[i];
+			tmpNodePositions[tmpNode.Hash] =
+			{
+				X: tmpNode.X,
+				Y: tmpNode.Y,
+				Width: tmpNode.Width,
+				Height: tmpNode.Height
+			};
+		}
+
+		// Capture panel positions keyed by NodeHash (panels get new hashes on each open)
+		for (let i = 0; i < tmpFlowData.OpenPanels.length; i++)
+		{
+			let tmpPanel = tmpFlowData.OpenPanels[i];
+			tmpPanelPositions[tmpPanel.NodeHash] =
+			{
+				X: tmpPanel.X,
+				Y: tmpPanel.Y,
+				Width: tmpPanel.Width,
+				Height: tmpPanel.Height
+			};
+		}
+
+		let tmpLayout =
+		{
+			Hash: tmpLayoutHash,
+			Name: pName || 'Untitled Layout',
+			CreatedAt: new Date().toISOString(),
+			NodePositions: tmpNodePositions,
+			PanelPositions: tmpPanelPositions,
+			ViewState:
+			{
+				PanX: tmpFlowData.ViewState.PanX,
+				PanY: tmpFlowData.ViewState.PanY,
+				Zoom: tmpFlowData.ViewState.Zoom
+			}
+		};
+
+		tmpFlowData.SavedLayouts.push(tmpLayout);
+		this._FlowView.marshalFromView();
+
+		if (this._FlowView._EventHandlerProvider)
+		{
+			this._FlowView._EventHandlerProvider.fireEvent('onLayoutSaved', tmpLayout);
+			this._FlowView._EventHandlerProvider.fireEvent('onFlowChanged', tmpFlowData);
+		}
+
+		this.log.trace(`PictProviderFlowLayouts saved layout '${tmpLayout.Name}' (${tmpLayout.Hash})`);
+
+		return tmpLayout;
+	}
+
+	/**
+	 * Restore a saved layout by hash.
+	 * Nodes present in the saved layout are placed at their saved positions.
+	 * Nodes not in the saved layout are auto-laid-out to the right of the
+	 * positioned nodes.
+	 * @param {string} pLayoutHash - The hash of the layout to restore
+	 * @returns {boolean} Whether the layout was restored
+	 */
+	restoreLayout(pLayoutHash)
+	{
+		if (!this._FlowView)
+		{
+			this.log.warn('PictProviderFlowLayouts restoreLayout: no FlowView reference');
+			return false;
+		}
+
+		let tmpFlowData = this._FlowView._FlowData;
+		let tmpLayout = tmpFlowData.SavedLayouts.find(
+			(pLayout) => pLayout.Hash === pLayoutHash
+		);
+
+		if (!tmpLayout)
+		{
+			this.log.warn(`PictProviderFlowLayouts restoreLayout: layout '${pLayoutHash}' not found`);
+			return false;
+		}
+
+		let tmpMatchedNodes = [];
+		let tmpUnmatchedNodes = [];
+
+		// Apply saved positions to matched nodes; collect unmatched ones
+		for (let i = 0; i < tmpFlowData.Nodes.length; i++)
+		{
+			let tmpNode = tmpFlowData.Nodes[i];
+			let tmpSaved = tmpLayout.NodePositions[tmpNode.Hash];
+
+			if (tmpSaved)
+			{
+				tmpNode.X = tmpSaved.X;
+				tmpNode.Y = tmpSaved.Y;
+				if (typeof tmpSaved.Width === 'number') tmpNode.Width = tmpSaved.Width;
+				if (typeof tmpSaved.Height === 'number') tmpNode.Height = tmpSaved.Height;
+				tmpMatchedNodes.push(tmpNode);
+			}
+			else
+			{
+				tmpUnmatchedNodes.push(tmpNode);
+			}
+		}
+
+		// Apply saved panel positions (keyed by NodeHash)
+		if (tmpLayout.PanelPositions)
+		{
+			for (let i = 0; i < tmpFlowData.OpenPanels.length; i++)
+			{
+				let tmpPanel = tmpFlowData.OpenPanels[i];
+				let tmpSavedPanel = tmpLayout.PanelPositions[tmpPanel.NodeHash];
+
+				if (tmpSavedPanel)
+				{
+					tmpPanel.X = tmpSavedPanel.X;
+					tmpPanel.Y = tmpSavedPanel.Y;
+					if (typeof tmpSavedPanel.Width === 'number') tmpPanel.Width = tmpSavedPanel.Width;
+					if (typeof tmpSavedPanel.Height === 'number') tmpPanel.Height = tmpSavedPanel.Height;
+				}
+			}
+		}
+
+		// Auto-layout unmatched nodes to the right of positioned nodes
+		if (tmpUnmatchedNodes.length > 0 && this._FlowView._LayoutService)
+		{
+			this._FlowView._LayoutService.autoLayoutSubset(
+				tmpUnmatchedNodes,
+				tmpMatchedNodes,
+				tmpFlowData.Connections
+			);
+		}
+
+		// Restore view state (camera position)
+		if (tmpLayout.ViewState)
+		{
+			if (typeof tmpLayout.ViewState.PanX === 'number')
+			{
+				tmpFlowData.ViewState.PanX = tmpLayout.ViewState.PanX;
+			}
+			if (typeof tmpLayout.ViewState.PanY === 'number')
+			{
+				tmpFlowData.ViewState.PanY = tmpLayout.ViewState.PanY;
+			}
+			if (typeof tmpLayout.ViewState.Zoom === 'number')
+			{
+				tmpFlowData.ViewState.Zoom = tmpLayout.ViewState.Zoom;
+			}
+		}
+
+		this._FlowView.renderFlow();
+		this._FlowView.marshalFromView();
+
+		if (this._FlowView._EventHandlerProvider)
+		{
+			this._FlowView._EventHandlerProvider.fireEvent('onLayoutRestored', tmpLayout);
+			this._FlowView._EventHandlerProvider.fireEvent('onFlowChanged', tmpFlowData);
+		}
+
+		this.log.trace(`PictProviderFlowLayouts restored layout '${tmpLayout.Name}' (${tmpLayout.Hash})`);
+
+		return true;
+	}
+
+	/**
+	 * Delete a saved layout by hash.
+	 * @param {string} pLayoutHash - The hash of the layout to delete
+	 * @returns {boolean} Whether the layout was deleted
+	 */
+	deleteLayout(pLayoutHash)
+	{
+		if (!this._FlowView)
+		{
+			this.log.warn('PictProviderFlowLayouts deleteLayout: no FlowView reference');
+			return false;
+		}
+
+		let tmpFlowData = this._FlowView._FlowData;
+		let tmpIndex = tmpFlowData.SavedLayouts.findIndex(
+			(pLayout) => pLayout.Hash === pLayoutHash
+		);
+
+		if (tmpIndex < 0)
+		{
+			this.log.warn(`PictProviderFlowLayouts deleteLayout: layout '${pLayoutHash}' not found`);
+			return false;
+		}
+
+		let tmpRemovedLayout = tmpFlowData.SavedLayouts.splice(tmpIndex, 1)[0];
+		this._FlowView.marshalFromView();
+
+		if (this._FlowView._EventHandlerProvider)
+		{
+			this._FlowView._EventHandlerProvider.fireEvent('onLayoutDeleted', tmpRemovedLayout);
+			this._FlowView._EventHandlerProvider.fireEvent('onFlowChanged', tmpFlowData);
+		}
+
+		this.log.trace(`PictProviderFlowLayouts deleted layout '${tmpRemovedLayout.Name}' (${tmpRemovedLayout.Hash})`);
+
+		return true;
+	}
+
+	/**
+	 * Get the list of saved layouts.
+	 * @returns {Array} Array of saved layout objects
+	 */
+	getLayouts()
+	{
+		if (!this._FlowView) return [];
+		return this._FlowView._FlowData.SavedLayouts;
+	}
+
+	/**
+	 * Get a specific saved layout by hash.
+	 * @param {string} pLayoutHash
+	 * @returns {Object|null}
+	 */
+	getLayout(pLayoutHash)
+	{
+		if (!this._FlowView) return null;
+		return this._FlowView._FlowData.SavedLayouts.find(
+			(pLayout) => pLayout.Hash === pLayoutHash
+		) || null;
+	}
+}
+
+module.exports = PictProviderFlowLayouts;
+
+module.exports.default_configuration = _ProviderConfiguration;

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

@@ -93,6 +93,20 @@ class PictProviderFlowNodeTypes extends libPictProvider
 
 		// Initialize with default node types
 		this._NodeTypes = JSON.parse(JSON.stringify(_DefaultNodeTypes));
+
+		// Merge any additional node types passed in via options
+		if (pOptions && pOptions.AdditionalNodeTypes && typeof pOptions.AdditionalNodeTypes === 'object')
+		{
+			let tmpAdditionalKeys = Object.keys(pOptions.AdditionalNodeTypes);
+			for (let i = 0; i < tmpAdditionalKeys.length; i++)
+			{
+				this._NodeTypes[tmpAdditionalKeys[i]] = Object.assign(
+					{},
+					this._NodeTypes[tmpAdditionalKeys[i]] || {},
+					JSON.parse(JSON.stringify(pOptions.AdditionalNodeTypes[tmpAdditionalKeys[i]]))
+				);
+			}
+		}
 	}
 
 	/**
@@ -166,6 +180,62 @@ class PictProviderFlowNodeTypes extends libPictProvider
 	{
 		return Object.keys(this._NodeTypes);
 	}
+
+	/**
+	 * Get all enabled node types that have FlowCard metadata.
+	 * Returns only types that are cards and whose Enabled flag is true.
+	 * @returns {Array<Object>} Array of node type configurations
+	 */
+	getEnabledCards()
+	{
+		let tmpCards = [];
+		let tmpKeys = Object.keys(this._NodeTypes);
+		for (let i = 0; i < tmpKeys.length; i++)
+		{
+			let tmpType = this._NodeTypes[tmpKeys[i]];
+			if (tmpType.CardMetadata)
+			{
+				if (tmpType.CardMetadata.Enabled !== false)
+				{
+					tmpCards.push(JSON.parse(JSON.stringify(tmpType)));
+				}
+			}
+		}
+		return tmpCards;
+	}
+
+	/**
+	 * Get all enabled cards grouped by category.
+	 * @returns {Object} Map of category name to array of node type configurations
+	 */
+	getCardsByCategory()
+	{
+		let tmpCards = this.getEnabledCards();
+		let tmpCategories = {};
+		for (let i = 0; i < tmpCards.length; i++)
+		{
+			let tmpCategory = (tmpCards[i].CardMetadata && tmpCards[i].CardMetadata.Category)
+				? tmpCards[i].CardMetadata.Category
+				: 'General';
+			if (!tmpCategories[tmpCategory])
+			{
+				tmpCategories[tmpCategory] = [];
+			}
+			tmpCategories[tmpCategory].push(tmpCards[i]);
+		}
+		return tmpCategories;
+	}
+
+	/**
+	 * Check whether a node type hash refers to a FlowCard (has CardMetadata).
+	 * @param {string} pTypeHash
+	 * @returns {boolean}
+	 */
+	isFlowCard(pTypeHash)
+	{
+		let tmpType = this._NodeTypes[pTypeHash];
+		return !!(tmpType && tmpType.CardMetadata);
+	}
 }
 
 module.exports = PictProviderFlowNodeTypes;