@daltonr/pathwrite-angular 0.5.0 → 0.6.0

package/README.md

@@ -87,6 +87,128 @@ facade.snapshot()?.data.name; // typed as string (or whatever MyData defines)
 
 ---
 
+## `injectPath()` — Recommended API for Components
+
+**New in v0.6.0** — `injectPath()` provides an ergonomic, signal-based API for accessing the path engine inside Angular components. This is the **recommended approach** for step components and forms — it mirrors React's `usePathContext()` and Vue's `usePath()` for consistency across frameworks.
+
+### Quick start
+
+```typescript
+import { Component } from "@angular/core";
+import { PathFacade, injectPath } from "@daltonr/pathwrite-angular";
+
+@Component({
+  selector: "app-contact-step",
+  standalone: true,
+  providers: [PathFacade],  // ← Required: provide at this component or a parent
+  template: `
+    @if (path.snapshot(); as s) {
+      <h2>{{ s.activeStep?.title }}</h2>
+      <input 
+        type="text" 
+        [value]="name"
+        (input)="updateName($any($event.target).value)"
+      />
+      <button (click)="path.next()">Next</button>
+    }
+  `
+})
+export class ContactStepComponent {
+  protected readonly path = injectPath<ContactData>();
+  protected name = "";
+
+  protected updateName(value: string): void {
+    this.name = value;
+    this.path.setData("name", value);  // ← No facade or template ref needed
+  }
+}
+```
+
+### API
+
+`injectPath()` returns an object with:
+
+| Member | Type | Description |
+|--------|------|-------------|
+| `snapshot` | `Signal<PathSnapshot \| null>` | Current path snapshot as a signal. `null` when no path is active. |
+| `start(path, data?)` | `Promise<void>` | Start or restart a path. |
+| `restart(path, data?)` | `Promise<void>` | Tear down and restart fresh. |
+| `startSubPath(path, data?, meta?)` | `Promise<void>` | Push a sub-path onto the stack. |
+| `next()` | `Promise<void>` | Advance one step. |
+| `previous()` | `Promise<void>` | Go back one step. |
+| `cancel()` | `Promise<void>` | Cancel the active path. |
+| `setData(key, value)` | `Promise<void>` | Update a single data field. Type-safe when `TData` is specified. |
+| `goToStep(stepId)` | `Promise<void>` | Jump to a step by ID (no guard checks). |
+| `goToStepChecked(stepId)` | `Promise<void>` | Jump to a step by ID (guard-checked). |
+
+### Type safety
+
+Pass your data type as a generic to get full type checking:
+
+```typescript
+interface ContactData {
+  name: string;
+  email: string;
+}
+
+const path = injectPath<ContactData>();
+
+path.setData("name", "Jane");   // ✅ OK
+path.setData("foo", 123);       // ❌ Type error: "foo" not in ContactData
+path.snapshot()?.data.name;     // ✅ Typed as string
+```
+
+### Requirements
+
+- **Angular 16+** (signals required)
+- `PathFacade` must be provided in the injector tree (either at the component or a parent component)
+
+### Compared to manual facade injection
+
+**Before** (manual facade injection + template reference):
+```typescript
+@Component({
+  providers: [PathFacade],
+  template: `
+    <pw-shell #shell ...>
+      <ng-template pwStep="contact">
+        <input (input)="shell.facade.setData('name', $any($event.target).value)" />
+      </ng-template>
+    </pw-shell>
+  `
+})
+export class MyComponent {
+  protected readonly facade = inject(PathFacade);
+}
+```
+
+**After** (with `injectPath()`):
+```typescript
+@Component({
+  providers: [PathFacade],
+  template: `
+    <input (input)="updateName($any($event.target).value)" />
+    <button (click)="path.next()">Next</button>
+  `
+})
+export class MyStepComponent {
+  protected readonly path = injectPath<MyData>();
+
+  protected updateName(value: string): void {
+    this.path.setData("name", value);  // ← Clean, no template ref
+  }
+}
+```
+
+The `injectPath()` approach:
+- **No template references** — access the engine directly from the component class
+- **Signal-native** — `path.snapshot()` returns the reactive signal directly
+- **Type-safe** — generic parameter flows through to all methods
+- **Framework-consistent** — matches React's `usePathContext()` and Vue's `usePath()`
+- **Less Angular-specific knowledge** — just `inject()` and signals, patterns Angular developers already know
+
+---
+
 ## Angular Forms integration — `syncFormGroup`
 
 `syncFormGroup` eliminates the boilerplate of manually wiring an Angular
