@d34dman/flowdrop 0.0.15 → 0.0.16

package/dist/stores/workflowStore.js

@@ -1,19 +1,176 @@
-import { writable, derived } from 'svelte/store';
-// Global workflow state
+/**
+ * Workflow Store for FlowDrop
+ *
+ * Provides global state management for workflows with dirty state tracking.
+ *
+ * @module stores/workflowStore
+ */
+import { writable, derived, get } from "svelte/store";
+// =========================================================================
+// Core Workflow Store
+// =========================================================================
+/** Global workflow state */
 export const workflowStore = writable(null);
-// Derived stores for individual workflow properties
-export const workflowId = derived(workflowStore, ($workflow) => $workflow?.id || null);
-export const workflowName = derived(workflowStore, ($workflow) => $workflow?.name || 'Untitled Workflow');
-export const workflowNodes = derived(workflowStore, ($workflow) => $workflow?.nodes || []);
-export const workflowEdges = derived(workflowStore, ($workflow) => $workflow?.edges || []);
-export const workflowMetadata = derived(workflowStore, ($workflow) => $workflow?.metadata || {
-    version: '1.0.0',
+// =========================================================================
+// Dirty State Tracking
+// =========================================================================
+/**
+ * Store for tracking if there are unsaved changes
+ *
+ * This is set to true whenever the workflow changes after initialization.
+ * It can be reset to false by calling markAsSaved().
+ */
+export const isDirtyStore = writable(false);
+/**
+ * Snapshot of the workflow when it was last saved
+ *
+ * Used to compare current state with saved state.
+ */
+let savedSnapshot = null;
+/**
+ * Callback for dirty state changes
+ *
+ * Set by the App component to notify parent application.
+ */
+let onDirtyStateChangeCallback = null;
+/**
+ * Callback for workflow changes
+ *
+ * Set by the App component to notify parent application.
+ */
+let onWorkflowChangeCallback = null;
+/**
+ * Set the dirty state change callback
+ *
+ * @param callback - Function to call when dirty state changes
+ */
+export function setOnDirtyStateChange(callback) {
+    onDirtyStateChangeCallback = callback;
+}
+/**
+ * Set the workflow change callback
+ *
+ * @param callback - Function to call when workflow changes
+ */
+export function setOnWorkflowChange(callback) {
+    onWorkflowChangeCallback = callback;
+}
+/**
+ * Create a snapshot of the workflow for comparison
+ *
+ * @param workflow - The workflow to snapshot
+ * @returns A JSON string representation for comparison
+ */
+function createSnapshot(workflow) {
+    if (!workflow)
+        return null;
+    // Only include the parts that matter for "dirty" detection
+    const toSnapshot = {
+        name: workflow.name,
+        description: workflow.description,
+        nodes: workflow.nodes.map((n) => ({
+            id: n.id,
+            position: n.position,
+            data: {
+                label: n.data.label,
+                config: n.data.config
+            }
+        })),
+        edges: workflow.edges.map((e) => ({
+            id: e.id,
+            source: e.source,
+            target: e.target,
+            sourceHandle: e.sourceHandle,
+            targetHandle: e.targetHandle
+        }))
+    };
+    return JSON.stringify(toSnapshot);
+}
+/**
+ * Update dirty state based on current workflow
+ *
+ * Compares current workflow with saved snapshot.
+ */
+function updateDirtyState() {
+    const currentWorkflow = get(workflowStore);
+    const currentSnapshot = createSnapshot(currentWorkflow);
+    const isDirty = currentSnapshot !== savedSnapshot;
+    const previousDirty = get(isDirtyStore);
+    if (isDirty !== previousDirty) {
+        isDirtyStore.set(isDirty);
+        if (onDirtyStateChangeCallback) {
+            onDirtyStateChangeCallback(isDirty);
+        }
+    }
+}
+/**
+ * Mark the workflow change and update dirty state
+ *
+ * @param changeType - The type of change that occurred
+ */
+function notifyWorkflowChange(changeType) {
+    const workflow = get(workflowStore);
+    if (workflow && onWorkflowChangeCallback) {
+        onWorkflowChangeCallback(workflow, changeType);
+    }
+    updateDirtyState();
+}
+/**
+ * Mark the current workflow state as saved
+ *
+ * Clears the dirty state by updating the saved snapshot.
+ */
+export function markAsSaved() {
+    const currentWorkflow = get(workflowStore);
+    savedSnapshot = createSnapshot(currentWorkflow);
+    isDirtyStore.set(false);
+    if (onDirtyStateChangeCallback) {
+        onDirtyStateChangeCallback(false);
+    }
+}
+/**
+ * Check if there are unsaved changes
+ *
+ * @returns true if there are unsaved changes
+ */
+export function isDirty() {
+    return get(isDirtyStore);
+}
+/**
+ * Get the current workflow
+ *
+ * @returns The current workflow or null
+ */
+export function getWorkflow() {
+    return get(workflowStore);
+}
+// =========================================================================
+// Derived Stores
+// =========================================================================
+/** Derived store for workflow ID */
+export const workflowId = derived(workflowStore, ($workflow) => $workflow?.id ?? null);
+/** Derived store for workflow name */
+export const workflowName = derived(workflowStore, ($workflow) => $workflow?.name ?? "Untitled Workflow");
+/** Derived store for workflow nodes */
+export const workflowNodes = derived(workflowStore, ($workflow) => $workflow?.nodes ?? []);
+/** Derived store for workflow edges */
+export const workflowEdges = derived(workflowStore, ($workflow) => $workflow?.edges ?? []);
+/** Derived store for workflow metadata */
+export const workflowMetadata = derived(workflowStore, ($workflow) => $workflow?.metadata ?? {
+    version: "1.0.0",
     createdAt: new Date().toISOString(),
     updatedAt: new Date().toISOString(),
     versionId: `${Date.now()}-${Math.random().toString(36).substr(2, 9)}`,
     updateNumber: 0
 });
-// Helper function to check if workflow data has actually changed
+// =========================================================================
+// Helper Functions
+// =========================================================================
+/**
+ * Check if workflow data has actually changed
+ *
+ * Used to prevent unnecessary updates and infinite loops.
+ */
 function hasWorkflowDataChanged(currentWorkflow, newNodes, newEdges) {
     if (!currentWorkflow)
         return true;
@@ -48,17 +205,40 @@ function hasWorkflowDataChanged(currentWorkflow, newNodes, newEdges) {
     }
     return false;
 }
-// Actions for updating the workflow
+// =========================================================================
+// Workflow Actions
+// =========================================================================
+/**
+ * Actions for updating the workflow
+ *
+ * All actions that modify the workflow will trigger dirty state updates
+ * and emit change events.
+ */
 export const workflowActions = {
-    // Initialize workflow
+    /**
+     * Initialize workflow (from load or new)
+     *
+     * This sets the initial saved snapshot and clears dirty state.
+     */
     initialize: (workflow) => {
         workflowStore.set(workflow);
+        // Set the saved snapshot - workflow is "clean" after initialization
+        savedSnapshot = createSnapshot(workflow);
+        isDirtyStore.set(false);
+        if (onDirtyStateChangeCallback) {
+            onDirtyStateChangeCallback(false);
+        }
     },
-    // Update the entire workflow
+    /**
+     * Update the entire workflow
+     */
     updateWorkflow: (workflow) => {
         workflowStore.set(workflow);
+        notifyWorkflowChange("metadata");
     },
-    // Update nodes
+    /**
+     * Update nodes
+     */
     updateNodes: (nodes) => {
         workflowStore.update(($workflow) => {
             if (!$workflow)
@@ -76,12 +256,15 @@ export const workflowActions = {
                     ...$workflow.metadata,
                     updatedAt: new Date().toISOString(),
                     versionId,
-                    updateNumber: ($workflow.metadata?.updateNumber || 0) + 1
+                    updateNumber: ($workflow.metadata?.updateNumber ?? 0) + 1
                 }
             };
         });
+        notifyWorkflowChange("node_move");
     },
-    // Update edges
+    /**
+     * Update edges
+     */
     updateEdges: (edges) => {
         workflowStore.update(($workflow) => {
             if (!$workflow)
@@ -99,12 +282,15 @@ export const workflowActions = {
                     ...$workflow.metadata,
                     updatedAt: new Date().toISOString(),
                     versionId,
-                    updateNumber: ($workflow.metadata?.updateNumber || 0) + 1
+                    updateNumber: ($workflow.metadata?.updateNumber ?? 0) + 1
                 }
             };
         });
+        notifyWorkflowChange("edge_add");
     },
-    // Update workflow name
+    /**
+     * Update workflow name
+     */
     updateName: (name) => {
         workflowStore.update(($workflow) => {
             if (!$workflow)
@@ -118,8 +304,11 @@ export const workflowActions = {
                 }
             };
         });
+        notifyWorkflowChange("name");
     },
