pict-section-flow 1.3.0 → 2.0.0

package/docs/Event_System.md

@@ -1,156 +0,0 @@
-# Event System
-
-Pict-Section-Flow exposes a rich event system through the `EventHandlerProvider`. Register handlers to react to user interactions, data changes, and lifecycle events without modifying core code.
-
-## Registering Handlers
-
-```javascript
-let tmpFlowView = _Pict.views.MyFlow;
-
-// Register a named handler
-tmpFlowView._EventHandlerProvider.registerHandler(
-    'onNodeAdded',
-    (pNode, pFlowView) =>
-    {
-        console.log('Node added:', pNode.Title);
-    },
-    'my-node-handler'
-);
-```
-
-The third parameter is an optional handler hash for later removal. If omitted, a unique hash is generated and returned.
-
-## Removing Handlers
-
-```javascript
-// Remove a specific handler
-tmpFlowView._EventHandlerProvider.removeHandler('onNodeAdded', 'my-node-handler');
-
-// Remove all handlers for an event
-tmpFlowView._EventHandlerProvider.removeAllHandlers('onNodeAdded');
-
-// Remove all handlers for all events
-tmpFlowView._EventHandlerProvider.removeAllHandlers();
-```
-
-## Querying Handlers
-
-```javascript
-// Check if any handlers are registered
-tmpFlowView._EventHandlerProvider.hasHandlers('onNodeAdded');  // true or false
-
-// Count registered handlers
-tmpFlowView._EventHandlerProvider.getHandlerCount('onNodeAdded');  // number
-```
-
-## Available Events
-
-### Node Events
-
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `onNodeSelected` | `node` or `null` | A node was selected or deselected |
-| `onNodeAdded` | `node` | A new node was created |
-| `onNodeRemoved` | `node` | A node was deleted |
-| `onNodeMoved` | `node` | A node was dragged to a new position |
-
-### Connection Events
-
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `onConnectionSelected` | `connection` | A connection was selected |
-| `onConnectionCreated` | `connection` | A new connection was created between ports |
-| `onConnectionRemoved` | `connection` | A connection was deleted |
-| `onConnectionHandleMoved` | `connection` | A bezier or orthogonal handle was dragged |
-| `onConnectionModeChanged` | `connection` | A connection toggled between bezier and orthogonal |
-
-### Panel Events
-
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `onPanelOpened` | `panelData` | A properties panel was opened |
-| `onPanelClosed` | `panelData` | A properties panel was closed |
-| `onPanelMoved` | `panelData` | A properties panel was dragged |
-
-### Tether Events
-
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `onTetherSelected` | `panelData` | A tether line was selected |
-| `onTetherHandleMoved` | `panelData` | A tether handle was dragged |
-| `onTetherModeChanged` | `panelData` | A tether toggled between bezier and orthogonal |
-
-### Layout and Meta Events
-
-| Event | Payload | Description |
-|-------|---------|-------------|
-| `onLayoutSaved` | `layoutData` | A layout snapshot was saved |
-| `onLayoutRestored` | `layoutData` | A saved layout was restored |
-| `onLayoutDeleted` | `layoutData` | A saved layout was deleted |
-| `onFlowChanged` | `flowData` | Catch-all fired after any data mutation |
-| `onThemeChanged` | `themeKey` | The active theme was switched |
-
-## Common Patterns
-
-### Undo/Redo Stack
-
-```javascript
-let tmpUndoStack = [];
-let tmpRedoStack = [];
-
-tmpFlowView._EventHandlerProvider.registerHandler(
-    'onFlowChanged',
-    (pFlowData) =>
-    {
-        tmpUndoStack.push(JSON.parse(JSON.stringify(pFlowData)));
-        tmpRedoStack = [];
-    },
-    'undo-tracker'
-);
-
-function undo()
-{
-    if (tmpUndoStack.length < 2) return;
-    tmpRedoStack.push(tmpUndoStack.pop());
-    tmpFlowView.setFlowData(tmpUndoStack[tmpUndoStack.length - 1]);
-}
-```
-
-### Server Sync
-
-```javascript
-tmpFlowView._EventHandlerProvider.registerHandler(
-    'onFlowChanged',
-    (pFlowData) =>
-    {
-        fetch('/api/flows/save',
-        {
-            method: 'POST',
-            headers: { 'Content-Type': 'application/json' },
-            body: JSON.stringify(pFlowData)
-        });
-    },
-    'server-sync'
-);
-```
-
-### Selection Sidebar
-
-```javascript
-tmpFlowView._EventHandlerProvider.registerHandler(
-    'onNodeSelected',
-    (pNode) =>
-    {
-        if (pNode)
-        {
-            document.getElementById('sidebar-title').textContent = pNode.Title;
-            document.getElementById('sidebar-type').textContent = pNode.Type;
-        }
-        else
-        {
-            document.getElementById('sidebar-title').textContent = 'No selection';
-        }
-    },
-    'sidebar-updater'
-);
-```