@@ -255,6 +377,38 @@ export class MyComponent {
 
 Each `<ng-template pwStep="<stepId>">` is rendered when the active step matches `stepId`. The shell handles all navigation internally.
 
+> **⚠️ Important: `pwStep` Values Must Match Step IDs**
+>
+> The string value passed to the `pwStep` directive **must exactly match** the corresponding step's `id`:
+>
+> ```typescript
+> const myPath: PathDefinition = {
+>   id: 'signup',
+>   steps: [
+>     { id: 'details' },  // ← Step ID
+>     { id: 'review' }    // ← Step ID
+>   ]
+> };
+> ```
+>
+> ```html
+> <pw-shell [path]="myPath">
+>   <ng-template pwStep="details">  <!-- ✅ Matches "details" step -->
+>     <app-details-form />
+>   </ng-template>
+>   <ng-template pwStep="review">   <!-- ✅ Matches "review" step -->
+>     <app-review-panel />
+>   </ng-template>
+>   <ng-template pwStep="foo">      <!-- ❌ No step with id "foo" -->
+>     <app-foo-panel />
+>   </ng-template>
+> </pw-shell>
+> ```
+>
+> If a `pwStep` value doesn't match any step ID, that template will never be rendered (silent — no error message).
+>
+> **💡 Tip:** Use your IDE's "Go to Definition" on the step ID in your path definition, then copy-paste the exact string when creating the `pwStep` directive. This ensures perfect matching and avoids typos.
+
 ### Context sharing
 
 `PathShellComponent` provides a `PathFacade` instance in its own `providers` array
@@ -306,7 +460,8 @@ export class MyComponent {
 | `completeLabel` | `string` | `"Complete"` | Complete button label (last step). |
 | `cancelLabel` | `string` | `"Cancel"` | Cancel button label. |
 | `hideCancel` | `boolean` | `false` | Hide the Cancel button. |
-| `hideProgress` | `boolean` | `false` | Hide the progress indicator. |
+| `hideProgress` | `boolean` | `false` | Hide the progress indicator. Also hidden automatically for single-step top-level paths. |
+| `footerLayout` | `"wizard" \| "form" \| "auto"` | `"auto"` | Footer button layout. `"auto"` uses `"form"` for single-step top-level paths, `"wizard"` otherwise. `"wizard"`: Back on left, Cancel+Submit on right. `"form"`: Cancel on left, Submit on right, no Back button. |
 
 ### Outputs
 
@@ -364,6 +519,38 @@ export class MyComponent { ... }
 
 Both directives can be combined. Only the sections you override are replaced — a custom header still shows the default footer, and vice versa.
 
+### Resetting the path
+
+There are two ways to reset `<pw-shell>` to step 1.
+
+**Option 1 — Toggle mount** (simplest, always correct)
+
+Toggle an `@if` flag to destroy and recreate the shell. Every child component resets from scratch:
+
+```html
+@if (isActive) {
+  <pw-shell [path]="myPath" (completed)="isActive = false" (cancelled)="isActive = false">
+    <ng-template pwStep="details"><app-details-form /></ng-template>
+  </pw-shell>
+} @else {
+  <button (click)="isActive = true">Try Again</button>
+}
+```
+
+**Option 2 — Call `restart()` on the shell ref** (in-place, no unmount)
+
+Use the existing `#shell` template reference — `restart()` is a public method:
+
+```html
+<pw-shell #shell [path]="myPath" (completed)="onDone($event)">
+  <ng-template pwStep="details"><app-details-form /></ng-template>
+</pw-shell>
+
+<button (click)="shell.restart()">Try Again</button>
+```
+
+`restart()` resets the path engine to step 1 with the original `[initialData]` without unmounting the component. Use this when you need to keep the shell mounted — for example, to preserve scroll position in a parent container or to drive a CSS transition.
+
 ---
 
 ## Sub-Paths

package/dist/index.css

@@ -204,6 +204,15 @@
   left: 4px;
 }
 
+.pw-shell__validation-label {
+  font-weight: 600;
+  margin-right: 3px;
+}
+
+.pw-shell__validation-label::after {
+  content: ":";
+}
+
 /* ------------------------------------------------------------------ */
 /* Footer — navigation buttons                                        */
 /* ------------------------------------------------------------------ */

package/dist/index.d.ts

@@ -65,6 +65,73 @@ export declare class PathFacade<TData extends PathData = PathData> implements On
     static ɵfac: i0.ɵɵFactoryDeclaration<PathFacade<any>, never>;
     static ɵprov: i0.ɵɵInjectableDeclaration<PathFacade<any>>;
 }
