@signaltree/ng-forms 3.0.2 → 4.0.0

package/README.md

@@ -1,884 +1,220 @@
 # @signaltree/ng-forms
 
-Angular Forms integration for SignalTree featuring reactive forms binding, validation, form state management, and seamless Angular integration.
+Angular 20 signal forms meet SignalTree. `@signaltree/ng-forms` keeps your form state, validation, persistence, and wizard flows in sync with the rest of your application signals—no manual plumbing.
 
 **Bundle size: 3.38KB gzipped**
 
-## What is @signaltree/ng-forms?
-
-The ng-forms package provides deep Angular Forms integration:
-
-- **Reactive Forms binding** with automatic synchronization
-- **Template-driven forms** support with signals
-- **Advanced validation** with real-time feedback
-- **Form state management** (dirty, touched, valid states)
-- **Dynamic form generation** from SignalTree state
-- **Cross-field validation** and complex form logic
-
 ## Installation
 
 ```bash
-npm install @signaltree/core @signaltree/ng-forms
+pnpm add @signaltree/core @signaltree/ng-forms
 ```
 
-## Basic usage
-
-```typescript
-import { signalTree } from '@signaltree/core';
-import { withForms } from '@signaltree/ng-forms';
-
-const tree = signalTree({
-  user: {
-    name: '',
-    email: '',
-    age: 0,
-  },
-  preferences: {
-    newsletter: false,
-    theme: 'light',
-  },
-});
-
-// Automatic form generation
-const userForm = tree.createForm('user');
-const preferencesForm = tree.createForm('preferences');
-
-// Forms automatically sync with SignalTree state
-```
+> The package targets Angular 20.3+ and TypeScript 5.5+. For Angular 17–19 support use the 0.10.x line.
 
-## Core features
-
-### Reactive Forms Integration
+## Quick start
 
 ```typescript
 import { Component } from '@angular/core';
-import { FormBuilder, Validators } from '@angular/forms';
+import { createFormTree, validators } from '@signaltree/ng-forms';
+
+interface ProfileForm {
+  name: string;
+  email: string;
+  marketing: boolean;
+}
 
 @Component({
+  selector: 'app-profile-form',
   template: `
-    <form [formGroup]="userForm" (ngSubmit)="onSubmit()">
-      <!-- Form automatically synced with SignalTree -->
+    <form [formGroup]="profile.form" (ngSubmit)="save()">
       <input formControlName="name" placeholder="Name" />
+      <span class="error" *ngIf="profile.getFieldError('name')()">
+        {{ profile.getFieldError('name')() }}
+      </span>
+
       <input formControlName="email" placeholder="Email" />
-      <input formControlName="age" type="number" placeholder="Age" />
+      <span class="error" *ngIf="profile.getFieldError('email')()">
+        {{ profile.getFieldError('email')() }}
+      </span>
 
-      <button type="submit" [disabled]="userForm.invalid">Submit</button>
+      <label> <input type="checkbox" formControlName="marketing" /> Email marketing </label>
+
+      <button type="submit" [disabled]="profile.valid() === false">
+        {{ profile.submitting() ? 'Saving...' : 'Save profile' }}
+      </button>
     </form>
 
