@flowdrop/flowdrop 1.0.0

package/dist/utils/nodeTypes.d.ts

@@ -0,0 +1,117 @@
+/**
+ * Node type utilities for FlowDrop
+ * Handles dynamic node type resolution based on NodeMetadata.
+ *
+ * This module provides utilities for:
+ * - Resolving which node type to use based on metadata and config
+ * - Getting available node types for a given metadata
+ * - Creating config schema properties for node type selection
+ *
+ * Works with both built-in types and custom registered types.
+ */
+import type { NodeType, NodeMetadata } from '../types/index.js';
+/**
+ * Gets the SvelteFlow component name for a given NodeType.
+ * Uses the node component registry to resolve types.
+ *
+ * @param nodeType - The node type identifier
+ * @returns The component name to use
+ */
+export declare function getComponentNameForNodeType(nodeType: NodeType | string): string;
+/**
+ * Gets the available node types for a given NodeMetadata.
+ * Priority: supportedTypes > type > "default"
+ *
+ * @param metadata - The node metadata
+ * @returns Array of available node type identifiers
+ */
+export declare function getAvailableNodeTypes(metadata: NodeMetadata): (NodeType | string)[];
+/**
+ * Gets the primary (default) node type for a given NodeMetadata.
+ * This is used when no specific type is configured by the user.
+ *
+ * @param metadata - The node metadata
+ * @returns The primary node type
+ */
+export declare function getPrimaryNodeType(metadata: NodeMetadata): NodeType | string;
+/**
+ * Determines the appropriate node type based on configuration and metadata.
+ *
+ * Priority:
+ * 1. configNodeType (if valid for this metadata)
+ * 2. metadata.type (if valid)
+ * 3. First supportedType
+ * 4. "default"
+ *
+ * @param metadata - The node metadata
+ * @param configNodeType - Optional type from user config
+ * @returns The resolved node type
+ */
+export declare function resolveNodeType(metadata: NodeMetadata, configNodeType?: string): NodeType | string;
+/**
+ * Gets the SvelteFlow component name for resolved node type.
+ * This is the main function used by UniversalNode to determine which component to render.
+ *
+ * @param metadata - The node metadata
+ * @param configNodeType - Optional type from user config
+ * @returns The component name to use
+ */
+export declare function resolveComponentName(metadata: NodeMetadata, configNodeType?: string): string;
+/**
+ * Validates if a node type is supported by the given metadata.
+ *
+ * @param metadata - The node metadata
+ * @param nodeType - The type to check
+ * @returns true if the type is supported
+ */
+export declare function isNodeTypeSupported(metadata: NodeMetadata, nodeType: NodeType | string): boolean;
+/**
+ * Gets oneOf options for node type configuration.
+ * Used in config schemas to show available options with labels.
+ *
+ * This function combines:
+ * - Types specified in metadata.supportedTypes
+ * - Registered custom types (optionally filtered)
+ *
+ * @param metadata - The node metadata
+ * @param includeCustomTypes - Whether to include registered custom types
+ * @returns Array of oneOf items with const (type value) and title (display name)
+ */
+export declare function getNodeTypeOneOfOptions(metadata: NodeMetadata, includeCustomTypes?: boolean): Array<{
+    const: string;
+    title: string;
+}>;
+/**
+ * Creates a nodeType config property that respects supportedTypes.
+ * This replaces hardcoded enum values in config schemas.
+ *
+ * Uses JSON Schema `oneOf` pattern with `const`/`title` for labeled options,
+ * which is the standard approach supported by form components.
+ *
+ * @param metadata - The node metadata
+ * @param defaultType - Optional default type override
+ * @returns Config schema property object with oneOf for labeled options
+ */
+export declare function createNodeTypeConfigProperty(metadata: NodeMetadata, defaultType?: NodeType | string): {
+    type: "string";
+    title: string;
+    description: string;
+    default: string;
+    oneOf: {
+        const: string;
+        title: string;
+    }[];
+};
+/**
+ * Check if a type string represents a valid registered or built-in type.
+ *
+ * @param type - The type to check
+ * @returns true if the type is valid
+ */
+export declare function isValidNodeType(type: string): boolean;
+/**
+ * Get all available node types (built-in + registered).
+ *
+ * @returns Array of all valid node type identifiers
+ */
+export declare function getAllNodeTypes(): string[];

package/dist/utils/nodeTypes.js

