pict-section-flow 0.0.2 → 0.0.5

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

@@ -0,0 +1,413 @@
+const libFableServiceProviderBase = require('fable-serviceproviderbase');
+
+class PictProviderFlowConnectorShapes extends libFableServiceProviderBase
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, pOptions, pServiceHash);
+
+		this.serviceType = 'PictProviderFlowConnectorShapes';
+
+		this._FlowView = (pOptions && pOptions.FlowView) ? pOptions.FlowView : null;
+
+		// Default shape configurations — each keyed by a shape identifier
+		// _OriginalShapes stores a deep copy for reset when switching themes.
+		this._DefaultShapes =
+		{
+			'port':
+			{
+				ElementType: 'circle',
+				Attributes: { r: '5' },
+				ClassName: 'pict-flow-port'
+			},
+			'panel-indicator':
+			{
+				ElementType: 'rect',
+				Attributes: { rx: '2', ry: '2' },
+				ClassName: 'pict-flow-node-panel-indicator'
+			},
+			'connection-path':
+			{
+				ElementType: 'path',
+				Attributes: {},
+				ClassName: 'pict-flow-connection'
+			},
+			'connection-hitarea':
+			{
+				ElementType: 'path',
+				Attributes: {},
+				ClassName: 'pict-flow-connection-hitarea'
+			},
+			'connection-handle':
+			{
+				ElementType: 'circle',
+				Attributes: { r: '6' },
+				ClassName: 'pict-flow-connection-handle'
+			},
+			'connection-handle-midpoint':
+			{
+				ElementType: 'circle',
+				Attributes: { r: '6' },
+				ClassName: 'pict-flow-connection-handle-midpoint'
+			},
+			'drag-connection':
+			{
+				ElementType: 'path',
+				Attributes: {},
+				ClassName: 'pict-flow-drag-connection'
+			},
+			'tether-path':
+			{
+				ElementType: 'path',
+				Attributes: {},
+				ClassName: 'pict-flow-tether-line'
+			},
+			'tether-hitarea':
+			{
+				ElementType: 'path',
+				Attributes: {},
+				ClassName: 'pict-flow-tether-hitarea'
+			},
+			'tether-handle':
+			{
+				ElementType: 'circle',
+				Attributes: { r: '6' },
+				ClassName: 'pict-flow-tether-handle'
+			},
+			'tether-handle-midpoint':
+			{
+				ElementType: 'circle',
+				Attributes: { r: '6' },
+				ClassName: 'pict-flow-tether-handle-midpoint'
+			},
+			'arrowhead-connection':
+			{
+				MarkerWidth: '5',
+				MarkerHeight: '7',
+				RefX: '7.5',
+				RefY: '3.5',
+				Points: '0 0, 5 3.5, 0 7',
+				Fill: '#95a5a6'
+			},
+			'arrowhead-connection-selected':
+			{
+				MarkerWidth: '5',
+				MarkerHeight: '7',
+				RefX: '7.5',
+				RefY: '3.5',
+				Points: '0 0, 5 3.5, 0 7',
+				Fill: '#3498db'
+			},
+			'arrowhead-tether':
+			{
+				MarkerWidth: '4',
+				MarkerHeight: '6',
+				RefX: '6',
+				RefY: '3',
+				Points: '0 0, 4 3, 0 6',
+				Fill: '#95a5a6'
+			}
+		};
+
+		// Store a deep copy for resetting when switching themes
+		this._OriginalShapes = JSON.parse(JSON.stringify(this._DefaultShapes));
+	}
+
+	// ── Theme Override Methods ─────────────────────────────────────────────
+
+	/**
+	 * Apply theme-specific shape overrides.
+	 * Merges the overrides into the active shape configs.
+	 * @param {Object} pOverrides - Map of shape key to partial config
+	 */
+	applyThemeOverrides(pOverrides)
+	{
+		if (!pOverrides || typeof pOverrides !== 'object')
+		{
+			return;
+		}
+		for (let tmpKey in pOverrides)
+		{
+			if (this._DefaultShapes.hasOwnProperty(tmpKey))
+			{
+				Object.assign(this._DefaultShapes[tmpKey], pOverrides[tmpKey]);
+			}
+			else
+			{
+				this._DefaultShapes[tmpKey] = pOverrides[tmpKey];
+			}
+		}
+	}
+
+	/**
+	 * Reset all shape configs to their original defaults.
+	 * Called before applying new theme overrides to prevent accumulation.
+	 */
+	resetToDefaults()
+	{
+		this._DefaultShapes = JSON.parse(JSON.stringify(this._OriginalShapes));
+	}
+
+	/**
+	 * Get a shape configuration by key.
+	 * @param {string} pShapeKey
+	 * @returns {Object|null}
+	 */
+	getShapeConfig(pShapeKey)
+	{
+		if (this._DefaultShapes.hasOwnProperty(pShapeKey))
+		{
+			return this._DefaultShapes[pShapeKey];
+		}
+		return null;
+	}
+
+	/**
+	 * Override or add a shape configuration.
+	 * Consumers can call this to customize connector shapes without subclassing.
+	 * @param {string} pShapeKey
+	 * @param {Object} pConfig
+	 */
+	setShapeConfig(pShapeKey, pConfig)
+	{
+		this._DefaultShapes[pShapeKey] = pConfig;
+	}
+
+	/**
+	 * Get all registered shape keys.
+	 * @returns {string[]}
+	 */
+	getShapeKeys()
+	{
+		return Object.keys(this._DefaultShapes);
+	}
+
+	// ---- Factory Methods ----
+
+	/**
+	 * Create a port SVG element.
+	 * @param {Object} pPortData - Port data with Hash, Direction
+	 * @param {{x: number, y: number}} pPosition - Local position within the node group
+	 * @param {string} pNodeHash - The owning node hash
+	 * @returns {SVGCircleElement}
+	 */
+	createPortElement(pPortData, pPosition, pNodeHash)
+	{
+		let tmpConfig = this._DefaultShapes['port'];
+		let tmpElement = this._FlowView._SVGHelperProvider.createSVGElement(tmpConfig.ElementType);
+		tmpElement.setAttribute('class', tmpConfig.ClassName + ' ' + pPortData.Direction);
+		tmpElement.setAttribute('cx', String(pPosition.x));
+		tmpElement.setAttribute('cy', String(pPosition.y));
+		// Apply config attributes (r, etc.)
+		for (let tmpKey in tmpConfig.Attributes)
+		{
+			tmpElement.setAttribute(tmpKey, tmpConfig.Attributes[tmpKey]);
+		}
+		tmpElement.setAttribute('data-port-hash', pPortData.Hash);
+		tmpElement.setAttribute('data-node-hash', pNodeHash);
+		tmpElement.setAttribute('data-port-direction', pPortData.Direction);
+		tmpElement.setAttribute('data-element-type', 'port');
+		return tmpElement;
+	}
+
+	/**
+	 * Create a panel indicator SVG element.
+	 * @param {string} pNodeHash
+	 * @param {number} pX
+	 * @param {number} pY
+	 * @param {number} pWidth
+	 * @param {number} pHeight
+	 * @returns {SVGRectElement}
+	 */
+	createPanelIndicatorElement(pNodeHash, pX, pY, pWidth, pHeight)
+	{
+		let tmpConfig = this._DefaultShapes['panel-indicator'];
+		let tmpElement = this._FlowView._SVGHelperProvider.createSVGElement(tmpConfig.ElementType);
+		tmpElement.setAttribute('class', tmpConfig.ClassName);
+		tmpElement.setAttribute('x', String(pX));
+		tmpElement.setAttribute('y', String(pY));
+		tmpElement.setAttribute('width', String(pWidth));
+		tmpElement.setAttribute('height', String(pHeight));
+		// Apply config attributes (rx, ry, etc.)
+		for (let tmpKey in tmpConfig.Attributes)
+		{
+			tmpElement.setAttribute(tmpKey, tmpConfig.Attributes[tmpKey]);
+		}
+		tmpElement.setAttribute('data-node-hash', pNodeHash);
+		tmpElement.setAttribute('data-element-type', 'panel-indicator');
+		return tmpElement;
+	}
+
+	/**
+	 * Create a visible connection path SVG element.
+	 * @param {string} pPath - The SVG path d-string
+	 * @param {string} pConnectionHash
+	 * @param {boolean} pIsSelected
+	 * @param {string} pViewIdentifier
+	 * @returns {SVGPathElement}
+	 */
+	createConnectionPathElement(pPath, pConnectionHash, pIsSelected, pViewIdentifier)
+	{
+		let tmpConfig = this._DefaultShapes['connection-path'];
+		let tmpElement = this._FlowView._SVGHelperProvider.createSVGElement(tmpConfig.ElementType);
+		tmpElement.setAttribute('class', tmpConfig.ClassName + (pIsSelected ? ' selected' : ''));
+		tmpElement.setAttribute('d', pPath);
+		tmpElement.setAttribute('data-connection-hash', pConnectionHash);
+		tmpElement.setAttribute('data-element-type', 'connection');
+
+		// Arrow marker
+		let tmpMarkerConfig = pIsSelected
+			? this._DefaultShapes['arrowhead-connection-selected']
+			: this._DefaultShapes['arrowhead-connection'];
+		// The marker id follows the naming convention used in generateMarkerDefs
+		let tmpMarkerId = pIsSelected
+			? ('flow-arrowhead-selected-' + pViewIdentifier)
+			: ('flow-arrowhead-' + pViewIdentifier);
+		tmpElement.setAttribute('marker-end', 'url(#' + tmpMarkerId + ')');
+
+		return tmpElement;
+	}
+
+	/**
+	 * Create a connection hit area SVG element (wider invisible path for click targeting).
+	 * @param {string} pPath - The SVG path d-string
+	 * @param {string} pConnectionHash
+	 * @returns {SVGPathElement}
+	 */
+	createConnectionHitAreaElement(pPath, pConnectionHash)
+	{
+		let tmpConfig = this._DefaultShapes['connection-hitarea'];
+		let tmpElement = this._FlowView._SVGHelperProvider.createSVGElement(tmpConfig.ElementType);
+		tmpElement.setAttribute('class', tmpConfig.ClassName);
+		tmpElement.setAttribute('d', pPath);
+		tmpElement.setAttribute('data-connection-hash', pConnectionHash);
+		tmpElement.setAttribute('data-element-type', 'connection-hitarea');
+		return tmpElement;
+	}
+
+	/**
+	 * Create a drag handle circle element.
+	 * Works for both connection handles and tether handles.
+	 * @param {string} pOwnerHash - Connection hash or panel hash
+	 * @param {string} pHandleType - e.g. 'ortho-corner1', 'bezier-midpoint'
+	 * @param {number} pX
+	 * @param {number} pY
+	 * @param {string} pShapeKey - 'connection-handle', 'connection-handle-midpoint', 'tether-handle', 'tether-handle-midpoint'
+	 * @returns {SVGCircleElement}
+	 */
+	createHandleElement(pOwnerHash, pHandleType, pX, pY, pShapeKey)
+	{
+		let tmpConfig = this._DefaultShapes[pShapeKey] || this._DefaultShapes['connection-handle'];
+		let tmpElement = this._FlowView._SVGHelperProvider.createSVGElement(tmpConfig.ElementType);
+		tmpElement.setAttribute('class', tmpConfig.ClassName);
+		tmpElement.setAttribute('cx', String(pX));
+		tmpElement.setAttribute('cy', String(pY));
+		// Apply config attributes (r, etc.)
+		for (let tmpKey in tmpConfig.Attributes)
+		{
+			tmpElement.setAttribute(tmpKey, tmpConfig.Attributes[tmpKey]);
+		}
+		tmpElement.setAttribute('data-handle-type', pHandleType);
+		return tmpElement;
+	}
+
+	/**
+	 * Create a temporary drag connection path element.
+	 * @param {string} pPath - The SVG path d-string
+	 * @returns {SVGPathElement}
+	 */
+	createDragConnectionElement(pPath)
+	{
+		let tmpConfig = this._DefaultShapes['drag-connection'];
+		let tmpElement = this._FlowView._SVGHelperProvider.createSVGElement(tmpConfig.ElementType);
+		tmpElement.setAttribute('class', tmpConfig.ClassName);
+		tmpElement.setAttribute('d', pPath);
+		return tmpElement;
+	}
+
+	/**
+	 * Create a visible tether path SVG element.
+	 * @param {string} pPath - The SVG path d-string
+	 * @param {string} pPanelHash
+	 * @param {boolean} pIsSelected
+	 * @param {string} pViewIdentifier
+	 * @returns {SVGPathElement}
+	 */
+	createTetherPathElement(pPath, pPanelHash, pIsSelected, pViewIdentifier)
+	{
+		let tmpConfig = this._DefaultShapes['tether-path'];
+		let tmpElement = this._FlowView._SVGHelperProvider.createSVGElement(tmpConfig.ElementType);
+		tmpElement.setAttribute('class', tmpConfig.ClassName + (pIsSelected ? ' selected' : ''));
+		tmpElement.setAttribute('d', pPath);
+		tmpElement.setAttribute('marker-end', 'url(#flow-tether-arrowhead-' + pViewIdentifier + ')');
+		tmpElement.setAttribute('data-element-type', 'tether');
+		tmpElement.setAttribute('data-panel-hash', pPanelHash);
+		return tmpElement;
+	}
+
+	/**
+	 * Create a tether hit area SVG element.
+	 * @param {string} pPath - The SVG path d-string
+	 * @param {string} pPanelHash
+	 * @returns {SVGPathElement}
+	 */
+	createTetherHitAreaElement(pPath, pPanelHash)
+	{
+		let tmpConfig = this._DefaultShapes['tether-hitarea'];
+		let tmpElement = this._FlowView._SVGHelperProvider.createSVGElement(tmpConfig.ElementType);
+		tmpElement.setAttribute('class', tmpConfig.ClassName);
+		tmpElement.setAttribute('d', pPath);
+		tmpElement.setAttribute('data-element-type', 'tether-hitarea');
+		tmpElement.setAttribute('data-panel-hash', pPanelHash);
+		return tmpElement;
+	}
+
+	/**
+	 * Generate SVG marker definition markup for all arrowhead types.
+	 * Returns raw SVG markup to be injected into the <defs> section.
+	 * @param {string} pViewIdentifier
+	 * @returns {string}
+	 */
+	generateMarkerDefs(pViewIdentifier)
+	{
+		let tmpConnectionMarker = this._DefaultShapes['arrowhead-connection'];
+		let tmpSelectedMarker = this._DefaultShapes['arrowhead-connection-selected'];
+		let tmpTetherMarker = this._DefaultShapes['arrowhead-tether'];
+
+		let tmpMarkup = '';
+
+		// Normal connection arrowhead
+		tmpMarkup += '<marker id="flow-arrowhead-' + pViewIdentifier + '"'
+			+ ' markerWidth="' + tmpConnectionMarker.MarkerWidth + '"'
+			+ ' markerHeight="' + tmpConnectionMarker.MarkerHeight + '"'
+			+ ' refX="' + tmpConnectionMarker.RefX + '"'
+			+ ' refY="' + tmpConnectionMarker.RefY + '"'
+			+ ' orient="auto" markerUnits="strokeWidth">'
+			+ '<polygon points="' + tmpConnectionMarker.Points + '" fill="' + tmpConnectionMarker.Fill + '" />'
+			+ '</marker>';
+
+		// Selected connection arrowhead
+		tmpMarkup += '<marker id="flow-arrowhead-selected-' + pViewIdentifier + '"'
+			+ ' markerWidth="' + tmpSelectedMarker.MarkerWidth + '"'
+			+ ' markerHeight="' + tmpSelectedMarker.MarkerHeight + '"'
+			+ ' refX="' + tmpSelectedMarker.RefX + '"'
+			+ ' refY="' + tmpSelectedMarker.RefY + '"'
+			+ ' orient="auto" markerUnits="strokeWidth">'
+			+ '<polygon points="' + tmpSelectedMarker.Points + '" fill="' + tmpSelectedMarker.Fill + '" />'
+			+ '</marker>';
+
+		// Tether arrowhead
+		tmpMarkup += '<marker id="flow-tether-arrowhead-' + pViewIdentifier + '"'
+			+ ' markerWidth="' + tmpTetherMarker.MarkerWidth + '"'
+			+ ' markerHeight="' + tmpTetherMarker.MarkerHeight + '"'
+			+ ' refX="' + tmpTetherMarker.RefX + '"'
+			+ ' refY="' + tmpTetherMarker.RefY + '"'
+			+ ' orient="auto" markerUnits="strokeWidth">'
+			+ '<polygon points="' + tmpTetherMarker.Points + '" fill="' + tmpTetherMarker.Fill + '" />'
+			+ '</marker>';
+
+		return tmpMarkup;
+	}
+}
+
+module.exports = PictProviderFlowConnectorShapes;

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

