@flowdrop/flowdrop 1.4.0 → 1.6.0

package/README.md

@@ -2,14 +2,15 @@
   <img src="https://raw.githubusercontent.com/flowdrop-io/flowdrop/main/libs/flowdrop/static/logo.svg" alt="FlowDrop" width="120" />
 </p>
 
-<h1 align="center">FlowDrop</h1>
+<h1 align="center">FlowDrop™</h1>
 
 <p align="center">
-  <img src="https://img.shields.io/github/actions/workflow/status/flowdrop-io/flowdrop/docker-publish.yml?style=flat-square&label=Build" alt="GitHub pages build status" />
+  <img src="https://img.shields.io/github/actions/workflow/status/flowdrop-io/flowdrop/docker-publish.yml?style=flat-square&label=Build" alt="GitHub build status" />
   <a href="https://www.npmjs.com/package/@flowdrop/flowdrop"><img src="https://img.shields.io/npm/v/@flowdrop/flowdrop?style=flat-square" alt="npm" /></a>
   <img src="https://img.shields.io/npm/unpacked-size/%40flowdrop%2Fflowdrop?style=flat-square" alt="NPM Unpacked Size" />
   <img src="https://img.shields.io/npm/types/@flowdrop/flowdrop?style=flat-square" alt="npm type definitions" />
-  <a href="http://npmjs.com/package/@flowdrop/flowdrop"><img src="https://img.shields.io/npm/dt/@flowdrop/flowdrop.svg?maxAge=2592000&style=flat-square" alt="npm downloads" /></a>
+  <a href="http://npmjs.com/package/@flowdrop/flowdrop"><img alt="NPM Downloads" src="https://img.shields.io/npm/d18m/%40flowdrop%2Fflowdrop"></a>
+
 </p>
 
 <p align="center">
@@ -22,10 +23,10 @@
 </p>
 
 <p align="center">
-  <a href="#quickstart">Quickstart</a> •
+  <a href="https://docs.flowdrop.io/getting-started/installation">Quickstart</a> •
   <a href="#features">Features</a> •
   <a href="#integration">Integration</a> •
-  <a href="#documentation">Docs</a>
+  <a href="https://docs.flowdrop.io">Docs</a>
 </p>
 
 <p align="center">
