wizzard-stepper-react 1.5.1 → 1.7.0

package/dist/index.d.ts

@@ -22,6 +22,13 @@ interface IValidatorAdapter<TData = unknown> {
  * - 'manual': Save only when manually triggered
  */
 type PersistenceMode = 'onStepChange' | 'onChange' | 'manual';
+/**
+ * Validation Mode
+ * - 'onChange': Validate on every data change (debounced)
+ * - 'onStepChange': Validate only when moving to next step
+ * - 'manual': Validate only when manually triggered
+ */
+type ValidationMode = 'onChange' | 'onStepChange' | 'manual';
 /**
  * Persistence Adapter Interface
  */
@@ -35,8 +42,8 @@ interface IPersistenceAdapter {
  * TStepData: Type of data for this step
  * TGlobalContext: Type of the global wizard data
  */
-interface IStepConfig<TStepData = unknown, TGlobalContext = unknown> {
-    id: string;
+interface IStepConfig<TStepData = unknown, TGlobalContext = unknown, StepId extends string = string> {
+    id: StepId;
     label: string;
     /**
      * Predicate to determine if step should be included/visible.
@@ -49,8 +56,16 @@ interface IStepConfig<TStepData = unknown, TGlobalContext = unknown> {
     validationAdapter?: IValidatorAdapter<TStepData>;
     /**
      * Override global auto-validation setting for this step
+     * @deprecated Use validationMode instead
      */
     autoValidate?: boolean;
+    /**
+     * Control when validation occurs for this step.
+     * - 'onChange': Validate on every keystroke (debounced)
+     * - 'onStepChange': Validate only when attempting to leave the step
+     * - 'manual': Only validate when explicitly triggered
+     */
+    validationMode?: ValidationMode;
     /**
      * Optional React Component to render for this step.
      * Used by the <WizardStepRenderer /> component.
@@ -60,20 +75,32 @@ interface IStepConfig<TStepData = unknown, TGlobalContext = unknown> {
      * Override global persistence adapter for this specific step.
      */
     persistenceAdapter?: IPersistenceAdapter;
+    /**
+     * Control when persistence occurs for this specific step.
+     * - 'onStepChange': Save when moving between steps (default)
+     * - 'onChange': Save on every data change (debounced)
+     * - 'manual': Save only when manually triggered
+     */
+    persistenceMode?: PersistenceMode;
 }
 /**
  * Wizard Configuration
  * T: Type of the Global Wizard Data
  */
-interface IWizardConfig<T = unknown> {
+interface IWizardConfig<T = unknown, StepId extends string = string> {
     /**
      * Array of step configurations
      */
-    steps: IStepConfig<unknown, T>[];
+    steps: IStepConfig<unknown, T, StepId>[];
     /**
      * Global auto-validation setting (default: true)
+     * @deprecated Use validationMode instead
      */
     autoValidate?: boolean;
+    /**
+     * Default validation mode for all steps (default: 'onChange')
+     */
+    validationMode?: ValidationMode;
     /**
      * Persistence configuration
      */
@@ -89,13 +116,13 @@ interface IWizardConfig<T = unknown> {
      * Callback triggered when step changes.
      * Useful for routing integration or analytics.
      */
-    onStepChange?: (fromStep: string | null, toStep: string, data: T) => void;
+    onStepChange?: (fromStep: StepId | null, toStep: StepId, data: T) => void;
 }
 /**
  * Core Wizard Context State
  */
-interface IWizardContext<T = unknown> {
-    currentStep: IStepConfig<unknown, T> | null;
+interface IWizardContext<T = unknown, StepId extends string = string> {
+    currentStep: IStepConfig<unknown, T, StepId> | null;
     currentStepIndex: number;
     isFirstStep: boolean;
     isLastStep: boolean;
@@ -104,7 +131,7 @@ interface IWizardContext<T = unknown> {
     /**
      * Active steps (those meeting conditions)
      */
-    activeSteps: IStepConfig<unknown, T>[];
+    activeSteps: IStepConfig<unknown, T, StepId>[];
     /**
      * Unified Wizard Data
      */
@@ -116,19 +143,19 @@ interface IWizardContext<T = unknown> {
     /**
      * Steps Status
      */
-    visitedSteps: Set<string>;
-    completedSteps: Set<string>;
-    errorSteps: Set<string>;
+    visitedSteps: Set<StepId>;
+    completedSteps: Set<StepId>;
+    errorSteps: Set<StepId>;
     /**
      * Navigation Actions
      */
     goToNextStep: () => Promise<void>;
     goToPrevStep: () => void;
-    goToStep: (stepId: string) => Promise<boolean>;
+    goToStep: (stepId: StepId) => Promise<boolean>;
     /**
      * Data Actions
      */
-    setStepData: (stepId: string, data: unknown) => void;
+    setStepData: (stepId: StepId, data: unknown) => void;
     handleStepChange: (field: string, value: unknown) => void;
     /**
      * Set data by path (supports dot notation and arrays, e.g., 'user.name' or 'items[0].value')
@@ -151,75 +178,84 @@ interface IWizardContext<T = unknown> {
     /**
      * Validation & Persistence
      */
-    validateStep: (sid: string) => Promise<boolean>;
+    validateStep: (sid: StepId) => Promise<boolean>;
     validateAll: () => Promise<{
         isValid: boolean;
         errors: Record<string, Record<string, string>>;
     }>;
-    save: () => void;
+    save: (stepIds?: StepId | StepId[] | boolean) => void;
     clearStorage: () => void;
 }
 
-interface IWizardState<T = unknown> {
-    currentStep: IStepConfig<unknown, T> | null;
+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>[];
-    visitedSteps: Set<string>;
-    completedSteps: Set<string>;
-    errorSteps: Set<string>;
+    activeSteps: IStepConfig<unknown, T, StepId>[];
+    visitedSteps: Set<StepId>;
+    completedSteps: Set<StepId>;
+    errorSteps: Set<StepId>;
     store: WizardStore<T>;
 }
-interface IWizardActions {
+interface IWizardActions<StepId extends string = string> {
     goToNextStep: () => Promise<void>;
     goToPrevStep: () => void;
-    goToStep: (stepId: string) => Promise<boolean>;
-    setStepData: (stepId: string, data: unknown) => void;
+    goToStep: (stepId: StepId) => Promise<boolean>;
+    setStepData: (stepId: StepId, data: unknown) => void;
     handleStepChange: (field: string, value: unknown) => void;
-    validateStep: (sid: string) => Promise<boolean>;
+    validateStep: (sid: StepId) => Promise<boolean>;
     validateAll: () => Promise<{
         isValid: boolean;
         errors: Record<string, Record<string, string>>;
     }>;
-    save: () => void;
+    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: () => {
+    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;
 }
-interface WizardProviderProps<T> {
-    config: IWizardConfig<T>;
+interface WizardProviderProps<T, StepId extends string> {
+    config: IWizardConfig<T, StepId>;
     initialData?: T;
-    initialStepId?: string;
+    initialStepId?: StepId;
     children: React$1.ReactNode;
 }
-declare function WizardProvider<T extends Record<string, any>>({ config, initialData, initialStepId, children, }: WizardProviderProps<T>): react_jsx_runtime.JSX.Element;
-declare function useWizardState<T = unknown>(): IWizardState<T>;
-declare function useWizardValue<TValue = any>(path: string): TValue;
+declare function WizardProvider<T extends Record<string, any>, StepId extends string = string>({ config, initialData, initialStepId, children, }: WizardProviderProps<T, StepId>): react_jsx_runtime.JSX.Element;
+declare function useWizardState<T = unknown, StepId extends string = string>(): IWizardState<T, StepId>;
+declare function useWizardValue<TValue = any>(path: string, options?: {
+    isEqual?: (a: TValue, b: TValue) => boolean;
+}): TValue;
 declare function useWizardError(path: string): string | undefined;
-declare function useWizardSelector<TSelected = any>(selector: (state: any) => TSelected): TSelected;
-declare function useWizardActions(): IWizardActions;
-declare function useWizardContext<T = any>(): IWizardContext<T> & {
+declare function useWizardSelector<TSelected = any>(selector: (state: any) => TSelected, options?: {
+    isEqual?: (a: TSelected, b: TSelected) => boolean;
+}): 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>;
 };
 
@@ -268,25 +304,29 @@ type PathValue<T, P extends Path<T>> = T extends any ? P extends `${infer K}.${i
  *
  * @template TSchema The shape of your wizard's global data state
  */
-declare function createWizardFactory<TSchema extends Record<string, any>>(): {
+declare function createWizardFactory<TSchema extends Record<string, any>, StepId extends string = string>(): {
     WizardProvider: ({ config, initialData, children, }: {
-        config: IWizardConfig<TSchema>;
+        config: IWizardConfig<TSchema, StepId>;
         initialData?: Partial<TSchema>;
         children: React$1.ReactNode;
     }) => react_jsx_runtime.JSX.Element;
-    useWizard: () => IWizardContext<TSchema>;
-    useWizardContext: () => IWizardContext<TSchema> & {
+    useWizard: () => IWizardContext<TSchema, StepId>;
+    useWizardContext: () => IWizardContext<TSchema, StepId> & {
         store: WizardStore<TSchema>;
     };
-    useWizardValue: <P extends Path<TSchema>>(path: P) => PathValue<TSchema, P>;
-    useWizardSelector: <TSelected>(selector: (state: TSchema) => TSelected) => TSelected;
+    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?: {
+        isEqual?: (a: TSelected, b: TSelected) => boolean;
+    }) => TSelected;
     useWizardError: <P extends Path<TSchema>>(path: P) => string | undefined;
-    useWizardActions: () => IWizardActions;
-    useWizardState: () => IWizardState<unknown>;
-    createStep: <TStepData = unknown>(config: IStepConfig<TStepData, TSchema>) => IStepConfig<TStepData, TSchema>;
+    useWizardActions: () => IWizardActions<StepId>;
+    useWizardState: () => IWizardState<TSchema, StepId>;
+    createStep: <TStepData = unknown>(config: IStepConfig<TStepData, TSchema, StepId>) => IStepConfig<TStepData, TSchema, StepId>;
 };
 
-declare const useWizard: <T = any>() => IWizardContext<T>;
+declare const useWizard: <T = any, StepId extends string = string>() => IWizardContext<T, StepId>;
 
 declare class MemoryAdapter implements IPersistenceAdapter {
     private storage;
@@ -341,12 +381,24 @@ declare class YupAdapter<T> implements IValidatorAdapter<T> {
 }
 
 /**
- * Retrieves a value from an object by path (dot notation or brackets)
+ * Parses a string path into an array of keys using a cache.
+ * Handles dot notation "a.b" and bracket notation "a[0].b".
+ */
+declare function toPath(path: string): string[];
+/**
+ * Retrieves a value from an object by path using cached key parsing.
+ * Optimized for frequent access.
  */
 declare function getByPath(obj: any, path: string, defaultValue?: unknown): unknown;
 /**
- * Immutably sets a value in an object by path
+ * Immutably sets a value in an object by path.
+ * iterative implementation (stack-safe and usually faster).
  */
 declare function setByPath<T extends object>(obj: T, path: string, value: unknown): T;
+/**
+ * Simple shallow equality check for objects and arrays.
+ * Useful for preventing re-renders in selectors.
+ */
+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 ValidationResult, WizardProvider, WizardStepRenderer, WizardStore, YupAdapter, ZodAdapter, createWizardFactory, getByPath, setByPath, useWizard, useWizardActions, useWizardContext, useWizardError, useWizardSelector, useWizardState, useWizardValue };
+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 };