@wizzard-packages/core 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,499 @@
+/**
+ * @module Types (Core)
+ */
+/**
+ * Full state of the wizard.
+ */
+interface IWizardState<T = unknown, StepId extends string = string> {
+    /** Global wizard data object */
+    data: T;
+    /** Current errors map by step and field */
+    errors: Record<StepId, Record<string, string>>;
+    /** Active step configuration (if any) */
+    currentStep: IStepConfig<T, StepId> | null;
+    /** Numeric index of current step in active steps list */
+    currentStepIndex: number;
+    /** True if currently on the first active step */
+    isFirstStep: boolean;
+    /** True if currently on the last active step */
+    isLastStep: boolean;
+    /** True if the wizard is in an initial loading/hydrating state */
+    isLoading: boolean;
+    /** True if an async action (like navigation or validation) is in progress */
+    isPending: boolean;
+    /** List of steps that currently meet their visibility conditions */
+    activeSteps: IStepConfig<T, StepId>[];
+    /** String ID of the current step */
+    currentStepId: StepId | '';
+    /** History of visited steps (navigation path) */
+    history: StepId[];
+    /** Set of step IDs that are currently performing async work */
+    busySteps: Set<StepId>;
+    /** Set of step IDs that have been visited by the user */
+    visitedSteps: Set<StepId>;
+    /** Set of step IDs that have passed validation */
+    completedSteps: Set<StepId>;
+    /** Set of step IDs that currently have active validation errors */
+    errorSteps: Set<StepId>;
+    /** Current wizard configuration */
+    config: IWizardConfig<T, StepId>;
+    /** Percentage of completion (0-100) */
+    progress: number;
+    /** Number of active steps */
+    activeStepsCount: number;
+    /** Alias for isPending */
+    isBusy: boolean;
+    /** True if any field has been modified since initialization */
+    isDirty: boolean;
+    /** Set of paths to fields that have been modified */
+    dirtyFields: Set<string>;
+    /** Breadcrumb items for navigation UI */
+    breadcrumbs: IBreadcrumb<StepId>[];
+    /** Result of the last goToStep action */
+    goToStepResult?: boolean | null | 'init';
+}
+/**
+ * Store interface for reading state and dispatching actions.
+ */
+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;
+    injectPersistence(adapter: IPersistenceAdapter): void;
+    save(stepId?: StepId): void;
+    hydrate(): void;
+    errorsMap: Map<string, Map<string, string>>;
+    resolveActiveSteps(data?: T): Promise<IStepConfig<T, StepId>[]>;
+    goToStep(stepId: StepId, options?: {
+        validate?: boolean;
+        providedActiveSteps?: IStepConfig<T, StepId>[];
+    }): Promise<boolean>;
+    validateStep: (stepId: StepId) => Promise<boolean>;
+    validateAll: () => Promise<{
+        isValid: boolean;
+        errors: Record<string, Record<string, string>>;
+    }>;
+}
+/**
+ * Public actions available to control the wizard.
+ */
+interface IWizardActions<StepId extends string = string> {
+    goToNextStep: () => Promise<void>;
+    goToPrevStep: () => Promise<void>;
+    goToStep: (stepId: StepId, providedActiveSteps?: any[], options?: {
+        validate?: boolean;
+    }) => 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;
+    updateConfig: (config: Partial<IWizardConfig<any, StepId>>) => void;
+}
+/**
+ * Validation Result Interface
+ */
+type ValidationResult = {
+    isValid: boolean;
+    errors?: Record<string, string>;
+};
+/**
+ * Validator Adapter Interface
+ */
+interface IValidatorAdapter<TData = unknown> {
+    validate: (data: TData) => Promise<ValidationResult> | ValidationResult;
+}
+/**
+ * Persistence strategy for step data.
+ */
+type PersistenceMode = 'onStepChange' | 'onChange' | 'manual';
+/**
+ * Validation strategy for step data.
+ */
+type ValidationMode = 'onChange' | 'onStepChange' | 'manual';
+/**
+ * Persistence Adapter Interface
+ */
+interface IPersistenceAdapter {
+    saveStep: <T>(stepId: string, data: T) => void;
+    getStep: <T>(stepId: string) => T | undefined;
+    getStepWithMeta?: <T>(stepId: string) => {
+        data: T;
+        timestamp: number;
+    } | undefined;
+    clearStep: (stepId: string) => void;
+    clear: () => void;
+}
+/**
+ * Step Navigation Direction
+ */
+type StepDirection = 'next' | 'prev';
+/**
+ * Step Configuration
+ */
+interface IStepConfig<TStepData = unknown, StepId extends string = string> {
+    id: StepId;
+    label: string;
+    condition?: (data: TStepData, metadata: Partial<IWizardState<TStepData, StepId>> & {
+        data?: TStepData | undefined;
+        allErrors?: any;
+    }) => boolean | Promise<boolean>;
+    showWhilePending?: boolean;
+    conditionDependsOn?: string[];
+    beforeLeave?: (data: TStepData, direction: StepDirection, metadata: Partial<IWizardState<TStepData, StepId>> & {
+        data?: TStepData | undefined;
+        allErrors?: any;
+    }) => boolean | Promise<boolean>;
+    validationAdapter?: IValidatorAdapter<TStepData>;
+    /** @deprecated Use validationMode instead */
+    autoValidate?: boolean;
+    validationMode?: ValidationMode;
+    component?: any;
+    persistenceAdapter?: IPersistenceAdapter;
+    persistenceMode?: PersistenceMode;
+    dependsOn?: string[];
+    clearData?: string | string[] | ((data: TStepData, changedFields: string[]) => Partial<TStepData>);
+    canNavigateTo?: (data: TStepData, metadata: Partial<IWizardState<TStepData, StepId>> & {
+        data?: TStepData | undefined;
+        allErrors?: any;
+    }) => boolean | Promise<boolean>;
+}
+/**
+ * Global Wizard Configuration.
+ */
+interface IWizardConfig<T = unknown, StepId extends string = string> {
+    steps: IStepConfig<T, StepId>[];
+    /** @deprecated Use validationMode instead */
+    autoValidate?: boolean;
+    validationMode?: ValidationMode;
+    validationDebounceTime?: number;
+    persistence?: {
+        mode?: PersistenceMode;
+        adapter?: IPersistenceAdapter;
+        storageKey?: string;
+        debounceTime?: number;
+    };
+    onConflict?: 'merge' | 'replace' | 'keep-local';
+    analytics?: {
+        onEvent: WizardEventHandler<StepId>;
+    };
+    middlewares?: WizardMiddleware<T, StepId>[];
+    navigationMode?: 'sequential' | 'visited' | 'free';
+    onStepChange?: (fromStep: StepId | null, toStep: StepId, data: T) => void;
+}
+/**
+ * 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;
+        to: StepId;
+        result: boolean | null | 'init';
+        nextVisitedSteps?: Set<StepId>;
+        nextHistory?: StepId[];
+    };
+} | {
+    type: 'VALIDATE_START';
+    payload: {
+        stepId: StepId;
+    };
+} | {
+    type: 'VALIDATE_END';
+    payload: {
+        stepId: StepId;
+        result: ValidationResult;
+    };
+} | {
+    type: 'SET_STEP_ERRORS';
+    payload: {
+        stepId: StepId;
+        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>;
+    };
+} | {
+    type: 'RESTORE_SNAPSHOT';
+    payload: {
+        snapshot: any;
+    };
+};
+/**
+ * Middleware API
+ */
+interface MiddlewareAPI<T = any, StepId extends string = string> {
+    dispatch: (action: WizardAction<T, StepId>) => void;
+    getState: () => T;
+    getSnapshot: () => IWizardState<T, StepId>;
+}
+/**
+ * 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;
+/**
+ * Breadcrumb Status
+ */
+type BreadcrumbStatus = 'visited' | 'current' | 'upcoming' | 'completed' | 'error' | 'hidden';
+/**
+ * Breadcrumb Interface
+ */
+interface IBreadcrumb<StepId extends string = string> {
+    id: StepId;
+    label: string;
+    status: BreadcrumbStatus;
+}
+/**
+ * High-level context for the wizard, combining state and actions.
+ */
+interface IWizardContext<T = unknown, StepId extends string = string> extends Omit<IWizardState<T, StepId>, 'errors'>, IWizardActions<StepId> {
+    /**
+     * The internal store instance.
+     */
+    store: IWizardStore<T, StepId>;
+    /**
+     * Combined error map (flat)
+     */
+    errors: Record<string, string>;
+    /**
+     * All errors by step and field.
+     */
+    allErrors: Record<StepId, Record<string, string>>;
+}
+
+/**
+ * Core event-driven store for managing wizard state, data, and navigation.
+ *
+ * @template T Type of the global wizard data object
+ * @template StepId String union of valid step IDs
+ */
+declare class WizardStore<T, StepId extends string = string> implements IWizardStore<T, StepId> {
+    private initialData;
+    private dirtyFields;
+    private state;
+    private listeners;
+    private actionListeners;
+    errorsMap: Map<StepId, Map<string, string>>;
+    private middlewareChain;
+    private persistenceAdapter?;
+    private persistenceDebounceTimers;
+    private stepsMap;
+    subscribeToActions(listener: (action: WizardAction<T, StepId>) => void): () => boolean;
+    private notifyActions;
+    constructor(initialData: T, middlewares?: WizardMiddleware<T, StepId>[]);
+    private setupMiddlewares;
+    /**
+     * Processes an action through the middleware chain and updates the state.
+     * This is the primary way to trigger any state change in the wizard.
+     *
+     * @param action The action to perform
+     */
+    dispatch(action: WizardAction<T, StepId>): void;
+    /**
+     * Internal dispatch that actually performs the state updates
+     */
+    private internalDispatch;
+    private updateDataByPath;
+    private updateBulkData;
+    /**
+     * Returns the current immutable snapshot of the wizard state.
+     */
+    getSnapshot: () => IWizardState<T, StepId>;
+    /**
+     * Performs a granular data update at a specific path.
+     * Automatically calculates dirty fields and triggers auto-save if configured.
+     *
+     * @param newData Full new data object
+     * @param changedPath Path(s) that were modified
+     */
+    update(newData: T, changedPath?: string | string[]): void;
+    updateMeta(newMeta: Partial<IWizardState<T, StepId>>): void;
+    private syncDerivedState;
+    /**
+     * Sets the initial data for the wizard.
+     * Resets dirty tracking based on this new data.
+     */
+    setInitialData(data: T): void;
+    private syncErrors;
+    updateErrors(newErrors: Record<StepId, Record<string, string>>): void;
+    setStepErrors(stepId: StepId, errors: Record<string, string> | undefined | null): boolean;
+    deleteError(stepId: StepId, path: string): boolean;
+    private notify;
+    subscribe: (listener: () => void) => () => boolean;
+    injectPersistence(adapter: IPersistenceAdapter): void;
+    /**
+     * Restores wizard state from persistence storage.
+     * Implements "latest wins" conflict resolution based on step timestamps.
+     */
+    hydrate(): void;
+    private saveMeta;
+    clearStepStorage(stepId: string): void;
+    /**
+     * Manually triggers data persistence for specific steps or the current step.
+     *
+     * @param stepId Optional ID of step to save. If omitted, saves current step.
+     */
+    save(stepId?: StepId): void;
+    private saveStepData;
+    private handleStepChangePersistence;
+    private checkAutoSave;
+    private conditionCache;
+    /**
+     * Evaluates visibility conditions for all steps and returns only those that should be active.
+     * Uses memoization to avoid redundant async calls if dependencies haven't changed.
+     *
+     * @param data Optional data override for evaluation
+     */
+    resolveActiveSteps(data?: T): Promise<IStepConfig<T, StepId>[]>;
+    validateStep(stepId: StepId): Promise<boolean>;
+    validateAll(): Promise<{
+        isValid: boolean;
+        errors: Record<string, Record<string, string>>;
+    }>;
+    goToStep(stepId: StepId, options?: {
+        validate?: boolean;
+        providedActiveSteps?: IStepConfig<T, StepId>[];
+    }): Promise<boolean>;
+}
+
+/**
+ * Parses a string path into an array of keys using a cache.
+ */
+declare function toPath(path: string): string[];
+/**
+ * Retrieves a value from an object by path.
+ */
+declare function getByPath(obj: any, path: string, defaultValue?: unknown): unknown;
+/**
+ * Immutably sets a value in an object by path.
+ */
+declare function setByPath<T extends object>(obj: T, path: string, value: unknown): T;
+/**
+ * Simple shallow equality check.
+ */
+declare function shallowEqual(a: any, b: any): boolean;
+
+/**
+ * Utility types for dot-notation paths
+ */
+type Primitive = null | undefined | string | number | boolean | symbol | bigint;
+type IsTuple<T extends ReadonlyArray<any>> = number extends T['length'] ? false : true;
+type TupleKeys<T extends ReadonlyArray<any>> = Exclude<keyof T, keyof any[]>;
+type PathImpl<K extends string | number, V> = V extends Primitive ? `${K}` : `${K}` | `${K}.${Path<V>}`;
+/**
+ * Dot-notation path for a nested data type.
+ */
+type Path<T> = T extends ReadonlyArray<infer V> ? IsTuple<T> extends true ? {
+    [K in TupleKeys<T>]-?: PathImpl<K & string, T[K]>;
+}[TupleKeys<T>] : PathImpl<number, V> : {
+    [K in keyof T]-?: PathImpl<K & string, T[K]>;
+}[keyof T];
+/**
+ * Value type resolved from a dot-notation path.
+ */
+type PathValue<T, P extends Path<T>> = T extends any ? P extends `${infer K}.${infer R}` ? K extends keyof T ? R extends Path<T[K]> ? PathValue<T[K], R> : never : K extends `${number}` ? T extends ReadonlyArray<infer V> ? R extends Path<V> ? PathValue<V, R> : never : never : never : P extends keyof T ? T[P] : P extends `${number}` ? T extends ReadonlyArray<infer V> ? V : never : never : never;
+
+export { type BreadcrumbStatus, type IBreadcrumb, type IPersistenceAdapter, type IStepConfig, type IValidatorAdapter, type IWizardActions, type IWizardConfig, type IWizardContext, type IWizardState, type IWizardStore, type MiddlewareAPI, type Path, type PathValue, type PersistenceMode, type StepDirection, type ValidationMode, type ValidationResult, type WizardAction, type WizardEventHandler, type WizardEventName, type WizardEventPayloads, type WizardMiddleware, WizardStore, getByPath, setByPath, shallowEqual, toPath };