@@ -57,8 +58,8 @@ You get a production-ready workflow UI. You keep full control of everything else
 
 ```svelte
 <script lang="ts">
-  import { WorkflowEditor } from "@flowdrop/flowdrop";
-  import "@flowdrop/flowdrop/styles/base.css";
+  import { WorkflowEditor } from '@flowdrop/flowdrop';
+  import '@flowdrop/flowdrop/styles/base.css';
 </script>
 
 <WorkflowEditor />
@@ -68,14 +69,14 @@ You get a production-ready workflow UI. You keep full control of everything else
 
 ## Features
 
-|                              |                                                                           |
-| ---------------------------- | ------------------------------------------------------------------------- |
-| 🎨 **Visual Editor Only**    | Pure UI component. No hidden backend, no external dependencies            |
-| 🔐 **You Own Everything**    | Your data, your servers, your orchestration logic, your security policies |
-| 🔌 **Backend Agnostic**      | Connect to any API: Drupal, Laravel, Express, FastAPI, or your own        |
-| 🧩 **7 Built-in Node Types** | From simple icons to complex gateway logic                                |
-| 🎭 **Framework Flexible**    | Use as Svelte component or mount into React, Vue, Angular, or vanilla JS  |
-| 🐳 **Deploy Anywhere**       | Runtime config means build once, deploy everywhere                        |
+|                           |                                                                           |
+| ------------------------- | ------------------------------------------------------------------------- |
+| **Visual Editor Only**    | Pure UI component. No hidden backend, no external dependencies            |
+| **You Own Everything**    | Your data, your servers, your orchestration logic, your security policies |
+| **Backend Agnostic**      | Connect to any API: Drupal, Laravel, Express, FastAPI, or your own        |
+| **8 Built-in Node Types** | From simple icons to complex gateway logic                                |
+| **Framework Flexible**    | Use as Svelte component or mount into React, Vue, Angular, or vanilla JS  |
+| **Deploy Anywhere**       | Runtime config means build once, deploy everywhere                        |
 
 ## Architecture Notes
 
@@ -85,7 +86,7 @@ You get a production-ready workflow UI. You keep full control of everything else
 
 ## Node Types
 
-FlowDrop ships with 7 beautifully designed node types:
+FlowDrop ships with 8 beautifully designed node types:
 
 | Type       | Purpose                                 |
 | ---------- | --------------------------------------- |
@@ -96,6 +97,7 @@ FlowDrop ships with 7 beautifully designed node types:
 | `gateway`  | Conditional branching logic             |
 | `terminal` | Start/end workflow points               |
 | `note`     | Markdown documentation blocks           |
+| `idea`     | Conceptual BPMN-like flow nodes         |
 
 <p align="center">
   <img src="https://raw.githubusercontent.com/flowdrop-io/flowdrop/main/libs/flowdrop/static/Node-Types.jpg" alt="FlowDrop Node Types" width="800" />
@@ -104,13 +106,56 @@ FlowDrop ships with 7 beautifully designed node types:
   <em>From simple triggers to complex branching logic, each node type is designed for specific workflow patterns.</em>
 </p>
 
+## Themes
+
+FlowDrop includes a theme system with built-in light/dark support:
+
+```svelte
+<script lang="ts">
+  import { WorkflowEditor } from '@flowdrop/flowdrop';
+  import '@flowdrop/flowdrop/styles';
+</script>
+
+<!-- Built-in themes: 'default' or 'minimal' -->
+<WorkflowEditor theme="minimal" />
+```
+
+Themes bundle a visual skin (CSS token palette) with behavioral UI defaults. You can also pass a custom theme object with your own skin tokens for full control over the light and dark palettes.
+
+```javascript
+// Via the mount API
+const app = await mountFlowDropApp(container, {
+  theme: 'minimal'
+  // or a custom theme object:
+  // theme: { name: 'minimal', skin: { tokens: { primary: '#e11d48' } } }
+});
+```
+
+## Sub-Module Exports
+
+FlowDrop provides tree-shakeable sub-module exports so you can import only what you need:
+
+| Export Path                        | Contents                                           |
+| ---------------------------------- | -------------------------------------------------- |
+| `@flowdrop/flowdrop`               | Full library (components, stores, services, types) |
+| `@flowdrop/flowdrop/core`          | Types and utilities only (no heavy dependencies)   |
+| `@flowdrop/flowdrop/editor`        | WorkflowEditor, stores, services                   |
+| `@flowdrop/flowdrop/form`          | SchemaForm, form fields, registry                  |
+| `@flowdrop/flowdrop/form/code`     | Code editor field (CodeMirror)                     |
+| `@flowdrop/flowdrop/form/markdown` | Markdown editor field                              |
+| `@flowdrop/flowdrop/display`       | MarkdownDisplay component                          |
+| `@flowdrop/flowdrop/playground`    | Playground components and services                 |
+| `@flowdrop/flowdrop/settings`      | SettingsPanel, stores, services                    |
+| `@flowdrop/flowdrop/styles`        | Base CSS stylesheet                                |
+| `@flowdrop/flowdrop/schema`        | Workflow JSON schema                               |
+
 ## Integration
 
 ### Svelte (Native)
 
 ```svelte
 <script>
-  import { WorkflowEditor, NodeSidebar } from "@flowdrop/flowdrop";
+  import { WorkflowEditor, NodeSidebar } from '@flowdrop/flowdrop';
 </script>
 
 <div class="flex h-screen">
@@ -122,15 +167,15 @@ FlowDrop ships with 7 beautifully designed node types:
 ### Vanilla JS / React / Vue / Angular
 
 ```javascript
-import { mountFlowDropApp, createEndpointConfig } from "@flowdrop/flowdrop";
+import { mountFlowDropApp, createEndpointConfig } from '@flowdrop/flowdrop';
 
-const app = await mountFlowDropApp(document.getElementById("editor"), {
+const app = await mountFlowDropApp(document.getElementById('editor'), {
   workflow: myWorkflow,
-  endpointConfig: createEndpointConfig("/api/flowdrop"),
+  endpointConfig: createEndpointConfig('/api/flowdrop'),
   eventHandlers: {
-    onDirtyStateChange: (isDirty) => console.log("Unsaved changes:", isDirty),
-    onAfterSave: (workflow) => console.log("Saved!", workflow),
-  },
+    onDirtyStateChange: (isDirty) => console.log('Unsaved changes:', isDirty),
+    onAfterSave: (workflow) => console.log('Saved!', workflow)
+  }
 });
 
 // Full control over the editor
@@ -142,27 +187,27 @@ app.destroy();
 ### Enterprise Integration
 
 ```javascript