package/docs/Getting_Started.md

@@ -1,237 +0,0 @@
-# Getting Started
-
-This guide walks you through creating a flow diagram from scratch -- installing the package, registering a view, adding nodes and connections, and wiring up custom card types.
-
-## Prerequisites
-
-- Node.js 16+
-- A Pict application (or willingness to create one)
-
-## Installation
-
-```bash
-npm install pict-section-flow
-```
-
-If you are building for the browser, also install the build tool:
-
-```bash
-npm install --save-dev quackage
-```
-
-## Step 1: Create a Pict Application
-
-If you do not already have a Pict application, create a minimal one:
-
-```javascript
-const libPict = require('pict');
-
-let _Pict = new libPict(
-	{
-		Product: 'FlowDemo',
-		ProductVersion: '1.0.0'
-	});
-```
-
-## Step 2: Register the Flow View
-
-Pict-Section-Flow exports a View class. Register it with your Pict instance:
-
-```javascript
-const libPictSectionFlow = require('pict-section-flow');
-
-_Pict.addView('MyFlowDiagram',
-	{
-		DefaultDestinationAddress: '#flow-container',
-		EnableToolbar: true,
-		EnableGridSnap: true,
-		GridSnapSize: 20
-	},
-	libPictSectionFlow);
-```
-
-Your HTML needs a target element:
-
-```html
-<div id="flow-container"></div>
-```
-
-## Step 3: Initialize and Render
-
-```javascript
-// Initialize the application (triggers view initialization)
-_Pict.initialize();
-
-// The flow view is now accessible
-let tmpFlowView = _Pict.views.MyFlowDiagram;
-```
-
-## Step 4: Add Nodes
-
-Use the `addNode` method to place nodes on the canvas:
-
-```javascript
-// addNode(pType, pX, pY, pTitle, pData)
-let tmpStart = tmpFlowView.addNode('start', 50, 150, 'Begin');
-let tmpProcess = tmpFlowView.addNode('default', 250, 150, 'Process Data');
-let tmpEnd = tmpFlowView.addNode('end', 450, 150, 'Done');
-```
-
-Five built-in node types are available out of the box:
-
-| Type | Ports | Color | Use Case |
-|------|-------|-------|----------|
-| `default` | In, Out | Gray | Generic operation |
-| `start` | Out | Green | Flow entry point |
-| `end` | In | Teal | Flow exit point |
-| `halt` | In | Red | Error termination |
-| `decision` | In, Yes, No | Orange | Conditional branch |
-
-## Step 5: Connect Nodes
-
-Link two ports by providing node and port hashes:
-
-```javascript
-// Get the output port of the start node
-let tmpSourcePort = tmpStart.Ports.find((pPort) => pPort.Direction === 'output');
-// Get the input port of the process node
-let tmpTargetPort = tmpProcess.Ports.find((pPort) => pPort.Direction === 'input');
-
-tmpFlowView.addConnection(
-	tmpStart.Hash, tmpSourcePort.Hash,
-	tmpProcess.Hash, tmpTargetPort.Hash
-);
-```
-
-## Step 6: Define a Custom Card Type
-
-For domain-specific node types, extend `PictFlowCard`:
-
-```javascript
-const libPictFlowCard = require('pict-section-flow').PictFlowCard;
-
-class FileReadCard extends libPictFlowCard
-{
-	constructor(pFable, pOptions, pServiceHash)
-	{
-		super(pFable, Object.assign({},
-			{
-				Title: 'File Read',
-				Code: 'FREAD',
-				Category: 'File I/O',
-				Description: 'Read contents from a file path',
-				TitleBarColor: '#2980b9',
-				Width: 160,
-				Height: 70,
-				Inputs:
-				[
-					{ Name: 'Path', Side: 'left', PortType: 'value' }
-				],
-				Outputs:
-				[
-					{ Name: 'Data', Side: 'right', PortType: 'value' },
-					{ Name: 'Error', Side: 'bottom', PortType: 'error' }
-				],
-				PropertiesPanel:
-				{
-					PanelType: 'Form',
-					Title: 'File Read Settings',
-					DefaultWidth: 300,
-					DefaultHeight: 180,
-					Configuration:
-					{
-						Fields:
-						[
-							{ Name: 'FilePath', DataType: 'String' },
-							{ Name: 'Encoding', DataType: 'String' }
-						]
-					}
-				}
-			}, pOptions), pServiceHash);
-	}
-}
-```
-
-Register it with the flow view:
-
-```javascript
-let tmpCard = new FileReadCard(_Pict, {});
-tmpCard.registerWithFlowView(tmpFlowView);
-```
-
-The card now appears in the toolbar palette under the "File I/O" category.
-
-## Step 7: Listen for Events
-
-Hook into the event system to react to user actions:
-
-```javascript
-tmpFlowView._EventHandlerProvider.registerHandler('onNodeSelected',
-	(pNode) =>
-	{
-		console.log('Selected node:', pNode.Title, pNode.Hash);
-	});
-
-tmpFlowView._EventHandlerProvider.registerHandler('onFlowChanged',
-	(pFlowData) =>
-	{
-		// Persist flow state to your backend
-		fetch('/api/flows/my-flow',
-			{
-				method: 'PUT',
-				headers: { 'Content-Type': 'application/json' },
-				body: JSON.stringify(pFlowData)
-			});
-	});
-```
-
-## Step 8: Switch Themes
-
-Apply a built-in theme or register a custom one:
-
-```javascript
-// Use a built-in theme
-tmpFlowView.setTheme('blueprint');
-
-// Or register your own
-tmpFlowView._ThemeProvider.registerTheme('dark',
-	{
-		Key: 'dark',
-		Label: 'Dark Mode',
-		CSSVariables:
-		{
-			'--pf-canvas-bg': '#1a1a2e',
-			'--pf-node-body-fill': '#16213e',
-			'--pf-text-primary': '#e8e8e8',
-			'--pf-node-selected-stroke': '#e94560'
-		}
-	});
-tmpFlowView.setTheme('dark');
-```
-
-## Step 9: Build for the Browser
-
-Add a build script to your `package.json`:
-
-```json
-{
-	"scripts": {
-		"build": "npx quack build"
-	}
-}
-```
-
-Then build:
-
-```bash
-npm run build
-```
-
-This produces a browser bundle in `dist/` that includes pict-section-flow and all its dependencies.
-
-## Next Steps
-
-- **[Architecture](Architecture.md)** -- Understand the service/provider design
-- **[Implementation Reference](Implementation_Reference.md)** -- Full API for every method
-- **[Custom Styling](Custom-Styling.md)** -- CSS variables and theme configuration
-- **[Layout Persistence](Layout_Persistence.md)** -- Save layouts to localStorage or a REST API