@flowuent-org/diagramming-core 1.0.7 → 1.1.0

package/packages/diagrams/README.md

@@ -1,447 +1,7 @@
-# @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
-
-### 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).
-
-### Building
-
-```bash
-nx build diagrams
-```
-
-### Running unit tests
-
-```bash
-nx test diagrams
-```
-
-## License
-
-MIT
+# common
+
+This library was generated with [Nx](https://nx.dev).
+
+## Running unit tests
+
+Run `nx test common` to execute the unit tests via [Jest](https://jestjs.io).

package/packages/diagrams/package.json

@@ -1,23 +1,54 @@
 {
-  "name": "@flowuent-labs/diagrams",
-  "version": "0.0.1",
+  "name": "@flowuent-org/diagrams",
+  "version": "0.3.4",
+  "description": "A powerful React diagramming library built on React Flow",
+  "main": "./index.js",
+  "types": "./index.d.ts",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/flowuent/diagramming-examples.git"
+  },
+  "keywords": [
+    "react",
+    "reactflow",
+    "diagram",
+    "flow",
+    "visualization",
+    "automation",
+    "workflow"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "react-dom": ">=18.0.0"
+  },
   "scripts": {
     "build": "nx build diagrams",
     "generate-barrels": "ctix build"
   },
   "dependencies": {
     "@mui/material": "^6.1.6",
+    "@mui/icons-material": "^6.1.8",
     "@types/js-beautify": "^1.14.3",
+    "@xyflow/react": "^12.3.5",
     "core-js": "^3.38.1",
     "file-saver": "^2.0.5",
     "highlight.js": "^11.10.0",
     "i18next": "^24.0.2",
     "js-beautify": "^1.15.1",
     "prettier": "^3.3.3",
+    "react": "19.0.0",
     "react-copy-to-clipboard": "^5.1.0",
+    "react-dom": "19.0.0",
     "react-i18next": "^15.1.2",
+    "react-icons": "^5.3.0",
+    "react-json-view": "^1.21.3",
     "react-syntax-highlighter": "^15.6.1",
-    "xlsx": "^0.18.5"
+    "xlsx": "^0.18.5",
+    "zustand": "^5.0.1"
   },
   "devDependencies": {
     "@types/file-saver": "^2.0.7",

package/tsconfig.base.json

@@ -1,30 +1,30 @@
-{
-  "compileOnSave": false,
-  "compilerOptions": {
-    "rootDir": ".",
-    "sourceMap": true,
-    "declaration": false,
-    "moduleResolution": "node",
-    "emitDecoratorMetadata": true,
-    "experimentalDecorators": true,
-    "importHelpers": true,
-    "target": "es2015",
-    "module": "esnext",
-    "lib": ["es2020", "dom"],
-    "skipLibCheck": true,
-    "skipDefaultLibCheck": true,
-    "baseUrl": ".",
-    "paths": {
-      "@flowuent-labs/api": ["packages/api/src/index.ts"],
-      "@flowuent-labs/atoms": ["packages/atoms/src/index.ts"],
-      "@flowuent-labs/common": ["packages/common/src/index.ts"],
-      "@flowuent-labs/contexts": ["packages/contexts/src/index.ts"],
-      "@flowuent-labs/diagrams": ["packages/diagrams/src/index.ts"],
-      "@flowuent-labs/interfaces": ["packages/interfaces/src/index.ts"],
-      "@flowuent-labs/molecules": ["packages/molecules/src/index.ts"],
-      "@flowuent-labs/organisms": ["packages/organisms/src/index.ts"],
-      "@flowuent-labs/zustand": ["packages/zustand/src/index.ts"]
-    }
-  },
-  "exclude": ["node_modules", "tmp"]
-}
+{
+  "compileOnSave": false,
+  "compilerOptions": {
+    "rootDir": ".",
+    "sourceMap": true,
+    "declaration": false,
+    "moduleResolution": "node",
+    "emitDecoratorMetadata": true,
+    "experimentalDecorators": true,
+    "importHelpers": true,
+    "target": "es2015",
+    "module": "esnext",
+    "lib": ["es2020", "dom"],
+    "skipLibCheck": true,
+    "skipDefaultLibCheck": true,
+    "baseUrl": ".",
+    "paths": {
+      "@flowuent-labs/api": ["packages/api/src/index.ts"],
+      "@flowuent-labs/atoms": ["packages/atoms/src/index.ts"],
+      "@flowuent-labs/common": ["packages/common/src/index.ts"],
+      "@flowuent-labs/contexts": ["packages/contexts/src/index.ts"],
+      "@flowuent-labs/diagrams": ["packages/diagrams/src/index.ts"],
+      "@flowuent-labs/interfaces": ["packages/interfaces/src/index.ts"],
+      "@flowuent-labs/molecules": ["packages/molecules/src/index.ts"],
+      "@flowuent-labs/organisms": ["packages/organisms/src/index.ts"],
+      "@flowuent-labs/zustand": ["packages/zustand/src/index.ts"]
+    }
+  },
+  "exclude": ["node_modules", "tmp"]
+}

package/.vscode/settings.json

@@ -1,6 +0,0 @@
-{
-  "folder-path-color.folders": [
-    { "path": "packages/diagrams", "symbol": "T", "tooltip": "diagrams" , "color": "red"}
-  ],
-  "nxConsole.generateAiAgentRules": true
-}

package/TRANSLATION_FIX_SUMMARY.md

@@ -1,118 +0,0 @@
-# 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)
-