@d34dman/flowdrop 0.0.19 → 0.0.21

package/README.md

@@ -1,429 +1,253 @@
-# FlowDrop
+<p align="center">
+  <img src="static/logo.svg" alt="FlowDrop" width="120" />
+</p>
 
-A visual workflow editor component library built with Svelte 5 and @xyflow/svelte. Create complex workflows with drag-and-drop functionality, node-based editing, and configurable API integration.
+<h1 align="center">FlowDrop</h1>
 
-## 🚀 Features
+<p align="center">
+  <img src="https://img.shields.io/github/actions/workflow/status/d34dman/flowdrop/docker-publish.yml?style=flat-square&label=Build" alt="GitHub pages build status" />
+  <a href="https://www.npmjs.com/package/@d34dman/flowdrop"><img src="https://img.shields.io/npm/v/@d34dman/flowdrop?style=flat-square" alt="npm" /></a>
+  <img src="https://img.shields.io/npm/unpacked-size/%40d34dman%2Fflowdrop?style=flat-square" alt="NPM Unpacked Size" />
+  <img src="https://img.shields.io/npm/types/@d34dman/flowdrop?style=flat-square" alt="npm type definitions" />
+  <a href="http://npmjs.com/package/@d34dman/flowdrop"><img src="https://img.shields.io/npm/dt/@d34dman/flowdrop.svg?maxAge=2592000&style=flat-square" alt="npm downloads" /></a>
+</p>
 
-- **Visual Workflow Editor**: Drag-and-drop interface for building node-based workflows
-- **Svelte 5 Components**: Modern, reactive components with runes
-- **Configurable API Client**: Flexible endpoint configuration for backend integration
-- **Runtime Configuration**: Build once, deploy anywhere with environment variables
-- **Node System**: Extensible node types with customizable configuration
-- **Real-time Updates**: Live workflow state management with stores
-- **Framework Agnostic**: Can be integrated into any web application
-- **TypeScript Support**: Full type definitions included
-- **Docker Ready**: Production-ready Dockerfile and Docker Compose configuration
+<p align="center">
+  <strong>Build beautiful workflow editors in minutes, not months.</strong>
+</p>
 
-### Enterprise Features (v0.0.16+)
+<p align="center">
+  An awesome workflow editor built with Svelte 5 and @xyflow/svelte.<br/>
+  You own the backend. You own the data. You own the orchestration.
+</p>
 
-- **Pluggable Authentication**: AuthProvider interface for OAuth, JWT, SSO integration
-- **Workflow Lifecycle Events**: Hooks for save, load, change, and unmount events
-- **Dirty State Tracking**: Monitor unsaved changes with reactive stores
-- **Draft Auto-Save**: Automatic localStorage drafts with configurable intervals
-- **Feature Flags**: Customize behavior for security and UX requirements
+<p align="center">
+  <a href="#quickstart">Quickstart</a> •
+  <a href="#features">Features</a> •
+  <a href="#integration">Integration</a> •
+  <a href="#documentation">Docs</a>
+</p>
 
-## 📦 Installation
+<p align="center">
+  <img src="static/FlowDrop-Screenshot.jpg" alt="FlowDrop Screenshot" width="800" />
+</p>
+<p align="center">
+  <em>Build AI-powered workflows with drag-and-drop simplicity. Connect nodes, configure inputs/outputs, and visualize your entire pipeline.</em>
+</p>
 
-```bash
-npm install @d34dman/flowdrop
-```
+## Why FlowDrop?
 
-## 📁 Project Structure
+Most workflow tools are SaaS platforms that lock you in. Your data lives on their servers. Your execution logic runs in their cloud. You pay per workflow, per user, per run.
 
-```
-@d34dman/flowdrop/
-├── dist/                        # Built library files
-│   ├── components/              # Svelte components
-│   ├── types/                   # TypeScript definitions
-│   ├── services/                # API and state management
-│   ├── utils/                   # Utility functions
-│   └── styles/                  # CSS styles
-├── src/                         # Source code
-│   └── lib/                     # Library source
-│       ├── components/          # Svelte components
-│       ├── services/            # Services and APIs
-│       ├── stores/              # State management
-│       └── types/               # Type definitions
-└── api/                         # API documentation
-```
+**FlowDrop is different.**
 
-## 🎯 Usage
+FlowDrop is a pure visual editor. You implement the backend. You control the orchestration. Your workflows run on your infrastructure, with your security policies, at your scale.
 
-### Basic Import
+No vendor lock-in. No data leaving your walls. No surprise bills.
 
-```javascript
-import { WorkflowEditor } from '@d34dman/flowdrop';
-import '@d34dman/flowdrop/styles/base.css';
+```bash
+npm install @d34dman/flowdrop
 ```
 
-### Using the WorkflowEditor Component
+You get a production-ready workflow UI. You keep full control of everything else.
+
+
+## Quickstart
 
 ```svelte
 <script lang="ts">
