pict-section-flow 1.3.0 → 2.0.0

package/.claude/launch.json

@@ -1,11 +0,0 @@
-{
-  "version": "0.0.1",
-  "configurations": [
-    {
-      "name": "simple-cards",
-      "runtimeExecutable": "npx",
-      "runtimeArgs": ["http-server", "example_applications/simple_cards/dist", "-p", "8085", "-c-1"],
-      "port": 8085
-    }
-  ]
-}

package/docs/Architecture.md

@@ -1,163 +0,0 @@
-# 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
-
-<!-- bespoke diagram: edit diagrams/high-level-design.mmd or .hints.json, then: npx pict-renderer-graph build modules/pict/pict-section-flow/docs -->
-![High-Level Design](diagrams/high-level-design.svg)
-
-## Data Flow
-
-All mutations flow through a predictable pipeline:
-
-<!-- bespoke diagram: edit diagrams/data-flow.mmd or .hints.json, then: npx pict-renderer-graph build modules/pict/pict-section-flow/docs -->
-![Data Flow](diagrams/data-flow.svg)
-
-## SVG Layer Structure
-
-The rendering system uses SVG group elements in a specific z-order:
-
-<!-- bespoke diagram: edit diagrams/svg-layer-structure.mmd or .hints.json, then: npx pict-renderer-graph build modules/pict/pict-section-flow/docs -->
-![SVG Layer Structure](diagrams/svg-layer-structure.svg)
-
-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:
-
-<!-- bespoke diagram: edit diagrams/service-initialization-sequence.mmd or .hints.json, then: npx pict-renderer-graph build modules/pict/pict-section-flow/docs -->
-![Service Initialization Sequence](diagrams/service-initialization-sequence.svg)
-
-## 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.

package/docs/Custom-Styling.md

