wizzard-stepper-react 1.7.1 → 2.0.0

package/dist/index.d.cts

@@ -1,6 +1,70 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React$1 from 'react';
 
+interface IWizardHandle<T = unknown, StepId extends string = string> {
+    state: IWizardState<T, StepId>;
+    actions: IWizardActions<StepId>;
+}
+interface IWizardState<T = unknown, StepId extends string = string> {
+    data: T;
+    errors: Record<string, Record<string, string>>;
+    currentStep: IStepConfig<T, StepId> | null;
+    currentStepIndex: number;
+    isFirstStep: boolean;
+    isLastStep: boolean;
+    isLoading: boolean;
+    isPending: boolean;
+    activeSteps: IStepConfig<T, StepId>[];
+    currentStepId: StepId | "";
+    history: StepId[];
+    busySteps: Set<StepId>;
+    visitedSteps: Set<StepId>;
+    completedSteps: Set<StepId>;
+    errorSteps: Set<StepId>;
+    config: IWizardConfig<T, StepId>;
+    progress: number;
+    activeStepsCount: number;
+    isBusy: boolean;
+    isDirty: boolean;
+    dirtyFields: Set<string>;
+    breadcrumbs: IBreadcrumb<StepId>[];
+}
+interface IWizardStore<T, StepId extends string = string> {
+    getSnapshot(): IWizardState<T, StepId>;
+    dispatch(action: WizardAction<T, StepId>): void;
+    update(newData: T, changedPath?: string | string[]): void;
+    updateMeta(newMeta: Partial<IWizardState<T, StepId>>): void;
+    setInitialData(data: T): void;
+    updateErrors(newErrors: Record<string, Record<string, string>>): void;
+    setStepErrors(stepId: string, errors: Record<string, string> | undefined | null): boolean;
+    deleteError(stepId: string, path: string): boolean;
+    subscribe(listener: () => void): () => void;
+    subscribeToActions(listener: (action: WizardAction<T, StepId>) => void): () => void;
+    errorsMap: Map<string, Map<string, string>>;
+}
+interface IWizardActions<StepId extends string = string> {
+    goToNextStep: () => Promise<void>;
+    goToPrevStep: () => void;
+    goToStep: (stepId: StepId) => Promise<boolean>;
+    setStepData: (stepId: StepId, data: unknown) => void;
+    handleStepChange: (field: string, value: unknown) => void;
+    validateStep: (sid: StepId) => Promise<boolean>;
+    validateAll: () => Promise<{
+        isValid: boolean;
+        errors: Record<string, Record<string, string>>;
+    }>;
+    save: (stepIds?: StepId | StepId[] | boolean) => void;
+    clearStorage: () => void;
+    reset: () => void;
+    setData: (path: string, value: unknown, options?: {
+        debounceValidation?: number;
+    }) => void;
+    updateData: (data: Partial<any>, options?: {
+        replace?: boolean;
+        persist?: boolean;
+    }) => void;
+    getData: (path: string, defaultValue?: unknown) => unknown;
+}
 /**
  * Validation Result Interface
  */
@@ -37,19 +101,39 @@ interface IPersistenceAdapter {
     getStep: <T>(stepId: string) => T | undefined;
     clear: () => void;
 }
+/**
+ * Step Navigation Direction
+ */
+type StepDirection = 'next' | 'prev';
 /**
  * Step Configuration
  * TStepData: Type of data for this step
  * TGlobalContext: Type of the global wizard data
  */