-	import { WorkflowEditor } from '@d34dman/flowdrop';
-	import type { NodeMetadata, Workflow } from '@d34dman/flowdrop';
-
-	let nodes: NodeMetadata[] = [
-		{
-			id: 'text_input',
-			name: 'Text Input',
-			category: 'input_output',
-			description: 'User input field',
-			inputs: [],
-			outputs: [{ id: 'value', name: 'Value', type: 'output', dataType: 'string' }]
-		}
-	];
-
-	let workflow: Workflow = {
-		id: 'workflow_1',
-		name: 'My Workflow',
-		nodes: [],
-		edges: []
-	};
+  import { WorkflowEditor } from "@d34dman/flowdrop";
+  import "@d34dman/flowdrop/styles/base.css";
 </script>
 
-<WorkflowEditor {nodes} />
+<WorkflowEditor />
 ```
 
-### Integration Methods
+**5 lines. One fully-functional workflow editor.**
 
-#### 1. As a Svelte Component (Recommended)
+
+## 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                        |
+
+
+## Node Types
+
+FlowDrop ships with 7 beautifully designed node types:
+
+| Type       | Purpose                                 |
+| ---------- | --------------------------------------- |
+| `default`  | Full-featured nodes with inputs/outputs |
+| `simple`   | Compact, space-efficient layout         |
+| `square`   | Icon-only minimal design                |
+| `tool`     | AI agent tool nodes                     |
+| `gateway`  | Conditional branching logic             |
+| `terminal` | Start/end workflow points               |
+| `note`     | Markdown documentation blocks           |
+
+<p align="center">
+  <img src="static/Node-Types.jpg" alt="FlowDrop Node Types" width="800" />
+</p>
+<p align="center">
+  <em>From simple triggers to complex branching logic, each node type is designed for specific workflow patterns.</em>
+</p>
+
+## Integration
+
+### Svelte (Native)
 
 ```svelte
 <script>
-	import { WorkflowEditor, NodeSidebar } from '@d34dman/flowdrop';
+  import { WorkflowEditor, NodeSidebar } from "@d34dman/flowdrop";
 </script>
 
-<div class="editor-container">
-	<NodeSidebar {nodes} />
-	<WorkflowEditor {nodes} />
+<div class="flex h-screen">
+  <NodeSidebar {nodes} />
+  <WorkflowEditor {nodes} />
 </div>
 ```
 
-#### 2. Using Mount Functions (Vanilla JS/Other Frameworks)
+### Vanilla JS / React / Vue / Angular
 
 ```javascript
