@flowdrop/flowdrop 1.0.0

package/dist/utils/handlePositioning.js

@@ -0,0 +1,35 @@
+/**
+ * Utility functions for calculating handle positions on nodes
+ */
+/**
+ * Calculate handle position along a circle arc using cos/sin
+ *
+ * Distributes handles evenly along an arc on the left or right side of a circle.
+ * For N handles, they are positioned at angles calculated as:
+ * angle = centerAngle - arcSpan/2 + arcSpan * (index + 1) / (count + 1)
+ *
+ * @param index - The index of the handle (0-based)
+ * @param count - Total number of handles on this side
+ * @param side - 'left' for inputs, 'right' for outputs
+ * @param radius - The radius of the circle (default: 40px for 80px diameter)
+ * @param arcSpan - The arc span in radians (default: 5π/6 = 150°)
+ * @returns Object with left and top pixel values relative to the circle's bounding box
+ *
+ * @example
+ * // Single handle on left side - positioned at center (180°)
+ * getCircleHandlePosition(0, 1, 'left') // { left: 0, top: 36 }
+ *
+ * @example
+ * // Two handles on left side - positioned at 150° and 210°
+ * getCircleHandlePosition(0, 2, 'left') // { left: ~4.8, top: ~18 }
+ * getCircleHandlePosition(1, 2, 'left') // { left: ~4.8, top: ~54 }
+ */
+export function getCircleHandlePosition(index, count, side, radius = 40, arcSpan = (Math.PI * 5) / 6) {
+    const centerAngle = side === 'left' ? Math.PI : 0; // 180° for left, 0° for right
+    const angle = centerAngle - arcSpan / 2 + (arcSpan * (index + 1)) / (count + 1);
+    const centerOffset = radius; // center of the circle (assuming square bounding box)
+    return {
+        left: centerOffset + radius * Math.cos(angle),
+        top: centerOffset + radius * Math.sin(angle)
+    };
+}

package/dist/utils/icons.d.ts

