pict-section-flow 0.0.12 → 0.0.13

package/.claude/launch.json

@@ -4,7 +4,7 @@
     {
       "name": "simple-cards",
       "runtimeExecutable": "npx",
-      "runtimeArgs": ["http-server", "example_applications/simple_cards", "-p", "8085", "-c-1"],
+      "runtimeArgs": ["http-server", "example_applications/simple_cards/dist", "-p", "8085", "-c-1"],
       "port": 8085
     }
   ]

package/README.md

@@ -77,6 +77,25 @@ class IfThenElseCard extends libPictFlowCard
 }
 ```
 
+### 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:
+
+```bash
+npm run generate-help
+```
+
+Reference the generated content in your card constructor:
+
+```javascript
+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 |

package/docs/Data_Model.md

@@ -0,0 +1,158 @@
+# Data Model
+
+The entire flow graph state is represented by a single JSON object called **FlowData**. Every mutation goes through the `DataManager` service and triggers a re-render. This structure is what gets persisted when you call `marshalFromView()` and restored with `marshalToView()`.
+
+## FlowData Structure
+
+```javascript
+{
+    Nodes: [],           // Array of node objects
+    Connections: [],     // Array of connection objects
+    OpenPanels: [],      // Array of panel objects
+    SavedLayouts: [],    // Array of layout snapshots
+    ViewState:
+    {
+        PanX: 0,         // Viewport horizontal offset
+        PanY: 0,         // Viewport vertical offset
+        Zoom: 1,         // Viewport zoom level
+        SelectedNodeHash: null,
+        SelectedConnectionHash: null,
+        SelectedTetherHash: null
+    }
+}
+```
+
+## Node
+
+Each node represents a discrete operation in the flow graph.
+
+```javascript
+{
+    Hash: 'abc123',          // Unique identifier (auto-generated)
+    Type: 'ITE',             // Card type code (references NodeTypes)
+    X: 200,                  // Horizontal position in SVG space
+    Y: 150,                  // Vertical position in SVG space
+    Width: 200,              // Node width in pixels
+    Height: 100,             // Node height in pixels
+    Title: 'If-Then-Else',   // Display title on the node
+    Ports:                   // Array of port definitions
+    [
+        {
+            Hash: 'port-1',
+            Direction: 'input',         // 'input' or 'output'
+            Side: 'left',              // Port position on node edge
+            Label: 'In',              // Port label text
+            PortType: 'event-in',     // Optional type for coloring
+            DataType: 'boolean',      // Optional data type hint
+            MinimumInputCount: 1,     // Minimum connections (0 = optional)
+            MaximumInputCount: 1      // Maximum connections (-1 = unlimited)
+        }
+    ],
+    Style:                   // Optional per-node style overrides
+    {
+        BodyFill: '#fef5e7',
+        BodyStroke: '#e67e22',
+        BodyStrokeWidth: 1,
+        TitleBarColor: '#e67e22'
+    },
+    Data: {}                 // User-defined payload (card-specific)
+}
+```
+
+### Port Side Positions
+
+Ports can be placed at 12 positions around the node perimeter using a zone system:
+
+```
+top-left        top         top-right
+left-top       (body)       right-top
+left                        right
+left-bottom    (body)       right-bottom
+bottom-left    bottom       bottom-right
+```
+
+The legacy four-value sides (`left`, `right`, `top`, `bottom`) map to the middle zone of each edge.
+
+## Connection
+
+A connection links an output port on one node to an input port on another.
+
+```javascript
+{
+    Hash: 'conn-1',
+    SourceNodeHash: 'node-a',
+    SourcePortHash: 'port-out',
+    TargetNodeHash: 'node-b',
+    TargetPortHash: 'port-in',
+    Data:
+    {
+        LineMode: 'bezier',       // 'bezier' or 'orthogonal'
+        HandleCustomized: false,  // True if handles have been manually moved
+
+        // Bezier handles (multi-point curve control)
+        BezierHandles: [{ x: 300, y: 175 }],
+
+        // Orthogonal handles (right-angle path corners)
+        OrthoCorner1X: 250,
+        OrthoCorner1Y: 150,
+        OrthoCorner2X: 350,
+        OrthoCorner2Y: 200,
+        OrthoMidOffset: 0
+    }
+}
+```
+
+### Connection Routing
+
+Connections support two path modes:
+
+- **Bezier** (default) — Smooth curves with one or more control handles. Right-click a connection to add a handle; drag handles to reshape the curve.
+- **Orthogonal** — Right-angle paths with two corner points. Double-click a connection handle to toggle between bezier and orthogonal modes.
+
+## Panel
+
+An open properties panel associated with a node.
+
+```javascript
+{
+    Hash: 'panel-1',
+    NodeHash: 'node-a',          // The node this panel belongs to
+    PanelType: 'Form',           // 'Template', 'Markdown', 'Form', 'View', or 'Info'
+    Title: 'Set Value Properties',
+    X: 450,                      // Panel position in SVG space
+    Y: 100,
+    Width: 320,
+    Height: 200
+}
+```
+
+Each panel is rendered as an HTML `foreignObject` inside the SVG, with a tether line connecting it to its parent node. Panels can be dragged, resized, and have tabbed views for Properties, Help, and Appearance.
+
+## ViewState
+
+Viewport and selection state, persisted with the flow data.
+
+```javascript
+{
+    PanX: -120,                       // Horizontal pan offset
+    PanY: -50,                        // Vertical pan offset
+    Zoom: 0.85,                       // Zoom level (0.1 to 5.0)
+    SelectedNodeHash: 'node-a',       // Currently selected node (null if none)
+    SelectedConnectionHash: null,     // Currently selected connection
+    SelectedTetherHash: null          // Currently selected tether line
+}
+```
+
+## Relationships
+
+```mermaid
+erDiagram
+    FlowData ||--o{ Node : contains
+    FlowData ||--o{ Connection : contains
+    FlowData ||--o{ Panel : contains
+    FlowData ||--|| ViewState : has
+    Node ||--o{ Port : has
+    Connection }o--|| Port : "source port"
+    Connection }o--|| Port : "target port"
+    Panel }o--|| Node : "attached to"
+```

