@daltonr/pathwrite-angular 0.11.0 → 0.12.0

package/src/index.ts

@@ -30,6 +30,13 @@ export class PathFacade<TData extends PathData = PathData> implements OnDestroy
   private _unsubscribeFromEngine: () => void = () => {};
   private readonly _stateSignal = signal<PathSnapshot<TData> | null>(null);
 
+  /**
+   * Arbitrary services object passed via `[services]` on `<pw-shell>`.
+   * Read it in step components via `usePathContext<TData, TServices>().services`.
+   * Set directly by `PathShellComponent` — do not set this manually.
+   */
+  public services: unknown = null;
+
   public readonly state$: Observable<PathSnapshot<TData> | null> = this._state$.asObservable();
   public readonly events$: Observable<PathEvent> = this._events$.asObservable();
   /** Signal version of state$. Updates on every path state change. Requires Angular 16+. */
@@ -72,8 +79,9 @@ export class PathFacade<TData extends PathData = PathData> implements OnDestroy
         this._state$.next(event.snapshot as PathSnapshot<TData>);
         this._stateSignal.set(event.snapshot as PathSnapshot<TData>);
       } else if (event.type === "completed" || event.type === "cancelled") {
-        this._state$.next(null);
-        this._stateSignal.set(null);
+        const snap = engine.snapshot() as PathSnapshot<TData> | null;
+        this._state$.next(snap);
+        this._stateSignal.set(snap);
       }
     });
   }
@@ -134,15 +142,15 @@ export class PathFacade<TData extends PathData = PathData> implements OnDestroy
     return this._engine.resetStep();
   }
 