@@ -0,0 +1,106 @@
+/**
+ * Centralized icon management for FlowDrop
+ * Ensures consistent icon usage across all components
+ */
+import type { NodeCategory } from '../types/index.js';
+/**
+ * Default icons for different contexts
+ */
+export declare const DEFAULT_ICONS: {
+    readonly NODE: "mdi:cube";
+    readonly CATEGORY: "mdi:folder";
+    readonly ADD: "mdi:plus";
+    readonly REMOVE: "mdi:minus";
+    readonly EDIT: "mdi:pencil";
+    readonly SAVE: "mdi:content-save";
+    readonly LOAD: "mdi:folder-open";
+    readonly EXPORT: "mdi:download";
+    readonly IMPORT: "mdi:upload";
+    readonly SEARCH: "mdi:magnify";
+    readonly CLOSE: "mdi:close";
+    readonly SETTINGS: "mdi:cog";
+    readonly HELP: "mdi:help-circle";
+    readonly SUCCESS: "mdi:check-circle";
+    readonly ERROR: "mdi:alert-circle";
+    readonly WARNING: "mdi:alert";
+    readonly INFO: "mdi:information";
+    readonly LOADING: "mdi:loading";
+    readonly HOME: "mdi:home";
+    readonly BACK: "mdi:arrow-left";
+    readonly FORWARD: "mdi:arrow-right";
+    readonly UP: "mdi:arrow-up";
+    readonly DOWN: "mdi:arrow-down";
+    readonly WORKFLOW: "mdi:graph";
+    readonly NODE_ADD: "mdi:plus-circle";
+    readonly NODE_DELETE: "mdi:minus-circle";
+    readonly CONNECTION: "mdi:connection";
+    readonly DATA: "mdi:database";
+    readonly FILE: "mdi:file";
+    readonly TEXT: "mdi:text";
+    readonly JSON: "mdi:code-json";
+    readonly MODEL: "mdi:chip";
+    readonly BRAIN: "mdi:brain";
+    readonly VECTOR: "mdi:vector-point";
+    readonly ROBOT: "mdi:robot";
+    readonly TOOL: "mdi:wrench";
+    readonly CALCULATOR: "mdi:calculator";
+    readonly CLOCK: "mdi:clock";
+    readonly CHAT: "mdi:chat";
+    readonly MESSAGE: "mdi:message";
+    readonly EMAIL: "mdi:email";
+    readonly WEBHOOK: "mdi:webhook";
+    readonly STORAGE: "mdi:database";
+    readonly MEMORY: "mdi:memory";
+    readonly CACHE: "mdi:cached";
+    readonly PROCESS: "mdi:cog";
+    readonly FILTER: "mdi:filter";
+    readonly SORT: "mdi:sort";
+    readonly TRANSFORM: "mdi:transform";
+    readonly LOGIC: "mdi:git-branch";
+    readonly CONDITION: "mdi:source-fork";
+    readonly LOOP: "mdi:loop";
+    readonly API: "mdi:api";
+    readonly LINK: "mdi:link";
+    readonly PLUGIN: "mdi:puzzle";
+    readonly BUNDLE: "mdi:package-variant";
+};
+/**
+ * Category-specific icons for built-in categories.
+ * Custom categories fall back to DEFAULT_ICONS.CATEGORY.
+ * These serve as static defaults; the categories store provides dynamic overrides.
+ */
+export declare const CATEGORY_ICONS: Record<string, string>;
+/**
+ * Get the appropriate icon for a node
+ * @param nodeIcon - The node's specific icon
+ * @param category - The node's category
+ * @returns The icon to use
+ */
+export declare function getNodeIcon(nodeIcon?: string, category?: NodeCategory): string;
+/**
+ * Get the appropriate icon for a category.
+ * Checks the categories store first (which includes API overrides),
+ * then falls back to the static CATEGORY_ICONS map, then to the default.
+ * @param category - The category
+ * @returns The icon to use
+ */
+export declare function getCategoryIcon(category: NodeCategory): string;
+/**
+ * Get a default icon by key
+ * @param key - The icon key from DEFAULT_ICONS
+ * @returns The icon string
+ */
+export declare function getDefaultIcon(key: keyof typeof DEFAULT_ICONS): string;
+/**
+ * Validate if an icon string is properly formatted
+ * @param icon - The icon string to validate
+ * @returns True if valid, false otherwise
+ */
+export declare function isValidIcon(icon: string): boolean;
+/**
+ * Get a fallback icon if the provided icon is invalid
+ * @param icon - The icon to check
+ * @param fallback - The fallback icon to use
+ * @returns The valid icon string
+ */
+export declare function getValidIcon(icon: string, fallback?: string): string;

package/dist/utils/icons.js