-    // Add a node
+    /**
+     * Add a node
+     */
     addNode: (node) => {
         workflowStore.update(($workflow) => {
             if (!$workflow)
@@ -133,8 +322,11 @@ export const workflowActions = {
                 }
             };
         });
+        notifyWorkflowChange("node_add");
     },
-    // Remove a node
+    /**
+     * Remove a node
+     */
     removeNode: (nodeId) => {
         workflowStore.update(($workflow) => {
             if (!$workflow)
@@ -149,8 +341,11 @@ export const workflowActions = {
                 }
             };
         });
+        notifyWorkflowChange("node_remove");
     },
-    // Add an edge
+    /**
+     * Add an edge
+     */
     addEdge: (edge) => {
         workflowStore.update(($workflow) => {
             if (!$workflow)
@@ -164,8 +359,11 @@ export const workflowActions = {
                 }
             };
         });
+        notifyWorkflowChange("edge_add");
     },
-    // Remove an edge
+    /**
+     * Remove an edge
+     */
     removeEdge: (edgeId) => {
         workflowStore.update(($workflow) => {
             if (!$workflow)
@@ -179,27 +377,40 @@ export const workflowActions = {
                 }
             };
         });
+        notifyWorkflowChange("edge_remove");
     },
-    // Update a specific node
+    /**
+     * Update a specific node
+     */
     updateNode: (nodeId, updates) => {
         workflowStore.update(($workflow) => {
             if (!$workflow)
                 return null;
             return {
                 ...$workflow,
-                nodes: $workflow.nodes.map((node) => (node.id === nodeId ? { ...node, ...updates } : node)),
+                nodes: $workflow.nodes.map((node) => node.id === nodeId ? { ...node, ...updates } : node),
                 metadata: {
                     ...$workflow.metadata,
                     updatedAt: new Date().toISOString()
                 }
             };
         });
+        notifyWorkflowChange("node_config");
     },