+/**
+ * Return type of `injectPath()`. 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> {
+    /** Current path snapshot as a signal. Returns `null` when no path is active. */
+    snapshot: Signal<PathSnapshot<TData> | null>;
+    /** Start (or restart) a path. */
+    start: (path: PathDefinition<any>, initialData?: PathData) => Promise<void>;
+    /** Push a sub-path onto the stack. */
+    startSubPath: (path: PathDefinition<any>, initialData?: PathData, meta?: Record<string, unknown>) => Promise<void>;
+    /** Advance one step. Completes the path on the last step. */
+    next: () => Promise<void>;
+    /** Go back one step. No-op when already on the first step. */
+    previous: () => Promise<void>;
+    /** Cancel the active path (or sub-path). */
+    cancel: () => Promise<void>;
+    /** Update a single data field. */
+    setData: <K extends string & keyof TData>(key: K, value: TData[K]) => Promise<void>;
+    /** Jump to a step by ID without checking guards. */
+    goToStep: (stepId: string) => Promise<void>;
+    /** Jump to a step by ID, checking guards first. */
+    goToStepChecked: (stepId: string) => Promise<void>;
+    /**
+     * Tears down any active path and immediately starts the given path fresh.
+     * Use for "Start over" / retry flows.
+     */
+    restart: (path: PathDefinition<any>, initialData?: PathData) => Promise<void>;
+}
+/**
+ * Inject a PathFacade and return a signal-based API for use in Angular 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.
+ *
+ * The optional generic `TData` narrows `snapshot().data` and `setData()` to your
+ * data shape. It is a **type-level assertion**, not a runtime guarantee.
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   selector: 'app-contact-step',
+ *   standalone: true,
+ *   providers: [PathFacade],  // ← Provide at this component or a parent
+ *   template: `
+ *     @if (path.snapshot(); as s) {
+ *       <div>Step: {{ s.activeStep?.title }}</div>
+ *       <button (click)="path.next()">Next</button>
+ *     }
+ *   `
+ * })
+ * export class ContactStepComponent {
+ *   protected readonly path = injectPath<ContactData>();
+ *
+ *   updateName(name: string) {
+ *     this.path.setData('name', name);
+ *   }
+ * }
+ * ```
+ *
+ * @throws Error if PathFacade is not provided in the injector tree
+ */
+export declare function injectPath<TData extends PathData = PathData>(): InjectPathReturn<TData>;
 /**
  * Minimal interface describing what syncFormGroup needs from an Angular
  * FormGroup. Typed as a duck interface so that @angular/forms is not a
@@ -106,5 +173,5 @@ export interface FormGroupLike {
  * ```
  */
 export declare function syncFormGroup<TData extends PathData = PathData>(facade: PathFacade<TData>, formGroup: FormGroupLike, destroyRef?: DestroyRef): () => void;
-export type { PathData, PathDefinition, PathEvent, PathSnapshot, PathStep, PathStepContext, SerializedPathState } from "@daltonr/pathwrite-core";
+export type { PathData, FieldErrors, PathDefinition, PathEvent, PathSnapshot, PathStep, PathStepContext, SerializedPathState } from "@daltonr/pathwrite-core";
 export { PathEngine } from "@daltonr/pathwrite-core";

package/dist/index.js

@@ -1,4 +1,4 @@
-import { Injectable, signal } from "@angular/core";
+import { Injectable, signal, inject } from "@angular/core";
 import { BehaviorSubject, Subject } from "rxjs";
 import { PathEngine } from "@daltonr/pathwrite-core";
 import * as i0 from "@angular/core";
@@ -116,6 +116,61 @@ export class PathFacade {
 i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: PathFacade, decorators: [{
             type: Injectable
         }], ctorParameters: () => [] });
+/**
+ * Inject a PathFacade and return a signal-based API for use in Angular 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.
+ *
+ * The optional generic `TData` narrows `snapshot().data` and `setData()` to your
+ * data shape. It is a **type-level assertion**, not a runtime guarantee.
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   selector: 'app-contact-step',
+ *   standalone: true,
+ *   providers: [PathFacade],  // ← Provide at this component or a parent
+ *   template: `
+ *     @if (path.snapshot(); as s) {
+ *       <div>Step: {{ s.activeStep?.title }}</div>
+ *       <button (click)="path.next()">Next</button>
+ *     }
+ *   `
+ * })
+ * export class ContactStepComponent {
+ *   protected readonly path = injectPath<ContactData>();
+ *
+ *   updateName(name: string) {
+ *     this.path.setData('name', name);
+ *   }
+ * }
+ * ```
+ *
+ * @throws Error if PathFacade is not provided in the injector tree
+ */
+export function injectPath() {
+    const facade = inject(PathFacade, { optional: true });
+    if (!facade) {
+        throw new Error("injectPath() requires PathFacade to be provided. " +
+            "Add 'providers: [PathFacade]' to your component or a parent component.");
+    }
+    return {
+        snapshot: facade.stateSignal,
+        start: (path, initialData = {}) => facade.start(path, initialData),
+        startSubPath: (path, initialData = {}, meta) => facade.startSubPath(path, initialData, meta),
+        next: () => facade.next(),
+        previous: () => facade.previous(),
+        cancel: () => facade.cancel(),
+        setData: (key, value) => facade.setData(key, value),
+        goToStep: (stepId) => facade.goToStep(stepId),
+        goToStepChecked: (stepId) => facade.goToStepChecked(stepId),
+        restart: (path, initialData = {}) => facade.restart(path, initialData),
+    };
+}
 /**
  * Syncs every key of an Angular FormGroup to the path engine via setData.
  *

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/shell.d.ts

@@ -113,8 +113,15 @@ export declare class PathShellComponent implements OnInit, OnDestroy {
     cancelLabel: string;
     /** Hide the Cancel button entirely. */
     hideCancel: boolean;
