@homebound/form-state 2.26.12 → 2.27.1

package/dist/config.d.ts

@@ -56,10 +56,14 @@ export type ListFieldConfig<U> = {
      *
      * When incremental, we only include changed rows in `changedValue`.
      *
+     * When deep-exhaustive, we include all rows in `changedValue` and also
+     * all fields in the child entities, i.e. not just placeholder `{ id: "b:1" }`
+     * values for otherwise-unchanged children.
+     *
      * Defaults to `exhaustive` b/c that is the safest and also Joist's
      * default behavior.
      */
-    update?: "exhaustive" | "incremental";
+    update?: "exhaustive" | "incremental" | "deep-exhaustive";
     /** Set to not consider the order of the list when evaluating changed/dirty states, defaults true. */
     strictOrder?: false;
 };

package/dist/fields/listField.d.ts

@@ -8,4 +8,4 @@ export interface ListFieldState<U> extends FieldState<U[]> {
     add(value: U, index?: number): void;
     remove(indexOrValue: number | U): void;
 }
-export declare function newListFieldState<T, K extends keyof T, U>(parentCopy: T, parentInstance: T, parentState: () => ObjectState<T>, key: K, rules: Rule<readonly ObjectState<U>[]>[], listConfig: ListFieldConfig<U>, config: ObjectFieldConfig<U>, strictOrder: boolean, maybeAutoSave: () => void): ListFieldState<U>;
+export declare function newListFieldState<T, K extends keyof T, U>(parentCopy: T, parentInstance: T, parentState: () => ObjectState<T>, key: K, rules: Rule<readonly ObjectState<U>[]>[], listConfig: ListFieldConfig<U>, config: ObjectFieldConfig<U>, strictOrder: boolean, maybeAutoSave: () => void, deepExhaustive: boolean): ListFieldState<U>;

package/dist/fields/listField.js

@@ -13,7 +13,7 @@ function newListFieldState(
 // parentCopy is objectField's deepClone-d `originalCopy` that it/we use for `dirty` checking
 parentCopy, 
 // parentInstance is objectField's `instance`, that we're currently mutating
-parentInstance, parentState, key, rules, listConfig, config, strictOrder, maybeAutoSave) {
+parentInstance, parentState, key, rules, listConfig, config, strictOrder, maybeAutoSave, deepExhaustive) {
     var _a;
     // Keep a map of "item in the parentInstance list" -> "that item's ObjectState"
     const rowMap = new Map();
@@ -30,6 +30,7 @@ parentInstance, parentState, key, rules, listConfig, config, strictOrder, maybeA
     });
     // Given a child POJO (or a copy/clone of a child POJO), return its ObjectState wrapper.
     function getOrCreateChildState(child, opts) {
+        var _a;
         let childState = rowMap.get(child);
         // If we're being reverted to our originalValue, i.e. values is actually
         // a list of copies, use the copyMap to recover the non-copy original value
@@ -50,7 +51,7 @@ parentInstance, parentState, key, rules, listConfig, config, strictOrder, maybeA
         }
         // If we didn't have an existing child, just make a new object state
         if (!childState) {
-            childState = (0, objectField_1.newObjectState)(config, parentState, undefined, list, child, undefined, maybeAutoSave);
+            childState = (0, objectField_1.newObjectState)(config, parentState, undefined, list, child, undefined, maybeAutoSave, (_a = listConfig.update === "deep-exhaustive") !== null && _a !== void 0 ? _a : deepExhaustive);
             rowMap.set(child, childState);
         }
         return childState;

package/dist/fields/objectField.d.ts

@@ -59,5 +59,5 @@ export declare function createObjectState<T>(config: ObjectConfig<T>, instance:
     maybeAutoSave?: () => void;
 }): ObjectState<T>;
 /** A more internal version of `createObjectState`. */
-export declare function newObjectState<T, P = any>(config: ObjectFieldConfig<T>, parentState: (() => ObjectState<P>) | undefined, parentInstance: P | undefined, parentListState: FieldState<any> | undefined, instance: T, key: keyof T | undefined, maybeAutoSave: () => void): ObjectState<T>;
+export declare function newObjectState<T, P = any>(config: ObjectFieldConfig<T>, parentState: (() => ObjectState<P>) | undefined, parentInstance: P | undefined, parentListState: FieldState<any> | undefined, instance: T, key: keyof T | undefined, maybeAutoSave: () => void, deepExhaustive: boolean): ObjectState<T>;
 export {};

