pict-section-flow 0.0.10 → 0.0.13

package/docs/api/marshalToView.md

@@ -0,0 +1,95 @@
+# marshalToView / marshalFromView
+
+Two-way data binding between the flow view and Pict's `AppData` store. Requires the `FlowDataAddress` configuration option to be set.
+
+## Signatures
+
+```javascript
+flowView.marshalToView();
+flowView.marshalFromView();
+```
+
+## marshalToView
+
+Load flow data from the AppData address specified in `FlowDataAddress` into the view and render it.
+
+This is the "pull" direction: AppData → Flow View.
+
+## marshalFromView
+
+Write the current flow data back to the AppData address specified in `FlowDataAddress`.
+
+This is the "push" direction: Flow View → AppData.
+
+## Configuration
+
+Set `FlowDataAddress` when registering the view:
+
+```javascript
+_Pict.addView('MyFlow',
+	{
+		FlowDataAddress: 'AppData.Workflows.MainFlow'
+	},
+	libPictSectionFlow);
+```
+
+## Examples
+
+### Load from AppData on initialization
+
+```javascript
+// Set up initial data in AppData
+_Pict.AppData.Workflows =
+{
+	MainFlow:
+	{
+		Nodes:
+		[
+			{
+				Hash: 'node-1',
+				Type: 'start',
+				X: 50, Y: 100,
+				Width: 140, Height: 80,
+				Title: 'Entry',
+				Ports:
+				[
+					{ Hash: 'port-1', Direction: 'output', Side: 'right', Label: 'Out' }
+				],
+				Data: {}
+			}
+		],
+		Connections: [],
+		OpenPanels: [],
+		SavedLayouts: [],
+		ViewState: { PanX: 0, PanY: 0, Zoom: 1 }
+	}
+};
+
+// The flow view pulls this data on render
+let tmpFlowView = _Pict.views.MyFlow;
+tmpFlowView.marshalToView();
+```
+
+### Push changes back to AppData
+
+```javascript
+// After the user edits the flow, persist to AppData
+tmpFlowView.marshalFromView();
+
+// Now AppData.Workflows.MainFlow reflects the current flow state
+console.log(_Pict.AppData.Workflows.MainFlow.Nodes.length);
+```
+
+### Auto-sync on flow changes
+
+```javascript
+tmpFlowView._EventHandlerProvider.registerHandler('onFlowChanged',
+	() =>
+	{
+		tmpFlowView.marshalFromView();
+	});
+```
+
+## See Also
+
+- [getFlowData / setFlowData](getFlowData.md) — Direct get/set without AppData

package/docs/api/openPanel.md