-    /** Hide the step progress indicator in the header. */
+    /** Hide the step progress indicator in the header. Also hidden automatically when the path has only one step. */
     hideProgress: boolean;
+    /**
+     * Footer 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.
+     */
+    footerLayout: "wizard" | "form" | "auto";
     completed: EventEmitter<PathData>;
     cancelled: EventEmitter<PathData>;
     pathEvent: EventEmitter<PathEvent>;
@@ -132,6 +139,23 @@ export declare class PathShellComponent implements OnInit, OnDestroy {
     ngOnInit(): void;
     ngOnDestroy(): void;
     doStart(): void;
+    /**
+     * Restart the active path from step 1 with the original `initialData`,
+     * without unmounting the shell. Call this via a `#shell` template reference:
+     *
+     * ```html
+     * <pw-shell #shell [path]="myPath" ...></pw-shell>
+     * <button (click)="shell.restart()">Try Again</button>
+     * ```
+     */
+    restart(): Promise<void>;
+    /** Returns Object.entries(s.fieldMessages) for use in *ngFor. */
+    protected fieldEntries(s: PathSnapshot): [string, string][];
+    /** Resolves "auto" footerLayout based on snapshot. Single-step top-level → "form", otherwise → "wizard". */
+    protected getResolvedFooterLayout(s: PathSnapshot): "wizard" | "form";
+    /** Converts a camelCase or lowercase field key to a display label.
+     *  e.g. "firstName" → "First Name", "email" → "Email" */
+    protected formatFieldKey(key: string): string;
     static ɵfac: i0.ɵɵFactoryDeclaration<PathShellComponent, never>;
-    static ɵcmp: i0.ɵɵComponentDeclaration<PathShellComponent, "pw-shell", never, { "path": { "alias": "path"; "required": true; }; "initialData": { "alias": "initialData"; "required": false; }; "autoStart": { "alias": "autoStart"; "required": false; }; "backLabel": { "alias": "backLabel"; "required": false; }; "nextLabel": { "alias": "nextLabel"; "required": false; }; "completeLabel": { "alias": "completeLabel"; "required": false; }; "cancelLabel": { "alias": "cancelLabel"; "required": false; }; "hideCancel": { "alias": "hideCancel"; "required": false; }; "hideProgress": { "alias": "hideProgress"; "required": false; }; }, { "completed": "completed"; "cancelled": "cancelled"; "pathEvent": "pathEvent"; }, ["customHeader", "customFooter", "stepDirectives"], never, true, never>;
+    static ɵcmp: i0.ɵɵComponentDeclaration<PathShellComponent, "pw-shell", never, { "path": { "alias": "path"; "required": true; }; "initialData": { "alias": "initialData"; "required": false; }; "autoStart": { "alias": "autoStart"; "required": false; }; "backLabel": { "alias": "backLabel"; "required": false; }; "nextLabel": { "alias": "nextLabel"; "required": false; }; "completeLabel": { "alias": "completeLabel"; "required": false; }; "cancelLabel": { "alias": "cancelLabel"; "required": false; }; "hideCancel": { "alias": "hideCancel"; "required": false; }; "hideProgress": { "alias": "hideProgress"; "required": false; }; "footerLayout": { "alias": "footerLayout"; "required": false; }; }, { "completed": "completed"; "cancelled": "cancelled"; "pathEvent": "pathEvent"; }, ["customHeader", "customFooter", "stepDirectives"], never, true, never>;
 }

package/dist/shell.js