@@ -0,0 +1,157 @@
+/**
+ * Centralized icon management for FlowDrop
+ * Ensures consistent icon usage across all components
+ */
+import { getCategoryIcon as getCategoryIconFromStore } from '../stores/categoriesStore.svelte.js';
+/**
+ * Default icons for different contexts
+ */
+export const DEFAULT_ICONS = {
+    // Node fallback icons
+    NODE: 'mdi:cube',
+    CATEGORY: 'mdi:folder',
+    // UI action icons
+    ADD: 'mdi:plus',
+    REMOVE: 'mdi:minus',
+    EDIT: 'mdi:pencil',
+    SAVE: 'mdi:content-save',
+    LOAD: 'mdi:folder-open',
+    EXPORT: 'mdi:download',
+    IMPORT: 'mdi:upload',
+    SEARCH: 'mdi:magnify',
+    CLOSE: 'mdi:close',
+    SETTINGS: 'mdi:cog',
+    HELP: 'mdi:help-circle',
+    // Status icons
+    SUCCESS: 'mdi:check-circle',
+    ERROR: 'mdi:alert-circle',
+    WARNING: 'mdi:alert',
+    INFO: 'mdi:information',
+    LOADING: 'mdi:loading',
+    // Navigation icons
+    HOME: 'mdi:home',
+    BACK: 'mdi:arrow-left',
+    FORWARD: 'mdi:arrow-right',
+    UP: 'mdi:arrow-up',
+    DOWN: 'mdi:arrow-down',
+    // Workflow icons
+    WORKFLOW: 'mdi:graph',
+    NODE_ADD: 'mdi:plus-circle',
+    NODE_DELETE: 'mdi:minus-circle',
+    CONNECTION: 'mdi:connection',
+    // Data icons
+    DATA: 'mdi:database',
+    FILE: 'mdi:file',
+    TEXT: 'mdi:text',
+    JSON: 'mdi:code-json',
+    // Model and processing icons
+    MODEL: 'mdi:chip',
+    BRAIN: 'mdi:brain',
+    VECTOR: 'mdi:vector-point',
+    ROBOT: 'mdi:robot',
+    // Tool icons
+    TOOL: 'mdi:wrench',
+    CALCULATOR: 'mdi:calculator',
+    CLOCK: 'mdi:clock',
+    // Communication icons
+    CHAT: 'mdi:chat',
+    MESSAGE: 'mdi:message',
+    EMAIL: 'mdi:email',
+    WEBHOOK: 'mdi:webhook',
+    // Storage icons
+    STORAGE: 'mdi:database',
+    MEMORY: 'mdi:memory',
+    CACHE: 'mdi:cached',
+    // Processing icons
+    PROCESS: 'mdi:cog',
+    FILTER: 'mdi:filter',
+    SORT: 'mdi:sort',
+    TRANSFORM: 'mdi:transform',
+    // Logic icons
+    LOGIC: 'mdi:git-branch',
+    CONDITION: 'mdi:source-fork',
+    LOOP: 'mdi:loop',
+    // Integration icons
+    API: 'mdi:api',
+    LINK: 'mdi:link',
+    PLUGIN: 'mdi:puzzle',
+    BUNDLE: 'mdi:package-variant'
+};
+/**
+ * Category-specific icons for built-in categories.
+ * Custom categories fall back to DEFAULT_ICONS.CATEGORY.
+ * These serve as static defaults; the categories store provides dynamic overrides.
+ */
+export const CATEGORY_ICONS = {
+    triggers: 'mdi:lightning-bolt',
+    inputs: 'mdi:arrow-down-circle',
+    outputs: 'mdi:arrow-up-circle',
+    prompts: 'mdi:message-text',
+    models: 'mdi:robot',
+    processing: 'mdi:cog',
+    logic: 'mdi:source-branch',
+    data: 'mdi:database',
+    helpers: 'mdi:help-circle',
+    tools: 'mdi:wrench',
+    'vector stores': 'mdi:vector-square',
+    embeddings: 'mdi:vector-polygon',
+    memories: 'mdi:brain',
+    agents: 'mdi:account-cog',
+    ai: 'mdi:shimmer',
+    interrupts: 'mdi:hand-back-left',
+    bundles: 'mdi:package-variant'
+};
+/**
+ * Get the appropriate icon for a node
+ * @param nodeIcon - The node's specific icon
+ * @param category - The node's category
+ * @returns The icon to use
+ */
+export function getNodeIcon(nodeIcon, category) {
+    // If node has a specific icon, use it
+    if (nodeIcon) {
+        return nodeIcon;
+    }
+    // If category is provided, use category icon from store (which includes API overrides)
+    if (category) {
+        return getCategoryIconFromStore(category);
+    }
+    // Fallback to default node icon
+    return DEFAULT_ICONS.NODE;
+}
+/**
+ * Get the appropriate icon for a category.
+ * Checks the categories store first (which includes API overrides),
+ * then falls back to the static CATEGORY_ICONS map, then to the default.
+ * @param category - The category
+ * @returns The icon to use
+ */
+export function getCategoryIcon(category) {
+    return getCategoryIconFromStore(category);
+}
+/**
+ * Get a default icon by key
+ * @param key - The icon key from DEFAULT_ICONS
+ * @returns The icon string
+ */
+export function getDefaultIcon(key) {
+    return DEFAULT_ICONS[key];
+}
+/**
+ * Validate if an icon string is properly formatted
+ * @param icon - The icon string to validate
+ * @returns True if valid, false otherwise
+ */
+export function isValidIcon(icon) {
+    // Check if it's a valid iconify format (e.g., "mdi:icon-name")
+    return /^[a-z-]+:[a-z-]+$/.test(icon);
+}
+/**
+ * Get a fallback icon if the provided icon is invalid
+ * @param icon - The icon to check
+ * @param fallback - The fallback icon to use
+ * @returns The valid icon string
+ */
+export function getValidIcon(icon, fallback = DEFAULT_ICONS.NODE) {
+    return isValidIcon(icon) ? icon : fallback;
+}

