pict-section-flow 1.3.0 → 2.0.0

package/docs/Implementation_Reference.md

@@ -1,528 +0,0 @@
-# Implementation Reference
-
-Complete API reference for Pict-Section-Flow. This document covers every public method on the main `PictViewFlow` class and the key internal services and providers developers interact with.
-
-## PictViewFlow -- Main View API
-
-The primary class exported by `pict-section-flow`. Extends `pict-view`.
-
-### Configuration
-
-```javascript
-const libPictSectionFlow = require('pict-section-flow');
-
-_Pict.addView('MyFlow',
-	{
-		ViewIdentifier: 'Pict-Flow',
-		DefaultDestinationAddress: '#flow-container',
-		FlowDataAddress: 'AppData.MyFlow',
-
-		EnableToolbar: true,
-		EnablePanning: true,
-		EnableZooming: true,
-		EnableNodeDragging: true,
-		EnableConnectionCreation: true,
-		EnableGridSnap: false,
-		GridSnapSize: 20,
-
-		MinZoom: 0.1,
-		MaxZoom: 5.0,
-		ZoomStep: 0.1,
-
-		DefaultNodeType: 'default',
-		DefaultNodeWidth: 180,
-		DefaultNodeHeight: 80,
-
-		Theme: 'default'
-	},
-	libPictSectionFlow);
-```
-
-| Option | Type | Default | Description |
-|--------|------|---------|-------------|
-| `ViewIdentifier` | string | `'Pict-Flow'` | Unique identifier for debugging and DOM IDs |
-| `DefaultDestinationAddress` | string | `'#Flow-Container'` | CSS selector for the container element |
-| `FlowDataAddress` | string/false | `false` | AppData path for two-way binding |
-| `EnableToolbar` | boolean | `true` | Show the toolbar UI |
-| `EnablePanning` | boolean | `true` | Allow canvas panning |
-| `EnableZooming` | boolean | `true` | Allow canvas zooming |
-| `EnableNodeDragging` | boolean | `true` | Allow node repositioning |
-| `EnableConnectionCreation` | boolean | `true` | Allow creating port-to-port connections |
-| `EnableGridSnap` | boolean | `false` | Snap node positions to grid |
-| `GridSnapSize` | number | `20` | Grid cell size in pixels |
-| `MinZoom` | number | `0.1` | Minimum zoom level |
-| `MaxZoom` | number | `5.0` | Maximum zoom level |
-| `ZoomStep` | number | `0.1` | Zoom increment per scroll tick |
-| `DefaultNodeType` | string | `'default'` | Node type when none specified |
-| `DefaultNodeWidth` | number | `180` | Default node width in pixels |
-| `DefaultNodeHeight` | number | `80` | Default node height in pixels |
-| `Theme` | string | `'default'` | Active theme key |
-
----
-
-## Data Management Methods
-
-### addNode(pType, pX, pY, pTitle, pData)
-
-Create a new node on the canvas.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `pType` | string | Node type key (e.g. `'start'`, `'default'`, or a custom card code) |
-| `pX` | number | X coordinate in SVG space |
-| `pY` | number | Y coordinate in SVG space |
-| `pTitle` | string | Display title |
-| `pData` | object | Optional custom data attached to the node |
-
-**Returns:** Node object with `Hash`, `Ports`, `Type`, etc.
-
-### removeNode(pNodeHash)
-
-Delete a node and all its connections.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `pNodeHash` | string | Hash of the node to remove |
-
-**Returns:** `boolean` -- `true` if the node was found and removed.
-
-### addConnection(pSourceNode, pSourcePort, pTargetNode, pTargetPort, pData)
-
-Connect two ports.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `pSourceNode` | string | Source node hash |
-| `pSourcePort` | string | Source port hash |
-| `pTargetNode` | string | Target node hash |
-| `pTargetPort` | string | Target port hash |
-| `pData` | object | Optional connection data (e.g. `{ LineMode: 'orthogonal' }`) |
-
-**Returns:** Connection object, or `false` if validation failed.
-
-### removeConnection(pConnectionHash)
-
-Delete a connection.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `pConnectionHash` | string | Hash of the connection to remove |
-
-**Returns:** `boolean` -- `true` if the connection was found and removed.
-
-### getFlowData()
-
-Get a deep clone of the complete flow state.
-
-**Returns:** `{ Nodes, Connections, OpenPanels, SavedLayouts, ViewState }`
-
-### setFlowData(pFlowData)
-
-Replace the entire flow state and re-render.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `pFlowData` | object | Complete flow data structure |
-
-### getNode(pNodeHash)
-
-Retrieve a node object by hash.
-
-**Returns:** Node object or `undefined`.
-
-### getConnection(pConnectionHash)
-
-Retrieve a connection object by hash.
-
-**Returns:** Connection object or `undefined`.
-
-### marshalToView()
-
-Load flow data from the AppData address specified in `FlowDataAddress` and render.
-
-### marshalFromView()
-
-Write the current flow data back to the AppData address specified in `FlowDataAddress`.
-
----
-
-## Selection Methods
-
-### selectNode(pNodeHash)
-
-Select a node. Pass `null` to deselect.
-
-### selectConnection(pConnectionHash)
-
-Select a connection. Pass `null` to deselect.
-
-### selectTether(pPanelHash)
-
-Select a tether line. Pass `null` to deselect.
-
-### deselectAll()
-
-Clear all selections (node, connection, and tether).
-
-### deleteSelected()
-
-Delete the currently selected node or connection.
-
-**Returns:** `boolean` -- `true` if something was deleted.
-
----
-
-## Viewport Methods
-
-### setZoom(pZoom, pFocusX, pFocusY)
-
-Set the zoom level with an optional focus point.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `pZoom` | number | Target zoom level (clamped to MinZoom..MaxZoom) |
-| `pFocusX` | number | Optional X focus point in SVG space |
-| `pFocusY` | number | Optional Y focus point in SVG space |
-
-### zoomToFit()
-
-Automatically adjust pan and zoom to fit all nodes in the viewport.
-
-### updateViewportTransform()
-
-Apply the current pan/zoom state to the SVG viewport group. Called automatically after pan/zoom changes.
-
-### toggleFullscreen()
-
-Toggle fullscreen overlay mode.
-
-**Returns:** `boolean` -- the new fullscreen state.
-
-### exitFullscreen()
-
-Exit fullscreen mode.
-
-### screenToSVGCoords(pScreenX, pScreenY)
-
-Convert screen pixel coordinates to SVG coordinate space.
-
-**Returns:** `{ x, y }`
-
-### autoLayout()
-
-Run the topological auto-layout algorithm to arrange nodes automatically.
-
----
-
-## Panel Methods
-
-### openPanel(pNodeHash)
-
-Open a properties panel for a node.
-
-**Returns:** Panel data object, or `false` if the node has no panel configuration.
-
-### closePanel(pPanelHash)
-
-Close a panel by its hash.
-
-**Returns:** `boolean`
-
-### closePanelForNode(pNodeHash)
-
-Close all panels associated with a node.
-
-**Returns:** `boolean`
-
-### togglePanel(pNodeHash)
-
-Toggle a node's panel open or closed.
-
-**Returns:** Panel data object or `false`.
-
-### updatePanelPosition(pPanelHash, pX, pY)
-
-Move a panel to new coordinates.
-
----
-
-## Theming Methods
-
-### setTheme(pThemeKey)
-
-Switch to a registered theme and re-render.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `pThemeKey` | string | Theme key (e.g. `'default'`, `'sketch'`, `'blueprint'`) |
-
-### setNoiseLevel(pLevel)
-
-Set the hand-drawn noise level.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `pLevel` | number | 0 (precise) to 1 (wobbly) |
-
-### getNoiseLevel()
-
-**Returns:** Current noise level (number).
-
-### getThemeKey()
-
-**Returns:** Active theme key (string).
-
----
-
-## Rendering Methods
-
-### renderFlow()
-
-Full re-render of all nodes, connections, panels, and tethers.
-
-### updateNodePosition(pNodeHash, pX, pY)
-
-Update a node's position during drag. Performs selective re-rendering of only the affected elements for smooth performance.
-
-### getPortPosition(pNodeHash, pPortHash)
-
-Get the absolute SVG coordinates of a port's center.
-
-**Returns:** `{ x, y }`
-
----
-
-## Connection Handle Methods
-
-### updateConnectionHandle(pConnectionHash, pHandleType, pX, pY)
-
-Update a bezier control point on a connection.
-
-### addConnectionHandle(pConnectionHash, pX, pY)
-
-Add a new control point to a connection.
-
-### removeConnectionHandle(pConnectionHash, pIndex)
-
-Remove a control point from a connection.
-
-### updateTetherHandle(pPanelHash, pHandleType, pX, pY)
-
-Update a bezier control point on a tether line.
-
----
-
-## Internal Service Accessors
-
-Developers access services and providers through underscore-prefixed properties on the flow view instance:
-
-| Property | Service/Provider |
-|----------|-----------------|
-| `_DataManager` | Node and connection CRUD |
-| `_RenderManager` | Rendering orchestration |
-| `_SelectionManager` | Selection state |
-| `_ViewportManager` | Pan, zoom, fullscreen |
-| `_PanelManager` | Panel lifecycle |
-| `_InteractionManager` | Event handling |
-| `_LayoutService` | Grid snap, auto-layout |
-| `_ConnectionRenderer` | Bezier/orthogonal drawing |
-| `_NodeTypeProvider` | Node type registry |
-| `_EventHandlerProvider` | Custom event hooks |
-| `_LayoutProvider` | Layout persistence |
-| `_ThemeProvider` | Theme system |
-| `_CSSProvider` | CSS generation and injection |
-| `_GeometryProvider` | Port positioning math |
-| `_NoiseProvider` | Hand-drawn effects |
-| `_SVGHelperProvider` | SVG DOM utilities |
-| `_ConnectorShapesProvider` | Arrowhead marker definitions |
-| `_IconProvider` | Icon templates |
-| `_PanelChromeProvider` | Panel UI template |
-
----
-
-## EventHandler Provider API
-
-### registerHandler(pEventName, pHandler, pHandlerHash)
-
-Register a callback for a named event.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `pEventName` | string | Event name (see list below) |
-| `pHandler` | function | Callback function |
-| `pHandlerHash` | string | Optional unique identifier for removal |
-
-**Returns:** Handler hash (string).
-
-### removeHandler(pEventName, pHandlerHash)
-
-Remove a previously registered handler.
-
-**Returns:** `boolean`
-
-### fireEvent(pEventName, pData)
-
-Fire all handlers for a named event.
-
-### Supported Events
-
-| Event | Payload | Fired When |
-|-------|---------|------------|
-| `onNodeSelected` | Node object | A node is selected |
-| `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 | 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 (bezier/orthogonal) |
-| `onPanelOpened` | Panel data | A properties panel opens |
-| `onPanelClosed` | Panel data | A properties panel closes |
-| `onPanelMoved` | Panel data | A panel is dragged |
-| `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 to the flow |
-| `onThemeChanged` | Theme key | The active theme changes |
-
----
-
-## NodeTypes Provider API
-
-### registerNodeType(pNodeTypeConfig)
-
-Register a new node type.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `pNodeTypeConfig` | object | Node type configuration (see PictFlowCard docs) |
-
-**Returns:** `boolean`
-
-### removeNodeType(pTypeHash)
-
-Unregister a node type.
-
-**Returns:** `boolean`
-
-### getNodeType(pTypeHash)
-
-Retrieve a node type configuration by hash.
-
-**Returns:** Node type config object, or the default type if not found.
-
-### getNodeTypes()
-
-**Returns:** Map of all registered node types.
-
-### getNodeTypeList()
-
-**Returns:** Array of registered type hashes.
-
-### getEnabledCards()
-
-**Returns:** Array of card configurations where `Enabled` is `true`.
-
-### getCardsByCategory()
-
-**Returns:** Object mapping category names to arrays of card configurations.
-
----
-
-## Theme Provider API
-
-### registerTheme(pThemeKey, pThemeConfig)
-
-Register a named theme.
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `pThemeKey` | string | Unique theme identifier |
-| `pThemeConfig` | object | Theme configuration (see below) |
-
-**Theme config shape:**
-
-```javascript
-{
-	Key: 'dark',
-	Label: 'Dark Mode',
-	CSSVariables:
-	{
-		'--pf-canvas-bg': '#1a1a2e',
-		'--pf-node-body-fill': '#16213e'
-	},
-	AdditionalCSS: '/* Extra rules */',
-	NodeBodyMode: 'rect',
-	NoiseConfig: { Enabled: true, Amount: 0.5 },
-	ConnectionConfig: { StrokeDashArray: '5,5' }
-}
-```
-
-### setTheme(pThemeKey)
-
-Activate a registered theme and re-render.
-
-**Returns:** `boolean` -- `true` if the theme was found and activated.
-
-### getActiveTheme()
-
-**Returns:** Active theme configuration object.
-
-### getActiveThemeKey()
-
-**Returns:** Active theme key string.
-
-### Built-in Themes
-
-| Key | Label | Style |
-|-----|-------|-------|
-| `default` | Modern | Clean, professional |
-| `sketch` | Sketch | Hand-drawn, informal |
-| `blueprint` | Blueprint | Technical blueprint |
-| `mono` | Monochrome | Black and white |
-| `retro-80s` | Retro 80s | Neon retro |
-| `retro-90s` | Retro 90s | Vaporwave |
-
----
-
-## Layouts Provider API
-
-### saveLayout(pName)
-
-Save the current spatial arrangement.
-
-**Returns:** Layout data object.
-
-### restoreLayout(pLayoutHash)
-
-Restore a previously saved layout.
-
-**Returns:** `boolean`
-
-### deleteLayout(pLayoutHash)
-
-Delete a saved layout.
-
-**Returns:** `boolean`
-
-### loadPersistedLayouts()
-
-Load layouts from the storage backend (localStorage by default).
-
-### getLayouts()
-
-**Returns:** Array of saved layout objects.
-
-### Storage Hooks
-
-Override these methods to use a custom storage backend:
-
-| Method | Signature | Description |
-|--------|-----------|-------------|
-| `storageWrite` | `(pLayouts, fCallback)` | Persist layouts |
-| `storageRead` | `(fCallback)` | Load layouts |
-| `storageDelete` | `(fCallback)` | Clear all layouts |

