@memberjunction/ng-flow-editor 0.0.1 → 4.1.0

package/README.md

@@ -1,45 +1,153 @@
 # @memberjunction/ng-flow-editor
 
-## ⚠️ IMPORTANT NOTICE ⚠️
-
-**This package is created solely for the purpose of setting up OIDC (OpenID Connect) trusted publishing with npm.**
-
-This is **NOT** a functional package and contains **NO** code or functionality beyond the OIDC setup configuration.
-
-## Purpose
-
-This package exists to:
-1. Configure OIDC trusted publishing for the package name `@memberjunction/ng-flow-editor`
-2. Enable secure, token-less publishing from CI/CD workflows
-3. Establish provenance for packages published under this name
-
-## What is OIDC Trusted Publishing?
-
-OIDC trusted publishing allows package maintainers to publish packages directly from their CI/CD workflows without needing to manage npm access tokens. Instead, it uses OpenID Connect to establish trust between the CI/CD provider (like GitHub Actions) and npm.
-
-## Setup Instructions
-
-To properly configure OIDC trusted publishing for this package:
-
-1. Go to [npmjs.com](https://www.npmjs.com/) and navigate to your package settings
-2. Configure the trusted publisher (e.g., GitHub Actions)
-3. Specify the repository and workflow that should be allowed to publish
-4. Use the configured workflow to publish your actual package
-
-## DO NOT USE THIS PACKAGE
-
-This package is a placeholder for OIDC configuration only. It:
-- Contains no executable code
-- Provides no functionality
-- Should not be installed as a dependency
-- Exists only for administrative purposes
-
-## More Information
-
-For more details about npm's trusted publishing feature, see:
-- [npm Trusted Publishing Documentation](https://docs.npmjs.com/generating-provenance-statements)
-- [GitHub Actions OIDC Documentation](https://docs.github.com/en/actions/deployment/security-hardening-your-deployments/about-security-hardening-with-openid-connect)
-
----
-
-**Maintained for OIDC setup purposes only**
+A generic, entity-agnostic visual flow editor component powered by Foblex Flow, with an agent-specific Flow Agent Editor for building AI agent workflows.
+
+## Installation
+
+```bash
+npm install @memberjunction/ng-flow-editor
+```
+
+## Overview
+
+The Flow Editor provides a canvas-based visual editor for building node-and-connection graphs. It wraps [Foblex Flow](https://www.foblex.com/flow) with a clean MemberJunction-style API and includes automatic layout via the Dagre graph algorithm. A specialized Agent Editor component is also included for visually designing AI agent step flows.
+
+```mermaid
+flowchart TD
+    subgraph Generic["Generic Flow Editor"]
+        A["FlowEditorComponent"] --> B["FlowNodeComponent"]
+        A --> C["FlowPaletteComponent"]
+        A --> D["FlowToolbarComponent"]
+        A --> E["FlowStatusBarComponent"]
+    end
+    subgraph Agent["Agent Editor"]
+        F["FlowAgentEditorComponent"] --> G["AgentPropertiesPanelComponent"]
+        F --> H["AgentStepListComponent"]
+        F --> I["AgentFlowTransformerService"]
+        I --> A
+    end
+    subgraph Services["Services"]
+        J["FlowStateService"]
+        K["FlowLayoutService (Dagre)"]
+    end
+
+    A --> J
+    A --> K
+
+    style Generic fill:#2d6a9f,stroke:#1a4971,color:#fff
+    style Agent fill:#7c5295,stroke:#563a6b,color:#fff
+    style Services fill:#2d8659,stroke:#1a5c3a,color:#fff
+```
+
+## Usage
+
+### Module Import
+
+```typescript
+import { FlowEditorModule } from '@memberjunction/ng-flow-editor';
+
+@NgModule({
+  imports: [FlowEditorModule]
+})
+export class YourModule {}
+```
+
+### Basic Flow Editor
+
+```html
+<mj-flow-editor
+  [Nodes]="myNodes"
+  [Connections]="myConnections"
+  [NodeTypes]="myNodeTypes"
+  [ShowMinimap]="true"
+  [ShowPalette]="true"
+  [ShowGrid]="true"
+  (NodeSelected)="onNodeSelected($event)"
+  (ConnectionCreated)="onConnectionCreated($event)"
+  (NodesChanged)="onNodesChanged($event)">
+</mj-flow-editor>
+```
+
+### Agent Flow Editor
+
+```html
+<mj-flow-agent-editor
+  [AgentId]="selectedAgentId"
+  [ReadOnly]="false"
+  (StepSelected)="onStepSelected($event)"
+  (FlowChanged)="onFlowChanged($event)">
+</mj-flow-agent-editor>
+```
+
+## Components
+
+| Component | Selector | Purpose |
+|-----------|----------|---------|
+| `FlowEditorComponent` | `mj-flow-editor` | Generic canvas-based flow editor |
+| `FlowNodeComponent` | internal | Renders individual nodes on the canvas |
+| `FlowPaletteComponent` | internal | Draggable palette of node types |
+| `FlowToolbarComponent` | internal | Toolbar with zoom, layout, grid controls |
+| `FlowStatusBarComponent` | internal | Displays node/connection counts |
+| `FlowAgentEditorComponent` | `mj-flow-agent-editor` | Agent-specific flow editor wrapper |
+| `AgentPropertiesPanelComponent` | internal | Agent property editing panel |
+| `AgentStepListComponent` | internal | List of agent steps |
+
+## FlowEditorComponent API
+
+### Inputs
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `Nodes` | `FlowNode[]` | `[]` | Array of flow nodes |
+| `Connections` | `FlowConnection[]` | `[]` | Array of connections between nodes |
+| `NodeTypes` | `FlowNodeTypeConfig[]` | `[]` | Available node type definitions |
+| `ReadOnly` | `boolean` | `false` | Disable editing |
+| `ShowMinimap` | `boolean` | `true` | Show minimap overlay |
+| `ShowPalette` | `boolean` | `true` | Show the node palette |
+| `ShowGrid` | `boolean` | `true` | Show background grid |
+| `ShowStatusBar` | `boolean` | `true` | Show the status bar |
+| `ShowToolbar` | `boolean` | `true` | Show the toolbar |
+| `ShowLegend` | `boolean` | `true` | Show the node type legend |
+| `GridSize` | `number` | `20` | Grid snap size in pixels |
+| `AutoLayoutDirection` | `FlowLayoutDirection` | `'vertical'` | Dagre auto-layout direction |
+
+### Outputs
+
+| Event | Type | Description |
+|-------|------|-------------|
+| `NodeSelected` | `EventEmitter<FlowNode \| null>` | A node was selected or deselected |
+| `NodeAdded` | `EventEmitter<FlowNodeAddedEvent>` | A node was added to the canvas |
+| `NodeRemoved` | `EventEmitter<FlowNode>` | A node was removed |
+| `NodeMoved` | `EventEmitter<FlowNodeMovedEvent>` | A node was repositioned |
+| `ConnectionCreated` | `EventEmitter<FlowConnectionCreatedEvent>` | A connection was created |
+| `ConnectionRemoved` | `EventEmitter<FlowConnection>` | A connection was removed |
+| `ConnectionReassigned` | `EventEmitter<FlowConnectionReassignedEvent>` | A connection endpoint was moved |
+| `SelectionChanged` | `EventEmitter<FlowSelectionChangedEvent>` | Selection state changed |
+| `NodesChanged` | `EventEmitter<FlowNode[]>` | The nodes array was modified |
+| `ConnectionsChanged` | `EventEmitter<FlowConnection[]>` | The connections array was modified |
+| `NodeEditRequested` | `EventEmitter<FlowNode>` | Double-click to edit a node |
+
+## Exported Types
+
+- `FlowNode` -- A node on the canvas with id, type, label, position, size, ports, badges
+- `FlowConnection` -- A connection between two node ports with optional label
+- `FlowNodeTypeConfig` -- Configuration for a node type (icon, color, ports, palette info)
+- `FlowNodePort` -- Input/output port definition
+- `FlowPosition` / `FlowSize` -- Position and size types
+- `FlowSnapshot` -- Serializable snapshot of the entire flow state
+- `FlowLayoutDirection` -- `'vertical' | 'horizontal'`
+
+## Services
+
+| Service | Purpose |
+|---------|---------|
+| `FlowStateService` | Manages undo/redo, snapshots, dirty state |
+| `FlowLayoutService` | Dagre-based auto-layout for flow graphs |
+| `AgentFlowTransformerService` | Transforms MJ Agent entities into flow graph data |
+
+## Dependencies
+
+- [@memberjunction/core](../../MJCore/README.md) -- Core MJ functionality
+- [@memberjunction/core-entities](../../MJCoreEntities/README.md) -- Entity types for agent editor
+- `@foblex/flow` -- Canvas rendering engine
+- `@dagrejs/dagre` -- Graph layout algorithm

package/dist/lib/agent-editor/agent-flow-transformer.service.d.ts

@@ -0,0 +1,83 @@
+import { AIAgentStepEntity, AIAgentStepPathEntity } from '@memberjunction/core-entities';
+import { FlowNode, FlowConnection, FlowNodeTypeConfig } from '../interfaces/flow-types';
+import * as i0 from "@angular/core";
+/** Picker item shape for Actions with optional icon */
+export interface ActionPickerItem {
+    ID: string;
+    Name: string;
+    IconClass?: string | null;
+}
+/** Picker item shape for Agents with optional icon and logo */
+export interface AgentPickerItem {
+    ID: string;
+    Name: string;
+    IconClass?: string | null;
+    LogoURL?: string | null;
+}
+/** Step types mapped to visual configuration */
+export declare const AGENT_STEP_TYPE_CONFIGS: FlowNodeTypeConfig[];
+/**
+ * Transforms MJ AIAgentStep/Path entities to/from generic FlowNode/FlowConnection models.
+ */
+export declare class AgentFlowTransformerService {
+    /** Convert MJ step entities to generic FlowNodes */
+    StepsToNodes(steps: AIAgentStepEntity[], actions?: ActionPickerItem[], agents?: AgentPickerItem[]): FlowNode[];
+    /** Convert MJ path entities to generic FlowConnections */
+    PathsToConnections(paths: AIAgentStepPathEntity[]): FlowConnection[];
+    /** Build the subtitle for a step based on its configured action/prompt/agent */
+    BuildStepSubtitle(step: AIAgentStepEntity): string;
+    /** Apply FlowNode position changes back to a step entity */
+    ApplyNodePosition(step: AIAgentStepEntity, node: FlowNode): void;
+    /** Map FlowNode status from step entity status */
+    MapStepStatus(stepStatus: string): FlowNode['Status'];
+    /**
+     * Returns a short human-readable message describing what's missing,
+     * or null if the step is fully configured.
+     */
+    BuildConfigWarningMessage(step: AIAgentStepEntity): string | null;
+    private buildLoopWarningMessage;
+    /**
+     * Returns true when a step is missing its required configuration reference
+     * (e.g., an Action step with no ActionID, a Prompt step with no PromptID).
+     */
+    IsStepMissingConfiguration(step: AIAgentStepEntity): boolean;
+    private isLoopBodyMissingReference;
+    /**
+     * Resolve the best icon and optional logo URL for a step based on its
+     * configured action/agent and available picker data.
+     *
+     * Resolution chain:
+     * - Action step: action's IconClass -> step-type fallback
+     * - Sub-Agent step: agent's LogoURL (stored in Data) -> agent's IconClass -> step-type fallback
+     * - Other steps: step-type icon
+     */
+    ResolveStepIcon(step: AIAgentStepEntity, actions?: ActionPickerItem[], agents?: AgentPickerItem[]): {
+        Icon: string;
+        LogoURL?: string | null;
+    };
+    private resolveLoopBodyIcon;
+    /** Convert a single MJ step entity to a FlowNode (public for direct use when adding nodes) */
+    StepToNode(step: AIAgentStepEntity, actions?: ActionPickerItem[], agents?: AgentPickerItem[]): FlowNode;
+    private pathToConnection;
+    private buildPathVisuals;
+    /** Populate loop-specific display data on the node's Data payload */
+    private populateLoopData;
+    /** Resolve the best icon for a loop body, checking picker data first */
+    private resolveLoopBodySpecificIcon;
+    /** Get icon for a loop body type */
+    private getBodyTypeIcon;
+    /** Get color for a loop body type */
+    private getBodyTypeColor;
+    private getIconForType;
+    private buildLoopSubtitle;
+    /** Resolve the display name for the loop body operation */
+    private resolveLoopBodyName;
+    /** Parse the Configuration JSON, returning null on failure */
+    private parseLoopConfig;
+    /** Build a short iteration summary for display on loop nodes */
+    BuildLoopIterationSummary(step: AIAgentStepEntity): string;
+    private truncateCondition;
+    static ɵfac: i0.ɵɵFactoryDeclaration<AgentFlowTransformerService, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<AgentFlowTransformerService>;
+}
+//# sourceMappingURL=agent-flow-transformer.service.d.ts.map

package/dist/lib/agent-editor/agent-flow-transformer.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-flow-transformer.service.d.ts","sourceRoot":"","sources":["../../../src/lib/agent-editor/agent-flow-transformer.service.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,iBAAiB,EAAE,qBAAqB,EAAE,MAAM,+BAA+B,CAAC;AACzF,OAAO,EAAE,QAAQ,EAAE,cAAc,EAAuB,kBAAkB,EAAgB,MAAM,0BAA0B,CAAC;;AAE3H,uDAAuD;AACvD,MAAM,WAAW,gBAAgB;IAAG,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAAE;AAE1F,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAAG,EAAE,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAAE;AAElH,gDAAgD;AAChD,eAAO,MAAM,uBAAuB,EAAE,kBAAkB,EAwDvD,CAAC;AAEF;;GAEG;AACH,qBACa,2BAA2B;IAEtC,oDAAoD;IACpD,YAAY,CACV,KAAK,EAAE,iBAAiB,EAAE,EAC1B,OAAO,CAAC,EAAE,gBAAgB,EAAE,EAC5B,MAAM,CAAC,EAAE,eAAe,EAAE,GACzB,QAAQ,EAAE;IAIb,0DAA0D;IAC1D,kBAAkB,CAAC,KAAK,EAAE,qBAAqB,EAAE,GAAG,cAAc,EAAE;IAIpE,gFAAgF;IAChF,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM;IAiBlD,4DAA4D;IAC5D,iBAAiB,CAAC,IAAI,EAAE,iBAAiB,EAAE,IAAI,EAAE,QAAQ,GAAG,IAAI;IAShE,kDAAkD;IAClD,aAAa,CAAC,UAAU,EAAE,MAAM,GAAG,QAAQ,CAAC,QAAQ,CAAC;IASrD;;;OAGG;IACH,yBAAyB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,GAAG,IAAI;IAgBjE,OAAO,CAAC,uBAAuB;IAW/B;;;OAGG;IACH,0BAA0B,CAAC,IAAI,EAAE,iBAAiB,GAAG,OAAO;IAgB5D,OAAO,CAAC,0BAA0B;IAWlC;;;;;;;;OAQG;IACH,eAAe,CACb,IAAI,EAAE,iBAAiB,EACvB,OAAO,CAAC,EAAE,gBAAgB,EAAE,EAC5B,MAAM,CAAC,EAAE,eAAe,EAAE,GACzB;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;KAAE;IAwB5C,OAAO,CAAC,mBAAmB;IAsB3B,8FAA8F;IAC9F,UAAU,CACR,IAAI,EAAE,iBAAiB,EACvB,OAAO,CAAC,EAAE,gBAAgB,EAAE,EAC5B,MAAM,CAAC,EAAE,eAAe,EAAE,GACzB,QAAQ;IA0DX,OAAO,CAAC,gBAAgB;IAwCxB,OAAO,CAAC,gBAAgB;IAgDxB,qEAAqE;IACrE,OAAO,CAAC,gBAAgB;IA4BxB,wEAAwE;IACxE,OAAO,CAAC,2BAA2B;IAmBnC,oCAAoC;IACpC,OAAO,CAAC,eAAe;IASvB,qCAAqC;IACrC,OAAO,CAAC,gBAAgB;IASxB,OAAO,CAAC,cAAc;IAKtB,OAAO,CAAC,iBAAiB;IAOzB,2DAA2D;IAC3D,OAAO,CAAC,mBAAmB;IAS3B,8DAA8D;IAC9D,OAAO,CAAC,eAAe;IASvB,gEAAgE;IAChE,yBAAyB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM;IAa1D,OAAO,CAAC,iBAAiB;yCAzbd,2BAA2B;6CAA3B,2BAA2B;CA8bvC"}