@daltonr/pathwrite-angular 0.10.0 → 0.11.0

package/README.md

@@ -1,6 +1,6 @@
 # @daltonr/pathwrite-angular
 
-Angular `@Injectable` facade over `@daltonr/pathwrite-core`. Exposes path state and events as RxJS observables that work seamlessly with Angular signals, the `async` pipe, and `takeUntilDestroyed`.
+Angular adapter for `@daltonr/pathwrite-core` — `PathFacade` injectable service with RxJS observables, Angular signals, and an optional `<pw-shell>` UI component.
 
 ## Installation
 
@@ -8,508 +8,133 @@ Angular `@Injectable` facade over `@daltonr/pathwrite-core`. Exposes path state
 npm install @daltonr/pathwrite-core @daltonr/pathwrite-angular
 ```
 
-## Exported Types
+Peer dependencies: Angular 17+, RxJS 7+.
 
-For convenience, this package re-exports core types so you don't need to import from `@daltonr/pathwrite-core`:
-
-```typescript
-import { 
-  PathFacade,           // Angular-specific
-  PathEngine,           // Re-exported from core (value + type)
-  PathData,             // Re-exported from core
-  PathDefinition,       // Re-exported from core
-  PathEvent,            // Re-exported from core
-  PathSnapshot,         // Re-exported from core
-  PathStep,             // Re-exported from core
-  PathStepContext,      // Re-exported from core
-  SerializedPathState   // Re-exported from core
-} from "@daltonr/pathwrite-angular";
-```
-
----
-
-## Setup
-
-Provide `PathFacade` at the component level so each component gets its own isolated path instance, and Angular handles cleanup automatically via `ngOnDestroy`.
-
-```typescript
-@Component({
-  // ...
-  providers: [PathFacade]
-})
-export class MyComponent {
-  protected readonly facade = inject(PathFacade);
-
-  // Reactive snapshot — updates whenever the path state changes
-  public readonly snapshot = toSignal(this.facade.state$, { initialValue: null });
-
-  constructor() {
-    // Automatically unsubscribes when the component is destroyed
-    this.facade.events$.pipe(takeUntilDestroyed()).subscribe((event) => {
-      console.log(event);
-    });
-  }
-}
-```
-
-## PathFacade API
-
-### Observables and signals
-
-| Member | Type | Description |
-|--------|------|-------------|
-| `state$` | `Observable<PathSnapshot \| null>` | Current snapshot. `null` when no path is active. Backed by a `BehaviorSubject` — late subscribers receive the current value immediately. |
-| `stateSignal` | `Signal<PathSnapshot \| null>` | Signal version of `state$`. Same value, updated synchronously. Use directly in signal-based components without `toSignal()`. |
-| `events$` | `Observable<PathEvent>` | All engine events: `stateChanged`, `completed`, `cancelled`, `resumed`. |
-
-### Methods
-
-| Method | Description |
-|--------|-------------|
-| `adoptEngine(engine)` | Adopt an externally-managed `PathEngine` (e.g. from `restoreOrStart()`). The facade immediately reflects the engine's current state and forwards all subsequent events. The caller is responsible for the engine's lifecycle. |
-| `start(definition, data?)` | Start or re-start a path. |
-| `restart(definition, data?)` | Tear down any active path (without firing hooks) and start the given path fresh. Safe to call at any time. Use for "Start over" / retry flows. |
-| `startSubPath(definition, data?, meta?)` | Push a sub-path. Requires an active path. `meta` is returned unchanged to `onSubPathComplete` / `onSubPathCancel`. |
-| `next()` | Advance one step. Completes the path on the last step. |
-| `previous()` | Go back one step. No-op when already on the first step of a top-level path. |
-| `cancel()` | Cancel the active path (or sub-path). |
-| `setData(key, value)` | Update a single data value; emits `stateChanged`. When `TData` is specified, `key` and `value` are type-checked against your data shape. |
-| `goToStep(stepId)` | Jump directly to a step by ID. Calls `onLeave`/`onEnter`; bypasses guards and `shouldSkip`. |
-| `goToStepChecked(stepId)` | Jump to a step by ID, checking `canMoveNext` (forward) or `canMovePrevious` (backward) first. Blocked if the guard returns false. |
-| `snapshot()` | Synchronous read of the current `PathSnapshot \| null`. |
-
-`PathFacade` accepts an optional generic `PathFacade<TData>`. Because Angular's DI cannot carry generics at runtime, narrow it with a cast at the injection site:
-
-```typescript
-protected readonly facade = inject(PathFacade) as PathFacade<MyData>;
-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
+## Quick start
 
 ```typescript
+// job-application.component.ts
 import { Component } from "@angular/core";
-import { PathFacade, injectPath } from "@daltonr/pathwrite-angular";
+import {
+  PathShellComponent,
+  PathStepDirective,
+} from "@daltonr/pathwrite-angular/shell";
+import { PathFacade } from "@daltonr/pathwrite-angular";
+import type { PathData } from "@daltonr/pathwrite-angular";
+import { applicationPath } from "./application-path";
+import { DetailsStepComponent } from "./details-step.component";
+import { ReviewStepComponent } from "./review-step.component";
 
 @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
-```
-
-#### Typing `setData` key parameters
-
-`setData` is typed as `setData<K extends string & keyof TData>(key: K, value: TData[K])`.
-The `string &` intersection is necessary because `keyof T` includes `number` and `symbol`
-(all valid JavaScript property key types), but `setData` only accepts string keys.
-
-When writing a reusable update method that receives a field name as a parameter, use
-`string & keyof TData` — not just `keyof TData` — to match the constraint:
-
-```typescript
-// ❌ Type error: keyof ContactData is string | number | symbol
-protected update(field: keyof ContactData, value: string): void {
-  this.path.setData(field, value);
-}
-
-// ✅ Correct: string & keyof ensures the type matches setData's signature
-protected update(field: string & keyof ContactData, value: string): void {
-  this.path.setData(field, value);
-}
-```
-
-Inline string literals are always fine — this pattern only matters when passing a key as a variable.
-
-#### Reading step data without local state
-
-Rather than mirroring engine data into local component state, use a typed getter that reads
-directly from the snapshot signal. Angular tracks the signal read during template evaluation,
-so any engine update (including back-navigation) triggers a re-render automatically:
-
-```typescript
-export class PersonalInfoStepComponent {
-  protected readonly path = injectPath<OnboardingData>();
-
-  // No local state, no ngOnInit, no dual-update event handlers.
-  protected get data(): OnboardingData {
-    return (this.path.snapshot()?.data ?? {}) as OnboardingData;
-  }
-}
-```
-
-Template reads from `data`; writes go directly to the engine:
-
-```html
-<input [value]="data.firstName ?? ''"
-       (input)="path.setData('firstName', $any($event.target).value.trim())" />
-```
-
-### 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],
+  imports: [PathShellComponent, PathStepDirective, DetailsStepComponent, ReviewStepComponent],
   template: `
-    <pw-shell #shell ...>
-      <ng-template pwStep="contact">
-        <input (input)="shell.facade.setData('name', $any($event.target).value)" />
+    <pw-shell
+      [path]="path"
+      [initialData]="{ name: '', email: '' }"
+      (complete)="onDone($event)"
+    >
+      <ng-template pwStep="details">
+        <app-details-step />
+      </ng-template>
+      <ng-template pwStep="review">
+        <app-review-step />
       </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
+export class JobApplicationComponent {
+  protected readonly path = applicationPath;
+  protected onDone(data: PathData): void {
+    console.log("Submitted:", data);
   }
 }
 ```
 