package/docs/Layout_Persistence.md

@@ -1,117 +0,0 @@
-# Layout Persistence
-
-Pict-Section-Flow can save and restore spatial arrangements of nodes and panels independently of the flow data itself. This lets users maintain multiple views of the same flow graph.
-
-## How It Works
-
-A **layout** captures the position, size, and viewport state of a flow diagram at a point in time. It does not store the flow's logical content (nodes, connections, data) -- only where things are on screen.
-
-Each saved layout contains:
-
-| Property | Description |
-|----------|-------------|
-| `Hash` | Unique identifier for the layout |
-| `Name` | Display name chosen by the user |
-| `CreatedAt` | ISO 8601 timestamp |
-| `NodePositions` | Map of node hash to `{ X, Y, Width, Height }` |
-| `PanelPositions` | Map of node hash to `{ X, Y, Width, Height }` |
-| `ViewState` | `{ PanX, PanY, Zoom }` |
-
-## Default Behavior: localStorage
-
-Saved layouts persist to `localStorage` by default, keyed by the flow view identifier (e.g. `pict-flow-layouts-MyFlowDiagram`). Layouts survive page refreshes without any configuration.
-
-```javascript
-// Save the current layout
-flowView._LayoutProvider.saveLayout('My Layout');
-
-// List all saved layouts
-let tmpLayouts = flowView._LayoutProvider.getLayouts();
-
-// Restore a layout
-flowView._LayoutProvider.restoreLayout(tmpLayouts[0].Hash);
-
-// Delete a layout
-flowView._LayoutProvider.deleteLayout(tmpLayouts[0].Hash);
-```
-
-## Overriding Storage (e.g. REST API)
-
-The `LayoutProvider` exposes three hookable storage methods that follow the `fCallback(pError, pResult)` convention. Replace them on the instance to use any backend:
-
-```javascript
-// After your flow view is initialized:
-let layoutProvider = flowView._LayoutProvider;
-
-// Persist layouts to a server
-layoutProvider.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));
-};
-
-// Load layouts from a server
-layoutProvider.storageRead = function(fCallback)
-{
-	fetch('/api/my-flow/layouts')
-		.then((pResponse) => pResponse.json())
-		.then((pLayouts) => fCallback(null, pLayouts))
-		.catch((pError) => fCallback(pError, []));
-};
-
-// Delete all layouts on the server
-layoutProvider.storageDelete = function(fCallback)
-{
-	fetch('/api/my-flow/layouts', { method: 'DELETE' })
-		.then(() => fCallback(null))
-		.catch((pError) => fCallback(pError));
-};
-
-// Load from the new backend now that hooks are set
-layoutProvider.loadPersistedLayouts();
-```
-
-## Configuration Options
-
-- **`StorageKey`** (string) -- Override the localStorage key. Passed via options when instantiating the provider.
-- **`StorageKey: false`** -- Disable localStorage persistence entirely (useful when using only a remote backend).
-
-## Events
-
-The layout system fires events you can hook into:
-
-```javascript
-flowView._EventHandlerProvider.registerHandler('onLayoutSaved',
-	(pLayoutData) =>
-	{
-		console.log('Layout saved:', pLayoutData.Name);
-	});
-
-flowView._EventHandlerProvider.registerHandler('onLayoutRestored',
-	(pLayoutData) =>
-	{
-		console.log('Layout restored:', pLayoutData.Name);
-	});
-
-flowView._EventHandlerProvider.registerHandler('onLayoutDeleted',
-	(pLayoutData) =>
-	{
-		console.log('Layout deleted:', pLayoutData.Name);
-	});
-```
-
-## Restore Behavior
-
-When a layout is restored, the provider:
-
-1. Positions each node whose hash appears in `NodePositions`
-2. Positions each panel whose node hash appears in `PanelPositions`
-3. Applies the saved `ViewState` (pan and zoom)
-4. Any nodes that exist in the flow but not in the layout remain in their current position
-5. Triggers a full re-render