@flowuent-org/diagramming-core 1.0.8 → 1.1.0

package/packages/diagrams/CUSTOM_ICONS.md

@@ -1,232 +0,0 @@
-# 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.

package/packages/diagrams/GOOGLE_SHEETS_IMPLEMENTATION.md

@@ -1,233 +0,0 @@
-# Google Sheets Automation Node Implementation
-
-This document explains the frontend-only Google Sheets Output Node. It supports Google Sheets export (cloud), Excel download (local), and email compose.
-
-## Features
-
-### ✅ Implemented
-
-1. **Google Sheets Export (Cloud)**
-   - OAuth via Google Identity Services (GIS) in the browser
-   - Creates a new spreadsheet when `spreadsheetId` is empty
-   - Ensures the target sheet exists and writes mapped values
-
-2. **Excel Download (Local)**
-   - Uses `xlsx` to build a workbook and `file-saver` to download
-   - Optional headers row
-
-3. **Email Output (Compose)**
-   - Opens Gmail compose in a new tab with pre-filled to/subject/body
-   - Falls back to `mailto:` handler if the popup is blocked
-   - Optionally includes a spreadsheet link in the message
-
-4. **Data Mapping & Formatting**
-   - Flexible column mapping with nested field support (dot notation)
-   - String/number/date/boolean formatting
-   - Append/overwrite controls via configuration
-
-5. **Export Modes**
-   - `sheets` (cloud)
-   - `excel` (local)
-   - `both` (cloud + local)
-
-6. **Error Handling & Logging**
-   - Config validation, structured logs, execution results per node
-
-## Dependencies
-
-Browser loads GIS from `https://accounts.google.com/gsi/client`. No server SDK required.
-
-Project packages used:
-
-```json
-{
-  "xlsx": "^0.18.5",
-  "file-saver": "^2.0.5",
-  "@types/file-saver": "^2.0.7"
-}
-```
-
-## Configuration Structure
-
-### Google Sheets Configuration
-```typescript
-sheetsConfig: {
-  spreadsheetId: string;
-  sheetName: string;
-  range: string;
-  credentials: {
-    type: 'oauth' | 'service-account' | 'api-key';
-    // Frontend OAuth (GIS)
-    clientId?: string;
-    scopes?: string[]; // default: ['https://www.googleapis.com/auth/spreadsheets']
-    oauthToken?: string; // optional pre-provided token
-    // Server-side options (not used in frontend-only mode)
-    serviceAccountKey?: string;
-    clientEmail?: string;
-    privateKey?: string;
-    apiKey?: string;
-  };
-}
-```
-
-### Export Options
-```typescript
-exportOptions: {
-  emailRecipients: string[];
-  fileName: string;
-  exportFormat: 'sheets' | 'excel' | 'both';
-  includeHeaders: boolean;
-  sendEmailNotification: boolean;
-  // Email compose options (optional)
-  emailSendEnabled?: boolean;
-  emailSender?: string;
-  emailSubject?: string;
-  emailMessage?: string;
-  includeSpreadsheetLink?: boolean;
-  attachExcel?: boolean; // requires Gmail API for real attachments
-}
-```
-
-### Data Mapping
-```typescript
-dataMapping: {
-  headers: Array<{
-    column: string;
-    sourceField: string;
-    dataType: 'string' | 'number' | 'date' | 'boolean';
-  }>;
-  appendMode: boolean;
-  clearSheet: boolean;
-}
-```
-
-## Usage Examples
-
-### Basic Google Sheets Export
-```typescript
-const sheetsService = new GoogleSheetsService();
-await sheetsService.initialize(sheetsConfig);
-
-const response = await sheetsService.exportToSheets(
-  data,
-  sheetsConfig,
-  dataMapping,
-  {
-    emailRecipients: ['user@example.com'],
-    fileName: 'report.xlsx',
-    exportFormat: 'sheets',
-    includeHeaders: true
-  }
-);
-```
-
-### Excel File Generation
-```typescript
-const excelResponse = await sheetsService.exportToExcel(
-  data,
-  dataMapping,
-  {
-    emailRecipients: ['user@example.com'],
-    fileName: 'data_export.xlsx',
-    includeHeaders: true
-  }
-);
-```
-
-### Both + Email Compose
-```typescript
-const response = await sheetsService.exportToSheets(
-  data,
-  sheetsConfig,
-  dataMapping,
-  {
-    emailRecipients: ['recipient@example.com'],
-    fileName: 'news_analysis_report',
-    exportFormat: 'both',
-    includeHeaders: true,
-    // email compose
-    emailSendEnabled: true,
-    emailSender: 'sender@example.com',
-    emailSubject: 'News Analysis Results',
-    emailMessage: 'Please find the latest output.',
-    includeSpreadsheetLink: true,
-  }
-);
-```
-
-## Authentication Setup (Frontend OAuth)
-
-1. Google Cloud Console → APIs & Services → Credentials → Create OAuth client ID → Application type: Web application.
-2. Authorized JavaScript origins: add your dev URLs (e.g., `http://localhost:5200`, `http://localhost:5300`).
-3. Enable the "Google Sheets API" for your project.
-4. OAuth consent screen: configure and Publish (or add test users).
-5. Put the client ID in `sheetsConfig.credentials.clientId`.
-6. Scopes: `['https://www.googleapis.com/auth/spreadsheets']` (default). For sending emails programmatically later, add `https://www.googleapis.com/auth/gmail.send`.
-7. Allow pop-ups for your dev origin so Gmail compose can open in a new tab.
-
-## Error Handling
-
-Includes:
-
-- Configuration validation
-- OAuth and API error messages with details
-- Range sizing that accounts for header rows
-- Logging and `executionResult` on each node
-
-## Security Considerations
-
-1. **Credentials Storage**: Store service account keys securely
-2. **API Key Restrictions**: Limit API key scope and usage
-3. **Sheet Permissions**: Use minimal required permissions
-4. **Data Privacy**: Ensure sensitive data is handled appropriately
-
-## Testing
-
-The implementation includes:
-- Configuration validation tests
-- Mock API responses for development
-- Error scenario handling
-- Data format validation
-
-## Future Enhancements
-
-1. Gmail API send with attachments (requires `gmail.send` scope and MIME building)
-2. Predefined Google Sheets templates and formatting
-3. Batch operations and partial updates
-4. Live progress UI during export
-
-### Potential Improvements
-1. **Caching**: Cache authentication tokens
-2. **Rate Limiting**: Handle API rate limits
-3. **Progress Tracking**: Real-time export progress
-4. **Data Validation**: Enhanced data type validation
-5. **Custom Formatting**: Cell formatting options
-
-## Troubleshooting
-
-### Common Issues
-1. **OAuth 400**: Ensure Authorized JavaScript origins match your dev URL and the consent screen is published.
-2. **No Gmail compose**: Enable pop-ups or try again; we open Gmail in a new tab.
-3. **Range errors**: Increase range or rely on auto-sizing; headers add one row.
-4. **Empty writes**: Verify the previous node outputs the fields referenced by `dataMapping.headers`.
-
-### Debug Mode
-Enable debug logging to see detailed execution information:
-```typescript
-// Debug logs are automatically included in execution results
-console.log('Execution result:', response);
-```
-
-## Contributing
-
-When contributing to this implementation:
-1. Follow TypeScript best practices
-2. Include comprehensive error handling
-3. Add appropriate tests
-4. Update documentation
-5. Consider security implications
-
-## License
-
-This implementation follows the same license as the parent project.
-