-  public goToStep(stepId: string): Promise<void> {
-    return this._engine.goToStep(stepId);
+  public goToStep(stepId: string, options?: { validateOnLeave?: boolean }): Promise<void> {
+    return this._engine.goToStep(stepId, options);
   }
 
   /** Jump to a step by ID, checking the current step's canMoveNext (forward) or
    *  canMovePrevious (backward) guard first. Navigation is blocked if the guard
    *  returns false. Throws if the step ID does not exist. */
-  public goToStepChecked(stepId: string): Promise<void> {
-    return this._engine.goToStepChecked(stepId);
+  public goToStepChecked(stepId: string, options?: { validateOnLeave?: boolean }): Promise<void> {
+    return this._engine.goToStepChecked(stepId, options);
   }
 
   public validate(): void {
@@ -163,7 +171,7 @@ export class PathFacade<TData extends PathData = PathData> implements OnDestroy
  * path state and strongly-typed navigation actions. Mirrors React's `usePathContext()`
  * return type for consistency across adapters.
  */
-export interface UsePathContextReturn<TData extends PathData = PathData> {
+export interface UsePathContextReturn<TData extends PathData = PathData, TServices = unknown> {
   /** Current path snapshot as a signal. Returns `null` when no path is active. */
   snapshot: Signal<PathSnapshot<TData> | null>;
   /** Start (or restart) a path. */
@@ -180,10 +188,10 @@ export interface UsePathContextReturn<TData extends PathData = PathData> {
   setData: <K extends string & keyof TData>(key: K, value: TData[K]) => Promise<void>;
   /** Reset the current step's data to what it was when the step was entered. */
   resetStep: () => Promise<void>;
-  /** Jump to a step by ID without checking guards. */
-  goToStep: (stepId: string) => Promise<void>;
+  /** Jump to a step by ID without checking guards. Pass `{ validateOnLeave: true }` to mark the departing step as attempted before navigating. */
+  goToStep: (stepId: string, options?: { validateOnLeave?: boolean }) => Promise<void>;
   /** Jump to a step by ID, checking guards first. */
-  goToStepChecked: (stepId: string) => Promise<void>;
+  goToStepChecked: (stepId: string, options?: { validateOnLeave?: boolean }) => Promise<void>;
   /**
    * Tears down any active path and immediately starts the given path fresh.
    * Use for "Start over" / retry flows.
@@ -193,6 +201,12 @@ export interface UsePathContextReturn<TData extends PathData = PathData> {
   retry: () => Promise<void>;
   /** Pause with intent to return, preserving all state. Emits `suspended`. */
   suspend: () => Promise<void>;
+  /**
+   * The services object passed to the nearest `<pw-shell>` via `[services]`.
+   * Typed as `TServices` — pass your services interface as the second generic:
+   * `usePathContext<MyData, MyServices>().services`.
+   */
+  services: TServices;
 }
 
 /**
@@ -231,7 +245,7 @@ export interface UsePathContextReturn<TData extends PathData = PathData> {
  *
  * @throws Error if PathFacade is not provided in the injector tree
  */
-export function usePathContext<TData extends PathData = PathData>(): UsePathContextReturn<TData> {
+export function usePathContext<TData extends PathData = PathData, TServices = unknown>(): UsePathContextReturn<TData, TServices> {
   const facade = inject(PathFacade, { optional: true }) as PathFacade<TData> | null;
 
   if (!facade) {
@@ -250,11 +264,12 @@ export function usePathContext<TData extends PathData = PathData>(): UsePathCont
     cancel: () => facade.cancel(),
     setData: (key, value) => facade.setData(key, value),
     resetStep: () => facade.resetStep(),
-    goToStep: (stepId) => facade.goToStep(stepId),
-    goToStepChecked: (stepId) => facade.goToStepChecked(stepId),
+    goToStep: (stepId, options) => facade.goToStep(stepId, options),
+    goToStepChecked: (stepId, options) => facade.goToStepChecked(stepId, options),
     restart: () => facade.restart(),
     retry: () => facade.retry(),
     suspend: () => facade.suspend(),
+    services: facade.services as TServices,
   };
 }
 

package/src/shell.ts

@@ -45,8 +45,8 @@ export interface PathShellActions {
   next: () => Promise<void>;
   previous: () => Promise<void>;
   cancel: () => Promise<void>;
-  goToStep: (stepId: string) => Promise<void>;
-  goToStepChecked: (stepId: string) => Promise<void>;
+  goToStep: (stepId: string, options?: { validateOnLeave?: boolean }) => Promise<void>;
+  goToStepChecked: (stepId: string, options?: { validateOnLeave?: boolean }) => Promise<void>;
   setData: (key: string, value: unknown) => Promise<void>;
   /** Restart the shell's current path with its current `initialData`. */
   restart: () => Promise<void>;
@@ -127,6 +127,31 @@ export class PathShellFooterDirective {
   ) {}
 }
 
+// ---------------------------------------------------------------------------
+// PathShellCompletionDirective
+// ---------------------------------------------------------------------------
+
+/**
+ * Replaces the default completion panel inside `<pw-shell>` when
+ * `snapshot.status === "completed"` (`completionBehaviour: "stayOnFinal"`).
+ * The template receives the current `PathSnapshot` as the implicit context.
+ *
+ * ```html
+ * <pw-shell [path]="myPath">
+ *   <ng-template pwShellCompletion let-s>
+ *     <my-completion-screen [data]="s.data" />
+ *   </ng-template>
+ *   <ng-template pwStep="details"><app-details-form /></ng-template>
+ * </pw-shell>
+ * ```
+ */
+@Directive({ selector: "[pwShellCompletion]", standalone: true })
+export class PathShellCompletionDirective {
+  public constructor(
+    public readonly templateRef: TemplateRef<{ $implicit: PathSnapshot }>
+  ) {}
+}
+
 // ---------------------------------------------------------------------------
 // PathShellComponent
 // ---------------------------------------------------------------------------
@@ -160,7 +185,7 @@ export class PathShellFooterDirective {
     <!-- Active path -->
     <div class="pw-shell" [ngClass]="progressLayout !== 'merged' ? 'pw-shell--progress-' + progressLayout : ''" *ngIf="facade.state$ | async as s">
       <!-- Root progress — persistent top-level bar visible during sub-paths -->
-      <div class="pw-shell__root-progress" *ngIf="!hideProgress && s.rootProgress && progressLayout !== 'activeOnly'">
+      <div class="pw-shell__root-progress" *ngIf="!effectiveHideProgress && s.rootProgress && progressLayout !== 'activeOnly'">
         <div class="pw-shell__steps">
           <div
             *ngFor="let step of s.rootProgress!.steps; let i = index"
@@ -181,7 +206,7 @@ export class PathShellFooterDirective {
         <ng-container *ngTemplateOutlet="customHeader.templateRef; context: { $implicit: s }"></ng-container>
       </ng-container>
       <ng-template #defaultHeader>
-        <div class="pw-shell__header" *ngIf="!hideProgress && (s.stepCount > 1 || s.nestingLevel > 0) && progressLayout !== 'rootOnly'">
+        <div class="pw-shell__header" *ngIf="!effectiveHideProgress && (s.stepCount > 1 || s.nestingLevel > 0) && progressLayout !== 'rootOnly'">
           <div class="pw-shell__steps">
             <div
               *ngFor="let step of s.steps; let i = index"
@@ -198,75 +223,91 @@ export class PathShellFooterDirective {
         </div>
       </ng-template>
 
-      <!-- Body — step content -->
-      <div class="pw-shell__body">
-        <ng-container *ngFor="let stepDir of stepDirectives">
-          <!-- Match by formId first (inner step of a StepChoice), then stepId -->
-          <ng-container *ngIf="stepDir.stepId === (s.formId ?? s.stepId)">
-            <ng-container *ngTemplateOutlet="stepDir.templateRef; injector: shellInjector"></ng-container>
-          </ng-container>
+      <!-- Completion panel — shown when path finishes with stayOnFinal -->
+      <ng-container *ngIf="s.status === 'completed'; else activeContent">
+        <ng-container *ngIf="customCompletion; else defaultCompletion">
+          <ng-container *ngTemplateOutlet="customCompletion.templateRef; context: { $implicit: s }"></ng-container>
         </ng-container>
-      </div>
+        <ng-template #defaultCompletion>
+          <div class="pw-shell__completion">
+            <p class="pw-shell__completion-message">All done.</p>
+            <button type="button" class="pw-shell__completion-restart" (click)="facade.restart()">Start over</button>
+          </div>
+        </ng-template>
+      </ng-container>
 
-      <!-- Validation messages — suppressed when validationDisplay="inline" -->
-      <ul class="pw-shell__validation" *ngIf="validationDisplay !== 'inline' && (s.hasAttemptedNext || s.hasValidated) && fieldEntries(s).length > 0">
-        <li *ngFor="let entry of fieldEntries(s)" class="pw-shell__validation-item">
-          <span *ngIf="entry[0] !== '_'" class="pw-shell__validation-label">{{ formatFieldKey(entry[0]) }}</span>{{ entry[1] }}
-        </li>
-      </ul>
-
-      <!-- Warning messages — non-blocking, shown immediately (no hasAttemptedNext gate) -->
-      <ul class="pw-shell__warnings" *ngIf="validationDisplay !== 'inline' && warningEntries(s).length > 0">
-        <li *ngFor="let entry of warningEntries(s)" class="pw-shell__warnings-item">
-          <span *ngIf="entry[0] !== '_'" class="pw-shell__warnings-label">{{ formatFieldKey(entry[0]) }}</span>{{ entry[1] }}
-        </li>
-      </ul>
-
-      <!-- Blocking error — guard returned { allowed: false, reason } -->
-      <p class="pw-shell__blocking-error"
-         *ngIf="validationDisplay !== 'inline' && (s.hasAttemptedNext || s.hasValidated) && 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>
+      <!-- Active step content -->
+      <ng-template #activeContent>
+        <!-- Body — step content -->
+        <div class="pw-shell__body">
+          <ng-container *ngFor="let stepDir of stepDirectives">
+            <!-- Match by formId first (inner step of a StepChoice), then stepId -->
+            <ng-container *ngIf="stepDir.stepId === (s.formId ?? s.stepId)">
+              <ng-container *ngTemplateOutlet="stepDir.templateRef; injector: shellInjector"></ng-container>
+            </ng-container>
+          </ng-container>
         </div>
-      </div>
-      <!-- Footer — custom or default navigation buttons -->
-      <ng-template #footerOrCustom>
-        <ng-container *ngIf="!hideFooter">
-          <ng-container *ngIf="customFooter; else defaultFooter">
-            <ng-container *ngTemplateOutlet="customFooter.templateRef; context: { $implicit: s, actions: shellActions }"></ng-container>
+
+        <!-- Validation messages — suppressed when validationDisplay="inline" -->
+        <ul class="pw-shell__validation" *ngIf="validationDisplay !== 'inline' && (s.hasAttemptedNext || s.hasValidated) && fieldEntries(s).length > 0">
+          <li *ngFor="let entry of fieldEntries(s)" class="pw-shell__validation-item">
+            <span *ngIf="entry[0] !== '_'" class="pw-shell__validation-label">{{ formatFieldKey(entry[0]) }}</span>{{ entry[1] }}
+          </li>
+        </ul>
+
+        <!-- Warning messages — non-blocking, shown immediately (no hasAttemptedNext gate) -->
+        <ul class="pw-shell__warnings" *ngIf="validationDisplay !== 'inline' && warningEntries(s).length > 0">
+          <li *ngFor="let entry of warningEntries(s)" class="pw-shell__warnings-item">
+            <span *ngIf="entry[0] !== '_'" class="pw-shell__warnings-label">{{ formatFieldKey(entry[0]) }}</span>{{ entry[1] }}
+          </li>
+        </ul>
+
+        <!-- Blocking error — guard returned { allowed: false, reason } -->
+        <p class="pw-shell__blocking-error"
+           *ngIf="validationDisplay !== 'inline' && (s.hasAttemptedNext || s.hasValidated) && 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-template #footerOrCustom>
+          <ng-container *ngIf="!effectiveHideFooter">
+            <ng-container *ngIf="customFooter; else defaultFooter">
+              <ng-container *ngTemplateOutlet="customFooter.templateRef; context: { $implicit: s, actions: shellActions }"></ng-container>
+            </ng-container>
           </ng-container>
-        </ng-container>
+        </ng-template>
       </ng-template>
       <ng-template #defaultFooter>
         <div class="pw-shell__footer">
           <div class="pw-shell__footer-left">
             <!-- Form mode: Cancel on the left -->
             <button
-              *ngIf="getResolvedFooterLayout(s) === 'form' && !hideCancel"
+              *ngIf="getResolvedLayout(s) === 'form' && !hideCancel"
               type="button"
               class="pw-shell__btn pw-shell__btn--cancel"
               [disabled]="s.status !== 'idle'"
@@ -274,7 +315,7 @@ export class PathShellFooterDirective {
             >{{ cancelLabel }}</button>
             <!-- Wizard mode: Back on the left -->
             <button
-              *ngIf="getResolvedFooterLayout(s) === 'wizard' && !s.isFirstStep"
+              *ngIf="getResolvedLayout(s) === 'wizard' && !s.isFirstStep"
               type="button"
               class="pw-shell__btn pw-shell__btn--back"
               [disabled]="s.status !== 'idle' || !s.canMovePrevious"
@@ -284,7 +325,7 @@ export class PathShellFooterDirective {
           <div class="pw-shell__footer-right">
             <!-- Wizard mode: Cancel on the right -->
             <button
-              *ngIf="getResolvedFooterLayout(s) === 'wizard' && !hideCancel"
+              *ngIf="getResolvedLayout(s) === 'wizard' && !hideCancel"
               type="button"
               class="pw-shell__btn pw-shell__btn--cancel"
               [disabled]="s.status !== 'idle'"
@@ -322,8 +363,14 @@ export class PathShellComponent implements OnInit, OnChanges, OnDestroy {
    * ```
    */
   @Input() engine?: PathEngine;
-  /** Initial data merged into the path engine on start. */
+  /** Initial data merged into the path engine on start. Used on first visit; overridden by stored snapshot when `restoreKey` is set. */
   @Input() initialData: PathData = {};
+  /**
+   * When set, this shell automatically saves its state into the nearest outer `pw-shell`'s
+   * data under this key on every change, and restores from that stored state on remount.
+   * No-op when used on a top-level shell with no outer `pw-shell` ancestor.
+   */
+  @Input() restoreKey?: string;
   /** Start the path automatically on ngOnInit. Set to false to call doStart() manually. */
   @Input() autoStart = true;
   /** Label for the Back navigation button. */
@@ -345,12 +392,19 @@ export class PathShellComponent implements OnInit, OnChanges, OnDestroy {
   /** When true, calls `validate()` on the facade so all steps show inline errors simultaneously. Useful when this shell is nested inside a step of an outer shell: bind to the outer snapshot's `hasAttemptedNext`. */
   @Input() validateWhen = false;
   /**
-   * Footer layout mode:
+   * Arbitrary services object made available to all step components via
+   * `usePathContext<TData, TServices>().services`. Pass API clients, feature
+   * flags, or any shared dependency without prop-drilling through each step.
+   */
+  @Input() services: unknown = null;
+  /**
+   * Shell layout mode:
    * - "auto" (default): Uses "form" for single-step top-level paths, "wizard" otherwise.
-   * - "wizard": Back button on left, Cancel and Submit together on right.
-   * - "form": Cancel on left, Submit alone on right. Back button never shown.
+   * - "wizard": Progress header + Back button on left, Cancel and Submit together on right.
+   * - "form": Progress header + Cancel on left, Submit alone on right. Back button never shown.
+   * - "tabs": No progress header, no footer. Use for tabbed interfaces with a custom tab bar inside the step body.
    */
-  @Input() footerLayout: "wizard" | "form" | "auto" = "auto";
+  @Input() layout: "wizard" | "form" | "auto" | "tabs" = "auto";
   /**
    * Controls whether the shell renders its auto-generated field-error summary box.
    * - `"summary"` (default): Shell renders the labeled error list below the step body.
@@ -374,11 +428,14 @@ export class PathShellComponent implements OnInit, OnChanges, OnDestroy {
   @ContentChildren(PathStepDirective) stepDirectives!: QueryList<PathStepDirective>;
   @ContentChild(PathShellHeaderDirective) customHeader?: PathShellHeaderDirective;
   @ContentChild(PathShellFooterDirective) customFooter?: PathShellFooterDirective;
+  @ContentChild(PathShellCompletionDirective) customCompletion?: PathShellCompletionDirective;
 
   public readonly facade = inject(PathFacade);
   /** The shell's own component-level injector. Passed to ngTemplateOutlet so that
    *  step components can resolve PathFacade (provided by this shell) via inject(). */
   protected readonly shellInjector = inject(Injector);
+  /** Outer shell's PathFacade — present when this shell is nested inside another pw-shell. */
+  private readonly outerFacade = inject(PathFacade, { skipSelf: true, optional: true });
   public started = false;
 
   /** Navigation actions passed to custom `pwShellFooter` templates. */
@@ -386,8 +443,8 @@ export class PathShellComponent implements OnInit, OnChanges, OnDestroy {
     next: () => this.facade.next(),
     previous: () => this.facade.previous(),
     cancel: () => this.facade.cancel(),
-    goToStep: (id) => this.facade.goToStep(id),
-    goToStepChecked: (id) => this.facade.goToStepChecked(id),
+    goToStep: (id, options) => this.facade.goToStep(id, options),
+    goToStepChecked: (id, options) => this.facade.goToStepChecked(id, options),
     setData: (key, value) => this.facade.setData(key, value as never),
     restart: () => this.facade.restart(),
     retry: () => this.facade.retry(),
@@ -403,13 +460,20 @@ export class PathShellComponent implements OnInit, OnChanges, OnDestroy {
     if (changes['validateWhen'] && this.validateWhen) {
       this.facade.validate();
     }
+    if (changes['services']) {
+      this.facade.services = this.services;
+    }
   }
 
   public ngOnInit(): void {
+    this.facade.services = this.services;
     this.facade.events$.pipe(takeUntil(this.destroy$)).subscribe((event) => {
       this.event.emit(event);
       if (event.type === "completed") this.complete.emit(event.data);
       if (event.type === "cancelled") this.cancel.emit(event.data);
+      if (this.restoreKey && this.outerFacade && event.type === "stateChanged") {
+        this.outerFacade.setData(this.restoreKey as any, (event as any).snapshot as any);
+      }
     });
 
     if (this.autoStart && !this.engine) {
@@ -425,7 +489,18 @@ export class PathShellComponent implements OnInit, OnChanges, OnDestroy {
   public doStart(): void {
     if (!this.path) throw new Error('[pw-shell] [path] is required when no [engine] is provided');
     this.started = true;
-    this.facade.start(this.path, this.initialData);
+    let startData: PathData = this.initialData;
+    let restoreStepId: string | undefined;
+    if (this.restoreKey && this.outerFacade) {
+      const stored = this.outerFacade.snapshot()?.data[this.restoreKey] as PathSnapshot | undefined;
+      if (stored != null && typeof stored === "object" && "stepId" in stored) {
+        startData = stored.data as PathData;
+        if (stored.stepIndex > 0) restoreStepId = stored.stepId as string;
+      }
+    }
+    this.facade.start(this.path, startData).then(() => {
+      if (restoreStepId) this.facade.goToStep(restoreStepId!);
+    });
   }
 
   /**
@@ -451,11 +526,14 @@ export class PathShellComponent implements OnInit, OnChanges, OnDestroy {
     return Object.entries(s.fieldWarnings) as [string, string][];
   }
 
-  /** Resolves "auto" footerLayout based on snapshot. Single-step top-level → "form", otherwise → "wizard". */
-  protected getResolvedFooterLayout(s: PathSnapshot): "wizard" | "form" {
-    return this.footerLayout === "auto"
+  get effectiveHideProgress(): boolean { return this.hideProgress || this.layout === "tabs"; }
+  get effectiveHideFooter(): boolean { return this.hideFooter || this.layout === "tabs"; }
+
+  /** Resolves "auto"/"tabs" layout to "wizard" or "form" for footer button arrangement. */
+  protected getResolvedLayout(s: PathSnapshot): "wizard" | "form" {
+    return this.layout === "auto" || this.layout === "tabs"
       ? (s.stepCount === 1 && s.nestingLevel === 0 ? "form" : "wizard")
-      : this.footerLayout;
+      : this.layout;
   }
 
   protected errorPhaseMessage = errorPhaseMessage;