@d34dman/flowdrop 0.0.46 → 0.0.48

package/dist/types/index.d.ts

@@ -69,6 +69,11 @@ export interface NodePort {
     required?: boolean;
     description?: string;
     defaultValue?: unknown;
+    /**
+     * Optional JSON Schema describing the structure of data on this port.
+     * Used for template variable autocomplete to drill into nested properties.
+     */
+    schema?: OutputSchema | InputSchema;
 }
 /**
  * Dynamic port configuration for user-defined inputs/outputs
@@ -612,6 +617,258 @@ export interface OutputProperty extends BaseProperty {
 export interface OutputSchema extends BaseSchema {
     properties: Record<string, OutputProperty>;
 }
+/**
+ * Primitive types for template variables
+ */
+export type TemplateVariableType = 'string' | 'number' | 'boolean' | 'array' | 'object' | 'integer' | 'mixed' | 'float';
+/**
+ * Represents a variable available for template interpolation.
+ * Used by the template editor for autocomplete suggestions.
+ *
+ * Supports hierarchical drilling:
+ * - Objects have `properties` for dot notation (e.g., `user.name`)
+ * - Arrays have `items` for index access (e.g., `items[0].name`)
+ *
+ * @example
+ * ```typescript
+ * const userVariable: TemplateVariable = {
+ *   name: "user",
+ *   label: "User Data",
+ *   type: "object",
+ *   properties: {
+ *     name: { name: "name", type: "string", label: "User Name" },
+ *     email: { name: "email", type: "string", label: "Email Address" },
+ *     address: {
+ *       name: "address",
+ *       type: "object",
+ *       label: "Address",
+ *       properties: {
+ *         city: { name: "city", type: "string", label: "City" },
+ *         country: { name: "country", type: "string", label: "Country" }
+ *       }
+ *     }
+ *   }
+ * };
+ * ```
+ */
+export interface TemplateVariable {
+    /** Variable name (used in template as {{ name }}) */
+    name: string;
+    /** Display label for the variable in autocomplete dropdown */
+    label?: string;
+    /** Description shown in autocomplete tooltip */
+    description?: string;
+    /** Data type of the variable */
+    type: TemplateVariableType;
+    /** For objects: child properties accessible via dot notation */
+    properties?: Record<string, TemplateVariable>;
+    /** For arrays: schema of array items accessible via index notation */
+    items?: TemplateVariable;
+    /** Source port ID this variable comes from */
+    sourcePort?: string;
+    /** Source node ID */
+    sourceNode?: string;
+}
+/**
+ * Schema passed to template editor for autocomplete functionality.
+ * Contains all available variables derived from connected upstream nodes.
+ *
+ * @example
+ * ```typescript
+ * const variableSchema: VariableSchema = {
+ *   variables: {
+ *     user: { name: "user", type: "object", properties: { ... } },
+ *     items: { name: "items", type: "array", items: { ... } },
+ *     config: { name: "config", type: "object", properties: { ... } }
+ *   }
+ * };
+ * ```
+ */
+export interface VariableSchema {
+    /** Map of available variables keyed by variable name */
+    variables: Record<string, TemplateVariable>;
+}
+/**
+ * Configuration for template variable autocomplete.
+ * Used in template fields to control which variables are available
+ * and how they are derived.
+ *
+ * Supports three modes:
+ * 1. **Schema-only** (existing): Variables from static schema and/or upstream ports
+ * 2. **API-only** (new): Variables fetched from backend endpoint
+ * 3. **Hybrid** (new): Merge API variables with static schema/ports
+ *
+ * @example
+ * ```json
+ * {
+ *   "type": "string",
+ *   "format": "template",
+ *   "variables": {
+ *     "ports": ["data", "context"],
+ *     "includePortName": true
+ *   }
+ * }
+ * ```
+ *
+ * @example API Mode
+ * ```json
+ * {
+ *   "type": "string",
+ *   "format": "template",
+ *   "variables": {
+ *     "api": {
+ *       "endpoint": {
+ *         "url": "/api/variables/{workflowId}/{nodeId}"
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+export interface TemplateVariablesConfig {
+    /**
+     * Specifies which input port IDs should provide variables for autocomplete.
+     * Only connections to these ports will provide variables.
+     *
+     * - If not specified, all input ports with connections are used.
+     * - If specified as an empty array, no variables will be derived from ports.
+     */
+    ports?: string[];
+    /**
+     * Pre-defined variable schema to use instead of (or in addition to) deriving from ports.
+     * Useful for providing static variables or overriding derived ones.
+     */
+    schema?: VariableSchema;
+    /**
+     * Whether to include the port name as a prefix for variables.
+     * When true, variables are named like `data.user` instead of just `user`.
+     * Useful when multiple ports might have overlapping variable names.
+     * @default false
+     */
+    includePortName?: boolean;
+    /**
+     * Whether to show available variables as clickable hints below the editor.
+     * @default true
+     */
+    showHints?: boolean;
+    /**
+     * API mode configuration for fetching variables from backend endpoint.
+     * When configured, variables will be fetched from the specified endpoint
+     * and can be merged with static schema and/or port-derived variables.
+     */
+    api?: ApiVariablesConfig;
+}
+/**
+ * Configuration for API-based variable fetching.
+ * Enables dynamic variable suggestions from backend endpoints.
+ *
+ * @example
+ * ```typescript
+ * const apiConfig: ApiVariablesConfig = {
+ *   endpoint: {
+ *     url: "/api/variables/{workflowId}/{nodeId}",
+ *     method: "GET"
+ *   },
+ *   cacheTtl: 300000,
+ *   mergeWithSchema: true,
+ *   fallbackOnError: true
+ * };
+ * ```
+ */
+export interface ApiVariablesConfig {
+    /**
+     * Endpoint configuration for fetching variable schema
+     */
+    endpoint: ApiVariablesEndpoint;
+    /**
+     * Cache TTL in milliseconds.
+     * Variables are cached to prevent excessive API calls during editing.
+     * @default 300000 (5 minutes)
+     */
+    cacheTtl?: number;
+    /**
+     * Whether to merge API variables with static schema.
+     * When true, variables from both API and schema are combined.
+     * @default true
+     */
+    mergeWithSchema?: boolean;
+    /**
+     * Whether to merge API variables with port-derived variables.
+     * When true, variables from both API and ports are combined.
+     * @default false
+     */
+    mergeWithPorts?: boolean;
+    /**
+     * Whether to fallback to schema/ports on API error.
+     * When true, gracefully degrades to static variables if API fails.
+     * When false, shows error message to user.
+     * @default true
+     */
+    fallbackOnError?: boolean;
+}
+/**
+ * Endpoint configuration for fetching variable schemas from backend API.
+ * Supports template variables in URL (e.g., {workflowId}, {nodeId})
+ * which are resolved at runtime from node context.
+ *
+ * @example GET Request
+ * ```typescript
+ * const endpoint: ApiVariablesEndpoint = {
+ *   url: "/api/variables/{workflowId}/{nodeId}",
+ *   method: "GET"
+ * };
+ * ```
+ *
+ * @example POST Request with Body
+ * ```typescript
+ * const endpoint: ApiVariablesEndpoint = {
+ *   url: "/api/variables",
+ *   method: "POST",
+ *   body: {
+ *     workflowId: "{workflowId}",
+ *     nodeId: "{nodeId}"
+ *   }
+ * };
+ * ```
+ */
+export interface ApiVariablesEndpoint {
+    /**
+     * URL to fetch variables from.
+     * Supports template placeholders:
+     * - `{workflowId}` - Resolved from workflow ID
+     * - `{nodeId}` - Resolved from node instance ID
+     *
+     * @example "/api/variables/{workflowId}/{nodeId}"
+     * @example "https://api.example.com/variables?workflow={workflowId}&node={nodeId}"
+     */
+    url: string;
+    /**
+     * HTTP method for the request.
+     * @default "GET"
+     */
+    method?: HttpMethod;
+    /**
+     * Custom headers to include in the request.
+     * Note: Authentication headers are automatically added via AuthProvider.
+     */
+    headers?: Record<string, string>;
+    /**
+     * Request body for POST/PUT/PATCH methods.
+     * Supports template variables like the URL.
+     */
+    body?: Record<string, unknown>;
+    /**
+     * Request timeout in milliseconds.
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * Whether to cache the fetched schema.
+     * When false, schema is fetched on every editor load.
+     * @default true
+     */
+    cacheEnabled?: boolean;
+}
 /**
  * Union type for all schema types
  */

