@daltonr/pathwrite-angular 0.9.0 → 0.10.1

package/src/index.ts

@@ -98,6 +98,16 @@ export class PathFacade<TData extends PathData = PathData> implements OnDestroy
     return this._engine.restart();
   }
 
+  /** Re-runs the operation that set `snapshot().error`. Increments `retryCount` on repeated failure. No-op when there is no pending error. */
+  public retry(): Promise<void> {
+    return this._engine.retry();
+  }
+
+  /** Pauses the path with intent to return. Emits `suspended`. All state is preserved. */
+  public suspend(): Promise<void> {
+    return this._engine.suspend();
+  }
+
   public startSubPath(path: PathDefinition<any>, initialData: PathData = {}, meta?: Record<string, unknown>): Promise<void> {
     return this._engine.startSubPath(path, initialData, meta);
   }
@@ -141,15 +151,15 @@ export class PathFacade<TData extends PathData = PathData> implements OnDestroy
 }
 
 // ---------------------------------------------------------------------------
-// injectPath() - Signal-based path access
+// usePathContext() - Signal-based path access
 // ---------------------------------------------------------------------------
 
 /**
- * Return type of `injectPath()`. Provides signal-based reactive access to the
+ * Return type of `usePathContext()`. Provides signal-based reactive access to the
  * path state and strongly-typed navigation actions. Mirrors React's `usePathContext()`
  * return type for consistency across adapters.
  */
