pict-section-flow 0.0.10 → 0.0.13

package/docs/api/saveLayout.md

@@ -0,0 +1,152 @@
+# saveLayout / restoreLayout / deleteLayout
+
+Save, restore, and manage spatial layout snapshots. Layouts capture node and panel positions plus viewport state, independent of the flow's logical content.
+
+## Signatures
+
+```javascript
+let tmpLayout = flowView._LayoutProvider.saveLayout(pName);
+flowView._LayoutProvider.restoreLayout(pLayoutHash);
+flowView._LayoutProvider.deleteLayout(pLayoutHash);
+flowView._LayoutProvider.getLayouts();
+flowView._LayoutProvider.loadPersistedLayouts();
+```
+
+## saveLayout
+
+Save the current spatial arrangement.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pName` | string | Yes | Display name for the layout |
+
+**Returns:** Layout data object.
+
+**Events Fired:** `onLayoutSaved`
+
+## restoreLayout
+
+Restore a previously saved layout.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pLayoutHash` | string | Yes | Hash of the layout to restore |
+
+**Returns:** `boolean`
+
+**Events Fired:** `onLayoutRestored`
+
+## deleteLayout
+
+Delete a saved layout.
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pLayoutHash` | string | Yes | Hash of the layout to delete |
+
+**Returns:** `boolean`
+
+**Events Fired:** `onLayoutDeleted`
+
+## getLayouts
+
+Returns an array of all saved layout objects.
+
+## loadPersistedLayouts
+
+Load layouts from the storage backend. Called automatically on initialization when using localStorage.
+
+## Examples
+
+### Save and list layouts
+
+```javascript
+// Save the current arrangement
+flowView._LayoutProvider.saveLayout('Default View');
+flowView._LayoutProvider.saveLayout('Zoomed In');
+
+// List all saved layouts
+let tmpLayouts = flowView._LayoutProvider.getLayouts();
+tmpLayouts.forEach((pLayout) =>
+{
+	console.log(pLayout.Name, pLayout.Hash, pLayout.CreatedAt);
+});
+```
+
+### Restore a layout
+
+```javascript
+let tmpLayouts = flowView._LayoutProvider.getLayouts();
+
+if (tmpLayouts.length > 0)
+{
+	flowView._LayoutProvider.restoreLayout(tmpLayouts[0].Hash);
+}
+```
+
+### Layout picker UI
+
+```javascript
+function renderLayoutPicker()
+{
+	let tmpLayouts = flowView._LayoutProvider.getLayouts();
+	let tmpContainer = document.getElementById('layout-picker');
+	tmpContainer.innerHTML = '';
+
+	tmpLayouts.forEach((pLayout) =>
+	{
+		let tmpButton = document.createElement('button');
+		tmpButton.textContent = pLayout.Name;
+		tmpButton.addEventListener('click', () =>
+		{
+			flowView._LayoutProvider.restoreLayout(pLayout.Hash);
+		});
+		tmpContainer.appendChild(tmpButton);
+	});
+}
+
+// Re-render picker when layouts change
+flowView._EventHandlerProvider.registerHandler('onLayoutSaved', renderLayoutPicker);
+flowView._EventHandlerProvider.registerHandler('onLayoutDeleted', renderLayoutPicker);
+```
+
+### Override storage for REST API
+
+```javascript
+let tmpLayoutProvider = flowView._LayoutProvider;
+
+tmpLayoutProvider.storageWrite = function(pLayouts, fCallback)
+{
+	fetch('/api/my-flow/layouts',
+		{
+			method: 'PUT',
+			headers: { 'Content-Type': 'application/json' },
+			body: JSON.stringify(pLayouts)
+		})
+		.then(() => fCallback(null))
+		.catch((pError) => fCallback(pError));
+};
+
+tmpLayoutProvider.storageRead = function(fCallback)
+{
+	fetch('/api/my-flow/layouts')
+		.then((pResponse) => pResponse.json())
+		.then((pLayouts) => fCallback(null, pLayouts))
+		.catch((pError) => fCallback(pError, []));
+};
+
+tmpLayoutProvider.storageDelete = function(fCallback)
+{
+	fetch('/api/my-flow/layouts', { method: 'DELETE' })
+		.then(() => fCallback(null))
+		.catch((pError) => fCallback(pError));
+};
+
+// Reload from the new backend
+tmpLayoutProvider.loadPersistedLayouts();
+```
+
+## See Also
+
+- [Layout Persistence](../Layout_Persistence.md) — Detailed guide on storage backends
+- [autoLayout](autoLayout.md) — Automatic topological layout

package/docs/api/screenToSVGCoords.md

@@ -0,0 +1,68 @@
+# screenToSVGCoords
+
+Convert screen pixel coordinates (e.g. from a mouse event) to the SVG coordinate space used internally by the flow diagram. Accounts for the current pan offset and zoom level.
+
+## Signature
+
+```javascript
+let tmpCoords = flowView.screenToSVGCoords(pScreenX, pScreenY);
+```
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pScreenX` | number | Yes | X coordinate in screen pixels |
+| `pScreenY` | number | Yes | Y coordinate in screen pixels |
+
+## Returns
+
+```javascript
+{ x: 142.5, y: 87.3 }
+```
+
+An object with `x` and `y` properties in SVG coordinate space.
+
+## Examples
+
+### Place a node at the click position
+
+```javascript
+document.getElementById('flow-container').addEventListener('click', (pEvent) =>
+{
+	let tmpSVG = flowView.screenToSVGCoords(pEvent.clientX, pEvent.clientY);
+	flowView.addNode('default', tmpSVG.x, tmpSVG.y, 'New Node');
+});
+```
+
+### Context menu at cursor position
+
+```javascript
+document.getElementById('flow-container').addEventListener('contextmenu', (pEvent) =>
+{
+	pEvent.preventDefault();
+	let tmpSVG = flowView.screenToSVGCoords(pEvent.clientX, pEvent.clientY);
+
+	showContextMenu(pEvent.clientX, pEvent.clientY,
+		{
+			svgX: tmpSVG.x,
+			svgY: tmpSVG.y
+		});
+});
+```
+
+### Debug coordinate output
+
+```javascript
+document.getElementById('flow-container').addEventListener('mousemove', (pEvent) =>
+{
+	let tmpSVG = flowView.screenToSVGCoords(pEvent.clientX, pEvent.clientY);
+	document.getElementById('coords').textContent =
+		'SVG: (' + Math.round(tmpSVG.x) + ', ' + Math.round(tmpSVG.y) + ')';
+});
+```
+
+## See Also
+
+- [setZoom](setZoom.md) — Viewport zoom (affects coordinate mapping)
+- [addNode](addNode.md) — Create nodes at specific coordinates