package/dist/utils/handlePositioning.d.ts

@@ -0,0 +1,31 @@
+/**
+ * Utility functions for calculating handle positions on nodes
+ */
+export interface HandlePosition {
+    left: number;
+    top: number;
+}
+/**
+ * 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 declare function getCircleHandlePosition(index: number, count: number, side: 'left' | 'right', radius?: number, arcSpan?: number): HandlePosition;

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/nodeTypes.d.ts

@@ -66,8 +66,8 @@ export declare function resolveComponentName(metadata: NodeMetadata, configNodeT
  */
 export declare function isNodeTypeSupported(metadata: NodeMetadata, nodeType: NodeType | string): boolean;
 /**
- * Gets enum options for node type configuration.
- * Used in config schemas to show available options.
+ * 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
@@ -75,27 +75,32 @@ export declare function isNodeTypeSupported(metadata: NodeMetadata, nodeType: No
  *
  * @param metadata - The node metadata
  * @param includeCustomTypes - Whether to include registered custom types
- * @returns Object with enum values and display names
+ * @returns Array of oneOf items with const (type value) and title (display name)
  */
-export declare function getNodeTypeEnumOptions(metadata: NodeMetadata, includeCustomTypes?: boolean): {
-    enum: string[];
-    enumNames: string[];
-};
+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
+ * @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;
-    enum: string[];
-    enumNames: string[];
+    oneOf: {
+        const: string;
+        title: string;
+    }[];
 };
 /**
  * Check if a type string represents a valid registered or built-in type.

package/dist/utils/nodeTypes.js

@@ -136,8 +136,8 @@ export function isNodeTypeSupported(metadata, nodeType) {
     return false;
 }
 /**
- * Gets enum options for node type configuration.
- * Used in config schemas to show available options.
+ * 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
@@ -145,58 +145,60 @@ export function isNodeTypeSupported(metadata, nodeType) {
  *
  * @param metadata - The node metadata
  * @param includeCustomTypes - Whether to include registered custom types
- * @returns Object with enum values and display names
+ * @returns Array of oneOf items with const (type value) and title (display name)
  */
