@flowuent-org/diagramming-core 1.0.5 → 1.0.6

package/packages/diagrams/UNDO_REDO_API.md

@@ -1,306 +1,306 @@
-# Undo/Redo API Documentation
-
-## Overview
-
-The diagramming library provides comprehensive undo/redo functionality for all diagram types, including automation diagrams. This document explains how to expose and use undo/redo controls externally when using the library.
-
-## How Undo/Redo Works
-
-### Internal Implementation
-
-1. **History Management**: The system maintains a `history` array and `historyIndex` in the DiagramStore
-2. **Change Tracking**: Every change to nodes/edges is tracked and stored as `HistoryEvent` objects
-3. **State Restoration**: Changes are applied in reverse (undo) or forward (redo) direction
-4. **Keyboard Shortcuts**: Ctrl+Z (undo) and Ctrl+Y/Cmd+Shift+Z (redo) work automatically
-
-### Key Components
-
-- **DiagramProvider**: Contains the main store with `undo()` and `redo()` methods
-- **History System**: Tracks all changes with forward/backward operations
-- **DownloadPanel**: Built-in undo/redo buttons (can be hidden)
-
-## External Undo/Redo Control
-
-### Method 1: Using Ref-based API (Recommended)
-
-The `DiagrammingPage` component now supports a ref that exposes undo/redo functionality:
-
-```typescript
-import React, { useRef } from 'react';
-import { DiagrammingPage, DiagrammingPageRef } from '@flowuent-org/diagrams';
-
-const MyComponent = () => {
-  const diagramRef = useRef<DiagrammingPageRef>(null);
-
-  const handleUndo = () => {
-    if (diagramRef.current?.canUndo()) {
-      diagramRef.current.undo();
-    }
-  };
-
-  const handleRedo = () => {
-    if (diagramRef.current?.canRedo()) {
-      diagramRef.current.redo();
-    }
-  };
-
-  return (
-    <div>
-      {/* Your external undo/redo buttons */}
-      <button onClick={handleUndo} disabled={!diagramRef.current?.canUndo()}>
-        Undo
-      </button>
-      <button onClick={handleRedo} disabled={!diagramRef.current?.canRedo()}>
-        Redo
-      </button>
-
-      {/* The diagram */}
-      <DiagrammingPage
-        ref={diagramRef}
-        diagramType="automation"
-        defaultNodes={nodes}
-        defaultEdges={edges}
-        availableFunctions={[]}
-        id={1}
-      />
-    </div>
-  );
-};
-```
-
-### Available Methods
-
-The `DiagrammingPageRef` interface provides these methods:
-
-```typescript
-interface DiagrammingPageRef {
-  undo: () => void;                    // Perform undo operation
-  redo: () => void;                    // Perform redo operation
-  canUndo: () => boolean;              // Check if undo is available
-  canRedo: () => boolean;              // Check if redo is available
-  reset: () => void;                   // Clear the diagram
-  getHistoryLength: () => number;      // Get total history length
-  getHistoryIndex: () => number;       // Get current history index
-}
-```
-
-### Method 2: Using DownloadPanel with Hidden Built-in Controls
-
-You can hide the built-in undo/redo buttons and use your own:
-
-```typescript
-import { DiagrammingPage, DownloadPanel } from '@flowuent-org/diagrams';
-
-const MyComponent = () => {
-  return (
-    <DiagrammingPage
-      diagramType="automation"
-      defaultNodes={nodes}
-      defaultEdges={edges}
-      availableFunctions={[]}
-      id={1}
-    >
-      {/* Hide built-in undo/redo buttons */}
-      <DownloadPanel 
-        hideUndo={true} 
-        hideRedo={true}
-        position="top-left"
-      />
-      
-      {/* Your custom controls */}
-      <YourCustomControls />
-    </DiagrammingPage>
-  );
-};
-```
-
-## Complete Example
-
-Here's a complete example showing how to implement external undo/redo controls:
-
-```typescript
-import React, { useRef, useState, useEffect } from 'react';
-import { Button, Box, Typography, IconButton } from '@mui/material';
-import { UndoIcon, RedoIcon, ClearIcon } from '@mui/icons-material';
-import { DiagrammingPage, DiagrammingPageRef } from '@flowuent-org/diagrams';
-import { ICardNode } from '@flowuent-org/diagrams';
-import { Edge } from '@xyflow/react';
-
-const AutomationDiagramWithExternalControls: React.FC = () => {
-  const diagramRef = useRef<DiagrammingPageRef>(null);
-  const [canUndo, setCanUndo] = useState(false);
-  const [canRedo, setCanRedo] = useState(false);
-  const [historyInfo, setHistoryInfo] = useState({ index: 0, length: 0 });
-
-  // Sample automation diagram data
-  const defaultNodes: ICardNode[] = [
-    {
-      id: '1',
-      type: 'AutomationStartNode',
-      position: { x: 100, y: 100 },
-      data: { label: 'Start Process' }
-    },
-    {
-      id: '2',
-      type: 'AutomationApiNode',
-      position: { x: 300, y: 100 },
-      data: { label: 'API Call' }
-    },
-    {
-      id: '3',
-      type: 'AutomationEndNode',
-      position: { x: 500, y: 100 },
-      data: { label: 'End Process' }
-    }
-  ];
-
-  const defaultEdges: Edge[] = [
-    { id: 'e1-2', source: '1', target: '2' },
-    { id: 'e2-3', source: '2', target: '3' }
-  ];
-
-  const updateButtonStates = () => {
-    if (diagramRef.current) {
-      setCanUndo(diagramRef.current.canUndo());
-      setCanRedo(diagramRef.current.canRedo());
-      setHistoryInfo({
-        index: diagramRef.current.getHistoryIndex(),
-        length: diagramRef.current.getHistoryLength()
-      });
-    }
-  };
-
-  const handleUndo = () => {
-    if (diagramRef.current?.canUndo()) {
-      diagramRef.current.undo();
-      updateButtonStates();
-    }
-  };
-
-  const handleRedo = () => {
-    if (diagramRef.current?.canRedo()) {
-      diagramRef.current.redo();
-      updateButtonStates();
-    }
-  };
-
-  const handleReset = () => {
-    diagramRef.current?.reset();
-    updateButtonStates();
-  };
-
-  // Update button states when diagram changes
-  useEffect(() => {
-    const interval = setInterval(updateButtonStates, 100);
-    return () => clearInterval(interval);
-  }, []);
-
-  return (
-    <Box sx={{ height: '100vh', display: 'flex', flexDirection: 'column' }}>
-      {/* External Controls Toolbar */}
-      <Box sx={{ 
-        p: 2, 
-        bgcolor: '#f5f5f5', 
-        borderBottom: '1px solid #ddd',
-        display: 'flex',
-        gap: 2,
-        alignItems: 'center',
-        boxShadow: '0 2px 4px rgba(0,0,0,0.1)'
-      }}>
-        <Typography variant="h6" sx={{ fontWeight: 'bold' }}>
-          Automation Diagram Controls
-        </Typography>
-        
-        <Box sx={{ display: 'flex', gap: 1, ml: 2 }}>
-          <IconButton 
-            onClick={handleUndo}
-            disabled={!canUndo}
-            sx={{ 
-              bgcolor: canUndo ? '#1976d2' : '#e0e0e0',
-              color: canUndo ? 'white' : '#9e9e9e',
-              '&:hover': {
-                bgcolor: canUndo ? '#1565c0' : '#e0e0e0'
-              }
-            }}
-          >
-            <UndoIcon />
-          </IconButton>
-          
-          <IconButton 
-            onClick={handleRedo}
-            disabled={!canRedo}
-            sx={{ 
-              bgcolor: canRedo ? '#1976d2' : '#e0e0e0',
-              color: canRedo ? 'white' : '#9e9e9e',
-              '&:hover': {
-                bgcolor: canRedo ? '#1565c0' : '#e0e0e0'
-              }
-            }}
-          >
-            <RedoIcon />
-          </IconButton>
-          
-          <IconButton 
-            onClick={handleReset}
-            sx={{ 
-              bgcolor: '#d32f2f',
-              color: 'white',
-              '&:hover': {
-                bgcolor: '#c62828'
-              }
-            }}
-          >
-            <ClearIcon />
-          </IconButton>
-        </Box>
-
-        <Typography variant="body2" sx={{ ml: 'auto', color: '#666' }}>
-          History: {historyInfo.index} / {historyInfo.length}
-        </Typography>
-      </Box>
-
-      {/* Diagram */}
-      <Box sx={{ flex: 1 }}>
-        <DiagrammingPage
-          ref={diagramRef}
-          diagramType="automation"
-          defaultNodes={defaultNodes}
-          defaultEdges={defaultEdges}
-          availableFunctions={[]}
-          id={1}
-          onChange={() => {
-            // Update button states when diagram changes
-            setTimeout(updateButtonStates, 100);
-          }}
-        />
-      </Box>
-    </Box>
-  );
-};
-
-export default AutomationDiagramWithExternalControls;
-```
-
-## Integration Steps for Your Team Member
-
-1. **Install the updated library** with the new ref-based API
-2. **Create a ref** to the DiagrammingPage component
-3. **Add external buttons** that call the ref methods
-4. **Handle state updates** to enable/disable buttons appropriately
-5. **Test the functionality** with various diagram operations
-
-## Key Benefits
-
-- **Full Control**: Complete control over undo/redo UI and behavior
-- **State Awareness**: Know when undo/redo is available
-- **History Information**: Access to history length and current index
-- **Keyboard Support**: Built-in keyboard shortcuts still work
-- **Flexible Integration**: Works with any UI framework or custom components
-
-## Notes
-
-- The undo/redo functionality works automatically for all diagram types
-- History is maintained per diagram instance
-- Changes are tracked for node/edge additions, deletions, modifications, and movements
-- The system prevents infinite loops and handles edge cases gracefully
-- Keyboard shortcuts (Ctrl+Z, Ctrl+Y) work alongside external controls
+# Undo/Redo API Documentation
+
+## Overview
+
+The diagramming library provides comprehensive undo/redo functionality for all diagram types, including automation diagrams. This document explains how to expose and use undo/redo controls externally when using the library.
+
+## How Undo/Redo Works
+
+### Internal Implementation
+
+1. **History Management**: The system maintains a `history` array and `historyIndex` in the DiagramStore
+2. **Change Tracking**: Every change to nodes/edges is tracked and stored as `HistoryEvent` objects
+3. **State Restoration**: Changes are applied in reverse (undo) or forward (redo) direction
+4. **Keyboard Shortcuts**: Ctrl+Z (undo) and Ctrl+Y/Cmd+Shift+Z (redo) work automatically
+
+### Key Components
+
+- **DiagramProvider**: Contains the main store with `undo()` and `redo()` methods
+- **History System**: Tracks all changes with forward/backward operations
+- **DownloadPanel**: Built-in undo/redo buttons (can be hidden)
+
+## External Undo/Redo Control
+
+### Method 1: Using Ref-based API (Recommended)
+
+The `DiagrammingPage` component now supports a ref that exposes undo/redo functionality:
+
+```typescript
+import React, { useRef } from 'react';
+import { DiagrammingPage, DiagrammingPageRef } from '@flowuent-labs/diagrams';
+
+const MyComponent = () => {
+  const diagramRef = useRef<DiagrammingPageRef>(null);
+
+  const handleUndo = () => {
+    if (diagramRef.current?.canUndo()) {
+      diagramRef.current.undo();
+    }
+  };
+
+  const handleRedo = () => {
+    if (diagramRef.current?.canRedo()) {
+      diagramRef.current.redo();
+    }
+  };
+
+  return (
+    <div>
+      {/* Your external undo/redo buttons */}
+      <button onClick={handleUndo} disabled={!diagramRef.current?.canUndo()}>
+        Undo
+      </button>
+      <button onClick={handleRedo} disabled={!diagramRef.current?.canRedo()}>
+        Redo
+      </button>
+
+      {/* The diagram */}
+      <DiagrammingPage
+        ref={diagramRef}
+        diagramType="automation"
+        defaultNodes={nodes}
+        defaultEdges={edges}
+        availableFunctions={[]}
+        id={1}
+      />
+    </div>
+  );
+};
+```
+
+### Available Methods
+
+The `DiagrammingPageRef` interface provides these methods:
+
+```typescript
+interface DiagrammingPageRef {
+  undo: () => void;                    // Perform undo operation
+  redo: () => void;                    // Perform redo operation
+  canUndo: () => boolean;              // Check if undo is available
+  canRedo: () => boolean;              // Check if redo is available
+  reset: () => void;                   // Clear the diagram
+  getHistoryLength: () => number;      // Get total history length
+  getHistoryIndex: () => number;       // Get current history index
+}
+```
+
+### Method 2: Using DownloadPanel with Hidden Built-in Controls
+
+You can hide the built-in undo/redo buttons and use your own:
+
+```typescript
+import { DiagrammingPage, DownloadPanel } from '@flowuent-labs/diagrams';
+
+const MyComponent = () => {
+  return (
+    <DiagrammingPage
+      diagramType="automation"
+      defaultNodes={nodes}
+      defaultEdges={edges}
+      availableFunctions={[]}
+      id={1}
+    >
+      {/* Hide built-in undo/redo buttons */}
+      <DownloadPanel 
+        hideUndo={true} 
+        hideRedo={true}
+        position="top-left"
+      />
+      
+      {/* Your custom controls */}
+      <YourCustomControls />
+    </DiagrammingPage>
+  );
+};
+```
+
+## Complete Example
+
+Here's a complete example showing how to implement external undo/redo controls:
+
+```typescript
+import React, { useRef, useState, useEffect } from 'react';
+import { Button, Box, Typography, IconButton } from '@mui/material';
+import { UndoIcon, RedoIcon, ClearIcon } from '@mui/icons-material';
+import { DiagrammingPage, DiagrammingPageRef } from '@flowuent-labs/diagrams';
+import { ICardNode } from '@flowuent-labs/diagrams';
+import { Edge } from '@xyflow/react';
+
+const AutomationDiagramWithExternalControls: React.FC = () => {
+  const diagramRef = useRef<DiagrammingPageRef>(null);
+  const [canUndo, setCanUndo] = useState(false);
+  const [canRedo, setCanRedo] = useState(false);
+  const [historyInfo, setHistoryInfo] = useState({ index: 0, length: 0 });
+
+  // Sample automation diagram data
+  const defaultNodes: ICardNode[] = [
+    {
+      id: '1',
+      type: 'AutomationStartNode',
+      position: { x: 100, y: 100 },
+      data: { label: 'Start Process' }
+    },
+    {
+      id: '2',
+      type: 'AutomationApiNode',
+      position: { x: 300, y: 100 },
+      data: { label: 'API Call' }
+    },
+    {
+      id: '3',
+      type: 'AutomationEndNode',
+      position: { x: 500, y: 100 },
+      data: { label: 'End Process' }
+    }
+  ];
+
+  const defaultEdges: Edge[] = [
+    { id: 'e1-2', source: '1', target: '2' },
+    { id: 'e2-3', source: '2', target: '3' }
+  ];
+
+  const updateButtonStates = () => {
+    if (diagramRef.current) {
+      setCanUndo(diagramRef.current.canUndo());
+      setCanRedo(diagramRef.current.canRedo());
+      setHistoryInfo({
+        index: diagramRef.current.getHistoryIndex(),
+        length: diagramRef.current.getHistoryLength()
+      });
+    }
+  };
+
+  const handleUndo = () => {
+    if (diagramRef.current?.canUndo()) {
+      diagramRef.current.undo();
+      updateButtonStates();
+    }
+  };
+
+  const handleRedo = () => {
+    if (diagramRef.current?.canRedo()) {
+      diagramRef.current.redo();
+      updateButtonStates();
+    }
+  };
+
+  const handleReset = () => {
+    diagramRef.current?.reset();
+    updateButtonStates();
+  };
+
+  // Update button states when diagram changes
+  useEffect(() => {
+    const interval = setInterval(updateButtonStates, 100);
+    return () => clearInterval(interval);
+  }, []);
+
+  return (
+    <Box sx={{ height: '100vh', display: 'flex', flexDirection: 'column' }}>
+      {/* External Controls Toolbar */}
+      <Box sx={{ 
+        p: 2, 
+        bgcolor: '#f5f5f5', 
+        borderBottom: '1px solid #ddd',
+        display: 'flex',
+        gap: 2,
+        alignItems: 'center',
+        boxShadow: '0 2px 4px rgba(0,0,0,0.1)'
+      }}>
+        <Typography variant="h6" sx={{ fontWeight: 'bold' }}>
+          Automation Diagram Controls
+        </Typography>
+        
+        <Box sx={{ display: 'flex', gap: 1, ml: 2 }}>
+          <IconButton 
+            onClick={handleUndo}
+            disabled={!canUndo}
+            sx={{ 
+              bgcolor: canUndo ? '#1976d2' : '#e0e0e0',
+              color: canUndo ? 'white' : '#9e9e9e',
+              '&:hover': {
+                bgcolor: canUndo ? '#1565c0' : '#e0e0e0'
+              }
+            }}
+          >
+            <UndoIcon />
+          </IconButton>
+          
+          <IconButton 
+            onClick={handleRedo}
+            disabled={!canRedo}
+            sx={{ 
+              bgcolor: canRedo ? '#1976d2' : '#e0e0e0',
+              color: canRedo ? 'white' : '#9e9e9e',
+              '&:hover': {
+                bgcolor: canRedo ? '#1565c0' : '#e0e0e0'
+              }
+            }}
+          >
+            <RedoIcon />
+          </IconButton>
+          
+          <IconButton 
+            onClick={handleReset}
+            sx={{ 
+              bgcolor: '#d32f2f',
+              color: 'white',
+              '&:hover': {
+                bgcolor: '#c62828'
+              }
+            }}
+          >
+            <ClearIcon />
+          </IconButton>
+        </Box>
+
+        <Typography variant="body2" sx={{ ml: 'auto', color: '#666' }}>
+          History: {historyInfo.index} / {historyInfo.length}
+        </Typography>
+      </Box>
+
+      {/* Diagram */}
+      <Box sx={{ flex: 1 }}>
+        <DiagrammingPage
+          ref={diagramRef}
+          diagramType="automation"
+          defaultNodes={defaultNodes}
+          defaultEdges={defaultEdges}
+          availableFunctions={[]}
+          id={1}
+          onChange={() => {
+            // Update button states when diagram changes
+            setTimeout(updateButtonStates, 100);
+          }}
+        />
+      </Box>
+    </Box>
+  );
+};
+
+export default AutomationDiagramWithExternalControls;
+```
+
+## Integration Steps for Your Team Member
+
+1. **Install the updated library** with the new ref-based API
+2. **Create a ref** to the DiagrammingPage component
+3. **Add external buttons** that call the ref methods
+4. **Handle state updates** to enable/disable buttons appropriately
+5. **Test the functionality** with various diagram operations
+
+## Key Benefits
+
+- **Full Control**: Complete control over undo/redo UI and behavior
+- **State Awareness**: Know when undo/redo is available
+- **History Information**: Access to history length and current index
+- **Keyboard Support**: Built-in keyboard shortcuts still work
+- **Flexible Integration**: Works with any UI framework or custom components
+
+## Notes
+
+- The undo/redo functionality works automatically for all diagram types
+- History is maintained per diagram instance
+- Changes are tracked for node/edge additions, deletions, modifications, and movements
+- The system prevents infinite loops and handles edge cases gracefully
+- Keyboard shortcuts (Ctrl+Z, Ctrl+Y) work alongside external controls