-import { mountFlowDropApp, CallbackAuthProvider } from "@flowdrop/flowdrop";
+import { mountFlowDropApp, CallbackAuthProvider } from '@flowdrop/flowdrop';
 
 const app = await mountFlowDropApp(container, {
   // Dynamic token refresh
   authProvider: new CallbackAuthProvider({
     getToken: () => authService.getAccessToken(),
-    onUnauthorized: () => authService.refreshToken(),
+    onUnauthorized: () => authService.refreshToken()
   }),
 
   // Lifecycle hooks
   eventHandlers: {
     onBeforeUnmount: (workflow, isDirty) => {
       if (isDirty) saveDraft(workflow);
-    },
+    }
   },
 
   // Auto-save, toasts, and more
   features: {
     autoSaveDraft: true,
-    autoSaveDraftInterval: 30000,
-  },
+    autoSaveDraftInterval: 30000
+  }
 });
 ```
 
@@ -171,34 +216,32 @@ const app = await mountFlowDropApp(container, {
 Connect to any backend in seconds:
 
 ```typescript
-import { createEndpointConfig } from "@flowdrop/flowdrop";
+import { createEndpointConfig } from '@flowdrop/flowdrop';
 
-const config = createEndpointConfig({
-  baseUrl: "https://api.example.com",
+const config = createEndpointConfig('https://api.example.com', {
   endpoints: {
-    nodes: { list: "/nodes", get: "/nodes/{id}" },
+    nodes: { list: '/nodes', get: '/nodes/{id}' },
     workflows: {
-      list: "/workflows",
-      get: "/workflows/{id}",
-      create: "/workflows",
-      update: "/workflows/{id}",
-      execute: "/workflows/{id}/execute",
-    },
-  },
-  auth: { type: "bearer", token: "your-token" },
+      list: '/workflows',
+      get: '/workflows/{id}',
+      create: '/workflows',
+      update: '/workflows/{id}',
+      execute: '/workflows/{id}/execute'
+    }
+  }
 });
 ```
 
 ## Customization
 
-Make it yours with CSS custom properties:
+The recommended way to customize FlowDrop's appearance is through the [theme system](#themes). For fine-grained control, you can also override individual CSS custom properties:
 
 ```css
 :root {
-  --flowdrop-background-color: #0a0a0a;
-  --flowdrop-primary-color: #6366f1;
-  --flowdrop-border-color: #27272a;
-  --flowdrop-text-color: #fafafa;
+  --fd-background: #0a0a0a;
+  --fd-primary: #6366f1;
+  --fd-border: #27272a;
+  --fd-foreground: #fafafa;
 }
 ```
 
@@ -223,12 +266,11 @@ Runtime configuration means you build once and deploy to staging, production, or
 
 ## Documentation
 
-| Resource                                                     | Description              |
-| ------------------------------------------------------------ | ------------------------ |
-| [API Documentation](https://flowdrop-io.github.io/flowdrop/) | REST API specification   |
-| [Docker Guide](../../apps/example-client-docker/README.md)   | Docker deployment guide  |
-| [QUICK_START.md](./QUICK_START.md)                           | Get running in 5 minutes |
-| [CHANGELOG.md](./CHANGELOG.md)                               | Version history          |
+| Resource                                                                                     | Description              |
+| -------------------------------------------------------------------------------------------- | ------------------------ |
+| [QUICK_START.md](https://docs.flowdrop.io/getting-started/installation/)                     | Get running in 5 minutes |
+| [API Documentation](https://api.flowdrop.io/v1/)                                             | REST API specification   |
+| [CHANGELOG.md](https://github.com/flowdrop-io/flowdrop/blob/main/libs/flowdrop/CHANGELOG.md) | Version history          |
 
 ## Development
 
@@ -237,6 +279,7 @@ pnpm install         # Install dependencies
 pnpm dev             # Start dev server
 pnpm build           # Build library
 pnpm test            # Run all tests
+pnpm storybook       # Launch Storybook
 ```
 
 ## Contributing