@@ -0,0 +1,128 @@
+# openPanel / closePanel / closePanelForNode / togglePanel / updatePanelPosition
+
+Manage the lifecycle and positioning of properties panels. Panels are floating UI elements tethered to nodes by a line. They display when a node is double-clicked or opened programmatically.
+
+## Signatures
+
+```javascript
+flowView.openPanel(pNodeHash);
+flowView.closePanel(pPanelHash);
+flowView.closePanelForNode(pNodeHash);
+flowView.togglePanel(pNodeHash);
+flowView.updatePanelPosition(pPanelHash, pX, pY);
+```
+
+## openPanel
+
+Open a properties panel for a node. The panel type and configuration come from the node type's `PropertiesPanel` definition.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pNodeHash` | string | Hash of the node to open a panel for |
+
+**Returns:** Panel data object, or `false` if the node type has no panel configuration.
+
+**Events Fired:** `onPanelOpened`
+
+## closePanel
+
+Close a panel by its hash.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pPanelHash` | string | Hash of the panel to close |
+
+**Returns:** `boolean`
+
+**Events Fired:** `onPanelClosed`
+
+## closePanelForNode
+
+Close all panels associated with a node.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pNodeHash` | string | Hash of the node whose panels to close |
+
+**Returns:** `boolean`
+
+## togglePanel
+
+Toggle a node's panel. Opens it if closed, closes it if open.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pNodeHash` | string | Hash of the node |
+
+**Returns:** Panel data object if opened, `false` if closed.
+
+## updatePanelPosition
+
+Move a panel to new coordinates.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pPanelHash` | string | Hash of the panel |
+| `pX` | number | New X coordinate |
+| `pY` | number | New Y coordinate |
+
+**Events Fired:** `onPanelMoved`
+
+## Examples
+
+### Open a panel programmatically
+
+```javascript
+let tmpNode = flowView.addNode('FREAD', 200, 150, 'Read Config');
+let tmpPanel = flowView.openPanel(tmpNode.Hash);
+
+if (tmpPanel)
+{
+	console.log('Panel opened:', tmpPanel.Hash);
+	console.log('Panel type:', tmpPanel.PanelType);
+}
+```
+
+### Toggle on button click
+
+```javascript
+document.getElementById('toggle-props').addEventListener('click', () =>
+{
+	let tmpFlowData = flowView.getFlowData();
+	if (tmpFlowData.ViewState.SelectedNodeHash)
+	{
+		flowView.togglePanel(tmpFlowData.ViewState.SelectedNodeHash);
+	}
+});
+```
+
+### Close all open panels
+
+```javascript
+let tmpFlowData = flowView.getFlowData();
+tmpFlowData.OpenPanels.forEach((pPanel) =>
+{
+	flowView.closePanel(pPanel.Hash);
+});
+```
+
+### Listen for panel events
+
+```javascript
+flowView._EventHandlerProvider.registerHandler('onPanelOpened',
+	(pPanelData) =>
+	{
+		console.log('Panel opened for node:', pPanelData.NodeHash);
+	});
+
+flowView._EventHandlerProvider.registerHandler('onPanelClosed',
+	(pPanelData) =>
+	{
+		console.log('Panel closed:', pPanelData.Hash);
+	});
+```
+
+## See Also
+
+- [PictFlowCard](PictFlowCard.md) — Define PropertiesPanel configuration on card types
+- [PictFlowCardPropertiesPanel](PictFlowCardPropertiesPanel.md) — Custom panel base class

package/docs/api/registerHandler.md

@@ -0,0 +1,174 @@
+# registerHandler / removeHandler / fireEvent
+
+The event system for hooking into flow diagram lifecycle events. Register callbacks to react to user actions, data changes, and state transitions without modifying core code.
+
+## Signatures
+
+```javascript
+let tmpHash = flowView._EventHandlerProvider.registerHandler(pEventName, pHandler, pHandlerHash);
+flowView._EventHandlerProvider.removeHandler(pEventName, pHandlerHash);
+flowView._EventHandlerProvider.fireEvent(pEventName, pData);
+```
+
+## registerHandler
+
+Register a callback for a named event.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pEventName` | string | Yes | Event name from the supported events list |
+| `pHandler` | function | Yes | Callback function receiving event data |
+| `pHandlerHash` | string | No | Optional unique ID for later removal |
+
+**Returns:** Handler hash (string). Auto-generated if not provided.
+
+## removeHandler
+
+Unregister a previously registered handler.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pEventName` | string | Yes | Event name |
+| `pHandlerHash` | string | Yes | Hash returned from `registerHandler` |
+
+**Returns:** `boolean`
+
+## fireEvent
+
+Manually fire all handlers for a named event. Typically used internally by services, but available for custom events.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pEventName` | string | Yes | Event name |
+| `pData` | any | No | Data passed to each handler |
+
+## Supported Events
+
+| Event | Payload | Description |
+|-------|---------|-------------|
+| `onNodeSelected` | Node object or null | A node is selected or deselected |
+| `onNodeAdded` | Node object | A node is created |
+| `onNodeRemoved` | Node object | A node is deleted |
+| `onNodeMoved` | Node object | A node's position changes |
+| `onConnectionSelected` | Connection object or null | A connection is selected |
+| `onConnectionCreated` | Connection object | A connection is created |
+| `onConnectionRemoved` | Connection object | A connection is deleted |
+| `onConnectionHandleMoved` | Connection object | A bezier handle is dragged |
+| `onConnectionModeChanged` | Connection object | Line mode switches |
+| `onPanelOpened` | Panel data | A properties panel opens |
+| `onPanelClosed` | Panel data | A properties panel closes |
+| `onPanelMoved` | Panel data | A panel is repositioned |
+| `onTetherSelected` | Panel data | A tether line is selected |
+| `onTetherHandleMoved` | Panel data | A tether handle is dragged |
+| `onTetherModeChanged` | Panel data | Tether mode switches |
+| `onLayoutSaved` | Layout data | A layout is saved |
+| `onLayoutRestored` | Layout data | A layout is restored |
+| `onLayoutDeleted` | Layout data | A layout is deleted |
+| `onFlowChanged` | Flow data | Any structural change |
+| `onThemeChanged` | Theme key (string) | The active theme changes |
+
+## Examples
+
+### Track all changes for undo/redo
+
+```javascript
+let tmpHistory = [];
+let tmpHistoryIndex = -1;
+
+flowView._EventHandlerProvider.registerHandler('onFlowChanged',
+	(pFlowData) =>
+	{
+		// Trim future states if we've undone
+		tmpHistory = tmpHistory.slice(0, tmpHistoryIndex + 1);
+		tmpHistory.push(JSON.parse(JSON.stringify(pFlowData)));
+		tmpHistoryIndex = tmpHistory.length - 1;
+	},
+	'undo-redo-tracker');
+
+function undo()
+{
+	if (tmpHistoryIndex > 0)
+	{
+		tmpHistoryIndex--;
+		flowView.setFlowData(tmpHistory[tmpHistoryIndex]);
+	}
+}
+
+function redo()
+{
+	if (tmpHistoryIndex < tmpHistory.length - 1)
+	{
+		tmpHistoryIndex++;
+		flowView.setFlowData(tmpHistory[tmpHistoryIndex]);
+	}
+}
+```
+
+### Sync to server on every change
+
+```javascript
+flowView._EventHandlerProvider.registerHandler('onFlowChanged',
+	(pFlowData) =>
+	{
+		fetch('/api/flows/my-flow',
+			{
+				method: 'PUT',
+				headers: { 'Content-Type': 'application/json' },
+				body: JSON.stringify(pFlowData)
+			});
+	},
+	'server-sync');
+```
+
+### Update a sidebar when selection changes
+
+```javascript
+flowView._EventHandlerProvider.registerHandler('onNodeSelected',
+	(pNode) =>
+	{
+		let tmpSidebar = document.getElementById('sidebar');
+
+		if (!pNode)
+		{
+			tmpSidebar.innerHTML = '<p>Select a node to view details</p>';
+			return;
+		}
+
+		tmpSidebar.innerHTML =
+			'<h3>' + pNode.Title + '</h3>' +
+			'<p>Type: ' + pNode.Type + '</p>' +
+			'<p>Ports: ' + pNode.Ports.length + '</p>';
+	});
+```
+
+### Remove a handler
+
+```javascript
+let tmpHandlerHash = flowView._EventHandlerProvider.registerHandler('onNodeAdded',
+	(pNode) =>
+	{
+		console.log('Node added:', pNode.Title);
+	});
+
+// Later, unregister it
+flowView._EventHandlerProvider.removeHandler('onNodeAdded', tmpHandlerHash);
+```
+
+### Multiple handlers for the same event
+
+```javascript
+// Both handlers fire when a node is added
+flowView._EventHandlerProvider.registerHandler('onNodeAdded',
+	(pNode) => { console.log('Handler 1:', pNode.Title); },
+	'logger');
+
+flowView._EventHandlerProvider.registerHandler('onNodeAdded',
+	(pNode) => { updateNodeCount(); },
+	'counter');
+```
+
+## See Also
+
+- [addNode](addNode.md) — Triggers `onNodeAdded` and `onFlowChanged`
+- [selectNode](selectNode.md) — Triggers `onNodeSelected`
+- [setTheme](setTheme.md) — Triggers `onThemeChanged`