@@ -0,0 +1,244 @@
+/**
+ * Node type utilities for FlowDrop
+ * Handles dynamic node type resolution based on NodeMetadata.
+ *
+ * This module provides utilities for:
+ * - Resolving which node type to use based on metadata and config
+ * - Getting available node types for a given metadata
+ * - Creating config schema properties for node type selection
+ *
+ * Works with both built-in types and custom registered types.
+ */
+import { nodeComponentRegistry } from '../registry/nodeComponentRegistry.js';
+import { resolveBuiltinAlias, isBuiltinType } from '../registry/builtinNodes.js';
+/**
+ * Display names for built-in node types.
+ */
+const TYPE_DISPLAY_NAMES = {
+    note: 'Note (sticky note style)',
+    simple: 'Simple (compact layout)',
+    square: 'Square (geometric layout)',
+    tool: 'Tool (specialized for agent tools)',
+    gateway: 'Gateway (branching control flow)',
+    terminal: 'Terminal (start/end/exit)',
+    default: 'Default (standard workflow node)'
+};
+/**
+ * Gets the SvelteFlow component name for a given NodeType.
+ * Uses the node component registry to resolve types.
+ *
+ * @param nodeType - The node type identifier
+ * @returns The component name to use
+ */
+export function getComponentNameForNodeType(nodeType) {
+    // Resolve aliases first (e.g., "default" -> "workflowNode")
+    const resolvedType = resolveBuiltinAlias(nodeType);
+    // Check if it's registered in the registry
+    if (nodeComponentRegistry.has(resolvedType)) {
+        return resolvedType;
+    }
+    // Unknown type - return workflowNode as default
+    return 'workflowNode';
+}
+/**
+ * Gets the available node types for a given NodeMetadata.
+ * Priority: supportedTypes > type > "default"
+ *
+ * @param metadata - The node metadata
+ * @returns Array of available node type identifiers
+ */
+export function getAvailableNodeTypes(metadata) {
+    if (metadata.supportedTypes && metadata.supportedTypes.length > 0) {
+        return metadata.supportedTypes;
+    }
+    if (metadata.type) {
+        return [metadata.type];
+    }
+    return ['default'];
+}
+/**
+ * Gets the primary (default) node type for a given NodeMetadata.
+ * This is used when no specific type is configured by the user.
+ *
+ * @param metadata - The node metadata
+ * @returns The primary node type
+ */
+export function getPrimaryNodeType(metadata) {
+    const availableTypes = getAvailableNodeTypes(metadata);
+    return availableTypes[0];
+}
+/**
+ * Determines the appropriate node type based on configuration and metadata.
+ *
+ * Priority:
+ * 1. configNodeType (if valid for this metadata)
+ * 2. metadata.type (if valid)
+ * 3. First supportedType
+ * 4. "default"
+ *
+ * @param metadata - The node metadata
+ * @param configNodeType - Optional type from user config
+ * @returns The resolved node type
+ */
+export function resolveNodeType(metadata, configNodeType) {
+    const availableTypes = getAvailableNodeTypes(metadata);
+    // Check if configNodeType is valid for this metadata
+    if (configNodeType) {
+        // Resolve alias for comparison
+        const resolvedConfig = resolveBuiltinAlias(configNodeType);
+        // Check if it's in available types
+        if (availableTypes.includes(configNodeType) ||
+            availableTypes.includes(resolvedConfig)) {
+            return configNodeType;
+        }
+        // Check if it's a registered custom type
+        if (nodeComponentRegistry.has(configNodeType) || nodeComponentRegistry.has(resolvedConfig)) {
+            return configNodeType;
+        }
+    }
+    // Fall back to primary type
+    return getPrimaryNodeType(metadata);
+}
+/**
+ * Gets the SvelteFlow component name for resolved node type.
+ * This is the main function used by UniversalNode to determine which component to render.
+ *
+ * @param metadata - The node metadata
+ * @param configNodeType - Optional type from user config
+ * @returns The component name to use
+ */
+export function resolveComponentName(metadata, configNodeType) {
+    const nodeType = resolveNodeType(metadata, configNodeType);
+    return getComponentNameForNodeType(nodeType);
+}
+/**
+ * Validates if a node type is supported by the given metadata.
+ *
+ * @param metadata - The node metadata
+ * @param nodeType - The type to check
+ * @returns true if the type is supported
+ */
+export function isNodeTypeSupported(metadata, nodeType) {
+    const availableTypes = getAvailableNodeTypes(metadata);
+    // Check direct match
+    if (availableTypes.includes(nodeType)) {
+        return true;
+    }
+    // Check alias match
+    const resolvedType = resolveBuiltinAlias(nodeType);
+    if (availableTypes.includes(resolvedType)) {
+        return true;
+    }
+    // Check if it's a registered custom type that's in the available list
+    if (nodeComponentRegistry.has(nodeType)) {
+        return availableTypes.some((t) => t === nodeType || resolveBuiltinAlias(t) === nodeType);
+    }
+    return false;
+}
+/**
+ * Gets oneOf options for node type configuration.
+ * Used in config schemas to show available options with labels.
+ *
+ * This function combines:
+ * - Types specified in metadata.supportedTypes
+ * - Registered custom types (optionally filtered)
+ *
+ * @param metadata - The node metadata
+ * @param includeCustomTypes - Whether to include registered custom types
+ * @returns Array of oneOf items with const (type value) and title (display name)
+ */
+export function getNodeTypeOneOfOptions(metadata, includeCustomTypes = false) {
+    const availableTypes = getAvailableNodeTypes(metadata);
+    const options = [];
+    const includedTypes = new Set();
+    for (const type of availableTypes) {
+        includedTypes.add(type);
+        // Get display name from registry or fallback to built-in names
+        const registration = nodeComponentRegistry.get(type);
+        let title;
+        if (registration) {
+            title = registration.displayName;
+        }
+        else if (type in TYPE_DISPLAY_NAMES) {
+            title = TYPE_DISPLAY_NAMES[type];
+        }
+        else {
+            // Format unknown type nicely
+            title = formatTypeName(type);
+        }
+        options.push({ const: type, title });
+    }
+    // Optionally include all registered custom types
+    if (includeCustomTypes) {
+        const registrations = nodeComponentRegistry.filter({
+            predicate: (reg) => !isBuiltinType(reg.type) && !includedTypes.has(reg.type)
+        });
+        for (const reg of registrations) {
+            options.push({ const: reg.type, title: reg.displayName });
+        }
+    }
+    return options;
+}
+/**
+ * Creates a nodeType config property that respects supportedTypes.
+ * This replaces hardcoded enum values in config schemas.
+ *
+ * Uses JSON Schema `oneOf` pattern with `const`/`title` for labeled options,
+ * which is the standard approach supported by form components.
+ *
+ * @param metadata - The node metadata
+ * @param defaultType - Optional default type override
+ * @returns Config schema property object with oneOf for labeled options
+ */
+export function createNodeTypeConfigProperty(metadata, defaultType) {
+    const oneOf = getNodeTypeOneOfOptions(metadata);
+    const primaryType = defaultType ?? getPrimaryNodeType(metadata);
+    return {
+        type: 'string',
+        title: 'Node Type',
+        description: 'Choose the visual representation for this node',
+        default: primaryType,
+        oneOf
+    };
+}
+/**
+ * Check if a type string represents a valid registered or built-in type.
+ *
+ * @param type - The type to check
+ * @returns true if the type is valid
+ */
+export function isValidNodeType(type) {
+    return isBuiltinType(type) || nodeComponentRegistry.has(type);
+}
+/**
+ * Get all available node types (built-in + registered).
+ *
+ * @returns Array of all valid node type identifiers
+ */
+export function getAllNodeTypes() {
+    return nodeComponentRegistry.getTypes();
+}
+/**
+ * Format a type name for display when no display name is registered.
+ *
+ * @param type - The raw type string
+ * @returns Formatted display name
+ */
+function formatTypeName(type) {
+    // Handle namespaced types (e.g., "mylib:fancy" -> "Mylib: Fancy")
+    if (type.includes(':')) {
+        const [namespace, name] = type.split(':');
+        return `${capitalize(namespace)}: ${capitalize(name)}`;
+    }
+    // Capitalize and add spaces for camelCase
+    return capitalize(type.replace(/([A-Z])/g, ' $1').trim());
+}
+/**
+ * Capitalize the first letter of a string.
+ *
+ * @param str - The string to capitalize
+ * @returns Capitalized string
+ */
+function capitalize(str) {
+    return str.charAt(0).toUpperCase() + str.slice(1);
+}

