@daltonr/pathwrite-core 0.6.3 → 0.8.0

package/LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2026 Richard Dalton
+Copyright (c) 2026 Devjoy Ltd.
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -21,6 +21,30 @@ onEnter: (ctx) => {
 }
 ```
 
+### ✅ Track Unsaved Changes with `isDirty`
+```typescript
+// In your UI component
+const snapshot = engine.snapshot();
+if (snapshot.isDirty) {
+  // Show "unsaved changes" warning, disable Save button until changes made, etc.
+}
+
+// Revert changes
+<button onClick={() => engine.resetStep()}>Undo Changes</button>
+```
+
+### ✅ Compute Time on Step with `stepEnteredAt`
+```typescript
+// Analytics or timeout warnings
+const snapshot = engine.snapshot();
+const durationMs = Date.now() - snapshot.stepEnteredAt;
+const durationSec = Math.floor(durationMs / 1000);
+
+if (durationSec > 300) { // 5 minutes
+  console.warn("User has been on this step for 5+ minutes");
+}
+```
+
 ### ✅ Correlate Sub-Paths with `meta`
 ```typescript
 // Starting sub-path
@@ -53,18 +77,26 @@ const path: PathDefinition<CourseData> = {
       onLeave: (ctx) => ({ courseName: ctx.data.courseName.trim() })
     },
     { id: "review" }
-  ]
+  ],
+  onComplete: (data) => {
+    // Called when the path completes
+    console.log("Course created:", data.courseName);
+  },
+  onCancel: (data) => {
+    // Called when the path is cancelled
+    console.log("Course creation cancelled");
+  }
 };
 ```
 
 | Type | Description |
 |------|-------------|
-| `PathDefinition<TData>` | A path's ID, title, and ordered list of step definitions. |
+| `PathDefinition<TData>` | A path's ID, title, ordered list of step definitions, and optional `onComplete` / `onCancel` callbacks. |
 | `PathStep<TData>` | A single step: guards, lifecycle hooks. |
 | `PathStepContext<TData>` | Passed to every hook and guard. `data` is a **readonly snapshot copy** — return a patch to update state. |
 | `PathSnapshot<TData>` | Point-in-time read of the engine: step ID, index, count, flags, and a copy of data. |
 | `PathEvent` | Union of `stateChanged` (includes `cause`), `completed`, `cancelled`, and `resumed`. |
-| `StateChangeCause` | Identifies the method that triggered a `stateChanged` event: `"start"` \| `"next"` \| `"previous"` \| `"goToStep"` \| `"goToStepChecked"` \| `"setData"` \| `"cancel"` \| `"restart"`. |
+| `StateChangeCause` | Identifies the method that triggered a `stateChanged` event: `"start"` \| `"next"` \| `"previous"` \| `"goToStep"` \| `"goToStepChecked"` \| `"setData"` \| `"resetStep"` \| `"cancel"` \| `"restart"`. |
 | `PathObserver` | `(event: PathEvent, engine: PathEngine) => void` — a function registered at construction time that receives every event for the engine's lifetime. |
 | `PathEngineOptions` | `{ observers?: PathObserver[] }` — options accepted by the `PathEngine` constructor and `PathEngine.fromState()`. |
 | `ObserverStrategy` | Union type for the five built-in trigger strategies: `"onEveryChange" \| "onNext" \| "onSubPathComplete" \| "onComplete" \| "manual"`. Import and use in your own observer factories. |
@@ -83,10 +115,15 @@ engine.next();
 engine.previous();
 engine.cancel();
 engine.setData(key, value);                // update a single data value; emits stateChanged
-engine.goToStep(stepId);                   // jump to step by ID; bypasses guards and shouldSkip
+engine.resetStep();                        // revert current step data to what it was on entry; emits stateChanged
 engine.goToStepChecked(stepId);            // jump to step by ID; checks canMoveNext / canMovePrevious first
 engine.snapshot();                         // returns PathSnapshot | null
 
+// Key PathSnapshot fields
+snapshot.isDirty                           // true if any data changed since entering this step (resets on navigation or resetStep)
+snapshot.hasAttemptedNext                  // true after user clicks Next at least once on this step
+snapshot.stepEnteredAt                     // Date.now() timestamp when step was entered (for analytics, timeout warnings)
+
 // Serialization API (for persistence)
 const state = engine.exportState();        // returns SerializedPathState | null
 const restoredEngine = PathEngine.fromState(state, pathDefinitions, { observers: [...] });
@@ -449,10 +486,20 @@ function ReviewStep() {
 ### What the Shell Renders During Sub-Paths
 
 When a sub-path is active:
-- Progress bar shows sub-path steps (parent steps disappear)
+- The **root progress bar** stays visible (compact, muted) above the sub-path's progress bar so users always see their place in the main flow
+- The main progress bar shows the sub-path's steps
 - Back button on sub-path's first step cancels the sub-path
 - Completing the sub-path returns to parent (parent step re-renders)
 
+The snapshot includes `rootProgress` (type `RootProgress`) when `nestingLevel > 0`:
+
+```typescript
+if (snapshot.rootProgress) {
+  // { pathId, stepIndex, stepCount, progress, steps }
+  console.log(`Main flow: step ${snapshot.rootProgress.stepIndex + 1} of ${snapshot.rootProgress.stepCount}`);
+}
+```
+
 ### Nesting Levels
 
 Sub-paths can themselves start sub-paths (unlimited nesting). Use `snapshot.nestingLevel` to determine depth:
@@ -519,3 +566,8 @@ Throws if:
 
 The restored engine is fully functional — you can continue navigation, modify data, complete or cancel paths normally.
 ```