-    // Clear the workflow
+    /**
+     * Clear the workflow
+     */
     clear: () => {
         workflowStore.set(null);
+        savedSnapshot = null;
+        isDirtyStore.set(false);
+        if (onDirtyStateChangeCallback) {
+            onDirtyStateChangeCallback(false);
+        }
     },
-    // Update workflow metadata
+    /**
+     * Update workflow metadata
+     */
     updateMetadata: (metadata) => {
         workflowStore.update(($workflow) => {
             if (!$workflow)
@@ -213,8 +424,13 @@ export const workflowActions = {
                 }
             };
         });
+        notifyWorkflowChange("metadata");
     },
-    // Batch update nodes and edges (useful for complex operations)
+    /**
+     * Batch update nodes and edges
+     *
+     * Useful for complex operations that update multiple things at once.
+     */
     batchUpdate: (updates) => {
         workflowStore.update(($workflow) => {
             if (!$workflow)
@@ -232,11 +448,15 @@ export const workflowActions = {
                 }
             };
         });
+        notifyWorkflowChange("metadata");
     }
 };
-// Derived store for workflow changes (useful for triggering saves)
+// =========================================================================
+// Additional Derived Stores
+// =========================================================================
+/** Derived store for workflow changes (useful for triggering saves) */
 export const workflowChanged = derived([workflowNodes, workflowEdges, workflowName], ([nodes, edges, name]) => ({ nodes, edges, name }));
