@rilaykit/workflow 2.0.1 → 4.0.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ril, FormConfiguration, StepLifecycleHooks, StepPermissions, CustomStepRenderer, DynamicStepConfig, NavigationConfig, PersistenceConfig, WorkflowAnalytics, CompletionConfig, WorkflowPlugin, StepConfig, WorkflowConfig, WorkflowContext, ValidationError, ValidationResult, RendererChildrenFunction, WorkflowNextButtonRendererProps, WorkflowPreviousButtonRendererProps, WorkflowSkipButtonRendererProps, WorkflowStepperRendererProps } from '@rilaykit/core';
+import { ril, FormConfiguration, StepLifecycleHooks, StepPermissions, CustomStepRenderer, DynamicStepConfig, NavigationConfig, PersistenceConfig, CompletionConfig, WorkflowAnalytics, WorkflowPlugin, StepConfig, WorkflowConfig, WorkflowContext, ValidationError, ValidationResult, RendererChildrenFunction, WorkflowNextButtonRendererProps, WorkflowPreviousButtonRendererProps, WorkflowSkipButtonRendererProps, WorkflowStepperRendererProps } from '@rilaykit/core';
 export * from '@rilaykit/core';
 export { createZodValidator, ril } from '@rilaykit/core';
 import { form } from '@rilaykit/forms';
@@ -7,21 +7,120 @@ import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as react from 'react';
 import react__default from 'react';
 
+/**
+ * Enhanced step configuration interface for better type safety and simplicity
+ *
+ * This interface defines the structure for creating workflow steps with all
+ * necessary configuration options. It provides a clean API for step definition
+ * while maintaining flexibility for complex workflows.
+ *
+ * @interface StepDefinition
+ */
 interface StepDefinition {
-    id: string;
+    /**
+     * Unique identifier for the step
+     * If not provided, will be auto-generated using the internal ID generator
+     */
+    id?: string;
+    /**
+     * Display title for the step
+     * This will be shown to users in the workflow interface
+     */
     title: string;
+    /**
+     * Optional description providing additional context about the step
+     * Useful for complex workflows where steps need explanation
+     */
     description?: string;
+    /**
+     * Form configuration for the step
+     * Can be either a built FormConfiguration or a form builder instance
+     */
     formConfig: FormConfiguration | form;
+    /**
+     * Whether users can skip this step
+     * @default false
+     */
     allowSkip?: boolean;
+    /**
+     * Whether this step is required to complete the workflow
+     * @default true
+     */
     requiredToComplete?: boolean;
+    /**
+     * Lifecycle hooks for step events
+     * Allows custom logic at different points in the step lifecycle
+     */
     hooks?: StepLifecycleHooks;
+    /**
+     * Permission configuration for step access control
+     * Defines who can view, edit, or complete this step
+     */
     permissions?: StepPermissions;
+    /**
+     * Custom renderer for the step
+     * Allows complete customization of step presentation
+     */
     renderer?: CustomStepRenderer;
+    /**
+     * Dynamic step configuration
+     * Enables conditional step behavior based on previous step data
+     */
     dynamicConfig?: DynamicStepConfig;
 }