package/dist/utils/logger.d.ts

@@ -0,0 +1,47 @@
+/**
+ * FlowDrop Logger
+ *
+ * Lightweight configurable logger for the FlowDrop library.
+ * Disabled by default — consumers enable it for debugging.
+ *
+ * @module utils/logger
+ *
+ * @example
+ * ```typescript
+ * import { setLogLevel } from '@flowdrop/flowdrop/core';
+ *
+ * // Enable debug logging during development
+ * setLogLevel('debug');
+ *
+ * // Enable only warnings and errors
+ * setLogLevel('warn');
+ *
+ * // Disable all logging (default)
+ * setLogLevel('none');
+ * ```
+ */
+/** Log severity levels. `'none'` disables all output. */
+export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
+/**
+ * Set the minimum log level for FlowDrop library output.
+ * Messages below this level are silently discarded.
+ *
+ * @param level - The minimum severity to display. Use `'none'` to disable all output.
+ */
+export declare function setLogLevel(level: LogLevel): void;
+/**
+ * Get the current log level.
+ */
+export declare function getLogLevel(): LogLevel;
+/**
+ * FlowDrop library logger.
+ *
+ * All methods are no-ops when the log level is set to `'none'` (default).
+ * Enable output by calling `setLogLevel()`.
+ */
+export declare const logger: {
+    debug(message: string, ...args: unknown[]): void;
+    info(message: string, ...args: unknown[]): void;
+    warn(message: string, ...args: unknown[]): void;
+    error(message: string, ...args: unknown[]): void;
+};

package/dist/utils/logger.js

@@ -0,0 +1,72 @@
+/**
+ * FlowDrop Logger
+ *
+ * Lightweight configurable logger for the FlowDrop library.
+ * Disabled by default — consumers enable it for debugging.
+ *
+ * @module utils/logger
+ *
+ * @example
+ * ```typescript
+ * import { setLogLevel } from '@flowdrop/flowdrop/core';
+ *
+ * // Enable debug logging during development
+ * setLogLevel('debug');
+ *
+ * // Enable only warnings and errors
+ * setLogLevel('warn');
+ *
+ * // Disable all logging (default)
+ * setLogLevel('none');
+ * ```
+ */
+const LOG_PRIORITY = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+    none: 4
+};
+let currentLevel = 'none';
+/**
+ * Set the minimum log level for FlowDrop library output.
+ * Messages below this level are silently discarded.
+ *
+ * @param level - The minimum severity to display. Use `'none'` to disable all output.
+ */
+export function setLogLevel(level) {
+    currentLevel = level;
+}
+/**
+ * Get the current log level.
+ */
+export function getLogLevel() {
+    return currentLevel;
+}
+function shouldLog(level) {
+    return LOG_PRIORITY[level] >= LOG_PRIORITY[currentLevel];
+}
+/**
+ * FlowDrop library logger.
+ *
+ * All methods are no-ops when the log level is set to `'none'` (default).
+ * Enable output by calling `setLogLevel()`.
+ */
+export const logger = {
+    debug(message, ...args) {
+        if (shouldLog('debug'))
+            console.debug(`[FlowDrop] ${message}`, ...args);
+    },
+    info(message, ...args) {
+        if (shouldLog('info'))
+            console.info(`[FlowDrop] ${message}`, ...args);
+    },
+    warn(message, ...args) {
+        if (shouldLog('warn'))
+            console.warn(`[FlowDrop] ${message}`, ...args);
+    },
+    error(message, ...args) {
+        if (shouldLog('error'))
+            console.error(`[FlowDrop] ${message}`, ...args);
+    }
+};