package/docs/api/registerNodeType.md

@@ -0,0 +1,142 @@
+# registerNodeType / removeNodeType / getNodeType
+
+Register, remove, and query node types in the flow diagram's type registry. Most developers will use `PictFlowCard.registerWithFlowView()` instead, but these methods provide direct access for dynamic or programmatic type management.
+
+## Signatures
+
+```javascript
+flowView._NodeTypeProvider.registerNodeType(pNodeTypeConfig);
+flowView._NodeTypeProvider.removeNodeType(pTypeHash);
+flowView._NodeTypeProvider.getNodeType(pTypeHash);
+flowView._NodeTypeProvider.getNodeTypes();
+flowView._NodeTypeProvider.getNodeTypeList();
+flowView._NodeTypeProvider.getEnabledCards();
+flowView._NodeTypeProvider.getCardsByCategory();
+```
+
+## registerNodeType
+
+Register a node type configuration directly.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pNodeTypeConfig` | object | Node type configuration |
+
+**Returns:** `boolean`
+
+### Configuration Shape
+
+```javascript
+{
+	Hash: 'FREAD',
+	Label: 'File Read',
+	DefaultWidth: 160,
+	DefaultHeight: 70,
+	TitleBarColor: '#2980b9',
+	DefaultPorts:
+	[
+		{ Hash: null, Direction: 'input', Side: 'left', Label: 'Path', PortType: 'value' },
+		{ Hash: null, Direction: 'output', Side: 'right', Label: 'Data', PortType: 'value' },
+		{ Hash: null, Direction: 'output', Side: 'bottom', Label: 'Error', PortType: 'error' }
+	],
+	CardMetadata:
+	{
+		Name: 'File Read',
+		Code: 'FREAD',
+		Description: 'Read contents from a file path',
+		Category: 'File I/O',
+		Enabled: true
+	}
+}
+```
+
+## removeNodeType
+
+Unregister a node type by hash.
+
+**Returns:** `boolean`
+
+## getNodeType
+
+Retrieve a node type configuration by hash. Returns the default type if the hash is not found.
+
+**Returns:** Node type configuration object.
+
+## getNodeTypes
+
+**Returns:** Map of all registered node types (hash → config).
+
+## getNodeTypeList
+
+**Returns:** Array of registered type hash strings.
+
+## getEnabledCards
+
+**Returns:** Array of card configurations where `CardMetadata.Enabled` is `true`.
+
+## getCardsByCategory
+
+**Returns:** Object mapping category names to arrays of card configurations. Useful for building palette UIs.
+
+## Examples
+
+### Register a type directly
+
+```javascript
+flowView._NodeTypeProvider.registerNodeType(
+	{
+		Hash: 'FILTER',
+		Label: 'Filter',
+		DefaultWidth: 140,
+		DefaultHeight: 60,
+		TitleBarColor: '#9b59b6',
+		DefaultPorts:
+		[
+			{ Hash: null, Direction: 'input', Side: 'left', Label: 'In' },
+			{ Hash: null, Direction: 'output', Side: 'right', Label: 'Pass' },
+			{ Hash: null, Direction: 'output', Side: 'bottom', Label: 'Reject' }
+		],
+		CardMetadata:
+		{
+			Code: 'FILTER',
+			Category: 'Data',
+			Enabled: true
+		}
+	});
+```
+
+### List all categories
+
+```javascript
+let tmpCategories = flowView._NodeTypeProvider.getCardsByCategory();
+
+Object.keys(tmpCategories).forEach((pCategory) =>
+{
+	console.log(pCategory + ':');
+	tmpCategories[pCategory].forEach((pCard) =>
+	{
+		console.log('  -', pCard.Label, '(' + pCard.Hash + ')');
+	});
+});
+```
+
+### Check if a type exists
+
+```javascript
+let tmpType = flowView._NodeTypeProvider.getNodeType('FREAD');
+if (tmpType.Hash === 'FREAD')
+{
+	console.log('File Read type is registered');
+}
+```
+
+### Remove a type at runtime
+
+```javascript
+flowView._NodeTypeProvider.removeNodeType('FREAD');
+```
+
+## See Also
+
+- [PictFlowCard](PictFlowCard.md) — Higher-level card class (recommended approach)
+- [addNode](addNode.md) — Create nodes from registered types

package/docs/api/removeConnection.md

@@ -0,0 +1,57 @@
+# removeConnection
+
+Delete a connection from the flow canvas.
+
+## Signature
+
+```javascript
+flowView.removeConnection(pConnectionHash)
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pConnectionHash` | string | Yes | Hash of the connection to remove |
+
+## Returns
+
+`boolean` — `true` if the connection was found and removed, `false` otherwise.
+
+## Events Fired
+
+- `onConnectionRemoved` — with the removed connection object
+- `onFlowChanged` — with the updated flow data
+
+## Examples
+
+### Basic removal
+
+```javascript
+let tmpConn = flowView.addConnection(
+	tmpA.Hash, tmpOutPort.Hash,
+	tmpB.Hash, tmpInPort.Hash
+);
+
+flowView.removeConnection(tmpConn.Hash);
+```
+
+### Remove all connections for a specific node
+
+```javascript
+let tmpFlowData = flowView.getFlowData();
+let tmpTargetHash = myNode.Hash;
+
+tmpFlowData.Connections.forEach((pConn) =>
+{
+	if (pConn.SourceNodeHash === tmpTargetHash || pConn.TargetNodeHash === tmpTargetHash)
+	{
+		flowView.removeConnection(pConn.Hash);
+	}
+});
+```
+
+## See Also
+
+- [addConnection](addConnection.md) — Create a connection
+- [removeNode](removeNode.md) — Remove a node (cascades connections)

package/docs/api/removeNode.md

@@ -0,0 +1,80 @@
+# removeNode
+
+Delete a node from the flow canvas. All connections attached to the node are also removed. Any open properties panel for the node is closed. The canvas is re-rendered.
+
+## Signature
+
+```javascript
+flowView.removeNode(pNodeHash)
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pNodeHash` | string | Yes | Hash of the node to remove |
+
+## Returns
+
+`boolean` — `true` if the node was found and removed, `false` otherwise.
+
+## Events Fired
+
+- `onNodeRemoved` — with the removed node object
+- `onConnectionRemoved` — for each connection that was cascaded
+- `onFlowChanged` — with the updated flow data
+
+## Examples
+
+### Basic removal
+
+```javascript
+let tmpNode = flowView.addNode('default', 100, 100, 'Temporary');
+
+// Later, remove it
+let tmpRemoved = flowView.removeNode(tmpNode.Hash);
+console.log(tmpRemoved); // true
+```
+
+### Remove with cascading connections
+
+```javascript
+let tmpA = flowView.addNode('start', 50, 100, 'A');
+let tmpB = flowView.addNode('default', 250, 100, 'B');
+let tmpC = flowView.addNode('end', 450, 100, 'C');
+
+// Connect A -> B -> C
+flowView.addConnection(tmpA.Hash, tmpA.Ports[0].Hash, tmpB.Hash, tmpB.Ports[0].Hash);
+flowView.addConnection(tmpB.Hash, tmpB.Ports[1].Hash, tmpC.Hash, tmpC.Ports[0].Hash);
+
+// Removing B also removes both connections
+flowView.removeNode(tmpB.Hash);
+
+let tmpFlowData = flowView.getFlowData();
+console.log(tmpFlowData.Connections.length); // 0
+```
+
+### Conditional removal with event tracking
+
+```javascript
+flowView._EventHandlerProvider.registerHandler('onNodeRemoved',
+	(pNode) =>
+	{
+		console.log('Removed:', pNode.Title);
+	});
+
+// Only remove nodes of a certain type
+let tmpFlowData = flowView.getFlowData();
+tmpFlowData.Nodes.forEach((pNode) =>
+{
+	if (pNode.Type === 'default')
+	{
+		flowView.removeNode(pNode.Hash);
+	}
+});
+```
+
+## See Also
+
+- [addNode](addNode.md) — Create a node
+- [deleteSelected](selectNode.md) — Delete the currently selected element