+/**
+ * Configuration options for workflow behavior and features
+ *
+ * This interface consolidates all workflow-level configuration options
+ * into a single, easy-to-use structure for the configure() method.
+ *
+ * @interface WorkflowOptions
+ */
+interface WorkflowOptions {
+    /** Navigation behavior configuration */
+    navigation?: NavigationConfig;
+    /** Data persistence settings */
+    persistence?: PersistenceConfig;
+    /** Workflow completion handling */
+    completion?: CompletionConfig;
+    /** Analytics and tracking configuration */
+    analytics?: WorkflowAnalytics;
+}
 /**
  * Workflow builder class for creating complex multi-step workflows
- * Simplified API with auto-build capability
+ *
+ * The flow class provides a comprehensive API for building multi-step workflows
+ * with form-based steps. It follows the builder pattern with method chaining
+ * and includes advanced features like dynamic steps, plugins, and analytics.
+ *
+ * Key Features:
+ * - Polymorphic step addition (single or multiple steps)
+ * - Plugin system for extensibility
+ * - Built-in validation and error handling
+ * - Clone and export/import functionality
+ * - Comprehensive statistics and analytics
+ * - Type-safe configuration management
+ *
+ * @example
+ * ```typescript
+ * const workflow = flow.create(rilConfig, 'user-onboarding', 'User Onboarding')
+ *   .addStep({
+ *     title: 'Personal Information',
+ *     formConfig: personalInfoForm
+ *   })
+ *   .addStep({
+ *     title: 'Account Setup',
+ *     formConfig: accountForm,
+ *     allowSkip: true
+ *   })
+ *   .configure({
+ *     navigation: { allowBackNavigation: true },
+ *     persistence: { saveOnStepComplete: true }
+ *   })
+ *   .build();
+ * ```
+ *
+ * @class flow
  */
 declare class flow {
     private config;
@@ -34,86 +133,415 @@ declare class flow {
     private completion?;
     private analytics?;
     private plugins;
+    private idGenerator;
+    /**
+     * Creates a new workflow builder instance
+     *
+     * @param config - The ril configuration instance
+     * @param workflowId - Unique identifier for the workflow
+     * @param workflowName - Display name for the workflow
+     * @param description - Optional description of the workflow purpose
+     */
     constructor(config: ril, workflowId: string, workflowName: string, description?: string);
+    /**
+     * Static factory method to create a new workflow builder
+     *
+     * This is the preferred way to create workflow builders as it provides
+     * better type inference and follows the factory pattern.
+     *
+     * @param config - The ril configuration instance
+     * @param workflowId - Unique identifier for the workflow
+     * @param workflowName - Display name for the workflow
+     * @param description - Optional description of the workflow purpose
+     * @returns A new flow builder instance
+     *
+     * @example
+     * ```typescript
+     * const workflow = flow.create(rilConfig, 'checkout', 'Checkout Process');
+     * ```
+     */
     static create(config: ril, workflowId: string, workflowName: string, description?: string): flow;
     /**
      * Helper method to create a step configuration from StepDefinition
+     *
+     * This internal method handles the conversion from the user-friendly
+     * StepDefinition interface to the internal StepConfig structure,
+     * including ID generation and form configuration processing.
+     *
+     * @private
+     * @param stepDef - The step definition to convert
+     * @returns A complete StepConfig object
      */
     private createStepFromDefinition;
     /**
-     * Add a step using simplified StepDefinition object
+     * Universal add method - handles single steps or multiple steps
+     *
+     * This polymorphic method provides a clean API for adding steps to the workflow.
+     * It can handle both single step definitions and arrays of step definitions,
+     * making it easy to build workflows programmatically.
+     *
+     * @param stepDefinition - Single step definition
+     * @returns The flow instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Add a single step
+     * workflow.addStep({
+     *   title: 'User Details',
+     *   formConfig: userForm
+     * });
+     * ```
      */
     addStep(stepDefinition: StepDefinition): this;
+    /**
+     * Universal add method - handles single steps or multiple steps
+     *
+     * @param stepDefinitions - Array of step definitions
+     * @returns The flow instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * // Add multiple steps at once
+     * workflow.addStep([
+     *   { title: 'Step 1', formConfig: form1 },
+     *   { title: 'Step 2', formConfig: form2 }
+     * ]);
+     * ```
+     */
+    addStep(stepDefinitions: StepDefinition[]): this;
     /**
      * Add a dynamic step using StepDefinition with dynamicConfig
+     *
+     * Dynamic steps can change their behavior, visibility, or configuration
+     * based on data from previous steps. This method is a convenience wrapper
+     * around addStep() with enhanced type safety for dynamic configurations.
+     *
+     * @param stepDefinition - Step definition with required dynamicConfig
+     * @returns The flow instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * workflow.addDynamicStep({
+     *   title: 'Conditional Step',
+     *   formConfig: conditionalForm,
+     *   dynamicConfig: {
+     *     condition: (data) => data.userType === 'premium',
+     *     generator: (data) => generatePremiumForm(data)
+     *   }
+     * });
+     * ```
      */
     addDynamicStep(stepDefinition: StepDefinition & {
         dynamicConfig: DynamicStepConfig;
     }): this;
     /**
-     * Add multiple steps at once
+     * Universal configuration method for all workflow options
+     *
+     * This method replaces individual setter methods with a single consolidated API
+     * for configuring all aspects of workflow behavior. It uses deep merging to
+     * preserve existing configurations while applying new settings.
+     *
+     * @param options - Configuration options to apply
+     * @returns The flow instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * workflow.configure({
+     *   navigation: {
+     *     allowBackNavigation: true,
+     *     showProgressBar: true
+     *   },
+     *   persistence: {
+     *     saveOnStepComplete: true,
+     *     storageKey: 'my-workflow'
+     *   },
+     *   analytics: {
+     *     trackStepCompletion: true,
+     *     trackFieldInteractions: false
+     *   }
+     * });
+     * ```
      */
-    addSteps(stepDefinitions: StepDefinition[]): this;
+    configure(options: WorkflowOptions): this;
     /**
-     * Configuration setters with fluent interface
+     * Plugin management with enhanced validation
+     *
+     * Installs a plugin into the workflow with dependency validation.
+     * Plugins can extend workflow functionality, add custom renderers,
+     * or integrate with external services.
+     *
+     * @param plugin - The plugin to install
+     * @returns The flow instance for method chaining
+     * @throws Error if plugin installation fails or dependencies are missing
+     *
+     * @example
+     * ```typescript
+     * workflow.use(customPlugin)
+     *         .use(anotherPlugin);
+     * ```
      */
-    setNavigation(navigation: NavigationConfig): this;
-    enableBackNavigation(enabled?: boolean): this;
-    enableStepSkipping(enabled?: boolean): this;
-    setPersistence(persistence: PersistenceConfig): this;
-    setAnalytics(analytics: WorkflowAnalytics): this;
-    setCompletion(completion: CompletionConfig): this;
+    use(plugin: WorkflowPlugin): this;
     /**
-     * Plugin management
+     * Validates plugin dependencies before installation
+     *
+     * @private
+     * @param plugin - The plugin to validate
+     * @throws Error if required dependencies are missing
      */
-    use(plugin: WorkflowPlugin): this;
     private validatePluginDependencies;
+    /**
+     * Remove a plugin from the workflow
+     *
+     * @param pluginName - Name of the plugin to remove
+     * @returns The flow instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * workflow.removePlugin('analytics-plugin');
+     * ```
+     */
     removePlugin(pluginName: string): this;
     /**
-     * Step management
+     * Update an existing step configuration
+     *
+     * Allows modification of step properties after the step has been added.
+     * Useful for dynamic workflows or configuration updates based on user input.
+     *
+     * @param stepId - ID of the step to update
+     * @param updates - Partial step configuration updates
+     * @returns The flow instance for method chaining
+     * @throws Error if step with given ID is not found
+     *
+     * @example
+     * ```typescript
+     * workflow.updateStep('step-1', {
+     *   title: 'Updated Title',
+     *   allowSkip: true
+     * });
+     * ```
      */
     updateStep(stepId: string, updates: Partial<Omit<StepConfig, 'id'>>): this;
+    /**
+     * Remove a step from the workflow
+     *
+     * @param stepId - ID of the step to remove
+     * @returns The flow instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * workflow.removeStep('optional-step');
+     * ```
+     */
     removeStep(stepId: string): this;
+    /**
+     * Get a specific step by ID
+     *
+     * @param stepId - ID of the step to retrieve
+     * @returns The step configuration or undefined if not found
+     *
+     * @example
+     * ```typescript
+     * const step = workflow.getStep('user-details');
+     * if (step) {
+     *   console.log(step.title);
+     * }
+     * ```
+     */
     getStep(stepId: string): StepConfig | undefined;
+    /**
+     * Get all steps in the workflow
+     *
+     * Returns a copy of the steps array to prevent external modification.
+     *
+     * @returns Array of all step configurations
+     *
+     * @example
+     * ```typescript
+     * const allSteps = workflow.getSteps();
+     * console.log(`Workflow has ${allSteps.length} steps`);
+     * ```
+     */
     getSteps(): StepConfig[];
+    /**
+     * Clear all steps from the workflow
+     *
+     * Removes all steps and resets the ID generator. Useful for rebuilding
+     * workflows or creating templates.
+     *
+     * @returns The flow instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * workflow.clearSteps()
+     *         .addStep(newStep1)
+     *         .addStep(newStep2);
+     * ```
+     */
     clearSteps(): this;
     /**
      * Clone the workflow builder
+     *
+     * Creates a deep copy of the workflow builder with optional new ID and name.
+     * All configuration, steps, and plugins are copied to the new instance.
+     *
+     * @param newWorkflowId - Optional new workflow ID
+     * @param newWorkflowName - Optional new workflow name
+     * @returns A new flow instance with copied configuration
+     *
+     * @example
+     * ```typescript
+     * const template = workflow.clone('new-workflow', 'New Workflow');
+     * template.addStep(additionalStep);
+     * ```
      */
     clone(newWorkflowId?: string, newWorkflowName?: string): flow;
     /**
-     * Validate the workflow configuration
+     * Enhanced validation using shared utilities
+     *
+     * Performs comprehensive validation of the workflow configuration,
+     * checking for common issues like missing steps, duplicate IDs,
+     * and plugin dependency problems.
+     *
+     * @returns Array of validation error messages (empty if valid)
+     *
+     * @example
+     * ```typescript
+     * const errors = workflow.validate();
+     * if (errors.length > 0) {
+     *   console.error('Validation errors:', errors);
+     * }
+     * ```
      */
     validate(): string[];
     /**
-     * Get workflow statistics
+     * Get comprehensive workflow statistics
+     *
+     * Provides detailed analytics about the workflow structure and configuration.
+     * Useful for monitoring, optimization, and reporting purposes.
+     *
+     * @returns Object containing various workflow statistics
+     *
+     * @example
+     * ```typescript
+     * const stats = workflow.getStats();
+     * console.log(`Workflow has ${stats.totalSteps} steps`);
+     * console.log(`Estimated ${stats.estimatedFields} total fields`);
+     * ```
      */
     getStats(): {
+        /** Total number of steps in the workflow */
         totalSteps: number;
+        /** Number of dynamic steps */
         dynamicSteps: number;
+        /** Number of installed plugins */
         pluginsInstalled: number;
+        /** Estimated total number of form fields across all steps */
         estimatedFields: number;
+        /** Whether persistence is configured */
         hasPersistence: boolean;
+        /** Whether analytics is configured */
         hasAnalytics: boolean;
+        /** Whether back navigation is allowed */
         allowBackNavigation: boolean;
     };
     /**
      * Build the final workflow configuration
+     *
+     * Validates the workflow and creates the final configuration object
+     * that can be used by the workflow runtime. This method should be
+     * called after all configuration is complete.
+     *
+     * @returns Complete workflow configuration
+     * @throws Error if validation fails
+     *
+     * @example
+     * ```typescript
+     * try {
+     *   const workflowConfig = workflow.build();
+     *   // Use workflowConfig with workflow runtime
+     * } catch (error) {
+     *   console.error('Workflow build failed:', error.message);
+     * }
+     * ```
      */
     build(): WorkflowConfig;
     /**
-     * Export/Import functionality
+     * Export workflow configuration to JSON
+     *
+     * Serializes the workflow configuration to a JSON-compatible object.
+     * Useful for saving workflows, creating templates, or transferring
+     * configurations between systems.
+     *
+     * @returns JSON-serializable workflow configuration
+     *
+     * @example
+     * ```typescript
+     * const json = workflow.toJSON();
+     * localStorage.setItem('workflow-template', JSON.stringify(json));
+     * ```
      */
     toJSON(): any;
+    /**
+     * Import workflow configuration from JSON
+     *
+     * Loads workflow configuration from a JSON object. This method
+     * performs partial updates, only modifying properties that are
+     * present in the JSON object.
+     *
+     * @param json - JSON object containing workflow configuration
+     * @returns The flow instance for method chaining
+     *
+     * @example
+     * ```typescript
+     * const json = JSON.parse(localStorage.getItem('workflow-template'));
+     * workflow.fromJSON(json);
+     * ```
+     */
     fromJSON(json: any): this;
 }
 /**
  * Factory function to create a workflow builder directly
+ *
+ * This is a convenience function that provides an alternative to using
+ * the class constructor or static create method. It's particularly useful
+ * for functional programming styles or when you prefer function calls
+ * over class instantiation.
+ *
+ * @param config - The ril configuration instance
+ * @param workflowId - Unique identifier for the workflow
+ * @param workflowName - Display name for the workflow
+ * @param description - Optional description of the workflow purpose
+ * @returns A new flow builder instance
+ *
+ * @example
+ * ```typescript
+ * const workflow = createFlow(rilConfig, 'onboarding', 'User Onboarding');
+ * ```
  */
 declare function createFlow(config: ril, workflowId: string, workflowName: string, description?: string): flow;
+/**
+ * Module augmentation to add createFlow method to ril instances
+ *
+ * This declaration extends the ril interface to include the createFlow
+ * method, allowing for a more integrated API experience where workflows
+ * can be created directly from ril configuration instances.
+ */
 declare module '@rilaykit/core' {
     interface ril {
-        createFlow(workflowId: string, workflowName: string, description?: string): flow;
+        /**
+         * Creates a new workflow builder using this ril configuration
+         *
+         * @param workflowId - Unique identifier for the workflow
+         * @param workflowName - Display name for the workflow
+         * @param description - Optional description of the workflow purpose
+         * @returns A new flow builder instance
+         *
+         * @example
+         * ```typescript
+         * const workflow = rilConfig.createFlow('checkout', 'Checkout Process');
+         * ```
+         */
+        flow(workflowId: string, workflowName: string, description?: string): flow;
     }
 }
 
@@ -276,93 +704,4 @@ declare class RilayLicenseManager {
     }>;
 }
 