package/packages/diagrams/I18N_SETUP.md

@@ -1,126 +0,0 @@
-# Internationalization (i18n) Setup
-
-The `@flowuent-labs/diagrams` library includes built-in translation support using i18next. To ensure translations work correctly in your application, you need to initialize i18n before using the library components.
-
-## Quick Start
-
-### Option 1: Use Built-in Initialization (Recommended)
-
-Import and call the `initDiagramsI18n` function before rendering any diagram components:
-
-```typescript
-import { initDiagramsI18n } from '@flowuent-labs/diagrams';
-
-// Initialize i18n with default translations
-initDiagramsI18n();
-
-// Now you can use any diagram components
-function App() {
-  return <YourDiagramComponent />;
-}
-```
-
-### Option 2: Manual Initialization with Custom Translations
-
-If you want to customize or extend the translations:
-
-```typescript
-import { initDiagramsI18n, translationEN } from '@flowuent-labs/diagrams';
-
-// Initialize with custom translations
-initDiagramsI18n({
-  en: {
-    translation: {
-      ...translationEN,
-      // Add your custom translations or overrides here
-      customKey: 'Custom value',
-    },
-  },
-  // Add other languages
-  es: {
-    translation: {
-      // Spanish translations
-    },
-  },
-});
-```
-
-### Option 3: Use Existing i18next Instance
-
-If your app already uses i18next, you can add the library's translations to your existing configuration:
-
-```typescript
-import i18n from 'i18next';
-import { initReactI18next } from 'react-i18next';
-import { translationEN } from '@flowuent-labs/diagrams';
-
-i18n
-  .use(initReactI18next)
-  .init({
-    resources: {
-      en: {
-        translation: {
-          // Your app translations
-          ...yourAppTranslations,
-          // Library translations
-          ...translationEN,
-        },
-      },
-    },
-    fallbackLng: 'en',
-    interpolation: {
-      escapeValue: false,
-    },
-  });
-```
-
-## Available Translations
-
-The library currently includes:
-- English (en) - `translationEN`
-
-## Common Issues
-
-### Translation Keys Showing Instead of Text
-
-If you see translation keys (e.g., `tooltip.clear`, `button.save`) instead of actual text, it means i18n is not initialized. Make sure to call `initDiagramsI18n()` before rendering any components.
-
-### Translations Not Working in Production
-
-Ensure your build process includes the `locales` folder from the library. The translation files are automatically included in the npm package.
-
-## API Reference
-
-### `initDiagramsI18n(customResources?: any): i18n`
-
-Initializes or updates the i18next instance with diagram translations.
-
-**Parameters:**
-- `customResources` (optional): Custom translation resources object
-
-**Returns:**
-- The i18next instance
-
-### `translationEN`
-
-The default English translation resource object. Can be imported for customization or extension.
-
-## Example: Complete Setup
-
-```typescript
-// main.tsx or index.tsx
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import { initDiagramsI18n } from '@flowuent-labs/diagrams';
-import App from './App';
-
-// Initialize i18n before rendering
-initDiagramsI18n();
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <App />
-  </React.StrictMode>
-);
-```
-