-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
-`FormGroup` to the path engine. Call it once (typically in `ngOnInit`) and every
-form value change is automatically propagated to the engine via `setData`, keeping
-`canMoveNext` guards reactive without any manual plumbing.
-
 ```typescript
-import { PathFacade, syncFormGroup } from "@daltonr/pathwrite-angular";
+// details-step.component.ts
+import { Component } from "@angular/core";
+import { injectPath } from "@daltonr/pathwrite-angular";
 
 @Component({
-  providers: [PathFacade],
+  selector: "app-details-step",
+  standalone: true,
   template: `
-    <form [formGroup]="form">
-      <input formControlName="name" />
-      <input formControlName="email" />
-    </form>
-    <button [disabled]="!(snapshot()?.canMoveNext)" (click)="facade.next()">Next</button>
+    @if (path.snapshot(); as s) {
+      <input
+        [value]="s.data['name'] ?? ''"
+        (input)="path.setData('name', $any($event.target).value)"
+        placeholder="Name"
+      />
+      <input
+        type="email"
+        [value]="s.data['email'] ?? ''"
+        (input)="path.setData('email', $any($event.target).value)"
+        placeholder="Email"
+      />
+    }
   `
 })
-export class DetailsStepComponent implements OnInit {
-  protected readonly facade  = inject(PathFacade);
-  protected readonly snapshot = toSignal(this.facade.state$, { initialValue: null });
-
-  protected readonly form = new FormGroup({
-    name:  new FormControl('', Validators.required),
-    email: new FormControl('', [Validators.required, Validators.email]),
-  });
-
-  async ngOnInit() {
-    await this.facade.start(myPath, { name: '', email: '' });
-    // Immediately syncs current form values and keeps them in sync on every change.
-    // Cleanup is automatic when the component is destroyed.
-    syncFormGroup(this.facade, this.form, inject(DestroyRef));
-  }
+export class DetailsStepComponent {
+  protected readonly path = injectPath();
 }
 ```
 