package/dist/adapters/WorkflowAdapter.d.ts

@@ -13,7 +13,7 @@
  * - External applications that want to integrate with FlowDrop
  * - Systems that need to generate or modify workflows programmatically
  */
-import type { Workflow, NodeMetadata, WorkflowFormat } from "../types/index.js";
+import type { Workflow, NodeMetadata, WorkflowFormat } from '../types/index.js';
 /**
  * Standard workflow node interface (SvelteFlow-agnostic)
  */

package/dist/adapters/WorkflowAdapter.js

@@ -13,28 +13,8 @@
  * - External applications that want to integrate with FlowDrop
  * - Systems that need to generate or modify workflows programmatically
  */
-import { v4 as uuidv4 } from "uuid";
-/**
- * Generate a unique node ID based on node type and existing nodes
- * Format: <node_type>.<number>
- * Example: boolean_gateway.1, calculator.2
- */
-function generateStandardNodeId(nodeTypeId, existingNodes) {
-    // Count how many nodes of this type already exist
-    const existingNodeIds = existingNodes
-        .filter((node) => node.data?.metadata?.id === nodeTypeId)
-        .map((node) => node.id);
-    // Extract the numbers from existing IDs with the same prefix
-    const existingNumbers = existingNodeIds
-        .map((id) => {
-        const match = id.match(new RegExp(`^${nodeTypeId}\\.(\\d+)$`));
-        return match ? parseInt(match[1], 10) : 0;
-    })
-        .filter((num) => num > 0);
-    // Find the next available number (highest + 1)
-    const nextNumber = existingNumbers.length > 0 ? Math.max(...existingNumbers) + 1 : 1;
-    return `${nodeTypeId}.${nextNumber}`;
-}
+import { v4 as uuidv4 } from 'uuid';
+import { generateNodeId } from '../utils/nodeIds.js';
 /**
  * Workflow Adapter Class
  * Provides a clean API for workflow operations without exposing SvelteFlow internals
@@ -55,10 +35,10 @@ export class WorkflowAdapter {
             nodes: [],
             edges: [],
             metadata: {
-                version: "1.0.0",
+                version: '1.0.0',
                 createdAt: new Date().toISOString(),
-                updatedAt: new Date().toISOString(),
-            },
+                updatedAt: new Date().toISOString()
+            }
         };
     }
     /**
@@ -70,7 +50,7 @@ export class WorkflowAdapter {
             throw new Error(`Node type '${nodeType}' not found`);
         }
         // Generate node ID based on node type and existing nodes
-        const nodeId = generateStandardNodeId(nodeType, workflow.nodes);
+        const nodeId = generateNodeId(nodeType, workflow.nodes);
         const node = {
             id: nodeId,
             type: nodeType,
@@ -78,8 +58,8 @@ export class WorkflowAdapter {
             data: {
                 label: metadata.name,
                 config: config || {},
-                metadata,
-            },
+                metadata
+            }
         };
         workflow.nodes.push(node);
         workflow.metadata.updatedAt = new Date().toISOString();
@@ -129,7 +109,7 @@ export class WorkflowAdapter {
             source: sourceNodeId,
             target: targetNodeId,
             sourceHandle,
-            targetHandle,
+            targetHandle
         };
         workflow.edges.push(edge);
         workflow.metadata.updatedAt = new Date().toISOString();
@@ -181,7 +161,7 @@ export class WorkflowAdapter {
         const warnings = [];
         // Check for empty workflow
         if (workflow.nodes.length === 0) {
-            warnings.push("Workflow has no nodes");
+            warnings.push('Workflow has no nodes');
         }
         // Check for orphaned edges
         const nodeIds = new Set(workflow.nodes.map((n) => n.id));
@@ -222,7 +202,7 @@ export class WorkflowAdapter {
         return {
             valid: errors.length === 0,
             errors,
-            warnings,
+            warnings
         };
     }
     /**
@@ -240,20 +220,20 @@ export class WorkflowAdapter {
             // Validate the imported workflow
             const validation = this.validateWorkflow(workflow);
             if (!validation.valid) {
-                throw new Error(`Invalid workflow: ${validation.errors.join(", ")}`);
+                throw new Error(`Invalid workflow: ${validation.errors.join(', ')}`);
             }
             // Update metadata
             workflow.metadata = {
-                version: workflow.metadata?.version || "1.0.0",
+                version: workflow.metadata?.version || '1.0.0',
                 createdAt: workflow.metadata?.createdAt || new Date().toISOString(),
                 updatedAt: new Date().toISOString(),
                 author: workflow.metadata?.author,
-                tags: workflow.metadata?.tags,
+                tags: workflow.metadata?.tags
             };
             return workflow;
         }
         catch (error) {
-            throw new Error(`Failed to import workflow: ${error instanceof Error ? error.message : "Unknown error"}`);
+            throw new Error(`Failed to import workflow: ${error instanceof Error ? error.message : 'Unknown error'}`);
         }
     }
     /**
@@ -271,17 +251,17 @@ export class WorkflowAdapter {
                 data: {
                     label: node.data.label,
                     config: node.data.config,
-                    metadata: node.data.metadata,
-                },
+                    metadata: node.data.metadata
+                }
             })),
             edges: svelteFlowWorkflow.edges.map((edge) => ({
                 id: edge.id,
                 source: edge.source,
                 target: edge.target,
                 sourceHandle: edge.sourceHandle,
-                targetHandle: edge.targetHandle,
+                targetHandle: edge.targetHandle
             })),
-            metadata: svelteFlowWorkflow.metadata,
+            metadata: svelteFlowWorkflow.metadata
         };
     }
     /**
@@ -294,24 +274,24 @@ export class WorkflowAdapter {
             description: workflow.description,
             nodes: workflow.nodes.map((node) => ({
                 id: node.id,
-                type: "workflowNode",
+                type: 'workflowNode',
                 position: node.position,
                 deletable: true,
                 data: {
                     label: node.data.label,
                     config: node.data.config,
                     metadata: node.data.metadata,
-                    nodeId: node.id,
-                },
+                    nodeId: node.id
+                }
             })),
             edges: workflow.edges.map((edge) => ({
                 id: edge.id,
                 source: edge.source,
                 target: edge.target,
                 sourceHandle: edge.sourceHandle,
-                targetHandle: edge.targetHandle,
+                targetHandle: edge.targetHandle
             })),
-            metadata: workflow.metadata,
+            metadata: workflow.metadata
         };
     }
     /**
@@ -326,7 +306,7 @@ export class WorkflowAdapter {
             totalNodes: workflow.nodes.length,
             totalEdges: workflow.edges.length,
             nodeTypeCounts: Object.fromEntries(nodeTypeCounts),
-            lastModified: workflow.metadata?.updatedAt,
+            lastModified: workflow.metadata?.updatedAt
         };
     }
     /**
@@ -357,11 +337,11 @@ export class WorkflowAdapter {
         cloned.id = uuidv4();
         cloned.name = newName || `${workflow.name} (Copy)`;
         cloned.metadata = {
-            version: cloned.metadata?.version || "1.0.0",
+            version: cloned.metadata?.version || '1.0.0',
             createdAt: new Date().toISOString(),
             updatedAt: new Date().toISOString(),
             author: cloned.metadata?.author,
-            tags: cloned.metadata?.tags,
+            tags: cloned.metadata?.tags
         };
         return cloned;
     }

package/dist/adapters/agentspec/AgentSpecAdapter.d.ts

@@ -9,8 +9,8 @@
  *
  * @see https://github.com/oracle/agent-spec
  */
-import type { AgentSpecFlow } from "../../types/agentspec.js";
-import type { StandardWorkflow } from "../WorkflowAdapter.js";
+import type { AgentSpecFlow } from '../../types/agentspec.js';
+import type { StandardWorkflow } from '../WorkflowAdapter.js';
 export declare class AgentSpecAdapter {
     /**
      * Convert a FlowDrop StandardWorkflow to an Agent Spec Flow.