pict-section-flow 1.4.0 → 2.0.0

package/docs/api/PictFlowCardPropertiesPanel.md

@@ -1,235 +0,0 @@
-# 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

@@ -1,101 +0,0 @@
-# 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

@@ -1,137 +0,0 @@
-# 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

@@ -1,77 +0,0 @@
-# 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

@@ -1,112 +0,0 @@
-# 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