@flowuent-org/diagramming-core 1.3.10 → 1.4.1

package/packages/diagrams/CUSTOM_ICONS.md

@@ -1,232 +1,232 @@
-# Fully Customizable Icons for Automation Nodes
-
-This document explains how to use fully customizable icons in automation nodes when using the diagramming library as a dependency.
-
-## Overview
-
-The automation nodes support **fully customizable icons** through the `iconName` field in the node data. Unlike traditional icon systems, this library provides **complete control** - users must define their own icon mappings, giving them the flexibility to use any icons from any library.
-
-## How It Works
-
-### 1. Add iconName to Node Data
-
-In your node data structure, add the `iconName` field:
-
-```typescript
-const nodeData = {
-  id: 'my-node',
-  type: 'AutomationStartNode',
-  position: { x: 100, y: 200 },
-  data: {
-    label: 'My Custom Node',
-    description: 'A node with a custom icon',
-    status: 'Ready',
-    backgroundColor: '#1e3a8a',
-    textColor: '#ffffff',
-    borderColor: '#3b82f6',
-    lastRun: 'Never',
-    duration: '0.0s',
-    iconName: 'MyCustomIcon', // Specify your custom icon name
-    // ... other node properties
-  }
-};
-```
-
-### 2. No Default Icons
-
-**Important**: This library comes with **no predefined icons**. Users have complete control and must define their own icon mappings. This approach provides:
-
-- **Maximum Flexibility**: Use any icon from any library
-- **Bundle Size Control**: Only include icons you actually use
-- **No Conflicts**: No predefined icons to override
-- **Complete Customization**: Design your own icon system
-
-### 3. Fallback Behavior
-
-If you don't specify an `iconName` or if the specified icon doesn't exist, the system will show:
-- A placeholder icon (❓) with a tooltip indicating the missing icon name
-- This helps developers identify which icons need to be defined
-
-### 4. Example Usage
-
-Here's a complete example of creating nodes with custom icons:
-
-```typescript
-// First, define your icon mappings
-import { addCustomIcons } from '@flowuent/diagramming-core/lib/utils/iconMapper';
-import { 
-  PlayArrow, 
-  Stop, 
-  Api, 
-  Article,
-  Home,
-  Cloud,
-  Database,
-  Email
-} from '@mui/icons-material';
-
-// Add your custom icons
-addCustomIcons({
-  'PlayArrow': PlayArrow,
-  'Stop': Stop,
-  'Api': Api,
-  'Article': Article,
-  'Home': Home,
-  'Cloud': Cloud,
-  'Database': Database,
-  'Email': Email
-});
-
-// Now create nodes with your custom icons
-const customNode = {
-  id: 'custom-start-node',
-  type: 'AutomationStartNode',
-  position: { x: 50, y: 200 },
-  data: {
-    label: 'Custom Workflow Trigger',
-    description: 'A custom start node with a home icon',
-    status: 'Ready',
-    backgroundColor: '#1e3a8a',
-    textColor: '#ffffff',
-    borderColor: '#3b82f6',
-    lastRun: 'Never',
-    duration: '0.0s',
-    iconName: 'Home', // Your custom icon
-    // ... rest of your node configuration
-  }
-};
-
-// Create an API node with a cloud icon
-const apiNode = {
-  id: 'cloud-api-node',
-  type: 'AutomationApiNode',
-  position: { x: 400, y: 200 },
-  data: {
-    label: 'Cloud API Call',
-    description: 'API call to cloud service',
-    status: 'Ready',
-    backgroundColor: '#1e40af',
-    textColor: '#ffffff',
-    borderColor: '#3b82f6',
-    lastRun: '5 minutes ago',
-    duration: '0.8s',
-    iconName: 'Cloud', // Your custom icon
-    // ... rest of your node configuration
-  }
-};
-```
-
-### 5. Adding Custom Icons
-
-Since there are no default icons, you **must** define your own icon mappings. Here are the different ways to do this:
-
-#### Method 1: Add Individual Icons
-
-```typescript
-import { addCustomIcon } from '@flowuent/diagramming-core/lib/utils/iconMapper';
-import { CustomIcon, AnotherIcon } from '@mui/icons-material';
-
-// Add a single custom icon
-addCustomIcon('CustomIcon', CustomIcon);
-
-// Now you can use it in your node data
-const nodeData = {
-  iconName: 'CustomIcon',
-  // ... other properties
-};
-```
-
-#### Method 2: Add Multiple Icons at Once
-
-```typescript
-import { addCustomIcons } from '@flowuent/diagramming-core/lib/utils/iconMapper';
-import { 
-  CustomIcon, 
-  AnotherIcon, 
-  ThirdIcon 
-} from '@mui/icons-material';
-
-// Add multiple custom icons
-addCustomIcons({
-  'CustomIcon': CustomIcon,
-  'AnotherIcon': AnotherIcon,
-  'ThirdIcon': ThirdIcon
-});
-
-// Now you can use any of these icons
-const nodeData = {
-  iconName: 'CustomIcon', // or 'AnotherIcon', 'ThirdIcon'
-  // ... other properties
-};
-```
-
-#### Method 3: Direct Icon Map Extension
-
-```typescript
-import { iconMap } from '@flowuent/diagramming-core/lib/utils/iconMapper';
-import { CustomIcon } from '@mui/icons-material';
-
-// Directly extend the icon map
-iconMap['CustomIcon'] = CustomIcon;
-```
-
-#### Method 4: Add Icons from Other Libraries
-
-```typescript
-import { addCustomIcon } from '@flowuent/diagramming-core/lib/utils/iconMapper';
-import { FaReact, FaNodeJs } from 'react-icons/fa'; // Font Awesome icons
-
-// Add icons from other libraries
-addCustomIcon('React', FaReact);
-addCustomIcon('NodeJS', FaNodeJs);
-```
-
-#### Method 5: Create Your Own Icon Components
-
-```typescript
-import { addCustomIcon } from '@flowuent/diagramming-core/lib/utils/iconMapper';
-
-// Create a custom icon component
-const MyCustomIcon = (props: any) => (
-  <svg {...props} viewBox="0 0 24 24">
-    <path d="M12 2L2 7l10 5 10-5-10-5zM2 17l10 5 10-5M2 12l10 5 10-5" />
-  </svg>
-);
-
-// Add your custom icon
-addCustomIcon('MyCustomIcon', MyCustomIcon);
-```
-
-## Best Practices
-
-1. **Choose Meaningful Icons**: Select icons that clearly represent the node's function
-2. **Consistency**: Use consistent icon choices across similar node types
-3. **Fallback**: Always test with fallback icons to ensure your nodes work even if custom icons fail
-4. **Performance**: Icons are loaded on-demand, so there's minimal performance impact
-
-## Troubleshooting
-
-### Icon Not Displaying
-- Check that the `iconName` is spelled correctly
-- Verify the icon exists in the available icons list
-- Ensure the icon name matches exactly (case-sensitive)
-
-### TypeScript Errors
-- Make sure you've added `iconName?: string` to your node data interface
-- Import the icon mapper utility if you're extending it
-
-### Custom Icons Not Working
-- Ensure you've properly extended the icon mapper
-- Check that your custom icon component is properly imported
-- Verify the icon component follows Material-UI icon patterns
-
-## Migration Guide
-
-If you're upgrading from a version without configurable icons:
-
-1. Add `iconName?: string` to your node data interfaces
-2. Optionally specify custom icons in your existing node data
-3. Test that fallback icons work correctly
-4. Update your documentation to reflect the new icon capabilities
-
-This feature maintains backward compatibility - existing nodes without `iconName` will continue to work with their default icons.
+# Fully Customizable Icons for Automation Nodes
+
+This document explains how to use fully customizable icons in automation nodes when using the diagramming library as a dependency.
+
+## Overview
+
+The automation nodes support **fully customizable icons** through the `iconName` field in the node data. Unlike traditional icon systems, this library provides **complete control** - users must define their own icon mappings, giving them the flexibility to use any icons from any library.
+
+## How It Works
+
+### 1. Add iconName to Node Data
+
+In your node data structure, add the `iconName` field:
+
+```typescript
+const nodeData = {
+  id: 'my-node',
+  type: 'AutomationStartNode',
+  position: { x: 100, y: 200 },
+  data: {
+    label: 'My Custom Node',
+    description: 'A node with a custom icon',
+    status: 'Ready',
+    backgroundColor: '#1e3a8a',
+    textColor: '#ffffff',
+    borderColor: '#3b82f6',
+    lastRun: 'Never',
+    duration: '0.0s',
+    iconName: 'MyCustomIcon', // Specify your custom icon name
+    // ... other node properties
+  }
+};
+```
+
+### 2. No Default Icons
+
+**Important**: This library comes with **no predefined icons**. Users have complete control and must define their own icon mappings. This approach provides:
+
+- **Maximum Flexibility**: Use any icon from any library
+- **Bundle Size Control**: Only include icons you actually use
+- **No Conflicts**: No predefined icons to override
+- **Complete Customization**: Design your own icon system
+
+### 3. Fallback Behavior
+
+If you don't specify an `iconName` or if the specified icon doesn't exist, the system will show:
+- A placeholder icon (❓) with a tooltip indicating the missing icon name
+- This helps developers identify which icons need to be defined
+
+### 4. Example Usage
+
+Here's a complete example of creating nodes with custom icons:
+
+```typescript
+// First, define your icon mappings
+import { addCustomIcons } from '@flowuent/diagramming-core/lib/utils/iconMapper';
+import { 
+  PlayArrow, 
+  Stop, 
+  Api, 
+  Article,
+  Home,
+  Cloud,
+  Database,
+  Email
+} from '@mui/icons-material';
+
+// Add your custom icons
+addCustomIcons({
+  'PlayArrow': PlayArrow,
+  'Stop': Stop,
+  'Api': Api,
+  'Article': Article,
+  'Home': Home,
+  'Cloud': Cloud,
+  'Database': Database,
+  'Email': Email
+});
+
+// Now create nodes with your custom icons
+const customNode = {
+  id: 'custom-start-node',
+  type: 'AutomationStartNode',
+  position: { x: 50, y: 200 },
+  data: {
+    label: 'Custom Workflow Trigger',
+    description: 'A custom start node with a home icon',
+    status: 'Ready',
+    backgroundColor: '#1e3a8a',
+    textColor: '#ffffff',
+    borderColor: '#3b82f6',
+    lastRun: 'Never',
+    duration: '0.0s',
+    iconName: 'Home', // Your custom icon
+    // ... rest of your node configuration
+  }
+};
+
+// Create an API node with a cloud icon
+const apiNode = {
+  id: 'cloud-api-node',
+  type: 'AutomationApiNode',
+  position: { x: 400, y: 200 },
+  data: {
+    label: 'Cloud API Call',
+    description: 'API call to cloud service',
+    status: 'Ready',
+    backgroundColor: '#1e40af',
+    textColor: '#ffffff',
+    borderColor: '#3b82f6',
+    lastRun: '5 minutes ago',
+    duration: '0.8s',
+    iconName: 'Cloud', // Your custom icon
+    // ... rest of your node configuration
+  }
+};
+```
+
+### 5. Adding Custom Icons
+
+Since there are no default icons, you **must** define your own icon mappings. Here are the different ways to do this:
+
+#### Method 1: Add Individual Icons
+
+```typescript
+import { addCustomIcon } from '@flowuent/diagramming-core/lib/utils/iconMapper';
+import { CustomIcon, AnotherIcon } from '@mui/icons-material';
+
+// Add a single custom icon
+addCustomIcon('CustomIcon', CustomIcon);
+
+// Now you can use it in your node data
+const nodeData = {
+  iconName: 'CustomIcon',
+  // ... other properties
+};
+```
+
+#### Method 2: Add Multiple Icons at Once
+
+```typescript
+import { addCustomIcons } from '@flowuent/diagramming-core/lib/utils/iconMapper';
+import { 
+  CustomIcon, 
+  AnotherIcon, 
+  ThirdIcon 
+} from '@mui/icons-material';
+
+// Add multiple custom icons
+addCustomIcons({
+  'CustomIcon': CustomIcon,
+  'AnotherIcon': AnotherIcon,
+  'ThirdIcon': ThirdIcon
+});
+
+// Now you can use any of these icons
+const nodeData = {
+  iconName: 'CustomIcon', // or 'AnotherIcon', 'ThirdIcon'
+  // ... other properties
+};
+```
+
+#### Method 3: Direct Icon Map Extension
+
+```typescript
+import { iconMap } from '@flowuent/diagramming-core/lib/utils/iconMapper';
+import { CustomIcon } from '@mui/icons-material';
+
+// Directly extend the icon map
+iconMap['CustomIcon'] = CustomIcon;
+```
+
+#### Method 4: Add Icons from Other Libraries
+
+```typescript
+import { addCustomIcon } from '@flowuent/diagramming-core/lib/utils/iconMapper';
+import { FaReact, FaNodeJs } from 'react-icons/fa'; // Font Awesome icons
+
+// Add icons from other libraries
+addCustomIcon('React', FaReact);
+addCustomIcon('NodeJS', FaNodeJs);
+```
+
+#### Method 5: Create Your Own Icon Components
+
+```typescript
+import { addCustomIcon } from '@flowuent/diagramming-core/lib/utils/iconMapper';
+
+// Create a custom icon component
+const MyCustomIcon = (props: any) => (
+  <svg {...props} viewBox="0 0 24 24">
+    <path d="M12 2L2 7l10 5 10-5-10-5zM2 17l10 5 10-5M2 12l10 5 10-5" />
+  </svg>
+);
+
+// Add your custom icon
+addCustomIcon('MyCustomIcon', MyCustomIcon);
+```
+
+## Best Practices
+
+1. **Choose Meaningful Icons**: Select icons that clearly represent the node's function
+2. **Consistency**: Use consistent icon choices across similar node types
+3. **Fallback**: Always test with fallback icons to ensure your nodes work even if custom icons fail
+4. **Performance**: Icons are loaded on-demand, so there's minimal performance impact
+
+## Troubleshooting
+
+### Icon Not Displaying
+- Check that the `iconName` is spelled correctly
+- Verify the icon exists in the available icons list
+- Ensure the icon name matches exactly (case-sensitive)
+
+### TypeScript Errors
+- Make sure you've added `iconName?: string` to your node data interface
+- Import the icon mapper utility if you're extending it
+
+### Custom Icons Not Working
+- Ensure you've properly extended the icon mapper
+- Check that your custom icon component is properly imported
+- Verify the icon component follows Material-UI icon patterns
+
+## Migration Guide
+
+If you're upgrading from a version without configurable icons:
+
+1. Add `iconName?: string` to your node data interfaces
+2. Optionally specify custom icons in your existing node data
+3. Test that fallback icons work correctly
+4. Update your documentation to reflect the new icon capabilities
+
+This feature maintains backward compatibility - existing nodes without `iconName` will continue to work with their default icons.