@flowuent-org/diagramming-core 1.0.6 → 1.0.8

package/TRANSLATION_FIX_SUMMARY.md

@@ -0,0 +1,118 @@
+# Translation Fix Summary
+
+## Problem
+Translation keys (like `tooltip.clear`, `button.save`) were showing instead of actual text when using the published npm library in another app.
+
+## Root Cause
+The translation files were in the `apps/workflow/locales` folder (not part of the library) and were not being bundled with the published npm package. The library code was using `useTranslation()` hooks but had no way to access the translation resources.
+
+## Solution Implemented
+
+### 1. Moved Translation Files to Library
+- ✅ Created `packages/diagrams/locales/en/translation.json`
+- ✅ Copied translation files from apps to library
+
+### 2. Updated Build Configuration
+- ✅ Modified `packages/diagrams/project.json` to include locales folder in build assets
+- ✅ This ensures translations are bundled with the npm package
+
+### 3. Created i18n Configuration
+- ✅ Created `packages/diagrams/src/lib/i18n.ts` with:
+  - `initDiagramsI18n()` - Function to initialize translations
+  - `translationEN` - Export of translation resources
+  - Auto-initialization if i18n not already configured
+
+### 4. Updated Package Dependencies
+- ✅ Added `i18next` and `react-i18next` to package.json dependencies
+
+### 5. Updated Exports
+- ✅ Modified `packages/diagrams/src/index.ts` to export i18n functionality
+
+### 6. Created Documentation
+- ✅ Created `I18N_SETUP.md` with detailed setup instructions
+- ✅ Updated `README.md` with quick start guide
+
+## How Consumers Should Use the Library
+
+### In their main.tsx or index.tsx (BEFORE rendering components):
+
+```typescript
+import { initDiagramsI18n } from '@flowuent-labs/diagrams';
+
+// Initialize i18n
+initDiagramsI18n();
+
+// Then render your app
+ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
+```
+
+## Next Steps
+
+1. **Fix Build Issue** (Separate from i18n):
+   The build is failing due to TypeScript path configuration issues (mixing Unix `/Users` and Windows `C:` paths). This is a pre-existing issue unrelated to the i18n changes. You may need to:
+   - Check your `tsconfig.json` and `tsconfig.lib.json`
+   - Ensure consistent path separators
+   - Or build on a single platform (all Unix or all Windows paths)
+
+2. **Test the Build**:
+   Once the path issue is resolved, rebuild:
+   ```bash
+   nx build diagrams
+   ```
+
+3. **Verify Translation Files Are Included**:
+   After successful build, check `dist/packages/diagrams/locales/` exists
+
+4. **Publish Updated Package**:
+   ```bash
+   cd packages/diagrams
+   npm version patch  # or minor/major
+   npm publish
+   ```
+
+5. **Update Consumer Apps**:
+   In apps using the library:
+   ```bash
+   npm update @flowuent-labs/diagrams
+   ```
+   
+   Then add initialization:
+   ```typescript
+   import { initDiagramsI18n } from '@flowuent-labs/diagrams';
+   initDiagramsI18n(); // Add this before rendering
+   ```
+
+## Alternative: Quick Fix Without Rebuilding
+
+If you need an immediate fix before resolving the build issues, consumers can manually add translations:
+
+```typescript
+import i18n from 'i18next';
+import { initReactI18next } from 'react-i18next';
+
+// Manually import/copy the translation.json content
+const translations = { /* paste translation.json content */ };
+
+i18n.use(initReactI18next).init({
+  resources: {
+    en: {
+      translation: translations
+    }
+  },
+  fallbackLng: 'en',
+  interpolation: {
+    escapeValue: false
+  }
+});
+```
+
+## Files Modified/Created
+
+1. ✅ `packages/diagrams/locales/en/translation.json` (new)
+2. ✅ `packages/diagrams/src/lib/i18n.ts` (new)
+3. ✅ `packages/diagrams/src/index.ts` (modified)
+4. ✅ `packages/diagrams/project.json` (modified - assets config)
+5. ✅ `packages/diagrams/package.json` (modified - added i18n deps)
+6. ✅ `packages/diagrams/README.md` (updated)
+7. ✅ `packages/diagrams/I18N_SETUP.md` (new)
+

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowuent-org/diagramming-core",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "license": "MIT",
   "publishConfig": {
     "access": "public"

package/packages/diagrams/I18N_SETUP.md

@@ -0,0 +1,126 @@
+# 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>
+);
+```
+

package/packages/diagrams/README.md

@@ -1,7 +1,463 @@
-# common
+# @flowuent-labs/diagrams
+
+A comprehensive React diagramming library built with React Flow, providing various diagram types including sequence diagrams, state machines, collaboration diagrams, and more.
+
+## Installation
+
+```bash
+npm install @flowuent-labs/diagrams
+# or
+yarn add @flowuent-labs/diagrams
+```
+
+## Quick Start
+
+### 1. Initialize i18n (Required)
+
+⚠️ **Important**: Before using any components from this library, you must initialize i18n to ensure translations work correctly.
+
+```typescript
+import { initDiagramsI18n } from '@flowuent-labs/diagrams';
+
+// Initialize with default translations
+initDiagramsI18n();
+```
+
+### 2. Use the DiagrammingPage Component
+
+⚠️ **Critical**: You MUST use the complete `DiagrammingPage` component which includes all necessary providers. Do not try to use individual internal components like hooks, atoms, or molecules directly without wrapping them in `DiagrammingPage`.
+
+```typescript
+import { DiagrammingPage } from '@flowuent-labs/diagrams';
+import type { DiagrammingPageRef } from '@flowuent-labs/diagrams';
+
+function App() {
+  const diagramRef = React.useRef<DiagrammingPageRef>(null);
+
+  return (
+    <DiagrammingPage
+      ref={diagramRef}
+      id={1}
+      diagramType="workflow" // or 'sequence', 'state-machine', etc.
+      defaultNodes={[]}
+      defaultEdges={[]}
+      availableFunctions={[]}
+      availableVariables={[]}
+      onChange={(nodes, edges) => {
+        console.log('Diagram changed:', nodes, edges);
+      }}
+    >
+      {/* Optional: Your custom content */}
+    </DiagrammingPage>
+  );
+}
+```
+
+### Required Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `id` | `number` | Unique identifier for the diagram instance |
+| `diagramType` | `DiagramTypes` | Type of diagram: `'workflow'`, `'sequence'`, `'state-machine'`, `'collaboration'`, `'use-case'`, `'system-flow'`, or `'cloud-arch'` |
+| `defaultNodes` | `ICardNode[]` | Initial nodes for the diagram |
+| `defaultEdges` | `Edge[]` | Initial edges for the diagram |
+| `availableFunctions` | `FunctionSignature[]` | Functions available for workflow nodes |
+
+### Optional Props
+
+| Prop | Type | Description |
+|------|------|-------------|
+| `availableVariables` | `AvailableVariable[]` | Variables available in the diagram |
+| `onChange` | `(nodes, edges) => void` | Callback when diagram changes |
+| `onNodeSelect` | `(payload) => void` | Callback when a node is selected |
+| `workflowNodeContent` | `WorkflowNodeContentType` | Custom content for workflow nodes |
+| `renderAddNodeView` | `RenderAddNodeViewType` | Custom add node view renderer |
+| `getDefaultNodeData` | `(type: string) => any` | Function to get default data for new nodes |
+| `conditionBuilderStates` | `ConditionBuilderState` | States for condition builder |
+| `enableNodeJsonPopover` | `boolean` | Enable/disable JSON popover (default: `true`) |
+| `showAutomationExecutionPanel` | `boolean` | Show automation execution panel |
+| `className` | `string` | Custom CSS class for the diagram container |
+
+## i18n Setup
+
+The library includes built-in translation support. For detailed i18n setup instructions, see [I18N_SETUP.md](./I18N_SETUP.md).
+
+### Quick Setup
+
+```typescript
+// In your 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>
+);
+```
+
+### Custom Translations
+
+```typescript
+import { initDiagramsI18n, translationEN } from '@flowuent-labs/diagrams';
+
+initDiagramsI18n({
+  en: {
+    translation: {
+      ...translationEN,
+      // Add your custom translations
+    },
+  },
+  es: {
+    translation: {
+      // Spanish translations
+    },
+  },
+});
+```
+
+## Troubleshooting
+
+### "DiagramStore context provider not initialized" Error
+
+If you see this error, it means you're trying to use internal library components or hooks **outside** of the `DiagrammingPage` component.
+
+**Common Causes:**
+
+1. **Importing internal components directly:**
+   ```typescript
+   // ❌ WRONG - Don't do this
+   import { useDiagram, EntityNode } from '@flowuent-labs/diagrams';
+   
+   function MyComponent() {
+     const nodes = useDiagram(state => state.nodes); // This will fail!
+     return <EntityNode />; // This will also fail!
+   }
+   ```
+
+2. **Not using DiagrammingPage component:**
+   ```typescript
+   // ❌ WRONG
+   import { Stencil, DiagramContainer } from '@flowuent-labs/diagrams';
+   
+   function App() {
+     return <DiagramContainer>...</DiagramContainer>; // Missing provider!
+   }
+   ```
+
+**Solution:**
+
+Always use the complete `DiagrammingPage` component which includes all necessary providers:
+
+```typescript
+// ✅ CORRECT
+import { DiagrammingPage } from '@flowuent-labs/diagrams';
+
+function App() {
+  return (
+    <DiagrammingPage
+      id={1}
+      diagramType="workflow"
+      defaultNodes={[]}
+      defaultEdges={[]}
+      availableFunctions={[]}
+    />
+  );
+}
+```
+
+If you need to extend functionality, pass custom content as children or use the provided callback props like `onChange`, `onNodeSelect`, etc.
+
+### Translation Keys Showing Instead of Text
+
+If you see keys like `tooltip.clear` or `button.save` instead of actual text:
+
+1. Make sure you called `initDiagramsI18n()` before rendering any components
+2. Verify the call is in your main entry file (e.g., `main.tsx` or `index.tsx`)
+3. Ensure the initialization happens before `ReactDOM.render()` or `createRoot()`
+
+Example:
+```typescript
+// ✅ Correct order
+initDiagramsI18n();
+ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
+
+// ❌ Wrong - components render before i18n initializes
+ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
+initDiagramsI18n(); // Too late!
+```
+
+## Features
+
+- Multiple diagram types:
+  - Sequence Diagrams
+  - State Machine Diagrams
+  - Collaboration Diagrams
+  - Use Case Diagrams
+  - System Flow Diagrams
+  - Cloud Architecture Diagrams
+  - Workflow/Automation Diagrams
+- Built-in i18n support
+- Customizable styling and themes
+- Export to JSON and images
+- Import/Export functionality
+- Undo/Redo support
+
+## Complete Working Example
+
+Here's a complete, minimal example to get you started:
+
+```typescript
+// main.tsx or index.tsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { initDiagramsI18n, DiagrammingPage } from '@flowuent-labs/diagrams';
+import '@xyflow/react/dist/style.css'; // Required for React Flow styles
+
+// Step 1: Initialize i18n BEFORE rendering
+initDiagramsI18n();
+
+// Step 2: Create your App component
+function App() {
+  const diagramRef = React.useRef(null);
+
+  const handleDiagramChange = (nodes, edges) => {
+    console.log('Diagram updated:', { nodes, edges });
+  };
+
+  return (
+    <div style={{ width: '100vw', height: '100vh' }}>
+      <DiagrammingPage
+        ref={diagramRef}
+        id={1}
+        diagramType="workflow"
+        defaultNodes={[]}
+        defaultEdges={[]}
+        availableFunctions={[]}
+        onChange={handleDiagramChange}
+      />
+    </div>
+  );
+}
+
+// Step 3: Render your app
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);
+```
+
+## Using with Imperative Methods
+
+The `DiagrammingPage` component exposes several methods through a ref:
+
+```typescript
+import { DiagrammingPage, DiagrammingPageRef } from '@flowuent-labs/diagrams';
+
+function App() {
+  const diagramRef = React.useRef<DiagrammingPageRef>(null);
+
+  const handleUndo = () => {
+    diagramRef.current?.undo();
+  };
+
+  const handleRedo = () => {
+    diagramRef.current?.redo();
+  };
+
+  const handleReset = () => {
+    diagramRef.current?.reset();
+  };
+
+  const getSelectedNode = () => {
+    const nodeId = diagramRef.current?.getSelectedNode();
+    if (nodeId) {
+      const nodeData = diagramRef.current?.getNodeData(nodeId);
+      console.log('Selected node data:', nodeData);
+    }
+  };
+
+  const updateNode = (nodeId: string, data: any) => {
+    const success = diagramRef.current?.updateNodeData(nodeId, data);
+    console.log('Node updated:', success);
+  };
+
+  return (
+    <div>
+      <div>
+        <button onClick={handleUndo}>Undo</button>
+        <button onClick={handleRedo}>Redo</button>
+        <button onClick={handleReset}>Reset</button>
+        <button onClick={getSelectedNode}>Get Selected Node</button>
+      </div>
+      <DiagrammingPage
+        ref={diagramRef}
+        id={1}
+        diagramType="workflow"
+        defaultNodes={[]}
+        defaultEdges={[]}
+        availableFunctions={[]}
+      />
+    </div>
+  );
+}
+```
+
+### Available Ref Methods
+
+- `undo()` - Undo last change
+- `redo()` - Redo last undone change
+- `canUndo()` - Check if undo is available
+- `canRedo()` - Check if redo is available
+- `reset()` - Clear the diagram
+- `getHistoryLength()` - Get history stack length
+- `getHistoryIndex()` - Get current history position
+- `getNodeData(nodeId)` - Get data for a specific node
+- `updateNodeData(nodeId, data)` - Update a specific node's data
+- `getSelectedNode()` - Get ID of currently selected node
+- `getNodes()` - Get all nodes
+- `getEdges()` - Get all edges
+
+## Automation Workflows
+
+The library includes powerful automation workflow capabilities with an execution engine and UI panel.
+
+### Using AutomationExecutionPanel
+
+The `AutomationExecutionPanel` component provides a UI for executing automation workflows with real-time status updates:
+
+```typescript
+import { useState } from 'react';
+import { useNodesState, useEdgesState } from '@xyflow/react';
+import { AutomationExecutionPanel } from '@flowuent-labs/diagrams';
+
+function MyWorkflow() {
+  const [nodes, setNodes, onNodesChange] = useNodesState([]);
+  const [edges, setEdges, onEdgesChange] = useEdgesState([]);
+
+  // CRITICAL: You must provide onNodeUpdate callback to see status changes
+  const handleNodeUpdate = (nodeId: string, updatedData: any) => {
+    setNodes((nds) =>
+      nds.map((node) => {
+        if (node.id === nodeId) {
+          return { ...node, data: { ...node.data, ...updatedData } };
+        }
+        return node;
+      })
+    );
+  };
+
+  return (
+    <div>
+      {/* Your React Flow diagram */}
+      <AutomationExecutionPanel
+        nodes={nodes}
+        edges={edges}
+        workflowId="my-workflow-1"
+        onNodeUpdate={handleNodeUpdate} // MUST provide this!
+      />
+    </div>
+  );
+}
+```
+
+### Why onNodeUpdate is Required
+
+The `AutomationExecutionEngine` updates node status during execution (`Ready` → `Running` → `Completed` / `Error`). Without the `onNodeUpdate` callback:
+- ❌ Node status changes won't trigger React re-renders
+- ❌ UI won't show real-time execution progress
+- ❌ Visual feedback will be missing
+
+With `onNodeUpdate`:
+- ✅ Real-time status updates in the UI
+- ✅ Visual feedback as nodes execute
+- ✅ Proper React state synchronization
+
+**Important**: The engine creates new object references when calling `onNodeUpdate` to ensure React detects changes. Make sure your callback updates state properly:
+
+```typescript
+const handleNodeUpdate = (nodeId: string, updatedData: any) => {
+  setNodes((nds) =>
+    nds.map((node) => {
+      if (node.id === nodeId) {
+        // This creates a new node object with updated data
+        return { ...node, data: updatedData };
+      }
+      return node;
+    })
+  );
+};
+```
+
+### Using AutomationExecutionEngine Directly
+
+You can also use the execution engine programmatically:
+
+```typescript
+import { AutomationExecutionEngine } from '@flowuent-labs/diagrams';
+import type { AutomationLog, AutomationResult } from '@flowuent-labs/diagrams';
+
+async function executeWorkflow(nodes, edges) {
+  const engine = new AutomationExecutionEngine(
+    nodes,
+    edges,
+    // onNodeUpdate callback - updates node status in real-time
+    (nodeId, updatedData) => {
+      console.log(`Node ${nodeId} updated:`, updatedData);
+      // Update your state here to reflect changes in UI
+    },
+    // onLog callback - streams execution logs
+    (log: AutomationLog) => {
+      console.log(`[${log.level}] ${log.message}`);
+    }
+  );
+
+  try {
+    const result: AutomationResult = await engine.executeWorkflow();
+    console.log('Workflow completed:', result);
+    return result;
+  } catch (error) {
+    console.error('Workflow failed:', error);
+    throw error;
+  }
+}
+```
+
+### Available Automation Node Types
+
+The library exports these automation node components:
+- `AutomationStartNode` - Workflow entry point
+- `AutomationApiNode` - HTTP API calls
+- `AutomationFormattingNode` - Data transformation
+- `AutomationSheetsNode` - Google Sheets integration
+- `AutomationAISuggestionNode` - AI-powered suggestions
+- `AutomationNoteNode` - Documentation/comments
+- `AutomationEndNode` - Workflow exit point
+
+All node types and their data structures are exported from the library.
+
+## Development
 
 This library was generated with [Nx](https://nx.dev).
 
-## Running unit tests
+### Building
+
+```bash
+nx build diagrams
+```
+
+### Running unit tests
+
+```bash
+nx test diagrams
+```
+
+## License
 
-Run `nx test common` to execute the unit tests via [Jest](https://jestjs.io).
+MIT