@rilaykit/workflow 5.2.1 → 6.0.0

package/dist/index.d.mts

@@ -1,9 +1,9 @@
-import { ril, FormConfiguration, CustomStepRenderer, StepDataHelper, WorkflowContext, WorkflowAnalytics, WorkflowPlugin, StepConfig, WorkflowConfig, ComponentRendererBaseProps, WorkflowNextButtonRendererProps, WorkflowPreviousButtonRendererProps, WorkflowSkipButtonRendererProps, WorkflowStepperRendererProps } from '@rilaykit/core';
+import { ril, FormConfiguration, CustomStepRenderer, StepConditionalBehavior, StepDataHelper, WorkflowContext, WorkflowAnalytics, WorkflowPlugin, StepConfig, WorkflowConfig, ConditionalBehavior, ComponentRendererBaseProps, WorkflowNextButtonRendererProps, WorkflowPreviousButtonRendererProps, WorkflowSkipButtonRendererProps, WorkflowStepperRendererProps } from '@rilaykit/core';
 export * from '@rilaykit/core';
 import { form } from '@rilaykit/forms';
 export { form } from '@rilaykit/forms';
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import React from 'react';
+import React$1 from 'react';
 
 /**
  * Enhanced step configuration interface for better type safety and simplicity
@@ -50,6 +50,11 @@ interface StepDefinition {
      * Allows complete customization of step presentation
      */
     renderer?: CustomStepRenderer;
+    /**
+     * Conditional behavior configuration for this step
+     * Controls visibility and skippable state
+     */
+    conditions?: StepConditionalBehavior;
     /**
      * Callback function that executes after successful validation and before moving to next step
      * Provides clean helper methods for modifying workflow data and pre-filling subsequent steps
@@ -300,6 +305,26 @@ declare class flow {
      * ```
      */
     updateStep(stepId: string, updates: Partial<Omit<StepConfig, 'id'>>): this;
