@flowdrop/flowdrop 1.0.0

package/dist/services/globalSave.js

@@ -0,0 +1,248 @@
+/**
+ * Global Save Service
+ * Provides save and export functionality that can be accessed from anywhere in the app.
+ * This is the single source of truth for save/export logic.
+ *
+ * App.svelte delegates to globalSaveWorkflow() / globalExportWorkflow() rather than
+ * reimplementing the logic, ensuring "blur active element" flushing and metadata
+ * construction happen in exactly one place.
+ */
+import { tick } from 'svelte';
+import { getWorkflowStore, workflowActions, markAsSaved as storeMarkAsSaved } from '../stores/workflowStore.svelte.js';
+import { workflowApi, setEndpointConfig } from './api.js';
+import { createEndpointConfig } from '../config/endpoints.js';
+import { v4 as uuidv4 } from 'uuid';
+import { DEFAULT_WORKFLOW_FORMAT } from '../types/index.js';
+import { apiToasts, workflowToasts, dismissToast } from './toastService.js';
+import { DEFAULT_FEATURES } from '../types/events.js';
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+/**
+ * Ensure API configuration is initialized.
+ * This is needed when the global save function is called from the layout component
+ * which doesn't initialize the API configuration like the App component does.
+ */
+async function ensureApiConfiguration() {
+    try {
+        const { getEndpointConfig } = await import('./api.js');
+        const currentConfig = getEndpointConfig();
+        if (currentConfig && currentConfig.baseUrl) {
+            return;
+        }
+    }
+    catch {
+        // Could not check existing API configuration, initializing
+    }
+    // API configuration is not initialized — derive URL from window.location when available
+    const apiBaseUrl = typeof window !== 'undefined'
+        ? `${window.location.protocol}//${window.location.host}/api/flowdrop`
+        : '/api/flowdrop';
+    const config = createEndpointConfig(apiBaseUrl, {
+        auth: {
+            type: 'none'
+        },
+        timeout: 10000,
+        retry: {
+            enabled: true,
+            maxAttempts: 2,
+            delay: 1000,
+            backoff: 'exponential'
+        }
+    });
+    setEndpointConfig(config);
+}
+/**
+ * Flush any pending form changes by blurring the active element.
+ * This ensures focusout handlers (like ConfigForm's handleFormBlur)
+ * sync local state to the global store before we read it.
+ *
+ * Must be called once, in this file only, so the logic lives in exactly one place.
+ */
+async function flushPendingFormChanges() {
+    if (typeof document !== 'undefined' && document.activeElement instanceof HTMLElement) {
+        document.activeElement.blur();
+    }
+    // Wait for any pending DOM / Svelte reactive updates before reading the store
+    await tick();
+}
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+/**
+ * Save the current workflow to the backend.
+ *
+ * This is the single source of truth for save logic. App.svelte delegates
+ * to this function rather than reimplementing the steps.
+ *
+ * Steps performed:
+ *  1. Flush pending form changes (blur active element + tick)
+ *  2. Optionally call onBeforeSave — return false cancels the save
+ *  3. Build the canonical Workflow object (preserving metadata, format, etc.)
+ *  4. Persist via enhanced apiClient or legacy workflowApi
+ *  5. Update the store if the server assigned a new ID
+ *  6. Call onMarkAsSaved / onAfterSave hooks
+ *  7. Show toast notifications (respecting features.showToasts)
+ */
+export async function globalSaveWorkflow(options = {}) {
+    const { apiClient, eventHandlers, onMarkAsSaved } = options;
+    const features = { ...DEFAULT_FEATURES, ...options.features };
+    // Step 1 — Flush pending form changes (single location for this logic)
+    await flushPendingFormChanges();
+    // Get current workflow from global store after flush
+    const currentWorkflow = getWorkflowStore();
+    if (!currentWorkflow) {
+        if (features.showToasts) {
+            apiToasts.error('Save workflow', 'No workflow to save');
+        }
+        return;
+    }
+    // Step 2 — Allow the parent to cancel the save
+    if (eventHandlers?.onBeforeSave) {
+        const shouldContinue = await eventHandlers.onBeforeSave(currentWorkflow);
+        if (shouldContinue === false) {
+            return;
+        }
+    }
+    const loadingToast = features.showToasts ? apiToasts.loading('Saving workflow') : null;
+    try {
+        // Ensure API configuration is initialised (needed when called outside App.svelte)
+        await ensureApiConfiguration();
+        // Step 3 — Build the canonical workflow object.
+        // Preserve all existing metadata fields (format, tags, etc.) so nothing is dropped.
+        const workflowId = currentWorkflow.id || uuidv4();
+        const finalWorkflow = {
+            id: workflowId,
+            name: currentWorkflow.name || 'Untitled Workflow',
+            description: currentWorkflow.description || '',
+            nodes: currentWorkflow.nodes || [],
+            edges: currentWorkflow.edges || [],
+            metadata: {
+                ...currentWorkflow.metadata,
+                version: currentWorkflow.metadata?.version || '1.0.0',
+                format: currentWorkflow.metadata?.format || DEFAULT_WORKFLOW_FORMAT,
+                createdAt: currentWorkflow.metadata?.createdAt || new Date().toISOString(),
+                updatedAt: new Date().toISOString()
+            }
+        };
+        // Step 4 — Persist
+        let savedWorkflow;
+        if (apiClient) {
+            // Enhanced client path — detects existing workflows by non-UUID ID
+            const isExistingWorkflow = finalWorkflow.id.length > 0 &&
+                !finalWorkflow.id.match(/^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i);
+            if (isExistingWorkflow) {
+                savedWorkflow = await apiClient.updateWorkflow(finalWorkflow.id, finalWorkflow);
+            }
+            else {
+                savedWorkflow = await apiClient.saveWorkflow(finalWorkflow);
+            }
+        }
+        else {
+            // Legacy path
+            savedWorkflow = await workflowApi.saveWorkflow(finalWorkflow);
+        }
+        // Step 5 — If the server assigned a new ID, sync the store
+        if (savedWorkflow.id && savedWorkflow.id !== finalWorkflow.id) {
+            workflowActions.batchUpdate({
+                nodes: finalWorkflow.nodes,
+                edges: finalWorkflow.edges,
+                name: finalWorkflow.name,
+                metadata: {
+                    ...finalWorkflow.metadata,
+                    ...savedWorkflow.metadata
+                }
+            });
+        }
+        // Step 6a — Mark dirty state as clean
+        if (onMarkAsSaved) {
+            onMarkAsSaved();
+        }
+        else {
+            // Fallback: call the store's own markAsSaved if no callback was provided
+            storeMarkAsSaved();
+        }
+        // Show success toast
+        if (loadingToast)
+            dismissToast(loadingToast);
+        if (features.showToasts) {
+            workflowToasts.saved(finalWorkflow.name);
+        }
+        // Step 6b — After-save hook
+        if (eventHandlers?.onAfterSave) {
+            await eventHandlers.onAfterSave(savedWorkflow);
+        }
+    }
+    catch (error) {
+        if (loadingToast)
+            dismissToast(loadingToast);
+        const errorObj = error instanceof Error ? error : new Error('Unknown error occurred');
+        // onSaveError hook
+        const currentWorkflowForError = getWorkflowStore();
+        if (eventHandlers?.onSaveError && currentWorkflowForError) {
+            await eventHandlers.onSaveError(errorObj, currentWorkflowForError);
+        }
+        // onApiError hook — return true suppresses the default toast
+        let suppressToast = false;
+        if (eventHandlers?.onApiError) {
+            suppressToast = eventHandlers.onApiError(errorObj, 'save') === true;
+        }
+        if (features.showToasts && !suppressToast) {
+            apiToasts.error('Save workflow', errorObj.message);
+        }
+        throw error;
+    }
+}
+/**
+ * Export the current workflow as a downloadable JSON file.
+ *
+ * This is the single source of truth for export logic. App.svelte delegates
+ * to this function rather than reimplementing the steps.
+ *
+ * Preserves all metadata fields (format, tags, etc.) consistently with save.
+ */
+export async function globalExportWorkflow(options = {}) {
+    const features = { ...DEFAULT_FEATURES, ...options.features };
+    try {
+        // Flush pending changes before exporting (same discipline as save)
+        await flushPendingFormChanges();
+        const currentWorkflow = getWorkflowStore();
+        if (!currentWorkflow) {
+            if (features.showToasts) {
+                apiToasts.error('Export workflow', 'No workflow to export');
+            }
+            return;
+        }
+        // Build the canonical export object — preserve all metadata fields
+        const finalWorkflow = {
+            id: currentWorkflow.id || 'untitled-workflow',
+            name: currentWorkflow.name || 'Untitled Workflow',
+            description: currentWorkflow.description || '',
+            nodes: currentWorkflow.nodes || [],
+            edges: currentWorkflow.edges || [],
+            metadata: {
+                ...currentWorkflow.metadata,
+                version: currentWorkflow.metadata?.version || '1.0.0',
+                format: currentWorkflow.metadata?.format || DEFAULT_WORKFLOW_FORMAT,
+                createdAt: currentWorkflow.metadata?.createdAt || new Date().toISOString(),
+                updatedAt: new Date().toISOString()
+            }
+        };
+        // Trigger browser download
+        const dataStr = JSON.stringify(finalWorkflow, null, 2);
+        const dataBlob = new Blob([dataStr], { type: 'application/json' });
+        const url = URL.createObjectURL(dataBlob);
+        const link = document.createElement('a');
+        link.href = url;
+        link.download = `${finalWorkflow.name}.json`;
+        link.click();
+        URL.revokeObjectURL(url);
+        if (features.showToasts) {
+            workflowToasts.exported(finalWorkflow.name);
+        }
+    }
+    catch (error) {
+        const errorObj = error instanceof Error ? error : new Error('Unknown error occurred');
+        apiToasts.error('Export workflow', errorObj.message);
+    }
+}