@@ -6,6 +6,16 @@ const libFableServiceProviderBase = require('fable-serviceproviderbase');
  * Shared geometry utilities for the flow diagram.
  * Provides direction vectors and edge center calculations used by
  * connections, tethers, and other flow components.
+ *
+ * Port Side values (12 positions):
+ *
+ *   Top edge:    'top-left'     'top'     'top-right'
+ *   Left edge:   'left-top'     'left'    'left-bottom'
+ *   Right edge:  'right-top'    'right'   'right-bottom'
+ *   Bottom edge: 'bottom-left'  'bottom'  'bottom-right'
+ *
+ * The old 4-value sides ('left', 'right', 'top', 'bottom') map to
+ * the middle position on each edge for backward compatibility.
  */
 class PictProviderFlowGeometry extends libFableServiceProviderBase
 {
@@ -16,15 +26,55 @@ class PictProviderFlowGeometry extends libFableServiceProviderBase
 		this.serviceType = 'PictProviderFlowGeometry';
 	}
 
+	/**
+	 * Extract the edge name from a Side value.
+	 *
+	 * Maps all 12 positions (and the 4 legacy values) back to
+	 * the edge they sit on: 'left', 'right', 'top', or 'bottom'.
+	 *
+	 * @param {string} pSide - Any valid Side value
+	 * @returns {string} The edge: 'left', 'right', 'top', or 'bottom'
+	 */
+	getEdgeFromSide(pSide)
+	{
+		switch (pSide)
+		{
+			case 'left-top':
+			case 'left':
+			case 'left-bottom':
+				return 'left';
+
+			case 'right-top':
+			case 'right':
+			case 'right-bottom':
+				return 'right';
+
+			case 'top-left':
+			case 'top':
+			case 'top-right':
+				return 'top';
+
+			case 'bottom-left':
+			case 'bottom':
+			case 'bottom-right':
+				return 'bottom';
+
+			default:
+				return 'right';
+		}
+	}
+
 	/**
 	 * Get the outward unit direction vector for a given side.
 	 *
-	 * @param {string} pSide - 'left', 'right', 'top', or 'bottom'
+	 * All positions on the same edge share the same direction vector.
+	 *
+	 * @param {string} pSide - Any valid Side value (12 positions or 4 legacy)
 	 * @returns {{dx: number, dy: number}}
 	 */
 	sideDirection(pSide)
 	{
-		switch (pSide)
+		switch (this.getEdgeFromSide(pSide))
 		{
 			case 'left':   return { dx: -1, dy: 0 };
 			case 'right':  return { dx: 1, dy: 0 };
@@ -59,6 +109,90 @@ class PictProviderFlowGeometry extends libFableServiceProviderBase
 				return { x: pRectData.X + pRectData.Width, y: pRectData.Y + pRectData.Height / 2 };
 		}
 	}
