Pict-Section-Flow

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

npm install pict-section-flow

Quick Start

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:

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);
	}
}

Card Help from Markdown

Store help documentation as markdown files in docs/card-help/ named by card code (e.g. ITE.md, SET.md). The build script converts them to HTML and generates a JavaScript module:

npm run generate-help

Reference the generated content in your card constructor:

const libCardHelp = require('./card-help-content');

// In the constructor options object:
Help: libCardHelp['ITE'] || false,

The || false fallback ensures the build never fails if a markdown file is missing.

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/

• Getting Started — First flow diagram in five minutes
• Architecture — Service/provider design and data flow
• Implementation Reference — Complete API surface
• Custom Styling — CSS custom properties and theme API
• Layout Persistence — Save/restore with localStorage or REST

API Reference (Function Docs)

Detailed per-function documentation with code snippets:

| Function | Description | |----------|-------------| | addNode | Create a node on the canvas | | removeNode | Delete a node and its connections | | addConnection | Connect two ports | | removeConnection | Delete a connection | | getFlowData / setFlowData | Get or load entire flow state | | selectNode / deselectAll | Manage selection state | | openPanel / closePanel / togglePanel | Properties panel lifecycle | | setZoom / zoomToFit | Viewport zoom controls | | autoLayout | Automatic topological layout | | setTheme / registerTheme | Theme management | | registerHandler / fireEvent | Event system | | saveLayout / restoreLayout | Layout persistence | | marshalToView / marshalFromView | AppData two-way binding | | PictFlowCard | Custom node type base class | | PictFlowCardPropertiesPanel | Custom panel base class | | registerNodeType | Node type registry | | screenToSVGCoords | Coordinate conversion | | toggleFullscreen | Fullscreen mode |

Related Packages

• pict — MVC application framework
• pict-view — View base class
• pict-provider — Provider base class
• pict-section-form — Form sections (used for Form panels)
• 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.