package/docs/Event_System.md

@@ -0,0 +1,156 @@
+# 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/_sidebar.md

@@ -1,13 +1,18 @@
 - Getting Started
 
-  - [Introduction](/)
-  - [Getting Started](Getting_Started.md)
-  - [Architecture](Architecture.md)
+  - [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)
-  - [Custom Styling](Custom-Styling.md)
   - [Layout Persistence](Layout_Persistence.md)
 
 - API — Data Management

package/docs/card-help/EACH.md

@@ -0,0 +1,19 @@
+# Each (Loop Iterator)
+
+The **Each** node iterates over a collection, executing connected downstream nodes once for each item. When iteration completes, the **Done** output fires.
+
+## Ports
+
+- **Collection** (input) — an array or iterable to loop over
+- **Item** (output) — fires once per element with the current item
+- **Done** (output) — fires after all items have been processed
+
+## Behavior
+
+When a collection arrives at the input port, the Each node processes items sequentially. For every element in the collection, the **Item** output is activated with the current element as the payload. After the final element is processed, the **Done** output fires to signal completion.
+
+## Tips
+
+- Connect **Item** to a processing chain and **Done** to continuation logic
+- Nested loops are supported by chaining multiple Each nodes
+- Empty collections skip directly to the **Done** output

package/docs/card-help/FREAD.md

@@ -0,0 +1,24 @@
+# File Read
+
+The **File Read** node reads the contents of a file from the filesystem and outputs the data.
+
+## Ports
+
+- **Path** (input) — the filesystem path to read
+- **Data** (output) — the file contents on success
+- **Error** (output) — fires if the read operation fails
+
+## Properties
+
+- **FilePath** — the path to the file to read
+- **Encoding** — character encoding for text files (e.g. `utf8`, `ascii`)
+
+## Behavior
+
+When triggered, the node reads the file at the configured path. On success, the raw file contents are emitted from the **Data** output. If the file does not exist or cannot be read, the **Error** output fires with a descriptive error message.
+
+## Tips
+
+- Use a Get Value node upstream to dynamically set the file path
+- Pair with a Data Preview node to inspect the file contents
+- Connect the **Error** output to logging or notification nodes for robust error handling

package/docs/card-help/FWRITE.md