+
+---
+
+© 2026 Devjoy Ltd. MIT License.
+

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 export type PathData = Record<string, unknown>;
 /**
- * The return type of a `fieldMessages` hook. Each key is a field ID; the value
+ * The return type of a `fieldErrors` hook. Each key is a field ID; the value
  * is an error string, or `undefined` / omitted to indicate no error for that field.
  *
  * Use `"_"` as a key for form-level errors that don't belong to a specific field:
@@ -16,12 +16,16 @@ export interface SerializedPathState {
     data: PathData;
     visitedStepIds: string[];
     subPathMeta?: Record<string, unknown>;
+    stepEntryData?: PathData;
+    stepEnteredAt?: number;
     pathStack: Array<{
         pathId: string;
         currentStepIndex: number;
         data: PathData;
         visitedStepIds: string[];
         subPathMeta?: Record<string, unknown>;
+        stepEntryData?: PathData;
+        stepEnteredAt?: number;
     }>;
     _isNavigating: boolean;
 }
@@ -51,6 +55,45 @@ export interface PathStepContext<TData extends PathData = PathData> {
      */
     readonly isFirstEntry: boolean;
 }
+/**
+ * A conditional step selection placed in a path's `steps` array in place of a
+ * single `PathStep`. When the engine reaches a `StepChoice` it calls `select`
+ * to decide which of the bundled `steps` to activate. The chosen step is then
+ * treated exactly like any other step — its hooks, guards, and validation all
+ * apply normally.
+ *
+ * `StepChoice` has its own `id` (used for progress tracking and `goToStep`)
+ * while `formId` on the snapshot exposes which inner step was selected, so the
+ * UI can render the right component.
+ *
+ * @example
+ * ```typescript
+ * {
+ *   id: "contact-details",
+ *   select: ({ data }) => data.accountType === "company" ? "company" : "individual",
+ *   steps: [
+ *     {
+ *       id: "individual",
+ *       fieldErrors: ({ data }) => ({ name: !data.name ? "Required." : undefined }),
+ *     },
+ *     {
+ *       id: "company",
+ *       fieldErrors: ({ data }) => ({ companyName: !data.companyName ? "Required." : undefined }),
+ *     },
+ *   ],
+ * }
+ * ```
+ */
+export interface StepChoice<TData extends PathData = PathData> {
+    id: string;
+    title?: string;
+    meta?: Record<string, unknown>;
+    /** Called on step entry. Return the `id` of the step to activate. Throws if the returned id is not found in `steps`. */
+    select: (ctx: PathStepContext<TData>) => string;
+    steps: PathStep<TData>[];
+    /** When `true`, the engine skips this choice slot entirely (same semantics as `PathStep.shouldSkip`). */
+    shouldSkip?: (ctx: PathStepContext<TData>) => boolean | Promise<boolean>;
+}
 export interface PathStep<TData extends PathData = PathData> {
     id: string;
     title?: string;
@@ -64,7 +107,7 @@ export interface PathStep<TData extends PathData = PathData> {
      * by field name) so consumers do not need to duplicate validation logic in
      * the template. Return `undefined` for a field to indicate no error.
      *
-     * When `fieldMessages` is provided and `canMoveNext` is **not**, the engine
+     * When `fieldErrors` is provided and `canMoveNext` is **not**, the engine
      * automatically derives `canMoveNext` as `true` when all values are `undefined`
      * (i.e. no messages), eliminating the need to express the same logic twice.
      *
@@ -72,13 +115,29 @@ export interface PathStep<TData extends PathData = PathData> {
      *
      * @example
      * ```typescript
-     * fieldMessages: ({ data }) => ({
+     * fieldErrors: ({ data }) => ({
      *   name:  !data.name?.trim()        ? "Required."             : undefined,
      *   email: !isValidEmail(data.email) ? "Invalid email address." : undefined,
      * })
      * ```
      */
-    fieldMessages?: (ctx: PathStepContext<TData>) => FieldErrors;
+    fieldErrors?: (ctx: PathStepContext<TData>) => FieldErrors;
+    /**
+     * Returns a map of field ID → warning message for non-blocking advisories.
+     * Same shape as `fieldErrors`, but warnings never affect `canMoveNext` —
+     * they are purely informational. Shells render them in amber/yellow instead
+     * of red.
+     *
+     * Evaluated synchronously on every snapshot; async functions default to `{}`.
+     *
+     * @example
+     * ```typescript
+     * fieldWarnings: ({ data }) => ({
+     *   email: looksLikeTypo(data.email) ? "Did you mean gmail.com?" : undefined,
+     * })
+     * ```
+     */
+    fieldWarnings?: (ctx: PathStepContext<TData>) => FieldErrors;
     onEnter?: (ctx: PathStepContext<TData>) => Partial<TData> | void | Promise<Partial<TData> | void>;
     onLeave?: (ctx: PathStepContext<TData>) => Partial<TData> | void | Promise<Partial<TData> | void>;
     /**
@@ -101,7 +160,20 @@ export interface PathStep<TData extends PathData = PathData> {
 export interface PathDefinition<TData extends PathData = PathData> {
     id: string;
     title?: string;
-    steps: PathStep<TData>[];
+    steps: (PathStep<TData> | StepChoice<TData>)[];
+    /**
+     * Optional callback invoked when this path completes (i.e. the user
+     * reaches the end of the last step). Receives the final path data.
+     * Only called for top-level paths — sub-path completion is handled by
+     * the parent step's `onSubPathComplete` hook.
+     */
+    onComplete?: (data: TData) => void | Promise<void>;
+    /**
+     * Optional callback invoked when this path is cancelled. Receives the
+     * path data at the time of cancellation. Only called for top-level paths —
+     * sub-path cancellation is handled by the parent step's `onSubPathCancel` hook.
+     */
+    onCancel?: (data: TData) => void | Promise<void>;
 }
 export type StepStatus = "completed" | "current" | "upcoming";
 export interface StepSummary {
@@ -110,11 +182,42 @@ export interface StepSummary {
     meta?: Record<string, unknown>;
     status: StepStatus;
 }
+/**
+ * Controls how the shell renders progress bars when a sub-path is active.
+ *
+ * | Value          | Behaviour                                                              |
+ * |----------------|------------------------------------------------------------------------|
+ * | `"merged"`     | Root and sub-path bars in one card (default)                           |
+ * | `"split"`      | Root and sub-path bars as separate cards                               |
+ * | `"rootOnly"`   | Only the root bar — sub-path bar hidden                                |
+ * | `"activeOnly"` | Only the active (sub-path) bar — root bar hidden (pre-v0.7 behaviour) |
+ */
+export type ProgressLayout = "merged" | "split" | "rootOnly" | "activeOnly";
+/**
+ * Summary of the root (top-level) path's progress. Present on `PathSnapshot`
+ * only when `nestingLevel > 0` — i.e. a sub-path is active.
+ *
+ * Shells use this to keep the top-level progress bar visible while navigating
+ * a sub-path, so users never lose sight of where they are in the main flow.
+ */
+export interface RootProgress {
+    pathId: string;
+    stepIndex: number;
+    stepCount: number;
+    progress: number;
+    steps: StepSummary[];
+}
 export interface PathSnapshot<TData extends PathData = PathData> {
     pathId: string;
     stepId: string;
     stepTitle?: string;
     stepMeta?: Record<string, unknown>;
+    /**
+     * The `id` of the selected inner `PathStep` when the current position in
+     * the path is a `StepChoice`. `undefined` for ordinary steps.
+     * Use this to decide which form component to render.
+     */
+    formId?: string;
     stepIndex: number;
     stepCount: number;
     progress: number;
@@ -122,9 +225,15 @@ export interface PathSnapshot<TData extends PathData = PathData> {
     isFirstStep: boolean;
     isLastStep: boolean;
     nestingLevel: number;
+    /**
+     * Progress summary of the root (top-level) path. Only present when
+     * `nestingLevel > 0`. Shells use this to render a persistent top-level
+     * 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;
-    /** Whether the current step's `canMoveNext` guard allows advancing. Async guards default to `true`. Auto-derived as `true` when `fieldMessages` is defined and returns no messages, and `canMoveNext` is not explicitly defined. */
+    /** 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`. */
     canMovePrevious: boolean;
@@ -137,28 +246,64 @@ export interface PathSnapshot<TData extends PathData = PathData> {
      * render and only appear after the user has attempted to proceed:
      *
      * ```svelte
-     * {#if snapshot.hasAttemptedNext && snapshot.fieldMessages.email}
-     *   <span class="error">{snapshot.fieldMessages.email}</span>
+     * {#if snapshot.hasAttemptedNext && snapshot.fieldErrors.email}
+     *   <span class="error">{snapshot.fieldErrors.email}</span>
      * {/if}
      * ```
      *
-     * The shell itself uses this flag to gate its own automatic `fieldMessages`
+     * The shell itself uses this flag to gate its own automatic `fieldErrors`
      * summary rendering — errors are never shown before the first Next attempt.
      */
     hasAttemptedNext: boolean;
+    /**
+     * True if any data has changed since entering this step. Automatically computed
+     * by comparing the current data to the snapshot taken on step entry. Resets to
+     * `false` when navigating to a new step or calling `resetStep()`.
+     *
+     * Useful for "unsaved changes" warnings, disabling Save buttons until changes
+     * are made, or styling forms to indicate modifications.
+     *
+     * ```typescript
+     * {#if snapshot.isDirty}
+     *   <span class="warning">You have unsaved changes</span>
+     * {/if}
+     * ```
+     */
+    isDirty: boolean;
+    /**
+     * Timestamp (from `Date.now()`) captured when the current step was entered.
+     * Useful for analytics, timeout warnings, or computing how long a user has
+     * been on a step.
+     *
+     * ```typescript
+     * const durationMs = Date.now() - snapshot.stepEnteredAt;
+     * const durationSec = Math.floor(durationMs / 1000);
+     * ```
+     *
+     * Resets to a new timestamp each time the step is entered (including when
+     * navigating back to a previously visited step).
+     */
+    stepEnteredAt: number;
     /**
      * 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.fieldMessages['email']`.
+     * Use in step templates to render inline per-field errors: `snapshot.fieldErrors['email']`.
      * The shell also renders these automatically in a labeled summary box.
      * Use `"_"` as a key for form-level (non-field-specific) errors.
      */
-    fieldMessages: Record<string, string>;
+    fieldErrors: Record<string, string>;
+    /**
+     * Field-keyed warning messages for the current step. Empty object when there are none.
+     * Same shape as `fieldErrors` but purely informational — warnings never block navigation.
+     * Shells render these in amber/yellow instead of red.
+     * Use `"_"` as a key for form-level (non-field-specific) warnings.
+     */
+    fieldWarnings: Record<string, string>;
     data: TData;
 }
 /**
  * Identifies the public method that triggered a `stateChanged` event.
  */
-export type StateChangeCause = "start" | "next" | "previous" | "goToStep" | "goToStepChecked" | "setData" | "cancel" | "restart";
+export type StateChangeCause = "start" | "next" | "previous" | "goToStep" | "goToStepChecked" | "setData" | "resetStep" | "cancel" | "restart";
 export type PathEvent = {
     type: "stateChanged";
     cause: StateChangeCause;
@@ -286,6 +431,13 @@ export declare class PathEngine {
      *  API consistency. */
     cancel(): Promise<void>;
     setData(key: string, value: unknown): Promise<void>;
+    /**
+     * Resets the current step's data to what it was when the step was entered.
+     * Useful for "Clear" or "Reset" buttons that undo changes within a step.
+     * Emits a `stateChanged` event with cause `"resetStep"`.
+     * Throws if no path is active.
+     */
+    resetStep(): Promise<void>;
     /** Jumps directly to the step with the given ID. Does not check guards or shouldSkip. */
     goToStep(stepId: string): Promise<void>;
     /**
@@ -323,7 +475,20 @@ export declare class PathEngine {
     private assertPathHasSteps;
     private emit;
     private emitStateChanged;
-    private getCurrentStep;
+    /** Returns the raw item at the current index — either a PathStep or a StepChoice. */
+    private getCurrentItem;
+    /**
+     * Calls `StepChoice.select` and caches the chosen inner step in
+     * `active.resolvedChoiceStep`. Clears the cache when the current item is a
+     * plain `PathStep`. Throws if `select` returns an id not present in `steps`.
+     */
+    private cacheResolvedChoiceStep;
+    /**
+     * Returns the effective `PathStep` for the current position. When the
+     * current item is a `StepChoice`, returns the cached resolved inner step.
+     * When it is a plain `PathStep`, returns it directly.
+     */
+    private getEffectiveStep;
     private applyPatch;
     private skipSteps;
     private enterCurrentStep;
@@ -348,18 +513,26 @@ export declare class PathEngine {
     /**
      * Evaluates `canMoveNext` synchronously for inclusion in the snapshot.
      * When `canMoveNext` is defined, delegates to `evaluateGuardSync`.
-     * When absent but `fieldMessages` is defined, auto-derives: `true` iff no messages.
+     * When absent but `fieldErrors` is defined, auto-derives: `true` iff no messages.
      * When neither is defined, returns `true`.
      */
     private evaluateCanMoveNextSync;
     /**
-     * Evaluates a fieldMessages function synchronously for inclusion in the snapshot.
+     * Evaluates a fieldErrors function synchronously for inclusion in the snapshot.
      * If the hook is absent, returns `{}`.
      * If the hook returns a `Promise`, returns `{}` (async hooks are not supported in snapshots).
      * `undefined` values are stripped from the result — only fields with a defined message are included.
      *
-     * **Note:** Like guards, `fieldMessages` is evaluated before `onEnter` runs on first
+     * **Note:** Like guards, `fieldErrors` is evaluated before `onEnter` runs on first
      * entry. Write it defensively so it does not throw when fields are absent.
      */
     private evaluateFieldMessagesSync;
+    /**
+     * Compares the current step data to the snapshot taken when the step was entered.
+     * Returns `true` if any data value has changed.
+     *
+     * Performs a shallow comparison — only top-level keys are checked. Nested objects
+     * are compared by reference, not by deep equality.
+     */
+    private computeIsDirty;
 }