@d34dman/flowdrop 0.0.56 → 0.0.57

package/dist/types/events.d.ts

@@ -6,7 +6,7 @@
  *
  * @module types/events
  */
-import type { Workflow } from './index.js';
+import type { Workflow, NodeExecutionInfo } from './index.js';
 /**
  * Types of workflow changes
  *
@@ -113,6 +113,33 @@ export interface FlowDropEventHandlers {
      * @returns true to suppress default error handling, false/void to show default toast
      */
     onApiError?: (error: Error, operation: string) => boolean | void;
+    /**
+     * Called when an Agent Spec execution starts
+     *
+     * @param executionId - The runtime execution ID
+     */
+    onAgentSpecExecutionStarted?: (executionId: string) => void;
+    /**
+     * Called when an Agent Spec execution completes successfully
+     *
+     * @param executionId - The runtime execution ID
+     * @param results - Execution results from the runtime
+     */
+    onAgentSpecExecutionCompleted?: (executionId: string, results: Record<string, unknown>) => void;
+    /**
+     * Called when an Agent Spec execution fails
+     *
+     * @param executionId - The runtime execution ID
+     * @param error - The error that occurred
+     */
+    onAgentSpecExecutionFailed?: (executionId: string, error: Error) => void;
+    /**
+     * Called when a node's execution status is updated during Agent Spec execution
+     *
+     * @param nodeId - The FlowDrop node ID
+     * @param status - Updated execution info
+     */
+    onAgentSpecNodeStatusUpdate?: (nodeId: string, status: NodeExecutionInfo) => void;
 }
 /**
  * Feature flags for FlowDrop

package/dist/types/index.d.ts

@@ -536,6 +536,17 @@ export interface NodeMetadata {
     inputs: NodePort[];
     outputs: NodePort[];
     configSchema?: ConfigSchema;
+    /**
+     * Optional UI Schema that controls how configSchema fields are
+     * arranged, grouped, and displayed in the configuration form.
+     *
+     * When not provided, fields render in flat order (backward compatible).
+     * Uses JSON Forms-inspired format with VerticalLayout, Group, and Control elements.
+     *
+     * @see UISchemaElement for the element type definitions
+     * @see https://jsonforms.io/docs/uischema
+     */
+    uiSchema?: import('./uischema.js').UISchemaElement;
     /** Default configuration values for this node type */
     config?: Record<string, unknown>;
     tags?: string[];
@@ -1199,3 +1210,5 @@ export type { AuthProvider, StaticAuthConfig, CallbackAuthConfig } from './auth.
 export { StaticAuthProvider, CallbackAuthProvider, NoAuthProvider } from './auth.js';
 export type { FlowDropSettings, ThemeSettings, EditorSettings, UISettings, BehaviorSettings, ApiSettings, ThemePreference, ResolvedTheme, SettingsCategory, PartialSettings, SyncStatus, SettingsStoreState, SettingsChangeEvent, SettingsChangeCallback } from './settings.js';
 export { DEFAULT_SETTINGS, DEFAULT_THEME_SETTINGS, DEFAULT_EDITOR_SETTINGS, DEFAULT_UI_SETTINGS, DEFAULT_BEHAVIOR_SETTINGS, DEFAULT_API_SETTINGS, SETTINGS_CATEGORIES, SETTINGS_CATEGORY_LABELS, SETTINGS_CATEGORY_ICONS, SETTINGS_STORAGE_KEY } from './settings.js';
+export type { UISchemaElementType, UISchemaElementBase, UISchemaControl, UISchemaVerticalLayout, UISchemaGroup, UISchemaElement } from './uischema.js';
+export { isUISchemaControl, isUISchemaVerticalLayout, isUISchemaGroup } from './uischema.js';

package/dist/types/index.js