-export function getNodeTypeEnumOptions(metadata, includeCustomTypes = false) {
+export function getNodeTypeOneOfOptions(metadata, includeCustomTypes = false) {
     const availableTypes = getAvailableNodeTypes(metadata);
-    // Build enum values and names
-    const enumValues = [];
-    const enumNames = [];
+    const options = [];
+    const includedTypes = new Set();
     for (const type of availableTypes) {
-        enumValues.push(type);
+        includedTypes.add(type);
         // Get display name from registry or fallback to built-in names
         const registration = nodeComponentRegistry.get(type);
+        let title;
         if (registration) {
-            enumNames.push(registration.displayName);
+            title = registration.displayName;
         }
         else if (type in TYPE_DISPLAY_NAMES) {
-            enumNames.push(TYPE_DISPLAY_NAMES[type]);
+            title = TYPE_DISPLAY_NAMES[type];
         }
         else {
             // Format unknown type nicely
-            enumNames.push(formatTypeName(type));
+            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) && !enumValues.includes(reg.type)
+            predicate: (reg) => !isBuiltinType(reg.type) && !includedTypes.has(reg.type)
         });
         for (const reg of registrations) {
-            enumValues.push(reg.type);
-            enumNames.push(reg.displayName);
+            options.push({ const: reg.type, title: reg.displayName });
         }
     }
-    return { enum: enumValues, enumNames };
+    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
+ * @returns Config schema property object with oneOf for labeled options
  */
 export function createNodeTypeConfigProperty(metadata, defaultType) {
-    const { enum: enumValues, enumNames } = getNodeTypeEnumOptions(metadata);
+    const oneOf = getNodeTypeOneOfOptions(metadata);
     const primaryType = defaultType ?? getPrimaryNodeType(metadata);
     return {
-        type: 'string',
-        title: 'Node Type',
-        description: 'Choose the visual representation for this node',
+        type: "string",
+        title: "Node Type",
+        description: "Choose the visual representation for this node",
         default: primaryType,
-        enum: enumValues,
-        enumNames
+        oneOf
     };
 }
 /**

package/package.json

@@ -2,7 +2,7 @@
 	"name": "@d34dman/flowdrop",
 	"license": "MIT",
 	"private": false,
-	"version": "0.0.46",
+	"version": "0.0.48",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run prepack",
@@ -12,7 +12,7 @@
 		"watch:build:production": "npm-watch build:production",
 		"watch:build": "npm-watch build",
 		"preview": "vite preview",
-		"prepare": "svelte-kit sync || echo ''",
+		"prepare": "svelte-kit sync || echo '' && husky",
 		"prepack": "svelte-kit sync && svelte-package && publint",
 		"check": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json",
 		"check:watch": "svelte-kit sync && svelte-check --tsconfig ./tsconfig.json --watch",
@@ -30,6 +30,7 @@
 		"build-storybook": "storybook build",
 		"api:lint": "redocly lint api/openapi.yaml --config api/redocly.yaml",
 		"api:bundle": "redocly bundle api/openapi.yaml -o api/bundled.yaml --config api/redocly.yaml",
+		"api:watch": "nodemon --watch api --ext yaml --ignore api/bundled.yaml --exec 'npm run api:bundle'",
 		"api:preview": "redocly preview-docs api/openapi.yaml --config api/redocly.yaml",
 		"api:docs": "redocly build-docs api/bundled.yaml -o api-docs/index.html"
 	},
@@ -172,8 +173,10 @@
 		"eslint-plugin-svelte": "^3.0.0",
 		"globals": "^16.0.0",
 		"happy-dom": "^20.0.11",
+		"husky": "^9.1.7",
 		"msw": "^2.12.7",
 		"npm-watch": "^0.13.0",
+		"picomatch": "^4.0.3",
 		"playwright": "^1.53.0",
 		"prettier": "^3.4.2",
 		"prettier-plugin-svelte": "^3.3.3",
@@ -187,7 +190,8 @@
 		"vite": "^6.2.6",
 		"vite-plugin-devtools-json": "^0.2.1",
 		"vitest": "^3.2.3",
-		"vitest-browser-svelte": "^0.1.0"
+		"vitest-browser-svelte": "^0.1.0",
+		"yaml": "^2.8.2"
 	},
 	"overrides": {
 		"@sveltejs/kit": {