@d34dman/flowdrop 0.0.46 → 0.0.47

package/dist/services/variableService.js

@@ -0,0 +1,367 @@
+/**
+ * Variable Service
+ * Derives available template variables from connected upstream nodes' output schemas.
+ * Used by the template editor for autocomplete suggestions.
+ *
+ * @module services/variableService
+ */
+/**
+ * Converts a JSON Schema property type to a TemplateVariableType.
+ *
+ * @param schemaType - The type from JSON Schema
+ * @returns The corresponding TemplateVariableType
+ */
+function toTemplateVariableType(schemaType) {
+    switch (schemaType) {
+        case "string":
+            return "string";
+        case "number":
+            return "number";
+        case "integer":
+            return "integer";
+        case "boolean":
+            return "boolean";
+        case "array":
+            return "array";
+        case "object":
+            return "object";
+        case "float":
+            return "float";
+        default:
+            return "mixed";
+    }
+}
+/**
+ * Converts a JSON Schema property to a TemplateVariable.
+ * Recursively processes nested objects and arrays.
+ *
+ * @param name - The property name
+ * @param property - The JSON Schema property definition
+ * @param sourcePort - Optional source port ID
+ * @param sourceNode - Optional source node ID
+ * @returns A TemplateVariable representing the property
+ */
+function propertyToTemplateVariable(name, property, sourcePort, sourceNode) {
+    const variable = {
+        name,
+        label: property.title ?? name,
+        description: property.description,
+        type: toTemplateVariableType(property.type),
+        sourcePort,
+        sourceNode
+    };
+    // Handle nested object properties
+    if (property.type === "object" && property.properties) {
+        variable.properties = {};
+        for (const [propName, propValue] of Object.entries(property.properties)) {
+            variable.properties[propName] = propertyToTemplateVariable(propName, propValue, sourcePort, sourceNode);
+        }
+    }
+    // Handle array items
+    if (property.type === "array" && property.items) {
+        variable.items = propertyToTemplateVariable("item", property.items, sourcePort, sourceNode);
+    }
+    return variable;
+}
+/**
+ * Creates a TemplateVariable from a NodePort.
+ * Uses the port's schema if available, otherwise creates a basic variable.
+ *
+ * @param port - The output port to convert
+ * @param sourceNode - The source node ID
+ * @returns A TemplateVariable representing the port's data
+ */
+function portToTemplateVariable(port, sourceNode) {
+    // If the port has a schema, use it to build a detailed variable
+    if (port.schema && port.schema.properties) {
+        const variable = {
+            name: port.id,
+            label: port.name,
+            description: port.description,
+            type: "object",
+            sourcePort: port.id,
+            sourceNode,
+            properties: {}
+        };
+        for (const [propName, propValue] of Object.entries(port.schema.properties)) {
+            variable.properties[propName] = propertyToTemplateVariable(propName, propValue, port.id, sourceNode);
+        }
+        return variable;
+    }
+    // Otherwise, create a basic variable based on dataType
+    return {
+        name: port.id,
+        label: port.name,
+        description: port.description,
+        type: toTemplateVariableType(port.dataType),
+        sourcePort: port.id,
+        sourceNode
+    };
+}
+/**
+ * Extracts the port ID from a handle ID.
+ * Handle IDs follow the format: {nodeId}-{input|output}-{portId}
+ *
+ * @param handleId - The handle ID (e.g., "http_request.1-output-json")
+ * @returns The port ID (e.g., "json") or the original handleId if parsing fails
+ */
+function extractPortIdFromHandle(handleId) {
+    if (!handleId)
+        return undefined;
+    // Handle format: {nodeId}-{input|output}-{portId}
+    // Example: "http_request.1-output-json" -> "json"
+    const outputMatch = handleId.match(/-output-(.+)$/);
+    if (outputMatch) {
+        return outputMatch[1];
+    }
+    const inputMatch = handleId.match(/-input-(.+)$/);
+    if (inputMatch) {
+        return inputMatch[1];
+    }
+    // Fallback: return the handle ID as-is (might be a simple port ID)
+    return handleId;
+}
+/**
+ * Finds all upstream connections to a node.
+ * Returns information about each connection including source node and ports.
+ *
+ * @param node - The node to find upstream connections for
+ * @param nodes - All nodes in the workflow
+ * @param edges - All edges in the workflow
+ * @returns Array of upstream connection information
+ */
+function findUpstreamConnections(node, nodes, edges) {
+    const connections = [];
+    // Find all edges that target this node
+    const incomingEdges = edges.filter((edge) => edge.target === node.id);
+    for (const edge of incomingEdges) {
+        // Find the source node
+        const sourceNode = nodes.find((n) => n.id === edge.source);
+        if (!sourceNode)
+            continue;
+        // Extract port IDs from handle IDs
+        // Handle format: {nodeId}-{input|output}-{portId}
+        const sourcePortId = extractPortIdFromHandle(edge.sourceHandle);
+        const targetPortId = extractPortIdFromHandle(edge.targetHandle);
+        // Find the source output port
+        const sourcePort = sourceNode.data.metadata.outputs.find((p) => p.id === sourcePortId);
+        // Find the target input port
+        const targetPort = node.data.metadata.inputs.find((p) => p.id === targetPortId);
+        connections.push({
+            edge,
+            sourceNode,
+            sourcePort,
+            targetPort
+        });
+    }
+    return connections;
+}
+/**
+ * Derives available template variables from connected upstream nodes.
+ * Variables are extracted from the output schemas of nodes connected to
+ * the current node's input ports.
+ *
+ * @param node - The current node being configured
+ * @param nodes - All nodes in the workflow
+ * @param edges - All edges in the workflow
+ * @param options - Optional configuration for filtering variables
+ * @returns A VariableSchema containing all available variables
+ *
+ * @example
+ * ```typescript
+ * // Get variables from all connected ports
+ * const variableSchema = getAvailableVariables(currentNode, allNodes, allEdges);
+ *
+ * // Get variables only from specific input ports
+ * const filteredSchema = getAvailableVariables(currentNode, allNodes, allEdges, {
+ *   targetPortIds: ["data", "context"]
+ * });
+ * ```
+ */
+export function getAvailableVariables(node, nodes, edges, options) {
+    const variables = {};
+    const { targetPortIds, includePortName } = options ?? {};
+    // Find all upstream connections
+    const connections = findUpstreamConnections(node, nodes, edges);
+    for (const connection of connections) {
+        const { sourceNode, sourcePort, targetPort } = connection;
+        // Skip trigger ports - they don't carry data
+        if (sourcePort?.dataType === "trigger")
+            continue;
+        if (targetPort?.dataType === "trigger")
+            continue;
+        // Get the target port ID for filtering
+        const targetPortId = targetPort?.id ?? sourcePort?.id ?? "data";
+        // Filter by target port IDs if specified
+        if (targetPortIds !== undefined) {
+            if (!targetPortIds.includes(targetPortId))
+                continue;
+        }
+        if (!sourcePort)
+            continue;
+        // If the source port has a schema with top-level properties,
+        // unpack them as top-level variables (unless includePortName is true)
+        if (sourcePort.schema?.properties && !includePortName) {
+            // Unpack schema properties as top-level variables
+            for (const [propName, propValue] of Object.entries(sourcePort.schema.properties)) {
+                // Skip if we already have a variable with this name
+                if (variables[propName])
+                    continue;
+                variables[propName] = propertyToTemplateVariable(propName, propValue, sourcePort.id, sourceNode.id);
+            }
+        }
+        else {
+            // No schema or includePortName is true - use port name as the variable
+            const variableName = includePortName ? targetPortId : (targetPortId);
+            // Skip if we already have a variable with this name
+            if (variables[variableName])
+                continue;
+            const variable = portToTemplateVariable(sourcePort, sourceNode.id);
+            variable.name = variableName;
+            variable.label = targetPort?.name ?? sourcePort.name;
+            variables[variableName] = variable;
+        }
+    }
+    return { variables };
+}
+/**
+ * Converts simple variable hints (string array) to a VariableSchema.
+ * Used for backward compatibility with the old variableHints format.
+ *
+ * @param hints - Array of variable names
+ * @returns A VariableSchema with basic string variables
+ */
+export function hintsToVariableSchema(hints) {
+    const variables = {};
+    for (const hint of hints) {
+        variables[hint] = {
+            name: hint,
+            type: "mixed"
+        };
+    }
+    return { variables };
+}
+/**
+ * Gets the child variables for a given path in the variable schema.
+ * Used for drilling down into nested objects and arrays.
+ *
+ * @param schema - The variable schema
+ * @param path - The path to the parent variable (e.g., "user", "user.address")
+ * @returns Array of child variables, or empty array if none found
+ *
+ * @example
+ * ```typescript
+ * // For path "user" with schema containing user.name, user.email, user.address
+ * getChildVariables(schema, "user");
+ * // Returns: [{ name: "name", ... }, { name: "email", ... }, { name: "address", ... }]
+ *
+ * // For path "user.address" with schema containing city, country
+ * getChildVariables(schema, "user.address");
+ * // Returns: [{ name: "city", ... }, { name: "country", ... }]
+ * ```
+ */
+export function getChildVariables(schema, path) {
+    const parts = path.split(".");
+    let current;
+    // Navigate to the target variable
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        // Handle array index access (e.g., "items[0]")
+        const arrayMatch = part.match(/^(\w+)\[(\d+|\*)\]$/);
+        if (arrayMatch) {
+            const [, varName] = arrayMatch;
+            if (i === 0) {
+                current = schema.variables[varName];
+            }
+            else if (current?.properties) {
+                current = current.properties[varName];
+            }
+            // After array access, move to items schema
+            if (current?.items) {
+                current = current.items;
+            }
+            continue;
+        }
+        // Regular property access
+        if (i === 0) {
+            current = schema.variables[part];
+        }
+        else if (current?.properties) {
+            current = current.properties[part];
+        }
+        else {
+            return [];
+        }
+    }
+    // Return child properties if available
+    if (current?.properties) {
+        return Object.values(current.properties);
+    }
+    return [];
+}
+/**
+ * Gets suggestions for array index access.
+ * Returns common index options like [0], [1], [2], and [*] for all items.
+ *
+ * @param maxIndex - Maximum index to suggest (default: 2)
+ * @returns Array of index suggestion strings
+ */
+export function getArrayIndexSuggestions(maxIndex = 2) {
+    const suggestions = [];
+    for (let i = 0; i <= maxIndex; i++) {
+        suggestions.push(`${i}]`);
+    }
+    // Add wildcard for "all items"
+    suggestions.push("*]");
+    return suggestions;
+}
+/**
+ * Checks if a variable at the given path is an array.
+ *
+ * @param schema - The variable schema
+ * @param path - The path to check (e.g., "items", "user.orders")
+ * @returns True if the variable is an array type
+ */
+export function isArrayVariable(schema, path) {
+    const parts = path.split(".");
+    let current;
+    for (let i = 0; i < parts.length; i++) {
+        const part = parts[i];
+        // Handle array index access
+        const arrayMatch = part.match(/^(\w+)\[(\d+|\*)\]$/);
+        if (arrayMatch) {
+            const [, varName] = arrayMatch;
+            if (i === 0) {
+                current = schema.variables[varName];
+            }
+            else if (current?.properties) {
+                current = current.properties[varName];
+            }
+            if (current?.items) {
+                current = current.items;
+            }
+            continue;
+        }
+        if (i === 0) {
+            current = schema.variables[part];
+        }
+        else if (current?.properties) {
+            current = current.properties[part];
+        }
+        else {
+            return false;
+        }
+    }
+    return current?.type === "array";
+}
+/**
+ * Checks if a variable at the given path has child properties.
+ *
+ * @param schema - The variable schema
+ * @param path - The path to check
+ * @returns True if the variable has children that can be drilled into
+ */
+export function hasChildren(schema, path) {
+    const children = getChildVariables(schema, path);
+    return children.length > 0;
+}

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,121 @@ 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.
+ *
+ * @example
+ * ```json
+ * {
+ *   "type": "string",
+ *   "format": "template",
+ *   "variables": {
+ *     "ports": ["data", "context"],
+ *     "includePortName": true
+ *   }
+ * }
+ * ```
+ */
+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;
+}
 /**
  * Union type for all schema types
  */

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.47",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run prepack",
@@ -214,4 +214,4 @@
 			"static"
 		]
 	}
-}
+}