mobx-formkit 1.2.0 → 1.3.0

package/src/Base.ts

@@ -30,6 +30,7 @@ import {
   isArrayOfObjects,
   getObservableMapValues,
   maxKey,
+  cloneValues,
   $try,
   isEvent,
   hasIntKeys,
@@ -80,6 +81,12 @@ export default abstract class Base<
   $hooks: any = {};
   $handlers: any = {};
 
+  /**
+    Values captured by the last `commit()`.
+    Not observable: it is a snapshot, not a UI state.
+  */
+  $committed: any = undefined;
+
   constructor() {
     makeObservable(this, {
       $submitted: observable,
@@ -111,6 +118,8 @@ export default abstract class Base<
       add: action,
       del: action,
       move: action,
+      commit: action,
+      restore: action,
     });
 
     // Any reorder of the fields (also when `fields.move()` is called
@@ -1125,6 +1134,67 @@ export default abstract class Base<
     });
   }
 
+  /**
+    Commit & Restore
+   */
+
+  /**
+    Captures the current values as the new restore reference.
+
+    It does not validate, it does not send anything and it does not change
+    the current values.
+   */
+  commit(): void {
+    this.$committed = cloneValues(this.values());
+  }
+
+  /**
+    Restores the values captured by the last `commit()`.
+
+    Before the first commit the reference is the reset target of the fields
+    (the `default` when it differs from the `initial`, the `initial`
+    otherwise), so `restore()` is useful even without a commit.
+   */
+  restore(): void | Promise<any> {
+    if (this.$committed === void 0) return;
+    this.update(cloneValues(this.$committed));
+    if (this.state.options.get(OptionsEnum.validateOnRestore, this)) {
+      return this.validate({
+        showErrors: this.state.options.get(
+          OptionsEnum.showErrorsOnRestore,
+          this,
+        ),
+      });
+    }
+  }
+
+  /**
+    The values captured by the last `commit()` (read only)
+   */
+  committed(): any {
+    return this.$committed === void 0 ? void 0 : cloneValues(this.$committed);
+  }
+
+  /**
+    Initializes the restore reference with the reset target of the fields
+    (the `default` when it differs from the `initial`, the `initial`
+    otherwise)
+   */
+  initCommittedSnapshot(): void {
+    this.$committed = cloneValues(this.resetTargetValues());
+  }
+
+  /**
+    The values the fields would have after a `reset()`
+   */
+  resetTargetValues(): any {
+    const $values: any = {};
+    getObservableMapValues(this.fields).forEach((field: any) => {
+      $values[field.key] = field.resetTargetValue();
+    });
+    return $values;
+  }
+
   /**
     Del Field
    */

package/src/Field.ts

@@ -301,6 +301,9 @@ export default class Field<T = any> extends Base<Record<string, any>> implements
     // this.checkValidationPlugins();
     this.initNestedFields(data, update);
 
+    // the restore reference starts from the reset target of the fields
+    this.initCommittedSnapshot();
+
     this.incremental = this.hasIncrementalKeys;
 
     this.debouncedValidation = debounce(
@@ -508,6 +511,22 @@ export default class Field<T = any> extends Base<Record<string, any>> implements
     return !isEqual(this.initial, value) || this.deleted;
   }
 