package/dist/utils/nodeStatus.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Node Status Utility Functions
+ * Provides utilities for managing and displaying node execution status
+ */
+import type { NodeExecutionStatus, NodeExecutionInfo } from '../types/index.js';
+/**
+ * Get the display color for a node execution status
+ */
+export declare function getStatusColor(status: NodeExecutionStatus): string;
+/**
+ * Get the display icon for a node execution status
+ */
+export declare function getStatusIcon(status: NodeExecutionStatus): string;
+/**
+ * Get the display label for a node execution status
+ */
+export declare function getStatusLabel(status: NodeExecutionStatus): string;
+/**
+ * Get the background color for a node execution status overlay
+ */
+export declare function getStatusBackgroundColor(status: NodeExecutionStatus): string;
+/**
+ * Get the text color for a node execution status overlay
+ */
+export declare function getStatusTextColor(status: NodeExecutionStatus): string;
+/**
+ * Create a default NodeExecutionInfo object
+ */
+export declare function createDefaultExecutionInfo(): NodeExecutionInfo;
+/**
+ * Update node execution info when execution starts
+ */
+export declare function updateExecutionStart(executionInfo: NodeExecutionInfo): NodeExecutionInfo;
+/**
+ * Update node execution info when execution completes successfully
+ */
+export declare function updateExecutionComplete(executionInfo: NodeExecutionInfo, duration: number): NodeExecutionInfo;
+/**
+ * Update node execution info when execution fails
+ */
+export declare function updateExecutionFailed(executionInfo: NodeExecutionInfo, error: string, duration: number): NodeExecutionInfo;
+/**
+ * Reset node execution info
+ */
+export declare function resetExecutionInfo(executionInfo: NodeExecutionInfo): NodeExecutionInfo;
+/**
+ * Format execution duration for display
+ */
+export declare function formatExecutionDuration(duration?: number): string;
+/**
+ * Format last executed timestamp for display
+ */
+export declare function formatLastExecuted(timestamp?: string): string;

package/dist/utils/nodeStatus.js