@@ -1,275 +0,0 @@
-# Custom Styling
-
-The flow diagram exposes a comprehensive set of CSS custom properties (design tokens) on the `.pict-flow-container` element. Override any of these variables to theme the flow diagram without modifying source code.
-
-## Quick Start
-
-Add a `<style>` block after the flow diagram initializes, or use a theme provider:
-
-```css
-/* Override via CSS */
-.pict-flow-container {
-    --pf-canvas-bg: #1a1a2e;
-    --pf-node-body-fill: #16213e;
-    --pf-node-body-stroke: #0f3460;
-    --pf-text-primary: #e8e8e8;
-    --pf-node-selected-stroke: #e94560;
-}
-```
-
-```javascript
-// Override via the Theme Provider API
-flowView._ThemeProvider.registerTheme('dark',
-{
-    Key: 'dark',
-    Label: 'Dark Mode',
-    CSSVariables:
-    {
-        '--pf-canvas-bg': '#1a1a2e',
-        '--pf-node-body-fill': '#16213e',
-        '--pf-node-body-stroke': '#0f3460',
-        '--pf-text-primary': '#e8e8e8',
-        '--pf-node-selected-stroke': '#e94560'
-    },
-    NodeBodyMode: 'rect'
-});
-flowView.setTheme('dark');
-```
-
-## Design Token Reference
-
-All variables are prefixed `--pf-` (short for *pict-flow*) and defined on `.pict-flow-container`. Default values shown below are for the built-in Modern theme.
-
-### Text
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--pf-text-primary` | `#2c3e50` | Primary text color (labels, body text, form values) |
-| `--pf-text-heading` | `#1a252f` | Heading text (info panel headers) |
-| `--pf-text-secondary` | `#7f8c8d` | Secondary text (descriptions, field labels) |
-| `--pf-text-tertiary` | `#8e99a4` | Tertiary text (section titles, constraints) |
-| `--pf-text-placeholder` | `#95a5a6` | Placeholder/muted text (category labels, code badges) |
-
-### Node
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--pf-node-body-fill` | `#ffffff` | Node body background |
-| `--pf-node-body-stroke` | `#d0d4d8` | Node body border |
-| `--pf-node-body-stroke-hover` | `#b0b8c0` | Node body border on hover |
-| `--pf-node-body-stroke-width` | `1` | Node body border width |
-| `--pf-node-body-radius` | `8px` | Node body corner radius |
-| `--pf-node-shadow` | `drop-shadow(0 1px 3px rgba(0,0,0,0.10))` | Default node shadow |
-| `--pf-node-shadow-hover` | `drop-shadow(0 2px 6px rgba(0,0,0,0.15))` | Shadow on hover |
-| `--pf-node-shadow-selected` | `drop-shadow(0 2px 8px rgba(52,152,219,0.25))` | Shadow when selected |
-| `--pf-node-shadow-dragging` | `drop-shadow(0 4px 12px rgba(0,0,0,0.20))` | Shadow while dragging |
-| `--pf-node-title-fill` | `#ffffff` | Title text color (on the title bar) |
-| `--pf-node-title-size` | `11.5px` | Title font size |
-| `--pf-node-title-weight` | `600` | Title font weight |
-| `--pf-node-title-bar-color` | `#2c3e50` | Default title bar background color |
-| `--pf-node-type-label-fill` | `#a0a8b0` | Node type label color (appears on hover) |
-| `--pf-node-selected-stroke` | `#3498db` | Primary accent / selection stroke color |
-
-### Node Variants
-
-Built-in node types override the node body fill and stroke. Use these tokens to customize variant colors globally.
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--pf-node-start-fill` | `#eafaf1` | Start node body fill |
-| `--pf-node-start-stroke` | `#27ae60` | Start node body stroke |
-| `--pf-node-end-fill` | `#e8f8f5` | End node body fill |
-| `--pf-node-end-stroke` | `#1abc9c` | End node body stroke |
-| `--pf-node-halt-fill` | `#fdedec` | Halt/error node body fill |
-| `--pf-node-halt-stroke` | `#e74c3c` | Halt/error node body stroke |
-| `--pf-node-decision-fill` | `#fff9e6` | Decision node body fill |
-| `--pf-node-decision-stroke` | `#f39c12` | Decision node body stroke |
-
-### Ports
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--pf-port-input-fill` | `#3498db` | Input port circle fill |
-| `--pf-port-output-fill` | `#2ecc71` | Output port circle fill |
-| `--pf-port-stroke` | `#ffffff` | Port circle border color |
-| `--pf-port-stroke-width` | `2` | Port circle border width |
-| `--pf-port-label-bg` | `rgba(255,253,240,0.5)` | Port label badge background |
-| `--pf-port-label-text` | `#2c3e50` | Port label text color |
-
-### Port Type Colors
-
-When ports have a `PortType` set, these colors override the default input/output fills.
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--pf-port-event-in-fill` | `#3498db` | Event input port |
-| `--pf-port-event-out-fill` | `#2ecc71` | Event output port |
-| `--pf-port-setting-fill` | `#e67e22` | Setting port |
-| `--pf-port-value-fill` | `#f1c40f` | Value port |
-| `--pf-port-error-fill` | `#e74c3c` | Error port |
-
-### Connection Type Colors
-
-Connections inherit color from their source port type.
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--pf-connection-event-in-stroke` | `#3498db` | Event-in connection stroke |
-| `--pf-connection-event-out-stroke` | `#2ecc71` | Event-out connection stroke |
-| `--pf-connection-setting-stroke` | `#e67e22` | Setting connection stroke |
-| `--pf-connection-value-stroke` | `#f1c40f` | Value connection stroke |
-| `--pf-connection-error-stroke` | `#e74c3c` | Error connection stroke |
-
-### Connections
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--pf-connection-stroke` | `#95a5a6` | Default connection line color |
-| `--pf-connection-stroke-hover` | `#7f8c8d` | Connection line color on hover |
-| `--pf-connection-selected-stroke` | `#3498db` | Connection line color when selected |
-
-### Panels
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--pf-panel-bg` | `#ffffff` | Panel background |
-| `--pf-panel-border` | `#d0d4d8` | Panel border color |
-| `--pf-panel-radius` | `8px` | Panel corner radius |
-| `--pf-panel-shadow` | `0 4px 12px rgba(0,0,0,0.10), ...` | Panel box shadow |
-| `--pf-panel-titlebar-bg` | `#f7f8fa` | Panel title bar background |
-| `--pf-panel-titlebar-border` | `#e8eaed` | Title bar bottom border |
-| `--pf-panel-title-color` | `#2c3e50` | Panel title text color |
-
-### Tabs
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--pf-tab-text` | `#8e99a4` | Inactive tab text color |
-| `--pf-tab-text-hover` | `#5a6a7a` | Tab text color on hover |
-| `--pf-tab-active-border` | `var(--pf-node-selected-stroke)` | Active tab top border color |
-| `--pf-resize-handle-hover` | `#e0e3e6` | Panel resize handle hover color |
-
-### Forms & Inputs
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--pf-input-border` | `#d5d8dc` | Input/select border color |
-| `--pf-input-border-focus` | `#3498db` | Input border color on focus |
-| `--pf-divider-light` | `#ecf0f1` | Light divider/separator color |
-| `--pf-divider-medium` | `#e8eaed` | Medium divider/separator color |
-
-### Buttons
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--pf-button-border` | `#bdc3c7` | Button border color |
-| `--pf-button-hover-border` | `#95a5a6` | Button border color on hover |
-| `--pf-button-hover-bg` | `#ecf0f1` | Button background on hover |
-| `--pf-button-active-bg` | `#d5dbdb` | Button background on active/press |
-| `--pf-button-danger-text` | `#e74c3c` | Danger button text color |
-| `--pf-button-danger-hover-bg` | `#fdedec` | Danger button hover background |
-| `--pf-button-close-color` | `#b0b8c0` | Panel close button color |
-
-### Badges
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--pf-badge-category-bg` | `#f0f2f4` | Category badge background |
-| `--pf-badge-category-text` | `#6b7b8d` | Category badge text color |
-| `--pf-badge-code-bg` | `#eaf2f8` | Code badge background |
-| `--pf-badge-code-text` | `#2980b9` | Code badge text color |
-
-### Info Panel
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--pf-port-item-bg` | `#f8f9fa` | Port list item background |
-
-### Toolbar
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--pf-toolbar-bg` | `#ffffff` | Toolbar background |
-| `--pf-toolbar-border` | `#e0e0e0` | Toolbar border and group separators |
-
-### Palette Cards
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--pf-card-border` | `#d5d8dc` | Palette card border |
-| `--pf-card-hover-bg` | `#eaf2f8` | Palette card hover background |
-| `--pf-card-hover-shadow` | `0 1px 3px rgba(52,152,219,0.15)` | Palette card hover shadow |
-
-### Canvas
-
-| Variable | Default | Description |
-|----------|---------|-------------|
-| `--pf-canvas-bg` | `#fafafa` | Background color of the SVG canvas |
-| `--pf-grid-stroke` | `#e8e8e8` | Grid line color |
-
-## Per-Node-Type Overrides
-
-Individual node types can scope-override any variable. The flow renderer adds a CSS class `.pict-flow-node-{type}` to each node group. Target these classes to customize specific node types without affecting others:
-
-```css
-/* Make "FileRead" nodes stand out */
-.pict-flow-node-FileRead .pict-flow-node-body {
-    fill: #fef9e7;
-    stroke: #f4d03f;
-}
-```
-
-## Theme Provider API
-
-The `PictProviderFlowTheme` service manages named themes and applies them via CSS variable overrides.
-
-### Registering a Theme
-
-```javascript
-flowView._ThemeProvider.registerTheme('corporate',
-{
-    Key: 'corporate',
-    Label: 'Corporate',
-    CSSVariables:
-    {
-        '--pf-canvas-bg': '#f5f6fa',
-        '--pf-node-selected-stroke': '#0066cc',
-        '--pf-node-body-stroke': '#c8d6e5',
-        '--pf-toolbar-bg': '#ffffff',
-        '--pf-panel-titlebar-bg': '#f0f2f5'
-    },
-    NodeBodyMode: 'rect',
-    NoiseConfig: { Enabled: false }
-});
-```
-
-### Switching Themes
-
-```javascript
-flowView.setTheme('corporate');    // Apply the corporate theme
-flowView.setTheme('default');      // Restore the default Modern theme
-flowView.setTheme('sketch');       // Hand-drawn style (built-in)
-flowView.setTheme('blueprint');    // Blueprint style (built-in)
-```
-
-### Theme Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `Key` | `string` | Unique identifier for the theme |
-| `Label` | `string` | Display name |
-| `CSSVariables` | `object` | Map of `--pf-*` variable names to values |
-| `AdditionalCSS` | `string` | Extra CSS appended after variable overrides |
-| `NodeBodyMode` | `string` | Node rendering mode: `'rect'` or `'bracket'` |
-| `NoiseConfig` | `object` | Hand-drawn effect configuration |
-
-### How It Works
-
-When a theme is activated:
-
-1. The CSS provider calls `generateCSS()` which aggregates all domain CSS
-2. If an active theme defines `CSSVariables`, they are emitted as a `.pict-flow-container` override block appended after the base CSS
-3. If `AdditionalCSS` is defined, it is appended after the variable overrides
-4. The combined CSS is re-injected via the Pict `CSSMap` service
-
-This means theme variable overrides have higher specificity than the base defaults (same selector, later in source order), and `AdditionalCSS` can add entirely new rules or increase specificity where needed.

package/docs/Data_Model.md

@@ -1,149 +0,0 @@
-# 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
-
-<!-- bespoke diagram: edit diagrams/relationships.mmd or .hints.json, then: npx pict-renderer-graph build modules/pict/pict-section-flow/docs -->
-![Relationships](diagrams/relationships.svg)