-// Derived store for workflow validation
+/** Derived store for workflow validation */
 export const workflowValidation = derived([workflowNodes, workflowEdges], ([nodes, edges]) => ({
     hasNodes: nodes.length > 0,
     hasEdges: edges.length > 0,
@@ -244,9 +464,9 @@ export const workflowValidation = derived([workflowNodes, workflowEdges], ([node
     edgeCount: edges.length,
     isValid: nodes.length > 0 && edges.length >= 0
 }));
-// Derived store for workflow metadata changes
+/** Derived store for workflow metadata changes */
 export const workflowMetadataChanged = derived(workflowMetadata, (metadata) => ({
     createdAt: metadata.createdAt,
     updatedAt: metadata.updatedAt,
-    version: metadata.version || '1.0.0'
+    version: metadata.version ?? "1.0.0"
 }));

package/dist/svelte-app.d.ts

@@ -1,10 +1,15 @@
 /**
  * Svelte App Wrapper for Framework Integration
- * Provides mount/unmount functions for integrating FlowDrop into any web application
- * Particularly useful for integration with vanilla JS, Drupal, WordPress, or other frameworks
+ *
+ * Provides mount/unmount functions for integrating FlowDrop into any web application.
+ * Particularly useful for integration with vanilla JS, Drupal, WordPress, or other frameworks.
+ *
+ * @module svelte-app
  */
-import type { Workflow, NodeMetadata, PortConfig } from './types/index.js';
-import type { EndpointConfig } from './config/endpoints.js';
+import type { Workflow, NodeMetadata, PortConfig } from "./types/index.js";
+import type { EndpointConfig } from "./config/endpoints.js";
+import type { AuthProvider } from "./types/auth.js";
+import type { FlowDropEventHandlers, FlowDropFeatures } from "./types/events.js";
 declare global {
     interface Window {
         flowdropSave?: () => Promise<void>;
@@ -12,57 +17,134 @@ declare global {
     }
 }
 /**
- * Return type for mounted Svelte app
+ * Navbar action configuration
  */
-interface MountedSvelteApp {
-    destroy: () => void;
-    save?: () => Promise<void>;
-    export?: () => void;
+export interface NavbarAction {
+    label: string;
+    href: string;
+    icon?: string;
+    variant?: "primary" | "secondary" | "outline";
+    onclick?: (event: Event) => void;
 }
 /**
- * Mount the full FlowDrop App with navbar, sidebars, and workflow editor
- * Use this for a complete workflow editing experience with all UI components
- * @param container - DOM element to mount the app into
- * @param options - Configuration options for the app
+ * Mount options for FlowDrop App
  */
-export declare function mountFlowDropApp(container: HTMLElement, options?: {
+export interface FlowDropMountOptions {
+    /** Initial workflow to load */
     workflow?: Workflow;
+    /** Available node types */
     nodes?: NodeMetadata[];
+    /** API endpoint configuration */
     endpointConfig?: EndpointConfig;
+    /** Port configuration for connections */
     portConfig?: PortConfig;
+    /** Editor height */
     height?: string | number;
+    /** Editor width */
     width?: string | number;
+    /** Show the navbar */
     showNavbar?: boolean;
+    /** Disable the node sidebar */
     disableSidebar?: boolean;
+    /** Lock the workflow (prevent changes) */
     lockWorkflow?: boolean;
+    /** Read-only mode */
     readOnly?: boolean;
-    nodeStatuses?: Record<string, 'pending' | 'running' | 'completed' | 'error'>;
+    /** Pipeline ID for status display */
     pipelineId?: string;
+    /** Node execution statuses */
+    nodeStatuses?: Record<string, "pending" | "running" | "completed" | "error">;
+    /** Custom navbar title */
     navbarTitle?: string;
-    navbarActions?: Array<{
-        label: string;
-        href: string;
-        icon?: string;
-        variant?: 'primary' | 'secondary' | 'outline';
-        onclick?: (event: Event) => void;
-    }>;
-}): Promise<MountedSvelteApp>;
+    /** Custom navbar actions */
+    navbarActions?: NavbarAction[];
+    /** Authentication provider for API requests */
+    authProvider?: AuthProvider;
+    /** Event handlers for workflow lifecycle */
+    eventHandlers?: FlowDropEventHandlers;
+    /** Feature configuration */
+    features?: FlowDropFeatures;
+    /** Custom storage key for localStorage drafts */
+    draftStorageKey?: string;
+}
+/**
+ * Return type for mounted FlowDrop app
+ */
+export interface MountedFlowDropApp {
+    /**
+     * Destroy the app and clean up resources
+     */
+    destroy: () => void;
+    /**
+     * Check if there are unsaved changes
+     */
+    isDirty: () => boolean;
+    /**
+     * Mark the workflow as saved (clears dirty state)
+     */
+    markAsSaved: () => void;
+    /**
+     * Get the current workflow data
+     */
+    getWorkflow: () => Workflow | null;
+    /**
+     * Trigger save operation
+     */
+    save: () => Promise<void>;
+    /**
+     * Trigger export operation (downloads JSON)
+     */
+    export: () => void;
+}
+/**
+ * Mount the full FlowDrop App with navbar, sidebars, and workflow editor
+ *
+ * Use this for a complete workflow editing experience with all UI components.
+ *
+ * @param container - DOM element to mount the app into
+ * @param options - Configuration options for the app
+ * @returns Promise resolving to a MountedFlowDropApp instance
+ *
+ * @example
+ * ```typescript
+ * const app = await mountFlowDropApp(document.getElementById("editor"), {
+ *   workflow: myWorkflow,
+ *   endpointConfig: createEndpointConfig("/api/flowdrop"),
+ *   authProvider: new CallbackAuthProvider({
+ *     getToken: () => authService.getAccessToken()
+ *   }),
+ *   eventHandlers: {
+ *     onDirtyStateChange: (isDirty) => updateSaveButton(isDirty),
+ *     onAfterSave: () => showSuccess("Saved!")
+ *   }
+ * });
+ * ```
+ */
+export declare function mountFlowDropApp(container: HTMLElement, options?: FlowDropMountOptions): Promise<MountedFlowDropApp>;
 /**
  * Mount the WorkflowEditor component in a container
- * Simpler alternative to mountFlowDropApp - only mounts the editor without navbar
+ *
+ * Simpler alternative to mountFlowDropApp - only mounts the editor without navbar.
+ *
+ * @param container - DOM element to mount the editor into
+ * @param options - Configuration options
+ * @returns Promise resolving to a MountedFlowDropApp instance
  */
 export declare function mountWorkflowEditor(container: HTMLElement, options?: {
     workflow?: Workflow;
     nodes?: NodeMetadata[];
     endpointConfig?: EndpointConfig;
     portConfig?: PortConfig;
-}): Promise<MountedSvelteApp>;
+}): Promise<MountedFlowDropApp>;
 /**
- * Unmount a Svelte app (works for both App and WorkflowEditor)
+ * Unmount a FlowDrop app
+ *
+ * @param app - The mounted app to unmount
  */
-export declare function unmountFlowDropApp(app: MountedSvelteApp): void;
+export declare function unmountFlowDropApp(app: MountedFlowDropApp): void;
 /**
- * Unmount a Svelte app (alias for backward compatibility)
+ * Unmount a FlowDrop app (alias for backward compatibility)
+ *
+ * @param app - The mounted app to unmount
  */
-export declare function unmountWorkflowEditor(app: MountedSvelteApp): void;
-export {};
+export declare function unmountWorkflowEditor(app: MountedFlowDropApp): void;