package/docs/api/selectNode.md

@@ -0,0 +1,116 @@
+# selectNode / selectConnection / selectTether / deselectAll / deleteSelected
+
+Manage the selection state of the flow canvas. At most one element (node, connection, or tether) can be selected at a time.
+
+## Signatures
+
+```javascript
+flowView.selectNode(pNodeHash);
+flowView.selectConnection(pConnectionHash);
+flowView.selectTether(pPanelHash);
+flowView.deselectAll();
+flowView.deleteSelected();
+```
+
+## selectNode
+
+Select a node by hash. Pass `null` to deselect.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pNodeHash` | string/null | Node hash, or `null` to deselect |
+
+**Events Fired:** `onNodeSelected`
+
+## selectConnection
+
+Select a connection by hash. Pass `null` to deselect.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pConnectionHash` | string/null | Connection hash, or `null` to deselect |
+
+**Events Fired:** `onConnectionSelected`
+
+## selectTether
+
+Select a tether line by its panel hash. Pass `null` to deselect.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pPanelHash` | string/null | Panel hash, or `null` to deselect |
+
+**Events Fired:** `onTetherSelected`
+
+## deselectAll
+
+Clear all selection state (node, connection, and tether).
+
+## deleteSelected
+
+Delete the currently selected node or connection. If a node is selected, its connections are also removed.
+
+**Returns:** `boolean` — `true` if something was deleted.
+
+## Examples
+
+### Programmatic selection
+
+```javascript
+let tmpNode = flowView.addNode('default', 100, 100, 'My Node');
+
+// Select the node
+flowView.selectNode(tmpNode.Hash);
+
+// Check selection state
+let tmpFlowData = flowView.getFlowData();
+console.log(tmpFlowData.ViewState.SelectedNodeHash); // 'node-...'
+
+// Clear selection
+flowView.deselectAll();
+```
+
+### Selection event handler
+
+```javascript
+flowView._EventHandlerProvider.registerHandler('onNodeSelected',
+	(pNode) =>
+	{
+		if (pNode)
+		{
+			document.getElementById('details-panel').innerHTML =
+				'Selected: ' + pNode.Title + ' (' + pNode.Type + ')';
+		}
+		else
+		{
+			document.getElementById('details-panel').innerHTML = 'Nothing selected';
+		}
+	});
+```
+
+### Delete with confirmation
+
+```javascript
+function handleDelete()
+{
+	let tmpFlowData = flowView.getFlowData();
+
+	if (tmpFlowData.ViewState.SelectedNodeHash)
+	{
+		let tmpNode = flowView.getNode(tmpFlowData.ViewState.SelectedNodeHash);
+		if (confirm('Delete node "' + tmpNode.Title + '"?'))
+		{
+			flowView.deleteSelected();
+		}
+	}
+	else if (tmpFlowData.ViewState.SelectedConnectionHash)
+	{
+		flowView.deleteSelected();
+	}
+}
+```
+
+## See Also
+
+- [addNode](addNode.md) / [removeNode](removeNode.md) — Node CRUD
+- [registerHandler](registerHandler.md) — Event hooks

package/docs/api/setTheme.md

@@ -0,0 +1,168 @@
+# setTheme / registerTheme
+
+Manage the visual theme of the flow diagram. Six built-in themes are available, and you can register custom themes with CSS variable overrides.
+
+## Signatures
+
+```javascript
+flowView.setTheme(pThemeKey);
+flowView._ThemeProvider.registerTheme(pThemeKey, pThemeConfig);
+flowView.setNoiseLevel(pLevel);
+flowView.getNoiseLevel();
+flowView.getThemeKey();
+```
+
+## setTheme
+
+Switch to a registered theme and re-render.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pThemeKey` | string | Theme identifier |
+
+**Events Fired:** `onThemeChanged`
+
+### Built-in Theme Keys
+
+| Key | Style |
+|-----|-------|
+| `default` | Clean, modern, professional |
+| `sketch` | Hand-drawn, informal |
+| `blueprint` | Technical blueprint |
+| `mono` | Monochrome |
+| `retro-80s` | Neon retro |
+| `retro-90s` | Vaporwave |
+
+## registerTheme
+
+Register a custom theme.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pThemeKey` | string | Unique theme identifier |
+| `pThemeConfig` | object | Theme configuration |
+
+### Theme Configuration Shape
+
+```javascript
+{
+	Key: 'dark',
+	Label: 'Dark Mode',
+	CSSVariables:
+	{
+		'--pf-canvas-bg': '#1a1a2e',
+		'--pf-node-body-fill': '#16213e',
+		'--pf-node-body-stroke': '#0f3460',
+		'--pf-text-primary': '#e8e8e8',
+		'--pf-node-selected-stroke': '#e94560'
+	},
+	AdditionalCSS: '/* Extra CSS rules */',
+	NodeBodyMode: 'rect',
+	NoiseConfig:
+	{
+		Enabled: true,
+		Amount: 0.5
+	},
+	ConnectionConfig:
+	{
+		StrokeDashArray: '5,5'
+	}
+}
+```
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `Key` | string | Unique identifier |
+| `Label` | string | Display name |
+| `CSSVariables` | object | Map of `--pf-*` variable names to values |
+| `AdditionalCSS` | string | Extra CSS appended after variable overrides |
+| `NodeBodyMode` | string | Node rendering mode: `'rect'` or `'bracket'` |
+| `NoiseConfig` | object | Hand-drawn effect: `{ Enabled, Amount }` |
+| `ConnectionConfig` | object | Connection styling: `{ StrokeDashArray }` |
+
+## setNoiseLevel / getNoiseLevel
+
+Control the hand-drawn rendering effect independently of the theme.
+
+```javascript
+flowView.setNoiseLevel(0.5);  // Moderate wobble
+flowView.setNoiseLevel(0);    // Precise, clean lines
+flowView.setNoiseLevel(1);    // Maximum hand-drawn effect
+
+let tmpLevel = flowView.getNoiseLevel(); // 0.5
+```
+
+## getThemeKey
+
+Returns the active theme key string.
+
+```javascript
+let tmpKey = flowView.getThemeKey(); // 'default'
+```
+
+## Examples
+
+### Switch to a built-in theme
+
+```javascript
+flowView.setTheme('blueprint');
+```
+
+### Register and apply a custom dark theme
+
+```javascript
+flowView._ThemeProvider.registerTheme('dark',
+	{
+		Key: 'dark',
+		Label: 'Dark Mode',
+		CSSVariables:
+		{
+			'--pf-canvas-bg': '#1a1a2e',
+			'--pf-node-body-fill': '#16213e',
+			'--pf-node-body-stroke': '#0f3460',
+			'--pf-text-primary': '#e8e8e8',
+			'--pf-node-selected-stroke': '#e94560',
+			'--pf-connection-stroke': '#4a6fa5',
+			'--pf-toolbar-bg': '#162447',
+			'--pf-panel-bg': '#1a1a2e',
+			'--pf-panel-titlebar-bg': '#162447'
+		},
+		NodeBodyMode: 'rect'
+	});
+
+flowView.setTheme('dark');
+```
+
+### Theme selector dropdown
+
+```javascript
+document.getElementById('theme-select').addEventListener('change', (pEvent) =>
+{
+	flowView.setTheme(pEvent.target.value);
+});
+```
+
+### Corporate branding theme
+
+```javascript
+flowView._ThemeProvider.registerTheme('corporate',
+	{
+		Key: 'corporate',
+		Label: 'Corporate',
+		CSSVariables:
+		{
+			'--pf-canvas-bg': '#f5f6fa',
+			'--pf-node-selected-stroke': '#0066cc',
+			'--pf-node-body-stroke': '#c8d6e5',
+			'--pf-node-title-bar-color': '#003366',
+			'--pf-toolbar-bg': '#ffffff',
+			'--pf-panel-titlebar-bg': '#f0f2f5'
+		},
+		NoiseConfig: { Enabled: false }
+	});
+```
+
+## See Also
+
+- [Custom Styling](../Custom-Styling.md) — Full CSS custom properties reference
+- [registerHandler](registerHandler.md) — Listen for `onThemeChanged` events

package/docs/api/setZoom.md

@@ -0,0 +1,97 @@
+# setZoom / zoomToFit
+
+Control the viewport zoom level. `setZoom` sets an explicit zoom value with an optional focus point. `zoomToFit` automatically adjusts pan and zoom to frame all nodes in the viewport.
+
+## Signatures
+
+```javascript
+flowView.setZoom(pZoom, pFocusX, pFocusY);
+flowView.zoomToFit();
+```
+
+## setZoom
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `pZoom` | number | Yes | Target zoom level (clamped to `MinZoom`..`MaxZoom`) |
+| `pFocusX` | number | No | X coordinate in SVG space to zoom toward |
+| `pFocusY` | number | No | Y coordinate in SVG space to zoom toward |
+
+## zoomToFit
+
+No parameters. Calculates the bounding box of all nodes and adjusts pan/zoom to fit them in the visible viewport with padding.
+
+## Examples
+
+### Set a specific zoom level
+
+```javascript
+// Zoom to 150%
+flowView.setZoom(1.5);
+
+// Zoom to 50% focused on a specific point
+flowView.setZoom(0.5, 300, 200);
+```
+
+### Zoom to fit after loading data
+
+```javascript
+flowView.setFlowData(savedFlowData);
+flowView.zoomToFit();
+```
+
+### Zoom controls
+
+```javascript
+document.getElementById('zoom-in').addEventListener('click', () =>
+{
+	let tmpCurrent = flowView.getFlowData().ViewState.Zoom;
+	flowView.setZoom(tmpCurrent + 0.1);
+});
+
+document.getElementById('zoom-out').addEventListener('click', () =>
+{
+	let tmpCurrent = flowView.getFlowData().ViewState.Zoom;
+	flowView.setZoom(tmpCurrent - 0.1);
+});
+
+document.getElementById('zoom-fit').addEventListener('click', () =>
+{
+	flowView.zoomToFit();
+});
+```
+
+### Zoom to a specific node
+
+```javascript
+function zoomToNode(pFlowView, pNodeHash, pZoomLevel)
+{
+	let tmpNode = pFlowView.getNode(pNodeHash);
+	if (tmpNode)
+	{
+		let tmpCenterX = tmpNode.X + (tmpNode.Width / 2);
+		let tmpCenterY = tmpNode.Y + (tmpNode.Height / 2);
+		pFlowView.setZoom(pZoomLevel || 1.5, tmpCenterX, tmpCenterY);
+	}
+}
+
+zoomToNode(flowView, myNode.Hash, 2.0);
+```
+
+## Configuration
+
+Zoom bounds are set in the view configuration:
+
+```javascript
+{
+	MinZoom: 0.1,
+	MaxZoom: 5.0,
+	ZoomStep: 0.1
+}
+```
+
+## See Also
+
+- [screenToSVGCoords](screenToSVGCoords.md) — Coordinate conversion
+- [toggleFullscreen](toggleFullscreen.md) — Fullscreen mode
+- [autoLayout](autoLayout.md) — Automatic node arrangement

package/docs/api/toggleFullscreen.md

@@ -0,0 +1,68 @@
+# toggleFullscreen / exitFullscreen
+
+Toggle the flow diagram into a fullscreen overlay that covers the entire browser viewport. Useful for maximizing workspace on complex flows.
+
+## Signatures
+
+```javascript
+flowView.toggleFullscreen();
+flowView.exitFullscreen();
+```
+
+## toggleFullscreen
+
+Toggles between normal and fullscreen modes.
+
+**Returns:** `boolean` — the new fullscreen state (`true` if now fullscreen).
+
+## exitFullscreen
+
+Explicitly exits fullscreen mode if active.
+
+## Examples
+
+### Toggle button
+
+```javascript
+document.getElementById('fullscreen-btn').addEventListener('click', () =>
+{
+	let tmpIsFullscreen = flowView.toggleFullscreen();
+
+	if (tmpIsFullscreen)
+	{
+		document.getElementById('fullscreen-btn').textContent = 'Exit Fullscreen';
+	}
+	else
+	{
+		document.getElementById('fullscreen-btn').textContent = 'Fullscreen';
+	}
+});
+```
+
+### Escape key to exit
+
+```javascript
+document.addEventListener('keydown', (pEvent) =>
+{
+	if (pEvent.key === 'Escape')
+	{
+		flowView.exitFullscreen();
+	}
+});
+```
+
+### Fullscreen with zoom-to-fit
+
+```javascript
+flowView.toggleFullscreen();
+
+// Wait for the CSS transition, then fit content
+setTimeout(() =>
+{
+	flowView.zoomToFit();
+}, 300);
+```
+
+## See Also
+
+- [setZoom / zoomToFit](setZoom.md) — Viewport controls

package/docs/card-help/EACH.md

@@ -0,0 +1,19 @@
+# Each (Loop Iterator)
+
+The **Each** node iterates over a collection, executing connected downstream nodes once for each item. When iteration completes, the **Done** output fires.
+
+## Ports
+
+- **Collection** (input) — an array or iterable to loop over
+- **Item** (output) — fires once per element with the current item
+- **Done** (output) — fires after all items have been processed
+
+## Behavior
+
+When a collection arrives at the input port, the Each node processes items sequentially. For every element in the collection, the **Item** output is activated with the current element as the payload. After the final element is processed, the **Done** output fires to signal completion.
+
+## Tips
+
+- Connect **Item** to a processing chain and **Done** to continuation logic
+- Nested loops are supported by chaining multiple Each nodes
+- Empty collections skip directly to the **Done** output

package/docs/card-help/FREAD.md

@@ -0,0 +1,24 @@
+# File Read
+
+The **File Read** node reads the contents of a file from the filesystem and outputs the data.
+
+## Ports
+
+- **Path** (input) — the filesystem path to read
+- **Data** (output) — the file contents on success
+- **Error** (output) — fires if the read operation fails
+
+## Properties
+
+- **FilePath** — the path to the file to read
+- **Encoding** — character encoding for text files (e.g. `utf8`, `ascii`)
+
+## Behavior
+
+When triggered, the node reads the file at the configured path. On success, the raw file contents are emitted from the **Data** output. If the file does not exist or cannot be read, the **Error** output fires with a descriptive error message.
+
+## Tips
+
+- Use a Get Value node upstream to dynamically set the file path
+- Pair with a Data Preview node to inspect the file contents
+- Connect the **Error** output to logging or notification nodes for robust error handling