feat(lib): add dirty functionality

Author: NetanelBasal

README.md

@@ -19,7 +19,8 @@
 ✅ Allows Typed Forms!<br>
 ✅ Auto persists the form's state upon user navigation.<br>
 ✅ Provides an API to reactively querying any form, from anywhere. <br>
-✅ Persist the form's state to local storage.
+✅ Persist the form's state to local storage.<br>
+✅ Built-in dirty functionality.
 
 <hr />
 
@@ -282,7 +283,7 @@ export class HomeComponent {
 `NgFormsManager` can take a generic type where you can define the forms shape. For example:
 
 ```ts
-export interface AppForms = {
+interface AppForms = {
   onboarding: {
     name: string;
     age: number;
@@ -305,6 +306,51 @@ export class OnboardingComponent {
 }
 ```
 
+Note that you can split the types across files using a definition file:
+
+```ts
+// login-form.d.ts
+interface AppForms {
+  login: {
+    email: string;
+    password: string
+  }
+}
+
+// onboarding.d.ts
+interface AppForms {
+  onboarding: {
+    ...
+  }
+}
+```
+
+## Using the Dirty Functionality
+
+The library provides built-in support for the common "Is the form dirty?" question. Dirty means that the current control's
+value is different from the initial value. It can be useful when we need to toggle the visibility of a "save" button or displaying a dialog when the user leaves the page.
+
+To start using it, you should set the `withInitialValue` option:
+
+```ts
+@Component({
+  template: `
+    <button *ngIf="isDirty$ | async">Save</button>
+  `,
+})
+export class SettingsComponent {
+  isDirty$ = this.formsManager.initialValueChanged(name);
+
+  constructor(private formsManager: NgFormsManager<AppForms>) {}
+
+  ngOnInit() {
+    this.formsManager.upsert(name, control, {
+      withInitialValue: true,
+    });
+  }
+}
+```
+
 ## NgFormsManager Config
 
 You can override the default config by passing the `NG_FORMS_MANAGER_CONFIG` provider:

projects/ngneat/forms-manager/src/lib/forms-manager.ts

@@ -1,10 +1,10 @@
 import { Inject, Injectable, Optional } from '@angular/core';
-import { AbstractControl, Form } from '@angular/forms';
-import { coerceArray, filterControlKeys, filterNil, isBrowser, mergeDeep } from './utils';
+import { AbstractControl } from '@angular/forms';
+import { coerceArray, filterControlKeys, filterNil, isBrowser, isObject, mergeDeep } from './utils';
 import { merge, Observable, Subject, Subscription } from 'rxjs';
-import { debounceTime, distinctUntilChanged, filter, map, tap } from 'rxjs/operators';
+import { debounceTime, distinctUntilChanged, filter, map } from 'rxjs/operators';
 import { FormsStore } from './forms-manager.store';
-import { Control, ControlFactory, FormKeys, HashMap } from './types';
+import { Control, ControlFactory, FormKeys, HashMap, UpsertConfig } from './types';
 import { Config, NG_FORMS_MANAGER_CONFIG, NgFormsManagerConfig } from './config';
 import { isEqual } from './isEqual';
 import { deleteControl, findControl, handleFormArray, toStore } from './builders';
@@ -14,6 +14,7 @@ export class NgFormsManager<FormsState = any> {
   private readonly store: FormsStore<FormsState>;
   private valueChanges$$: Map<keyof FormsState, Subscription> = new Map();
   private instances$$: Map<keyof FormsState, AbstractControl> = new Map();
+  private initialValues$$: Map<keyof FormsState, any> = new Map();
   private destroy$$ = new Subject();
 
   constructor(@Optional() @Inject(NG_FORMS_MANAGER_CONFIG) private config: NgFormsManagerConfig) {
@@ -33,6 +34,19 @@ export class NgFormsManager<FormsState = any> {
     return this.controlChanges(name, path).pipe(map(control => control.valid));
   }
 
+  /**
+   *
+   * Whether the control is valid
+   *
+   * @example
+   *
+   * manager.isValid(name);
+   *
+   */
+  isValid(name: keyof FormsState) {
+    return this.hasControl(name) && this.getControl(name).valid;
+  }
+
   /**
    *
    * @example
@@ -116,6 +130,25 @@ export class NgFormsManager<FormsState = any> {
     );
   }
 
+  /**
+   *
+   * Whether the initial control value is deep equal to current value
+   *
+   * @example
+   *
+   * const dirty$ = manager.initialValueChanged('settings');
+   *
+   */
+  initialValueChanged(name: keyof FormsState): Observable<boolean> {
+    if (this.initialValues$$.has(name) === false) {
+      console.error(`You should set the withInitialValue option to the ${name} control`);
+    }
+
+    return this.valueChanges(name).pipe(
+      map(current => isEqual(current, this.initialValues$$.get(name)) === false)
+    );
+  }
+
   /**
    *
    * @example
@@ -214,6 +247,19 @@ export class NgFormsManager<FormsState = any> {
     }
   }
 
+  /**
+   *
+   * Sets the initial value for a control
+   *
+   * @example
+   *
+   * manager.setInitialValue('login', value);
+   *
+   */
+  setInitialValue(name: keyof FormsState, value: any) {
+    this.initialValues$$.set(name, value);
+  }
+
   /**
    *
    * @example
@@ -254,6 +300,7 @@ export class NgFormsManager<FormsState = any> {
   clear(name?: FormKeys<FormsState>) {
     name ? this.deleteControl(name) : this.store.set({} as FormsState);
     this.removeFromStorage();
+    this.removeInitialValue(name);
   }
 
   /**
@@ -283,16 +330,12 @@ export class NgFormsManager<FormsState = any> {
    * manager.upsert('login', this.login, { arrControlFactory: value => new FormControl('') });
    *
    */
-  upsert(
-    name: keyof FormsState,
-    control: AbstractControl,
-    config: {
-      persistState?: boolean;
-      debounceTime?: number;
-      arrControlFactory?: ControlFactory | HashMap<ControlFactory>;
-    } = {}
-  ) {
-    const mergedConfig = this.config.merge(config) as Config & { arrControlFactory; persistState };
+  upsert(name: keyof FormsState, control: AbstractControl, config: UpsertConfig = {}) {
+    const mergedConfig: Config & UpsertConfig = this.config.merge(config);
+
+    if (mergedConfig.withInitialValue && this.initialValues$$.has(name) === false) {
+      this.setInitialValue(name, control.value);
+    }
 
     if (isBrowser() && config.persistState && this.hasControl(name) === false) {
       const storageValue = this.getFromStorage(mergedConfig.storage.key);
@@ -374,4 +417,8 @@ export class NgFormsManager<FormsState = any> {
 
     return value;
   }
+
+  private removeInitialValue(name: FormKeys<FormsState>) {
+    coerceArray(name).forEach(name => this.initialValues$$.delete(name));
+  }
 }

projects/ngneat/forms-manager/src/lib/test-types.ts

@@ -18,8 +18,8 @@ const formTwo = new FormGroup({
   age: new FormControl(),
 });
 
-manager.upsert('formOne', formOne);
-manager.upsert('formTwo', formTwo);
+manager.upsert({ name: 'formOne', control: formOne });
+manager.upsert({ name: 'formTwo', control: formTwo });
 
 manager.validityChanges('formOne').subscribe(isValid => {
   // infer boolean

projects/ngneat/forms-manager/src/lib/types.ts

@@ -12,3 +12,10 @@ export interface HashMap<T = any> {
 }
 
 export type FormKeys<FormsState> = keyof FormsState | (keyof FormsState)[];
+
+export interface UpsertConfig {
+  persistState?: boolean;
+  debounceTime?: number;
+  arrControlFactory?: ControlFactory | HashMap<ControlFactory>;
+  withInitialValue?: boolean;
+}

src/app/app-routing.module.ts

@@ -1,7 +1,9 @@
 import { NgModule } from '@angular/core';
-import { Routes, RouterModule } from '@angular/router';
-import { FormsComponent } from './forms/forms.component';
+import { RouterModule, Routes } from '@angular/router';
 import { HomeComponent } from './home/home.component';
+import { DemoComponent } from './demo/demo.component';
+import { StepOneComponent } from './step-one/step-one.component';
+import { StepTwoComponent } from './step-two/step-two.component';
 
 const routes: Routes = [
   {
@@ -10,8 +12,23 @@ const routes: Routes = [
     pathMatch: 'full',
   },
   {
-    path: 'forms',
-    component: FormsComponent,
+    path: 'demo',
+    component: DemoComponent,
+    children: [
+      {
+        path: '',
+        pathMatch: 'full',
+        redirectTo: 'one',
+      },
+      {
+        path: 'one',
+        component: StepOneComponent,
+      },
+      {
+        path: 'two',
+        component: StepTwoComponent,
+      },
+    ],
   },
 ];
 

src/app/app.component.html

@@ -12,7 +12,7 @@
         >
       </li>
       <li class="nav-item">
-        <a class="nav-link" routerLinkActive="active" routerLink="forms">Forms</a>
+        <a class="nav-link" routerLinkActive="active" routerLink="demo">Demo</a>
       </li>
     </ul>
   </div>

src/app/app.module.ts

@@ -3,13 +3,14 @@ import { NgModule } from '@angular/core';
 
 import { AppRoutingModule } from './app-routing.module';
 import { AppComponent } from './app.component';
-import { FormsComponent } from './forms/forms.component';
 import { ReactiveFormsModule } from '@angular/forms';
-import { NG_FORMS_MANAGER_CONFIG, NgFormsManagerConfig } from '@ngneat/forms-manager';
 import { HomeComponent } from './home/home.component';
+import { DemoComponent } from './demo/demo.component';
+import { StepTwoComponent } from './step-two/step-two.component';
+import { StepOneComponent } from './step-one/step-one.component';
 
 @NgModule({
-  declarations: [AppComponent, FormsComponent, HomeComponent],
+  declarations: [AppComponent, HomeComponent, DemoComponent, StepTwoComponent, StepOneComponent],
   imports: [BrowserModule, AppRoutingModule, ReactiveFormsModule],
   providers: [
     // {

src/app/demo/demo.component.scss

@@ -0,0 +1,54 @@
+import { Component, OnInit } from '@angular/core';
+import { NgFormsManager } from '@ngneat/forms-manager';
+import { map, tap } from 'rxjs/operators';
+
+@Component({
+  template: `
+    <div class="container mt">
+      <div class="row">
+        <div class="col-3">
+          <div class="nav flex-column nav-pills">
+            <a
+              class="nav-link"
+              routerLink="one"
+              routerLinkActive="active"
+              [ngStyle]="stepOneInvalid$ | async"
+              >Step One</a
+            >
+            <a
+              class="nav-link"
+              routerLink="two"
+              [ngStyle]="stepTwoInvalid$ | async"
+              routerLinkActive="active"
+              >Step Two</a
+            >
+          </div>
+        </div>
+        <div class="col-9">
+          <div class="tab-content">
+            <router-outlet></router-outlet>
+          </div>
+          <button class="btn btn-info" (click)="save()">Save</button>
+        </div>
+      </div>
+    </div>
+  `,
+})
+export class DemoComponent implements OnInit {
+  stepOneInvalid$ = this.manager
+    .validityChanges('stepOne')
+    .pipe(map(valid => (valid ? null : { background: 'red' })));
+  stepTwoInvalid$ = this.manager
+    .validityChanges('stepTwo')
+    .pipe(map(valid => (valid ? null : { background: 'red' })));
+
+  constructor(private manager: NgFormsManager<AppForms>) {}
+
+  ngOnInit() {}
+
+  save() {
+    if (this.manager.isValid('stepOne') && this.manager.isValid('stepTwo')) {
+      console.log('valid');
+    }
+  }
+}