-interface AnalyticsPluginConfig {
-    providers: {
-        googleAnalytics?: {
-            trackingId: string;
-            customDimensions?: Record<string, string>;
-        };
-        mixpanel?: {
-            token: string;
-            options?: any;
-        };
-        amplitude?: {
-            apiKey: string;
-            options?: any;
-        };
-        custom?: {
-            endpoint: string;
-            headers?: Record<string, string>;
-        };
-    };
-    eventMapping?: {
-        workflowStart?: string;
-        workflowComplete?: string;
-        stepStart?: string;
-        stepComplete?: string;
-        stepSkip?: string;
-        validationError?: string;
-    };
-    includeUserContext?: boolean;
-    includeFormData?: boolean;
-    enablePerformanceTracking?: boolean;
-}
-declare class AnalyticsPlugin implements WorkflowPlugin {
-    name: string;
-    version: string;
-    private config;
-    private performanceData;
-    constructor(config: AnalyticsPluginConfig);
-    install(workflowBuilder: any): void;
-    private track;
-    private trackGoogleAnalytics;
-    private trackMixpanel;
-    private trackAmplitude;
-    private trackCustom;
-    private getContextData;
-    private calculateCompletionPercentage;
-}
-
-interface ValidationPluginConfig {
-    schema?: {
-        type: 'zod' | 'yup' | 'custom';
-        schema?: any;
-    };
-    rules: {
-        required?: string[];
-        email?: string[];
-        phone?: string[];
-        minLength?: Record<string, number>;
-        maxLength?: Record<string, number>;
-        pattern?: Record<string, RegExp>;
-        custom?: Record<string, (value: any, context: WorkflowContext) => ValidationResult | Promise<ValidationResult>>;
-    };
-    crossFieldValidation?: Array<{
-        fields: string[];
-        validator: (values: Record<string, any>, context: WorkflowContext) => ValidationResult | Promise<ValidationResult>;
-        message: string;
-    }>;
-    asyncRules?: Record<string, {
-        url: string;
-        debounceMs?: number;
-        method?: 'GET' | 'POST';
-        headers?: Record<string, string>;
-    }>;
-    onValidationComplete?: (result: ValidationResult, context: WorkflowContext) => void;
-}
-declare class ValidationPlugin implements WorkflowPlugin {
-    name: string;
-    version: string;
-    dependencies: never[];
-    private config;
-    private debounceTimers;
-    constructor(config: ValidationPluginConfig);
-    install(workflowBuilder: any): void;
-    private validateStep;
-    private validateWithSchema;
-    private validateWithRules;
-    private validateCrossField;
-    private validateAsync;
-}
-
-export { AnalyticsPlugin, type LicensePayload, type LicensePlan, type LicenseResult, RilayLicenseManager, type StepDefinition, ValidationPlugin, Workflow, WorkflowBody, type WorkflowContextValue, WorkflowNextButton, type WorkflowNextButtonProps, WorkflowPreviousButton, type WorkflowPreviousButtonProps, WorkflowProvider, type WorkflowProviderProps, WorkflowSkipButton, type WorkflowSkipButtonProps, WorkflowStepper, type WorkflowStepperProps, createFlow, flow, useWorkflowContext };
+export { type LicensePayload, type LicensePlan, type LicenseResult, RilayLicenseManager, type StepDefinition, Workflow, WorkflowBody, type WorkflowContextValue, WorkflowNextButton, type WorkflowNextButtonProps, WorkflowPreviousButton, type WorkflowPreviousButtonProps, WorkflowProvider, type WorkflowProviderProps, WorkflowSkipButton, type WorkflowSkipButtonProps, WorkflowStepper, type WorkflowStepperProps, createFlow, flow, useWorkflowContext };