-import { mountWorkflowEditor } from '@d34dman/flowdrop';
-
-const container = document.getElementById('workflow-container');
-const editor = mountWorkflowEditor(container, {
-	nodes: availableNodes,
-	endpointConfig: {
-		baseUrl: '/api/flowdrop',
-		endpoints: {
-			workflows: {
-				list: '/workflows',
-				get: '/workflows/{id}',
-				create: '/workflows',
-				update: '/workflows/{id}'
-			}
-		}
-	}
+import { mountFlowDropApp, createEndpointConfig } from "@d34dman/flowdrop";
+
+const app = await mountFlowDropApp(document.getElementById("editor"), {
+  workflow: myWorkflow,
+  endpointConfig: createEndpointConfig("/api/flowdrop"),
+  eventHandlers: {
+    onDirtyStateChange: (isDirty) => console.log("Unsaved changes:", isDirty),
+    onAfterSave: (workflow) => console.log("Saved!", workflow)
+  }
 });
 
-// Cleanup
-editor.destroy();
+// Full control over the editor
+app.save();
+app.getWorkflow();
+app.destroy();
 ```
 
-#### 3. Enterprise Integration (v0.0.16+)
+### Enterprise Integration
 
 ```javascript
-import { mountFlowDropApp, createEndpointConfig, CallbackAuthProvider } from '@d34dman/flowdrop';
+import { mountFlowDropApp, CallbackAuthProvider } from "@d34dman/flowdrop";
 
 const app = await mountFlowDropApp(container, {
-	workflow: myWorkflow,
-	endpointConfig: createEndpointConfig('/api/flowdrop'),
-
-	// Dynamic authentication with token refresh
-	authProvider: new CallbackAuthProvider({
-		getToken: () => authService.getAccessToken(),
-		onUnauthorized: () => authService.refreshToken()
-	}),
-
-	// Workflow lifecycle hooks
-	eventHandlers: {
-		onDirtyStateChange: (isDirty) => updateSaveButton(isDirty),
-		onAfterSave: (workflow) => showSuccess('Saved!'),
-		onBeforeUnmount: (workflow, isDirty) => {
-			if (isDirty) saveDraft(workflow);
-		}
-	},
-
-	// Feature configuration
-	features: {
-		autoSaveDraft: true,
-		autoSaveDraftInterval: 30000,
-		showToasts: true
-	}
+  // Dynamic token refresh
+  authProvider: new CallbackAuthProvider({
+    getToken: () => authService.getAccessToken(),
+    onUnauthorized: () => authService.refreshToken()
+  }),
+
+  // Lifecycle hooks
+  eventHandlers: {
+    onBeforeUnmount: (workflow, isDirty) => {
+      if (isDirty) saveDraft(workflow);
+    }
+  },
+
+  // Auto-save, toasts, and more
+  features: {
+    autoSaveDraft: true,
+    autoSaveDraftInterval: 30000
+  }
 });
-
-// Access instance methods
-if (app.isDirty()) {
-	await app.save();
-}
-
-// Get current workflow data
-const workflow = app.getWorkflow();
-
-// Cleanup
-app.destroy();
-```
-
-#### 3. Integration with Backend Frameworks
-
-##### Drupal Example
-
-```javascript
-Drupal.behaviors.flowdropEditor = {
-	attach: function (context, settings) {
-		const container = context.querySelector('.flowdrop-container');
-		if (container && window.FlowDrop) {
-			window.FlowDrop.mountWorkflowEditor(container, {
-				endpointConfig: settings.flowdrop.endpointConfig,
-				nodes: settings.flowdrop.nodes
-			});
-		}
-	}
-};
 ```
 
-## 📚 Core Components
-
-### WorkflowEditor
-
-Main editor component for creating and editing workflows.
-
-**Props:**
-
-- `nodes`: Array of available node types
-- `endpointConfig`: API endpoint configuration
-- `height`: Editor height (default: "100vh")
-- `width`: Editor width (default: "100%")
-- `lockWorkflow`: Disable editing
-- `readOnly`: Read-only mode
-
-### NodeSidebar
-
-Sidebar displaying available node types.
-
-**Props:**
-
-- `nodes`: Array of node types to display
-
-### ConfigSidebar
-
-Configuration panel for selected nodes.
 
-**Props:**
+## API Configuration
 
-- `isOpen`: Sidebar visibility
-- `configSchema`: JSON schema for configuration
-- `configValues`: Current configuration values
-- `onSave`: Save handler
-- `onClose`: Close handler
-
-## 🔧 API Configuration
-
-Configure the API client to connect to your backend:
+Connect to any backend in seconds:
 
 ```typescript
-import { createEndpointConfig } from '@d34dman/flowdrop';
+import { createEndpointConfig } from "@d34dman/flowdrop";
 
 const config = createEndpointConfig({
-	baseUrl: 'https://api.example.com',
-	endpoints: {
-		nodes: {
-			list: '/nodes',
-			get: '/nodes/{id}'
-		},
-		workflows: {
-			list: '/workflows',
-			get: '/workflows/{id}',
-			create: '/workflows',
-			update: '/workflows/{id}',
-			delete: '/workflows/{id}',
-			execute: '/workflows/{id}/execute'
-		}
-	},
-	timeout: 30000,
-	auth: {
-		type: 'bearer',
-		token: 'your-token'
-	}
+  baseUrl: "https://api.example.com",
+  endpoints: {
+    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" }
 });
 ```
 
-## 🎨 Customization
 
-### Styling
+## Customization
 
-Override CSS custom properties:
+Make it yours with CSS custom properties:
 
 ```css
 :root {
-	--flowdrop-background-color: #f9fafb;
-	--flowdrop-primary-color: #3b82f6;
-	--flowdrop-border-color: #e5e7eb;
-	--flowdrop-text-color: #1f2937;
+  --flowdrop-background-color: #0a0a0a;
+  --flowdrop-primary-color: #6366f1;
+  --flowdrop-border-color: #27272a;
+  --flowdrop-text-color: #fafafa;
 }
 ```
 
-### Node Types
-
-FlowDrop includes 7 built-in visual node types that control how nodes are rendered:
-
-| Type       | Description                                             | Use Case                 |
-| ---------- | ------------------------------------------------------- | ------------------------ |
-| `default`  | Full-featured workflow node with inputs/outputs display | Standard nodes           |
-| `simple`   | Compact layout with header, icon, and description       | Space-efficient nodes    |
-| `square`   | Minimal square node showing only an icon                | Icon-only representation |
-| `tool`     | Specialized node for agent tools with tool metadata     | AI agent tools           |
-| `gateway`  | Branching control flow with multiple output branches    | Conditional logic        |
-| `terminal` | Circular node for workflow start/end/exit points        | Workflow boundaries      |
-| `note`     | Documentation note with markdown support                | Comments/documentation   |
-
-#### Terminal Nodes
-
-Terminal nodes are special circular nodes for workflow boundaries:
-
-```typescript
-// Start node - output only
-const startNode: NodeMetadata = {
-	id: 'workflow-start',
-	name: 'Start',
-	type: 'terminal',
-	tags: ['start'],
-	inputs: [],
-	outputs: [{ id: 'trigger', name: 'Go', type: 'output', dataType: 'trigger' }]
-};
-
-// End node - input only
-const endNode: NodeMetadata = {
-	id: 'workflow-end',
-	name: 'End',
-	type: 'terminal',
-	tags: ['end'],
-	inputs: [{ id: 'done', name: 'Done', type: 'input', dataType: 'trigger' }],
-	outputs: []
-};
-```
-
 
-## 🔌 Backend Integration
+## Deploy
 
-FlowDrop is backend-agnostic. Implement the API endpoints expected by the client:
-
-### Required Endpoints
-
-- `GET /api/nodes` - List available node types
-- `GET /api/workflows` - List workflows
-- `GET /api/workflows/{id}` - Get workflow
-- `POST /api/workflows` - Create workflow
-- `PUT /api/workflows/{id}` - Update workflow
-- `DELETE /api/workflows/{id}` - Delete workflow
-- `POST /api/workflows/{id}/execute` - Execute workflow
-
-See `API.md` for detailed endpoint specifications.
-
-## 🧪 Testing
+### Docker (Recommended)
 
 ```bash
-# Unit tests
-npm run test:unit
-
-# E2E tests
-npm run test:e2e
-
-# All tests
-npm test
+cp env.example .env
+docker-compose up -d
 ```
 
-## 🛠️ Development
+### Node.js
 
 ```bash
-# Install dependencies
-npm install
-
-# Development server
-npm run dev
-
-# Build library
 npm run build
-
-# Build for production
-npm run build:production
-
-# Linting
-npm run lint
-
-# Format code
-npm run format
+FLOWDROP_API_BASE_URL=http://your-backend/api node build
 ```
 
-## 📖 Documentation
-
-- **API.md** - REST API specification
-- **CHANGELOG.md** - Version history
-
-## 🤝 Contributing
+Runtime configuration means you build once and deploy to staging, production, or anywhere else with just environment variables.
 
-Not accepting contributions until the library stabilizes. Stay tuned.
 
-## 📄 License
 
-MIT
+## Documentation
 
-## 🆘 Support
+| Resource                           | Description              |
+| ---------------------------------- | ------------------------ |
+| [API.md](./API.md)                 | REST API specification   |
+| [DOCKER.md](./DOCKER.md)           | Docker deployment guide  |
+| [QUICK_START.md](./QUICK_START.md) | Get running in 5 minutes |
+| [CHANGELOG.md](./CHANGELOG.md)     | Version history          |
 
-- Check the API documentation in `API.md`
-- Create an issue in the project repository
-- Review the examples in `src/lib/examples/`
-
-## 🚢 Deployment
-
-FlowDrop uses **runtime configuration** instead of build-time environment variables, allowing you to build once and deploy to multiple environments.
-
-### Quick Start with Docker
+## Development
 
 ```bash
-# Copy environment file
-cp env.example .env
-
-# Edit .env with your configuration
-# Set FLOWDROP_API_BASE_URL to your backend API URL
-
-# Start with Docker Compose
-docker-compose up -d
+npm install          # Install dependencies
+npm run dev          # Start dev server
+npm run build        # Build library
+npm test             # Run all tests
 ```
 
-### Environment Variables
-
-**Production (Runtime):**
-
-- `FLOWDROP_API_BASE_URL` - Backend API URL
-- `FLOWDROP_THEME` - UI theme (light/dark/auto)
-- `FLOWDROP_TIMEOUT` - Request timeout in milliseconds
-- `FLOWDROP_AUTH_TYPE` - Authentication type (none/bearer/api_key/custom)
-- `FLOWDROP_AUTH_TOKEN` - Authentication token
-
-### Build for Production
 
-```bash
-# Install dependencies
-npm ci
-
-# Build the application
-npm run build
-
-# Set environment variables and start
-export FLOWDROP_API_BASE_URL=http://your-backend:8080/api/flowdrop
-node build
-```
+## Contributing
 
-For detailed deployment instructions, see:
+FlowDrop is stabilizing. Contributions will open soon. Star the repo to stay updated.
 
-- [DOCKER.md](./DOCKER.md) - Docker quick start
 
----
+<p align="center">
+  <strong>FlowDrop</strong> - The visual workflow editor you own completely
+</p>
 
-**FlowDrop** - Visual workflow editing for modern web applications
+<p align="center">
+  Built with ❤️ Svelte 5 and @xyflow/svelte
+</p>