+
+	/**
+	 * Calculate a port's local position relative to node origin.
+	 *
+	 * Supports 12 positions (3 zones per edge).  For left/right edges,
+	 * the body area below the title bar is divided into three vertical zones
+	 * (start/middle/end).  For top/bottom edges, the full width is divided
+	 * into three horizontal zones.
+	 *
+	 * Multiple ports sharing the same Side value distribute evenly within
+	 * their zone.
+	 *
+	 * @param {string} pSide - Side value (any of 12 positions or 4 legacy)
+	 * @param {number} pIndex - Index of this port within its Side group
+	 * @param {number} pTotal - Total ports with this Side value
+	 * @param {number} pWidth - Node width
+	 * @param {number} pHeight - Node height
+	 * @param {number} pTitleBarHeight - Height of the node title bar
+	 * @returns {{x: number, y: number}}
+	 */
+	getPortLocalPosition(pSide, pIndex, pTotal, pWidth, pHeight, pTitleBarHeight)
+	{
+		let tmpEdge = this.getEdgeFromSide(pSide);
+		let tmpZone = this._getZoneFromSide(pSide);
+
+		if (tmpEdge === 'left' || tmpEdge === 'right')
+		{
+			let tmpX = (tmpEdge === 'left') ? 0 : pWidth;
+			let tmpBodyHeight = pHeight - pTitleBarHeight;
+			let tmpZoneStart = pTitleBarHeight + tmpBodyHeight * tmpZone.start;
+			let tmpZoneHeight = tmpBodyHeight * (tmpZone.end - tmpZone.start);
+			let tmpSpacing = tmpZoneHeight / (pTotal + 1);
+			let tmpY = tmpZoneStart + tmpSpacing * (pIndex + 1);
+			return { x: tmpX, y: tmpY };
+		}
+
+		// top or bottom
+		let tmpY = (tmpEdge === 'top') ? 0 : pHeight;
+		let tmpZoneStart = pWidth * tmpZone.start;
+		let tmpZoneWidth = pWidth * (tmpZone.end - tmpZone.start);
+		let tmpSpacing = tmpZoneWidth / (pTotal + 1);
+		let tmpX = tmpZoneStart + tmpSpacing * (pIndex + 1);
+		return { x: tmpX, y: tmpY };
+	}
+
+	/**
+	 * Get the zone fraction (start, end) for a Side value.
+	 *
+	 * Each edge is divided into three zones of equal size:
+	 *   start:  0.0 — 0.333
+	 *   middle: 0.333 — 0.667
+	 *   end:    0.667 — 1.0
+	 *
+	 * @param {string} pSide
+	 * @returns {{start: number, end: number}}
+	 */
+	_getZoneFromSide(pSide)
+	{
+		switch (pSide)
+		{
+			// Left edge: top, middle, bottom
+			case 'left-top':     return { start: 0.0,   end: 0.333 };
+			case 'left':         return { start: 0.333, end: 0.667 };
+			case 'left-bottom':  return { start: 0.667, end: 1.0 };
+
+			// Right edge: top, middle, bottom
+			case 'right-top':    return { start: 0.0,   end: 0.333 };
+			case 'right':        return { start: 0.333, end: 0.667 };
+			case 'right-bottom': return { start: 0.667, end: 1.0 };
+
+			// Top edge: left, middle, right
+			case 'top-left':     return { start: 0.0,   end: 0.333 };
+			case 'top':          return { start: 0.333, end: 0.667 };
+			case 'top-right':    return { start: 0.667, end: 1.0 };
+
+			// Bottom edge: left, middle, right
+			case 'bottom-left':  return { start: 0.0,   end: 0.333 };
+			case 'bottom':       return { start: 0.333, end: 0.667 };
+			case 'bottom-right': return { start: 0.667, end: 1.0 };
+
+			// Fallback: full range (legacy behavior)
+			default:             return { start: 0.0,   end: 1.0 };
+		}
+	}
 }
 
 module.exports = PictProviderFlowGeometry;