-The corresponding path definition can now use a clean `canMoveNext` guard with no
-manual sync code in the template:
-
-```typescript
-const myPath: PathDefinition = {
-  id: 'registration',
-  steps: [
-    {
-      id: 'details',
-      canMoveNext: (ctx) =>
-        typeof ctx.data.name  === 'string' && ctx.data.name.trim().length > 0 &&
-        typeof ctx.data.email === 'string' && ctx.data.email.includes('@'),
-    },
-    { id: 'review' },
-  ],
-};
-```
-
-### `syncFormGroup` signature
-
-```typescript
-function syncFormGroup(
-  facade:     PathFacade,
-  formGroup:  FormGroupLike,
-  destroyRef?: DestroyRef
-): () => void
-```
-
-| Parameter | Type | Description |
-|-----------|------|-------------|
-| `facade` | `PathFacade` | The facade to write values into. |
-| `formGroup` | `FormGroupLike` | Any Angular `FormGroup` (or any object satisfying the duck interface). |
-| `destroyRef` | `DestroyRef` *(optional)* | Pass `inject(DestroyRef)` to auto-unsubscribe on component destroy. |
-| **returns** | `() => void` | Cleanup function — call manually if not using `DestroyRef`. |
-
-#### Behaviour details
-
-- **Immediate sync** — current `getRawValue()` is written on the first call, so
-  guards evaluate against the real form state from the first snapshot.
-- **Disabled controls included** — uses `getRawValue()` (not `formGroup.value`)
-  so disabled controls are always synced.
-- **Safe before `start()`** — if no path is active when a change fires, the call
-  is silently ignored (no error).
-- **`FormGroupLike` duck interface** — `@angular/forms` is not a required import;
-  any object with `getRawValue()` and `valueChanges` works.
-
-### Lifecycle
-
-`PathFacade` implements `OnDestroy`. When Angular destroys the providing component, `ngOnDestroy` is called automatically, which:
-- Unsubscribes from the internal `PathEngine`
-- Completes `state$` and `events$`
-
-## Using with signals (Angular 16+)
+## PathFacade
 
-`PathFacade` ships a pre-wired `stateSignal` so no manual `toSignal()` call is
-needed:
+`PathFacade` must be provided at the **component level** (not root) so each wizard gets its own isolated engine instance and Angular destroys it automatically when the component is destroyed.
 
 ```typescript
 @Component({ providers: [PathFacade] })
-export class MyComponent {
-  protected readonly facade = inject(PathFacade);
-
-  // Use stateSignal directly — no toSignal() required
-  protected readonly snapshot = this.facade.stateSignal;
-
-  // Derive computed values
-  public readonly isActive    = computed(() => this.snapshot() !== null);
-  public readonly currentStep = computed(() => this.snapshot()?.stepId ?? null);
-  public readonly canAdvance  = computed(() => this.snapshot()?.canMoveNext ?? false);
-}
-```
-
-If you prefer the Observable-based approach, `toSignal()` still works as before:
-
-```typescript
-public readonly snapshot = toSignal(this.facade.state$, { initialValue: null });
-```
-
-## Using with the async pipe
-
-```html
-<ng-container *ngIf="facade.state$ | async as s">
-  <p>{{ s.pathId }} / {{ s.stepId }}</p>
-</ng-container>
-```
-
-## Peer dependencies
-
-| Package | Version |
-|---------|---------|
-| `@angular/core` | `>=16.0.0` |
-| `rxjs` | `>=7.0.0` |
-
----
-
-## Default UI — `<pw-shell>`
-
-The Angular adapter ships an optional shell component that renders a complete progress indicator, step content area, and navigation buttons out of the box. You only need to define the per-step content.
-
-The shell lives in a separate entry point so that headless-only usage does not pull in the Angular compiler:
-
-```typescript
-import {
-  PathShellComponent,
-  PathStepDirective,
-  PathShellHeaderDirective,
-  PathShellFooterDirective,
-} from "@daltonr/pathwrite-angular/shell";
-```
-
-### Usage
-
-```typescript
-@Component({
-  imports: [PathShellComponent, PathStepDirective],
-  template: `
-    <pw-shell [path]="myPath" [initialData]="{ name: '' }" (complete)="onDone($event)">
-      <ng-template pwStep="details"><app-details-form /></ng-template>
-      <ng-template pwStep="review"><app-review-panel /></ng-template>
-    </pw-shell>
-  `
-})
-export class MyComponent {
-  protected myPath = coursePath;
-  protected onDone(data: PathData) { console.log("Done!", data); }
-}
+export class MyWizardComponent { }
 ```
 
-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.
+### Observables and signals
 