@@ -0,0 +1,183 @@
+/**
+ * Node Status Utility Functions
+ * Provides utilities for managing and displaying node execution status
+ */
+/**
+ * Get the display color for a node execution status
+ */
+export function getStatusColor(status) {
+    const statusColors = {
+        idle: '#6b7280', // gray
+        pending: '#f59e0b', // amber
+        running: '#3b82f6', // blue
+        completed: '#10b981', // emerald
+        failed: '#ef4444', // red
+        cancelled: '#6b7280', // gray
+        skipped: '#8b5cf6' // violet
+    };
+    return statusColors[status] || statusColors.idle;
+}
+/**
+ * Get the display icon for a node execution status
+ */
+export function getStatusIcon(status) {
+    const statusIcons = {
+        idle: 'mdi:circle-outline',
+        pending: 'mdi:clock-outline',
+        running: 'mdi:loading',
+        completed: 'mdi:check-circle',
+        failed: 'mdi:alert-circle',
+        cancelled: 'mdi:cancel',
+        skipped: 'mdi:skip-next'
+    };
+    return statusIcons[status] || statusIcons.idle;
+}
+/**
+ * Get the display label for a node execution status
+ */
+export function getStatusLabel(status) {
+    const statusLabels = {
+        idle: 'Idle',
+        pending: 'Pending',
+        running: 'Running',
+        completed: 'Completed',
+        failed: 'Failed',
+        cancelled: 'Cancelled',
+        skipped: 'Skipped'
+    };
+    return statusLabels[status] || statusLabels.idle;
+}
+/**
+ * Get the background color for a node execution status overlay
+ */
+export function getStatusBackgroundColor(status) {
+    const statusBackgroundColors = {
+        idle: '#f9fafb', // light gray
+        pending: '#fef3c7', // light amber
+        running: '#dbeafe', // light blue
+        completed: '#d1fae5', // light emerald
+        failed: '#fee2e2', // light red
+        cancelled: '#f3f4f6', // light gray
+        skipped: '#ede9fe' // light violet
+    };
+    return statusBackgroundColors[status] || statusBackgroundColors.idle;
+}
+/**
+ * Get the text color for a node execution status overlay
+ */
+export function getStatusTextColor(status) {
+    const statusTextColors = {
+        idle: '#6b7280', // gray
+        pending: '#d97706', // amber
+        running: '#1d4ed8', // blue
+        completed: '#059669', // emerald
+        failed: '#dc2626', // red
+        cancelled: '#6b7280', // gray
+        skipped: '#7c3aed' // violet
+    };
+    return statusTextColors[status] || statusTextColors.idle;
+}
+/**
+ * Create a default NodeExecutionInfo object
+ */
+export function createDefaultExecutionInfo() {
+    return {
+        status: 'idle',
+        executionCount: 0,
+        isExecuting: false
+    };
+}
+/**
+ * Update node execution info when execution starts
+ */
+export function updateExecutionStart(executionInfo) {
+    return {
+        ...executionInfo,
+        status: 'running',
+        isExecuting: true
+    };
+}
+/**
+ * Update node execution info when execution completes successfully
+ */
+export function updateExecutionComplete(executionInfo, duration) {
+    return {
+        ...executionInfo,
+        status: 'completed',
+        executionCount: executionInfo.executionCount + 1,
+        lastExecuted: new Date().toISOString(),
+        lastExecutionDuration: duration,
+        isExecuting: false,
+        lastError: undefined // Clear any previous error
+    };
+}
+/**
+ * Update node execution info when execution fails
+ */
+export function updateExecutionFailed(executionInfo, error, duration) {
+    return {
+        ...executionInfo,
+        status: 'failed',
+        executionCount: executionInfo.executionCount + 1,
+        lastExecuted: new Date().toISOString(),
+        lastExecutionDuration: duration,
+        isExecuting: false,
+        lastError: error
+    };
+}
+/**
+ * Reset node execution info
+ */
+export function resetExecutionInfo(executionInfo) {
+    return {
+        ...executionInfo,
+        status: 'idle',
+        isExecuting: false,
+        lastError: undefined
+    };
+}
+/**
+ * Format execution duration for display
+ */
+export function formatExecutionDuration(duration) {
+    if (!duration)
+        return 'N/A';
+    if (duration < 1000) {
+        return `${Math.round(duration)}ms`;
+    }
+    else if (duration < 60000) {
+        return `${(duration / 1000).toFixed(1)}s`;
+    }
+    else {
+        const minutes = Math.floor(duration / 60000);
+        const seconds = Math.floor((duration % 60000) / 1000);
+        return `${minutes}m ${seconds}s`;
+    }
+}
+/**
+ * Format last executed timestamp for display
+ */
+export function formatLastExecuted(timestamp) {
+    if (!timestamp)
+        return 'Never';
+    const date = new Date(timestamp);
+    const now = new Date();
+    const diffMs = now.getTime() - date.getTime();
+    if (diffMs < 60000) {
+        // Less than 1 minute
+        return 'Just now';
+    }
+    else if (diffMs < 3600000) {
+        // Less than 1 hour
+        const minutes = Math.floor(diffMs / 60000);
+        return `${minutes}m ago`;
+    }
+    else if (diffMs < 86400000) {
+        // Less than 1 day
+        const hours = Math.floor(diffMs / 3600000);
+        return `${hours}h ago`;
+    }
+    else {
+        return date.toLocaleDateString();
+    }
+}