@procaaso/alphinity-ui-components 1.0.2 → 1.0.4

package/IMPLEMENTATION_GUIDE.md

@@ -0,0 +1,1351 @@
+# P&ID Canvas Implementation Guide
+
+## Architecture Overview
+
+This library provides **UI primitives** for building P&ID diagram editors and runtime viewers. Your application handles **state management** and **data binding**.
+
+```
+┌─────────────────────────────────────────────┐
+│  Your Application (Engineering Mode)        │
+│  - Diagram state management                 │
+│  - Save/load from database                  │
+│  - Data stream configuration                │
+│  - User permissions                         │
+└─────────────┬───────────────────────────────┘
+              │ Props & Callbacks
+              ▼
+┌─────────────────────────────────────────────┐
+│  @procaaso/alphinity-ui-components          │
+│  - PIDCanvas (rendering & interaction)      │
+│  - Hooks (useTelemetry, useViewBox, etc.)  │
+│  - Visual components                        │
+└─────────────────────────────────────────────┘
+```
+
+---
+
+## Quick Start: Minimal Implementation
+
+### 1. Basic Viewer (Read-Only)
+
+```tsx
+import { PIDCanvas } from '@procaaso/alphinity-ui-components';
+import type { PIDDiagram } from '@procaaso/alphinity-ui-components';
+
+function DiagramViewer({ diagram }: { diagram: PIDDiagram }) {
+  return (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <PIDCanvas
+        diagram={diagram}
+        features={{
+          pan: true,
+          zoom: true,
+          selection: false,
+          telemetry: false,
+        }}
+      />
+    </div>
+  );
+}
+```
+
+### 2. Interactive Editor
+
+```tsx
+import { PIDCanvas, SymbolLibrary } from '@procaaso/alphinity-ui-components';
+import { useState } from 'react';
+import type { PIDDiagram, NodeInstance, PipeEdge } from '@procaaso/alphinity-ui-components';
+
+function DiagramEditor() {
+  const [diagram, setDiagram] = useState<PIDDiagram>({
+    nodes: [],
+    pipes: [],
+    viewBox: { x: 0, y: 0, width: 2000, height: 1500 },
+  });
+
+  const handleSymbolDrop = (symbolId: string, position: { x: number; y: number }) => {
+    const newNode: NodeInstance = {
+      id: `node-${Date.now()}`,
+      symbolId,
+      transform: { x: position.x, y: position.y, rotation: 0 },
+      label: symbolId,
+    };
+
+    setDiagram((prev) => ({
+      ...prev,
+      nodes: [...prev.nodes, newNode],
+    }));
+  };
+
+  const handlePipeCreated = (
+    sourceId: string,
+    targetId: string,
+    sourcePort?: string,
+    targetPort?: string
+  ) => {
+    const newPipe: PipeEdge = {
+      id: `pipe-${Date.now()}`,
+      fromNodeId: sourceId,
+      toNodeId: targetId,
+      fromPortId: sourcePort,
+      toPortId: targetPort,
+      routePoints: [], // Will be calculated by library
+    };
+
+    setDiagram((prev) => ({
+      ...prev,
+      pipes: [...prev.pipes, newPipe],
+    }));
+  };
+
+  const handleDelete = (nodeIds: string[], pipeIds: string[]) => {
+    setDiagram((prev) => ({
+      ...prev,
+      nodes: prev.nodes.filter((n) => !nodeIds.includes(n.id)),
+      pipes: prev.pipes.filter((p) => !pipeIds.includes(p.id)),
+    }));
+  };
+
+  return (
+    <div style={{ display: 'flex', height: '100vh' }}>
+      {/* Symbol Library */}
+      <SymbolLibrary onSymbolDragEnd={handleSymbolDrop} />
+
+      {/* Canvas */}
+      <div style={{ flex: 1 }}>
+        <PIDCanvas
+          diagram={diagram}
+          features={{
+            pan: true,
+            zoom: true,
+            selection: true,
+            dragNodes: true,
+            keyboardShortcuts: true,
+            connectionMode: true,
+            allowSymbolDrop: true,
+          }}
+          onSymbolDrop={handleSymbolDrop}
+          onPipeCreated={handlePipeCreated}
+          onDiagramChange={setDiagram}
+          onDelete={handleDelete}
+        />
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## Adding Custom SVG Symbols
+
+The library comes with a basic set of P&ID symbols, but you can easily add your own. Symbols are static SVG definitions that can be reused across diagrams.
+
+### Symbol Structure
+
+Each symbol is defined by the `SymbolDefinition` interface:
+
+```typescript
+import type { SymbolDefinition } from '@procaaso/alphinity-ui-components';
+
+const mySymbol: SymbolDefinition = {
+  id: 'tank-vertical', // Unique identifier
+  name: 'Vertical Tank', // Display name
+  category: 'vessel', // Category for grouping
+  viewBox: { x: 0, y: 0, width: 60, height: 100 }, // SVG coordinate space
+  ports: [
+    // Connection points for pipes
+    { id: 'inlet', x: 30, y: 0, type: 'inlet', direction: 'in' },
+    { id: 'outlet', x: 30, y: 100, type: 'outlet', direction: 'out' },
+  ],
+  svgContent: `                   // SVG markup (inline as string)
+    <g>
+      <rect x="10" y="10" width="40" height="80" 
+            fill="#b0bec5" stroke="#546e7a" stroke-width="2"/>
+      <line x1="30" y1="0" x2="30" y2="10" 
+            stroke="#546e7a" stroke-width="3"/>
+      <line x1="30" y1="90" x2="30" y2="100" 
+            stroke="#546e7a" stroke-width="3"/>
+    </g>
+  `,
+  metadata: {
+    // Optional metadata
+    description: 'Vertical storage tank',
+    tags: ['tank', 'vessel', 'storage'],
+  },
+};
+```
+
+### Method 1: Extend the Built-in Library
+
+Create a custom symbol library file in your app:
+
+```typescript
+// src/symbols/customSymbols.ts
+import type { SymbolDefinition } from '@procaaso/alphinity-ui-components';
+import { mockSymbolLibrary } from '@procaaso/alphinity-ui-components';
+
+export const customSymbols: Record<string, SymbolDefinition> = {
+  ...mockSymbolLibrary, // Include built-in symbols
+
+  'tank-vertical': {
+    id: 'tank-vertical',
+    name: 'Vertical Tank',
+    category: 'vessel',
+    viewBox: { x: 0, y: 0, width: 60, height: 100 },
+    ports: [
+      { id: 'inlet', x: 30, y: 0, type: 'inlet', direction: 'in' },
+      { id: 'outlet', x: 30, y: 100, type: 'outlet', direction: 'out' },
+      { id: 'drain', x: 50, y: 100, type: 'outlet', direction: 'out' },
+    ],
+    svgContent: `
+      <g>
+        <!-- Tank body -->
+        <rect x="10" y="10" width="40" height="80" 
+              fill="#b0bec5" stroke="#546e7a" stroke-width="2" rx="2"/>
+        <!-- Inlet pipe -->
+        <line x1="30" y1="0" x2="30" y2="10" 
+              stroke="#546e7a" stroke-width="3" stroke-linecap="round"/>
+        <!-- Outlet pipe -->
+        <line x1="30" y1="90" x2="30" y2="100" 
+              stroke="#546e7a" stroke-width="3" stroke-linecap="round"/>
+        <!-- Drain pipe -->
+        <line x1="50" y1="90" x2="50" y2="100" 
+              stroke="#546e7a" stroke-width="2" stroke-linecap="round"/>
+        <!-- Level indicator -->
+        <line x1="12" y1="50" x2="48" y2="50" 
+              stroke="#0277bd" stroke-width="1" stroke-dasharray="2,2"/>
+      </g>
+    `,
+    metadata: {
+      description: 'Vertical storage tank with drain',
+      tags: ['tank', 'vessel', 'storage'],
+    },
+  },
+
+  'motor-electric': {
+    id: 'motor-electric',
+    name: 'Electric Motor',
+    category: 'actuator',
+    viewBox: { x: 0, y: 0, width: 50, height: 50 },
+    ports: [{ id: 'shaft', x: 25, y: 0, type: 'outlet', direction: 'out' }],
+    svgContent: `
+      <g>
+        <!-- Motor housing -->
+        <circle cx="25" cy="25" r="20" 
+                fill="#546e7a" stroke="#263238" stroke-width="2"/>
+        <!-- M label -->
+        <text x="25" y="32" text-anchor="middle" 
+              font-size="20" font-weight="bold" fill="#ffffff">M</text>
+        <!-- Shaft -->
+        <line x1="25" y1="0" x2="25" y2="5" 
+              stroke="#263238" stroke-width="3" stroke-linecap="round"/>
+      </g>
+    `,
+  },
+};
+
+// Helper to get symbols
+export function getCustomSymbol(id: string): SymbolDefinition | undefined {
+  return customSymbols[id];
+}
+```
+
+Then use your custom library in components:
+
+```tsx
+import { SymbolLibrary } from '@procaaso/alphinity-ui-components';
+import { customSymbols } from './symbols/customSymbols';
+
+function App() {
+  return (
+    <SymbolLibrary symbols={Object.values(customSymbols)} onSymbolDragEnd={handleSymbolDrop} />
+  );
+}
+```
+
+### Method 2: Import from SVG Files
+
+If you have existing SVG files, extract the content:
+
+```typescript
+// symbols/fromSvgFile.ts
+export const valveFromFile: SymbolDefinition = {
+  id: 'valve-butterfly',
+  name: 'Butterfly Valve',
+  category: 'valve',
+  viewBox: { x: 0, y: 0, width: 60, height: 40 },
+  ports: [
+    { id: 'inlet', x: 0, y: 20, type: 'inlet', direction: 'in' },
+    { id: 'outlet', x: 60, y: 20, type: 'outlet', direction: 'out' },
+  ],
+  // Copy/paste the SVG content from your .svg file
+  // Remove the <svg> wrapper and any <?xml> declarations
+  svgContent: `
+    <g>
+      <!-- Paste SVG content here -->
+      <path d="M 10 10 L 50 30 L 10 50 Z" fill="#ccc" stroke="#333" stroke-width="2"/>
+    </g>
+  `,
+};
+```
+
+**From diagrams.net/draw.io exports:**
+
+1. Export as SVG
+2. Open in text editor
+3. Copy everything between `<svg>...</svg>`
+4. Remove `<svg>` tags, keep inner `<g>` content
+5. Paste into `svgContent`
+
+### Method 3: Database-Backed Symbols
+
+For enterprise apps, store symbols in a database:
+
+```typescript
+// api/symbols.ts
+export async function loadSymbolLibrary(): Promise<Record<string, SymbolDefinition>> {
+  const response = await fetch('/api/symbols');
+  const symbols = await response.json();
+
+  return symbols.reduce((acc, symbol) => {
+    acc[symbol.id] = symbol;
+    return acc;
+  }, {});
+}
+
+// Usage in app
+function App() {
+  const [symbols, setSymbols] = useState<Record<string, SymbolDefinition>>({});
+
+  useEffect(() => {
+    loadSymbolLibrary().then(setSymbols);
+  }, []);
+
+  return <SymbolLibrary symbols={Object.values(symbols)} />;
+}
+```
+
+### Port Positioning Rules
+
+Ports define where pipes connect to symbols:
+
+```typescript
+ports: [
+  {
+    id: 'inlet', // Unique within this symbol
+    x: 0, // X coordinate in viewBox space
+    y: 25, // Y coordinate in viewBox space
+    type: 'inlet', // Type (inlet, outlet, or custom)
+    direction: 'in', // Optional: flow direction hint
+  },
+];
+```
+
+**Key points:**
+
+- Coordinates are relative to `viewBox` origin (top-left)
+- Ports at edges should be at `x: 0`, `x: width`, `y: 0`, or `y: height`
+- Multiple ports are supported (manifolds, 3-way valves, etc.)
+- Port types are informational only - library doesn't enforce flow direction
+
+**Example multi-port symbol:**
+
+```typescript
+{
+  id: 'valve-3way',
+  viewBox: { x: 0, y: 0, width: 60, height: 60 },
+  ports: [
+    { id: 'inlet', x: 0, y: 30, type: 'inlet' },
+    { id: 'outlet-1', x: 60, y: 20, type: 'outlet' },
+    { id: 'outlet-2', x: 60, y: 40, type: 'outlet' },
+  ],
+  // SVG content...
+}
+```
+
+### SVG Styling Best Practices
+
+**Use inline styles for portability:**
+
+```svg
+<!-- ✅ GOOD - Inline attributes -->
+<rect fill="#546e7a" stroke="#263238" stroke-width="2"/>
+
+<!-- ❌ BAD - CSS classes (won't work) -->
+<rect class="tank-body"/>
+```
+
+**Keep colors consistent:**
+
+```typescript
+// Standard industrial colors
+const COLORS = {
+  steel: '#546e7a', // Equipment bodies
+  pipe: '#263238', // Pipes and connections
+  fluid: '#0277bd', // Liquid indicators
+  actuator: '#f57c00', // Actuators/motors
+  alarm: '#d32f2f', // Alarms/warnings
+};
+```
+
+**Optimize for zoom:**
+
+- Use `stroke-width: 2` or higher (visible when zoomed out)
+- Avoid text unless it's large (16px+)
+- Use simple shapes (better performance)
+
+### Testing New Symbols
+
+Add to the demo to preview:
+
+```tsx
+// demo/RuntimeDemo.tsx
+import { customSymbols } from '../src/symbols/customSymbols';
+
+// Test your symbol
+const testDiagram = {
+  nodes: [
+    {
+      id: 'test-1',
+      symbolId: 'tank-vertical', // Your custom symbol
+      transform: { x: 100, y: 100, rotation: 0 },
+    },
+  ],
+  pipes: [],
+  viewBox: { x: 0, y: 0, width: 2000, height: 1500 },
+};
+```
+
+---
+
+## Production Implementation Pattern
+
+### Application Structure
+
+```
+your-app/
+├── src/
+│   ├── features/
+│   │   ├── engineering-mode/      # Edit mode
+│   │   │   ├── DiagramEditor.tsx
+│   │   │   ├── DataStreamConfig.tsx
+│   │   │   └── useEngineeringMode.ts
+│   │   ├── runtime-mode/          # HMI viewer
+│   │   │   ├── RuntimeViewer.tsx
+│   │   │   ├── TelemetryBinding.tsx
+│   │   │   └── useDataStreams.ts
+│   │   └── persistence/
+│   │       ├── useDiagramStorage.ts
+│   │       └── api.ts
+│   └── components/
+│       └── DiagramWorkspace.tsx   # Mode switcher
+```
+
+### State Management Hook
+
+```tsx
+// features/persistence/useDiagramStorage.ts
+import { useState, useEffect } from 'react';
+import type { PIDDiagram } from '@procaaso/alphinity-ui-components';
+
+export function useDiagramStorage(diagramId: string) {
+  const [diagram, setDiagram] = useState<PIDDiagram | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [saving, setSaving] = useState(false);
+
+  // Load from database
+  useEffect(() => {
+    async function load() {
+      const response = await fetch(`/api/diagrams/${diagramId}`);
+      const data = await response.json();
+      setDiagram(data);
+      setLoading(false);
+    }
+    load();
+  }, [diagramId]);
+
+  // Save to database (debounced)
+  const saveDiagram = async (updated: PIDDiagram) => {
+    setDiagram(updated);
+    setSaving(true);
+
+    try {
+      await fetch(`/api/diagrams/${diagramId}`, {
+        method: 'PUT',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(updated),
+      });
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return { diagram, loading, saving, saveDiagram };
+}
+```
+
+### Engineering Mode (Edit)
+
+```tsx
+// features/engineering-mode/DiagramEditor.tsx
+import { PIDCanvas, SymbolLibrary } from '@procaaso/alphinity-ui-components';
+import { useDiagramStorage } from '../persistence/useDiagramStorage';
+import { DataStreamConfig } from './DataStreamConfig';
+
+export function DiagramEditor({ diagramId }: { diagramId: string }) {
+  const { diagram, loading, saveDiagram } = useDiagramStorage(diagramId);
+  const [selectedNodeId, setSelectedNodeId] = useState<string | null>(null);
+
+  if (loading || !diagram) return <div>Loading...</div>;
+
+  return (
+    <div style={{ display: 'flex', height: '100vh' }}>
+      {/* Left: Symbol Library */}
+      <div style={{ width: 250, borderRight: '1px solid #ccc' }}>
+        <SymbolLibrary
+          onSymbolDragEnd={(symbolId, x, y) => {
+            // Add node to diagram
+            const newNode = {
+              id: `node-${Date.now()}`,
+              symbolId,
+              transform: { x, y, rotation: 0 },
+            };
+            saveDiagram({
+              ...diagram,
+              nodes: [...diagram.nodes, newNode],
+            });
+          }}
+        />
+      </div>
+
+      {/* Center: Canvas */}
+      <div style={{ flex: 1 }}>
+        <PIDCanvas
+          diagram={diagram}
+          features={{
+            selection: true,
+            dragNodes: true,
+            connectionMode: true,
+            keyboardShortcuts: true,
+            allowSymbolDrop: true,
+          }}
+          onNodeClick={setSelectedNodeId}
+          onDiagramChange={saveDiagram}
+          onDelete={(nodeIds, pipeIds) => {
+            saveDiagram({
+              ...diagram,
+              nodes: diagram.nodes.filter((n) => !nodeIds.includes(n.id)),
+              pipes: diagram.pipes.filter((p) => !pipeIds.includes(p.id)),
+            });
+          }}
+        />
+      </div>
+
+      {/* Right: Configuration Panel */}
+      <div style={{ width: 300, borderLeft: '1px solid #ccc' }}>
+        {selectedNodeId && (
+          <DataStreamConfig nodeId={selectedNodeId} diagram={diagram} onUpdate={saveDiagram} />
+        )}
+      </div>
+    </div>
+  );
+}
+```
+
+### Data Stream Configuration
+
+```tsx
+// features/engineering-mode/DataStreamConfig.tsx
+import { useState } from 'react';
+import type { PIDDiagram } from '@procaaso/alphinity-ui-components';
+
+export function DataStreamConfig({
+  nodeId,
+  diagram,
+  onUpdate,
+}: {
+  nodeId: string;
+  diagram: PIDDiagram;
+  onUpdate: (diagram: PIDDiagram) => void;
+}) {
+  const node = diagram.nodes.find((n) => n.id === nodeId);
+  const [dataSource, setDataSource] = useState('');
+
+  const handleBindData = () => {
+    // Store data binding metadata on the node
+    const updatedNodes = diagram.nodes.map((n) =>
+      n.id === nodeId
+        ? {
+            ...n,
+            metadata: {
+              ...n.metadata,
+              dataSource,
+              dataType: 'temperature',
+              unit: '°F',
+            },
+          }
+        : n
+    );
+
+    onUpdate({ ...diagram, nodes: updatedNodes });
+  };
+
+  return (
+    <div style={{ padding: 16 }}>
+      <h3>Data Stream Configuration</h3>
+      <p>Node: {node?.label || nodeId}</p>
+
+      <label>
+        Data Source (Tag ID):
+        <input
+          type="text"
+          value={dataSource}
+          onChange={(e) => setDataSource(e.target.value)}
+          placeholder="e.g., PLC1.Tank01.Temp"
+        />
+      </label>
+
+      <button onClick={handleBindData}>Bind Data Stream</button>
+
+      <div style={{ marginTop: 20 }}>
+        <h4>Current Bindings:</h4>
+        <pre>{JSON.stringify(node?.metadata, null, 2)}</pre>
+      </div>
+    </div>
+  );
+}
+```
+
+### Runtime Mode (HMI Viewer)
+
+```tsx
+// features/runtime-mode/RuntimeViewer.tsx
+import { PIDCanvas } from '@procaaso/alphinity-ui-components';
+import { useDiagramStorage } from '../persistence/useDiagramStorage';
+import { useDataStreams } from './useDataStreams';
+
+export function RuntimeViewer({ diagramId }: { diagramId: string }) {
+  const { diagram, loading } = useDiagramStorage(diagramId);
+
+  // Connect to real-time data (WebSocket, MQTT, OPC UA, etc.)
+  const telemetry = useDataStreams(diagram?.nodes || []);
+
+  if (loading || !diagram) return <div>Loading...</div>;
+
+  return (
+    <div style={{ width: '100%', height: '100vh' }}>
+      <PIDCanvas
+        diagram={diagram}
+        features={{
+          pan: true,
+          zoom: true,
+          telemetry: true,
+        }}
+        telemetry={telemetry}
+      />
+    </div>
+  );
+}
+```
+
+### Real-Time Data Hook
+
+```tsx
+// features/runtime-mode/useDataStreams.ts
+import { useState, useEffect } from 'react';
+import type {
+  NodeInstance,
+  TelemetryMap,
+  TelemetryBinding,
+} from '@procaaso/alphinity-ui-components';
+
+export function useDataStreams(nodes: NodeInstance[]): TelemetryMap {
+  const [telemetry, setTelemetry] = useState<TelemetryMap>(new Map());
+
+  useEffect(() => {
+    // Example: Connect to WebSocket
+    const ws = new WebSocket('wss://your-scada-server/data');
+
+    ws.onmessage = (event) => {
+      const update = JSON.parse(event.data);
+
+      // Match incoming data to nodes
+      const updatedTelemetry = new Map(telemetry);
+
+      nodes.forEach((node) => {
+        const dataSource = node.metadata?.dataSource;
+        if (dataSource && update[dataSource]) {
+          const binding: TelemetryBinding = {
+            nodeId: node.id,
+            tagId: dataSource,
+            value: update[dataSource].value,
+            timestamp: new Date(update[dataSource].timestamp),
+            quality: update[dataSource].quality || 'good',
+            unit: node.metadata?.unit || '',
+            display: {
+              label: node.label || dataSource,
+              valueColor: '#ffffff',
+            },
+          };
+          updatedTelemetry.set(node.id, binding);
+        }
+      });
+
+      setTelemetry(updatedTelemetry);
+    };
+
+    return () => ws.close();
+  }, [nodes]);
+
+  return telemetry;
+}
+```
+
+---
+
+## Layout & Sizing
+
+### Container Requirements
+
+**PIDCanvas requires a sized container**. It uses `width: 100%` and `height: 100%` internally, so the parent must have explicit dimensions:
+
+```tsx
+// ✅ GOOD - Parent has explicit height
+<div style={{ width: '100%', height: '100vh' }}>
+  <PIDCanvas diagram={diagram} />
+</div>
+
+// ✅ GOOD - Flexbox with flex: 1
+<div style={{ display: 'flex', height: '100vh' }}>
+  <Sidebar />
+  <div style={{ flex: 1 }}>
+    <PIDCanvas diagram={diagram} />
+  </div>
+</div>
+
+// ❌ BAD - Parent has no height
+<div>
+  <PIDCanvas diagram={diagram} /> {/* Will collapse to 0 height */}
+</div>
+```
+
+### ViewBox Coordinates
+
+The `viewBox` defines the world coordinate system (in SVG units), independent of pixel dimensions:
+
+```tsx
+diagram.viewBox = { x: 0, y: 0, width: 2000, height: 1500 };
+// Node at { x: 1000, y: 750 } is at the center
+// Works on any screen size (mobile, desktop, ultrawide)
+```
+
+**Key Points:**
+
+- Node positions (transform.x/y) are in viewBox units, not pixels
+- Pan/zoom modifies the viewBox, not node positions
+- Grid spacing (25 units) scales with zoom level
+- Use consistent viewBox dimensions across diagrams for predictable spacing
+
+### Aspect Ratio Preservation
+
+PIDCanvas uses `preserveAspectRatio="xMidYMid meet"`:
+
+- Content is centered and scaled to fit
+- Maintains aspect ratio (no distortion)
+- May add letterboxing (top/bottom) or pillarboxing (sides) on ultra-wide/tall displays
+
+This is handled automatically - coordinate transformation accounts for it.
+
+### Performance Considerations
+
+**Large Diagrams (100+ nodes):**
+
+- Each node/pipe is a separate SVG element (good for interactivity)
+- Port indicators render for all nodes in connection mode
+- Consider implementing viewport culling if needed (future enhancement)
+
+**High-Frequency Telemetry Updates:**
+
+- Use `useTelemetry` hook with batched updates
+- Debounce incoming data streams (max 1-2 updates/sec per node)
+- DataOverlay components re-render only when their telemetry changes
+
+---
+
+## Recommended Patterns (From Demo)
+
+These patterns from `RuntimeDemo.tsx` represent best practices for production implementations:
+
+### 1. Edit/Runtime Mode Switching
+
+```tsx
+function DiagramWorkspace({ diagramId }: { diagramId: string }) {
+  const [mode, setMode] = useState<'edit' | 'runtime'>('edit');
+  const { diagram, saveDiagram } = useDiagramStorage(diagramId);
+
+  return (
+    <div style={{ display: 'flex', flexDirection: 'column', height: '100vh' }}>
+      {/* Mode Toggle */}
+      <header style={{ padding: 10, borderBottom: '1px solid #ccc' }}>
+        <button onClick={() => setMode('edit')}>Edit Mode</button>
+        <button onClick={() => setMode('runtime')}>Runtime Mode</button>
+      </header>
+
+      {/* Canvas with mode-specific features */}
+      <div style={{ flex: 1, display: 'flex' }}>
+        {mode === 'edit' && <SymbolLibrary />}
+
+        <div style={{ flex: 1 }}>
+          <PIDCanvas
+            diagram={diagram}
+            features={{
+              // Edit features
+              selection: mode === 'edit',
+              dragNodes: mode === 'edit',
+              connectionMode: mode === 'edit',
+              keyboardShortcuts: mode === 'edit',
+              allowSymbolDrop: mode === 'edit',
+              editPipeRoutes: mode === 'edit',
+
+              // Runtime features
+              telemetry: mode === 'runtime',
+
+              // Always enabled
+              pan: true,
+              zoom: true,
+            }}
+            onDiagramChange={mode === 'edit' ? saveDiagram : undefined}
+            telemetry={mode === 'runtime' ? telemetry : undefined}
+          />
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+**Why this pattern:**
+
+- Clear separation of concerns (editing vs monitoring)
+- Prevents accidental edits in production HMI
+- Features are explicitly tied to user role/mode
+
+### 2. Connection Mode with Visual Port Selection
+
+```tsx
+const [connectionMode, setConnectionMode] = useState(false);
+
+<PIDCanvas
+  features={{
+    connectionMode: connectionMode && mode === 'edit',
+    // Disable other interactions during connection
+    selection: !connectionMode && mode === 'edit',
+    dragNodes: !connectionMode && mode === 'edit',
+  }}
+  onPipeCreated={(sourceId, targetId, sourcePort, targetPort) => {
+    const newPipe = {
+      id: `pipe-${Date.now()}`,
+      fromNodeId: sourceId,
+      toNodeId: targetId,
+      fromPortId: sourcePort, // User-selected port
+      toPortId: targetPort, // User-selected port
+      routePoints: [],
+    };
+    saveDiagram({ ...diagram, pipes: [...diagram.pipes, newPipe] });
+    setConnectionMode(false);
+  }}
+/>;
+
+{
+  /* Connection Mode Toggle */
+}
+<button onClick={() => setConnectionMode(!connectionMode)}>
+  {connectionMode ? 'Cancel Connection' : 'Connect Nodes'}
+</button>;
+```
+
+**Why this pattern:**
+
+- User has full control over which ports connect
+- Visual feedback (port circles, rubber-band line)
+- No directional enforcement (any port → any port)
+- Works with node rotation (ports move with transforms)
+
+### 3. Auto-Save with Diagram Changes
+
+```tsx
+const debouncedSave = useDebouncedCallback(
+  (diagram: PIDDiagram) => {
+    fetch(`/api/diagrams/${diagramId}`, {
+      method: 'PUT',
+      body: JSON.stringify(diagram),
+    });
+  },
+  1000 // Save 1 second after last change
+);
+
+<PIDCanvas
+  onDiagramChange={debouncedSave}
+  onNodeMove={debouncedSave}
+  // Other callbacks also trigger auto-save
+/>;
+```
+
+**Why this pattern:**
+
+- No manual "Save" button needed
+- Prevents data loss from browser crashes
+- Debouncing prevents excessive API calls during drag operations
+
+### 4. Three-Panel Layout (Symbol Library + Canvas + Config)
+
+```tsx
+<div style={{ display: 'flex', height: '100vh' }}>
+  {/* Left: Symbol Library */}
+  <div style={{ width: 250, borderRight: '1px solid #ccc', overflowY: 'auto' }}>
+    <SymbolLibrary onSymbolDragEnd={handleSymbolDrop} />
+  </div>
+
+  {/* Center: Canvas */}
+  <div style={{ flex: 1, position: 'relative' }}>
+    <PIDCanvas
+      diagram={diagram}
+      onNodeClick={setSelectedNodeId}
+      // ... other props
+    />
+
+    {/* Connection mode toggle overlay */}
+    {mode === 'edit' && (
+      <button
+        style={{ position: 'absolute', top: 20, left: 20 }}
+        onClick={() => setConnectionMode(!connectionMode)}
+      >
+        {connectionMode ? '✖ Cancel' : '🔗 Connect'}
+      </button>
+    )}
+  </div>
+
+  {/* Right: Configuration Panel */}
+  {selectedNodeId && (
+    <div style={{ width: 300, borderLeft: '1px solid #ccc', padding: 16 }}>
+      <NodeConfigPanel nodeId={selectedNodeId} diagram={diagram} onUpdate={saveDiagram} />
+    </div>
+  )}
+</div>
+```
+
+**Why this pattern:**
+
+- Familiar CAD/drawing tool UX
+- Symbol library always accessible
+- Configuration panel appears when node selected
+- Canvas takes remaining space (responsive)
+
+### 5. Keyboard Shortcuts
+
+```tsx
+<PIDCanvas
+  features={{
+    keyboardShortcuts: mode === 'edit',
+  }}
+  onDelete={(nodeIds, pipeIds) => {
+    const updatedDiagram = {
+      ...diagram,
+      nodes: diagram.nodes.filter((n) => !nodeIds.includes(n.id)),
+      pipes: diagram.pipes.filter((p) => !pipeIds.includes(p.id)),
+    };
+    saveDiagram(updatedDiagram);
+  }}
+/>
+```
+
+**Built-in shortcuts when enabled:**
+
+- `Delete` - Remove selected nodes/pipes
+- `Ctrl+C` - Copy selection (calls `onItemsCopied`)
+- `Ctrl+V` - Paste (calls `onPaste`)
+
+**Why this pattern:**
+
+- Industry-standard shortcuts
+- Opt-in (disabled in runtime mode)
+- You implement the actual copy/paste logic
+
+### 6. Port-Based Routing (No Direction Enforcement)
+
+```tsx
+// Library auto-calculates route between any two ports
+onPipeCreated={(sourceId, targetId, sourcePort, targetPort) => {
+  // sourcePort and targetPort can be any port (inlet, outlet, or custom)
+  // Library doesn't enforce "outlet → inlet" direction
+  const pipe = {
+    fromNodeId: sourceId,
+    toNodeId: targetId,
+    fromPortId: sourcePort || 'outlet', // Fallback to default if not specified
+    toPortId: targetPort || 'inlet',
+    routePoints: [], // Library calculates orthogonal routing
+  };
+  // ...
+}
+```
+
+**Why this pattern:**
+
+- Supports non-standard connections (recirculation loops, bypass lines)
+- Works with rotated nodes (ports maintain correct positions)
+- Users can rotate nodes after connecting without breaking pipes
+- Future-proof for multi-port symbols (3-way valves, manifolds)
+
+---
+
+## Best Practices
+
+### 1. Separate Edit and Runtime Modes
+
+**Don't** enable interactive features in runtime mode:
+
+```tsx
+// ❌ BAD - allows editing in production HMI
+<PIDCanvas features={{ selection: true, dragNodes: true }} />
+```
+
+**Do** use role-based feature flags:
+
+```tsx
+// ✅ GOOD - features based on user role
+<PIDCanvas
+  features={{
+    selection: user.role === 'engineer',
+    dragNodes: user.role === 'engineer',
+    telemetry: mode === 'runtime',
+  }}
+/>
+```
+
+### 2. Store Data Bindings as Metadata
+
+```tsx
+// Store on node.metadata (not in telemetry)
+const node: NodeInstance = {
+  id: 'tank-01',
+  symbolId: 'tank-vertical',
+  transform: { x: 100, y: 100, rotation: 0 },
+  metadata: {
+    // Your application data
+    dataSource: 'PLC1.TK001.Level',
+    unit: '%',
+    alarmHigh: 95,
+    alarmLow: 10,
+  },
+};
+```
+
+### 3. Lazy Load Diagrams
+
+```tsx
+// Don't load all diagrams at once
+const diagrams = await fetch('/api/diagrams?summary=true');
+
+// Load full diagram when needed
+const fullDiagram = await fetch(`/api/diagrams/${id}`);
+```
+
+### 4. Debounce Saves
+
+````tsx
+import { useDebouncedCallback } from 'use-debounce';
+
+const debouncedSave = useDebouncedCallback((diagram) => {
+  saveDiagram(diagram);
+### 4. Debounce Saves
+
+```tsx
+import { useDebouncedCallback } from 'use-debounce';
+
+const debouncedSave = useDebouncedCallback((diagram) => {
+  saveDiagram(diagram);
+}, 1000);
+````
+
+### 5. Handle Connection Mode State
+
+When connection mode is active, disable conflicting features:
+
+```tsx
+const features = {
+  selection: mode === 'edit' && !connectionMode,
+  dragNodes: mode === 'edit' && !connectionMode,
+  connectionMode: mode === 'edit' && connectionMode,
+  editPipeRoutes: mode === 'edit' && !connectionMode,
+};
+```
+
+**Why:** Prevents confusing UX where user tries to drag nodes while connecting pipes.
+
+### 6. Use Absolute Positioning for Overlays
+
+```tsx
+{
+  /* Connection mode button */
+}
+<button
+  style={{
+    position: 'absolute',
+    top: 20,
+    left: 20,
+    zIndex: 10,
+  }}
+  onClick={() => setConnectionMode(!connectionMode)}
+>
+  {connectionMode ? '✖ Cancel Connection' : '🔗 Connect Nodes'}
+</button>;
+```
+
+**Why:** Keeps controls accessible without interfering with canvas pan/zoom.
+
+---
+
+## Common Gotchas
+
+### 1. Container Height Collapsing
+
+**Problem:** Canvas doesn't appear or has 0 height.
+
+**Solution:** Ensure parent has explicit height:
+
+```tsx
+// Add height: '100vh' to root container
+<div style={{ height: '100vh' }}>
+  <PIDCanvas ... />
+</div>
+```
+
+### 2. Node Positions After Zoom
+
+**Problem:** Dropped symbols appear at wrong location when zoomed.
+
+**Solution:** Already handled! `screenToWorld()` accounts for viewBox and aspect ratio. Just use:
+
+```tsx
+onSymbolDrop={(symbolId, position) => {
+  // position.x/y are already in world coordinates
+  const node = { transform: { x: position.x, y: position.y } };
+}}
+```
+
+### 3. Port Indicators Not Visible at Low Zoom
+
+**Problem:** Port circles (5px radius) become tiny when zoomed out.
+
+**Solution:** Indicators are SVG elements that scale with zoom. If needed, adjust radius:
+
+```tsx
+// Port indicators are sized in world units, not pixels
+// At viewBox scale 1:1, radius 5 = 5 screen pixels
+// At 50% zoom, radius 5 = 2.5 screen pixels
+```
+
+For zoom-independent sizing, consider adding a feature request for screen-space indicators.
+
+### 4. Pipe Routes Not Updating After Node Rotation
+
+**Problem:** Rotating a node doesn't update connected pipe endpoints.
+
+**Solution:** Call `onDiagramChange` or manually recalculate routes:
+
+```tsx
+import { generateRoutePoints } from '@procaaso/alphinity-ui-components';
+
+const updatedPipes = diagram.pipes.map((pipe) => {
+  const source = diagram.nodes.find((n) => n.id === pipe.fromNodeId);
+  const target = diagram.nodes.find((n) => n.id === pipe.toNodeId);
+
+  return {
+    ...pipe,
+    routePoints: generateRoutePoints(source, pipe.fromPortId, target, pipe.toPortId),
+  };
+});
+```
+
+Library auto-handles this for node dragging, but not for rotation (yet).
+
+### 5. Telemetry Updates Causing Performance Issues
+
+**Problem:** WebSocket sends 100 updates/second, UI lags.
+
+**Solution:** Throttle updates in your data hook:
+
+```tsx
+import { throttle } from 'lodash';
+
+const updateTelemetry = throttle((data) => {
+  setTelemetry(data);
+}, 500); // Max 2 updates/second
+```
+
+### 6. Multiple Connection Mode Buttons
+
+**Problem:** User clicks "Connect" again while already connecting.
+
+**Solution:** Show different UI states:
+
+```tsx
+<button
+  onClick={() => setConnectionMode(!connectionMode)}
+  style={{
+    backgroundColor: connectionMode ? '#ef4444' : '#3b82f6',
+  }}
+>
+  {connectionMode ? '✖ Cancel Connection' : '🔗 Connect Nodes'}
+</button>;
+
+{
+  connectionMode && <p style={{ marginTop: 8 }}>Click first node to start connection...</p>;
+}
+```
+
+---
+
+## Migration from Demo
+
+```typescript
+// Example Express.js routes
+app.get('/api/diagrams/:id', async (req, res) => {
+  const diagram = await db.diagrams.findById(req.params.id);
+  res.json(diagram);
+});
+
+app.put('/api/diagrams/:id', async (req, res) => {
+  const diagram = req.body;
+  await db.diagrams.update(req.params.id, diagram);
+  res.json({ success: true });
+});
+
+// WebSocket for real-time data
+wss.on('connection', (ws) => {
+  const interval = setInterval(() => {
+    // Fetch latest values from SCADA/PLC
+    const data = {
+      'PLC1.Tank01.Temp': { value: 72.5, timestamp: new Date(), quality: 'good' },
+      'PLC1.Tank01.Level': { value: 45.2, timestamp: new Date(), quality: 'good' },
+    };
+    ws.send(JSON.stringify(data));
+  }, 1000);
+
+  ws.on('close', () => clearInterval(interval));
+});
+```
+
+---
+
+## API Backend Example
+
+```typescript
+// Example Express.js routes
+app.get('/api/diagrams/:id', async (req, res) => {
+  const diagram = await db.diagrams.findById(req.params.id);
+  res.json(diagram);
+});
+
+app.put('/api/diagrams/:id', async (req, res) => {
+  const diagram = req.body;
+  await db.diagrams.update(req.params.id, diagram);
+  res.json({ success: true });
+});
+
+// WebSocket for real-time data
+wss.on('connection', (ws) => {
+  const interval = setInterval(() => {
+    // Fetch latest values from SCADA/PLC
+    const data = {
+      'PLC1.Tank01.Temp': { value: 72.5, timestamp: new Date(), quality: 'good' },
+      'PLC1.Tank01.Level': { value: 45.2, timestamp: new Date(), quality: 'good' },
+    };
+    ws.send(JSON.stringify(data));
+  }, 1000);
+
+  ws.on('close', () => clearInterval(interval));
+});
+```
+
+---
+
+## Performance Tuning
+
+### Large Diagrams (100+ Nodes)
+
+**Symptom:** Lag during pan/zoom or slow rendering.
+
+**Solutions:**
+
+1. **Limit telemetry updates:** Max 1-2 Hz per node
+2. **Debounce auto-save:** Wait for user to stop editing
+3. **Lazy load diagrams:** Load summary list, full diagram on demand
+4. **Consider pagination:** Split large process units across multiple diagrams
+
+### High-Frequency Data
+
+**Symptom:** CPU spikes, choppy animation.
+
+**Solutions:**
+
+```tsx
+// Throttle incoming WebSocket messages
+const throttledUpdate = throttle((data) => {
+  updateTelemetry(data);
+}, 500); // 2 updates/sec max
+
+ws.onmessage = (event) => {
+  throttledUpdate(JSON.parse(event.data));
+};
+```
+
+### Memory Leaks
+
+**Symptom:** Browser memory grows over time in runtime mode.
+
+**Solutions:**
+
+```tsx
+// Clean up WebSocket connections
+useEffect(() => {
+  const ws = new WebSocket('...');
+
+  return () => {
+    ws.close(); // Important!
+  };
+}, []);
+
+// Clean up intervals
+useEffect(() => {
+  const interval = setInterval(...);
+
+  return () => {
+    clearInterval(interval); // Important!
+  };
+}, []);
+```
+
+---
+
+## Migration from Demo
+
+The `RuntimeDemo.tsx` file demonstrates all recommended patterns. To migrate to production:
+
+1. **Extract state management** → Create `useDiagramStorage` hook
+2. **Move mode switching** → Implement in your app's routing/layout
+3. **Add persistence** → Integrate with your database API
+4. **Add authentication** → Role-based feature flags (engineer vs operator)
+5. **Connect real data** → Replace mock simulation with SCADA/OPC UA client
+
+**The patterns in RuntimeDemo are production-ready** - they represent best practices for:
+
+- Edit/runtime mode separation
+- Visual port selection
+- Three-panel layout
+- Auto-save with debouncing
+- Keyboard shortcuts
+- Connection mode state management
+
+The library handles **"how to render and interact"**, your app handles **"what to show and where data comes from"**.