@daltonr/pathwrite-core 0.9.0 → 0.10.0

package/dist/index.d.ts

@@ -9,6 +9,27 @@ export type PathData = Record<string, unknown>;
  * ```
  */
 export type FieldErrors = Record<string, string | undefined>;
+/**
+ * The return type of a `canMoveNext` or `canMovePrevious` guard.
+ *
+ * - `true` — allow navigation
+ * - `{ allowed: false }` — block silently (no message)
+ * - `{ allowed: false, reason: "..." }` — block with a message; the shell surfaces
+ *   this as `snapshot.blockingError` between the step content and the nav buttons
+ *
+ * @example
+ * ```typescript
+ * canMoveNext: async ({ data }) => {
+ *   const result = await checkEligibility(data.applicantId);
+ *   if (!result.eligible) return { allowed: false, reason: result.reason };
+ *   return true;
+ * }
+ * ```
+ */
+export type GuardResult = true | {
+    allowed: false;
+    reason?: string;
+};
 export interface SerializedPathState {
     version: 1;
     pathId: string;
@@ -27,7 +48,7 @@ export interface SerializedPathState {
         stepEntryData?: PathData;
         stepEnteredAt?: number;
     }>;
-    _isNavigating: boolean;
+    _status: PathStatus;
 }
 /**
  * The interface every path state store must implement.
@@ -99,8 +120,8 @@ export interface PathStep<TData extends PathData = PathData> {
     title?: string;
     meta?: Record<string, unknown>;
     shouldSkip?: (ctx: PathStepContext<TData>) => boolean | Promise<boolean>;
-    canMoveNext?: (ctx: PathStepContext<TData>) => boolean | Promise<boolean>;
-    canMovePrevious?: (ctx: PathStepContext<TData>) => boolean | Promise<boolean>;
+    canMoveNext?: (ctx: PathStepContext<TData>) => GuardResult | Promise<GuardResult>;
+    canMovePrevious?: (ctx: PathStepContext<TData>) => GuardResult | Promise<GuardResult>;
     /**
      * Returns a map of field ID → error message explaining why the step is not
      * yet valid. The shell displays these messages below the step content (labeled
@@ -176,6 +197,24 @@ export interface PathDefinition<TData extends PathData = PathData> {
     onCancel?: (data: TData) => void | Promise<void>;
 }
 export type StepStatus = "completed" | "current" | "upcoming";
+/**
+ * The engine's current operational state. Exposed as `snapshot.status`.
+ *
+ * | Status        | Meaning                                                      |
+ * |---------------|--------------------------------------------------------------|
+ * | `idle`        | On a step, waiting for user input                            |
+ * | `entering`    | `onEnter` hook is running                                    |
+ * | `validating`  | `canMoveNext` / `canMovePrevious` guard is running           |
+ * | `leaving`     | `onLeave` hook is running                                    |
+ * | `completing`  | `PathDefinition.onComplete` is running                       |
+ * | `error`       | An async operation failed — see `snapshot.error` for details |
+ */
+export type PathStatus = "idle" | "entering" | "validating" | "leaving" | "completing" | "error";
+/**
+ * The subset of `PathStatus` values that identify which phase was active
+ * when an error occurred. Used by `snapshot.error.phase`.
+ */
+export type ErrorPhase = Exclude<PathStatus, "idle" | "error">;
 export interface StepSummary {
     id: string;
     title?: string;
@@ -231,8 +270,36 @@ export interface PathSnapshot<TData extends PathData = PathData> {
      * progress bar above the sub-path's own progress bar.
      */
     rootProgress?: RootProgress;
-    /** True while an async guard or hook is executing. Use to disable navigation controls. */
-    isNavigating: boolean;
+    /**
+     * The engine's current operational state. Use this instead of multiple boolean flags.
+     *
+     * Common patterns:
+     * - `status !== "idle"` — disable all navigation buttons (engine is busy or errored)
+     * - `status === "entering"` — show a skeleton/spinner inside the step area
+     * - `status === "validating"` — show "Checking…" on the Next button
+     * - `status === "error"` — show the retry / suspend error UI
+     */
+    status: PathStatus;
+    /**
+     * Structured error set when an engine-invoked async operation throws. `null` when no error is active.
+     *
+     * `phase` identifies which operation failed so shells can adapt the message.
+     * `retryCount` counts how many times the user has explicitly called `retry()` — starts at 0 on
+     * first failure, increments on each retry. Use this to escalate from "Try again" to "Come back later".
+     *
+     * Cleared automatically when navigation succeeds or when `retry()` is called.
+     */
+    error: {
+        message: string;
+        phase: ErrorPhase;
+        retryCount: number;
+    } | null;
+    /**
+     * `true` when a `PathStore` is attached via `PathEngineOptions.hasPersistence`.
+     * Shells use this to decide whether to promise the user that progress is saved
+     * when showing the "come back later" escalation message.
+     */
+    hasPersistence: boolean;
     /** Whether the current step's `canMoveNext` guard allows advancing. Async guards default to `true`. Auto-derived as `true` when `fieldErrors` is defined and returns no messages, and `canMoveNext` is not explicitly defined. */
     canMoveNext: boolean;
     /** Whether the current step's `canMovePrevious` guard allows going back. Async guards default to `true`. */
@@ -284,6 +351,15 @@ export interface PathSnapshot<TData extends PathData = PathData> {
      * navigating back to a previously visited step).
      */
     stepEnteredAt: number;
+    /**
+     * A guard-level blocking message set when `canMoveNext` returns
+     * `{ allowed: false, reason: "..." }`. `null` when there is no blocking message.
+     *
+     * Distinct from `fieldErrors` (field-attached) and `error` (async crash).
+     * Shells render this between the step content and the navigation buttons.
+     * Cleared automatically when the user successfully navigates to a new step.
+     */
+    blockingError: string | null;
     /**
      * Field-keyed validation messages for the current step. Empty object when there are none.
      * Use in step templates to render inline per-field errors: `snapshot.fieldErrors['email']`.
@@ -303,7 +379,7 @@ export interface PathSnapshot<TData extends PathData = PathData> {
 /**
  * Identifies the public method that triggered a `stateChanged` event.
  */
-export type StateChangeCause = "start" | "next" | "previous" | "goToStep" | "goToStepChecked" | "setData" | "resetStep" | "cancel" | "restart";
+export type StateChangeCause = "start" | "next" | "previous" | "goToStep" | "goToStepChecked" | "setData" | "resetStep" | "cancel" | "restart" | "retry" | "suspend";
 export type PathEvent = {
     type: "stateChanged";
     cause: StateChangeCause;
@@ -316,6 +392,10 @@ export type PathEvent = {
     type: "cancelled";
     pathId: string;
     data: PathData;
+} | {
+    type: "suspended";
+    pathId: string;
+    data: PathData;
 } | {
     type: "resumed";
     resumedPathId: string;
@@ -372,17 +452,48 @@ export interface PathEngineOptions {
      * listeners use `engine.subscribe()`.
      */
     observers?: PathObserver[];
+    /**
+     * Set to `true` when a `PathStore` is attached and will persist path state.
+     * Exposed as `snapshot.hasPersistence` so shells can honestly tell the user
+     * their progress is saved when showing the "come back later" escalation message.
+     */
+    hasPersistence?: boolean;
 }
+/**
+ * Converts a camelCase or lowercase field key to a display label.
+ * `"firstName"` → `"First Name"`, `"email"` → `"Email"`.
+ * Used by shells to render labeled field-error summaries.
+ */
+export declare function formatFieldKey(key: string): string;
+/**
+ * Returns a human-readable description of which operation failed, keyed by
+ * the `ErrorPhase` value on `snapshot.error.phase`. Used by shells to render
+ * the error panel message.
+ */
+export declare function errorPhaseMessage(phase: string): string;
 export declare class PathEngine {
     private activePath;
     private readonly pathStack;
     private readonly listeners;
-    private _isNavigating;
+    private _status;
     /** True after the user has called next() on the current step at least once. Resets on step entry. */
     private _hasAttemptedNext;
+    /** Blocking message from canMoveNext returning { allowed: false, reason }. Cleared on step entry. */
+    private _blockingError;
     /** The path and initial data from the most recent top-level start() call. Used by restart(). */
     private _rootPath;
     private _rootInitialData;
+    /** Structured error from the most recent failed async operation. Null when no error is active. */
+    private _error;
+    /** Stored retry function. Null when no error is pending. */
+    private _pendingRetry;
+    /**
+     * Counts how many times `retry()` has been called for the current error sequence.
+     * Reset to 0 by `next()` (fresh navigation). Incremented by `retry()`.
+     */
+    private _retryCount;
+    private _hasPersistence;
+    private _hasWarnedAsyncShouldSkip;
     constructor(options?: PathEngineOptions);
     /**
      * Restores a PathEngine from previously exported state.
@@ -428,6 +539,29 @@ export declare class PathEngine {
     startSubPath(path: PathDefinition<any>, initialData?: PathData, meta?: Record<string, unknown>): Promise<void>;
     next(): Promise<void>;
     previous(): Promise<void>;
+    /**
+     * Re-runs the operation that caused the most recent `snapshot.error`.
+     * Increments `snapshot.error.retryCount` so shells can escalate from
+     * "Try again" to "Come back later" after repeated failures.
+     *
+     * No-op if there is no pending error or if navigation is in progress.
+     */
+    retry(): Promise<void>;
+    /**
+     * Pauses the path with intent to return. Preserves all state and data.
+     *
+     * - Clears any active error state
+     * - Emits a `suspended` event that the application can listen for to dismiss
+     *   the wizard UI (close a modal, navigate away, etc.)
+     * - The engine remains in its current state — call `start()` / `restoreOrStart()`
+     *   to resume when the user returns
+     *
+     * Use in the "Come back later" escalation path when `snapshot.error.retryCount`
+     * has crossed `retryThreshold`. The `suspended` event signals the app to dismiss
+     * the UI; Pathwrite's persistence layer handles saving progress automatically via
+     * the configured store and observer strategy.
+     */
+    suspend(): Promise<void>;
     /** Cancel is synchronous for top-level paths (no hooks). Sub-path cancellation
      *  is async when an `onSubPathCancel` hook is present. Returns a Promise for
      *  API consistency. */
@@ -473,6 +607,22 @@ export declare class PathEngine {
     private _goToStepCheckedAsync;
     private _cancelSubPathAsync;
     private finishActivePath;
+    /**
+     * Wraps `finishActivePath` with error handling for the `completing` phase.
+     * On failure: sets `_error`, stores a retry that re-calls `finishActivePath`,
+     * resets status to `"error"`, and emits `stateChanged`.
+     * On success: resets status to `"idle"` (finishActivePath sets activePath = null,
+     * so no stateChanged is needed — the `completed` event is the terminal signal).
+     */
+    private _finishActivePathWithErrorHandling;
+    /**
+     * Wraps `enterCurrentStep` with error handling for the `entering` phase.
+     * Called by both `_startAsync` and `_nextAsync` after advancing to a new step.
+     * On failure: sets `_error`, stores a retry that re-calls this method,
+     * resets status to `"error"`, and emits `stateChanged` with the given `cause`.
+     */
+    private _enterCurrentStepWithErrorHandling;
+    private static errorMessage;
     private requireActivePath;
     private assertPathHasSteps;
     private emit;
@@ -497,6 +647,7 @@ export declare class PathEngine {
     private leaveCurrentStep;
     private canMoveNext;
     private canMovePrevious;
+    private static normaliseGuardResult;
     /**
      * Evaluates a guard function synchronously for inclusion in the snapshot.
      * If the guard is absent, returns `true`.