@@ -0,0 +1,24 @@
+# File Write
+
+The **File Write** node writes data to a file on the filesystem.
+
+## Ports
+
+- **Path** (input) — the destination filesystem path
+- **Data** (input) — the content to write
+- **Done** (output) — fires after a successful write
+- **Error** (output) — fires if the write operation fails
+
+## Behavior
+
+When both inputs are satisfied, the node writes the provided data to the specified file path. On success the **Done** output fires. If the write fails (for example due to permissions or a missing directory), the **Error** output fires with a descriptive error message.
+
+## Properties Panel
+
+The properties panel shows a View-based info panel with details about the configured file path and write options.
+
+## Tips
+
+- Directories in the path are not created automatically — ensure they exist before writing
+- Combine with a Set Value node to format data before writing
+- Connect the **Error** output to a Log Values node to capture write failures

package/docs/card-help/GET.md

@@ -0,0 +1,22 @@
+# Get Value
+
+The **Get Value** node retrieves a named variable from the flow context and emits its current value.
+
+## Ports
+
+- **In** (input) — trigger to read the value
+- **Value** (output) — the retrieved value
+
+## Behavior
+
+When triggered, the node looks up a named key in the flow context and emits the stored value from the **Value** output. If the key does not exist, the output value is `undefined`.
+
+## Usage
+
+Pair with a **Set Value** node to establish a read/write variable pattern. The Set Value node stores a value under a named key; the Get Value node retrieves it downstream.
+
+## Tips
+
+- Variable names are case-sensitive
+- Use descriptive variable names to keep flows readable
+- Get Value is especially useful for accessing values set in a different branch of the flow

package/docs/card-help/ITE.md

@@ -0,0 +1,23 @@
+# If-Then-Else
+
+The **If-Then-Else** node evaluates a boolean condition expression and routes the flow to one of two outputs.
+
+## Ports
+
+- **In** (input) — trigger that starts the evaluation
+- **Then** (output) — activated when the condition is **true**
+- **Else** (output) — activated when the condition is **false**
+
+## Behavior
+
+When the input fires, the node evaluates the configured condition expression against the current flow context. If the expression resolves to a truthy value, the **Then** output is activated. Otherwise, the **Else** output is activated. Exactly one output fires per evaluation.
+
+## Configuration
+
+Set the condition expression in the node's data properties. The expression is evaluated in the flow context, giving it access to any variables set by upstream Set Value nodes.
+
+## Tips
+
+- Chain multiple If-Then-Else nodes for complex branching logic
+- Connect the **Else** output to another If-Then-Else to build else-if chains
+- Use descriptive condition expressions to keep the flow self-documenting

package/docs/card-help/LOG.md

@@ -0,0 +1,23 @@
+# Log Values
+
+The **Log Values** node writes incoming data to the console or log output for debugging purposes.
+
+## Ports
+
+- **Values** (input, multi) — accepts one or more connections carrying values to log
+- **Pass** (output) — passes the last received value through unchanged
+
+## Properties
+
+- **LogLevel** — the severity level for the log entry (e.g. `info`, `warn`, `error`, `trace`)
+- **Format** — an optional format string controlling how values are serialized
+
+## Behavior
+
+When data arrives at any input connection, the node serializes the value and writes it to the configured log output at the specified log level. The data is then forwarded to the **Pass** output unchanged, so the Log Values node can be inserted inline without disrupting the flow.
+
+## Tips
+
+- Use multiple input connections to aggregate log output from parallel branches
+- Set the log level to `trace` during development and `warn` in production flows
+- Insert between any two nodes for quick inline debugging

package/docs/card-help/NOTE.md

@@ -0,0 +1,17 @@
+# Comment
+
+The **Comment** node is a floating annotation for documenting flow logic. It has no input or output ports and does not participate in data flow execution.
+
+## Usage
+
+Drop a Comment node anywhere on the canvas to add context, explain design decisions, or leave notes for collaborators. The note text is stored in the node's `Data.NoteText` property and displayed directly in the node body.
+
+## Properties
+
+- **NoteText** — the annotation content displayed in the node body
+
+## Tips
+
+- Use comments to explain complex branching logic or non-obvious configuration choices
+- Comment nodes can be freely repositioned without affecting connections
+- Group related comments near the nodes they describe

package/docs/card-help/PREV.md