-    <!-- Real-time state display -->
-    <div>
-      <p>Current State: {{ tree.$.user() | json }}</p>
-      <p>Form Valid: {{ userForm.valid }}</p>
-      <p>Form Dirty: {{ userForm.dirty }}</p>
-    </div>
+    <pre>Signals: {{ profile.$.name() }} / {{ profile.$.email() }}</pre>
   `,
 })
-class UserFormComponent {
-  tree = signalTree({
-    user: {
-      name: '',
-      email: '',
-      age: 0,
-    },
-  });
-
-  // Create form with automatic binding
-  userForm = this.tree.createForm('user', {
-    name: ['', [Validators.required, Validators.minLength(2)]],
-    email: ['', [Validators.required, Validators.email]],
-    age: [0, [Validators.required, Validators.min(18)]],
-  });
-
-  onSubmit() {
-    if (this.userForm.valid) {
-      console.log('Form Data:', this.tree.$.user());
-      console.log('Form Value:', this.userForm.value);
-      // Both are automatically synchronized!
-    }
-  }
-}
-```
+export class ProfileFormComponent {
+  private storage = typeof window !== 'undefined' ? window.localStorage : undefined;
 
-### Template-Driven Forms
-
-```typescript
-@Component({
-  template: `
-    <form #userForm="ngForm" (ngSubmit)="onSubmit(userForm)">
-      <!-- Bind directly to SignalTree signals -->
-      <input name="name" ngModel [ngModel]="tree.$.user.name()" (ngModelChange)="tree.$.user.name.set($event)" #name="ngModel" required minlength="2" />
-      <div *ngIf="name.invalid && name.touched">Name is required (min 2 characters)</div>
-
-      <input name="email" type="email" ngModel [ngModel]="tree.$.user.email()" (ngModelChange)="tree.$.user.email.set($event)" #email="ngModel" required email />
-      <div *ngIf="email.invalid && email.touched">Valid email is required</div>
-
-      <button type="submit" [disabled]="userForm.invalid">Submit</button>
-    </form>
-  `,
-})
-class TemplateFormComponent {
-  tree = signalTree({
-    user: {
+  profile = createFormTree<ProfileForm>(
+    {
       name: '',
       email: '',
+      marketing: false,
     },
-  });
-
-  onSubmit(form: NgForm) {
-    if (form.valid) {
-      console.log('User Data:', this.tree.$.user());
+    {
+      persistKey: 'profile-form',
+      storage: this.storage,
+      fieldConfigs: {
+        name: { validators: validators.required('Name is required') },
+        email: {
+          validators: [validators.required(), validators.email()],
+          debounceMs: 150,
+        },
+      },
     }
-  }
-}
-```
-
-### Advanced Validation
-
-```typescript
-const tree = signalTree({
-  registration: {
-    username: '',
-    email: '',
-    password: '',
-    confirmPassword: '',
-    agreeToTerms: false,
-  },
-});
-
-// Custom validators that can access SignalTree state
-const usernameAsyncValidator = (control: AbstractControl) => {
-  return of(control.value).with(
-    delay(300), // Debounce
-    switchMap((username) =>
-      // Check if username exists (can access tree state)
-      this.userService.checkUsernameAvailability(username)
-    ),
-    map((isAvailable) => (isAvailable ? null : { usernameTaken: true }))
   );
-};
 
-const passwordMatchValidator = (group: AbstractControl) => {
-  const password = group.get('password')?.value;
-  const confirmPassword = group.get('confirmPassword')?.value;
-  return password === confirmPassword ? null : { passwordMismatch: true };
-};
-
-const registrationForm = tree.createForm(
-  'registration',
-  {
-    username: [
-      '',
-      {
-        validators: [Validators.required, Validators.minLength(3)],
-        asyncValidators: [usernameAsyncValidator],
-      },
-    ],
-    email: ['', [Validators.required, Validators.email]],
-    password: ['', [Validators.required, Validators.minLength(8)]],
-    confirmPassword: ['', Validators.required],
-    agreeToTerms: [false, Validators.requiredTrue],
-  },
-  {
-    validators: [passwordMatchValidator], // Form-level validator
-  }
-);
-
-// Real-time validation feedback
-@Component({
-  template: `
-    <form [formGroup]="registrationForm" (ngSubmit)="onSubmit()">
-      <div class="field">
-        <input formControlName="username" placeholder="Username" />
-        <div class="validation-messages">
-          @if (registrationForm.get('username')?.hasError('required')) {
-          <span class="error">Username is required</span>
-          } @if (registrationForm.get('username')?.hasError('minlength')) {
-          <span class="error">Username must be at least 3 characters</span>
-          } @if (registrationForm.get('username')?.hasError('usernameTaken')) {
-          <span class="error">Username is already taken</span>
-          } @if (registrationForm.get('username')?.pending) {
-          <span class="checking">Checking availability...</span>
-          }
-        </div>
-      </div>
-
-      <div class="field">
-        <input formControlName="password" type="password" placeholder="Password" />
-        <div class="validation-messages">
-          @if (registrationForm.get('password')?.hasError('required')) {
-          <span class="error">Password is required</span>
-          } @if (registrationForm.get('password')?.hasError('minlength')) {
-          <span class="error">Password must be at least 8 characters</span>
-          }
-        </div>
-      </div>
-
-      <div class="field">
-        <input formControlName="confirmPassword" type="password" placeholder="Confirm Password" />
-        <div class="validation-messages">
-          @if (registrationForm.hasError('passwordMismatch')) {
-          <span class="error">Passwords don't match</span>
-          }
-        </div>
-      </div>
-
-      <label>
-        <input formControlName="agreeToTerms" type="checkbox" />
-        I agree to the terms and conditions
-      </label>
-
-      <button type="submit" [disabled]="registrationForm.invalid">Register</button>
-    </form>
-  `,
-})
-class RegistrationComponent {
-  registrationForm = registrationForm;
-
-  onSubmit() {
-    if (this.registrationForm.valid) {
-      console.log('Registration Data:', tree.$.registration());
-    }
+  async save() {
+    await this.profile.submit(async (values) => {
+      // Persist values to your API or service layer here
+      console.log('Saving profile', values);
+    });
   }
 }
 ```
 
-### Dynamic Form Generation
-
-```typescript
-interface FormField {
-  name: string;
-  type: 'text' | 'email' | 'number' | 'checkbox' | 'select';
-  label: string;
-  required?: boolean;
-  options?: Array<{ value: any; label: string }>;
-  validators?: any[];
-}
-
-const tree = signalTree({
-  dynamicData: {} as Record<string, any>,
-  formConfig: {
-    fields: [] as FormField[],
-  },
-});
+The returned `FormTree` exposes:
 
-@Injectable()
-class DynamicFormService {
-  generateForm(fields: FormField[]) {
-    const formConfig: Record<string, any> = {};
+- `form`: Angular `FormGroup` for templates and directives
+- `$` / `state`: signal-backed access to individual fields
+- `errors`, `asyncErrors`, `valid`, `dirty`, `submitting`: writable signals for UI state
+- Helpers such as `setValue`, `setValues`, `reset`, `validate`, and `submit`
 
-    fields.forEach((field) => {
-      const validators = [];
-      if (field.required) validators.push(Validators.required);
-      if (field.type === 'email') validators.push(Validators.email);
+## Core capabilities
 
-      formConfig[field.name] = ['', validators];
-    });
+- **Signal-synced forms**: Bidirectional sync between Angular FormControls and SignalTree signals
+- **Per-field configuration**: Debounce, sync & async validators, and wildcard matcher support
+- **Conditional fields**: Enable/disable controls based on dynamic predicates
+- **Persistence**: Keep form state in `localStorage`, IndexedDB, or custom storage with debounced writes
+- **Validation batching**: Aggregate touched/errors updates to avoid jitter in large forms
+- **Wizard & history helpers**: Higher-level APIs for multi-step flows and undo/redo stacks
+- **Signal ↔ Observable bridge**: Convert signals to RxJS streams for interoperability
+- **Template-driven adapter**: `SignalValueDirective` bridges standalone signals with `ngModel`
 
-    return tree.createForm('dynamicData', formConfig);
-  }
-}
-
-@Component({
-  template: `
-    <form [formGroup]="dynamicForm" (ngSubmit)="onSubmit()">
-      @for (field of formFields(); track field.name) {
-      <div class="field">
-        <label>{{ field.label }}</label>
-
-        @switch (field.type) { @case ('text') {
-        <input [formControlName]="field.name" type="text" />
-        } @case ('email') {
-        <input [formControlName]="field.name" type="email" />
-        } @case ('number') {
-        <input [formControlName]="field.name" type="number" />
-        } @case ('checkbox') {
-        <input [formControlName]="field.name" type="checkbox" />
-        } @case ('select') {
-        <select [formControlName]="field.name">
-          @for (option of field.options; track option.value) {
-          <option [value]="option.value">{{ option.label }}</option>
-          }
-        </select>
-        } }
-
-        <div class="validation-messages">
-          @if (dynamicForm.get(field.name)?.invalid && dynamicForm.get(field.name)?.touched) {
-          <span class="error">{{ field.label }} is invalid</span>
-          }
-        </div>
-      </div>
-      }
-
-      <button type="submit" [disabled]="dynamicForm.invalid">Submit</button>
-    </form>
-  `,
-})
-class DynamicFormComponent {
-  formFields = computed(() => tree.$.formConfig.fields());
-  dynamicForm = this.dynamicFormService.generateForm(this.formFields());
-
-  constructor(private dynamicFormService: DynamicFormService) {}
-
-  onSubmit() {
-    if (this.dynamicForm.valid) {
-      console.log('Dynamic Form Data:', tree.$.dynamicData());
-    }
-  }
-}
-```
-
-## Advanced configuration
+## Form tree configuration
 
 ```typescript
-const tree = signalTree(state).with(
-  /* createFormTree options can be passed here if applicable */
-    // Automatic synchronization settings
-    autoSync: true,
-    syncDirection: 'bidirectional', // 'toForm' | 'toState' | 'bidirectional'
-
-    // Debounce settings for performance
-    debounceTime: 300,
-
-    // Validation settings
-    validateOnChange: true,
-    validateOnBlur: true,
-    showErrorsOnTouched: true,
-
-    // Form state management
-    trackFormState: true, // Track dirty, touched, valid states
-    persistFormState: true, // Persist across navigation
-
-    // Custom error messages
-    errorMessages: {
-      required: 'This field is required',
-      email: 'Please enter a valid email',
-      minlength: 'Minimum length not met',
-      maxlength: 'Maximum length exceeded',
-    },
-
-    // Custom validators
-    validators: {
-      strongPassword: (control: AbstractControl) => {
-        const value = control.value;
-        const hasNumber = /[0-9]/.test(value);
-        const hasUpper = /[A-Z]/.test(value);
-        const hasLower = /[a-z]/.test(value);
-        const hasSpecial = /[#?!@$%^&*-]/.test(value);
-
-        const valid = hasNumber && hasUpper && hasLower && hasSpecial;
-        return valid ? null : { strongPassword: true };
-      },
+const checkout = createFormTree(initialState, {
+  validators: {
+    'shipping.zip': (value) => (/^[0-9]{5}$/.test(String(value)) ? null : 'Enter a valid ZIP code'),
+  },
+  asyncValidators: {
+    'account.email': async (value) => ((await emailService.isTaken(value)) ? 'Email already used' : null),
+  },
+  fieldConfigs: {
+    'payment.card.number': { debounceMs: 200 },
+    'preferences.*': { validators: validators.required() },
+  },
+  conditionals: [
+    {
+      when: (values) => values.shipping.sameAsBilling,
+      fields: ['shipping.address', 'shipping.city', 'shipping.zip'],
     },
-  })
-);
+  ],
+  persistKey: 'checkout-draft',
+  storage: sessionStorage,
+  persistDebounceMs: 500,
+  validationBatchMs: 16,
+});
 ```
 
-## Real-world examples
+- `validators` / `asyncValidators`: Map paths (supports `*` globs) to declarative validation functions
+- `fieldConfigs`: Attach validators and per-field debounce without scattering logic
+- `conditionals`: Automatically disable controls when predicates fail
+- `persistKey` + `storage`: Load persisted values on creation and auto-save thereafter
+- `validationBatchMs`: Batch aggregate signal updates when running lots of validators at once
 
-### Multi-Step Form Wizard
+## Wizard flows
 
 ```typescript
-interface WizardState {
-  currentStep: number;
-  steps: {
-    personal: {
-      firstName: string;
-      lastName: string;
-      email: string;
-      phone: string;
-    };
-    address: {
-      street: string;
-      city: string;
-      state: string;
-      zipCode: string;
-    };
-    preferences: {
-      newsletter: boolean;
-      notifications: boolean;
-      theme: 'light' | 'dark';
-    };
-  };
-  validation: {
-    personalValid: boolean;
-    addressValid: boolean;
-    preferencesValid: boolean;
-  };
-}
+import { createWizardForm, FormStep } from '@signaltree/ng-forms';
 
-const wizardTree = signalTree<WizardState>({
-  currentStep: 1,
-  steps: {
-    personal: {
-      firstName: '',
-      lastName: '',
-      email: '',
-      phone: '',
-    },
-    address: {
-      street: '',
-      city: '',
-      state: '',
-      zipCode: '',
-    },
-    preferences: {
-      newsletter: false,
-      notifications: true,
-      theme: 'light',
+const steps: FormStep<AccountSetup>[] = [
+  {
+    fields: ['profile.name', 'profile.email'],
+    validate: async (form) => {
+      await form.validate('profile.email');
+      return !form.getFieldError('profile.email')();
     },
   },
-  validation: {
-    personalValid: false,
-    addressValid: false,
-    preferencesValid: false,
+  {
+    fields: ['security.password', 'security.confirm'],
   },
-});
-
-@Component({
-  template: `
-    <div class="wizard">
-      <div class="wizard-steps">
-        @for (step of steps; track step.number) {
-        <div class="step" [class.active]="currentStep() === step.number" [class.completed]="isStepCompleted(step.number)">
-          {{ step.title }}
-        </div>
-        }
-      </div>
-
-      <div class="wizard-content">
-        @switch (currentStep()) { @case (1) {
-        <form [formGroup]="personalForm">
-          <h2>Personal Information</h2>
-          <input formControlName="firstName" placeholder="First Name" />
-          <input formControlName="lastName" placeholder="Last Name" />
-          <input formControlName="email" placeholder="Email" />
-          <input formControlName="phone" placeholder="Phone" />
-        </form>
-        } @case (2) {
-        <form [formGroup]="addressForm">
-          <h2>Address Information</h2>
-          <input formControlName="street" placeholder="Street Address" />
-          <input formControlName="city" placeholder="City" />
-          <input formControlName="state" placeholder="State" />
-          <input formControlName="zipCode" placeholder="ZIP Code" />
-        </form>
-        } @case (3) {
-        <form [formGroup]="preferencesForm">
-          <h2>Preferences</h2>
-          <label>
-            <input formControlName="newsletter" type="checkbox" />
-            Subscribe to newsletter
-          </label>
-          <label>
-            <input formControlName="notifications" type="checkbox" />
-            Enable notifications
-          </label>
-          <select formControlName="theme">
-            <option value="light">Light Theme</option>
-            <option value="dark">Dark Theme</option>
-          </select>
-        </form>
-        } }
-      </div>
-
-      <div class="wizard-navigation">
-        <button (click)="previousStep()" [disabled]="currentStep() === 1">Previous</button>
-
-        @if (currentStep() < 3) {
-        <button (click)="nextStep()" [disabled]="!canProceed()">Next</button>
-        } @else {
-        <button (click)="submitWizard()" [disabled]="!allStepsValid()">Submit</button>
-        }
-      </div>
-    </div>
-  `,
-})
-class WizardComponent {
-  wizardTree = wizardTree;
-  currentStep = computed(() => this.wizardTree.$.currentStep());
-
-  steps = [
-    { number: 1, title: 'Personal' },
-    { number: 2, title: 'Address' },
-    { number: 3, title: 'Preferences' },
-  ];
-
-  // Create forms for each step
-  personalForm = this.wizardTree.createForm('steps.personal', {
-    firstName: ['', Validators.required],
-    lastName: ['', Validators.required],
-    email: ['', [Validators.required, Validators.email]],
-    phone: ['', Validators.required],
-  });
-
-  addressForm = this.wizardTree.createForm('steps.address', {
-    street: ['', Validators.required],
-    city: ['', Validators.required],
-    state: ['', Validators.required],
-    zipCode: ['', [Validators.required, Validators.pattern(/^\d{5}$/)]],
-  });
-
-  preferencesForm = this.wizardTree.createForm('steps.preferences');
-
-  // Track form validity
-  constructor() {
-    // Update validation state when forms change
-    effect(() => {
-      this.wizardTree.$.validation.personalValid.set(this.personalForm.valid);
-      this.wizardTree.$.validation.addressValid.set(this.addressForm.valid);
-      this.wizardTree.$.validation.preferencesValid.set(this.preferencesForm.valid);
-    });
-  }
-
-  nextStep() {
-    if (this.canProceed()) {
-      this.wizardTree.$.currentStep.update((step) => step + 1);
-    }
-  }
-
-  previousStep() {
-    this.wizardTree.$.currentStep.update((step) => Math.max(1, step - 1));
-  }
-
-  canProceed(): boolean {
-    const step = this.currentStep();
-    const validation = this.wizardTree.$.validation();
-
-    switch (step) {
-      case 1:
-        return validation.personalValid;
-      case 2:
-        return validation.addressValid;
-      case 3:
-        return validation.preferencesValid;
-      default:
-        return false;
-    }
-  }
-
-  isStepCompleted(stepNumber: number): boolean {
-    const validation = this.wizardTree.$.validation();
-    switch (stepNumber) {
-      case 1:
-        return validation.personalValid;
-      case 2:
-        return validation.addressValid;
-      case 3:
-        return validation.preferencesValid;
-      default:
-        return false;
-    }
-  }
-
-  allStepsValid(): boolean {
-    const validation = this.wizardTree.$.validation();
-    return validation.personalValid && validation.addressValid && validation.preferencesValid;
-  }
-
-  submitWizard() {
-    if (this.allStepsValid()) {
-      const wizardData = this.wizardTree.$.steps();
-      console.log('Wizard completed:', wizardData);
-      // Submit to API
-    }
-  }
-}
-```
-
-### Dynamic Survey Builder
-
-```typescript
-interface Question {
-  id: string;
-  type: 'text' | 'number' | 'select' | 'radio' | 'checkbox';
-  label: string;
-  required: boolean;
-  options?: string[];
-  validation?: {
-    min?: number;
-    max?: number;
-    pattern?: string;
-  };
-}
+];
 
-interface Survey {
-  id: string;
-  title: string;
-  questions: Question[];
-}
-
-interface SurveyResponse {
-  surveyId: string;
-  responses: Record<string, any>;
-  submittedAt?: Date;
-}
-
-const surveyTree = signalTree({
-  survey: null as Survey | null,
-  responses: {} as Record<string, any>,
-  currentQuestion: 0,
-  isSubmitting: false,
-  submitError: null as string | null,
+const wizard = createWizardForm(steps, initialValues, {
+  conditionals: [
+    {
+      when: ({ marketingOptIn }) => marketingOptIn,
+      fields: ['preferences.frequency'],
+    },
+  ],
 });
 
-@Component({
-  template: `
-    <div class="survey" *ngIf="survey()">
-      <h1>{{ survey()!.title }}</h1>
-
-      <div class="progress">
-        <div class="progress-bar" [style.width.%]="progressPercent()"></div>
-      </div>
-
-      <form [formGroup]="surveyForm" (ngSubmit)="submitSurvey()">
-        @for (question of survey()!.questions; track question.id; let i = $index) {
-        <div class="question" [class.active]="currentQuestion() === i">
-          <h3>{{ question.label }}</h3>
-
-          @switch (question.type) { @case ('text') {
-          <input [formControlName]="question.id" type="text" [placeholder]="question.label" />
-          } @case ('number') {
-          <input [formControlName]="question.id" type="number" [min]="question.validation?.min" [max]="question.validation?.max" />
-          } @case ('select') {
-          <select [formControlName]="question.id">
-            <option value="">Select an option</option>
-            @for (option of question.options; track option) {
-            <option [value]="option">{{ option }}</option>
-            }
-          </select>
-          } @case ('radio') { @for (option of question.options; track option) {
-          <label>
-            <input [formControlName]="question.id" type="radio" [value]="option" />
-            {{ option }}
-          </label>
-          } } @case ('checkbox') { @for (option of question.options; track option) {
-          <label>
-            <input type="checkbox" [value]="option" (change)="onCheckboxChange(question.id, option, $event)" />
-            {{ option }}
-          </label>
-          } } }
-
-          <div class="validation-error" *ngIf="getQuestionError(question.id)">
-            {{ getQuestionError(question.id) }}
-          </div>
-        </div>
-        }
-
-        <div class="survey-navigation">
-          <button type="button" (click)="previousQuestion()" [disabled]="currentQuestion() === 0">Previous</button>
-
-          @if (currentQuestion() < survey()!.questions.length - 1) {
-          <button type="button" (click)="nextQuestion()" [disabled]="!isCurrentQuestionValid()">Next</button>
-          } @else {
-          <button type="submit" [disabled]="surveyForm.invalid || isSubmitting()">
-            {{ isSubmitting() ? 'Submitting...' : 'Submit Survey' }}
-          </button>
-          }
-        </div>
-      </form>
-
-      <div class="error" *ngIf="submitError()">
-        {{ submitError() }}
-      </div>
-    </div>
-  `,
-})
-class SurveyComponent implements OnInit {
-  surveyTree = surveyTree;
-  surveyForm!: FormGroup;
-
-  survey = computed(() => this.surveyTree.$.survey());
-  currentQuestion = computed(() => this.surveyTree.$.currentQuestion());
-  isSubmitting = computed(() => this.surveyTree.$.isSubmitting());
-  submitError = computed(() => this.surveyTree.$.submitError());
-
-  progressPercent = computed(() => {
-    const survey = this.survey();
-    const current = this.currentQuestion();
-    if (!survey) return 0;
-    return ((current + 1) / survey.questions.length) * 100;
-  });
-
-  ngOnInit() {
-    // Load survey and create form
-    this.loadSurvey().then((survey) => {
-      this.surveyTree.$.survey.set(survey);
-      this.createSurveyForm(survey);
-    });
-  }
-
-  private createSurveyForm(survey: Survey) {
-    const formConfig: Record<string, any> = {};
-
-    survey.questions.forEach((question) => {
-      const validators = [];
-
-      if (question.required) {
-        validators.push(Validators.required);
-      }
-
-      if (question.validation) {
-        if (question.validation.min !== undefined) {
-          validators.push(Validators.min(question.validation.min));
-        }
-        if (question.validation.max !== undefined) {
-          validators.push(Validators.max(question.validation.max));
-        }
-        if (question.validation.pattern) {
-          validators.push(Validators.pattern(question.validation.pattern));
-        }
-      }
-
-      const defaultValue = question.type === 'checkbox' ? [] : '';
-      formConfig[question.id] = [defaultValue, validators];
-    });
-
-    this.surveyForm = this.surveyTree.createForm('responses', formConfig);
-  }
-
-  nextQuestion() {
-    if (this.isCurrentQuestionValid()) {
-      this.surveyTree.$.currentQuestion.update((q) => q + 1);
-    }
-  }
-
-  previousQuestion() {
-    this.surveyTree.$.currentQuestion.update((q) => Math.max(0, q - 1));
-  }
-
-  isCurrentQuestionValid(): boolean {
-    const survey = this.survey();
-    const current = this.currentQuestion();
-    if (!survey) return false;
-
-    const question = survey.questions[current];
-    const control = this.surveyForm.get(question.id);
-    return control ? control.valid : false;
-  }
-
-  getQuestionError(questionId: string): string | null {
-    const control = this.surveyForm.get(questionId);
-    if (control?.errors && control.touched) {
-      if (control.errors['required']) return 'This question is required';
-      if (control.errors['min']) return `Minimum value is ${control.errors['min'].min}`;
-      if (control.errors['max']) return `Maximum value is ${control.errors['max'].max}`;
-      if (control.errors['pattern']) return 'Invalid format';
-    }
-    return null;
-  }
+await wizard.nextStep();
+wizard.previousStep();
+wizard.currentStep(); // readonly signal
+wizard.isFieldVisible('preferences.frequency')();
+```
 
-  onCheckboxChange(questionId: string, option: string, event: any) {
-    const control = this.surveyForm.get(questionId);
-    const currentValue = control?.value || [];
+Wizard forms reuse the same `form` instance and `FormTree` helpers, adding `currentStep`, `nextStep`, `previousStep`, `goToStep`, and `isFieldVisible` helpers for UI state.
 
-    if (event.target.checked) {
-      control?.setValue([...currentValue, option]);
-    } else {
-      control?.setValue(currentValue.filter((v: string) => v !== option));
-    }
-  }
+## Form history snapshots
 
-  async submitSurvey() {
-    if (this.surveyForm.valid) {
-      this.surveyTree.$.isSubmitting.set(true);
-      this.surveyTree.$.submitError.set(null);
-
-      try {
-        const response: SurveyResponse = {
-          surveyId: this.survey()!.id,
-          responses: this.surveyTree.$.responses(),
-          submittedAt: new Date(),
-        };
-
-        await this.submitSurveyResponse(response);
-        console.log('Survey submitted successfully');
-      } catch (error) {
-        this.surveyTree.$.submitError.set('Failed to submit survey. Please try again.');
-      } finally {
-        this.surveyTree.$.isSubmitting.set(false);
-      }
-    }
-  }
+```typescript
+import { withFormHistory } from '@signaltree/ng-forms';
 
-  private async loadSurvey(): Promise<Survey> {
-    // Load survey from API
-    return {
-      id: '1',
-      title: 'Customer Satisfaction Survey',
-      questions: [
-        {
-          id: 'q1',
-          type: 'radio',
-          label: 'How satisfied are you with our service?',
-          required: true,
-          options: ['Very Satisfied', 'Satisfied', 'Neutral', 'Dissatisfied', 'Very Dissatisfied'],
-        },
-        {
-          id: 'q2',
-          type: 'text',
-          label: 'What can we improve?',
-          required: false,
-        },
-        {
-          id: 'q3',
-          type: 'number',
-          label: 'Rate us from 1-10',
-          required: true,
-          validation: { min: 1, max: 10 },
-        },
-      ],
-    };
-  }
+const form = withFormHistory(createFormTree(initialValues), { capacity: 20 });
 
-  private async submitSurveyResponse(response: SurveyResponse): Promise<void> {
-    // Submit to API
-    await new Promise((resolve) => setTimeout(resolve, 1000));
-  }
-}
+form.setValue('profile.name', 'Ada');
+form.undo();
+form.redo();
+form.history(); // signal with { past, present, future }
+form.clearHistory();
 ```
 
-## When to use ng-forms
+History tracking works at the FormGroup level so it plays nicely with external updates and preserved snapshots.
 
-Perfect for:
+## Helpers and utilities
 
-- Angular applications with complex forms
-- Real-time form validation and feedback
-- Multi-step forms and wizards
-- Dynamic form generation
-- Forms with cross-field validation
-- Applications requiring form state persistence
+- `validators` / `asyncValidators`: Lightweight factories for common rules (required, email, minLength, unique, etc.)
+- `createVirtualFormArray`: Virtualize huge `FormArray`s by only instantiating the visible window
+- `toObservable(signal)`: Convert any Angular signal to an RxJS `Observable`
+- `SIGNAL_FORM_DIRECTIVES`: Re-export of `SignalValueDirective` for template-driven helpers
+- `FormValidationError`: Error thrown from `submit` when validation fails, containing sync & async errors
 
-## Composition with other packages
+## Template-driven bridge
 
-```typescript
-import { createFormTree } from '@signaltree/ng-forms';
-import { withDevTools } from '@signaltree/devtools';
-
-// Compose DevTools with your app tree separately if desired
-const form = createFormTree(state);
-// In development, you can enhance your app's SignalTree with DevTools
-// const appTree = signalTree(appState).with(withDevTools());
+```html
+<input type="text" [(ngModel)]="userName" [signalTreeSignalValue]="formTree.$.user.name" (signalTreeSignalValueChange)="audit($event)" />
 ```
 
-## Performance benefits
+Use `SignalValueDirective` to keep standalone signals and `ngModel` fields aligned in legacy sections while new pages migrate to forms-first APIs.
+
+## When to reach for ng-forms
 
-- **Automatic synchronization** between forms and state
-- **Debounced updates** prevent excessive state changes
-- **Efficient validation** with minimal re-computation
-- **Tree-shakeable** - only includes what you use
-- **Memory efficient** form state management
+- Complex Angular forms that need to remain in sync with SignalTree application state
+- Workflows that require persistence, auto-save, or offline drafts
+- Multi-step wizards or surveys with dynamic branching
+- Applications that benefit from first-class signal APIs around Angular forms
 
 ## Links
 
 - [SignalTree Documentation](https://signaltree.io)
 - [Core Package](https://www.npmjs.com/package/@signaltree/core)
 - [GitHub Repository](https://github.com/JBorgia/signaltree)
-- [ng-forms Examples](https://signaltree.io/examples/ng-forms)
+- [Demo Application](https://signaltree.io/examples)
 
 ## License
 
-MIT License with AI Training Restriction - see the [LICENSE](../../LICENSE) file for details.
+MIT License with AI Training Restriction — see the [LICENSE](../../LICENSE) file for details.
 
 ---
 
-**Seamless Angular Forms** with SignalTree power! 🅰️
+**Seamless signal-first Angular forms.**