-interface IStepConfig<TStepData = unknown, TGlobalContext = unknown, StepId extends string = string> {
+interface IStepConfig<TStepData = unknown, StepId extends string = string> {
     id: StepId;
     label: string;
     /**
      * Predicate to determine if step should be included/visible.
-     * If returns false, step is strictly skipped.
+     * Supports both synchronous and asynchronous predicates.
      */
-    condition?: (context: TGlobalContext) => boolean;
+    condition?: (data: TStepData, metadata: Partial<IWizardState<TStepData, StepId>> & {
+        wizardData?: TStepData | undefined;
+        allErrors?: any;
+    }) => boolean | Promise<boolean>;
+    /**
+     * If true, the step will be visible while its condition is being resolved.
+     * Default: false (step is hidden until condition is resolved)
+     */
+    showWhilePending?: boolean;
+    /**
+     * Guard function called before leaving the step.
+     * Return false or throw to prevent navigation.
+     */
+    beforeLeave?: (data: TStepData, direction: StepDirection, metadata: Partial<IWizardState<TStepData, StepId>> & {
+        wizardData?: TStepData | undefined;
+        allErrors?: any;
+    }) => boolean | Promise<boolean>;
     /**
      * Adapter for validation logic
      */
@@ -82,6 +166,15 @@ interface IStepConfig<TStepData = unknown, TGlobalContext = unknown, StepId exte
      * - 'manual': Save only when manually triggered
      */
     persistenceMode?: PersistenceMode;
+    /**
+     * Dependency Tracking: Reset this step's data/status when these paths change.
+     */
+    dependsOn?: string[];
+    /**
+     * Paths to clear when dependencies change.
+     * Can be a single path string, an array of paths, or a function returning a data patch to merge.
+     */
+    clearData?: string | string[] | ((data: TStepData) => Partial<TStepData>);
 }
 /**
  * Wizard Configuration
@@ -91,7 +184,7 @@ interface IWizardConfig<T = unknown, StepId extends string = string> {
     /**
      * Array of step configurations
      */
-    steps: IStepConfig<unknown, T, StepId>[];
+    steps: IStepConfig<T, StepId>[];
     /**
      * Global auto-validation setting (default: true)
      * @deprecated Use validationMode instead
@@ -111,27 +204,194 @@ interface IWizardConfig<T = unknown, StepId extends string = string> {
          * Storage key prefix (default: 'wizard_')
          */
         storageKey?: string;
+        /**
+         * Debounce time in ms for 'onChange' persistence (default: 0)
+         */
+        debounceTime?: number;
     };
+    /**
+     * Conflict resolution strategy for persistence hydration.
+     * - 'merge': Shallow merge local and initial/server data (default)
+     * - 'replace': Overwrite local with initial/server data
+     * - 'keep-local': Ignore initial/server data if local exists
+     */
+    onConflict?: 'merge' | 'replace' | 'keep-local';
+    /**
+     * Analytics integration.
+     */
+    analytics?: {
+        onEvent: WizardEventHandler<StepId>;
+    };
+    /**
+     * Optional middlewares to intercept actions.
+     */
+    middlewares?: WizardMiddleware<T, StepId>[];
     /**
      * Callback triggered when step changes.
      * Useful for routing integration or analytics.
      */
     onStepChange?: (fromStep: StepId | null, toStep: StepId, data: T) => void;
 }