@@ -20,3 +20,4 @@ export function dynamicPortToNodePort(port, portType) {
 }
 export { StaticAuthProvider, CallbackAuthProvider, NoAuthProvider } from './auth.js';
 export { DEFAULT_SETTINGS, DEFAULT_THEME_SETTINGS, DEFAULT_EDITOR_SETTINGS, DEFAULT_UI_SETTINGS, DEFAULT_BEHAVIOR_SETTINGS, DEFAULT_API_SETTINGS, SETTINGS_CATEGORIES, SETTINGS_CATEGORY_LABELS, SETTINGS_CATEGORY_ICONS, SETTINGS_STORAGE_KEY } from './settings.js';
+export { isUISchemaControl, isUISchemaVerticalLayout, isUISchemaGroup } from './uischema.js';

package/dist/types/uischema.d.ts

@@ -0,0 +1,144 @@
+/**
+ * UISchema Types for FlowDrop Form Layout
+ *
+ * Inspired by JSON Forms (EclipseSource) UISchema specification.
+ * Controls how form fields are arranged, grouped, and displayed
+ * without modifying the underlying data schema (ConfigSchema).
+ *
+ * The UISchema is a separate concern from the data schema:
+ * - ConfigSchema defines what data is valid (validation)
+ * - UISchema defines how the form is rendered (presentation)
+ *
+ * @see https://jsonforms.io/docs/uischema
+ *
+ * @example
+ * ```json
+ * {
+ *   "type": "VerticalLayout",
+ *   "elements": [
+ *     { "type": "Control", "scope": "#/properties/model" },
+ *     {
+ *       "type": "Group",
+ *       "label": "Advanced Settings",
+ *       "collapsible": true,
+ *       "defaultOpen": false,
+ *       "elements": [
+ *         { "type": "Control", "scope": "#/properties/temperature" },
+ *         { "type": "Control", "scope": "#/properties/maxTokens" }
+ *       ]
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+/**
+ * Supported UISchema element types.
+ * Designed for future extension with HorizontalLayout, Categorization, etc.
+ */
+export type UISchemaElementType = 'VerticalLayout' | 'Group' | 'Control';
+/**
+ * Base interface for all UISchema elements.
+ */
+export interface UISchemaElementBase {
+    /** Discriminator for the element type */
+    type: UISchemaElementType;
+}
+/**
+ * Control element - references a single field in the data schema.
+ * Uses JSON Pointer syntax for the scope path.
+ *
+ * @example
+ * ```json
+ * { "type": "Control", "scope": "#/properties/temperature" }
+ * ```
+ */
+export interface UISchemaControl extends UISchemaElementBase {
+    type: 'Control';
+    /**
+     * JSON Pointer to the property in the data schema.
+     * Must follow the format: #/properties/<fieldName>
+     */
+    scope: string;
+    /**
+     * Optional label override. If not provided, the field's
+     * schema title or key is used.
+     */
+    label?: string;
+}
+/**
+ * Layout container that arranges its child elements vertically.
+ * Can be used as root element or nested inside groups.
+ *
+ * @example
+ * ```json
+ * {
+ *   "type": "VerticalLayout",
+ *   "elements": [
+ *     { "type": "Control", "scope": "#/properties/name" },
+ *     { "type": "Control", "scope": "#/properties/email" }
+ *   ]
+ * }
+ * ```
+ */
+export interface UISchemaVerticalLayout extends UISchemaElementBase {
+    type: 'VerticalLayout';
+    /** Child elements to render vertically */
+    elements: UISchemaElement[];
+}
+/**
+ * Group element - renders a fieldset with a label and optional collapsible behavior.
+ * Extends the JSON Forms Group with FlowDrop-specific collapse options.
+ *
+ * @example
+ * ```json
+ * {
+ *   "type": "Group",
+ *   "label": "Advanced Settings",
+ *   "description": "Fine-tuning parameters",
+ *   "collapsible": true,
+ *   "defaultOpen": false,
+ *   "elements": [
+ *     { "type": "Control", "scope": "#/properties/temperature" },
+ *     { "type": "Control", "scope": "#/properties/maxTokens" }
+ *   ]
+ * }
+ * ```
+ */
+export interface UISchemaGroup extends UISchemaElementBase {
+    type: 'Group';
+    /** Display label for the fieldset legend / summary */
+    label: string;
+    /** Child elements within the group */
+    elements: UISchemaElement[];
+    /** Optional description displayed below the label */
+    description?: string;
+    /**
+     * Whether the group can be collapsed.
+     * When true, renders as `<details>/<summary>`.
+     * @default true
+     */
+    collapsible?: boolean;
+    /**
+     * Whether the group is initially open (expanded).
+     * Only relevant when collapsible is true.
+     * @default true
+     */
+    defaultOpen?: boolean;
+}
+/**
+ * Union type of all supported UISchema elements.
+ * This is the recursive type used in elements arrays.
+ */
+export type UISchemaElement = UISchemaControl | UISchemaVerticalLayout | UISchemaGroup;
+/**
+ * Type guard: checks if element is a Control
+ */
+export declare function isUISchemaControl(element: UISchemaElement): element is UISchemaControl;
+/**
+ * Type guard: checks if element is a VerticalLayout
+ */
+export declare function isUISchemaVerticalLayout(element: UISchemaElement): element is UISchemaVerticalLayout;
+/**
+ * Type guard: checks if element is a Group
+ */
+export declare function isUISchemaGroup(element: UISchemaElement): element is UISchemaGroup;