@@ -119,8 +119,15 @@ export class PathShellComponent {
         this.cancelLabel = "Cancel";
         /** Hide the Cancel button entirely. */
         this.hideCancel = false;
-        /** Hide the step progress indicator in the header. */
+        /** Hide the step progress indicator in the header. Also hidden automatically when the path has only one step. */
         this.hideProgress = false;
+        /**
+         * Footer 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.
+         */
+        this.footerLayout = "auto";
         this.completed = new EventEmitter();
         this.cancelled = new EventEmitter();
         this.pathEvent = new EventEmitter();
@@ -161,8 +168,35 @@ export class PathShellComponent {
         this.started = true;
         this.facade.start(this.path, this.initialData);
     }
+    /**
+     * Restart the active path from step 1 with the original `initialData`,
+     * without unmounting the shell. Call this via a `#shell` template reference:
+     *
+     * ```html
+     * <pw-shell #shell [path]="myPath" ...></pw-shell>
+     * <button (click)="shell.restart()">Try Again</button>
+     * ```
+     */
+    restart() {
+        return this.facade.restart(this.path, this.initialData);
+    }
+    /** Returns Object.entries(s.fieldMessages) for use in *ngFor. */
+    fieldEntries(s) {
+        return Object.entries(s.fieldMessages);
+    }
+    /** Resolves "auto" footerLayout based on snapshot. Single-step top-level → "form", otherwise → "wizard". */
+    getResolvedFooterLayout(s) {
+        return this.footerLayout === "auto"
+            ? (s.stepCount === 1 && s.nestingLevel === 0 ? "form" : "wizard")
+            : this.footerLayout;
+    }
+    /** Converts a camelCase or lowercase field key to a display label.
+     *  e.g. "firstName" → "First Name", "email" → "Email" */
+    formatFieldKey(key) {
+        return key.replace(/([A-Z])/g, " $1").replace(/^./, c => c.toUpperCase()).trim();
+    }
     static { this.ɵfac = i0.ɵɵngDeclareFactory({ minVersion: "12.0.0", version: "17.3.12", ngImport: i0, type: PathShellComponent, deps: [], target: i0.ɵɵFactoryTarget.Component }); }
-    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "17.3.12", type: PathShellComponent, isStandalone: true, selector: "pw-shell", inputs: { path: "path", initialData: "initialData", autoStart: "autoStart", backLabel: "backLabel", nextLabel: "nextLabel", completeLabel: "completeLabel", cancelLabel: "cancelLabel", hideCancel: "hideCancel", hideProgress: "hideProgress" }, outputs: { completed: "completed", cancelled: "cancelled", pathEvent: "pathEvent" }, providers: [PathFacade], queries: [{ propertyName: "customHeader", first: true, predicate: PathShellHeaderDirective, descendants: true }, { propertyName: "customFooter", first: true, predicate: PathShellFooterDirective, descendants: true }, { propertyName: "stepDirectives", predicate: PathStepDirective }], ngImport: i0, template: `
+    static { this.ɵcmp = i0.ɵɵngDeclareComponent({ minVersion: "14.0.0", version: "17.3.12", type: PathShellComponent, isStandalone: true, selector: "pw-shell", inputs: { path: "path", initialData: "initialData", autoStart: "autoStart", backLabel: "backLabel", nextLabel: "nextLabel", completeLabel: "completeLabel", cancelLabel: "cancelLabel", hideCancel: "hideCancel", hideProgress: "hideProgress", footerLayout: "footerLayout" }, outputs: { completed: "completed", cancelled: "cancelled", pathEvent: "pathEvent" }, providers: [PathFacade], queries: [{ propertyName: "customHeader", first: true, predicate: PathShellHeaderDirective, descendants: true }, { propertyName: "customFooter", first: true, predicate: PathShellFooterDirective, descendants: true }, { propertyName: "stepDirectives", predicate: PathStepDirective }], ngImport: i0, template: `
     <!-- Empty state -->
     <div class="pw-shell" *ngIf="!(facade.state$ | async)">
       <div class="pw-shell__empty" *ngIf="!started">
@@ -178,7 +212,7 @@ export class PathShellComponent {
         <ng-container *ngTemplateOutlet="customHeader.templateRef; context: { $implicit: s }"></ng-container>
       </ng-container>
       <ng-template #defaultHeader>
-        <div class="pw-shell__header" *ngIf="!hideProgress">
+        <div class="pw-shell__header" *ngIf="!hideProgress && (s.stepCount > 1 || s.nestingLevel > 0)">
           <div class="pw-shell__steps">
             <div
               *ngFor="let step of s.steps; let i = index"
@@ -204,9 +238,11 @@ export class PathShellComponent {
         </ng-container>
       </div>
 
-      <!-- Validation messages -->
-      <ul class="pw-shell__validation" *ngIf="s.validationMessages.length > 0">
-        <li *ngFor="let msg of s.validationMessages" class="pw-shell__validation-item">{{ msg }}</li>
+      <!-- Validation messages — labeled by field name -->
+      <ul class="pw-shell__validation" *ngIf="s.hasAttemptedNext && 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>
 
       <!-- Footer — custom or default navigation buttons -->
@@ -216,8 +252,17 @@ export class PathShellComponent {
       <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"
+              type="button"
+              class="pw-shell__btn pw-shell__btn--cancel"
+              [disabled]="s.isNavigating"
+              (click)="facade.cancel()"
+            >{{ cancelLabel }}</button>
+            <!-- Wizard mode: Back on the left -->
             <button
-              *ngIf="!s.isFirstStep"
+              *ngIf="getResolvedFooterLayout(s) === 'wizard' && !s.isFirstStep"
               type="button"
               class="pw-shell__btn pw-shell__btn--back"
               [disabled]="s.isNavigating || !s.canMovePrevious"
@@ -225,17 +270,19 @@ export class PathShellComponent {
             >{{ backLabel }}</button>
           </div>
           <div class="pw-shell__footer-right">
+            <!-- Wizard mode: Cancel on the right -->
             <button
-              *ngIf="!hideCancel"
+              *ngIf="getResolvedFooterLayout(s) === 'wizard' && !hideCancel"
               type="button"
               class="pw-shell__btn pw-shell__btn--cancel"
               [disabled]="s.isNavigating"
               (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 || !s.canMoveNext"
+              [disabled]="s.isNavigating"
               (click)="facade.next()"
             >{{ s.isLastStep ? completeLabel : nextLabel }}</button>
           </div>
@@ -268,7 +315,7 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
         <ng-container *ngTemplateOutlet="customHeader.templateRef; context: { $implicit: s }"></ng-container>
       </ng-container>
       <ng-template #defaultHeader>
-        <div class="pw-shell__header" *ngIf="!hideProgress">
+        <div class="pw-shell__header" *ngIf="!hideProgress && (s.stepCount > 1 || s.nestingLevel > 0)">
           <div class="pw-shell__steps">
             <div
               *ngFor="let step of s.steps; let i = index"
@@ -294,9 +341,11 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
         </ng-container>
       </div>
 
-      <!-- Validation messages -->
-      <ul class="pw-shell__validation" *ngIf="s.validationMessages.length > 0">
-        <li *ngFor="let msg of s.validationMessages" class="pw-shell__validation-item">{{ msg }}</li>
+      <!-- Validation messages — labeled by field name -->
+      <ul class="pw-shell__validation" *ngIf="s.hasAttemptedNext && 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>
 
       <!-- Footer — custom or default navigation buttons -->
@@ -306,8 +355,17 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
       <ng-template #defaultFooter>
         <div class="pw-shell__footer">
           <div class="pw-shell__footer-left">
+            <!-- Form mode: Cancel on the left -->
             <button
-              *ngIf="!s.isFirstStep"
+              *ngIf="getResolvedFooterLayout(s) === 'form' && !hideCancel"
+              type="button"
+              class="pw-shell__btn pw-shell__btn--cancel"
+              [disabled]="s.isNavigating"
+              (click)="facade.cancel()"
+            >{{ cancelLabel }}</button>
+            <!-- Wizard mode: Back on the left -->
+            <button
+              *ngIf="getResolvedFooterLayout(s) === 'wizard' && !s.isFirstStep"
               type="button"
               class="pw-shell__btn pw-shell__btn--back"
               [disabled]="s.isNavigating || !s.canMovePrevious"
@@ -315,17 +373,19 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
             >{{ backLabel }}</button>
           </div>
           <div class="pw-shell__footer-right">
+            <!-- Wizard mode: Cancel on the right -->
             <button
-              *ngIf="!hideCancel"
+              *ngIf="getResolvedFooterLayout(s) === 'wizard' && !hideCancel"
               type="button"
               class="pw-shell__btn pw-shell__btn--cancel"
               [disabled]="s.isNavigating"
               (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 || !s.canMoveNext"
+              [disabled]="s.isNavigating"
               (click)="facade.next()"
             >{{ s.isLastStep ? completeLabel : nextLabel }}</button>
           </div>
@@ -353,6 +413,8 @@ i0.ɵɵngDeclareClassMetadata({ minVersion: "12.0.0", version: "17.3.12", ngImpo
                 type: Input
             }], hideProgress: [{
                 type: Input
+            }], footerLayout: [{
+                type: Input
             }], completed: [{
                 type: Output
             }], cancelled: [{

package/dist/shell.js.map

@@ -1 +1 @@
-{"version":3,"file":"shell.js","sourceRoot":"","sources":["../src/shell.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"shell.js","sourceRoot":"","sources":["../src/shell.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@daltonr/pathwrite-angular",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "type": "module",
   "license": "MIT",
   "description": "Angular adapter for @daltonr/pathwrite-core — RxJS observables, signal-friendly, with optional <pw-shell> default UI.",
@@ -29,7 +29,8 @@
       "types": "./dist/shell.d.ts",
       "import": "./dist/shell.js"
     },
-    "./styles.css": "./dist/index.css"
+    "./styles.css": "./dist/index.css",
+    "./dist/index.css": "./dist/index.css"
   },
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -60,7 +61,7 @@
     "@angular/compiler-cli": "^17.0.0"
   },
   "dependencies": {
-    "@daltonr/pathwrite-core": "^0.5.0"
+    "@daltonr/pathwrite-core": "^0.6.0"
   },
   "publishConfig": {
     "access": "public"

package/src/index.ts

@@ -1,4 +1,4 @@
-import { Injectable, OnDestroy, DestroyRef, signal, Signal } from "@angular/core";
+import { Injectable, OnDestroy, DestroyRef, signal, Signal, inject } from "@angular/core";
 import { BehaviorSubject, Observable, Subject } from "rxjs";
 import {
   PathData,
@@ -134,6 +134,101 @@ export class PathFacade<TData extends PathData = PathData> implements OnDestroy
   }
 }
 
+// ---------------------------------------------------------------------------
+// injectPath() - Signal-based path access
+// ---------------------------------------------------------------------------
+
+/**
+ * Return type of `injectPath()`. 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> {
+  /** Current path snapshot as a signal. Returns `null` when no path is active. */
+  snapshot: Signal<PathSnapshot<TData> | null>;
+  /** Start (or restart) a path. */
+  start: (path: PathDefinition<any>, initialData?: PathData) => Promise<void>;
+  /** Push a sub-path onto the stack. */
+  startSubPath: (path: PathDefinition<any>, initialData?: PathData, meta?: Record<string, unknown>) => Promise<void>;
+  /** Advance one step. Completes the path on the last step. */
+  next: () => Promise<void>;
+  /** Go back one step. No-op when already on the first step. */
+  previous: () => Promise<void>;
+  /** Cancel the active path (or sub-path). */
+  cancel: () => Promise<void>;
+  /** Update a single data field. */
+  setData: <K extends string & keyof TData>(key: K, value: TData[K]) => Promise<void>;
+  /** Jump to a step by ID without checking guards. */
+  goToStep: (stepId: string) => Promise<void>;
+  /** Jump to a step by ID, checking guards first. */
+  goToStepChecked: (stepId: string) => Promise<void>;
+  /**
+   * Tears down any active path and immediately starts the given path fresh.
+   * Use for "Start over" / retry flows.
+   */
+  restart: (path: PathDefinition<any>, initialData?: PathData) => Promise<void>;
+}
+
+/**
+ * Inject a PathFacade and return a signal-based API for use in Angular 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.
+ *
+ * The optional generic `TData` narrows `snapshot().data` and `setData()` to your
+ * data shape. It is a **type-level assertion**, not a runtime guarantee.
+ *
+ * @example
+ * ```typescript
+ * @Component({
+ *   selector: 'app-contact-step',
+ *   standalone: true,
+ *   providers: [PathFacade],  // ← Provide at this component or a parent
+ *   template: `
+ *     @if (path.snapshot(); as s) {
+ *       <div>Step: {{ s.activeStep?.title }}</div>
+ *       <button (click)="path.next()">Next</button>
+ *     }
+ *   `
+ * })
+ * export class ContactStepComponent {
+ *   protected readonly path = injectPath<ContactData>();
+ *
+ *   updateName(name: string) {
+ *     this.path.setData('name', name);
+ *   }
+ * }
+ * ```
+ *
+ * @throws Error if PathFacade is not provided in the injector tree
+ */
+export function injectPath<TData extends PathData = PathData>(): InjectPathReturn<TData> {
+  const facade = inject(PathFacade, { optional: true }) as PathFacade<TData> | null;
+  
+  if (!facade) {
+    throw new Error(
+      "injectPath() requires PathFacade to be provided. " +
+      "Add 'providers: [PathFacade]' to your component or a parent component."
+    );
+  }
+
+  return {
+    snapshot: facade.stateSignal,
+    start: (path, initialData = {}) => facade.start(path, initialData),
+    startSubPath: (path, initialData = {}, meta) => facade.startSubPath(path, initialData, meta),
+    next: () => facade.next(),
+    previous: () => facade.previous(),
+    cancel: () => facade.cancel(),
+    setData: (key, value) => facade.setData(key, value),
+    goToStep: (stepId) => facade.goToStep(stepId),
+    goToStepChecked: (stepId) => facade.goToStepChecked(stepId),
+    restart: (path, initialData = {}) => facade.restart(path, initialData),
+  };
+}
+
 // ---------------------------------------------------------------------------
 // Forms integration
 // ---------------------------------------------------------------------------
@@ -206,6 +301,7 @@ export function syncFormGroup<TData extends PathData = PathData>(
 // Re-export core types for convenience (users don't need to import from @daltonr/pathwrite-core)
 export type {
   PathData,
+  FieldErrors,
   PathDefinition,
   PathEvent,
   PathSnapshot,

package/src/shell.ts

@@ -153,7 +153,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">
+        <div class="pw-shell__header" *ngIf="!hideProgress && (s.stepCount > 1 || s.nestingLevel > 0)">
           <div class="pw-shell__steps">
             <div
               *ngFor="let step of s.steps; let i = index"
@@ -179,9 +179,11 @@ export class PathShellFooterDirective {
         </ng-container>
       </div>
 
-      <!-- Validation messages -->
-      <ul class="pw-shell__validation" *ngIf="s.validationMessages.length > 0">
-        <li *ngFor="let msg of s.validationMessages" class="pw-shell__validation-item">{{ msg }}</li>
+      <!-- Validation messages — labeled by field name -->
+      <ul class="pw-shell__validation" *ngIf="s.hasAttemptedNext && 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>
 
       <!-- Footer — custom or default navigation buttons -->
@@ -191,8 +193,17 @@ export class PathShellFooterDirective {
       <ng-template #defaultFooter>
         <div class="pw-shell__footer">
           <div class="pw-shell__footer-left">
+            <!-- Form mode: Cancel on the left -->
             <button
-              *ngIf="!s.isFirstStep"
+              *ngIf="getResolvedFooterLayout(s) === 'form' && !hideCancel"
+              type="button"
+              class="pw-shell__btn pw-shell__btn--cancel"
+              [disabled]="s.isNavigating"
+              (click)="facade.cancel()"
+            >{{ cancelLabel }}</button>
+            <!-- Wizard mode: Back on the left -->
+            <button
+              *ngIf="getResolvedFooterLayout(s) === 'wizard' && !s.isFirstStep"
               type="button"
               class="pw-shell__btn pw-shell__btn--back"
               [disabled]="s.isNavigating || !s.canMovePrevious"
@@ -200,17 +211,19 @@ export class PathShellFooterDirective {
             >{{ backLabel }}</button>
           </div>
           <div class="pw-shell__footer-right">
+            <!-- Wizard mode: Cancel on the right -->
             <button
-              *ngIf="!hideCancel"
+              *ngIf="getResolvedFooterLayout(s) === 'wizard' && !hideCancel"
               type="button"
               class="pw-shell__btn pw-shell__btn--cancel"
               [disabled]="s.isNavigating"
               (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 || !s.canMoveNext"
+              [disabled]="s.isNavigating"
               (click)="facade.next()"
             >{{ s.isLastStep ? completeLabel : nextLabel }}</button>
           </div>
@@ -236,8 +249,15 @@ export class PathShellComponent implements OnInit, OnDestroy {
   @Input() cancelLabel = "Cancel";
   /** Hide the Cancel button entirely. */
   @Input() hideCancel = false;
-  /** Hide the step progress indicator in the header. */
+  /** Hide the step progress indicator in the header. Also hidden automatically when the path has only one step. */
   @Input() hideProgress = false;
+  /**
+   * Footer 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.
+   */
+  @Input() footerLayout: "wizard" | "form" | "auto" = "auto";
 
   @Output() completed = new EventEmitter<PathData>();
   @Output() cancelled = new EventEmitter<PathData>();
@@ -287,4 +307,35 @@ export class PathShellComponent implements OnInit, OnDestroy {
     this.started = true;
     this.facade.start(this.path, this.initialData);
   }
+
+  /**
+   * Restart the active path from step 1 with the original `initialData`,
+   * without unmounting the shell. Call this via a `#shell` template reference:
+   *
+   * ```html
+   * <pw-shell #shell [path]="myPath" ...></pw-shell>
+   * <button (click)="shell.restart()">Try Again</button>
+   * ```
+   */
+  public restart(): Promise<void> {
+    return this.facade.restart(this.path, this.initialData);
+  }
+
+  /** Returns Object.entries(s.fieldMessages) for use in *ngFor. */
+  protected fieldEntries(s: PathSnapshot): [string, string][] {
+    return Object.entries(s.fieldMessages) 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"
+      ? (s.stepCount === 1 && s.nestingLevel === 0 ? "form" : "wizard")
+      : 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();
+  }
 }