+  /**
+    The value the field would have after a `reset()`: the `default` when it
+    differs from the `initial`, the `initial` otherwise. For a field with
+    nested fields it is the tree of the nested values.
+   */
+  resetTargetValue(): any {
+    if (this.hasNestedFields) {
+      const $nested: any = {};
+      getObservableMapValues(this.fields).forEach((field: any) => {
+        $nested[field.key] = field.resetTargetValue();
+      });
+      return this.hasIncrementalKeys ? Object.values($nested) : $nested;
+    }
+    return this.$default !== this.$initial ? this.$default : this.$initial;
+  }
+
   get isPristine(): boolean {
     const value = this.changed ? this.value : this.initial;
     return isEqual(this.initial, value) && !this.deleted;

package/src/Form.ts

@@ -108,6 +108,9 @@ export default class Form<F extends Record<string, any> = Record<string, any>> e
 
     this.initFields(initial.setup);
 
+    // the restore reference starts from the reset target of the fields
+    this.initCommittedSnapshot();
+
     this.debouncedValidation = debounce(
       this.validate,
       this.state.options.get(OptionsEnum.validationDebounceWait),

package/src/Options.ts

@@ -26,6 +26,7 @@ export default class Options implements OptionsInterface {
     showErrorsOnChange: true,
     showErrorsOnClear: false,
     showErrorsOnReset: true,
+    showErrorsOnRestore: false,
     validateOnInit: true,
     validateOnSubmit: true,
     validateOnBlur: true,
@@ -34,6 +35,7 @@ export default class Options implements OptionsInterface {
     validateOnChangeAfterSubmit: false,
     validateOnClear: false,
     validateOnReset: false,
+    validateOnRestore: false,
     validateDisabledFields: false,
     validateDeletedFields: false,
     validatePristineFields: true,

package/src/models/BaseInterface.ts

@@ -40,6 +40,9 @@ export interface BaseInterface<F extends Record<string, any> = Record<string, an
   onAdd(args: any): any;
   onDel(args: any): any;
   firstError(): string | null;
+  commit(): void;
+  restore(): void | Promise<any>;
+  committed(): any;
 }
 
 export default BaseInterface;

package/src/models/OptionsModel.ts

@@ -10,6 +10,7 @@ export enum OptionsEnum {
   showErrorsOnChange = 'showErrorsOnChange',
   showErrorsOnClear = 'showErrorsOnClear',
   showErrorsOnReset = 'showErrorsOnReset',
+  showErrorsOnRestore = 'showErrorsOnRestore',
   validateOnInit = 'validateOnInit',
   validateOnSubmit = 'validateOnSubmit',
   validateOnBlur = 'validateOnBlur',
@@ -22,6 +23,7 @@ export enum OptionsEnum {
   validateTrimmedValue = 'validateTrimmedValue',
   validateOnClear = 'validateOnClear',
   validateOnReset = 'validateOnReset',
+  validateOnRestore = 'validateOnRestore',
   strictSet = 'strictSet',
   strictUpdate = 'strictUpdate',
   strictDelete = 'strictDelete',
@@ -58,6 +60,7 @@ export interface OptionsModel {
   [OptionsEnum.showErrorsOnChange]?: boolean;
   [OptionsEnum.showErrorsOnClear]?: boolean;
   [OptionsEnum.showErrorsOnReset]?: boolean;
+  [OptionsEnum.showErrorsOnRestore]?: boolean;
   [OptionsEnum.validateOnInit]?: boolean;
   [OptionsEnum.validateOnSubmit]?: boolean;
   [OptionsEnum.validateOnBlur]?: boolean;
@@ -66,6 +69,7 @@ export interface OptionsModel {
   [OptionsEnum.validateOnChangeAfterSubmit]?: boolean;
   [OptionsEnum.validateOnClear]?: boolean;
   [OptionsEnum.validateOnReset]?: boolean;
+  [OptionsEnum.validateOnRestore]?: boolean;
   [OptionsEnum.validateDisabledFields]?: boolean;
   [OptionsEnum.validateDeletedFields]?: boolean;
   [OptionsEnum.validatePristineFields]?: boolean;

package/src/utils.ts

@@ -1,4 +1,4 @@
-import { has, isEmpty, isPlainObject } from "lodash";
+import { each, has, isEmpty, isPlainObject } from "lodash";
 import { values as mobxValues, keys as mobxKeys } from "mobx";
 import { FieldInterface } from "./models/FieldInterface";
 import { AllowedFieldPropsTypes, FieldPropsEnum, FieldPropsOccurrence } from "./models/FieldProps";
@@ -165,6 +165,25 @@ const maxKey = (fields: any): number => {
   return maxVal === void 0 ? 0 : maxVal + 1;
 };
 
+/**
+  Clones a value tree keeping it independent from the original one.
+
+  Plain objects, arrays and dates are cloned, any other object (File, Blob,
+  class instances, ...) is kept by reference because it cannot be cloned
+  safely.
+*/
+const cloneValues = (value: any): any => {
+  if (value === null || typeof value !== "object") return value;
+  if (Array.isArray(value)) return value.map((item: any) => cloneValues(item));
+  if (value instanceof Date) return new Date(value.getTime());
+  if (!isPlainObject(value)) return value;
+  const result: any = {};
+  each(Object.keys(value), (key: string) => {
+    result[key] = cloneValues(value[key]);
+  });
+  return result;
+};
+
 let _idCounter = 0;
 const _localUniqueId = (prefix: string): string => `${prefix}${++_idCounter}`;
 
@@ -207,6 +226,7 @@ export {
   parseIntKeys,
   hasIntKeys,
   maxKey,
+  cloneValues,
   uniqueId,
   isEvent,
   hasFiles,

package/umd/MobxFormkit.umd.js

@@ -619,6 +619,28 @@
         const maxVal = keys.length ? Math.max(...keys) : undefined;
         return maxVal === void 0 ? 0 : maxVal + 1;
     };
+    /**
+      Clones a value tree keeping it independent from the original one.
+
+      Plain objects, arrays and dates are cloned, any other object (File, Blob,
+      class instances, ...) is kept by reference because it cannot be cloned
+      safely.
+    */
+    const cloneValues = (value) => {
+        if (value === null || typeof value !== "object")
+            return value;
+        if (Array.isArray(value))
+            return value.map((item) => cloneValues(item));
+        if (value instanceof Date)
+            return new Date(value.getTime());
+        if (!lodash.isPlainObject(value))
+            return value;
+        const result = {};
+        lodash.each(Object.keys(value), (key) => {
+            result[key] = cloneValues(value[key]);
+        });
+        return result;
+    };
     let _idCounter = 0;
     const _localUniqueId = (prefix) => `${prefix}${++_idCounter}`;
     const uniqueId = (field) => _localUniqueId([field.path.replace(/\./g, "-"), "--"].join(""));
@@ -879,6 +901,7 @@
         OptionsEnum["showErrorsOnChange"] = "showErrorsOnChange";
         OptionsEnum["showErrorsOnClear"] = "showErrorsOnClear";
         OptionsEnum["showErrorsOnReset"] = "showErrorsOnReset";
+        OptionsEnum["showErrorsOnRestore"] = "showErrorsOnRestore";
         OptionsEnum["validateOnInit"] = "validateOnInit";
         OptionsEnum["validateOnSubmit"] = "validateOnSubmit";
         OptionsEnum["validateOnBlur"] = "validateOnBlur";
@@ -891,6 +914,7 @@
         OptionsEnum["validateTrimmedValue"] = "validateTrimmedValue";
         OptionsEnum["validateOnClear"] = "validateOnClear";
         OptionsEnum["validateOnReset"] = "validateOnReset";
+        OptionsEnum["validateOnRestore"] = "validateOnRestore";
         OptionsEnum["strictSet"] = "strictSet";
         OptionsEnum["strictUpdate"] = "strictUpdate";
         OptionsEnum["strictDelete"] = "strictDelete";
@@ -936,6 +960,11 @@
         $changed = 0;
         $hooks = {};
         $handlers = {};
+        /**
+          Values captured by the last `commit()`.
+          Not observable: it is a snapshot, not a UI state.
+        */
+        $committed = undefined;
         constructor() {
             makeObservable(this, {
                 $submitted: mobx.observable,
@@ -967,6 +996,8 @@
                 add: mobx.action,
                 del: mobx.action,
                 move: mobx.action,
+                commit: mobx.action,
+                restore: mobx.action,
             });
             // Any reorder of the fields (also when `fields.move()` is called
             // directly) flags the field and the form as changed. (#657)
@@ -1667,6 +1698,59 @@
                 }
             });
         }
+        /**
+          Commit & Restore
+         */
+        /**
+          Captures the current values as the new restore reference.
+      
+          It does not validate, it does not send anything and it does not change
+          the current values.
+         */
+        commit() {
+            this.$committed = cloneValues(this.values());
+        }
+        /**
+          Restores the values captured by the last `commit()`.
+      
+          Before the first commit the reference is the reset target of the fields
+          (the `default` when it differs from the `initial`, the `initial`
+          otherwise), so `restore()` is useful even without a commit.
+         */
+        restore() {
+            if (this.$committed === void 0)
+                return;
+            this.update(cloneValues(this.$committed));
+            if (this.state.options.get(OptionsEnum.validateOnRestore, this)) {
+                return this.validate({
+                    showErrors: this.state.options.get(OptionsEnum.showErrorsOnRestore, this),
+                });
+            }
+        }
+        /**
+          The values captured by the last `commit()` (read only)
+         */
+        committed() {
+            return this.$committed === void 0 ? void 0 : cloneValues(this.$committed);
+        }
+        /**
+          Initializes the restore reference with the reset target of the fields
+          (the `default` when it differs from the `initial`, the `initial`
+          otherwise)
+         */
+        initCommittedSnapshot() {
+            this.$committed = cloneValues(this.resetTargetValues());
+        }
+        /**
+          The values the fields would have after a `reset()`
+         */
+        resetTargetValues() {
+            const $values = {};
+            getObservableMapValues(this.fields).forEach((field) => {
+                $values[field.key] = field.resetTargetValue();
+            });
+            return $values;
+        }
         /**
           Del Field
          */
@@ -2068,6 +2152,7 @@
             showErrorsOnChange: true,
             showErrorsOnClear: false,
             showErrorsOnReset: true,
+            showErrorsOnRestore: false,
             validateOnInit: true,
             validateOnSubmit: true,
             validateOnBlur: true,
@@ -2076,6 +2161,7 @@
             validateOnChangeAfterSubmit: false,
             validateOnClear: false,
             validateOnReset: false,
+            validateOnRestore: false,
             validateDisabledFields: false,
             validateDeletedFields: false,
             validatePristineFields: true,
@@ -2529,6 +2615,8 @@
             this.setupField(key, path, struct, data, props, update);
             // this.checkValidationPlugins();
             this.initNestedFields(data, update);
+            // the restore reference starts from the reset target of the fields
+            this.initCommittedSnapshot();
             this.incremental = this.hasIncrementalKeys;
             this.debouncedValidation = lodash.debounce(this.validate, this.state.options.get(OptionsEnum.validationDebounceWait, this), this.state.options.get(OptionsEnum.validationDebounceOptions, this));
             this.observeValidationOnBlur();
@@ -2677,6 +2765,21 @@
             // a soft deleted field differs from its initial state
             return !lodash.isEqual(this.initial, value) || this.deleted;
         }
+        /**
+          The value the field would have after a `reset()`: the `default` when it
+          differs from the `initial`, the `initial` otherwise. For a field with
+          nested fields it is the tree of the nested values.
+         */
+        resetTargetValue() {
+            if (this.hasNestedFields) {
+                const $nested = {};
+                getObservableMapValues(this.fields).forEach((field) => {
+                    $nested[field.key] = field.resetTargetValue();
+                });
+                return this.hasIncrementalKeys ? Object.values($nested) : $nested;
+            }
+            return this.$default !== this.$initial ? this.$default : this.$initial;
+        }
         get isPristine() {
             const value = this.changed ? this.value : this.initial;
             return lodash.isEqual(this.initial, value) && !this.deleted;
@@ -3139,6 +3242,8 @@
                 plugins: initial.plugins,
             });
             this.initFields(initial.setup);
+            // the restore reference starts from the reset target of the fields
+            this.initCommittedSnapshot();
             this.debouncedValidation = lodash.debounce(this.validate, this.state.options.get(OptionsEnum.validationDebounceWait), this.state.options.get(OptionsEnum.validationDebounceOptions));
             // execute validation on form initialization
             this.state.options.get(OptionsEnum.validateOnInit) &&