@flowdrop/flowdrop 1.0.0

package/dist/types/playground.d.ts

@@ -0,0 +1,351 @@
+/**
+ * Playground Types
+ *
+ * TypeScript types for the Playground feature, enabling interactive
+ * workflow testing with chat interface and session management.
+ *
+ * @module types/playground
+ */
+import type { ConfigProperty } from './index.js';
+/**
+ * Status of a playground session
+ */
+export type PlaygroundSessionStatus = 'idle' | 'running' | 'awaiting_input' | 'completed' | 'failed';
+/**
+ * Statuses that stop polling by default (resource efficiency)
+ */
+export declare const DEFAULT_STOP_POLLING_STATUSES: PlaygroundSessionStatus[];
+/**
+ * Statuses that are considered terminal by default (clears isExecuting)
+ */
+export declare const DEFAULT_TERMINAL_STATUSES: PlaygroundSessionStatus[];
+/**
+ * Default implementation for determining if polling should stop.
+ * Consumers can override this via PlaygroundConfig.shouldStopPolling.
+ *
+ * @param status - The current session status
+ * @returns True if polling should stop
+ */
+export declare function defaultShouldStopPolling(status: PlaygroundSessionStatus): boolean;
+/**
+ * Default implementation for determining if a status is terminal (clears isExecuting).
+ * Consumers can override this via PlaygroundConfig.isTerminalStatus.
+ *
+ * @param status - The current session status
+ * @returns True if the status is terminal
+ */
+export declare function defaultIsTerminalStatus(status: PlaygroundSessionStatus): boolean;
+/**
+ * Role of a message sender in the playground
+ *
+ * - `user`: Message from the user
+ * - `assistant`: Response from the workflow/AI
+ * - `system`: System notifications
+ * - `log`: Execution log entries
+ */
+export type PlaygroundMessageRole = 'user' | 'assistant' | 'system' | 'log';
+/**
+ * Log level for log-type messages
+ */
+export type PlaygroundMessageLevel = 'info' | 'warning' | 'error' | 'debug';
+/**
+ * Status of a playground message
+ */
+export type PlaygroundMessageStatus = 'pending' | 'processing' | 'completed' | 'failed';
+/**
+ * Playground session representing a test conversation
+ *
+ * Sessions maintain conversation history and allow interactive testing
+ * of workflows in an isolated environment.
+ *
+ * @example
+ * ```typescript
+ * const session: PlaygroundSession = {
+ *   id: "sess-123",
+ *   workflowId: "wf-456",
+ *   name: "Test Session 1",
+ *   status: "idle",
+ *   createdAt: "2024-01-20T10:00:00Z",
+ *   updatedAt: "2024-01-20T10:30:00Z"
+ * };
+ * ```
+ */
+export interface PlaygroundSession {
+    /** Session unique identifier */
+    id: string;
+    /** Associated workflow ID */
+    workflowId: string;
+    /** Session display name */
+    name: string;
+    /** Current session status */
+    status: PlaygroundSessionStatus;
+    /** Session creation timestamp (ISO 8601) */
+    createdAt: string;
+    /** Last activity timestamp (ISO 8601) */
+    updatedAt: string;
+    /** Custom session metadata */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Message metadata containing additional context
+ */
+export interface PlaygroundMessageMetadata {
+    /** Log level for log-type messages */
+    level?: PlaygroundMessageLevel;
+    /** Execution duration in milliseconds */
+    duration?: number;
+    /** Human-readable node label */
+    nodeLabel?: string;
+    /** Node output data */
+    outputs?: Record<string, unknown>;
+    /** User's display name for user-role messages (from backend) */
+    userName?: string;
+    /** Allow additional properties */
+    [key: string]: unknown;
+}
+/**
+ * Message in a playground session
+ *
+ * Messages can be user inputs, assistant responses, system notifications,
+ * or execution logs. Each message is timestamped and can be associated
+ * with a specific workflow node.
+ *
+ * @example
+ * ```typescript
+ * const message: PlaygroundMessage = {
+ *   id: "msg-123",
+ *   sessionId: "sess-456",
+ *   role: "assistant",
+ *   content: "I've analyzed your data and found 3 patterns.",
+ *   timestamp: "2024-01-20T10:30:00Z",
+ *   nodeId: "node-ai-analyzer",
+ *   metadata: { duration: 2500, nodeLabel: "AI Analyzer" }
+ * };
+ * ```
+ */
+export interface PlaygroundMessage {
+    /** Message unique identifier */
+    id: string;
+    /** Parent session ID */
+    sessionId: string;
+    /** Role of the message sender */
+    role: PlaygroundMessageRole;
+    /** Message content */
+    content: string;
+    /** Message timestamp (ISO 8601) */
+    timestamp: string;
+    /** Message status */
+    status?: PlaygroundMessageStatus;
+    /**
+     * Sequence number for ordering messages
+     * - User messages: incrementing numbers (1, 2, 3, ...)
+     * - Assistant/system responses: 0 (sorted after parent via parentMessageId)
+     */
+    sequenceNumber?: number;
+    /** Parent message ID (for assistant responses linked to user messages) */
+    parentMessageId?: string;
+    /** Associated node ID (for log/assistant messages) */
+    nodeId?: string | null;
+    /** Additional message metadata */
+    metadata?: PlaygroundMessageMetadata;
+}
+/**
+ * Input field derived from workflow input nodes
+ *
+ * Used to auto-generate input forms in the playground based on
+ * the workflow's input nodes' configSchema.
+ *
+ * @example
+ * ```typescript
+ * const inputField: PlaygroundInputField = {
+ *   nodeId: "node-text-input",
+ *   fieldId: "user_message",
+ *   label: "User Message",
+ *   type: "string",
+ *   defaultValue: "Hello!",
+ *   required: true,
+ *   schema: { type: "string", format: "multiline" }
+ * };
+ * ```
+ */
+export interface PlaygroundInputField {
+    /** Source node ID */
+    nodeId: string;
+    /** Field identifier */
+    fieldId: string;
+    /** Display label */
+    label: string;
+    /** Field data type */
+    type: string;
+    /** Default value from node config */
+    defaultValue?: unknown;
+    /** Whether the field is required */
+    required: boolean;
+    /** JSON Schema for the field */
+    schema?: ConfigProperty;
+}
+/**
+ * Request payload for sending a message to the playground
+ */
+export interface PlaygroundMessageRequest {
+    /** Message content (typically user input) */
+    content: string;
+    /** Additional input values for workflow nodes */
+    inputs?: Record<string, unknown>;
+}
+/**
+ * Response from the messages endpoint with polling support
+ */
+export interface PlaygroundMessagesResult {
+    /** Array of messages */
+    messages: PlaygroundMessage[];
+    /** Whether there are more messages to fetch */
+    hasMore: boolean;
+    /** Current session status (useful for polling) */
+    sessionStatus: PlaygroundSessionStatus;
+}
+/**
+ * Configuration for the Playground component
+ */
+export interface PlaygroundConfig {
+    /** Polling interval in milliseconds (default: 1500) */
+    pollingInterval?: number;
+    /** Maximum number of messages to display (default: 500) */
+    maxMessages?: number;
+    /** Auto-scroll to bottom on new messages (default: true) */
+    autoScroll?: boolean;
+    /** Show timestamps on messages (default: true) */
+    showTimestamps?: boolean;
+    /** Show log messages inline or in collapsible section (default: "collapsible") */
+    logDisplayMode?: 'inline' | 'collapsible';
+    /** Enable markdown rendering in messages (default: true) */
+    enableMarkdown?: boolean;
+    /**
+     * Whether to show the chat text input (default: true)
+     * When false, only the "Run" button is displayed for workflow execution.
+     */
+    showChatInput?: boolean;
+    /**
+     * Whether to show the "Run" button (default: true)
+     * When false, the Run button is hidden. If both showChatInput and showRunButton
+     * are false, a helpful message is displayed to the user.
+     */
+    showRunButton?: boolean;
+    /**
+     * Predefined message to send when "Run" button is clicked (default: "Run workflow")
+     * Used when showChatInput is false to provide a default message for workflow execution.
+     */
+    predefinedMessage?: string;
+    /**
+     * Automatically run the workflow once when the playground loads (default: false)
+     * When true, the workflow will execute immediately using the predefinedMessage.
+     * This is useful for scenarios where the workflow should start without user interaction.
+     * Note: Only runs once per session - subsequent runs require clicking the Run button.
+     */
+    autoRun?: boolean;
+    /**
+     * Width of the sidebar in CSS units (default: "280px")
+     * Accepts any valid CSS width value, e.g. "300px", "20rem".
+     */
+    sidebarWidth?: string;
+    /**
+     * Whether to show the sidebar with session list (default: true)
+     * When false, the sidebar is hidden, creating a minimal chat widget experience.
+     * Use with initialSessionId to load a pre-created session directly.
+     */
+    showSidebar?: boolean;
+    /**
+     * Whether to show the session header bar (default: true)
+     * When false, the header with session name and close button is hidden.
+     * Typically used together with showSidebar: false for minimal UI.
+     */
+    showSessionHeader?: boolean;
+    /**
+     * Determines if polling should stop for a given session status.
+     * Override to customize which statuses pause polling.
+     * @default defaultShouldStopPolling (stops on idle, completed, failed, awaiting_input)
+     */
+    shouldStopPolling?: (status: PlaygroundSessionStatus) => boolean;
+    /**
+     * Determines if a session status is terminal (clears isExecuting).
+     * Override to customize which statuses end the executing state.
+     * @default defaultIsTerminalStatus (terminal on idle, completed, failed, awaiting_input)
+     */
+    isTerminalStatus?: (status: PlaygroundSessionStatus) => boolean;
+}
+/**
+ * Metadata field to control Run button state from backend.
+ * When a message contains this field set to true, the Run button becomes enabled.
+ *
+ * @example
+ * ```typescript
+ * // Backend sends a message with this metadata to re-enable Run button:
+ * const message: PlaygroundMessage = {
+ *   id: "msg-123",
+ *   sessionId: "sess-456",
+ *   role: "system",
+ *   content: "Workflow completed. Ready for next run.",
+ *   timestamp: new Date().toISOString(),
+ *   metadata: {
+ *     enableRun: true
+ *   }
+ * };
+ * ```
+ */
+export declare const ENABLE_RUN_METADATA_KEY = "enableRun";
+/**
+ * Check if a message metadata contains the enableRun flag
+ *
+ * @param metadata - The message metadata to check
+ * @returns True if the metadata signals to enable the Run button
+ */
+export declare function hasEnableRunFlag(metadata: PlaygroundMessageMetadata | undefined): boolean;
+/**
+ * Display mode for the Playground component
+ */
+export type PlaygroundMode = 'embedded' | 'standalone' | 'modal';
+/**
+ * Chat input detection patterns for identifying chat nodes in workflows
+ */
+export declare const CHAT_INPUT_PATTERNS: readonly ["chat_input", "text_input", "user_input", "message_input", "prompt_input"];
+/**
+ * Check if a node type is a chat input node
+ *
+ * @param nodeTypeId - The node type identifier
+ * @returns True if the node is a chat input type
+ */
+export declare function isChatInputNode(nodeTypeId: string): boolean;
+/**
+ * API response wrapper for playground endpoints
+ */
+export interface PlaygroundApiResponse<T> {
+    /** Whether the request was successful */
+    success: boolean;
+    /** Response data */
+    data?: T;
+    /** Error message if unsuccessful */
+    error?: string;
+    /** Human-readable message */
+    message?: string;
+}
+/**
+ * Type alias for session list response
+ */
+export type PlaygroundSessionsResponse = PlaygroundApiResponse<PlaygroundSession[]>;
+/**
+ * Type alias for single session response
+ */
+export type PlaygroundSessionResponse = PlaygroundApiResponse<PlaygroundSession>;
+/**
+ * Type alias for message response
+ */
+export type PlaygroundMessageResponse = PlaygroundApiResponse<PlaygroundMessage>;
+/**
+ * Type alias for messages list response with polling metadata
+ */
+export interface PlaygroundMessagesApiResponse extends PlaygroundApiResponse<PlaygroundMessage[]> {
+    /** Whether there are more messages to fetch */
+    hasMore?: boolean;
+    /** Current session status */
+    sessionStatus?: PlaygroundSessionStatus;
+}

package/dist/types/playground.js

@@ -0,0 +1,95 @@
+/**
+ * Playground Types
+ *
+ * TypeScript types for the Playground feature, enabling interactive
+ * workflow testing with chat interface and session management.
+ *
+ * @module types/playground
+ */
+/**
+ * Statuses that stop polling by default (resource efficiency)
+ */
+export const DEFAULT_STOP_POLLING_STATUSES = [
+    'idle',
+    'completed',
+    'failed',
+    'awaiting_input'
+];
+/**
+ * Statuses that are considered terminal by default (clears isExecuting)
+ */
+export const DEFAULT_TERMINAL_STATUSES = [
+    'idle',
+    'completed',
+    'failed',
+    'awaiting_input'
+];
+/**
+ * Default implementation for determining if polling should stop.
+ * Consumers can override this via PlaygroundConfig.shouldStopPolling.
+ *
+ * @param status - The current session status
+ * @returns True if polling should stop
+ */
+export function defaultShouldStopPolling(status) {
+    return DEFAULT_STOP_POLLING_STATUSES.includes(status);
+}
+/**
+ * Default implementation for determining if a status is terminal (clears isExecuting).
+ * Consumers can override this via PlaygroundConfig.isTerminalStatus.
+ *
+ * @param status - The current session status
+ * @returns True if the status is terminal
+ */
+export function defaultIsTerminalStatus(status) {
+    return DEFAULT_TERMINAL_STATUSES.includes(status);
+}
+/**
+ * Metadata field to control Run button state from backend.
+ * When a message contains this field set to true, the Run button becomes enabled.
+ *
+ * @example
+ * ```typescript
+ * // Backend sends a message with this metadata to re-enable Run button:
+ * const message: PlaygroundMessage = {
+ *   id: "msg-123",
+ *   sessionId: "sess-456",
+ *   role: "system",
+ *   content: "Workflow completed. Ready for next run.",
+ *   timestamp: new Date().toISOString(),
+ *   metadata: {
+ *     enableRun: true
+ *   }
+ * };
+ * ```
+ */
+export const ENABLE_RUN_METADATA_KEY = 'enableRun';
+/**
+ * Check if a message metadata contains the enableRun flag
+ *
+ * @param metadata - The message metadata to check
+ * @returns True if the metadata signals to enable the Run button
+ */
+export function hasEnableRunFlag(metadata) {
+    return metadata?.[ENABLE_RUN_METADATA_KEY] === true;
+}
+/**
+ * Chat input detection patterns for identifying chat nodes in workflows
+ */
+export const CHAT_INPUT_PATTERNS = [
+    'chat_input',
+    'text_input',
+    'user_input',
+    'message_input',
+    'prompt_input'
+];
+/**
+ * Check if a node type is a chat input node
+ *
+ * @param nodeTypeId - The node type identifier
+ * @returns True if the node is a chat input type
+ */
+export function isChatInputNode(nodeTypeId) {
+    const normalizedId = nodeTypeId.toLowerCase();
+    return CHAT_INPUT_PATTERNS.some((pattern) => normalizedId.includes(pattern));
+}

package/dist/types/settings.d.ts

@@ -0,0 +1,189 @@
+/**
+ * Settings Types for FlowDrop
+ *
+ * Provides comprehensive type definitions for all user-configurable settings.
+ * Supports theme, editor, UI, behavior, and API settings with hybrid persistence.
+ *
+ * @module types/settings
+ */
+/**
+ * Theme preference options
+ * - 'light': Force light theme
+ * - 'dark': Force dark theme
+ * - 'auto': Follow system preference
+ */
+export type ThemePreference = 'light' | 'dark' | 'auto';
+/**
+ * Resolved theme (actual applied theme, never 'auto')
+ */
+export type ResolvedTheme = 'light' | 'dark';
+/**
+ * Theme-related settings
+ */
+export interface ThemeSettings {
+    /** User's theme preference */
+    preference: ThemePreference;
+}
+/**
+ * Editor canvas and interaction settings
+ */
+export interface EditorSettings {
+    /** Show grid lines on the canvas */
+    showGrid: boolean;
+    /** Snap nodes to grid when dragging */
+    snapToGrid: boolean;
+    /** Grid cell size in pixels */
+    gridSize: number;
+    /** Show minimap for navigation */
+    showMinimap: boolean;
+    /** Default zoom level (1 = 100%) */
+    defaultZoom: number;
+    /** Automatically fit workflow to view on load */
+    fitViewOnLoad: boolean;
+    /** Enable proximity connect when dragging nodes near other nodes */
+    proximityConnect: boolean;
+    /** Distance threshold in pixels for proximity connect */
+    proximityConnectDistance: number;
+}
+/**
+ * UI layout and display settings
+ */
+export interface UISettings {
+    /** Width of the node sidebar in pixels */
+    sidebarWidth: number;
+    /** Whether the sidebar is collapsed */
+    sidebarCollapsed: boolean;
+    /** Enable compact mode for denser UI */
+    compactMode: boolean;
+}
+/**
+ * Application behavior and automation settings
+ */
+export interface BehaviorSettings {
+    /** Automatically save changes */
+    autoSave: boolean;
+    /** Auto-save interval in milliseconds */
+    autoSaveInterval: number;
+    /** Maximum number of undo history entries */
+    undoHistoryLimit: number;
+    /** Show confirmation dialog before deleting nodes */
+    confirmDelete: boolean;
+}
+/**
+ * API connection and request settings
+ */
+export interface ApiSettings {
+    /** Request timeout in milliseconds */
+    timeout: number;
+    /** Enable automatic retry on failure */
+    retryEnabled: boolean;
+    /** Maximum number of retry attempts */
+    retryAttempts: number;
+    /** Enable response caching */
+    cacheEnabled: boolean;
+}
+/**
+ * All FlowDrop settings organized by category
+ */
+export interface FlowDropSettings {
+    /** Theme appearance settings */
+    theme: ThemeSettings;
+    /** Editor canvas settings */
+    editor: EditorSettings;
+    /** UI layout settings */
+    ui: UISettings;
+    /** Application behavior settings */
+    behavior: BehaviorSettings;
+    /** API connection settings */
+    api: ApiSettings;
+}
+/**
+ * Settings category names for iteration and tab rendering
+ */
+export type SettingsCategory = keyof FlowDropSettings;
+/**
+ * All available settings categories
+ */
+export declare const SETTINGS_CATEGORIES: SettingsCategory[];
+/**
+ * Human-readable labels for settings categories
+ */
+export declare const SETTINGS_CATEGORY_LABELS: Record<SettingsCategory, string>;
+/**
+ * Icons for settings categories (Iconify icon names)
+ */
+export declare const SETTINGS_CATEGORY_ICONS: Record<SettingsCategory, string>;
+/**
+ * Default theme settings
+ */
+export declare const DEFAULT_THEME_SETTINGS: ThemeSettings;
+/**
+ * Default editor settings
+ */
+export declare const DEFAULT_EDITOR_SETTINGS: EditorSettings;
+/**
+ * Default UI settings
+ */
+export declare const DEFAULT_UI_SETTINGS: UISettings;
+/**
+ * Default behavior settings
+ */
+export declare const DEFAULT_BEHAVIOR_SETTINGS: BehaviorSettings;
+/**
+ * Default API settings
+ */
+export declare const DEFAULT_API_SETTINGS: ApiSettings;
+/**
+ * Complete default settings object
+ */
+export declare const DEFAULT_SETTINGS: FlowDropSettings;
+/**
+ * Deep partial type for nested settings updates
+ */
+export type DeepPartial<T> = {
+    [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+/**
+ * Partial settings for incremental updates
+ */
+export type PartialSettings = DeepPartial<FlowDropSettings>;
+/**
+ * Event payload for settings changes
+ */
+export interface SettingsChangeEvent {
+    /** The category that changed */
+    category: SettingsCategory;
+    /** The key within the category that changed */
+    key: string;
+    /** The previous value */
+    previousValue: unknown;
+    /** The new value */
+    newValue: unknown;
+}
+/**
+ * Callback type for settings change listeners
+ */
+export type SettingsChangeCallback = (event: SettingsChangeEvent) => void;
+/**
+ * localStorage key for persisting settings
+ */
+export declare const SETTINGS_STORAGE_KEY = "flowdrop-settings";
+/**
+ * API sync status
+ */
+export type SyncStatus = 'idle' | 'syncing' | 'synced' | 'error';
+/**
+ * Settings store state including sync metadata
+ */
+export interface SettingsStoreState {
+    /** Current settings values */
+    settings: FlowDropSettings;
+    /** Whether settings have been loaded from storage */
+    initialized: boolean;
+    /** API sync status */
+    syncStatus: SyncStatus;
+    /** Last sync timestamp */
+    lastSyncedAt: number | null;
+    /** Last sync error message */
+    syncError: string | null;
+}