pict-section-flow 0.0.10 → 0.0.13

package/docs/api/PictFlowCardPropertiesPanel.md

@@ -0,0 +1,235 @@
+# PictFlowCardPropertiesPanel
+
+Base class for flow card property panels. Extend this class to create custom panel types beyond the four built-in types (Template, Markdown, Form, View).
+
+## Import
+
+```javascript
+const libPictFlowCardPropertiesPanel = require('pict-section-flow').PictFlowCardPropertiesPanel;
+```
+
+## Constructor
+
+```javascript
+class MyPanel extends libPictFlowCardPropertiesPanel
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, Object.assign({},
+			{
+				PanelType: 'Custom',
+				Title: 'My Panel',
+				Width: 300,
+				Height: 200,
+				Configuration: {}
+			}, pOptions), pServiceHash);
+	}
+}
+```
+
+## Configuration Options
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `PanelType` | string | `'Base'` | Panel type identifier |
+| `Title` | string | `'Properties'` | Panel title bar text |
+| `Width` | number | `300` | Default width in pixels |
+| `Height` | number | `200` | Default height in pixels |
+| `Configuration` | object | `{}` | Panel-type-specific config |
+
+## Methods to Override
+
+### render(pContainer, pNodeData)
+
+Render the panel's content into a DOM container element. Subclasses **must** override this.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pContainer` | HTMLElement | The DOM element to render into |
+| `pNodeData` | object | The node data object (has `.Data` property) |
+
+### marshalToPanel(pNodeData)
+
+Marshal data from the node's Data object into the panel UI. Called when the panel opens or when data changes externally.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pNodeData` | object | The node data object |
+
+### marshalFromPanel(pNodeData)
+
+Marshal data from the panel UI into the node's Data object. Called before saving or when the panel is about to close.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pNodeData` | object | The node data object to update |
+
+### destroy()
+
+Called when the panel is being closed. Clean up resources, event listeners, etc.
+
+## Internal Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `this._FlowView` | PictViewFlow | Reference to the flow view (set when panel is activated) |
+| `this._NodeData` | object | The node data this panel is operating on |
+| `this._ContentContainer` | HTMLElement | The DOM container element |
+| `this._Configuration` | object | Panel-type-specific configuration |
+
+## Built-in Panel Types
+
+### Template
+
+Renders Pict templates inside the panel.
+
+```javascript
+{
+	PanelType: 'Template',
+	Configuration:
+	{
+		Templates:
+		[
+			{
+				Hash: 'my-template',
+				Template: '<div class="info">{~D:Record.Data.Label~}</div>'
+			}
+		],
+		TemplateHash: 'my-template'
+	}
+}
+```
+
+### Markdown
+
+Renders markdown content via `pict-section-content`.
+
+```javascript
+{
+	PanelType: 'Markdown',
+	Configuration:
+	{
+		Markdown: '## Help\nThis node reads a file from disk.\n\n**Inputs:** File path\n**Outputs:** File contents or error'
+	}
+}
+```
+
+### Form
+
+Creates an ephemeral `pict-section-form` section.
+
+```javascript
+{
+	PanelType: 'Form',
+	Configuration:
+	{
+		Fields:
+		[
+			{ Name: 'FilePath', DataType: 'String' },
+			{ Name: 'Encoding', DataType: 'String' },
+			{ Name: 'MaxSize', DataType: 'Number' }
+		]
+	}
+}
+```
+
+### View
+
+Renders an existing registered Pict view inside the panel.
+
+```javascript
+{
+	PanelType: 'View',
+	Configuration:
+	{
+		ViewHash: 'my-custom-view'
+	}
+}
+```
+
+## Examples
+
+### Custom chart panel
+
+```javascript
+class ChartPanel extends libPictFlowCardPropertiesPanel
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, Object.assign({},
+			{
+				PanelType: 'Chart',
+				Title: 'Data Preview',
+				Width: 400,
+				Height: 300
+			}, pOptions), pServiceHash);
+
+		this._ChartInstance = null;
+	}
+
+	render(pContainer, pNodeData)
+	{
+		super.render(pContainer, pNodeData);
+
+		let tmpCanvas = document.createElement('canvas');
+		tmpCanvas.width = 380;
+		tmpCanvas.height = 260;
+		pContainer.appendChild(tmpCanvas);
+
+		// Create chart from node data
+		this._ChartInstance = new Chart(tmpCanvas,
+			{
+				type: 'line',
+				data: pNodeData.Data.ChartData || { labels: [], datasets: [] }
+			});
+	}
+
+	marshalToPanel(pNodeData)
+	{
+		super.marshalToPanel(pNodeData);
+		if (this._ChartInstance && pNodeData.Data.ChartData)
+		{
+			this._ChartInstance.data = pNodeData.Data.ChartData;
+			this._ChartInstance.update();
+		}
+	}
+
+	destroy()
+	{
+		if (this._ChartInstance)
+		{
+			this._ChartInstance.destroy();
+			this._ChartInstance = null;
+		}
+		super.destroy();
+	}
+}
+```
+
+### Using a custom panel in a card
+
+```javascript
+class DataPreviewCard extends libPictFlowCard
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, Object.assign({},
+			{
+				Title: 'Data Preview',
+				Code: 'DPRV',
+				PropertiesPanel:
+				{
+					PanelType: 'Chart',
+					Title: 'Preview',
+					DefaultWidth: 400,
+					DefaultHeight: 300
+				}
+			}, pOptions), pServiceHash);
+	}
+}
+```
+
+## See Also
+
+- [PictFlowCard](PictFlowCard.md) — Define cards that use panels
+- [openPanel / closePanel](openPanel.md) — Panel lifecycle methods