package/dist/types/uischema.js

@@ -0,0 +1,51 @@
+/**
+ * UISchema Types for FlowDrop Form Layout
+ *
+ * Inspired by JSON Forms (EclipseSource) UISchema specification.
+ * Controls how form fields are arranged, grouped, and displayed
+ * without modifying the underlying data schema (ConfigSchema).
+ *
+ * The UISchema is a separate concern from the data schema:
+ * - ConfigSchema defines what data is valid (validation)
+ * - UISchema defines how the form is rendered (presentation)
+ *
+ * @see https://jsonforms.io/docs/uischema
+ *
+ * @example
+ * ```json
+ * {
+ *   "type": "VerticalLayout",
+ *   "elements": [
+ *     { "type": "Control", "scope": "#/properties/model" },
+ *     {
+ *       "type": "Group",
+ *       "label": "Advanced Settings",
+ *       "collapsible": true,
+ *       "defaultOpen": false,
+ *       "elements": [
+ *         { "type": "Control", "scope": "#/properties/temperature" },
+ *         { "type": "Control", "scope": "#/properties/maxTokens" }
+ *       ]
+ *     }
+ *   ]
+ * }
+ * ```
+ */
+/**
+ * Type guard: checks if element is a Control
+ */
+export function isUISchemaControl(element) {
+    return element.type === 'Control';
+}
+/**
+ * Type guard: checks if element is a VerticalLayout
+ */
+export function isUISchemaVerticalLayout(element) {
+    return element.type === 'VerticalLayout';
+}
+/**
+ * Type guard: checks if element is a Group
+ */
+export function isUISchemaGroup(element) {
+    return element.type === 'Group';
+}

package/dist/utils/uischema.d.ts

@@ -0,0 +1,52 @@
+/**
+ * UISchema Utilities
+ *
+ * Functions for resolving JSON Pointer scope strings to property keys,
+ * and for generating default UISchema from a ConfigSchema.
+ */
+import type { ConfigSchema } from '../types/index.js';
+import type { UISchemaElement, UISchemaVerticalLayout } from '../types/uischema.js';
+/**
+ * Resolve a JSON Pointer scope string to a property key.
+ *
+ * Supports the JSON Forms scope format: #/properties/<fieldName>
+ *
+ * @param scope - JSON Pointer string (e.g., "#/properties/temperature")
+ * @returns The property key (e.g., "temperature"), or null if invalid
+ *
+ * @example
+ * ```typescript
+ * resolveScopeToKey("#/properties/temperature") // => "temperature"
+ * resolveScopeToKey("#/properties/nested/deep")  // => null (only single-level supported)
+ * resolveScopeToKey("invalid")                   // => null
+ * ```
+ */
+export declare function resolveScopeToKey(scope: string): string | null;
+/**
+ * Build a scope string from a property key.
+ * Inverse of resolveScopeToKey.
+ *
+ * @param key - Property key (e.g., "temperature")
+ * @returns JSON Pointer scope string (e.g., "#/properties/temperature")
+ */
+export declare function keyToScope(key: string): string;
+/**
+ * Generate a default UISchema from a ConfigSchema.
+ * Creates a flat VerticalLayout with one Control per property,
+ * preserving the property iteration order.
+ *
+ * This is a convenience utility for programmatically building UISchema.
+ *
+ * @param schema - The ConfigSchema to generate a UISchema from
+ * @returns A VerticalLayout UISchema element
+ */
+export declare function generateDefaultUISchema(schema: ConfigSchema): UISchemaVerticalLayout;
+/**
+ * Collect all property keys referenced by Controls in a UISchema tree.
+ * Useful for detecting properties that are NOT in the UISchema
+ * (e.g., to warn about unreferenced fields during development).
+ *
+ * @param element - Root UISchema element
+ * @returns Set of property keys referenced by Controls
+ */
+export declare function collectReferencedKeys(element: UISchemaElement): Set<string>;