package/dist/utils/nodeWrapper.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Node Wrapper Utilities
+ * Provides utilities for wrapping nodes with status overlays
+ */
+import type { NodeExecutionInfo } from '../types/index.js';
+/**
+ * Configuration for node status overlay
+ */
+export interface NodeStatusConfig {
+    position?: 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+    size?: 'sm' | 'md' | 'lg';
+    showDetails?: boolean;
+}
+/**
+ * Default configuration for node status overlays
+ */
+export declare const DEFAULT_NODE_STATUS_CONFIG: NodeStatusConfig;
+/**
+ * Create a node wrapper configuration
+ */
+export declare function createNodeWrapperConfig(nodeId: string, executionInfo?: NodeExecutionInfo, config?: NodeStatusConfig): {
+    nodeId: string;
+    executionInfo?: NodeExecutionInfo;
+    statusPosition: NodeStatusConfig['position'];
+    statusSize: NodeStatusConfig['size'];
+    showStatusDetails: boolean;
+};
+/**
+ * Check if a node should show status overlay
+ */
+export declare function shouldShowNodeStatus(executionInfo?: NodeExecutionInfo): boolean;
+/**
+ * Get optimal status position based on node type
+ */
+export declare function getOptimalStatusPosition(nodeType: string): NodeStatusConfig['position'];
+/**
+ * Get optimal status size based on node type
+ */
+export declare function getOptimalStatusSize(nodeType: string): NodeStatusConfig['size'];