-### Context sharing
+| Member | Type | Description |
+|--------|------|-------------|
+| `state$` | `Observable<PathSnapshot \| null>` | Current snapshot. Backed by a `BehaviorSubject` — late subscribers receive the current value immediately. |
+| `stateSignal` | `Signal<PathSnapshot \| null>` | Pre-wired signal version of `state$`. Use directly without `toSignal()`. |
+| `events$` | `Observable<PathEvent>` | All engine events: `stateChanged`, `completed`, `cancelled`, `resumed`. |
 
-`PathShellComponent` provides a `PathFacade` instance in its own `providers` array
-and passes its component-level `Injector` to every step template via
-`ngTemplateOutletInjector`. Step components can therefore resolve the shell's
-`PathFacade` directly via `inject()` — no extra provider setup required:
+### Methods
 
-```typescript
-// Step component — inject(PathFacade) resolves the shell's instance automatically
-@Component({
-  template: `
-    <input [value]="snapshot()?.data?.['name'] ?? ''"
-           (input)="facade.setData('name', $event.target.value)" />
-  `
-})
-export class DetailsFormComponent {
-  protected readonly facade   = inject(PathFacade);
-  protected readonly snapshot = this.facade.stateSignal;
-}
-```
+| Method | Description |
+|--------|-------------|
+| `snapshot()` | Synchronous read of the current `PathSnapshot \| null`. |
+| `start(definition, data?)` | Start or re-start a path. |
+| `restart(definition, data?)` | Tear down any active path and start fresh. Safe to call at any time. |
+| `next()` | Advance one step. Completes the path on the last step. |
+| `previous()` | Go back one step. No-op on the first step of a top-level path. |
+| `cancel()` | Cancel the active path (or sub-path). |
+| `goToStep(stepId)` | Jump to a step by ID. Calls `onLeave`/`onEnter`; bypasses guards. |
+| `goToStepChecked(stepId)` | Jump to a step by ID, checking the current step's guard first. |
+| `setData(key, value)` | Update a single data field. Type-safe when `TData` is specified. |
+| `startSubPath(definition, data?, meta?)` | Push a sub-path. `meta` is returned to `onSubPathComplete`/`onSubPathCancel`. |
+| `adoptEngine(engine)` | Adopt an externally-managed `PathEngine` (e.g. from `restoreOrStart()`). |
 
-The parent component hosting `<pw-shell>` does **not** need its own
-`PathFacade` provider. To access the facade from the parent, use `@ViewChild`:
+## `<pw-shell>` inputs/outputs
 
-```typescript
-@Component({
-  imports: [PathShellComponent, PathStepDirective],
-  template: `
-    <pw-shell #shell [path]="myPath" (complete)="onDone($event)">
-      <ng-template pwStep="details"><app-details-form /></ng-template>
-    </pw-shell>
-  `
-})
-export class MyComponent {
-  @ViewChild('shell', { read: PathShellComponent }) shell!: PathShellComponent;
-  protected onDone(data: PathData) { console.log('done', data); }
-}
-```
+Step content is provided via `<ng-template pwStep="stepId">` directives inside `<pw-shell>`. The `pwStep` string must exactly match the step's `id`.
 
 ### Inputs
 
 | Input | Type | Default | Description |
 |-------|------|---------|-------------|
-| `path` | `PathDefinition` | — | The path definition to drive. Required unless `[engine]` is provided. |
-| `engine` | `PathEngine` | — | An externally-managed engine (e.g. from `restoreOrStart()`). When provided, `autoStart` is suppressed and the shell immediately reflects the engine's current state. Use `@if (engine)` in the parent template to gate mounting until the engine is ready. |
+| `path` | `PathDefinition` | required | Path definition to drive. Mutually exclusive with `engine`. |
 | `initialData` | `PathData` | `{}` | Initial data passed to `facade.start()`. |
-| `autoStart` | `boolean` | `true` | Start the path automatically on `ngOnInit`. Ignored when `[engine]` is provided. |
+| `engine` | `PathEngine` | — | Externally-managed engine (e.g. from `restoreOrStart()`). Suppresses `autoStart`. |
+| `autoStart` | `boolean` | `true` | Start the path on `ngOnInit`. Ignored when `engine` is provided. |
+| `validationDisplay` | `"summary" \| "inline" \| "both"` | `"summary"` | Where `fieldErrors` are rendered. Use `"inline"` so step components render their own errors. |
+| `loadingLabel` | `string` | — | Label shown while the path is navigating. |
+| `footerLayout` | `"wizard" \| "form" \| "auto"` | `"auto"` | `"wizard"`: Back on left, Cancel+Submit on right. `"form"`: Cancel on left, Submit on right, no Back. `"auto"` picks `"form"` for single-step paths. |
+| `hideProgress` | `boolean` | `false` | Hide the progress indicator. Also hidden automatically for single-step paths. |
 | `backLabel` | `string` | `"Previous"` | Previous button label. |
 | `nextLabel` | `string` | `"Next"` | Next button label. |
 | `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. 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
 
@@ -519,489 +144,27 @@ export class MyComponent {
 | `(cancel)` | `PathData` | Emitted when the path is cancelled. |
 | `(event)` | `PathEvent` | Emitted for every engine event. |
 
-### Customising the header and footer
-
-Use `pwShellHeader` and `pwShellFooter` directives to replace the built-in progress bar or navigation buttons with your own templates. Both are declared on `<ng-template>` elements inside the shell.
+## `injectPath()`
 
-**`pwShellHeader`** — receives the current `PathSnapshot` as the implicit template variable:
+`injectPath()` is the preferred API for step components and forms rendered inside `<pw-shell>`. It resolves the `PathFacade` from the nearest injector in the tree and returns a signal-based interface typed with an optional `TData` generic — no `providers: [PathFacade]` needed in step components.
 
 ```typescript