package/docs/api/addConnection.md

@@ -0,0 +1,101 @@
+# addConnection
+
+Connect two ports on the flow canvas. Creates a visual line between the source port (typically an output) and the target port (typically an input). The connection is validated before creation.
+
+## Signature
+
+```javascript
+flowView.addConnection(pSourceNode, pSourcePort, pTargetNode, pTargetPort, pData)
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pSourceNode` | string | Yes | Hash of the source node |
+| `pSourcePort` | string | Yes | Hash of the source port |
+| `pTargetNode` | string | Yes | Hash of the target node |
+| `pTargetPort` | string | Yes | Hash of the target port |
+| `pData` | object | No | Optional connection metadata |
+
+### Connection Data Options
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `LineMode` | string | `'bezier'` | Path style: `'bezier'` or `'orthogonal'` |
+
+## Returns
+
+The connection object on success, or `false` if validation failed (e.g. duplicate connection, self-connection, or port not found).
+
+```javascript
+{
+	Hash: 'conn-x1y2z3',
+	SourceNodeHash: 'node-a1b2',
+	SourcePortHash: 'port-c3d4',
+	TargetNodeHash: 'node-e5f6',
+	TargetPortHash: 'port-g7h8',
+	Data:
+	{
+		LineMode: 'bezier',
+		HandleCustomized: false
+	}
+}
+```
+
+## Events Fired
+
+- `onConnectionCreated` — with the new connection object
+- `onFlowChanged` — with the complete flow data
+
+## Examples
+
+### Basic connection
+
+```javascript
+let tmpStart = flowView.addNode('start', 50, 150, 'Begin');
+let tmpEnd = flowView.addNode('end', 400, 150, 'Done');
+
+let tmpOutPort = tmpStart.Ports.find((pPort) => pPort.Direction === 'output');
+let tmpInPort = tmpEnd.Ports.find((pPort) => pPort.Direction === 'input');
+
+let tmpConn = flowView.addConnection(
+	tmpStart.Hash, tmpOutPort.Hash,
+	tmpEnd.Hash, tmpInPort.Hash
+);
+
+console.log(tmpConn.Hash); // 'conn-...'
+```
+
+### Orthogonal connection
+
+```javascript
+let tmpConn = flowView.addConnection(
+	tmpA.Hash, tmpOutPort.Hash,
+	tmpB.Hash, tmpInPort.Hash,
+	{ LineMode: 'orthogonal' }
+);
+```
+
+### Decision node branching
+
+```javascript
+let tmpDecision = flowView.addNode('decision', 200, 150, 'Check Status');
+let tmpSuccess = flowView.addNode('default', 400, 50, 'Handle Success');
+let tmpFailure = flowView.addNode('halt', 400, 250, 'Handle Error');
+
+// Find the Yes and No output ports on the decision node
+let tmpYesPort = tmpDecision.Ports.find((pPort) => pPort.Label === 'Yes');
+let tmpNoPort = tmpDecision.Ports.find((pPort) => pPort.Label === 'No');
+
+let tmpSuccessIn = tmpSuccess.Ports.find((pPort) => pPort.Direction === 'input');
+let tmpFailureIn = tmpFailure.Ports.find((pPort) => pPort.Direction === 'input');
+
+flowView.addConnection(tmpDecision.Hash, tmpYesPort.Hash, tmpSuccess.Hash, tmpSuccessIn.Hash);
+flowView.addConnection(tmpDecision.Hash, tmpNoPort.Hash, tmpFailure.Hash, tmpFailureIn.Hash);
+```
+
+## See Also
+
+- [removeConnection](removeConnection.md) — Delete a connection
+- [addNode](addNode.md) — Create nodes to connect

