pict-section-flow 0.0.10 → 0.0.13

package/docs/README.md

@@ -1,69 +1,132 @@
-# Pict Section Flow Diagram
+# Pict-Section-Flow
+
+An interactive flow diagram section view for the [Pict](https://github.com/stevenvelozo/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.
+
+## What It Does
+
+Pict-Section-Flow renders an SVG-based canvas where users can:
+
+- **Drag nodes** from a palette onto the canvas
+- **Connect ports** between nodes with bezier or orthogonal paths
+- **Open properties panels** on any node for editing, documentation, or custom views
+- **Pan and zoom** the viewport with mouse or trackpad
+- **Save and restore** spatial layouts to localStorage or a remote backend
+- **Theme the entire diagram** with built-in themes or CSS custom properties
+
+All interaction is driven by a JSON data structure that represents the flow graph. The view marshals data bidirectionally with Pict's `AppData` store, so the flow state integrates naturally with the rest of your application.
+
+## Architecture at a Glance
+
+```mermaid
+graph TD
+    A[Your Application] --> B[PictViewFlow]
+    B --> C[Services]
+    B --> D[Providers]
+    B --> E[Views]
+
+    C --> C1[DataManager]
+    C --> C2[RenderManager]
+    C --> C3[SelectionManager]
+    C --> C4[ViewportManager]
+    C --> C5[PanelManager]
+    C --> C6[InteractionManager]
+    C --> C7[Layout Service]
+
+    D --> D1[NodeTypes]
+    D --> D2[EventHandler]
+    D --> D3[Layouts]
+    D --> D4[Theme]
+    D --> D5[CSS]
+    D --> D6[Geometry]
+
+    E --> E1[Flow Node View]
+    E --> E2[Toolbar View]
+    E --> E3[Properties Panel View]
+
+    style A fill:#e8f5e9,stroke:#42b983,color:#333
+    style B fill:#e3f2fd,stroke:#42a5f5,color:#333
+    style C fill:#fff3e0,stroke:#ffa726,color:#333
+    style D fill:#f3e5f5,stroke:#ab47bc,color:#333
+    style E fill:#fce4ec,stroke:#ef5350,color:#333
+```
 
-A Pict section view for rendering flow diagrams. Provides views, providers, and services for visual flow-based layouts within Pict applications.
+The module follows the standard Pict layered architecture:
 
-## Installation
+- **Views** handle rendering and DOM interaction
+- **Services** contain business logic (CRUD, selection, viewport math)
+- **Providers** supply configuration and stateless utilities (themes, node types, geometry)
 
-```bash
-npm install pict-section-flow
-```
+## Key Concepts
 
-## Building
+### Flow Data
 
-```bash
-npx quack build
-```
+The entire graph state lives in a single JSON object with four collections: `Nodes`, `Connections`, `OpenPanels`, and `SavedLayouts`. Every mutation goes through the `DataManager` service and triggers a re-render.
+
+### Custom Card Types
+
+Developers define reusable node types by extending `PictFlowCard`. Each card declares its title, ports, category, appearance, and optional properties panel. Cards register with the flow view's `NodeTypeProvider` and appear in the toolbar palette.
 
-## Layout Persistence
+### Properties Panels
 
-Saved layouts are persisted to `localStorage` by default, keyed by the flow view identifier (e.g. `pict-flow-layouts-MyFlowDiagram`). Layouts survive page refreshes without any configuration.
+Nodes can open floating panels tethered to them by a line. Four built-in panel types cover common needs — Template, Markdown, Form, and View — or you can create custom panel types by extending `PictFlowCardPropertiesPanel`.
 
-### Overriding Storage (e.g. REST API)
+### Theming
 
-The `LayoutProvider` exposes three hookable storage methods that follow the `fCallback(pError, pResult)` convention. Replace them on the instance to use any backend:
+Six built-in themes ship with the module. The theme system is CSS-variable-based: override any of 70+ `--pf-*` design tokens on `.pict-flow-container` to customize colors, shadows, radii, and typography without touching source code.
+
+### Event Hooks
+
+The `EventHandlerProvider` exposes 20+ named events (node selected, connection created, flow changed, theme changed, etc.). Register handlers to build integrations, undo/redo stacks, or server sync without modifying core code.
+
+## Quick Example
 
 ```javascript
-// After your flow view is initialized:
-let layoutProvider = myFlowView._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();
+const libPictSectionFlow = require('pict-section-flow');
+const libPict = require('pict');
+
+let _Pict = new libPict({ Product: 'FlowDemo' });
+
+_Pict.addView('MyFlow', {}, libPictSectionFlow);
+
+let tmpFlow = _Pict.views.MyFlow;
+
+// Add two nodes
+let tmpStart = tmpFlow.addNode('start', 50, 150, 'Begin');
+let tmpEnd = tmpFlow.addNode('end', 400, 150, 'Done');
+
+// Connect them
+tmpFlow.addConnection(
+	tmpStart.Hash, tmpStart.Ports[0].Hash,
+	tmpEnd.Hash, tmpEnd.Ports[0].Hash
+);
+
+// Listen for changes
+tmpFlow._EventHandlerProvider.registerHandler('onFlowChanged',
+	(pFlowData) =>
+	{
+		console.log('Flow updated:', pFlowData.Nodes.length, 'nodes');
+	});
 ```
 
-### Configuration Options
+## Learn More
+
+- **[Getting Started](Getting_Started.md)** — Build your first flow diagram in five minutes
+- **[Architecture](Architecture.md)** — Detailed service/provider design with data flow diagrams
+- **[Implementation Reference](Implementation_Reference.md)** — Complete API surface for every service and provider
+- **[Custom Styling](Custom-Styling.md)** — CSS custom properties reference and theme API
+- **[Layout Persistence](Layout_Persistence.md)** — Save and restore layouts with localStorage or REST
+
+## Ecosystem
+
+Pict-Section-Flow is part of the [Retold](https://github.com/stevenvelozo/retold) module suite:
 
-- **`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).
+- [pict](https://github.com/stevenvelozo/pict) — Core 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 panel type)
+- [fable](https://github.com/stevenvelozo/fable) — Service infrastructure and dependency injection
 
 ## License
 

package/docs/_cover.md

@@ -0,0 +1,11 @@
+# Pict-Section-Flow <small>0</small>
+
+> Interactive flow diagram section view for the Pict application framework
+
+- Node-based graph editor with typed ports and bezier connections
+- Custom card types, properties panels, and event hooks
+- Six built-in themes with 70+ CSS design tokens
+- Layout persistence to localStorage or any backend
+
+[GitHub](https://github.com/stevenvelozo/pict-section-flow)
+[Get Started](#pict-section-flow)

package/docs/_sidebar.md

@@ -0,0 +1,52 @@
+- Getting Started
+
+  - [Overview](/)
+  - [Quick Start](Getting_Started.md)
+  - [Custom Styling](Custom-Styling.md)
+
+- Architecture
+
+  - [Design Overview](Architecture.md)
+  - [Data Model](Data_Model.md)
+  - [Event System](Event_System.md)
+
+- Reference
+
+  - [Implementation Reference](Implementation_Reference.md)
+  - [Layout Persistence](Layout_Persistence.md)
+
+- API — Data Management
+
+  - [addNode](api/addNode.md)
+  - [removeNode](api/removeNode.md)
+  - [addConnection](api/addConnection.md)
+  - [removeConnection](api/removeConnection.md)
+  - [getFlowData / setFlowData](api/getFlowData.md)
+  - [marshalToView / marshalFromView](api/marshalToView.md)
+
+- API — Selection & Viewport
+
+  - [selectNode / deselectAll](api/selectNode.md)
+  - [setZoom / zoomToFit](api/setZoom.md)
+  - [autoLayout](api/autoLayout.md)
+  - [screenToSVGCoords](api/screenToSVGCoords.md)
+  - [toggleFullscreen](api/toggleFullscreen.md)
+
+- API — Panels
+
+  - [openPanel / closePanel / togglePanel](api/openPanel.md)
+
+- API — Theming & Events
+
+  - [setTheme / registerTheme](api/setTheme.md)
+  - [registerHandler / fireEvent](api/registerHandler.md)
+
+- API — Layout Persistence
+
+  - [saveLayout / restoreLayout](api/saveLayout.md)
+
+- API — Extension Points
+
+  - [PictFlowCard](api/PictFlowCard.md)
+  - [PictFlowCardPropertiesPanel](api/PictFlowCardPropertiesPanel.md)
+  - [registerNodeType](api/registerNodeType.md)

package/docs/_topbar.md

@@ -0,0 +1,8 @@
+# Pict Section Flow
+
+- [Overview](README.md)
+- [Getting Started](Getting_Started.md)
+- [Architecture](Architecture.md)
+- [API Reference](Implementation_Reference.md)
+- [Custom Styling](Custom-Styling.md)
+- [GitHub](https://github.com/stevenvelozo/pict-section-flow)

package/docs/api/PictFlowCard.md

@@ -0,0 +1,216 @@
+# PictFlowCard
+
+Base class for defining reusable flow diagram node types. Extend this class to create custom cards that appear in the toolbar palette. Each card declares its title, ports, category, appearance, and optional properties panel.
+
+## Import
+
+```javascript
+const libPictFlowCard = require('pict-section-flow').PictFlowCard;
+```
+
+## Constructor
+
+```javascript
+class MyCard extends libPictFlowCard
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, Object.assign({},
+			{
+				Title: 'My Card',
+				Code: 'MC',
+				// ... options
+			}, pOptions), pServiceHash);
+	}
+}
+```
+
+## Configuration Options
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `Title` | string | `'Card'` | Display name on the node title bar |
+| `Name` | string | `false` | Longer descriptive name |
+| `Code` | string | `''` | Short identifier used as the node type key |
+| `Description` | string | `false` | Brief explanation of the card's purpose |
+| `Icon` | string | `false` | Icon identifier or emoji |
+| `PreviewImage` | string | `false` | URL to a preview thumbnail |
+| `Documentation` | string | `false` | URL or inline documentation text |
+| `Tooltip` | string | `false` | Hover tooltip text |
+| `Help` | string | `false` | HTML help content for the Help tab |
+| `Category` | string | `'General'` | Palette grouping category |
+| `Enabled` | boolean | `true` | Whether the card appears in the palette |
+| `TitleBarColor` | string | `'#2c3e50'` | Title bar background color |
+| `BodyStyle` | object | `{}` | SVG style attributes for the node body |
+| `Width` | number | `180` | Default node width in pixels |
+| `Height` | number | `80` | Default node height in pixels |
+
+### Port Options
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `Inputs` | array | `[]` | Input port definitions |
+| `Outputs` | array | `[]` | Output port definitions |
+
+Each port object:
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `Name` | string | Required | Port label |
+| `Side` | string | `'left'`/`'right'` | Port side: `'left'`, `'right'`, `'top'`, `'bottom'` |
+| `MinimumInputCount` | number | `0` | Minimum required connections (inputs only) |
+| `MaximumInputCount` | number | `-1` | Maximum allowed connections (-1 = unlimited, inputs only) |
+| `PortType` | string | — | Type for styling: `'event'`, `'setting'`, `'value'`, `'error'` |
+| `DataType` | string | — | Semantic data type (for validation/display) |
+
+### Label Display Options
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `ShowTypeLabel` | boolean | `true` | Show the type code badge on hover |
+| `PortLabelsOnHover` | boolean | `false` | Only show port labels on hover |
+| `PortLabelsVertical` | boolean | `false` | Render port labels vertically |
+| `PortLabelPadding` | boolean | `false` | Extra spacing to avoid overlap |
+| `PortLabelsOutside` | boolean | `false` | Render labels outside the node body |
+| `LabelsInFront` | boolean | `true` | Labels render in front of body content |
+
+### Properties Panel Configuration
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `PropertiesPanel.PanelType` | string | `'Template'`, `'Markdown'`, `'Form'`, or `'View'` |
+| `PropertiesPanel.DefaultWidth` | number | Panel width in pixels |
+| `PropertiesPanel.DefaultHeight` | number | Panel height in pixels |
+| `PropertiesPanel.Title` | string | Panel title bar text |
+| `PropertiesPanel.Configuration` | object | Panel-type-specific config |
+
+### Body Content Configuration
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `BodyContent.ContentType` | string | `'svg'`, `'html'`, or `'canvas'` |
+| `BodyContent.Template` | string | Pict template string |
+| `BodyContent.TemplateHash` | string | Registered template hash (overrides Template) |
+| `BodyContent.Templates` | array | Templates to auto-register: `[{ Hash, Template }]` |
+| `BodyContent.RenderCallback` | function | Imperative render callback for canvas mode |
+| `BodyContent.Padding` | number | Inner padding in pixels |
+
+## Methods
+
+### getNodeTypeConfiguration()
+
+Generate the configuration object for the NodeTypes provider.
+
+**Returns:** Node type configuration object.
+
+### registerWithFlowView(pFlowView)
+
+Register this card with a flow view's node type provider.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `pFlowView` | PictViewFlow | The flow view instance |
+
+**Returns:** `boolean` — whether registration succeeded.
+
+## Examples
+
+### Minimal card
+
+```javascript
+class LogCard extends libPictFlowCard
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, Object.assign({},
+			{
+				Title: 'Log',
+				Code: 'LOG',
+				Inputs: [{ Name: 'Data', Side: 'left' }],
+				Outputs: [{ Name: 'Pass', Side: 'right' }]
+			}, pOptions), pServiceHash);
+	}
+}
+```
+
+### Card with typed ports and properties panel
+
+```javascript
+class IfThenElseCard extends libPictFlowCard
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, Object.assign({},
+			{
+				Title: 'If-Then-Else',
+				Code: 'ITE',
+				Category: 'Control Flow',
+				Description: 'Route flow based on a boolean condition',
+				TitleBarColor: '#e67e22',
+				Width: 160,
+				Height: 90,
+				Inputs:
+				[
+					{ Name: 'Condition', Side: 'left', PortType: 'value' }
+				],
+				Outputs:
+				[
+					{ Name: 'Then', Side: 'right', PortType: 'event' },
+					{ Name: 'Else', Side: 'bottom', PortType: 'error' }
+				],
+				PropertiesPanel:
+				{
+					PanelType: 'Markdown',
+					Title: 'If-Then-Else',
+					DefaultWidth: 280,
+					DefaultHeight: 150,
+					Configuration:
+					{
+						Markdown: '## Conditional Branch\nRoutes flow based on a boolean condition.'
+					}
+				}
+			}, pOptions), pServiceHash);
+	}
+}
+```
+
+### Card with custom SVG body content
+
+```javascript
+class SparklineCard extends libPictFlowCard
+{
+	constructor(pFable, pOptions, pServiceHash)
+	{
+		super(pFable, Object.assign({},
+			{
+				Title: 'Sparkline',
+				Code: 'SPARK',
+				Category: 'Visualization',
+				Width: 200,
+				Height: 100,
+				Inputs: [{ Name: 'Values', Side: 'left', PortType: 'value' }],
+				BodyContent:
+				{
+					ContentType: 'svg',
+					Template: '<polyline points="0,50 20,30 40,45 60,10 80,35 100,20" fill="none" stroke="#3498db" stroke-width="2" />'
+				}
+			}, pOptions), pServiceHash);
+	}
+}
+```
+
+### Registration
+
+```javascript
+let tmpCard = new IfThenElseCard(_Pict, {});
+tmpCard.registerWithFlowView(flowView);
+
+// The card now appears in the toolbar palette under "Control Flow"
+// Users can drag it onto the canvas to create new ITE nodes
+```
+
+## See Also
+
+- [registerNodeType](registerNodeType.md) — Register types directly without PictFlowCard
+- [PictFlowCardPropertiesPanel](PictFlowCardPropertiesPanel.md) — Custom panel types
+- [addNode](addNode.md) — Create nodes from registered types