package/dist/utils/nodeWrapper.js

@@ -0,0 +1,62 @@
+/**
+ * Node Wrapper Utilities
+ * Provides utilities for wrapping nodes with status overlays
+ */
+/**
+ * Default configuration for node status overlays
+ */
+export const DEFAULT_NODE_STATUS_CONFIG = {
+    position: 'top-right',
+    size: 'md',
+    showDetails: true
+};
+/**
+ * Create a node wrapper configuration
+ */
+export function createNodeWrapperConfig(nodeId, executionInfo, config = {}) {
+    return {
+        nodeId,
+        executionInfo,
+        statusPosition: config.position || DEFAULT_NODE_STATUS_CONFIG.position,
+        statusSize: config.size || DEFAULT_NODE_STATUS_CONFIG.size,
+        showStatusDetails: config.showDetails ?? DEFAULT_NODE_STATUS_CONFIG.showDetails ?? true
+    };
+}
+/**
+ * Check if a node should show status overlay
+ */
+export function shouldShowNodeStatus(executionInfo) {
+    if (!executionInfo)
+        return false;
+    return (executionInfo.status !== 'idle' || executionInfo.executionCount > 0 || executionInfo.isExecuting);
+}
+/**
+ * Get optimal status position based on node type
+ */
+export function getOptimalStatusPosition(nodeType) {
+    switch (nodeType) {
+        case 'tool':
+            return 'top-left';
+        case 'note':
+            return 'bottom-right';
+        case 'simple':
+        case 'square':
+        default:
+            return 'top-right';
+    }
+}
+/**
+ * Get optimal status size based on node type
+ */
+export function getOptimalStatusSize(nodeType) {
+    switch (nodeType) {
+        case 'tool':
+            return 'sm';
+        case 'note':
+            return 'sm';
+        case 'simple':
+        case 'square':
+        default:
+            return 'md';
+    }
+}

package/dist/utils/performanceUtils.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Performance Utilities
+ * Helper functions for optimizing performance in the FlowDrop app
+ */
+import type { WorkflowNode, WorkflowEdge } from '../types/index.js';
+/**
+ * Fast shallow comparison for workflow nodes
+ * Avoids expensive JSON.stringify operations
+ */
+export declare function areNodeArraysEqual(nodes1: WorkflowNode[], nodes2: WorkflowNode[]): boolean;
+/**
+ * Fast shallow comparison for workflow edges
+ * Avoids expensive JSON.stringify operations
+ */
+export declare function areEdgeArraysEqual(edges1: WorkflowEdge[], edges2: WorkflowEdge[]): boolean;
+/**
+ * Throttle function execution to reduce frequency
+ * Uses requestAnimationFrame for smooth UI updates
+ */
+export declare function throttle<T extends (...args: any[]) => void>(func: T, wait: number): (...args: Parameters<T>) => void;
+/**
+ * Debounce function execution to reduce frequency
+ * Waits for a pause in calls before executing
+ */
+export declare function debounce<T extends (...args: any[]) => void>(func: T, wait: number): (...args: Parameters<T>) => void;
+/**
+ * RequestAnimationFrame-based throttle for smooth animations
+ * Better for visual updates like node dragging
+ */
+export declare function rafThrottle<T extends (...args: any[]) => void>(func: T): (...args: Parameters<T>) => void;

package/dist/utils/performanceUtils.js

