@homebound/form-state 2.26.2 → 2.26.4

package/README.md

@@ -104,6 +104,69 @@ See the [sample](https://github.com/homebound-team/form-state/blob/main/src/Form
 
 # Features
 
+## Incremental changedValue/dirty Management
+
+In general, we have two types of forms:
+
+- `autoSave` forms
+- `submit` forms
+
+### autoSave forms
+
+For auto save forms, the expectation is that you should:
+
+- Pass `useFormState` an `init.input` and `init.map` that updates the form-state from the initial GraphQL request & any cache updates
+- Pass `useFormState` an `autoSave` lambda that calls your GraphQL mutation, using `changedValue`.
+- Have your `save` mutation response return the acked/updated entity/fragment
+
+  ```ts
+  autoSave: async () => {
+    const input = formState.changedValue;
+    await saveAuthor(input);
+  };
+  ```
+
+With these in place, we will correctly handle interleaved edits/saves, i.e.:
+
+1. User changes `{ firstName: bob }`
+2. We submit `{ id: 1, firstName: bob }` to the backend
+3. While waiting for the response, the user sets `{ lastName: smith }`
+4. The GraphQL mutation acks that `{ id: 1, firstName: bob }` is committed
+5. The `init.map` updates `formState` to realize `firstName` is no longer dirty, but `lastName` keeps its WIP change
+6. formState will trigger a 2nd `autoSave` for just the `lastName` change
+
+### Submit forms
+
+For submit forms, the expectation is that you should:
+
+- Pass `useFormState` an `init.input` and `init.map` that updates the form-state from the initial GraphQL request & any cache updates
+- In your `onClick` lambda, use `formState.changedValue` to call your GraphQL mutation
+- Have your `save` mutation response return the acked/updated entity/fragment
+
+If you do this, you should not have to call `commitChanges` manually, because code like:
+
+```ts
+  onClick: async () => {
+    const input = formState.changedValue;
+    await saveAuthor(input);
+    // checks if formState.dirty is true before closing
+    closeModal();
+  };
+```
+
+Will "just work" because the control flow will be:
+
+- User changes `{ firstName: bob }` and clicks Submit
+- `onClick` runs and we submit `{ id: 1, firstName: bob }` to `saveAuthor`
+- _Before_ the `await` promise resolves, the GraphQL response of `saveAuthor { ...AuthorFragment }` will:
+  - Update the apollo cache
+  - Re-render the `AuthorEditor` component with the new data
+  - Call `init.map` to update `formState` with the new data
+  - Realize the `firstName` is no longer dirty
+- When `closeModal` runs, no "You have unsaved changes?" will appear
+
+Basically, in a correctly-setup form, you should never have to call `commitChanges` manually, and doing so risks losing edits that the user made while any saves (either auto save or submit save) were in-flight.
+
 ## Fragments
 
 Normally, form-state expects all fields in the form to be inputs to the GraphQL mutation/wire call. For example, the `author.firstName` field will always be submitted to the `saveAuthor` mutation (albeit with `author.changedValue` you can have `firstName` conditionally included).

package/dist/fields/objectField.js

@@ -57,6 +57,10 @@ function newObjectState(config, parentState, parentInstance, parentListState, in
             field = (0, listField_1.newListFieldState)(originalCopy, instance, getObjectState, key, config.rules || [], config, { type: "object", config: config.config }, (_d = config.strictOrder) !== null && _d !== void 0 ? _d : true, maybeAutoSave);
         }
         else if (config.type === "object") {
+            // Because our objectField will fundamentally want to do `child.firstName.set(...)` or
+            // even `child.firstName !== undefined`, etc., we "simplify" things by always setting
+            // an empty object, for our child valueFields/listFields to use/read from, although
+            // we then have to "oh right ignore {}" in places like `dirty`.
             if (!instance[key]) {
                 instance[key] = {};
             }
@@ -131,7 +135,10 @@ function newObjectState(config, parentState, parentInstance, parentListState, in
             return getFields(this).flatMap((f) => f.errors.map((e) => `${f.key}: ${e}`));
         },
         get dirty() {
-            return getFields(this).some((f) => f.dirty) || this.isUnset();
+            return (getFields(this).some((f) => f.dirty) ||
+                // `isUnset` checks if our `parent[key] === undefined`, which can mean "surely we're dirty",
+                // but as long as we've got some keys actually set
+                (this.isUnset() && !(0, utils_1.areEqual)(this.value, {})));
         },
         get isNewEntity() {
             const idField = getFields(this).find((f) => f._isIdKey);
@@ -207,7 +214,11 @@ function newObjectState(config, parentState, parentInstance, parentListState, in
                     // look dirty, but if we're new we should include them anyway.
                     (this.isNewEntity && f._kind === "value" && f.value !== undefined) ||
                     // ...or they're non-empty sub-objects
-                    (this.isNewEntity && f._kind === "object" && Object.entries(f.changedValue).length > 0) ||
+                    (this.isNewEntity &&
+                        f._kind === "object" &&
+                        // Child objects that are unset will have `changedValue = null`
+                        f.changedValue &&
+                        Object.entries(f.changedValue).length > 0) ||
                     // ...or they're non-empty sub-lists
                     (this.isNewEntity && f._kind === "list" && ((_a = f.value) === null || _a === void 0 ? void 0 : _a.length) > 0)) {
                     result[f.key] = f.changedValue;

package/dist/fields/valueField.js

@@ -100,7 +100,8 @@ function newValueFieldState(parentCopy, parentInstance, parentState, key, rules,
             if (this.readOnly && !opts.resetting && !opts.refreshing) {
                 throw new Error(`${String(key)} is currently readOnly`);
             }
-            if (opts.refreshing && this.dirty && this.value !== value) {
+            const isAckingUnset = this.value === null && (value === null || value === undefined);
+            if (opts.refreshing && this.dirty && this.value !== value && !isAckingUnset) {
                 // Ignore incoming values if we have changes (this.dirty) unless our latest change (this.value)
                 // matches the incoming value (value), b/c if it does we should accept it and reset originalValue
                 // so that we're no longer dirty.

package/dist/formState.test.js

@@ -595,6 +595,19 @@ describe("formState", () => {
         a1.firstName.set("a1");
         expect(a1.dirty).toBeFalsy();
     });
+    it("realizes object fields set to null aren't actually dirty", () => {
+        // Given we started off with a `object: undefined`
+        const a1 = createAuthorWithAddressInputState({ address: undefined });
+        expect(a1.address.dirty).toBe(false);
+        expect(a1.address.value).toEqual({});
+        // And it's later set to null, i.e. from a mutation returning `{ address: null }`
+        a1.set({ firstName: "a1", address: null });
+        // Then we convert it to `{}` to potentially hold data
+        expect(a1.address.value).toEqual({});
+        // But we don't consider the address dirty
+        expect(a1.address.dirty).toBe(false);
+        expect(a1.changedValue).toEqual({ firstName: "a1" });
+    });
     it("knows an object's field of type object is dirty", () => {
         const a1 = createAuthorInputState({
             books: [{ title: "b1", classification: formStateDomain_1.dd100 }],
@@ -722,6 +735,13 @@ describe("formState", () => {
         expect(a1.firstName.value).toBeNull();
         expect(a1.originalValue.firstName).toBe("asdf");
         expect(a1.firstName.dirty).toBeTruthy();
+        // And when the server acks as null
+        a1.set({ firstName: undefined }, { refreshing: true });
+        // Then it's no longer dirty
+        expect(a1.firstName.dirty).toBe(false);
+        expect(a1.firstName.originalValue).toBe(undefined);
+        expect(a1.firstName.value).toBe(undefined);
+        expect(a1.changedValue).toEqual({});
     });
     it("initializes null values to be undefined", () => {
         // Given a property that is initially set to null

package/package.json

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