@homebound/form-state 2.2.12 → 2.4.1

package/dist/formState.d.ts

@@ -25,7 +25,7 @@
  */
 export declare type ObjectState<T, P = any> = FieldStates<T> & FieldState<P, T> & {
     /** Sets the state of fields in `state`. */
-    set(state: Partial<T>): void;
+    set(state: Partial<T>, opts?: SetOpts): void;
     /** Returns whether the object can be saved, i.e. is valid, but also as a side-effect marks touched. */
     canSave(): boolean;
 };
@@ -72,14 +72,21 @@ export interface FieldState<T, V> {
     readonly changedValue: V;
     /** Focuses the field. Disables changes from `ObjectState.set` calls. */
     focus(): void;
-    /** Blur essentially touches the field. */
+    /** Blur marks the field as touched and triggers an auto-save. */
     blur(): void;
-    set(value: V): void;
+    /** Triggers an auto-save; the caller (i.e. useFormState) should still dirty & valid check. */
+    maybeAutoSave(): void;
+    set(value: V, opts?: SetOpts): void;
     /** Reverts back to the original value and resets dirty/touched. */
     reset(): void;
     /** Accepts the current changed value (if any) as the original and resets dirty/touched. */
     save(): void;
 }
+/** Public options for our `set` command. */
+export interface SetOpts {
+    /** Whether this `set` should trigger an auto-save; defaults to true. */
+    autoSave?: boolean;
+}
 /** Form state for list of children, i.e. `U` is a `Book` in a form with a `books: Book[]`. */
 export interface ListFieldState<T, U> extends Omit<FieldState<T, U[]>, "originalValue"> {
     readonly rows: ReadonlyArray<ObjectState<U>>;
@@ -156,7 +163,7 @@ export declare type ObjectFieldConfig<U> = {
  * individual fields as well as the top-level form/object itself.
  */
 export declare function createObjectState<T>(config: ObjectConfig<T>, instance: T, opts?: {
-    onBlur?: () => void;
+    maybeAutoSave?: () => void;
 }): ObjectState<T>;
 declare type Primitive = undefined | null | boolean | string | number | Function | Date | {
     toJSON(): any;

package/dist/formState.js

@@ -12,7 +12,8 @@ const utils_1 = require("./utils");
 // We pre-emptively make this a mobx action so that it's identity doesn't change when proxy-ified
 // and breaks our ability to do `rules.some(r => r === required)`.
 exports.required = mobx_1.action(({ value: v }) => {
-    return v !== undefined && v !== null && v !== "" ? undefined : "Required";
+    const isEmptyString = typeof v === "string" ? v.trim() === "" : false;
+    return v !== undefined && v !== null && !isEmptyString ? undefined : "Required";
 });
 /**
  * Creates a new `ObjectState` for a given form object `T` given config rules in `config`.
@@ -23,10 +24,10 @@ exports.required = mobx_1.action(({ value: v }) => {
  */
 function createObjectState(config, instance, opts = {}) {
     const noop = () => { };
-    return newObjectState(config, undefined, instance, undefined, opts.onBlur || noop);
+    return newObjectState(config, undefined, instance, undefined, opts.maybeAutoSave || noop);
 }
 exports.createObjectState = createObjectState;
-function newObjectState(config, parentState, instance, key, onBlur) {
+function newObjectState(config, parentState, instance, key, maybeAutoSave) {
     // 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.
@@ -42,16 +43,16 @@ function newObjectState(config, parentState, instance, key, onBlur) {
         const config = _config;
         let field;
         if (config.type === "value") {
-            field = newValueFieldState(instance, getObjectState, key, config.rules || [], config.isIdKey || key === "id", config.isDeleteKey || false, config.isReadOnlyKey || false, config.computed || false, config.readOnly || false, onBlur);
+            field = newValueFieldState(instance, getObjectState, key, config.rules || [], config.isIdKey || key === "id", config.isDeleteKey || false, config.isReadOnlyKey || false, config.computed || false, config.readOnly || false, maybeAutoSave);
         }
         else if (config.type === "list") {
-            field = newListFieldState(instance, getObjectState, key, config.rules || [], config, config.config, onBlur);
+            field = newListFieldState(instance, getObjectState, key, config.rules || [], config, config.config, maybeAutoSave);
         }
         else if (config.type === "object") {
             if (!instance[key]) {
                 instance[key] = {};
             }
-            field = newObjectState(config.config, getObjectState, instance[key], key, onBlur);
+            field = newObjectState(config.config, getObjectState, instance[key], key, maybeAutoSave);
         }
         else {
             throw new Error("Unsupported");
@@ -185,7 +186,7 @@ function newObjectState(config, parentState, instance, key, onBlur) {
     mobx_1.reaction(() => getFields(proxy).map((f) => f.value), () => _tick.value++);
     return proxy;
 }
-function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, isDeleteKey, isReadOnlyKey, computed, readOnly, onBlur) {
+function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, isDeleteKey, isReadOnlyKey, computed, readOnly, 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;
@@ -260,14 +261,15 @@ function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, is
             this._focused = true;
         },
         blur() {
-            // Now that the user is done editing the field, we sneak in some trim logic
-            if (this._focused) {
-                this.maybeTrim();
-            }
+            this.maybeAutoSave();
             this._focused = false;
+        },
+        maybeAutoSave() {
+            // Now that the user is done editing the field (note maybe w/o blurring, i.e. if they hit enter), we sneak in some trim logic
+            this.maybeTrim();
             // touched is readonly, but we're allowed to change it
             this.touched = true;
-            onBlur();
+            maybeAutoSave();
         },
         set(value, opts = {}) {
             if (this.readOnly && !opts.resetting && !opts.refreshing) {
@@ -298,8 +300,8 @@ function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, is
             }
             // If we're being set programmatically, i.e. we don't currently have focus,
             // call blur to trigger any auto-saves.
-            if (!this._focused && !opts.refreshing && !opts.resetting && this.dirty && changed) {
-                this.blur();
+            if (!this._focused && !opts.refreshing && !opts.resetting && this.dirty && changed && opts.autoSave !== false) {
+                this.maybeAutoSave();
             }
         },
         reset() {
@@ -339,7 +341,7 @@ function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, is
     };
     return field;
 }
-function newListFieldState(parentInstance, parentState, key, rules, listConfig, config, onBlur) {
+function newListFieldState(parentInstance, parentState, key, rules, listConfig, config, maybeAutoSave) {
     // Keep a map of "item in the parent list" -> "that item's ObjectState"
     const rowMap = new Map();
     const _tick = mobx_1.observable({ value: 1 });
@@ -399,7 +401,7 @@ function newListFieldState(parentInstance, parentState, key, rules, listConfig,
                 // Because we're reading from this.value, child will be the proxy version
                 let childState = rowMap.get(child);
                 if (!childState) {
-                    childState = newObjectState(config, parentState, child, undefined, onBlur);
+                    childState = newObjectState(config, parentState, child, undefined, maybeAutoSave);
                     rowMap.set(child, childState);
                 }
                 return childState;
@@ -442,8 +444,11 @@ function newListFieldState(parentInstance, parentState, key, rules, listConfig,
         },
         blur() {
             this._focused = false;
+            this.maybeAutoSave();
+        },
+        maybeAutoSave() {
             this.touched = true;
-            onBlur();
+            maybeAutoSave();
         },
         set(values, opts = {}) {
             if (this.readOnly && !opts.resetting && !opts.refreshing) {
@@ -462,7 +467,7 @@ function newListFieldState(parentInstance, parentState, key, rules, listConfig,
                         }
                     }
                     // If we didn't have an existing child, just make a new object state
-                    childState = createObjectState(config, value, { onBlur });
+                    childState = createObjectState(config, value, { maybeAutoSave });
                     rowMap.set(value, childState);
                 }
                 // Return the already-observable'd value so that our `parent.value[key] = values` doesn't re-proxy things
@@ -476,12 +481,12 @@ function newListFieldState(parentInstance, parentState, key, rules, listConfig,
         },
         add(value, spliceIndex) {
             // This is called by the user, so value should be a non-proxy value we should keep
-            const childState = createObjectState(config, value, { onBlur });
+            const childState = createObjectState(config, value, { maybeAutoSave });
             rowMap.set(value, childState);
             this.ensureSet();
             this.value.splice(typeof spliceIndex === "number" ? spliceIndex : this.value.length, 0, childState.value);
             _tick.value++;
-            onBlur();
+            maybeAutoSave();
         },
         remove(indexOrValue) {
             this.ensureSet();
@@ -495,7 +500,7 @@ function newListFieldState(parentInstance, parentState, key, rules, listConfig,
                 }
             }
             _tick.value++;
-            onBlur();
+            maybeAutoSave();
         },
         reset() {
             if (originalCopy) {

package/dist/formState.test.js

@@ -39,6 +39,21 @@ describe("formState", () => {
         expect(a.title.required).toBeTruthy();
         expect(a.isPublished.required).toBeFalsy();
     });
+    it("trims whitespace within the required rule", () => {
+        const a = formState_1.createObjectState({ title: { type: "value", rules: [formState_1.required] } }, { title: "initial valid title" });
+        let numErrors = 0;
+        mobx_1.autorun(() => {
+            numErrors = a.title.errors.length;
+        });
+        expect(a.valid).toBeTruthy();
+        expect(numErrors).toEqual(0);
+        // When a value contains only whitespace
+        a.title.value = "  ";
+        expect(a.title.valid).toBeFalsy();
+        expect(numErrors).toEqual(1);
+        expect(a.title.errors).toEqual(["Required"]);
+        expect(a.errors).toEqual(["title: Required"]);
+    });
     it("can set values", () => {
         const a = formState_1.createObjectState({ title: { type: "value" } }, { title: "b1" });
         expect(a.title.value).toEqual("b1");
@@ -285,6 +300,52 @@ describe("formState", () => {
         expect(a.firstName.valid).toBeTruthy();
         expect(a.lastName.errors).toEqual(["Last name cannot be first name"]);
     });
+    it("passes sanitized values to validation rules", () => {
+        // Given a field with a validation rule
+        const rule = jest.fn().mockReturnValue("Required");
+        const a = formState_1.createObjectState({ firstName: { type: "value", rules: [rule] } }, {});
+        expect(rule).toHaveBeenCalledTimes(0);
+        // When the field is set to empty string
+        a.firstName.value = "";
+        expect(a.firstName.errors).toEqual(["Required"]);
+        expect(rule).toHaveBeenCalledTimes(1);
+        // Then the validation rule was passed undefined
+        expect(rule).toHaveBeenCalledWith({
+            value: undefined,
+            originalValue: undefined,
+            key: "firstName",
+            object: expect.anything(),
+        });
+    });
+    it("passes trimmed values to validation rules on maybeAutoSave", () => {
+        // Given we have a required rule
+        const rule = jest.fn().mockReturnValue("Required");
+        const a = formState_1.createObjectState({ firstName: { type: "value", rules: [rule] } }, {});
+        expect(rule).toHaveBeenCalledTimes(0);
+        // When the user initially sets an empty string value
+        a.firstName.focus();
+        a.firstName.value = "   ";
+        expect(a.firstName.errors).toEqual(["Required"]);
+        // Then initially the rule is called with the empty string
+        expect(rule).toHaveBeenCalledTimes(1);
+        expect(rule).toHaveBeenCalledWith({
+            value: "   ",
+            originalValue: undefined,
+            key: "firstName",
+            object: expect.anything(),
+        });
+        // But then when the field maybeAutoSaves (i.e. via blur)
+        a.firstName.maybeAutoSave();
+        expect(a.firstName.errors).toEqual(["Required"]);
+        // Then the rule is called with the undefined
+        expect(rule).toHaveBeenCalledTimes(2);
+        expect(rule).toHaveBeenCalledWith({
+            value: undefined,
+            originalValue: undefined,
+            key: "firstName",
+            object: expect.anything(),
+        });
+    });
     it("simple value changes trigger observers", () => {
         const a = formState_1.createObjectState({
             title: { type: "value", rules: [formState_1.required] },
@@ -330,69 +391,78 @@ describe("formState", () => {
         a1.books.remove(0);
         expect(a1.dirty).toBeFalsy();
     });
-    it("calls onBlur when adding or removing to a list", () => {
-        const onBlur = jest.fn();
-        const a1 = createAuthorInputState({ books: [] }, onBlur);
+    it("calls maybeAutoSave when adding or removing to a list", () => {
+        const maybeAutoSave = jest.fn();
+        const a1 = createAuthorInputState({ books: [] }, maybeAutoSave);
         expect(a1.books.dirty).toBeFalsy();
         a1.books.add({ title: "t2" });
         expect(a1.books.dirty).toBeTruthy();
         a1.books.remove(0);
         expect(a1.dirty).toBeFalsy();
-        expect(onBlur).toBeCalledTimes(2);
+        expect(maybeAutoSave).toBeCalledTimes(2);
     });
-    it("calls onBlur when programmatically setting a value", () => {
-        const onBlur = jest.fn();
+    it("calls maybeAutoSave when programmatically setting a value", () => {
+        const maybeAutoSave = jest.fn();
         // Given an author listening for blur
-        const a1 = createAuthorInputState({ books: [{}] }, onBlur);
+        const a1 = createAuthorInputState({ books: [{}] }, maybeAutoSave);
         // When we programmatically set a field that isn't focused
         a1.firstName.value = "first";
-        // Then we call onBlur
-        expect(onBlur).toBeCalledTimes(1);
+        // Then we call maybeAutoSave
+        expect(maybeAutoSave).toBeCalledTimes(1);
         // And when we set a nested value
         a1.books.rows[0].title.value = "title";
-        // Then we called onBlur again
-        expect(onBlur).toBeCalledTimes(2);
+        // Then we called maybeAutoSave again
+        expect(maybeAutoSave).toBeCalledTimes(2);
     });
-    it("defers calling onBlur when setting a bound value", () => {
-        const onBlur = jest.fn();
+    it("can skip maybeAutoSave when programmatically setting a value", () => {
+        const maybeAutoSave = jest.fn();
         // Given an author listening for blur
-        const a1 = createAuthorInputState({ books: [{}] }, onBlur);
+        const a1 = createAuthorInputState({ books: [{}] }, maybeAutoSave);
+        // When we programmatically set a field that isn't focused
+        a1.set({ firstName: "first" }, { autoSave: false });
+        // Then we don't call maybeAutoSave
+        expect(maybeAutoSave).toBeCalledTimes(0);
+    });
+    it("defers calling maybeAutoSave when setting a focused value", () => {
+        const maybeAutoSave = jest.fn();
+        // Given an author listening for blur
+        const a1 = createAuthorInputState({ books: [{}] }, maybeAutoSave);
         // And the field is focused
         a1.firstName.focus();
         // When we we set the field
         a1.firstName.value = "first";
-        // Then we don't call onBlur
-        expect(onBlur).toBeCalledTimes(0);
+        // Then we don't call maybeAutoSave
+        expect(maybeAutoSave).toBeCalledTimes(0);
     });
-    it("skips onBlur when refreshing", () => {
-        const onBlur = jest.fn();
+    it("skips maybeAutoSave when refreshing", () => {
+        const maybeAutoSave = jest.fn();
         // Given an author listening for blur
-        const a1 = createAuthorInputState({ books: [{}] }, onBlur);
+        const a1 = createAuthorInputState({ books: [{}] }, maybeAutoSave);
         // When we programmatically set a field that isn't focused
         a1.set({ firstName: "first" }, { refreshing: true });
-        // Then we don't call onBlur
-        expect(onBlur).toBeCalledTimes(0);
+        // Then we don't call maybeAutoSave
+        expect(maybeAutoSave).toBeCalledTimes(0);
     });
-    it("skips onBlur when resetting", () => {
-        const onBlur = jest.fn();
+    it("skips maybeAutoSave when resetting", () => {
+        const maybeAutoSave = jest.fn();
         // Given an author listening for blur
-        const a1 = createAuthorInputState({ books: [{}] }, onBlur);
-        // And we called onBlur once
+        const a1 = createAuthorInputState({ books: [{}] }, maybeAutoSave);
+        // And we called maybeAutoSave once
         a1.set({ firstName: "first" });
-        expect(onBlur).toBeCalledTimes(1);
+        expect(maybeAutoSave).toBeCalledTimes(1);
         // When we reset
         a1.reset();
         // We don't call blur again
-        expect(onBlur).toBeCalledTimes(1);
+        expect(maybeAutoSave).toBeCalledTimes(1);
     });
-    it("skips onBlur when not dirty", () => {
-        const onBlur = jest.fn();
+    it("skips maybeAutoSave when not dirty", () => {
+        const maybeAutoSave = jest.fn();
         // Given an author listening for blur
-        const a1 = createAuthorInputState({ firstName: "first", books: [{}] }, onBlur);
+        const a1 = createAuthorInputState({ firstName: "first", books: [{}] }, maybeAutoSave);
         // When we programmatically set a field to it's existing valued
         a1.firstName.value = "first";
-        // Then we don't call onBlur
-        expect(onBlur).toBeCalledTimes(0);
+        // Then we don't call maybeAutoSave
+        expect(maybeAutoSave).toBeCalledTimes(0);
     });
     it("knows list of primitives are dirty", () => {
         const a1 = formState_1.createObjectState({ favoriteColors: { type: "value" } }, {});
@@ -955,6 +1025,20 @@ describe("formState", () => {
         // Then we trim it
         expect(formState.firstName.value).toEqual("f");
     });
+    it("trims string values on maybeAutoSave", () => {
+        const formState = formState_1.createObjectState(authorWithBooksConfig, { firstName: "f", lastName: "l" });
+        // Given the user is typing with spaces
+        formState.firstName.focus();
+        formState.firstName.set("f ");
+        // And we initially keep the space
+        expect(formState.firstName.value).toEqual("f ");
+        // When the user hits Enter (which will call maybeAutoSave)
+        formState.firstName.maybeAutoSave();
+        // Then we trim it
+        expect(formState.firstName.value).toEqual("f");
+        // And the field is considered touched
+        expect(formState.firstName.touched).toEqual(true);
+    });
     it("trims empty values to undefined on blur", () => {
         const formState = formState_1.createObjectState(authorWithBooksConfig, { firstName: "f", lastName: "l" });
         // Given the user is typing with only spaces
@@ -1093,8 +1177,8 @@ const authorWithBooksConfig = {
         },
     },
 };
-function createAuthorInputState(input, onBlur) {
-    return formState_1.createObjectState(authorWithBooksConfig, input, { onBlur });
+function createAuthorInputState(input, maybeAutoSave) {
+    return formState_1.createObjectState(authorWithBooksConfig, input, { maybeAutoSave });
 }
 const authorWithAddressConfig = {
     id: { type: "value" },

package/dist/useFormState.js

@@ -6,6 +6,9 @@ const mobx_1 = require("mobx");
 const react_1 = require("react");
 const formState_1 = require("./formState");
 const utils_1 = require("./utils");
+// If the user's autoSave hook makes some last-minute `.set` calls to sneak
+// in some business logic right before their GraphQL mutation call, ignore it
+// so that we don't infinite loop.
 let isAutoSaving = false;
 /**
  * Creates a formState instance for editing in a form.
@@ -22,8 +25,8 @@ function useFormState(opts) {
     // If they're using init.input, useMemo on it (and it might be an array), otherwise allow the identity of init be unstable
     const dep = init && "input" in init && "map" in init ? (Array.isArray(init.input) ? init.input : [init.input]) : [];
     const form = react_1.useMemo(() => {
-        function onBlur() {
-            // Don't use canSave() because we don't want to set touched for all of the field
+        function maybeAutoSave() {
+            // Don't use canSave() because we don't want to set touched for all the fields
             if (autoSaveRef.current && form.dirty && form.valid && !isAutoSaving) {
                 try {
                     isAutoSaving = true;
@@ -35,7 +38,7 @@ function useFormState(opts) {
             }
         }
         const value = firstRunRef.current ? firstInitValue : initValue(config, init);
-        const form = formState_1.createObjectState(config, value, { onBlur });
+        const form = formState_1.createObjectState(config, value, { maybeAutoSave });
         form.readOnly = readOnly;
         // The identity of `addRules` is not stable, but assume that it is for better UX.
         // eslint-disable-next-line react-hooks/exhaustive-deps

package/dist/useFormState.test.js

@@ -306,8 +306,8 @@ describe("useFormState", () => {
             });
             return (jsx_runtime_1.jsx(mobx_react_1.Observer, { children: () => (jsx_runtime_1.jsxs("div", { children: [jsx_runtime_1.jsx("button", { "data-testid": "refreshData", onClick: () => setData(data2) }, void 0),
                         jsx_runtime_1.jsx("button", { "data-testid": "add", onClick: () => form.books.add({ title: "New Book" }) }, void 0),
-                        jsx_runtime_1.jsx("button", { "data-testid": "blurBookOne", onClick: () => form.books.rows[0].title.blur() }, void 0),
-                        jsx_runtime_1.jsx("button", { "data-testid": "blurBookTwo", onClick: () => form.books.rows[1].title.blur() }, void 0)] }, void 0)) }, void 0));
+                        jsx_runtime_1.jsx("button", { "data-testid": "blurBookOne", onClick: () => focusAndBlur(form.books.rows[0].title) }, void 0),
+                        jsx_runtime_1.jsx("button", { "data-testid": "blurBookTwo", onClick: () => focusAndBlur(form.books.rows[1].title) }, void 0)] }, void 0)) }, void 0));
         }
         // Given a formState with `onBlur` set
         const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
@@ -472,3 +472,8 @@ const authorWithAddressAndBooksConfig = {
         },
     },
 };
+/** Emulates a user focusing and then blurring a field. */
+function focusAndBlur(state) {
+    state.focus();
+    state.blur();
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homebound/form-state",
-  "version": "2.2.12",
+  "version": "2.4.1",
   "author": "Homebound",
   "license": "MIT",
   "main": "dist/index.js",
@@ -25,7 +25,9 @@
     "fast-deep-equal": "^3.1.3",
     "is-plain-object": "^5.0.0",
     "mobx": "^6.3.2",
-    "mobx-react": "^7.2.0",
+    "mobx-react": "^7.2.0"
+  },
+  "peerDependencies": {
     "react": ">=16"
   },
   "devDependencies": {