@@ -0,0 +1,108 @@
+/**
+ * Performance Utilities
+ * Helper functions for optimizing performance in the FlowDrop app
+ */
+/**
+ * Fast shallow comparison for workflow nodes
+ * Avoids expensive JSON.stringify operations
+ */
+export function areNodeArraysEqual(nodes1, nodes2) {
+    if (nodes1.length !== nodes2.length)
+        return false;
+    for (let i = 0; i < nodes1.length; i++) {
+        const node1 = nodes1[i];
+        const node2 = nodes2[i];
+        // Quick ID check
+        if (node1?.id !== node2?.id)
+            return false;
+        // Check position (most common change during drag)
+        if (node1?.position?.x !== node2?.position?.x || node1?.position?.y !== node2?.position?.y) {
+            return false;
+        }
+        // Check selected state
+        if (node1?.selected !== node2?.selected)
+            return false;
+        // Skip deep config comparison unless we need to
+        // Most updates are position-based
+    }
+    return true;
+}
+/**
+ * Fast shallow comparison for workflow edges
+ * Avoids expensive JSON.stringify operations
+ */
+export function areEdgeArraysEqual(edges1, edges2) {
+    if (edges1.length !== edges2.length)
+        return false;
+    for (let i = 0; i < edges1.length; i++) {
+        const edge1 = edges1[i];
+        const edge2 = edges2[i];
+        if (edge1?.id !== edge2?.id ||
+            edge1?.source !== edge2?.source ||
+            edge1?.target !== edge2?.target ||
+            edge1?.sourceHandle !== edge2?.sourceHandle ||
+            edge1?.targetHandle !== edge2?.targetHandle) {
+            return false;
+        }
+    }
+    return true;
+}
+/**
+ * Throttle function execution to reduce frequency
+ * Uses requestAnimationFrame for smooth UI updates
+ */
+export function throttle(func, wait) {
+    let timeout = null;
+    let lastRan = 0;
+    return function (...args) {
+        const now = Date.now();
+        if (!lastRan || now - lastRan >= wait) {
+            func(...args);
+            lastRan = now;
+        }
+        else {
+            if (timeout) {
+                clearTimeout(timeout);
+            }
+            timeout = setTimeout(() => {
+                func(...args);
+                lastRan = Date.now();
+            }, wait - (now - lastRan));
+        }
+    };
+}
+/**
+ * Debounce function execution to reduce frequency
+ * Waits for a pause in calls before executing
+ */
+export function debounce(func, wait) {
+    let timeout = null;
+    return function (...args) {
+        if (timeout) {
+            clearTimeout(timeout);
+        }
+        timeout = setTimeout(() => {
+            func(...args);
+        }, wait);
+    };
+}
+/**
+ * RequestAnimationFrame-based throttle for smooth animations
+ * Better for visual updates like node dragging
+ */
+export function rafThrottle(func) {
+    let rafId = null;
+    let lastArgs = null;
+    return function (...args) {
+        lastArgs = args;
+        if (rafId === null) {
+            rafId = requestAnimationFrame(() => {
+                if (lastArgs) {
+                    func(...lastArgs);
+                }
+                rafId = null;
+                lastArgs = null;
+            });
+        }
+    };
+}

package/dist/utils/sanitize.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Sanitize an HTML string to prevent XSS attacks.
+ *
+ * Uses DOMPurify defaults which strip dangerous elements (script, iframe, object)
+ * and event handler attributes (onerror, onclick, etc.) while preserving safe HTML
+ * elements typically produced by markdown renderers.
+ *
+ * @param dirty - The untrusted HTML string to sanitize
+ * @returns Sanitized HTML string safe for use with {@html}
+ *
+ * @example
+ * ```typescript
+ * import { sanitizeHtml } from '@flowdrop/flowdrop/core';
+ * import { marked } from 'marked';
+ *
+ * const safeHtml = sanitizeHtml(marked.parse(userInput) as string);
+ * ```
+ */
+export declare function sanitizeHtml(dirty: string): string;

package/dist/utils/sanitize.js

@@ -0,0 +1,31 @@
+/**
+ * HTML Sanitization Utility
+ *
+ * Provides XSS protection for rendered HTML content using DOMPurify.
+ * Used internally by components that render user-provided or API-provided HTML
+ * (e.g., markdown output, interrupt review diffs).
+ *
+ * @module utils/sanitize
+ */
+import DOMPurify from 'dompurify';
+/**
+ * Sanitize an HTML string to prevent XSS attacks.
+ *
+ * Uses DOMPurify defaults which strip dangerous elements (script, iframe, object)
+ * and event handler attributes (onerror, onclick, etc.) while preserving safe HTML
+ * elements typically produced by markdown renderers.
+ *
+ * @param dirty - The untrusted HTML string to sanitize
+ * @returns Sanitized HTML string safe for use with {@html}
+ *
+ * @example
+ * ```typescript
+ * import { sanitizeHtml } from '@flowdrop/flowdrop/core';
+ * import { marked } from 'marked';
+ *
+ * const safeHtml = sanitizeHtml(marked.parse(userInput) as string);
+ * ```
+ */
+export function sanitizeHtml(dirty) {
+    return DOMPurify.sanitize(dirty);
+}