@flowuent-org/diagramming-core 1.0.8 → 1.1.1

package/packages/diagrams/README.md

@@ -1,463 +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
-
-**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).
-
-### 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).