-@Component({
-  imports: [PathShellComponent, PathStepDirective, PathShellHeaderDirective],
-  template: `
-    <pw-shell [path]="myPath">
-      <ng-template pwShellHeader let-s>
-        <p>Step {{ s.stepIndex + 1 }} of {{ s.stepCount }} — {{ s.stepTitle }}</p>
-      </ng-template>
-      <ng-template pwStep="details"><app-details-form /></ng-template>
-      <ng-template pwStep="review"><app-review-panel /></ng-template>
-    </pw-shell>
-  `
-})
-export class MyComponent { ... }
-```
-
-**`pwShellFooter`** — receives the snapshot as the implicit variable and an `actions` variable with all navigation callbacks:
-
-```typescript
-@Component({
-  imports: [PathShellComponent, PathStepDirective, PathShellFooterDirective],
-  template: `
-    <pw-shell [path]="myPath">
-      <ng-template pwShellFooter let-s let-actions="actions">
-        <button (click)="actions.previous()" [disabled]="s.isFirstStep || s.isNavigating">Back</button>
-        <button (click)="actions.next()"     [disabled]="!s.canMoveNext || s.isNavigating">
-          {{ s.isLastStep ? 'Complete' : 'Next' }}
-        </button>
-      </ng-template>
-      <ng-template pwStep="details"><app-details-form /></ng-template>
-    </pw-shell>
-  `
-})
-export class MyComponent { ... }
-```
-
-`actions` (`PathShellActions`) contains: `next`, `previous`, `cancel`, `goToStep`, `goToStepChecked`, `setData`, `restart`. All return `Promise<void>`.
-
-`restart()` restarts the shell's own `[path]` input with its own `[initialData]` input — useful for a "Start over" button in a custom footer.
-
-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.
+import { injectPath } from "@daltonr/pathwrite-angular";
 
-**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" (complete)="isActive = false" (cancel)="isActive = false">
-    <ng-template pwStep="details"><app-details-form /></ng-template>
-  </pw-shell>
-} @else {
-  <button (click)="isActive = true">Try Again</button>
+export class DetailsStepComponent {
+  protected readonly path = injectPath<ApplicationData>();
+  // path.snapshot() — Signal<PathSnapshot | null>
+  // path.setData(key, value) — type-safe with TData
+  // path.next(), path.previous(), path.cancel(), etc.
 }
 ```
 
-**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" (complete)="onDone($event)">
-  <ng-template pwStep="details"><app-details-form /></ng-template>
-</pw-shell>
-
-<button (click)="shell.restart()">Try Again</button>
-```
+## Further reading
 
-`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.
+- [Angular getting started guide](../../docs/getting-started/frameworks/angular.md)
+- [Navigation & guards](../../docs/guides/navigation.md)
+- [Full documentation](../../docs/README.md)
 
 ---
 
