pict-section-flow 0.0.9 → 0.0.12

package/README.md

@@ -0,0 +1,157 @@
+# Pict-Section-Flow
+
+[![npm version](https://badge.fury.io/js/pict-section-flow.svg)](https://www.npmjs.com/package/pict-section-flow)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+An interactive flow diagram section view for the Pict application framework. Build node-based visual editors, workflow designers, and data pipeline tools with a declarative, configuration-driven API.
+
+Pict-Section-Flow provides a complete graph editing experience — nodes, ports, connections, properties panels, theming, and layout persistence — all composable through the Fable service provider pattern.
+
+## Features
+
+- **Node-Based Graph Editor** — Drag-and-drop nodes with typed input/output ports and bezier or orthogonal connections
+- **Custom Card Types** — Define reusable node types with the `PictFlowCard` base class; register categories, icons, port constraints, and body content
+- **Properties Panels** — On-graph panels with four built-in types: Template, Markdown, Form, and View
+- **Theming** — Six built-in themes plus a CSS custom properties API with 70+ design tokens
+- **Layout Persistence** — Save and restore spatial arrangements to localStorage or any backend
+- **Event System** — Hook into 20+ lifecycle events for custom behavior without modifying core code
+- **Viewport Controls** — Pan, zoom, fullscreen, grid snap, zoom-to-fit, and auto-layout
+
+## Installation
+
+```bash
+npm install pict-section-flow
+```
+
+## Quick Start
+
+```javascript
+const libPictSectionFlow = require('pict-section-flow');
+const libPict = require('pict');
+
+let _Pict = new libPict({ Product: 'MyFlowApp' });
+
+// Register the flow view
+_Pict.addView('MyFlow', {}, libPictSectionFlow);
+
+// Add a node programmatically
+let tmpFlowView = _Pict.views.MyFlow;
+tmpFlowView.addNode('start', 50, 100, 'Begin');
+tmpFlowView.addNode('end', 400, 100, 'Finish');
+```
+
+## Custom Card Types
+
+Define reusable node types by extending `PictFlowCard`:
+
+```javascript
+const libPictFlowCard = require('pict-section-flow').PictFlowCard;
+
+class IfThenElseCard extends libPictFlowCard
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, Object.assign({},
+			{
+				Title: 'If-Then-Else',
+				Code: 'ITE',
+				Category: 'Control Flow',
+				TitleBarColor: '#e67e22',
+				Inputs: [{ Name: 'Condition', Side: 'left' }],
+				Outputs:
+				[
+					{ Name: 'Then', Side: 'right', PortType: 'event' },
+					{ Name: 'Else', Side: 'bottom', PortType: 'error' }
+				],
+				PropertiesPanel:
+				{
+					PanelType: 'Markdown',
+					Title: 'If-Then-Else',
+					Configuration:
+					{
+						Markdown: '## Conditional Branch\nRoutes flow based on a boolean condition.'
+					}
+				}
+			}, pOptions), pServiceHash);
+	}
+}
+```
+
+## Configuration Options
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `ViewIdentifier` | string | `'Pict-Flow'` | Unique view identifier |
+| `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 port-to-port connections |
+| `EnableGridSnap` | boolean | `false` | Snap nodes to grid |
+| `GridSnapSize` | number | `20` | Grid cell size in pixels |
+| `MinZoom` | number | `0.1` | Minimum zoom level |
+| `MaxZoom` | number | `5.0` | Maximum zoom level |
+| `Theme` | string | `'default'` | Active theme key |
+
+## Built-in Themes
+
+| Theme | Style |
+|-------|-------|
+| `default` | Clean, modern, professional |
+| `sketch` | Hand-drawn, informal |
+| `blueprint` | Technical blueprint |
+| `mono` | Monochrome |
+| `retro-80s` | Neon retro |
+| `retro-90s` | Vaporwave |
+
+## Documentation
+
+Full documentation is available at [https://stevenvelozo.github.io/pict-section-flow/](https://stevenvelozo.github.io/pict-section-flow/)
+
+- [Getting Started](https://stevenvelozo.github.io/pict-section-flow/#/Getting_Started) — First flow diagram in five minutes
+- [Architecture](https://stevenvelozo.github.io/pict-section-flow/#/Architecture) — Service/provider design and data flow
+- [Implementation Reference](https://stevenvelozo.github.io/pict-section-flow/#/Implementation_Reference) — Complete API surface
+- [Custom Styling](https://stevenvelozo.github.io/pict-section-flow/#/Custom-Styling) — CSS custom properties and theme API
+- [Layout Persistence](https://stevenvelozo.github.io/pict-section-flow/#/Layout_Persistence) — Save/restore with localStorage or REST
+
+## API Reference (Function Docs)
+
+Detailed per-function documentation with code snippets:
+
+| Function | Description |
+|----------|-------------|
+| [addNode](docs/api/addNode.md) | Create a node on the canvas |
+| [removeNode](docs/api/removeNode.md) | Delete a node and its connections |
+| [addConnection](docs/api/addConnection.md) | Connect two ports |
+| [removeConnection](docs/api/removeConnection.md) | Delete a connection |
+| [getFlowData / setFlowData](docs/api/getFlowData.md) | Get or load entire flow state |
+| [selectNode / deselectAll](docs/api/selectNode.md) | Manage selection state |
+| [openPanel / closePanel / togglePanel](docs/api/openPanel.md) | Properties panel lifecycle |
+| [setZoom / zoomToFit](docs/api/setZoom.md) | Viewport zoom controls |
+| [autoLayout](docs/api/autoLayout.md) | Automatic topological layout |
+| [setTheme / registerTheme](docs/api/setTheme.md) | Theme management |
+| [registerHandler / fireEvent](docs/api/registerHandler.md) | Event system |
+| [saveLayout / restoreLayout](docs/api/saveLayout.md) | Layout persistence |
+| [marshalToView / marshalFromView](docs/api/marshalToView.md) | AppData two-way binding |
+| [PictFlowCard](docs/api/PictFlowCard.md) | Custom node type base class |
+| [PictFlowCardPropertiesPanel](docs/api/PictFlowCardPropertiesPanel.md) | Custom panel base class |
+| [registerNodeType](docs/api/registerNodeType.md) | Node type registry |
+| [screenToSVGCoords](docs/api/screenToSVGCoords.md) | Coordinate conversion |
+| [toggleFullscreen](docs/api/toggleFullscreen.md) | Fullscreen mode |
+
+## Related Packages
+
+- [pict](https://github.com/stevenvelozo/pict) — MVC application framework
+- [pict-view](https://github.com/stevenvelozo/pict-view) — View base class
+- [pict-provider](https://github.com/stevenvelozo/pict-provider) — Provider base class
+- [pict-section-form](https://github.com/stevenvelozo/pict-section-form) — Form sections (used for Form panels)
+- [fable](https://github.com/stevenvelozo/fable) — Service infrastructure
+
+## License
+
+MIT
+
+## Contributing
+
+Pull requests are welcome. For details on our code of conduct, contribution process, and testing requirements, see the [Retold Contributing Guide](https://github.com/stevenvelozo/retold/blob/main/docs/contributing.md).

package/docs/Architecture.md

@@ -0,0 +1,303 @@
+# Architecture
+
+Pict-Section-Flow follows the standard Pict layered architecture — Views for rendering, Services for business logic, and Providers for configuration and stateless utilities. All components register with a Fable instance through the service provider pattern.
+
+## High-Level Design
+
+```mermaid
+graph TB
+    subgraph Application["Your Application"]
+        AppCode[Application Code]
+        AppData[Pict AppData Store]
+    end
+
+    subgraph FlowView["PictViewFlow (Main Entry Point)"]
+        direction TB
+        FV[PictViewFlow]
+    end
+
+    subgraph Views["Views (Rendering)"]
+        NodeView[Flow Node View]
+        ToolbarView[Toolbar View]
+        FloatingToolbar[Floating Toolbar View]
+        PanelView[Properties Panel View]
+    end
+
+    subgraph Services["Services (Business Logic)"]
+        DM[DataManager]
+        RM[RenderManager]
+        SM[SelectionManager]
+        VM[ViewportManager]
+        PM[PanelManager]
+        IM[InteractionManager]
+        LS[Layout Service]
+        CR[ConnectionRenderer]
+        PG[PathGenerator]
+        PR[PortRenderer]
+        CHM[ConnectionHandleManager]
+        TM[Tether Service]
+    end
+
+    subgraph Providers["Providers (Configuration)"]
+        NTP[NodeTypes Provider]
+        EHP[EventHandler Provider]
+        LP[Layouts Provider]
+        TP[Theme Provider]
+        CP[CSS Provider]
+        GP[Geometry Provider]
+        NP[Noise Provider]
+        SVG[SVGHelpers Provider]
+        CSP[ConnectorShapes Provider]
+        IP[Icons Provider]
+        PCP[PanelChrome Provider]
+    end
+
+    subgraph Extension["Extension Points"]
+        FC[PictFlowCard]
+        FCP[PictFlowCardPropertiesPanel]
+        PT[Panel: Template]
+        PMD[Panel: Markdown]
+        PF[Panel: Form]
+        PVW[Panel: View]
+    end
+
+    AppCode --> FV
+    FV <--> AppData
+    FV --> Views
+    FV --> Services
+    FV --> Providers
+
+    DM <--> AppData
+    RM --> NodeView
+    RM --> CR
+    PM --> PanelView
+    IM --> SM
+    IM --> VM
+    CR --> PG
+    CR --> PR
+
+    FC --> NTP
+    FCP --> PM
+    PT --> PanelView
+    PMD --> PanelView
+    PF --> PanelView
+    PVW --> PanelView
+
+    EHP --> AppCode
+
+    style Application fill:#e8f5e9,stroke:#42b983,color:#333
+    style FlowView fill:#e3f2fd,stroke:#42a5f5,color:#333
+    style Views fill:#fce4ec,stroke:#ef5350,color:#333
+    style Services fill:#fff3e0,stroke:#ffa726,color:#333
+    style Providers fill:#f3e5f5,stroke:#ab47bc,color:#333
+    style Extension fill:#e0f2f1,stroke:#26a69a,color:#333
+```
+
+## Data Flow
+
+All mutations flow through a predictable pipeline:
+
+```mermaid
+sequenceDiagram
+    participant App as Application
+    participant FV as PictViewFlow
+    participant DM as DataManager
+    participant EH as EventHandler
+    participant RM as RenderManager
+
+    App->>FV: addNode('start', 50, 100, 'Begin')
+    FV->>DM: addNode(pType, pX, pY, pTitle, pData)
+    DM->>DM: Create node object with UUID hash
+    DM->>DM: Merge default ports from NodeType
+    DM->>EH: fireEvent('onNodeAdded', node)
+    DM->>EH: fireEvent('onFlowChanged', flowData)
+    DM->>RM: renderFlow()
+    RM->>RM: Render SVG nodes, connections, tethers, panels
+    DM-->>FV: Return node object
+    FV-->>App: Return node object
+```
+
+## SVG Layer Structure
+
+The rendering system uses SVG group elements in a specific z-order:
+
+```mermaid
+graph TB
+    subgraph SVG["SVG Canvas"]
+        Grid["Grid Background (pattern)"]
+        subgraph Viewport["Viewport Group (pan/zoom transform)"]
+            Connections["Connections Layer (bezier/orthogonal paths)"]
+            Nodes["Nodes Layer (rect + ports + labels)"]
+            Tethers["Tethers Layer (panel-to-node lines)"]
+            Panels["Panels Layer (foreignObject panels)"]
+        end
+    end
+
+    Grid --> Viewport
+    Connections --> Nodes
+    Nodes --> Tethers
+    Tethers --> Panels
+
+    style SVG fill:#f5f5f5,stroke:#bdbdbd,color:#333
+    style Viewport fill:#e3f2fd,stroke:#42a5f5,color:#333
+```
+
+Connections render behind nodes so lines do not obscure node bodies. Tethers render above nodes so the connecting line from a panel to its node is always visible. Panels render last so they float above everything.
+
+## Component Roles
+
+### Views
+
+| View | Role |
+|------|------|
+| `PictViewFlow` | Main entry point. Orchestrates services, providers, and child views. Exposes the public API. |
+| `PictViewFlowNode` | Renders individual node SVG groups (title bar, body, ports, labels). |
+| `PictViewFlowToolbar` | Renders the docked toolbar with palette cards, zoom controls, and layout buttons. |
+| `PictViewFlowFloatingToolbar` | Renders context-sensitive floating toolbar on node selection. |
+| `PictViewFlowPropertiesPanel` | Renders panel chrome and delegates content to panel type handlers. |
+
+### Services
+
+| Service | Role |
+|---------|------|
+| `DataManager` | CRUD for nodes and connections. Marshals to/from AppData. Fires data events. |
+| `RenderManager` | Orchestrates full and partial re-renders. Delegates to node, connection, and panel renderers. |
+| `SelectionManager` | Tracks selected node, connection, or tether. Fires selection events. |
+| `ViewportManager` | Pan, zoom, fullscreen, coordinate transforms. |
+| `PanelManager` | Open, close, toggle, and position properties panels. |
+| `InteractionManager` | Pointer and keyboard event handling. State machine for drag modes. |
+| `Layout Service` | Grid snap math and topological auto-layout algorithm. |
+| `ConnectionRenderer` | Renders bezier and orthogonal paths with arrowheads. |
+| `PathGenerator` | Pure math: bezier curves and orthogonal routing. |
+| `PortRenderer` | Renders port circles on node boundaries. |
+| `ConnectionHandleManager` | Manages bezier control point state for manual path adjustments. |
+| `Tether` | Renders the connecting lines between panels and their parent nodes. |
+
+### Providers
+
+| Provider | Role |
+|----------|------|
+| `NodeTypes` | Registry of available node types. Cards register here. |
+| `EventHandler` | Named event system with multi-handler support. |
+| `Layouts` | Save/restore/delete layout snapshots. Pluggable storage backend. |
+| `Theme` | Named theme registry. Applies CSS variable overrides. |
+| `CSS` | Generates and injects all CSS into Pict's CSSMap service. |
+| `Geometry` | Port positioning math: local coordinates, minimum node height, port counts by side. |
+| `Noise` | Perlin-like noise for the hand-drawn rendering effect. |
+| `SVGHelpers` | DOM utilities for creating and manipulating SVG elements. |
+| `ConnectorShapes` | SVG marker definitions for arrowheads by port type. |
+| `Icons` | Icon template library for toolbar and node UI. |
+| `PanelChrome` | Panel title bar and tab bar template generation. |
+
+## Flow Data Structure
+
+The canonical flow state is a plain JavaScript object:
+
+```javascript
+{
+	Nodes:
+	[
+		{
+			Hash: 'node-<UUID>',
+			Type: 'start',
+			X: 50, Y: 180,
+			Width: 140, Height: 80,
+			Title: 'Start',
+			Ports:
+			[
+				{
+					Hash: 'port-<UUID>',
+					Direction: 'output',
+					Side: 'right',
+					Label: 'Out',
+					PortType: 'event'
+				}
+			],
+			Data: {}
+		}
+	],
+
+	Connections:
+	[
+		{
+			Hash: 'conn-<UUID>',
+			SourceNodeHash: 'node-...',
+			SourcePortHash: 'port-...',
+			TargetNodeHash: 'node-...',
+			TargetPortHash: 'port-...',
+			Data:
+			{
+				LineMode: 'bezier',
+				HandleCustomized: false
+			}
+		}
+	],
+
+	OpenPanels:
+	[
+		{
+			Hash: 'panel-<UUID>',
+			NodeHash: 'node-...',
+			PanelType: 'Template',
+			Title: 'Properties',
+			X: 300, Y: 250,
+			Width: 300, Height: 200
+		}
+	],
+
+	SavedLayouts: [],
+
+	ViewState:
+	{
+		PanX: 0, PanY: 0,
+		Zoom: 1,
+		SelectedNodeHash: null,
+		SelectedConnectionHash: null,
+		SelectedTetherHash: null
+	}
+}
+```
+
+## Service Initialization Sequence
+
+When PictViewFlow initializes, it follows a declarative registry to instantiate all components:
+
+```mermaid
+sequenceDiagram
+    participant App as Application
+    participant FV as PictViewFlow
+    participant PR as Providers
+    participant SV as Services
+    participant VW as Child Views
+
+    App->>FV: new PictViewFlow(fable, options)
+    FV->>PR: Register & instantiate providers
+    Note over PR: SVGHelpers, Geometry, Noise (no FlowView ref)
+    Note over PR: Theme, CSS, Icons, NodeTypes, EventHandler, Layouts (with FlowView ref)
+    FV->>SV: Register & instantiate services
+    Note over SV: DataManager, RenderManager, SelectionManager, etc.
+    FV->>VW: Register & instantiate child views
+    Note over VW: Node, Toolbar, FloatingToolbar, PropertiesPanel
+
+    App->>FV: render()
+    FV->>SV: DataManager.marshalToView()
+    FV->>SV: RenderManager.renderFlow()
+```
+
+## Design Patterns
+
+### Service Provider Pattern
+
+Every service and provider extends `fable-serviceproviderbase` and registers with the Fable instance. This means any component can access any other through `this.fable` without explicit imports or singletons.
+
+### Event-Driven Architecture
+
+The `EventHandlerProvider` decouples application code from the flow internals. Services fire events; application code registers handlers. This avoids subclassing or monkey-patching to extend behavior.
+
+### Data/View Separation
+
+The flow data structure is completely separate from the SVG DOM. Mutations operate on the data model; the render manager regenerates the DOM from the model. This makes serialization, undo/redo, and server sync straightforward.
+
+### Selective Re-rendering
+
+Full re-renders are used when the graph topology changes (node added/removed, connection added/removed). During interactive operations like node dragging, only the affected elements (the dragged node and its connections) are updated for smooth performance.