package/docs/api/addNode.md

@@ -0,0 +1,137 @@
+# addNode
+
+Create a new node on the flow canvas. The node is added to the flow data, assigned a UUID hash, populated with default ports from the node type definition, and the canvas is re-rendered.
+
+## Signature
+
+```javascript
+flowView.addNode(pType, pX, pY, pTitle, pData)
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pType` | string | Yes | Node type key. Built-in types: `'start'`, `'end'`, `'halt'`, `'decision'`, `'default'`. Custom types use the `Code` from a registered `PictFlowCard`. |
+| `pX` | number | Yes | X coordinate in SVG space |
+| `pY` | number | Yes | Y coordinate in SVG space |
+| `pTitle` | string | Yes | Display title shown on the node's title bar |
+| `pData` | object | No | Optional custom data object attached to the node's `Data` property |
+
+## Returns
+
+The newly created node object:
+
+```javascript
+{
+	Hash: 'node-a1b2c3d4',
+	Type: 'start',
+	X: 50,
+	Y: 150,
+	Width: 140,
+	Height: 80,
+	Title: 'Begin',
+	Ports:
+	[
+		{
+			Hash: 'port-e5f6g7h8',
+			Direction: 'output',
+			Side: 'right',
+			Label: 'Out'
+		}
+	],
+	Data: {}
+}
+```
+
+## Events Fired
+
+- `onNodeAdded` — with the new node object
+- `onFlowChanged` — with the complete flow data
+
+## Examples
+
+### Basic usage
+
+```javascript
+// Add a start node at position (50, 150)
+let tmpStart = flowView.addNode('start', 50, 150, 'Begin');
+
+// Add a processing node
+let tmpProcess = flowView.addNode('default', 250, 150, 'Transform Data');
+
+// Add an end node
+let tmpEnd = flowView.addNode('end', 450, 150, 'Done');
+```
+
+### With custom data
+
+```javascript
+let tmpFileRead = flowView.addNode('FREAD', 100, 200, 'Read Config',
+	{
+		FilePath: '/etc/app/config.json',
+		Encoding: 'utf-8'
+	});
+
+console.log(tmpFileRead.Data.FilePath); // '/etc/app/config.json'
+```
+
+### Adding a decision node
+
+```javascript
+let tmpDecision = flowView.addNode('decision', 300, 200, 'Is Valid?');
+
+// The decision node has three ports by default: In, Yes, No
+console.log(tmpDecision.Ports.length); // 3
+```
+
+### Programmatic flow construction
+
+```javascript
+function buildPipeline(pFlowView, pSteps)
+{
+	let tmpPreviousNode = null;
+
+	for (let i = 0; i < pSteps.length; i++)
+	{
+		let tmpNode = pFlowView.addNode(
+			pSteps[i].Type,
+			100 + (i * 200),
+			150,
+			pSteps[i].Title,
+			pSteps[i].Data
+		);
+
+		if (tmpPreviousNode)
+		{
+			let tmpOutPort = tmpPreviousNode.Ports.find((pPort) => pPort.Direction === 'output');
+			let tmpInPort = tmpNode.Ports.find((pPort) => pPort.Direction === 'input');
+
+			if (tmpOutPort && tmpInPort)
+			{
+				pFlowView.addConnection(
+					tmpPreviousNode.Hash, tmpOutPort.Hash,
+					tmpNode.Hash, tmpInPort.Hash
+				);
+			}
+		}
+
+		tmpPreviousNode = tmpNode;
+	}
+}
+
+buildPipeline(flowView,
+	[
+		{ Type: 'start', Title: 'Begin' },
+		{ Type: 'FREAD', Title: 'Load Data', Data: { FilePath: '/data/input.csv' } },
+		{ Type: 'default', Title: 'Process' },
+		{ Type: 'end', Title: 'Complete' }
+	]);
+```
+
+## See Also
+
+- [removeNode](removeNode.md) — Delete a node
+- [getFlowData](getFlowData.md) — Retrieve the full flow state
+- [PictFlowCard](PictFlowCard.md) — Define custom node types
+- [registerNodeType](registerNodeType.md) — Register node types directly

package/docs/api/autoLayout.md