-## Sub-Paths
-
-Sub-paths allow you to nest multi-step workflows. Common use cases include:
-- Running a child workflow per collection item (e.g., approve each document)
-- Conditional drill-down flows (e.g., "Add payment method" modal)
-- Reusable wizard components
-
-### Basic Sub-Path Flow
-
-When a sub-path is active:
-- The shell switches to show the sub-path's steps
-- The progress bar displays sub-path steps (not main path steps)
-- Pressing Back on the first sub-path step **cancels** the sub-path and returns to the parent
-- The `PathFacade` (and thus `state$`, `stateSignal`) reflects the **sub-path** snapshot, not the parent's
-
-### Complete Example: Approver Collection
-
-```typescript
-import { PathData, PathDefinition, PathFacade } from "@daltonr/pathwrite-angular";
-
-// Sub-path data shape
-interface ApproverReviewData extends PathData {
-  decision: "approve" | "reject" | "";
-  comments: string;
-}
-
-// Main path data shape
-interface ApprovalWorkflowData extends PathData {
-  documentTitle: string;
-  approvers: string[];
-  approvals: Array<{ approver: string; decision: string; comments: string }>;
-}
-
-// Define the sub-path (approver review wizard)
-const approverReviewPath: PathDefinition<ApproverReviewData> = {
-  id: "approver-review",
-  steps: [
-    { id: "review", title: "Review Document" },
-    {
-      id: "decision",
-      title: "Make Decision",
-      canMoveNext: ({ data }) =>
-        data.decision === "approve" || data.decision === "reject",
-      validationMessages: ({ data }) =>
-        !data.decision ? ["Please select Approve or Reject"] : []
-    },
-    { id: "comments", title: "Add Comments" }
-  ]
-};
-
-// Define the main path
-const approvalWorkflowPath: PathDefinition<ApprovalWorkflowData> = {
-  id: "approval-workflow",
-  steps: [
-    {
-      id: "setup",
-      title: "Setup Approval",
-      canMoveNext: ({ data }) =>
-        (data.documentTitle ?? "").trim().length > 0 &&
-        data.approvers.length > 0
-    },
-    {
-      id: "run-approvals",
-      title: "Collect Approvals",
-      // Block "Next" until all approvers have completed their reviews
-      canMoveNext: ({ data }) =>
-        data.approvals.length === data.approvers.length,
-      validationMessages: ({ data }) => {
-        const remaining = data.approvers.length - data.approvals.length;
-        return remaining > 0
-          ? [`${remaining} approver(s) pending review`]
-          : [];
-      },
-      // When an approver finishes their sub-path, record the result
-      onSubPathComplete(subPathId, subPathData, ctx, meta) {
-        const approverName = meta?.approverName as string;
-        const result = subPathData as ApproverReviewData;
-        return {
-          approvals: [
-            ...ctx.data.approvals,
-            {
-              approver: approverName,
-              decision: result.decision,
-              comments: result.comments
-            }
-          ]
-        };
-      },
-      // If an approver cancels (presses Back on first step), you can track it
-      onSubPathCancel(subPathId, subPathData, ctx, meta) {
-        console.log(`${meta?.approverName} cancelled their review`);
-        // Optionally return data changes, or just log
-      }
-    },
-    { id: "summary", title: "Summary" }
-  ]
-};
-
-// Component
-@Component({
-  selector: 'app-approval-workflow',
-  standalone: true,
-  imports: [PathShellComponent, PathStepDirective],
-  providers: [PathFacade],
-  template: `
-    <pw-shell [path]="approvalWorkflowPath" [initialData]="initialData">
-      <!-- Main path steps -->
-      <ng-template pwStep="setup">
-        <input [(ngModel)]="facade.snapshot()!.data.documentTitle" placeholder="Document title" />
-        <!-- approver selection UI here -->
-      </ng-template>
-
-      <ng-template pwStep="run-approvals">
-        <h3>Approvers</h3>
-        <ul>
-          @for (approver of facade.snapshot()!.data.approvers; track $index) {
-            <li>
-              {{ approver }}
-              @if (!hasApproval(approver)) {
-                <button (click)="launchReviewForApprover(approver, $index)">
-                  Start Review
-                </button>
-              } @else {
-                <span>✓ {{ getApproval(approver)?.decision }}</span>
-              }
-            </li>
-          }
-        </ul>
-      </ng-template>
-
-      <ng-template pwStep="summary">
-        <h3>All Approvals Collected</h3>
-        <ul>
-          @for (approval of facade.snapshot()!.data.approvals; track approval.approver) {
-            <li>{{ approval.approver }}: {{ approval.decision }}</li>
-          }
-        </ul>
-      </ng-template>
-
-      <!-- Sub-path steps (must be co-located in the same pw-shell) -->
-      <ng-template pwStep="review">
-        <p>Review the document: "{{ facade.snapshot()!.data.documentTitle }}"</p>
-      </ng-template>
-
-      <ng-template pwStep="decision">
-        <label><input type="radio" value="approve" [(ngModel)]="facade.snapshot()!.data.decision" /> Approve</label>
-        <label><input type="radio" value="reject" [(ngModel)]="facade.snapshot()!.data.decision" /> Reject</label>
-      </ng-template>
-
-      <ng-template pwStep="comments">
-        <textarea [(ngModel)]="facade.snapshot()!.data.comments" placeholder="Optional comments"></textarea>
-      </ng-template>
-    </pw-shell>
-  `
-})
-export class ApprovalWorkflowComponent {
-  protected readonly facade = inject(PathFacade) as PathFacade<ApprovalWorkflowData>;
-  protected readonly approvalWorkflowPath = approvalWorkflowPath;
-  protected readonly initialData = { documentTitle: '', approvers: [], approvals: [] };
-
-  protected launchReviewForApprover(approverName: string, index: number): void {
-    // Pass correlation data via `meta` — it's echoed back to onSubPathComplete
-    void this.facade.startSubPath(
-      approverReviewPath,
-      { decision: "", comments: "" },
-      { approverName, approverIndex: index }
-    );
-  }
-
-  protected hasApproval(approver: string): boolean {
-    return this.facade.snapshot()!.data.approvals.some(a => a.approver === approver);
-  }
-
-  protected getApproval(approver: string) {
-    return this.facade.snapshot()!.data.approvals.find(a => a.approver === approver);
-  }
-}
-```
-
-### Key Notes
-
-**1. Sub-path steps must be co-located with main path steps**  
-All `pwStep` templates (main path + sub-path steps) live in the same `<pw-shell>`. When a sub-path is active, the shell renders the sub-path's step templates. This means:
-- Parent and sub-path step IDs **must not collide** (e.g., don't use `summary` in both)
-- The shell matches step IDs from the current path only (main or sub), but all templates are registered globally
-
-**2. The `meta` correlation field**  
-`startSubPath` accepts an optional third argument (`meta`) that is returned unchanged to `onSubPathComplete` and `onSubPathCancel`. Use it to correlate which collection item triggered the sub-path:
-
-```typescript
-facade.startSubPath(subPath, initialData, { itemIndex: 3, itemId: "abc" });
-
-// In the parent step:
-onSubPathComplete(subPathId, subPathData, ctx, meta) {
-  const itemIndex = meta?.itemIndex; // 3
-}
-```
-
-**3. Root progress bar persists during sub-paths**  
-When `snapshot.nestingLevel > 0`, you're in a sub-path. The shell automatically renders a compact, muted **root progress bar** above the sub-path's own progress bar so users always see their place in the main flow. The `steps` array in the snapshot contains the sub-path's steps. Use `snapshot.rootProgress` (type `RootProgress`) in a custom `pwShellHeader` template to render your own persistent top-level indicator.
-
-**4. Accessing parent path data from sub-path components**  
-There is currently no way to inject a "parent facade" in sub-path step components. If a sub-path step needs parent data (e.g., the document title), pass it via `initialData` when calling `startSubPath`:
-
-```typescript
-facade.startSubPath(approverReviewPath, {
-  decision: "",
-  comments: "",
-  documentTitle: facade.snapshot()!.data.documentTitle // copy from parent
-});
-```
-
----
-
-## Guards and Lifecycle Hooks
-
-### Defensive Guards (Important!)
-
-**Guards and `validationMessages` are evaluated *before* `onEnter` runs on first entry.**
-
-If you access fields in a guard that `onEnter` is supposed to initialize, the guard will throw a `TypeError` on startup. Write guards defensively using nullish coalescing:
-
-```typescript
-// ✗ Unsafe — crashes if data.name is undefined
-canMoveNext: ({ data }) => data.name.trim().length > 0
-
-// ✓ Safe — handles undefined gracefully
-canMoveNext: ({ data }) => (data.name ?? "").trim().length > 0
-```
-
-Alternatively, pass `initialData` to `start()` / `<pw-shell>` so all fields are present from the first snapshot:
-
-```typescript
-<pw-shell [path]="myPath" [initialData]="{ name: '', age: 0 }" />
-```
-
-If a guard throws, the engine catches it, logs a warning, and returns `true` (allow navigation) as a safe default.
-
-### Async Guards and Validation Messages
-
-Guards and `validationMessages` must be **synchronous** for inclusion in snapshots. Async functions are detected and warned about:
-- Async `canMoveNext` / `canMovePrevious` default to `true` (optimistic)
-- Async `validationMessages` default to `[]`
-
-The async version is still enforced during actual navigation (when you call `next()` / `previous()`), but the snapshot won't reflect the pending state. If you need async validation, perform it in the guard and store the result in `data` so the guard can read it synchronously.
-
-### `isFirstEntry` Flag
-
-The `PathStepContext` passed to all hooks includes an `isFirstEntry: boolean` flag. It's `true` the first time a step is visited, `false` on re-entry (e.g., after navigating back then forward again).
-
-Use it to distinguish initialization from re-entry:
-
-```typescript
-{
-  id: "details",
-  onEnter: ({ isFirstEntry, data }) => {
-    if (isFirstEntry) {
-      // Only pre-fill on first visit, not when returning via Back
-      return { name: "Default Name" };
-    }
-  }
-}
-```
-
-**Important:** `onEnter` fires every time you enter the step. If you want "initialize once" behavior, either:
-1. Use `isFirstEntry` to conditionally return data
-2. Provide `initialData` to `start()` instead of using `onEnter`
-
----
-
-## Persistence
-
-Use with [@daltonr/pathwrite-store](../store) for automatic state persistence. The engine is created externally via `restoreOrStart()` and passed directly to `<pw-shell>` via the `[engine]` input.
-
-### Simple persistence example
-
-```typescript
-import { Component, OnInit } from '@angular/core';
-import { PathEngine } from '@daltonr/pathwrite-angular';
-import { PathShellComponent, PathStepDirective } from '@daltonr/pathwrite-angular/shell';
-import { HttpStore, restoreOrStart, persistence } from '@daltonr/pathwrite-store';
-import { signupPath } from './signup-path';
-
-@Component({
-  selector: 'app-signup-wizard',
-  standalone: true,
-  imports: [PathShellComponent, PathStepDirective],
-  template: `
-    @if (engine) {
-      <pw-shell [path]="path" [engine]="engine" (complete)="onComplete($event)">
-        <ng-template pwStep="details"><app-details-form /></ng-template>
-        <ng-template pwStep="review"><app-review-panel /></ng-template>
-      </pw-shell>
-    } @else {
-      <p>Loading…</p>
-    }
-  `
-})
-export class SignupWizardComponent implements OnInit {
-  path = signupPath;
-  engine: PathEngine | null = null;
-
-  async ngOnInit() {
-    const store = new HttpStore({ baseUrl: '/api/wizard' });
-    const key = 'user:signup';
-
-    const { engine, restored } = await restoreOrStart({
-      store,
-      key,
-      path: this.path,
-      initialData: { name: '', email: '' },
-      observers: [
-        persistence({ store, key, strategy: 'onNext' })
-      ]
-    });
-
-    this.engine = engine;
-
-    if (restored) {
-      console.log('Progress restored — resuming from', engine.snapshot()?.stepId);
-    }
-  }
-
-  onComplete(data: any) {
-    console.log('Wizard completed:', data);
-  }
-}
-```
-
-### Key points
-
-- **`[engine]`** passes an externally-managed engine directly to the shell. The shell adopts it immediately and skips `autoStart`.
-- **`@if (engine)`** acts as the async gate — the shell only mounts once the engine is ready, so there is no timing window where `autoStart` could fire before the engine arrives.
-- **`restoreOrStart()`** handles the load-or-create logic: if saved state exists on the server, it restores the engine mid-flow; otherwise it starts fresh.
-
----
-
-## Styling
-
-Import the optional stylesheet for sensible default styles. All visual values are CSS custom properties (`--pw-*`) so you can theme without overriding selectors.
-
-### In `angular.json` (recommended)
-
-```json
-"styles": [
-  "src/styles.css",
-  "node_modules/@daltonr/pathwrite-angular/dist/index.css"
-]
-```
-
-### In a global stylesheet
-
-```css
-@import "@daltonr/pathwrite-angular/styles.css";
-```
-
-### Theming
-
-Override any `--pw-*` variable to customise the appearance:
-
-```css
-:root {
-  --pw-color-primary: #8b5cf6;
-  --pw-shell-radius: 12px;
-}
-```
-
-### Available CSS Custom Properties
-
-**Layout:**
-- `--pw-shell-max-width` — Maximum width of the shell (default: `720px`)
-- `--pw-shell-padding` — Internal padding (default: `24px`)
-- `--pw-shell-gap` — Gap between header, body, footer (default: `20px`)
-- `--pw-shell-radius` — Border radius for cards (default: `10px`)
-
-**Colors:**
-- `--pw-color-bg` — Background color (default: `#ffffff`)
-- `--pw-color-border` — Border color (default: `#dbe4f0`)
-- `--pw-color-text` — Primary text color (default: `#1f2937`)
-- `--pw-color-muted` — Muted text color (default: `#5b677a`)
-- `--pw-color-primary` — Primary/accent color (default: `#2563eb`)
-- `--pw-color-primary-light` — Light primary for backgrounds (default: `rgba(37, 99, 235, 0.12)`)
-- `--pw-color-btn-bg` — Button background (default: `#f8fbff`)
-- `--pw-color-btn-border` — Button border (default: `#c2d0e5`)
-
-**Validation:**
-- `--pw-color-error` — Error text color (default: `#dc2626`)
-- `--pw-color-error-bg` — Error background (default: `#fef2f2`)
-- `--pw-color-error-border` — Error border (default: `#fecaca`)
-
-**Progress Indicator:**
-- `--pw-dot-size` — Step dot size (default: `32px`)
-- `--pw-dot-font-size` — Font size inside dots (default: `13px`)
-- `--pw-track-height` — Progress track height (default: `4px`)
-
-**Buttons:**
-- `--pw-btn-padding` — Button padding (default: `8px 16px`)
-- `--pw-btn-radius` — Button border radius (default: `6px`)
-
-
----
-
-© 2026 Devjoy Ltd. MIT License.
-
+MIT — © 2026 Devjoy Ltd.