@@ -0,0 +1,18 @@
+# Data Preview
+
+The **Data Preview** node displays a tabular summary of the data flowing through it. Use it as an inline debugger to inspect field names, types, and current values without interrupting the flow.
+
+## Ports
+
+- **Data** (input) — the data object to inspect
+- **Pass** (output) — passes the data through unchanged
+
+## Behavior
+
+The preview renders a compact table inside the node body showing each field's name, inferred data type, and current value. The node is pass-through: data enters on the left and exits on the right without modification.
+
+## Tips
+
+- Insert a Data Preview between two nodes to inspect intermediate state
+- The preview updates whenever new data arrives at the input port
+- Useful during development for verifying data transformations

package/docs/card-help/SET.md

@@ -0,0 +1,27 @@
+# Set Value
+
+The **Set Value** node assigns a value to a named variable in the flow context.
+
+## Ports
+
+- **In** (input) — trigger to perform the assignment
+- **Out** (output) — fires after the value has been set
+
+## Properties
+
+- **Variable Name** — the key under which the value will be stored
+- **Value Expression** — the expression to evaluate and assign
+
+## Behavior
+
+When triggered, the node evaluates the **Value Expression** and stores the result under the configured **Variable Name** in the flow context. Downstream nodes can read this value using a **Get Value** node with the same variable name.
+
+## Configuration
+
+Open the properties panel to configure the variable name and value expression using the built-in form editor.
+
+## Tips
+
+- Variable names are case-sensitive — use consistent naming conventions
+- Value expressions have access to the current flow context
+- Use Set Value at the beginning of a flow to initialize default variables

package/docs/card-help/SPKL.md

@@ -0,0 +1,22 @@
+# Sparkline
+
+The **Sparkline** node renders a live sparkline chart visualizing numeric throughput data directly in the node body.
+
+## Ports
+
+- **Values** (input) — a numeric array or stream of values to plot
+- **Stats** (output) — emits computed statistics (min, max, mean) for the data set
+
+## Behavior
+
+The node draws a compact line chart inside the node body using a canvas renderer. As new numeric data arrives at the input, the chart updates to reflect the latest values. The filled area under the line and an endpoint dot provide visual emphasis on the current value.
+
+## Appearance
+
+The chart uses the node's theme color for the line and fill area. The last data point is highlighted with a dot. The sparkline scales automatically to fit the available body area.
+
+## Tips
+
+- Connect to any node that produces a numeric array for instant visualization
+- Use alongside a Data Preview node for combined visual and tabular inspection
+- The Stats output is useful for feeding threshold values into an If-Then-Else node

package/docs/card-help/STAT.md

@@ -0,0 +1,23 @@
+# Status Monitor
+
+The **Status Monitor** node monitors the health status of upstream services and reports availability.
+
+## Ports
+
+- **Check** (input, multi) — accepts connections from one or more services to monitor
+- **Healthy** (output) — fires when all monitored services report healthy
+- **Degraded** (output) — fires when one or more services report degraded status
+
+## Behavior
+
+The node body displays a visual health grid showing the status of each monitored service with colored indicators. Green indicates a healthy service; yellow indicates degraded performance. When all services are healthy, the **Healthy** output is activated. If any service reports degraded status, the **Degraded** output fires instead.
+
+## Appearance
+
+The node body renders SVG status circles labeled with service names (e.g. API, DB, Cache, Queue). Port labels appear on hover for a cleaner default appearance.
+
+## Tips
+
+- Connect multiple services to the **Check** input to build a comprehensive health dashboard
+- Route the **Degraded** output to notification or alerting nodes
+- Combine with an Each node to check a dynamic list of service endpoints

package/docs/card-help/SW.md

@@ -0,0 +1,25 @@
+# Switch
+
+The **Switch** node routes execution to one of multiple outputs based on a matching value, similar to a switch/case statement in programming.
+
+## Ports
+
+- **In** (input) — the value to match against cases
+- **Case A** (output) — fires when the input matches case A
+- **Case B** (output) — fires when the input matches case B
+- **Default** (output) — fires when the input does not match any defined case
+
+## Behavior
+
+When a value arrives at the input, the node compares it against each configured case. The first matching case's output is activated. If no case matches, the **Default** output fires. Only one output is activated per evaluation.
+
+## Configuration
+
+Define case match values in the node's data properties. Each case corresponds to one of the named outputs.
+
+## Tips
+
+- Add more output ports by extending the card definition for additional cases
+- Use the **Default** output as a catch-all for unexpected values
+- Chain a Switch after an If-Then-Else for multi-level routing logic
+- Case matching is based on strict equality