@homebound/form-state 2.13.0 → 2.14.0

package/README.md

@@ -1,3 +1,6 @@
+![npm](https://img.shields.io/npm/v/@homebound/form-state)
+[![CircleCI](https://circleci.com/gh/homebound-team/form-state.svg?style=svg)](https://circleci.com/gh/homebound-team/form-state)
+
 # form-state
 
 form-state is a headless form state management library, built on top of mobx.
@@ -7,14 +10,18 @@ It acts as a buffer between the canonical data/entity (i.e. the server-side data
 It also keeps track of low-level form UX details like:
 
 * Which form fields are dirty
-* Which forms fields are valid/invalid
-* Which forms fields are touched (i.e. don't show validation errors for untouched fields)
+* Which form fields are valid/invalid
+* Which form fields are touched (i.e. don't show validation errors for untouched fields)
 * Enabling/disabling buttons/form UX based on the overall form-wide state
 * Submitting the form should touch (validate) all fields
 * Auto-saving the form when appropriate (i.e. not on keystroke, but after blur/leaving the field)
-* Queue and debounce auto-saves if one is already in-flight
+* Queueing auto-saves if one is already in-flight
+  * Auto-saves in a table with per-row forms will serialize to avoid cross-child write conflicts on the backend
+* Not over-writing the user's WIP/actively-focused field when auto-saved data refreshes 
 * Building a wire payload that has only changed fields
-  * Handles children, i.e. a `author: { books: [...} }` will include only changed books if necessary
+  * `form.changedValue` will return the entity `id` + only changed fields to faciliate doing partial update APIs
+  * Supports collections of children, i.e. a `author: { books: [...} }` will include only changed books if necessary
+  * Child collections can be either exhausive (if any child changes, submit them all) or incremental (only include changed children), to match the backend endpoint's semantics
 
 # The Three Type/Shapes Mental Model
 

package/dist/config.d.ts

@@ -37,6 +37,8 @@ export declare type ValueFieldConfig<T, V> = {
     computed?: boolean;
     /** Marks a field as being initially read-only, i.e. `field.readOnly = true/false` can change this default. */
     readOnly?: boolean;
+    /** Marks an array field to be order agnostic when determining changed/dirty states */
+    strictOrder?: false;
 };
 /** Field configuration for list values, i.e. `U` is `Book` in a form with `books: Book[]`. */
 export declare type ListFieldConfig<T, U> = {

package/dist/fields/objectField.js

@@ -29,11 +29,12 @@ function newObjectState(config, parentState, parentListState, instance, key, may
         return proxy;
     }
     const fieldStates = Object.entries(config).map(([_key, _config]) => {
+        var _a;
         const key = _key;
         const config = _config;
         let field;
         if (config.type === "value") {
-            field = valueField_1.newValueFieldState(instance, getObjectState, key, config.rules || [], config.isIdKey || key === "id", config.isDeleteKey || false, config.isReadOnlyKey || false, config.computed || false, config.readOnly || false, maybeAutoSave);
+            field = valueField_1.newValueFieldState(instance, getObjectState, key, config.rules || [], config.isIdKey || key === "id", config.isDeleteKey || false, config.isReadOnlyKey || false, config.computed || false, config.readOnly || false, (_a = config.strictOrder) !== null && _a !== void 0 ? _a : true, maybeAutoSave);
         }
         else if (config.type === "list") {
             field = listField_1.newListFieldState(instance, getObjectState, key, config.rules || [], config, config.config, maybeAutoSave);

package/dist/fields/valueField.d.ts

@@ -56,4 +56,4 @@ export interface FieldStateInternal<T, V> extends FieldState<T, V> {
     _isReadOnlyKey: boolean;
     _focused: boolean;
 }
-export declare function newValueFieldState<T, K extends keyof T>(parentInstance: T, parentState: () => ObjectState<T>, key: K, rules: Rule<T, T[K] | null | undefined>[], isIdKey: boolean, isDeleteKey: boolean, isReadOnlyKey: boolean, computed: boolean, readOnly: boolean, maybeAutoSave: () => void): FieldState<T, T[K] | null | undefined>;
+export declare function newValueFieldState<T, K extends keyof T>(parentInstance: T, parentState: () => ObjectState<T>, key: K, rules: Rule<T, T[K] | null | undefined>[], isIdKey: boolean, isDeleteKey: boolean, isReadOnlyKey: boolean, computed: boolean, readOnly: boolean, strictOrder: boolean, maybeAutoSave: () => void): FieldState<T, T[K] | null | undefined>;

package/dist/fields/valueField.js

@@ -5,7 +5,7 @@ const is_plain_object_1 = require("is-plain-object");
 const mobx_1 = require("mobx");
 const rules_1 = require("../rules");
 const utils_1 = require("../utils");
-function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, isDeleteKey, isReadOnlyKey, computed, readOnly, maybeAutoSave) {
+function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, isDeleteKey, isReadOnlyKey, computed, readOnly, strictOrder, maybeAutoSave) {
     // keep a copy here for reference equality
     const value = parentInstance[key];
     let _originalValue = value === null ? undefined : is_plain_object_1.isPlainObject(value) ? mobx_1.toJS(value) : value;
@@ -35,7 +35,7 @@ function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, is
             this.set(v);
         },
         get dirty() {
-            return !utils_1.areEqual(this.originalValue, this.value);
+            return !utils_1.areEqual(this.originalValue, this.value, strictOrder);
         },
         /** Returns whether this field is readOnly, although if our parent is readOnly then it trumps. */
         get readOnly() {
@@ -106,7 +106,7 @@ function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, is
             const coerceEmptyList = value && value instanceof Array && value.length === 0 && utils_1.isEmpty(this.originalValue);
             const newValue = keepNull ? null : utils_1.isEmpty(value) || coerceEmptyList ? undefined : value;
             // Set the value on our parent object
-            const changed = !utils_1.areEqual(newValue, this.value);
+            const changed = !utils_1.areEqual(newValue, this.value, strictOrder);
             parentInstance[key] = newValue;
             _tick.value++;
             if (opts.refreshing) {

package/dist/formState.test.js

@@ -487,6 +487,24 @@ describe("formState", () => {
         a1.favoriteColors.set([]);
         expect(a1.dirty).toBeFalsy();
     });
+    it("can evaluate arrays to be equal even if order of options are different from original when strictOrder = false", () => {
+        // Given an array field value where we define `strictOrder` as false
+        const a1 = objectField_1.createObjectState({ favoriteColors: { type: "value", strictOrder: false } }, { favoriteColors: [formStateDomain_1.Color.Red, formStateDomain_1.Color.Blue] });
+        expect(a1.favoriteColors.dirty).toBeFalsy();
+        // When changing the order of the values
+        a1.favoriteColors.set([formStateDomain_1.Color.Blue, formStateDomain_1.Color.Red]);
+        // Then expect the field to not be dirty
+        expect(a1.dirty).toBeFalsy();
+    });
+    it("evaluates arrays to be equal based on order by default", () => {
+        // Given an array field value
+        const a1 = objectField_1.createObjectState({ favoriteColors: { type: "value" } }, { favoriteColors: [formStateDomain_1.Color.Red, formStateDomain_1.Color.Blue] });
+        expect(a1.favoriteColors.dirty).toBeFalsy();
+        // When we change the order of the values
+        a1.favoriteColors.set([formStateDomain_1.Color.Blue, formStateDomain_1.Color.Red]);
+        // Then the field should be dirty
+        expect(a1.dirty).toBeTruthy();
+    });
     it("knows originally unset fields are dirty", () => {
         // Given firstName is purposefully not set when originally initialized
         const a1 = createAuthorInputState({});

package/dist/utils.d.ts

@@ -37,7 +37,7 @@ export declare function isEmpty(value: any): boolean;
  * - objects that implement `toJSON`
  *
  */
-export declare function areEqual<T>(a?: T, b?: T): boolean;
+export declare function areEqual<T>(a?: T, b?: T, strictOrder?: boolean): boolean;
 export declare function hasToJSON(o?: unknown): o is {
     toJSON(): void;
 };

package/dist/utils.js

@@ -102,7 +102,7 @@ exports.isEmpty = isEmpty;
  * - objects that implement `toJSON`
  *
  */
-function areEqual(a, b) {
+function areEqual(a, b, strictOrder) {
     if (is_plain_object_1.isPlainObject(a)) {
         return fast_deep_equal_1.default(mobx_1.toJS(a), mobx_1.toJS(b));
     }
@@ -112,7 +112,12 @@ function areEqual(a, b) {
         return fast_deep_equal_1.default(a1, b1);
     }
     if (a && b && a instanceof Array && b instanceof Array) {
-        return fast_deep_equal_1.default(a, b);
+        if (strictOrder !== false) {
+            return fast_deep_equal_1.default(a, b);
+        }
+        if (a.length !== b.length)
+            return false;
+        return a.every((a1) => b.some((b1) => fast_deep_equal_1.default(a1, b1)));
     }
     return a === b;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homebound/form-state",
-  "version": "2.13.0",
+  "version": "2.14.0",
   "author": "Homebound",
   "license": "MIT",
   "main": "dist/index.js",