package/dist/utils/uischema.js

@@ -0,0 +1,88 @@
+/**
+ * UISchema Utilities
+ *
+ * Functions for resolving JSON Pointer scope strings to property keys,
+ * and for generating default UISchema from a ConfigSchema.
+ */
+/**
+ * Resolve a JSON Pointer scope string to a property key.
+ *
+ * Supports the JSON Forms scope format: #/properties/<fieldName>
+ *
+ * @param scope - JSON Pointer string (e.g., "#/properties/temperature")
+ * @returns The property key (e.g., "temperature"), or null if invalid
+ *
+ * @example
+ * ```typescript
+ * resolveScopeToKey("#/properties/temperature") // => "temperature"
+ * resolveScopeToKey("#/properties/nested/deep")  // => null (only single-level supported)
+ * resolveScopeToKey("invalid")                   // => null
+ * ```
+ */
+export function resolveScopeToKey(scope) {
+    const prefix = '#/properties/';
+    if (!scope.startsWith(prefix)) {
+        return null;
+    }
+    const key = scope.slice(prefix.length);
+    // Only support single-level property references (no nested paths)
+    if (key.includes('/') || key.length === 0) {
+        return null;
+    }
+    return key;
+}
+/**
+ * Build a scope string from a property key.
+ * Inverse of resolveScopeToKey.
+ *
+ * @param key - Property key (e.g., "temperature")
+ * @returns JSON Pointer scope string (e.g., "#/properties/temperature")
+ */
+export function keyToScope(key) {
+    return `#/properties/${key}`;
+}
+/**
+ * Generate a default UISchema from a ConfigSchema.
+ * Creates a flat VerticalLayout with one Control per property,
+ * preserving the property iteration order.
+ *
+ * This is a convenience utility for programmatically building UISchema.
+ *
+ * @param schema - The ConfigSchema to generate a UISchema from
+ * @returns A VerticalLayout UISchema element
+ */
+export function generateDefaultUISchema(schema) {
+    const elements = Object.keys(schema.properties).map((key) => ({
+        type: 'Control',
+        scope: keyToScope(key)
+    }));
+    return {
+        type: 'VerticalLayout',
+        elements
+    };
+}
+/**
+ * Collect all property keys referenced by Controls in a UISchema tree.
+ * Useful for detecting properties that are NOT in the UISchema
+ * (e.g., to warn about unreferenced fields during development).
+ *
+ * @param element - Root UISchema element
+ * @returns Set of property keys referenced by Controls
+ */
+export function collectReferencedKeys(element) {
+    const keys = new Set();
+    function walk(el) {
+        if (el.type === 'Control') {
+            const key = resolveScopeToKey(el.scope);
+            if (key)
+                keys.add(key);
+        }
+        else if (el.type === 'VerticalLayout' || el.type === 'Group') {
+            for (const child of el.elements) {
+                walk(child);
+            }
+        }
+    }
+    walk(element);
+    return keys;
+}

package/package.json

@@ -2,7 +2,7 @@
 	"name": "@d34dman/flowdrop",
 	"license": "MIT",
 	"private": false,
-	"version": "0.0.56",
+	"version": "0.0.57",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run prepack",