@@ -0,0 +1,77 @@
+# autoLayout
+
+Automatically arrange all nodes in the flow using a topological sort algorithm. Nodes are positioned in columns based on their dependency order, with even vertical spacing within each column. This is useful for organizing complex flows or providing a clean starting arrangement.
+
+## Signature
+
+```javascript
+flowView.autoLayout();
+```
+
+## Parameters
+
+None.
+
+## Behavior
+
+1. Performs a topological sort of the node graph based on connections
+2. Assigns nodes to columns (layers) based on their depth from root nodes
+3. Distributes nodes evenly within each column
+4. Re-renders the entire canvas
+5. Optionally snaps to grid if `EnableGridSnap` is `true`
+
+Nodes with no connections are placed in a separate area to the side.
+
+## Examples
+
+### Basic usage
+
+```javascript
+// After constructing a complex flow programmatically
+flowView.autoLayout();
+flowView.zoomToFit();
+```
+
+### Auto-layout after data load
+
+```javascript
+fetch('/api/flows/my-flow')
+	.then((pResponse) => pResponse.json())
+	.then((pFlowData) =>
+	{
+		flowView.setFlowData(pFlowData);
+		flowView.autoLayout();
+		flowView.zoomToFit();
+	});
+```
+
+### Layout button
+
+```javascript
+document.getElementById('auto-layout-btn').addEventListener('click', () =>
+{
+	flowView.autoLayout();
+	flowView.zoomToFit();
+});
+```
+
+## Grid Snap
+
+When `EnableGridSnap` is `true`, the auto-layout algorithm snaps node positions to the nearest grid point based on `GridSnapSize`:
+
+```javascript
+_Pict.addView('MyFlow',
+	{
+		EnableGridSnap: true,
+		GridSnapSize: 20
+	},
+	libPictSectionFlow);
+
+// Auto-layout will snap to 20px grid
+flowView.autoLayout();
+```
+
+## See Also
+
+- [setZoom / zoomToFit](setZoom.md) — Fit the result in the viewport
+- [saveLayout / restoreLayout](saveLayout.md) — Persist spatial arrangements

package/docs/api/getFlowData.md

@@ -0,0 +1,112 @@
+# getFlowData / setFlowData
+
+Get or replace the entire flow state. `getFlowData` returns a deep clone so mutations do not affect the live state. `setFlowData` replaces the flow data and triggers a full re-render.
+
+## Signatures
+
+```javascript
+let tmpFlowData = flowView.getFlowData();
+flowView.setFlowData(pFlowData);
+```
+
+## getFlowData
+
+### Parameters
+
+None.
+
+### Returns
+
+A deep clone of the complete flow state:
+
+```javascript
+{
+	Nodes: [ /* ... */ ],
+	Connections: [ /* ... */ ],
+	OpenPanels: [ /* ... */ ],
+	SavedLayouts: [ /* ... */ ],
+	ViewState:
+	{
+		PanX: 0,
+		PanY: 0,
+		Zoom: 1,
+		SelectedNodeHash: null,
+		SelectedConnectionHash: null,
+		SelectedTetherHash: null
+	}
+}
+```
+
+## setFlowData
+
+### Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pFlowData` | object | Yes | Complete flow data structure |
+
+### Events Fired
+
+- `onFlowChanged` — with the new flow data
+
+## Examples
+
+### Save flow state to a server
+
+```javascript
+let tmpFlowData = flowView.getFlowData();
+
+fetch('/api/flows/my-flow',
+	{
+		method: 'PUT',
+		headers: { 'Content-Type': 'application/json' },
+		body: JSON.stringify(tmpFlowData)
+	});
+```
+
+### Load flow state from a server
+
+```javascript
+fetch('/api/flows/my-flow')
+	.then((pResponse) => pResponse.json())
+	.then((pFlowData) =>
+	{
+		flowView.setFlowData(pFlowData);
+	});
+```
+
+### Clone a flow
+
+```javascript
+let tmpOriginal = flowView.getFlowData();
+
+// Modify the clone without affecting the original
+tmpOriginal.Nodes.forEach((pNode) =>
+{
+	pNode.X += 200;
+});
+
+flowView.setFlowData(tmpOriginal);
+```
+
+### Inspect flow statistics
+
+```javascript
+let tmpData = flowView.getFlowData();
+
+console.log('Nodes:', tmpData.Nodes.length);
+console.log('Connections:', tmpData.Connections.length);
+console.log('Open Panels:', tmpData.OpenPanels.length);
+console.log('Saved Layouts:', tmpData.SavedLayouts.length);
+console.log('Zoom:', tmpData.ViewState.Zoom);
+```
+
+## Related Methods
+
+- `getNode(pNodeHash)` — Retrieve a single node by hash
+- `getConnection(pConnectionHash)` — Retrieve a single connection by hash
+
+## See Also
+
+- [marshalToView / marshalFromView](marshalToView.md) — AppData two-way binding
+- [addNode](addNode.md) — Add individual nodes