+    /**
+     * Adds conditions to a specific step by ID
+     *
+     * This method allows adding conditional behavior to a step after it has been created,
+     * useful for dynamic conditional requirements.
+     *
+     * @param stepId - The ID of the step to add conditions to
+     * @param conditions - Conditional behavior configuration
+     * @returns The flow instance for method chaining
+     * @throws Error if the step with the specified ID is not found
+     *
+     * @example
+     * ```typescript
+     * workflow.addStepConditions('payment-step', {
+     *   visible: when('hasPayment').equals(true).build(),
+     *   skippable: when('balance').equals(0).build()
+     * });
+     * ```
+     */
+    addStepConditions(stepId: string, conditions: StepConditionalBehavior): this;
     /**
      * Remove a step from the workflow
      *
@@ -516,6 +541,163 @@ declare module '@rilaykit/core' {
     }
 }
 
+interface ConditionEvaluationResult {
+    visible: boolean;
+    disabled: boolean;
+    required: boolean;
+    readonly: boolean;
+}
+/**
+ * Hook to evaluate conditional behaviors based on workflow data
+ *
+ * @param conditions - The conditional behavior configuration
+ * @param workflowData - Current workflow data to evaluate against
+ * @param defaultState - Default state when no conditions are provided
+ * @returns Evaluated condition results
+ */
+declare function useConditionEvaluation(conditions?: ConditionalBehavior, workflowData?: Record<string, any>, defaultState?: Partial<ConditionEvaluationResult>): ConditionEvaluationResult;
+/**
+ * Hook to evaluate multiple field conditions at once
+ *
+ * @param fieldsWithConditions - Map of field IDs to their conditional behaviors
+ * @param workflowData - Current workflow data to evaluate against
+ * @returns Map of field IDs to their evaluated conditions
+ */
+declare function useMultipleConditionEvaluation(fieldsWithConditions: Record<string, ConditionalBehavior | undefined>, workflowData?: Record<string, any>): Record<string, ConditionEvaluationResult>;
+/**
+ * Hook to evaluate multiple step conditions at once using numeric indices
+ *
+ * @param stepsWithConditions - Map of step indices to their conditional behaviors
+ * @param workflowData - Current workflow data to evaluate against
+ * @returns Map of step indices to their evaluated conditions
+ */
+declare function useMultipleStepConditionEvaluation(stepsWithConditions: Record<number, ConditionalBehavior | undefined>, workflowData?: Record<string, any>): Record<number, ConditionEvaluationResult>;
+
+/**
+ * @fileoverview Persistence system types for Rilay workflows
+ *
+ * This module defines the core interfaces and types for the workflow persistence system.
+ * It provides a flexible adapter pattern allowing different persistence strategies:
+ * - localStorage persistence
+ * - API-based persistence
+ * - Custom persistence implementations
+ *
+ * The system is designed to be type-safe and extensible while maintaining
+ * a simple API for common use cases.
+ */
+
+/**
+ * Persistent workflow data that gets saved/loaded
+ */
+interface PersistedWorkflowData {
+    /** Unique identifier for the workflow */
+    workflowId: string;
+    /** Current step index in the workflow */
+    currentStepIndex: number;
+    /** All collected data across steps */
+    allData: Record<string, any>;
+    /** Currently active step data */
+    stepData: Record<string, any>;
+    /** Set of visited step IDs */
+    visitedSteps: string[];
+    /** When this data was last saved */
+    lastSaved: number;
+    /** Optional metadata for custom persistence needs */
+    metadata?: Record<string, any>;
+}
+/**
+ * Options for persistence operations
+ */
+interface PersistenceOptions {
+    /** Whether to automatically persist on state changes */
+    autoPersist?: boolean;
+    /** Debounce delay in ms for auto-persistence (default: 500ms) */
+    debounceMs?: number;
+    /** Custom key for storage (overrides default) */
+    storageKey?: string;
+    /** Additional metadata to include in persisted data */
+    metadata?: Record<string, any>;
+}
+/**
+ * Core persistence adapter interface
+ *
+ * All persistence implementations must implement this interface.
+ * It provides a consistent API regardless of the underlying storage mechanism.
+ */
+interface WorkflowPersistenceAdapter {
+    /**
+     * Save workflow data
+     * @param key - Unique identifier for the stored data
+     * @param data - Workflow data to persist
+     * @returns Promise that resolves when save is complete
+     */
+    save(key: string, data: PersistedWorkflowData): Promise<void>;
+    /**
+     * Load workflow data
+     * @param key - Unique identifier for the stored data
+     * @returns Promise that resolves to persisted data or null if not found
+     */
+    load(key: string): Promise<PersistedWorkflowData | null>;
+    /**
+     * Remove persisted workflow data
+     * @param key - Unique identifier for the stored data
+     * @returns Promise that resolves when deletion is complete
+     */
+    remove(key: string): Promise<void>;
+    /**
+     * Check if data exists for the given key
+     * @param key - Unique identifier to check
+     * @returns Promise that resolves to true if data exists
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * List all available keys (optional, for debugging/admin)
+     * @returns Promise that resolves to array of available keys
+     */
+    listKeys?(): Promise<string[]>;
+    /**
+     * Clear all persisted data (optional, for cleanup)
+     * @returns Promise that resolves when all data is cleared
+     */
+    clear?(): Promise<void>;
+}
+/**
+ * Configuration for localStorage persistence adapter
+ */
+interface LocalStorageAdapterConfig {
+    /** Prefix for localStorage keys (default: 'rilay_workflow_') */
+    keyPrefix?: string;
+    /** Whether to compress data before storage */
+    compress?: boolean;
+    /** Maximum age in ms before data expires (optional) */
+    maxAge?: number;
+}
+/**
+ * Error types for persistence operations
+ */
+declare class WorkflowPersistenceError extends Error {
+    readonly code: string;
+    readonly cause?: Error | undefined;
+    constructor(message: string, code: string, cause?: Error | undefined);
+}
+/**
+ * Persistence hook return type
+ */
+interface UsePersistenceReturn {
+    /** Whether persistence is currently saving */
+    isPersisting: boolean;
+    /** Last persistence error (if any) */
+    persistenceError: WorkflowPersistenceError | null;
+    /** Manually trigger a save operation */
+    persistNow: () => Promise<void>;
+    /** Load data from persistence */
+    loadPersistedData: () => Promise<PersistedWorkflowData | null>;
+    /** Clear persisted data */
+    clearPersistedData: () => Promise<void>;
+    /** Whether persisted data exists */
+    hasPersistedData: () => Promise<boolean>;
+}
+
 interface WorkflowState {
     currentStepIndex: number;
     allData: Record<string, any>;
@@ -524,23 +706,175 @@ interface WorkflowState {
     isSubmitting: boolean;
     isTransitioning: boolean;
 }
-interface WorkflowContextValue {
+type WorkflowAction = {
+    type: 'SET_CURRENT_STEP';
+    stepIndex: number;
+} | {
+    type: 'SET_STEP_DATA';
+    data: Record<string, any>;
+    stepId: string;
+} | {
+    type: 'SET_ALL_DATA';
+    data: Record<string, any>;
+} | {
+    type: 'SET_FIELD_VALUE';
+    fieldId: string;
+    value: any;
+    stepId: string;
+} | {
+    type: 'SET_SUBMITTING';
+    isSubmitting: boolean;
+} | {
+    type: 'SET_TRANSITIONING';
+    isTransitioning: boolean;
+} | {
+    type: 'MARK_STEP_VISITED';
+    stepIndex: number;
+    stepId: string;
+} | {
+    type: 'RESET_WORKFLOW';
+} | {
+    type: 'LOAD_PERSISTED_STATE';
+    state: Partial<WorkflowState>;
+};
+interface UseWorkflowStateProps {
+    defaultValues?: Record<string, any>;
+    persistence?: {
+        workflowId: string;
+        adapter?: WorkflowPersistenceAdapter;
+        options?: PersistenceOptions;
+        userId?: string;
+        autoLoad?: boolean;
+    };
+}
+declare function useWorkflowState({ defaultValues, persistence }: UseWorkflowStateProps): {
     workflowState: WorkflowState;
+    setCurrentStep: (stepIndex: number) => void;
+    setStepData: (data: Record<string, any>, stepId: string) => void;
+    setFieldValue: (fieldId: string, value: any, stepId: string) => void;
+    setSubmitting: (isSubmitting: boolean) => void;
+    setTransitioning: (isTransitioning: boolean) => void;
+    markStepVisited: (stepIndex: number, stepId: string) => void;
+    resetWorkflow: () => void;
+    loadPersistedState: () => Promise<boolean>;
+    persistence: {
+        isPersisting: boolean;
+        persistenceError: WorkflowPersistenceError | null;
+        persistNow: () => Promise<void>;
+        clearPersistedData: () => Promise<void>;
+        hasPersistedData: () => Promise<boolean>;
+    } | null;
+};
+
+interface UseWorkflowAnalyticsProps {
+    workflowConfig: WorkflowConfig;
+    workflowState: WorkflowState;
+    workflowContext: WorkflowContext;
+}
+interface UseWorkflowAnalyticsReturn {
+    analyticsStartTime: React.MutableRefObject<number>;
+    trackStepSkip: (stepId: string, reason: string) => void;
+    trackError: (error: Error) => void;
+}
+declare function useWorkflowAnalytics({ workflowConfig, workflowState, workflowContext, }: UseWorkflowAnalyticsProps): UseWorkflowAnalyticsReturn;
+
+interface UseWorkflowConditionsProps {
+    workflowConfig: WorkflowConfig;
+    workflowState: WorkflowState;
+    currentStep: StepConfig;
+}
+/**
+ * Result of step condition evaluation - only relevant properties for workflow steps
+ */
+interface StepConditionResult {
+    visible: boolean;
+    skippable: boolean;
+}
+interface UseWorkflowConditionsReturn {
+    stepConditions: StepConditionResult;
+    fieldConditions: Record<string, ConditionEvaluationResult>;
+    allStepConditions: Record<number, StepConditionResult>;
+    isStepVisible: (stepIndex: number) => boolean;
+    isStepSkippable: (stepIndex: number) => boolean;
+    isFieldVisible: (fieldId: string) => boolean;
+    isFieldDisabled: (fieldId: string) => boolean;
+    isFieldRequired: (fieldId: string) => boolean;
+    isFieldReadonly: (fieldId: string) => boolean;
+}
+/**
+ * Hook to manage conditional behaviors for workflow steps and fields
+ *
+ * This hook evaluates conditions for steps and form fields within a workflow,
+ * providing convenient methods to check step and field states based on conditions.
+ *
+ * Steps have different condition types than fields:
+ * - Steps: visible, skippable
+ * - Fields: visible, disabled, required, readonly
+ */
+declare function useWorkflowConditions({ workflowConfig, workflowState, currentStep, }: UseWorkflowConditionsProps): UseWorkflowConditionsReturn;
+
+interface UseWorkflowNavigationProps {
+    workflowConfig: WorkflowConfig;
+    workflowState: WorkflowState;
+    workflowContext: WorkflowContext;
+    conditionsHelpers: UseWorkflowConditionsReturn;
+    setCurrentStep: (stepIndex: number) => void;
+    setTransitioning: (isTransitioning: boolean) => void;
+    markStepVisited: (stepIndex: number, stepId: string) => void;
+    setStepData: (data: Record<string, any>, stepId: string) => void;
+    onStepChange?: (fromStep: number, toStep: number, context: WorkflowContext) => void;
+}
+interface UseWorkflowNavigationReturn {
+    goToStep: (stepIndex: number) => Promise<boolean>;
+    goNext: () => Promise<boolean>;
+    goPrevious: () => Promise<boolean>;
+    skipStep: () => Promise<boolean>;
+    canGoToStep: (stepIndex: number) => boolean;
+    canGoNext: () => boolean;
+    canGoPrevious: () => boolean;
+    canSkipCurrentStep: () => boolean;
+}
+declare function useWorkflowNavigation({ workflowConfig, workflowState, workflowContext, conditionsHelpers, setCurrentStep, setTransitioning, markStepVisited, setStepData, onStepChange, }: UseWorkflowNavigationProps): UseWorkflowNavigationReturn;
+
+interface UseWorkflowSubmissionProps {
+    workflowConfig: WorkflowConfig;
+    workflowState: WorkflowState;
+    workflowContext: WorkflowContext;
+    setSubmitting: (isSubmitting: boolean) => void;
+    onWorkflowComplete?: (data: Record<string, any>) => void | Promise<void>;
+    analyticsStartTime: React.MutableRefObject<number>;
+}
+interface UseWorkflowSubmissionReturn {
+    submitWorkflow: () => Promise<void>;
+    isSubmitting: boolean;
+    canSubmit: boolean;
+}
+declare function useWorkflowSubmission({ workflowConfig, workflowState, workflowContext, setSubmitting, onWorkflowComplete, analyticsStartTime, }: UseWorkflowSubmissionProps): UseWorkflowSubmissionReturn;
+
+interface WorkflowContextValue {
+    workflowState: ReturnType<typeof useWorkflowState>['workflowState'];
     workflowConfig: WorkflowConfig;
     currentStep: StepConfig;
     context: WorkflowContext;
     formConfig?: FormConfiguration;
+    conditionsHelpers: UseWorkflowConditionsReturn;
     goToStep: (stepIndex: number) => Promise<boolean>;
     goNext: () => Promise<boolean>;
     goPrevious: () => Promise<boolean>;
     skipStep: () => Promise<boolean>;
+    canGoToStep: (stepIndex: number) => boolean;
+    canGoNext: () => boolean;
+    canGoPrevious: () => boolean;
+    canSkipCurrentStep: () => boolean;
     setValue: (fieldId: string, value: any) => void;
     setStepData: (data: Record<string, any>) => void;
-    submitWorkflow: () => Promise<void>;
     resetWorkflow: () => void;
+    submitWorkflow: () => Promise<void>;
+    isSubmitting: boolean;
+    canSubmit: boolean;
 }
 interface WorkflowProviderProps {
-    children: React.ReactNode;
+    children: React$1.ReactNode;
     workflowConfig: WorkflowConfig;
     defaultValues?: Record<string, any>;
     onStepChange?: (fromStep: number, toStep: number, context: WorkflowContext) => void;
@@ -551,7 +885,7 @@ declare function WorkflowProvider({ children, workflowConfig, defaultValues, onS
 declare function useWorkflowContext(): WorkflowContextValue;
 
 type WorkflowProps = Omit<WorkflowProviderProps, 'children' | 'workflowConfig'> & {
-    children: React.ReactNode;
+    children: React$1.ReactNode;
     workflowConfig: WorkflowConfig | flow;
 };
 /**
@@ -579,6 +913,169 @@ interface WorkflowStepperProps extends ComponentRendererBaseProps<WorkflowSteppe
 }
 declare function WorkflowStepper({ onStepClick, className, ...props }: WorkflowStepperProps): react_jsx_runtime.JSX.Element;
 
+/**
+ * @fileoverview LocalStorage persistence adapter for Rilay workflows
+ *
+ * This adapter provides browser localStorage-based persistence for workflow data.
+ * It includes features like data compression, expiration handling, and error recovery.
+ *
+ * Key features:
+ * - Automatic data expiration based on maxAge
+ * - Optional data compression for large workflows
+ * - Graceful handling of localStorage quota exceeded
+ * - Type-safe serialization/deserialization
+ */
+
+/**
+ * LocalStorage-based persistence adapter
+ *
+ * Provides a robust localStorage implementation with features like:
+ * - Automatic cleanup of expired data
+ * - Configurable key prefixes for namespace isolation
+ * - Error handling for quota exceeded scenarios
+ * - Optional data compression
+ *
+ * @example
+ * ```typescript
+ * const adapter = new LocalStorageAdapter({
+ *   keyPrefix: 'myapp_workflow_',
+ *   maxAge: 24 * 60 * 60 * 1000, // 24 hours
+ *   compress: true
+ * });
+ * ```
+ */
+declare class LocalStorageAdapter implements WorkflowPersistenceAdapter {
+    private readonly keyPrefix;
+    private readonly compress;
+    private readonly maxAge?;
+    private readonly version;
+    constructor(config?: LocalStorageAdapterConfig);
+    /**
+     * Save workflow data to localStorage
+     */
+    save(key: string, data: PersistedWorkflowData): Promise<void>;
+    /**
+     * Load workflow data from localStorage
+     */
+    load(key: string): Promise<PersistedWorkflowData | null>;
+    /**
+     * Remove workflow data from localStorage
+     */
+    remove(key: string): Promise<void>;
+    /**
+     * Check if data exists for the given key
+     */
+    exists(key: string): Promise<boolean>;
+    /**
+     * List all available keys
+     */
+    listKeys(): Promise<string[]>;
+    /**
+     * Clear all workflow data
+     */
+    clear(): Promise<void>;
+    /**
+     * Get the full storage key with prefix
+     */
+    private getStorageKey;
+    /**
+     * Check if localStorage is available
+     */
+    private isLocalStorageAvailable;
+    /**
+     * Simple data compression using basic string compression
+     * Note: In production, you might want to use a proper compression library
+     */
+    private compressData;
+    /**
+     * Decompress data
+     */
+    private decompressData;
+    /**
+     * Clear expired data entries
+     */
+    private clearExpiredData;
+}
+
+/**
+ * @fileoverview Persistence utilities for Rilay workflows
+ *
+ * This module provides utility functions for working with workflow persistence,
+ * including data transformation, validation, and helper functions for
+ * converting between different data formats.
+ */
+
+/**
+ * Convert WorkflowState to PersistedWorkflowData format
+ */
+declare function workflowStateToPersisted(workflowId: string, state: WorkflowState, metadata?: Record<string, any>): PersistedWorkflowData;
+/**
+ * Convert PersistedWorkflowData to WorkflowState format
+ */
+declare function persistedToWorkflowState(data: PersistedWorkflowData): Partial<WorkflowState>;
+/**
+ * Validate persisted workflow data structure
+ */
+declare function validatePersistedData(data: any): data is PersistedWorkflowData;
+/**
+ * Generate a storage key for a workflow
+ */
+declare function generateStorageKey(workflowId: string, userId?: string): string;
+/**
+ * Debounce function for auto-persistence
+ */
+declare function debounce<T extends (...args: any[]) => any>(func: T, wait: number): (...args: Parameters<T>) => void;
+/**
+ * Merge persisted data with current state, handling conflicts
+ */
+declare function mergePersistedState(currentState: WorkflowState, persistedData: PersistedWorkflowData, strategy?: 'persist' | 'current' | 'merge'): Partial<WorkflowState>;
+
+/**
+ * @fileoverview Persistence hook for Rilay workflows
+ *
+ * This hook provides workflow persistence functionality with automatic
+ * debounced saving, error handling, and flexible adapter support.
+ * It integrates seamlessly with the existing workflow state management.
+ */
+
+interface UsePersistenceProps {
+    /** Unique workflow identifier */
+    workflowId: string;
+    /** Current workflow state */
+    workflowState: WorkflowState;
+    /** Persistence adapter to use */
+    adapter: WorkflowPersistenceAdapter;
+    /** Persistence options */
+    options?: PersistenceOptions;
+    /** Optional user ID for multi-user scenarios */
+    userId?: string;
+}
+/**
+ * Hook for managing workflow persistence
+ *
+ * Provides automatic persistence with debouncing, manual save/load operations,
+ * and comprehensive error handling. Integrates with any persistence adapter
+ * that implements the WorkflowPersistenceAdapter interface.
+ *
+ * @example
+ * ```typescript
+ * const persistence = usePersistence({
+ *   workflowId: 'user-onboarding',
+ *   workflowState,
+ *   adapter: new LocalStorageAdapter(),
+ *   options: {
+ *     autoPersist: true,
+ *     debounceMs: 1000
+ *   }
+ * });
+ *
+ * if (persistence.persistenceError) {
+ *   console.error('Persistence error:', persistence.persistenceError);
+ * }
+ * ```
+ */
+declare function usePersistence({ workflowId, workflowState, adapter, options, userId, }: UsePersistenceProps): UsePersistenceReturn;
+
 interface LicensePayload {
     plan: 'ARCHITECT' | 'FOUNDRY';
     company: string;
@@ -647,4 +1144,4 @@ declare class RilayLicenseManager {
     }>;
 }
 
-export { type LicensePayload, type LicensePlan, type LicenseResult, RilayLicenseManager, type StepDefinition, Workflow, WorkflowBody, type WorkflowContextValue, WorkflowNextButton, WorkflowPreviousButton, WorkflowProvider, WorkflowSkipButton, WorkflowStepper, createFlow, flow, useWorkflowContext };
+export { type ConditionEvaluationResult, type LicensePayload, type LicensePlan, type LicenseResult, LocalStorageAdapter, type LocalStorageAdapterConfig, type PersistedWorkflowData, type PersistenceOptions, RilayLicenseManager, type StepConditionResult, type StepDefinition, type UsePersistenceProps, type UsePersistenceReturn, type UseWorkflowAnalyticsProps, type UseWorkflowAnalyticsReturn, type UseWorkflowConditionsProps, type UseWorkflowConditionsReturn, type UseWorkflowNavigationProps, type UseWorkflowNavigationReturn, type UseWorkflowStateProps, type UseWorkflowSubmissionProps, type UseWorkflowSubmissionReturn, Workflow, type WorkflowAction, WorkflowBody, type WorkflowContextValue, WorkflowNextButton, type WorkflowPersistenceAdapter, WorkflowPersistenceError, WorkflowPreviousButton, WorkflowProvider, WorkflowSkipButton, type WorkflowState, WorkflowStepper, createFlow, debounce, flow, generateStorageKey, mergePersistedState, persistedToWorkflowState, useConditionEvaluation, useMultipleConditionEvaluation, useMultipleStepConditionEvaluation, usePersistence, useWorkflowAnalytics, useWorkflowConditions, useWorkflowContext, useWorkflowNavigation, useWorkflowState, useWorkflowSubmission, validatePersistedData, workflowStateToPersisted };