package/dist/services/historyService.d.ts

@@ -0,0 +1,208 @@
+/**
+ * History Service for FlowDrop
+ *
+ * Provides undo/redo functionality for the workflow editor using snapshot-based history.
+ * Supports debounced drag operations and configurable history limits.
+ *
+ * @module services/historyService
+ */
+import type { Workflow } from '../types/index.js';
+/**
+ * Represents a single entry in the history stack
+ */
+export interface HistoryEntry {
+    /** Deep clone of the workflow state at this point */
+    snapshot: Workflow;
+    /** Timestamp when the entry was created */
+    timestamp: number;
+    /** Human-readable description of the change (e.g., "Add node", "Delete edge") */
+    description?: string;
+}
+/**
+ * Current state of the history service
+ */
+export interface HistoryState {
+    /** Whether undo is available */
+    canUndo: boolean;
+    /** Whether redo is available */
+    canRedo: boolean;
+    /** Current position in the history stack */
+    currentIndex: number;
+    /** Total number of entries in the history stack */
+    historyLength: number;
+    /** Whether a transaction is currently active */
+    isInTransaction: boolean;
+}
+/**
+ * Options for pushing a new state to history
+ */
+export interface PushOptions {
+    /** Description of the change for debugging/display */
+    description?: string;
+    /** Whether to skip adding this to history (used internally for undo/redo) */
+    skipHistory?: boolean;
+}
+/**
+ * Manages undo/redo history for workflow state
+ *
+ * Uses a snapshot-based approach where each history entry contains
+ * a complete copy of the workflow state. This trades memory for simplicity
+ * and reliability.
+ *
+ * @example
+ * ```typescript
+ * const historyService = new HistoryService();
+ *
+ * // Initialize with current workflow
+ * historyService.initialize(workflow);
+ *
+ * // Push state before making changes
+ * historyService.push(workflow, { description: "Add node" });
+ *
+ * // Undo/Redo
+ * const previousState = historyService.undo();
+ * const nextState = historyService.redo();
+ * ```
+ */
+export declare class HistoryService {
+    /** Stack of history entries */
+    private undoStack;
+    /** Stack of redo entries (cleared when new changes are made) */
+    private redoStack;
+    /** Maximum number of entries to keep in history */
+    private maxEntries;
+    /** Flag to track if we're in a transaction (batch operation) */
+    private inTransaction;
+    /** Snapshot captured at transaction start */
+    private transactionSnapshot;
+    /** Description for the transaction */
+    private transactionDescription;
+    /** Callbacks to notify when history state changes */
+    private changeCallbacks;
+    /**
+     * Creates a new HistoryService instance
+     *
+     * @param maxEntries - Maximum number of history entries to keep (default: 50)
+     */
+    constructor(maxEntries?: number);
+    /**
+     * Initialize the history with the current workflow state
+     *
+     * This clears any existing history and sets the initial state.
+     * Should be called when a workflow is first loaded.
+     *
+     * @param workflow - The initial workflow state
+     */
+    initialize(workflow: Workflow): void;
+    /**
+     * Push the current state to history before making changes
+     *
+     * Call this BEFORE modifying the workflow to capture the "before" state.
+     * The redo stack is cleared when new changes are pushed.
+     *
+     * @param workflow - The current workflow state (before changes)
+     * @param options - Options for this history entry
+     */
+    push(workflow: Workflow, options?: PushOptions): void;
+    /**
+     * Undo the last change
+     *
+     * Returns the previous workflow state, or null if at the beginning of history.
+     *
+     * @returns The previous workflow state, or null if cannot undo
+     */
+    undo(): Workflow | null;
+    /**
+     * Redo the last undone change
+     *
+     * Returns the next workflow state, or null if at the end of history.
+     *
+     * @returns The next workflow state, or null if cannot redo
+     */
+    redo(): Workflow | null;
+    /**
+     * Start a transaction for grouping multiple changes
+     *
+     * All changes made during a transaction are combined into a single undo entry.
+     * Useful for operations like "delete node" which also removes connected edges.
+     *
+     * @param workflow - The current workflow state (before changes)
+     * @param description - Description for the combined change
+     */
+    startTransaction(workflow: Workflow, description?: string): void;
+    /**
+     * Commit the current transaction
+     *
+     * Pushes the state captured at transaction start to the history stack.
+     */
+    commitTransaction(): void;
+    /**
+     * Cancel the current transaction without committing
+     *
+     * Discards the transaction without adding to history.
+     */
+    cancelTransaction(): void;
+    /**
+     * Clear all history
+     *
+     * Resets the history stack. Optionally keeps the current state as initial.
+     *
+     * @param currentWorkflow - If provided, keeps this as the initial state
+     */
+    clear(currentWorkflow?: Workflow): void;
+    /**
+     * Get the current history state
+     *
+     * @returns The current state of the history service
+     */
+    getState(): HistoryState;
+    /**
+     * Check if undo is available
+     */
+    canUndo(): boolean;
+    /**
+     * Check if redo is available
+     */
+    canRedo(): boolean;
+    /**
+     * Subscribe to history state changes
+     *
+     * @param callback - Function to call when history state changes
+     * @returns Unsubscribe function
+     */
+    subscribe(callback: (state: HistoryState) => void): () => void;
+    /**
+     * Update the maximum number of history entries
+     *
+     * @param maxEntries - New maximum number of entries
+     */
+    setMaxEntries(maxEntries: number): void;
+    /**
+     * Internal method to push a state to history
+     */
+    private pushInternal;
+    /**
+     * Trim history to stay within maxEntries limit.
+     * A maxEntries of 0 means unlimited (no trimming).
+     */
+    private trimHistory;
+    /**
+     * Create a deep clone of a workflow
+     *
+     * Uses JSON parse/stringify to properly strip non-serializable values
+     * like functions (e.g., onConfigOpen callbacks) that are added to nodes
+     * at runtime but shouldn't be persisted in history.
+     */
+    private cloneWorkflow;
+    /**
+     * Notify all subscribers of state changes
+     */
+    private notifyChange;
+}
+/**
+ * Singleton instance of the history service
+ *
+ * Use this for the main workflow editor. For isolated instances,
+ * create a new HistoryService directly.
+ */
+export declare const historyService: HistoryService;