-export interface InjectPathReturn<TData extends PathData = PathData> {
+export interface UsePathContextReturn<TData extends PathData = PathData> {
   /** Current path snapshot as a signal. Returns `null` when no path is active. */
   snapshot: Signal<PathSnapshot<TData> | null>;
   /** Start (or restart) a path. */
@@ -175,16 +185,20 @@ export interface InjectPathReturn<TData extends PathData = PathData> {
    * Use for "Start over" / retry flows.
    */
   restart: () => Promise<void>;
+  /** Re-run the operation that set `snapshot().error`. */
+  retry: () => Promise<void>;
+  /** Pause with intent to return, preserving all state. Emits `suspended`. */
+  suspend: () => Promise<void>;
 }
 
 /**
- * Inject a PathFacade and return a signal-based API for use in Angular components.
+ * Access the nearest `PathFacade`'s path instance for use in Angular step components.
  * Requires `PathFacade` to be provided in the component's injector tree (either via
  * `providers: [PathFacade]` in the component or a parent component).
  *
  * **This is the recommended way to consume Pathwrite in Angular components** — it
- * provides the same ergonomic, framework-native API that React's `usePathContext()`
- * and Vue's `usePath()` offer. No template references or manual facade injection needed.
+ * provides the same ergonomic API as React's `usePathContext()` and Vue's `usePathContext()`.
+ * No template references or manual facade injection needed.
  *
  * The optional generic `TData` narrows `snapshot().data` and `setData()` to your
  * data shape. It is a **type-level assertion**, not a runtime guarantee.
@@ -203,7 +217,7 @@ export interface InjectPathReturn<TData extends PathData = PathData> {
  *   `
  * })
  * export class ContactStepComponent {
- *   protected readonly path = injectPath<ContactData>();
+ *   protected readonly path = usePathContext<ContactData>();
  *
  *   updateName(name: string) {
  *     this.path.setData('name', name);
@@ -213,12 +227,12 @@ export interface InjectPathReturn<TData extends PathData = PathData> {
  *
  * @throws Error if PathFacade is not provided in the injector tree
  */
-export function injectPath<TData extends PathData = PathData>(): InjectPathReturn<TData> {
+export function usePathContext<TData extends PathData = PathData>(): UsePathContextReturn<TData> {
   const facade = inject(PathFacade, { optional: true }) as PathFacade<TData> | null;
-  
+
   if (!facade) {
     throw new Error(
-      "injectPath() requires PathFacade to be provided. " +
+      "usePathContext() requires PathFacade to be provided. " +
       "Add 'providers: [PathFacade]' to your component or a parent component."
     );
   }
@@ -235,6 +249,8 @@ export function injectPath<TData extends PathData = PathData>(): InjectPathRetur
     goToStep: (stepId) => facade.goToStep(stepId),
     goToStepChecked: (stepId) => facade.goToStepChecked(stepId),
     restart: () => facade.restart(),
+    retry: () => facade.retry(),
+    suspend: () => facade.suspend(),
   };
 }
 

package/src/shell.ts

@@ -26,7 +26,9 @@ import {
   PathEvent,
   PathSnapshot,
   ProgressLayout,
-  RootProgress
+  RootProgress,
+  formatFieldKey,
+  errorPhaseMessage,
 } from "@daltonr/pathwrite-core";
 import { PathFacade } from "./index";
 
@@ -48,6 +50,10 @@ export interface PathShellActions {
   setData: (key: string, value: unknown) => Promise<void>;
   /** Restart the shell's current path with its current `initialData`. */
   restart: () => Promise<void>;
+  /** Re-run the operation that set `snapshot.error`. */
+  retry: () => Promise<void>;
+  /** Pause with intent to return, preserving all state. Emits `suspended`. */
+  suspend: () => Promise<void>;
 }
 
 // ---------------------------------------------------------------------------
@@ -216,10 +222,43 @@ export class PathShellFooterDirective {
         </li>
       </ul>
 
+      <!-- Blocking error — guard returned { allowed: false, reason } -->
+      <p class="pw-shell__blocking-error"
+         *ngIf="validationDisplay !== 'inline' && s.hasAttemptedNext && s.blockingError">
+        {{ s.blockingError }}
+      </p>
+
+      <!-- Error panel — replaces footer when an async operation has failed -->
+      <div class="pw-shell__error" *ngIf="s.status === 'error' && s.error; else footerOrCustom">
+        <div class="pw-shell__error-title">{{ s.error!.retryCount >= 2 ? 'Still having trouble.' : 'Something went wrong.' }}</div>
+        <div class="pw-shell__error-message">{{ errorPhaseMessage(s.error!.phase) }}{{ s.error!.message ? ' ' + s.error!.message : '' }}</div>
+        <div class="pw-shell__error-actions">
+          <button
+            *ngIf="s.error!.retryCount < 2"
+            type="button"
+            class="pw-shell__btn pw-shell__btn--retry"
+            (click)="facade.retry()"
+          >Try again</button>
+          <button
+            *ngIf="s.hasPersistence"
+            type="button"
+            [class]="'pw-shell__btn ' + (s.error!.retryCount >= 2 ? 'pw-shell__btn--retry' : 'pw-shell__btn--suspend')"
+            (click)="facade.suspend()"
+          >Save and come back later</button>
+          <button
+            *ngIf="s.error!.retryCount >= 2 && !s.hasPersistence"
+            type="button"
+            class="pw-shell__btn pw-shell__btn--retry"
+            (click)="facade.retry()"
+          >Try again</button>
+        </div>
+      </div>
       <!-- Footer — custom or default navigation buttons -->
-      <ng-container *ngIf="customFooter; else defaultFooter">
-        <ng-container *ngTemplateOutlet="customFooter.templateRef; context: { $implicit: s, actions: shellActions }"></ng-container>
-      </ng-container>
+      <ng-template #footerOrCustom>
+        <ng-container *ngIf="customFooter; else defaultFooter">
+          <ng-container *ngTemplateOutlet="customFooter.templateRef; context: { $implicit: s, actions: shellActions }"></ng-container>
+        </ng-container>
+      </ng-template>
       <ng-template #defaultFooter>
         <div class="pw-shell__footer">
           <div class="pw-shell__footer-left">
@@ -228,7 +267,7 @@ export class PathShellFooterDirective {
               *ngIf="getResolvedFooterLayout(s) === 'form' && !hideCancel"
               type="button"
               class="pw-shell__btn pw-shell__btn--cancel"
-              [disabled]="s.isNavigating"
+              [disabled]="s.status !== 'idle'"
               (click)="facade.cancel()"
             >{{ cancelLabel }}</button>
             <!-- Wizard mode: Back on the left -->
@@ -236,7 +275,7 @@ export class PathShellFooterDirective {
               *ngIf="getResolvedFooterLayout(s) === 'wizard' && !s.isFirstStep"
               type="button"
               class="pw-shell__btn pw-shell__btn--back"
-              [disabled]="s.isNavigating || !s.canMovePrevious"
+              [disabled]="s.status !== 'idle' || !s.canMovePrevious"
               (click)="facade.previous()"
             >{{ backLabel }}</button>
           </div>
@@ -246,16 +285,17 @@ export class PathShellFooterDirective {
               *ngIf="getResolvedFooterLayout(s) === 'wizard' && !hideCancel"
               type="button"
               class="pw-shell__btn pw-shell__btn--cancel"
-              [disabled]="s.isNavigating"
+              [disabled]="s.status !== 'idle'"
               (click)="facade.cancel()"
             >{{ cancelLabel }}</button>
             <!-- Both modes: Submit on the right -->
             <button
               type="button"
               class="pw-shell__btn pw-shell__btn--next"
-              [disabled]="s.isNavigating"
+              [class.pw-shell__btn--loading]="s.status !== 'idle'"
+              [disabled]="s.status !== 'idle'"
               (click)="facade.next()"
-            >{{ s.isLastStep ? completeLabel : nextLabel }}</button>
+            >{{ s.status !== 'idle' && loadingLabel ? loadingLabel : s.isLastStep ? completeLabel : nextLabel }}</button>
           </div>
         </div>
       </ng-template>
@@ -290,6 +330,8 @@ export class PathShellComponent implements OnInit, OnChanges, OnDestroy {
   @Input() nextLabel = "Next";
   /** Label for the Next button when on the last step. */
   @Input() completeLabel = "Complete";
+  /** Label shown on the Next/Complete button while an async operation is in progress. When undefined, the button keeps its label and shows a CSS spinner only. */
+  @Input() loadingLabel?: string;
   /** Label for the Cancel button. */
   @Input() cancelLabel = "Cancel";
   /** Hide the Cancel button entirely. */
@@ -342,6 +384,8 @@ export class PathShellComponent implements OnInit, OnChanges, OnDestroy {
     goToStepChecked: (id) => this.facade.goToStepChecked(id),
     setData: (key, value) => this.facade.setData(key, value as never),
     restart: () => this.facade.restart(),
+    retry: () => this.facade.retry(),
+    suspend: () => this.facade.suspend(),
   };
 
   private readonly destroy$ = new Subject<void>();
@@ -405,9 +449,6 @@ export class PathShellComponent implements OnInit, OnChanges, OnDestroy {
       : this.footerLayout;
   }
 
-  /** Converts a camelCase or lowercase field key to a display label.
-   *  e.g. "firstName" → "First Name", "email" → "Email" */
-  protected formatFieldKey(key: string): string {
-    return key.replace(/([A-Z])/g, " $1").replace(/^./, c => c.toUpperCase()).trim();
-  }
+  protected errorPhaseMessage = errorPhaseMessage;
+  protected formatFieldKey = formatFieldKey;
 }