package/dist/fields/objectField.js

@@ -21,10 +21,10 @@ function fragment(value) {
  */
 function createObjectState(config, instance, opts = {}) {
     const noop = () => { };
-    return newObjectState({ type: "object", config }, undefined, undefined, undefined, instance, undefined, opts.maybeAutoSave || noop);
+    return newObjectState({ type: "object", config }, undefined, undefined, undefined, instance, undefined, opts.maybeAutoSave || noop, false);
 }
 /** A more internal version of `createObjectState`. */
-function newObjectState(config, parentState, parentInstance, parentListState, instance, key, maybeAutoSave) {
+function newObjectState(config, parentState, parentInstance, parentListState, instance, key, maybeAutoSave, deepExhaustive) {
     // This is what we return, but we only know it's value until we call `observable`, so
     // we create a mutable variable to capture it so that we can create fields/call their
     // constructors and give them a way to access it later.
@@ -55,7 +55,7 @@ function newObjectState(config, parentState, parentInstance, parentListState, in
             ((0, mobx_1.isObservable)(instance) ? !(key in originalCopy) : false), (_b = config.readOnly) !== null && _b !== void 0 ? _b : false, (_c = config.strictOrder) !== null && _c !== void 0 ? _c : true, maybeAutoSave);
         }
         else if (config.type === "list") {
-            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);
+            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, deepExhaustive);
         }
         else if (config.type === "object") {
             // Because our objectField will fundamentally want to do `child.firstName.set(...)` or
@@ -65,7 +65,7 @@ function newObjectState(config, parentState, parentInstance, parentListState, in
             if (!instance[key]) {
                 instance[key] = {};
             }
-            field = newObjectState(config, getObjectState, instance, undefined, instance[key], key, maybeAutoSave);
+            field = newObjectState(config, getObjectState, instance, undefined, instance[key], key, maybeAutoSave, deepExhaustive);
         }
         else if (config.type === "fragment") {
             field = (0, fragmentField_1.newFragmentField)(instance, key);
@@ -223,7 +223,9 @@ function newObjectState(config, parentState, parentInstance, parentListState, in
                         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)) {
+                    (this.isNewEntity && f._kind === "list" && ((_a = f.value) === null || _a === void 0 ? void 0 : _a.length) > 0) ||
+                    // ...or the parent list is deep-exhaustive
+                    deepExhaustive) {
                     result[f.key] = f.changedValue;
                 }
             });

package/dist/fields/valueField.js