+/**
+ * Middleware Action Types
+ */
+type WizardAction<T = any, StepId extends string = string> = {
+    type: 'INIT';
+    payload: {
+        data: T;
+        config: IWizardConfig<T, StepId>;
+    };
+} | {
+    type: 'SET_DATA';
+    payload: {
+        path: string;
+        value: any;
+        options?: any;
+    };
+} | {
+    type: 'UPDATE_DATA';
+    payload: {
+        data: Partial<T>;
+        options?: any;
+    };
+} | {
+    type: 'GO_TO_STEP';
+    payload: {
+        from: StepId | null;
+        to: StepId;
+    };
+} | {
+    type: 'VALIDATE_START';
+    payload: {
+        stepId: StepId;
+    };
+} | {
+    type: 'VALIDATE_END';
+    payload: {
+        stepId: StepId;
+        result: ValidationResult;
+    };
+} | {
+    type: 'SET_STEP_ERRORS';
+    payload: {
+        stepId: string;
+        errors: Record<string, string> | undefined | null;
+    };
+} | {
+    type: 'RESET';
+    payload: {
+        data: T;
+    };
+} | {
+    type: 'UPDATE_META';
+    payload: {
+        meta: Partial<IWizardState<T, StepId>>;
+    };
+} | {
+    type: 'SET_CURRENT_STEP_ID';
+    payload: {
+        stepId: StepId | "";
+    };
+} | {
+    type: 'SET_HISTORY';
+    payload: {
+        history: StepId[];
+    };
+} | {
+    type: 'SET_ACTIVE_STEPS';
+    payload: {
+        steps: IStepConfig<T, StepId>[];
+    };
+} | {
+    type: 'SET_VISITED_STEPS';
+    payload: {
+        steps: Set<StepId>;
+    };
+} | {
+    type: 'SET_COMPLETED_STEPS';
+    payload: {
+        steps: Set<StepId>;
+    };
+} | {
+    type: 'SET_ERROR_STEPS';
+    payload: {
+        steps: Set<StepId>;
+    };
+};
+/**
+ * Middleware API
+ */
+interface MiddlewareAPI<T = any, StepId extends string = string> {
+    dispatch: (action: WizardAction<T, StepId>) => void;
+    getState: () => T;
+    getSnapshot: () => any;
+}
+/**
+ * Middleware Type Definition
+ */
+type WizardMiddleware<T = any, StepId extends string = string> = (api: MiddlewareAPI<T, StepId>) => (next: (action: WizardAction<T, StepId>) => void) => (action: WizardAction<T, StepId>) => void;
+/**
+ * Standardized Event Names
+ */
+type WizardEventName = "step_change" | "validation_error" | "wizard_reset";
+/**
+ * Event Payloads
+ */
+type WizardEventPayloads<StepId extends string = string> = {
+    step_change: {
+        from: StepId | null;
+        to: StepId;
+        timestamp: number;
+    };
+    validation_error: {
+        stepId: StepId;
+        errors: Record<string, string> | undefined;
+        timestamp: number;
+    };
+    wizard_reset: {
+        data: any;
+        timestamp?: number;
+    };
+};
+/**
+ * Generic Event Handler Type
+ */
+type WizardEventHandler<StepId extends string = string> = <E extends WizardEventName>(name: E, payload: WizardEventPayloads<StepId>[E]) => void;
 /**
  * Core Wizard Context State
  */
 interface IWizardContext<T = unknown, StepId extends string = string> {
-    currentStep: IStepConfig<unknown, T, StepId> | null;
+    config: IWizardConfig<T, StepId>;
+    currentStep: IStepConfig<T, StepId> | null;
+    currentStepId: StepId | "";
     currentStepIndex: number;
     isFirstStep: boolean;
     isLastStep: boolean;
     isLoading: boolean;
     isPending?: boolean;
+    isBusy: boolean;
+    /**
+     * Dirty State Tracking
+     */
+    isDirty: boolean;
+    dirtyFields: Set<string>;
+    /**
+     * Progress and Stats
+     */
+    progress: number;
+    activeStepsCount: number;
     /**
      * Active steps (those meeting conditions)
      */
-    activeSteps: IStepConfig<unknown, T, StepId>[];
+    activeSteps: IStepConfig<T, StepId>[];
+    /**
+     * Navigation History
+     */
+    history: StepId[];
+    /**
+     * Steps that are currently performing async actions (conditions, validation, guards)
+     */
+    busySteps: Set<StepId>;
     /**
      * Unified Wizard Data
      */
@@ -146,6 +406,10 @@ interface IWizardContext<T = unknown, StepId extends string = string> {
     visitedSteps: Set<StepId>;
     completedSteps: Set<StepId>;
     errorSteps: Set<StepId>;
+    /**
+     * Breadcrumbs
+     */
+    breadcrumbs: IBreadcrumb<StepId>[];
     /**
      * Navigation Actions
      */
@@ -185,60 +449,25 @@ interface IWizardContext<T = unknown, StepId extends string = string> {
     }>;
     save: (stepIds?: StepId | StepId[] | boolean) => void;
     clearStorage: () => void;
+    reset: () => void;
+    /**
+     * Dynamic Configuration
+     */
+    updateConfig: (config: Partial<IWizardConfig<T, StepId>>) => void;
 }
-
-interface IWizardState<T = unknown, StepId extends string = string> {
-    currentStep: IStepConfig<unknown, T, StepId> | null;
-    currentStepIndex: number;
-    isFirstStep: boolean;
-    isLastStep: boolean;
-    isLoading: boolean;
-    isPending: boolean;
-    activeSteps: IStepConfig<unknown, T, StepId>[];
-    visitedSteps: Set<StepId>;
-    completedSteps: Set<StepId>;
-    errorSteps: Set<StepId>;
-    store: WizardStore<T>;
-}
-interface IWizardActions<StepId extends string = string> {
-    goToNextStep: () => Promise<void>;
-    goToPrevStep: () => void;
-    goToStep: (stepId: StepId) => Promise<boolean>;
-    setStepData: (stepId: StepId, data: unknown) => void;
-    handleStepChange: (field: string, value: unknown) => void;
-    validateStep: (sid: StepId) => Promise<boolean>;
-    validateAll: () => Promise<{
-        isValid: boolean;
-        errors: Record<string, Record<string, string>>;
-    }>;
-    save: (stepIds?: StepId | StepId[] | boolean) => void;
-    clearStorage: () => void;
-    setData: (path: string, value: unknown, options?: {
-        debounceValidation?: number;
-    }) => void;
-    updateData: (data: Partial<any>, options?: {
-        replace?: boolean;
-        persist?: boolean;
-    }) => void;
-    getData: (path: string, defaultValue?: unknown) => unknown;
-}
-declare class WizardStore<T> {
-    private state;
-    private listeners;
-    errorsMap: Map<string, Map<string, string>>;
-    constructor(initialData: T);
-    getSnapshot(): {
-        data: T;
-        errors: Record<string, Record<string, string>>;
-    };
-    update(newData: T): void;
-    private syncErrors;
-    updateErrors(newErrors: Record<string, Record<string, string>>): void;
-    setStepErrors(stepId: string, errors: Record<string, string> | undefined | null): boolean;
-    deleteError(stepId: string, path: string): boolean;
-    private notify;
-    subscribe: (listener: () => void) => () => boolean;
+/**
+ * Breadcrumb Status
+ */
+type BreadcrumbStatus = 'visited' | 'current' | 'upcoming' | 'completed' | 'error' | 'hidden';
+/**
+ * Breadcrumb Interface
+ */
+interface IBreadcrumb<StepId extends string = string> {
+    id: StepId;
+    label: string;
+    status: BreadcrumbStatus;
 }
+
 interface WizardProviderProps<T, StepId extends string> {
     config: IWizardConfig<T, StepId>;
     initialData?: T;
@@ -256,7 +485,7 @@ declare function useWizardSelector<TSelected = any>(selector: (state: any) => TS
 }): TSelected;
 declare function useWizardActions<StepId extends string = string>(): IWizardActions<StepId>;
 declare function useWizardContext<T = any, StepId extends string = string>(): IWizardContext<T, StepId> & {
-    store: WizardStore<T>;
+    store: IWizardStore<T, StepId>;
 };
 
 interface WizardStepRendererProps {
@@ -268,6 +497,10 @@ interface WizardStepRendererProps {
         children: React$1.ReactNode;
         key: string;
     }>;
+    /**
+     * Optional fallback to show while lazy-loading a step component.
+     */
+    fallback?: React$1.ReactNode;
 }
 /**
  * A declarative component that renders the current step based on the configuration.
@@ -312,18 +545,19 @@ declare function createWizardFactory<TSchema extends Record<string, any>, StepId
     }) => react_jsx_runtime.JSX.Element;
     useWizard: () => IWizardContext<TSchema, StepId>;
     useWizardContext: () => IWizardContext<TSchema, StepId> & {
-        store: WizardStore<TSchema>;
+        store: IWizardStore<TSchema, StepId>;
     };
     useWizardValue: <P extends Path<TSchema>>(path: P, options?: {
         isEqual?: (a: PathValue<TSchema, P>, b: PathValue<TSchema, P>) => boolean;
     }) => PathValue<TSchema, P>;
-    useWizardSelector: <TSelected>(selector: (state: TSchema) => TSelected, options?: {
+    useWizardSelector: <TSelected>(selector: (state: IWizardContext<TSchema, StepId>) => TSelected, options?: {
         isEqual?: (a: TSelected, b: TSelected) => boolean;
     }) => TSelected;
     useWizardError: <P extends Path<TSchema>>(path: P) => string | undefined;
     useWizardActions: () => IWizardActions<StepId>;
     useWizardState: () => IWizardState<TSchema, StepId>;
-    createStep: <TStepData = unknown>(config: IStepConfig<TStepData, TSchema, StepId>) => IStepConfig<TStepData, TSchema, StepId>;
+    useBreadcrumbs: () => IBreadcrumb<StepId>[];
+    createStep: <TSchema_1 extends Record<string, any>, TStepId extends string = string>(config: IStepConfig<TSchema_1, TStepId>) => IStepConfig<TSchema_1, TStepId>;
 };
 
 declare const useWizard: <T = any, StepId extends string = string>() => IWizardContext<T, StepId>;
@@ -380,6 +614,18 @@ declare class YupAdapter<T> implements IValidatorAdapter<T> {
     validate(data: unknown): Promise<ValidationResult>;
 }
 
+/**
+ * Simple logger middleware for Wizard actions
+ */
+declare const loggerMiddleware: WizardMiddleware<any, any>;
+
+/**
+ * Middleware for Redux DevTools integration
+ */
+declare const devToolsMiddleware: WizardMiddleware<any, any>;
+
+declare function WizardDevTools(): react_jsx_runtime.JSX.Element;
+
 /**
  * Parses a string path into an array of keys using a cache.
  * Handles dot notation "a.b" and bracket notation "a[0].b".
@@ -401,4 +647,4 @@ declare function setByPath<T extends object>(obj: T, path: string, value: unknow
  */
 declare function shallowEqual(a: any, b: any): boolean;
 
-export { type IPersistenceAdapter, type IStepConfig, type IValidatorAdapter, type IWizardActions, type IWizardConfig, type IWizardContext, type IWizardState, LocalStorageAdapter, MemoryAdapter, type PersistenceMode, type ValidationMode, type ValidationResult, WizardProvider, WizardStepRenderer, WizardStore, YupAdapter, ZodAdapter, createWizardFactory, getByPath, setByPath, shallowEqual, toPath, useWizard, useWizardActions, useWizardContext, useWizardError, useWizardSelector, useWizardState, useWizardValue };
+export { type BreadcrumbStatus, type IBreadcrumb, type IPersistenceAdapter, type IStepConfig, type IValidatorAdapter, type IWizardActions, type IWizardConfig, type IWizardContext, type IWizardHandle, type IWizardState, type IWizardStore, LocalStorageAdapter, MemoryAdapter, type MiddlewareAPI, type PersistenceMode, type StepDirection, type ValidationMode, type ValidationResult, type WizardAction, WizardDevTools, type WizardEventHandler, type WizardEventName, type WizardEventPayloads, type WizardMiddleware, WizardProvider, WizardStepRenderer, YupAdapter, ZodAdapter, createWizardFactory, devToolsMiddleware, getByPath, loggerMiddleware, setByPath, shallowEqual, toPath, useWizard, useWizardActions, useWizardContext, useWizardError, useWizardSelector, useWizardState, useWizardValue };