@rilaykit/workflow 7.1.0 → 7.2.0

package/dist/index.d.ts

@@ -5,6 +5,202 @@ export { form } from '@rilaykit/forms';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React$1 from 'react';
 
+interface WorkflowState {
+    currentStepIndex: number;
+    allData: Record<string, any>;
+    stepData: Record<string, any>;
+    visitedSteps: Set<string>;
+    isSubmitting: boolean;
+    isTransitioning: boolean;
+    isInitializing: boolean;
+}
+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>;
+} | {
+    type: 'SET_INITIALIZATION_COMPLETE';
+};
+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;
+};
+
+/**
+ * @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>;
+}
+
 /**
  * Enhanced step configuration interface for better type safety and simplicity
  *
@@ -97,6 +293,12 @@ interface StepDefinition {
 interface WorkflowOptions {
     /** Analytics and tracking configuration */
     analytics?: WorkflowAnalytics;
+    /** Persistence configuration */
+    persistence?: {
+        adapter: WorkflowPersistenceAdapter;
+        options?: PersistenceOptions;
+        userId?: string;
+    };
 }
 /**
  * Workflow builder class for creating complex multi-step workflows
@@ -141,6 +343,7 @@ declare class flow {
     private workflowDescription?;
     private steps;
     private analytics?;
+    private persistenceConfig?;
     private plugins;
     private idGenerator;
     /**
@@ -231,17 +434,14 @@ declare class flow {
      * @example
      * ```typescript
      * workflow.configure({
-     *   navigation: {
-     *     allowBackNavigation: true,
-     *     showProgressBar: true
-     *   },
-     *   persistence: {
-     *     saveOnStepComplete: true,
-     *     storageKey: 'my-workflow'
-     *   },
      *   analytics: {
      *     trackStepCompletion: true,
      *     trackFieldInteractions: false
+     *   },
+     *   persistence: {
+     *     adapter: new LocalStorageAdapter(),
+     *     options: { autoPersist: true, debounceMs: 1000 },
+     *     userId: 'user123'
      *   }
      * });
      * ```
@@ -574,197 +774,50 @@ declare function useMultipleConditionEvaluation(fieldsWithConditions: Record<str
 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
+ * @fileoverview Persistence hook for Rilay workflows
  *
- * The system is designed to be type-safe and extensible while maintaining
- * a simple API for common use cases.
+ * 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.
  */
 
-/**
- * Persistent workflow data that gets saved/loaded
- */
-interface PersistedWorkflowData {
-    /** Unique identifier for the workflow */
+interface UsePersistenceProps {
+    /** Unique workflow identifier */
     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>;
+    /** Current workflow state */
+    workflowState: WorkflowState;
+    /** Persistence adapter to use */
+    adapter: WorkflowPersistenceAdapter;
+    /** Persistence options */
+    options?: PersistenceOptions;
+    /** Optional user ID for multi-user scenarios */
+    userId?: string;
 }
 /**
- * Core persistence adapter interface
+ * Hook for managing workflow persistence
  *
- * 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
+ * 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);
+ * }
+ * ```
  */
-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>;
-    stepData: Record<string, any>;
-    visitedSteps: Set<string>;
-    isSubmitting: boolean;
-    isTransitioning: boolean;
-}
-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;
-};
+declare function usePersistence({ workflowId, workflowState, adapter, options, userId, }: UsePersistenceProps): UsePersistenceReturn;
 
 interface UseWorkflowAnalyticsProps {
     workflowConfig: WorkflowConfig;
@@ -872,6 +925,9 @@ interface WorkflowContextValue {
     submitWorkflow: () => Promise<void>;
     isSubmitting: boolean;
     canSubmit: boolean;
+    persistNow?: () => Promise<void>;
+    isPersisting?: boolean;
+    persistenceError?: Error | null;
 }
 interface WorkflowProviderProps {
     children: React$1.ReactNode;
@@ -1031,52 +1087,6 @@ declare function debounce<T extends (...args: any[]) => any>(func: T, wait: numb
  */
 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;