@@ -11,6 +11,13 @@ function newValueFieldState(parentCopy, parentInstance, parentState, key, rules,
     // which itself is not a proxy, we use this as our "value changed" trigger.
     const _tick = (0, mobx_1.observable)({ value: 1 });
     const _originalValueTick = (0, mobx_1.observable)({ value: 1 });
+    // Track "this is probably what we put into a mutation to the server" to allow
+    // use to better accept server acks/responses that change our initial submission.
+    //
+    // I.e. we submit `firstName: bob` and the server acks `firstName: Bob`, we should
+    // accept it if we can tell we haven't changed `bob` since our initial submission.
+    let hasInflightChangedValue = false;
+    let lastChangedValue = undefined;
     const field = {
         key: key,
         touched: false,
@@ -60,6 +67,10 @@ function newValueFieldState(parentCopy, parentInstance, parentState, key, rules,
         },
         // For primitive fields, the changed value is just the value.
         get changedValue() {
+            // Add some hints to let `set(..., { refreshing: true })` accept server-driven changes to our value,
+            // if the user hasn't changed it yet-again while the changedValue was in in-flight.
+            hasInflightChangedValue = true;
+            lastChangedValue = this.value;
             // Usually if we see a field being unset, we set `parent[key] = null`, but if we're wrapping
             // a mobx observable object, it might have changed to `undefined` without us being able to
             // tell it to be `null` (and potentially break the type contract of `string | undefined`).
@@ -100,12 +111,18 @@ function newValueFieldState(parentCopy, parentInstance, parentState, key, rules,
             if (this.readOnly && !opts.resetting && !opts.refreshing) {
                 throw new Error(`${String(key)} is currently readOnly`);
             }
-            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.
-                return;
+            if (opts.refreshing && this.dirty) {
+                // See if we should ignore the incoming server-side value, to avoid dropping local WIP changes
+                const isAckingUnset = this.value === null && (value === null || value === undefined);
+                const acceptServerAck = hasInflightChangedValue && this.value === lastChangedValue;
+                // Ignore incoming values if we have changes (this.dirty) unless:
+                // - our latest change (this.value) matches the incoming value (value), i.e. the server
+                //   is exactly acking our change, or
+                // - the user hasn't made any changes since `.changedValue` was put on the wire, i.e. the
+                //   server received our value, but wanted to to change it.
+                const keepLocalWipChange = this.value !== value && !isAckingUnset && !acceptServerAck;
+                if (keepLocalWipChange)
+                    return;
             }
             else if (computed && (opts.resetting || opts.refreshing)) {
                 // Computeds can't be either reset or refreshed
@@ -117,6 +134,7 @@ function newValueFieldState(parentCopy, parentInstance, parentState, key, rules,
             // If a list of primitives was originally undefined, coerce `[]` to `undefined`
             const coerceEmptyList = value && value instanceof Array && value.length === 0 && (0, utils_1.isEmpty)(this.originalValue);
             const newValue = keepNull ? null : (0, utils_1.isEmpty)(value) || coerceEmptyList ? undefined : value;
+            hasInflightChangedValue = false;
             // Set the value on our parent object
             const changed = !(0, utils_1.areEqual)(newValue, this.value, strictOrder);
             parentInstance[key] = newValue;

package/dist/formState.test.js

@@ -1339,7 +1339,7 @@ describe("formState", () => {
         // And we don't include it in the changedValue
         expect(formState.changedValue).toEqual({ firstName: "First" });
     });
-    it("can return only changed list fields", () => {
+    it("can return only changed and exhaustive list fields", () => {
         // Given an author with some books
         const formState = (0, objectField_1.createObjectState)(authorWithBooksConfig, {
             id: "a:1",
@@ -1430,6 +1430,40 @@ describe("formState", () => {
             books: [{ id: "b:1", title: "t1b" }],
         });
     });
+    it("can return only changed but deep exhaustive list fields", () => {
+        // Given an author
+        const formState = (0, objectField_1.createObjectState)({
+            id: { type: "value" },
+            // And the books collection is marked as deep-exhaustive
+            books: {
+                type: "list",
+                update: "deep-exhaustive",
+                config: {
+                    id: { type: "value" },
+                    title: { type: "value", rules: [rules_1.required] },
+                },
+            },
+        }, {
+            id: "a:1",
+            firstName: "f",
+            books: [
+                { id: "b:1", title: "t1" },
+                { id: "b:2", title: "t2" },
+            ],
+        });
+        // And initially nothing is changed
+        expect(formState.changedValue).toEqual({ id: "a:1" });
+        // When we change the 1st book
+        formState.books.rows[0].title.value = "t1b";
+        // Then we see all books & all attributes
+        expect(formState.changedValue).toEqual({
+            id: "a:1",
+            books: [
+                { id: "b:1", title: "t1b" },
+                { id: "b:2", title: "t2" },
+            ],
+        });
+    });
     it("uses the op key as a hint to use incremental list behavior", () => {
         // Given an author
         const formState = (0, objectField_1.createObjectState)({
@@ -1527,7 +1561,7 @@ describe("formState", () => {
         formState.books.add({ title: "b2" });
         expect(ticks).toEqual(2);
     });
-    it("does not override a focused, changed field", () => {
+    it("keeps WIP changes for changed field", () => {
         const formState = (0, objectField_1.createObjectState)(authorWithBooksConfig, { firstName: "f", lastName: "l" });
         // Given first name is focused
         formState.firstName.focus();
@@ -1542,6 +1576,36 @@ describe("formState", () => {
         formState.firstName.set("fff");
         expect(formState.firstName.value).toEqual("fff");
     });
+    it("accepts server result if we have no further changes", () => {
+        const formState = (0, objectField_1.createObjectState)(authorWithBooksConfig, { id: "a:1", firstName: "f" });
+        // Given first name has wip edits
+        formState.firstName.set("ff");
+        // When a mutation result sets both firstName and lastName
+        formState.set({ firstName: "f2" }, { refreshing: true });
+        // Then we don't overwrite the user's WIP work
+        expect(formState.firstName.value).toEqual("ff");
+        // But if we call changedValue, insinuating we're sending the value off to the server
+        expect(formState.changedValue).toEqual({ id: "a:1", firstName: "ff" });
+        // And now the server acks something different
+        formState.set({ firstName: "FF" }, { refreshing: true });
+        // Then we accept the value
+        expect(formState.firstName.value).toEqual("FF");
+        expect(formState.firstName.dirty).toEqual(false);
+    });
+    it("rejects server result if we have further changes", () => {
+        const formState = (0, objectField_1.createObjectState)(authorWithBooksConfig, { id: "a:1", firstName: "f" });
+        // Given first name has wip edits
+        formState.firstName.set("ff");
+        // And we call changedValue, insinuating we're sending the value off to the server
+        expect(formState.changedValue).toEqual({ id: "a:1", firstName: "ff" });
+        // And the user changes the name yet again
+        formState.firstName.set("fff");
+        // And now the server acks something different
+        formState.set({ firstName: "FF" }, { refreshing: true });
+        // Then we keep the "post-changedValue" value
+        expect(formState.firstName.value).toEqual("fff");
+        expect(formState.firstName.dirty).toEqual(true);
+    });
     it("does update a focused, unchanged field", () => {
         const formState = (0, objectField_1.createObjectState)(authorWithBooksConfig, { firstName: "f", lastName: "l" });
         // Given first name is focused, but has not changed

package/dist/useFormState.test.js

@@ -175,7 +175,7 @@ describe("useFormState", () => {
                 form.address.street.value = "local";
                 form.books.rows[0].title.value = "local";
             }
-            return ((0, jsx_runtime_1.jsx)(mobx_react_1.Observer, { children: () => ((0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("div", { "data-testid": "firstName", children: form.firstName.value }), (0, jsx_runtime_1.jsx)("div", { "data-testid": "lastName", children: form.lastName.value }), (0, jsx_runtime_1.jsx)("div", { "data-testid": "street", children: form.address.street.value }), (0, jsx_runtime_1.jsx)("div", { "data-testid": "city", children: form.address.city.value }), (0, jsx_runtime_1.jsx)("div", { "data-testid": "title1", children: form.books.rows[0].title.value }), (0, jsx_runtime_1.jsx)("div", { "data-testid": "title2", children: form.books.rows[1].title.value }), (0, jsx_runtime_1.jsx)("div", { "data-testid": "booksLength", children: form.books.rows.length }), (0, jsx_runtime_1.jsx)("button", { "data-testid": "makeLocalChanges", onClick: makeLocalChanges }), (0, jsx_runtime_1.jsx)("button", { "data-testid": "refreshData", onClick: () => setData(data2) }), (0, jsx_runtime_1.jsx)("button", { "data-testid": "saveData", onClick: () => setData(data3) }), (0, jsx_runtime_1.jsx)("div", { "data-testid": "changedValue", children: JSON.stringify(form.changedValue) })] })) }));
+            return ((0, jsx_runtime_1.jsx)(mobx_react_1.Observer, { children: () => ((0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("div", { "data-testid": "firstName", children: form.firstName.value }), (0, jsx_runtime_1.jsx)("div", { "data-testid": "lastName", children: form.lastName.value }), (0, jsx_runtime_1.jsx)("div", { "data-testid": "street", children: form.address.street.value }), (0, jsx_runtime_1.jsx)("div", { "data-testid": "city", children: form.address.city.value }), (0, jsx_runtime_1.jsx)("div", { "data-testid": "title1", children: form.books.rows[0].title.value }), (0, jsx_runtime_1.jsx)("div", { "data-testid": "title2", children: form.books.rows[1].title.value }), (0, jsx_runtime_1.jsx)("div", { "data-testid": "booksLength", children: form.books.rows.length }), (0, jsx_runtime_1.jsx)("button", { "data-testid": "makeLocalChanges", onClick: makeLocalChanges }), (0, jsx_runtime_1.jsx)("button", { "data-testid": "refreshData", onClick: () => setData(data2) }), (0, jsx_runtime_1.jsx)("button", { "data-testid": "saveData", onClick: () => setData(data3) }), (0, jsx_runtime_1.jsx)("div", { "data-testid": "dirty", children: String(form.dirty) })] })) }));
         }
         // And we start out with the initial query data
         const r = await (0, rtl_utils_1.render)((0, jsx_runtime_1.jsx)(TestComponent, {}));
@@ -188,12 +188,7 @@ describe("useFormState", () => {
         expect(r.firstName.textContent).toEqual("local");
         expect(r.street.textContent).toEqual("local");
         expect(r.title1.textContent).toEqual("local");
-        expect(JSON.parse(r.changedValue.textContent)).toEqual({
-            id: "a:1",
-            address: { id: "address:1", street: "local" },
-            books: [{ id: "b:1", title: "local" }, { id: "b:2" }],
-            firstName: "local",
-        });
+        expect(r.dirty.textContent).toEqual("true");
         // And when the new query is ran i.e. due to a cache refresh
         (0, rtl_utils_1.click)(r.refreshData);
         // Then we kept our local changes
@@ -205,18 +200,41 @@ describe("useFormState", () => {
         expect(r.city.textContent).toEqual("c2");
         expect(r.title2.textContent).toEqual("b2");
         expect(r.booksLength.textContent).toEqual("3");
-        expect(JSON.parse(r.changedValue.textContent)).toEqual({
-            id: "a:1",
-            address: { id: "address:1", street: "local" },
-            books: [{ id: "b:1", title: "local" }, { id: "b:2" }, { id: "b:3" }],
-            firstName: "local",
-        });
+        expect(r.dirty.textContent).toEqual("true");
         // And then when our mutation results come back
         (0, rtl_utils_1.click)(r.saveData);
-        // Then changedValue doesn't show our local changes anymore
-        expect(JSON.parse(r.changedValue.textContent)).toEqual({
-            id: "a:1",
-        });
+        // And we're not dirty anymore
+        expect(r.dirty.textContent).toEqual("false");
+    });
+    it("accepts server values if client has no further changes", async () => {
+        function TestComponent() {
+            const config = authorWithAddressAndBooksConfig;
+            // The initial resposne
+            const data1 = { id: "a:1", firstName: "F1" };
+            // The acked response, which uppercases our submission
+            const data2 = { id: "a:1", firstName: "F2" };
+            // And we start out with data1
+            const [data, setData] = (0, react_2.useState)(data1);
+            const form = (0, useFormState_1.useFormState)({ config, init: { input: data } });
+            function makeLocalChanges() {
+                form.firstName.value = "f2";
+            }
+            return ((0, jsx_runtime_1.jsx)(mobx_react_1.Observer, { children: () => ((0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("div", { "data-testid": "firstName", children: form.firstName.value }), (0, jsx_runtime_1.jsx)("button", { "data-testid": "makeLocalChanges", onClick: makeLocalChanges }), (0, jsx_runtime_1.jsx)("button", { "data-testid": "refreshData", onClick: () => {
+                                noop(form.changedValue); // pretend we put this on the wire
+                                setData(data2);
+                            } })] })) }));
+        }
+        // And we start out with the initial query data
+        const r = await (0, rtl_utils_1.render)((0, jsx_runtime_1.jsx)(TestComponent, {}));
+        expect(r.firstName.textContent).toEqual("F1");
+        // When we make some local changes
+        (0, rtl_utils_1.click)(r.makeLocalChanges);
+        // Then we see them
+        expect(r.firstName.textContent).toEqual("f2");
+        // And when the server acks a slightly different result
+        (0, rtl_utils_1.click)(r.refreshData);
+        // Then we accept it
+        expect(r.firstName.textContent).toEqual("F2");
     });
     it("can accept new data while read only", async () => {
         // Given a component
@@ -694,3 +712,4 @@ function focusAndBlur(state) {
     state.focus();
     state.blur();
 }
+function noop(value) { }

package/package.json

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