@homebound/form-state 2.12.0 → 2.15.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,21 +10,25 @@ 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
 
 In general when working with forms (e.g. not just form-state), there are three types/shapes of data involved:
 
 1. The input data/shape from the server (i.e. a GraphQL/REST query)
-2. The form data/shape that is being reactively bound to form fields (i.e. used as `<TextField value=form.firstName onChange=(v) => form.firstName = v />`)
+2. The form data/shape that is being reactively bound to form fields (i.e. used as `<TextField value={form.firstName} onChange={(v) => form.firstName = v} />`)
 3. The mutation data/shape that will submit the change to the server (i.e. the GraphQL mutation/REST POST)
 
 form-state generally refers to each of these shapes as:

package/dist/AutoSaveStatus/AutoSaveStatusProvider.d.ts

@@ -0,0 +1,24 @@
+import React, { PropsWithChildren } from "react";
+export declare enum AutoSaveStatus {
+    IDLE = "idle",
+    SAVING = "saving",
+    DONE = "done",
+    ERROR = "error"
+}
+export interface AutoSaveStatusContextType {
+    status: AutoSaveStatus;
+    /** Resets status to IDLE, particularly useful if "Error" or "Done" is stale */
+    resetStatus: VoidFunction;
+    errors: unknown[];
+    /** Notifies AutoSaveContext that a request is in-flight */
+    triggerAutoSave: VoidFunction;
+    /** Notifies AutoSaveContext that a request has settled, optionally taking an error */
+    resolveAutoSave: (error?: unknown) => void;
+}
+export declare const AutoSaveStatusContext: React.Context<AutoSaveStatusContextType>;
+declare type AutoSaveStatusProviderProps = PropsWithChildren<{
+    /** After a successful save, reset Status back to `Idle` after this many milliseconds */
+    resetToIdleTimeout?: number;
+}>;
+export declare function AutoSaveStatusProvider({ children, resetToIdleTimeout }: AutoSaveStatusProviderProps): JSX.Element;
+export {};

package/dist/AutoSaveStatus/AutoSaveStatusProvider.js

@@ -0,0 +1,84 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AutoSaveStatusProvider = exports.AutoSaveStatusContext = exports.AutoSaveStatus = void 0;
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_1 = __importStar(require("react"));
+var AutoSaveStatus;
+(function (AutoSaveStatus) {
+    AutoSaveStatus["IDLE"] = "idle";
+    AutoSaveStatus["SAVING"] = "saving";
+    AutoSaveStatus["DONE"] = "done";
+    AutoSaveStatus["ERROR"] = "error";
+})(AutoSaveStatus = exports.AutoSaveStatus || (exports.AutoSaveStatus = {}));
+exports.AutoSaveStatusContext = react_1.default.createContext({
+    status: AutoSaveStatus.IDLE,
+    resetStatus() { },
+    errors: [],
+    triggerAutoSave() { },
+    resolveAutoSave() { },
+});
+function AutoSaveStatusProvider({ children, resetToIdleTimeout = 6000 }) {
+    const [status, setStatus] = react_1.useState(AutoSaveStatus.IDLE);
+    const [errors, setErrors] = react_1.useState([]);
+    const [inFlight, setInFlight] = react_1.useState(0);
+    const resetToIdleTimeoutRef = react_1.useRef(null);
+    /** Handles setting Status */
+    react_1.useEffect(() => {
+        if (inFlight > 0)
+            return setStatus(AutoSaveStatus.SAVING);
+        if (status === AutoSaveStatus.IDLE)
+            return;
+        if (errors.length)
+            return setStatus(AutoSaveStatus.ERROR);
+        return setStatus(AutoSaveStatus.DONE);
+    }, [errors.length, inFlight, status]);
+    const triggerAutoSave = react_1.useCallback(() => {
+        setInFlight((c) => c + 1);
+        setErrors([]);
+    }, []);
+    const resolveAutoSave = react_1.useCallback((error) => {
+        setInFlight((c) => Math.max(0, c - 1));
+        if (error)
+            setErrors((errs) => errs.concat(error));
+    }, []);
+    const resetStatus = react_1.useCallback(() => {
+        setStatus(AutoSaveStatus.IDLE);
+        setErrors([]);
+    }, []);
+    /** Resets AutoSaveStatus from "Done" to "Idle" after a timeout, if one is provided */
+    react_1.useEffect(() => {
+        if (resetToIdleTimeout === undefined)
+            return;
+        // Specifically avoid auto-reset if Errors are present
+        if (status !== AutoSaveStatus.DONE)
+            return;
+        // Only run the latest Timeout
+        if (resetToIdleTimeoutRef.current)
+            clearTimeout(resetToIdleTimeoutRef.current);
+        resetToIdleTimeoutRef.current = window.setTimeout(() => {
+            resetStatus();
+            resetToIdleTimeoutRef.current = null;
+        }, resetToIdleTimeout);
+    }, [resetStatus, resetToIdleTimeout, status]);
+    return (jsx_runtime_1.jsx(exports.AutoSaveStatusContext.Provider, Object.assign({ value: { status, resetStatus, errors, triggerAutoSave, resolveAutoSave } }, { children: children }), void 0));
+}
+exports.AutoSaveStatusProvider = AutoSaveStatusProvider;

package/dist/AutoSaveStatus/index.d.ts

@@ -0,0 +1,2 @@
+export { AutoSaveStatusContext, AutoSaveStatusProvider } from "./AutoSaveStatusProvider";
+export { useAutoSaveStatus } from "./useAutoSaveStatus";

package/dist/AutoSaveStatus/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useAutoSaveStatus = exports.AutoSaveStatusProvider = exports.AutoSaveStatusContext = void 0;
+var AutoSaveStatusProvider_1 = require("./AutoSaveStatusProvider");
+Object.defineProperty(exports, "AutoSaveStatusContext", { enumerable: true, get: function () { return AutoSaveStatusProvider_1.AutoSaveStatusContext; } });
+Object.defineProperty(exports, "AutoSaveStatusProvider", { enumerable: true, get: function () { return AutoSaveStatusProvider_1.AutoSaveStatusProvider; } });
+var useAutoSaveStatus_1 = require("./useAutoSaveStatus");
+Object.defineProperty(exports, "useAutoSaveStatus", { enumerable: true, get: function () { return useAutoSaveStatus_1.useAutoSaveStatus; } });

package/dist/AutoSaveStatus/useAutoSaveStatus.d.ts

@@ -0,0 +1 @@
+export declare function useAutoSaveStatus(): import("./AutoSaveStatusProvider").AutoSaveStatusContextType;

package/dist/AutoSaveStatus/useAutoSaveStatus.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useAutoSaveStatus = void 0;
+const react_1 = require("react");
+const AutoSaveStatusProvider_1 = require("./AutoSaveStatusProvider");
+function useAutoSaveStatus() {
+    return react_1.useContext(AutoSaveStatusProvider_1.AutoSaveStatusContext);
+}
+exports.useAutoSaveStatus = useAutoSaveStatus;

package/dist/AutoSaveStatus/useAutoSaveStatus.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/AutoSaveStatus/useAutoSaveStatus.test.js

@@ -0,0 +1,152 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const jsx_runtime_1 = require("react/jsx-runtime");
+const react_hooks_1 = require("@testing-library/react-hooks");
+const AutoSaveStatusProvider_1 = require("./AutoSaveStatusProvider");
+const useAutoSaveStatus_1 = require("./useAutoSaveStatus");
+describe(useAutoSaveStatus_1.useAutoSaveStatus, () => {
+    /** The internal setTimeout running after tests is spamming the console, so cancel them all here */
+    afterEach(() => {
+        jest.clearAllTimers();
+    });
+    it("renders without a provider", () => {
+        const { result } = react_hooks_1.renderHook(() => useAutoSaveStatus_1.useAutoSaveStatus());
+        expect(result.current.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.IDLE);
+    });
+    it("renders with a provider", () => {
+        const { result } = react_hooks_1.renderHook(() => useAutoSaveStatus_1.useAutoSaveStatus(), {
+            wrapper: ({ children }) => jsx_runtime_1.jsx(AutoSaveStatusProvider_1.AutoSaveStatusProvider, { children: children }, void 0),
+        });
+        expect(result.current.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.IDLE);
+    });
+    it("indicates when something is in-flight", () => {
+        const { result } = react_hooks_1.renderHook(() => useAutoSaveStatus_1.useAutoSaveStatus(), {
+            wrapper: ({ children }) => jsx_runtime_1.jsx(AutoSaveStatusProvider_1.AutoSaveStatusProvider, { children: children }, void 0),
+        });
+        react_hooks_1.act(() => result.current.triggerAutoSave());
+        expect(result.current.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.SAVING);
+    });
+    it("indicates when a request has settled", () => {
+        const { result } = react_hooks_1.renderHook(() => useAutoSaveStatus_1.useAutoSaveStatus(), {
+            wrapper: ({ children }) => jsx_runtime_1.jsx(AutoSaveStatusProvider_1.AutoSaveStatusProvider, { children: children }, void 0),
+        });
+        react_hooks_1.act(() => result.current.triggerAutoSave());
+        react_hooks_1.act(() => result.current.resolveAutoSave());
+        expect(result.current.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.DONE);
+    });
+    it("indicates when an error happened", () => {
+        const { result } = react_hooks_1.renderHook(() => useAutoSaveStatus_1.useAutoSaveStatus(), {
+            wrapper: ({ children }) => jsx_runtime_1.jsx(AutoSaveStatusProvider_1.AutoSaveStatusProvider, { children: children }, void 0),
+        });
+        react_hooks_1.act(() => result.current.triggerAutoSave());
+        react_hooks_1.act(() => result.current.resolveAutoSave(new Error("Some error")));
+        expect(result.current.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.ERROR);
+        expect(result.current.errors.length).toBe(1);
+    });
+    it("resets status to Idle when told to", () => {
+        const { result } = react_hooks_1.renderHook(() => useAutoSaveStatus_1.useAutoSaveStatus(), {
+            wrapper: ({ children }) => jsx_runtime_1.jsx(AutoSaveStatusProvider_1.AutoSaveStatusProvider, { children: children }, void 0),
+        });
+        react_hooks_1.act(() => result.current.triggerAutoSave());
+        react_hooks_1.act(() => result.current.resolveAutoSave());
+        react_hooks_1.act(() => result.current.resetStatus());
+        expect(result.current.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.IDLE);
+    });
+    it("status goes through the full lifecycle when passed a reset timeout", async () => {
+        // Given a timeout has been passed to `useAutoSave()`
+        const { result } = react_hooks_1.renderHook(() => useAutoSaveStatus_1.useAutoSaveStatus(), {
+            wrapper: ({ children }) => jsx_runtime_1.jsx(AutoSaveStatusProvider_1.AutoSaveStatusProvider, Object.assign({ resetToIdleTimeout: 1000 }, { children: children }), void 0),
+        });
+        // When we trigger a save
+        react_hooks_1.act(() => result.current.triggerAutoSave());
+        // Then status is Saving
+        expect(result.current.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.SAVING);
+        // And when we trigger a resolution
+        react_hooks_1.act(() => result.current.resolveAutoSave());
+        // Then status is Done
+        expect(result.current.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.DONE);
+        // But when the timer runs out
+        react_hooks_1.act(() => {
+            jest.runOnlyPendingTimers();
+        });
+        // Then the status is reset to Idle
+        expect(result.current.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.IDLE);
+    });
+    it("clears errors on reset status", () => {
+        const { result } = react_hooks_1.renderHook(() => useAutoSaveStatus_1.useAutoSaveStatus(), {
+            wrapper: ({ children }) => jsx_runtime_1.jsx(AutoSaveStatusProvider_1.AutoSaveStatusProvider, { children: children }, void 0),
+        });
+        react_hooks_1.act(() => result.current.triggerAutoSave());
+        react_hooks_1.act(() => result.current.resolveAutoSave(new Error("some error")));
+        expect(result.current.errors.length).toBe(1);
+        react_hooks_1.act(() => result.current.resetStatus());
+        expect(result.current.errors.length).toBe(0);
+        expect(result.current.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.IDLE);
+    });
+    it("does not automatically invoke reset timeout if there are errors", () => {
+        // Given a timeout has been passed to `useAutoSave()`
+        const { result } = react_hooks_1.renderHook(() => useAutoSaveStatus_1.useAutoSaveStatus(), {
+            wrapper: ({ children }) => jsx_runtime_1.jsx(AutoSaveStatusProvider_1.AutoSaveStatusProvider, { children: children }, void 0),
+        });
+        react_hooks_1.act(() => result.current.triggerAutoSave());
+        react_hooks_1.act(() => result.current.resolveAutoSave(new Error("Some error")));
+        react_hooks_1.act(() => {
+            jest.runOnlyPendingTimers();
+        });
+        expect(result.current.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.ERROR);
+        expect(result.current.errors.length).toBe(1);
+    });
+    it("does allow manual resetting even if there are errors", () => {
+        // Given a timeout has been passed to `useAutoSave()`
+        const { result } = react_hooks_1.renderHook(() => useAutoSaveStatus_1.useAutoSaveStatus(), {
+            wrapper: ({ children }) => jsx_runtime_1.jsx(AutoSaveStatusProvider_1.AutoSaveStatusProvider, { children: children }, void 0),
+        });
+        react_hooks_1.act(() => result.current.triggerAutoSave());
+        react_hooks_1.act(() => result.current.resolveAutoSave(new Error("Some error")));
+        react_hooks_1.act(() => {
+            jest.runOnlyPendingTimers();
+        });
+        react_hooks_1.act(() => result.current.resetStatus());
+        expect(result.current.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.IDLE);
+        expect(result.current.errors.length).toBe(0);
+    });
+    it("handles multiple in-flight requests", () => {
+        const { result } = react_hooks_1.renderHook(() => useAutoSaveStatus_1.useAutoSaveStatus(), {
+            wrapper: ({ children }) => jsx_runtime_1.jsx(AutoSaveStatusProvider_1.AutoSaveStatusProvider, { children: children }, void 0),
+        });
+        // When we trigger 2 AutoSaves and only resolve 1
+        react_hooks_1.act(() => result.current.triggerAutoSave());
+        react_hooks_1.act(() => result.current.triggerAutoSave());
+        react_hooks_1.act(() => result.current.resolveAutoSave());
+        // We expect something to still be in-flight
+        expect(result.current.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.SAVING);
+        // And when we resolve the final one
+        react_hooks_1.act(() => result.current.resolveAutoSave());
+        // We expect it to finally settle
+        expect(result.current.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.DONE);
+    });
+    it("clears errors when a new save is triggered", () => {
+        const { result } = react_hooks_1.renderHook(() => useAutoSaveStatus_1.useAutoSaveStatus(), {
+            wrapper: ({ children }) => jsx_runtime_1.jsx(AutoSaveStatusProvider_1.AutoSaveStatusProvider, { children: children }, void 0),
+        });
+        react_hooks_1.act(() => result.current.triggerAutoSave());
+        react_hooks_1.act(() => result.current.resolveAutoSave(new Error("some error")));
+        react_hooks_1.act(() => result.current.triggerAutoSave());
+        expect(result.current.errors.length).toBe(0);
+    });
+    it("handles calling resolve too much", () => {
+        const { result } = react_hooks_1.renderHook(() => useAutoSaveStatus_1.useAutoSaveStatus(), {
+            wrapper: ({ children }) => jsx_runtime_1.jsx(AutoSaveStatusProvider_1.AutoSaveStatusProvider, { children: children }, void 0),
+        });
+        // When save hasn't been invoked yet
+        react_hooks_1.act(() => result.current.resolveAutoSave());
+        // Then we effectively didn't run
+        expect(result.current.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.IDLE);
+        // And when 1 save has triggered, and we resolve too much
+        react_hooks_1.act(() => result.current.triggerAutoSave());
+        react_hooks_1.act(() => result.current.resolveAutoSave());
+        react_hooks_1.act(() => result.current.resolveAutoSave());
+        // Then we expect it to be happily "Done"
+        expect(result.current.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.DONE);
+    });
+});

package/dist/FormStateApp.js

@@ -52,8 +52,8 @@ function FormStateApp() {
                                                     jsx_runtime_1.jsx("td", { children: formState.valid.toString() }, void 0),
                                                     jsx_runtime_1.jsx("td", { children: formState.dirty.toString() }, void 0)] }, void 0) }, void 0)] }), void 0),
                                 jsx_runtime_1.jsxs("div", { children: [jsx_runtime_1.jsx("button", Object.assign({ "data-testid": "touch", onClick: () => (formState.touched = !formState.touched) }, { children: "touch" }), void 0),
-                                        jsx_runtime_1.jsx("button", Object.assign({ "data-testid": "reset", onClick: () => formState.reset() }, { children: "reset" }), void 0),
-                                        jsx_runtime_1.jsx("button", Object.assign({ "data-testid": "save", onClick: () => formState.save() }, { children: "save" }), void 0),
+                                        jsx_runtime_1.jsx("button", Object.assign({ "data-testid": "revertChanges", onClick: () => formState.revertChanges() }, { children: "revert" }), void 0),
+                                        jsx_runtime_1.jsx("button", Object.assign({ "data-testid": "commitChanges", onClick: () => formState.commitChanges() }, { children: "commit" }), void 0),
                                         jsx_runtime_1.jsx("button", Object.assign({ "data-testid": "set", onClick: () => formState.set({ firstName: "a2" }) }, { children: "set" }), void 0)] }, void 0)] }, void 0)] }), void 0) }), void 0));
         } }, void 0));
 }

package/dist/FormStateApp.test.js

@@ -12,7 +12,7 @@ describe("FormStateApp", () => {
         expect(r.firstName_dirty()).toHaveTextContent("true");
         react_1.fireEvent.blur(r.firstName());
         expect(r.firstName_touched()).toHaveTextContent("true");
-        rtl_utils_1.click(r.save);
+        rtl_utils_1.click(r.commitChanges);
         expect(r.firstName_dirty()).toHaveTextContent("false");
         expect(r.firstName_touched()).toHaveTextContent("false");
     });
@@ -20,7 +20,7 @@ describe("FormStateApp", () => {
         const r = await rtl_utils_1.render(jsx_runtime_1.jsx(FormStateApp_1.FormStateApp, {}, void 0));
         expect(r.firstName_original()).toHaveTextContent("a1");
         rtl_utils_1.click(r.set);
-        rtl_utils_1.click(r.save);
+        rtl_utils_1.click(r.commitChanges);
         expect(r.firstName_original()).toHaveTextContent("a2");
     });
 });

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/listField.js

@@ -184,16 +184,14 @@ function newListFieldState(parentInstance, parentState, key, rules, listConfig,
             _tick.value++;
             maybeAutoSave();
         },
-        reset() {
+        revertChanges() {
             if (originalCopy) {
                 this.set(originalCopy, { resetting: true });
-                this.rows.forEach((r) => r.reset());
+                this.rows.forEach((r) => r.revertChanges());
             }
         },
-        save() {
-            this.rows.forEach((r) => {
-                r.save();
-            });
+        commitChanges() {
+            this.rows.forEach((r) => r.commitChanges());
             originalCopy = [...(parentInstance[key] || [])];
             _tick.value++;
         },

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);
@@ -132,12 +133,12 @@ function newObjectState(config, parentState, parentListState, instance, key, may
             });
         },
         // Resets all fields back to their original values
-        reset() {
-            getFields(this).forEach((f) => f.reset());
+        revertChanges() {
+            getFields(this).forEach((f) => f.revertChanges());
         },
         // Saves all current values into _originalValue
-        save() {
-            getFields(this).forEach((f) => f.save());
+        commitChanges() {
+            getFields(this).forEach((f) => f.commitChanges());
         },
         // Create a result that is only populated with changed keys
         get changedValue() {

package/dist/fields/valueField.d.ts

@@ -33,9 +33,9 @@ export interface FieldState<T, V> {
     maybeAutoSave(): void;
     set(value: V, opts?: SetOpts): void;
     /** Reverts back to the original value and resets dirty/touched. */
-    reset(): void;
+    revertChanges(): void;
     /** Accepts the current changed value (if any) as the original and resets dirty/touched. */
-    save(): void;
+    commitChanges(): void;
 }
 /** Public options for our `set` command. */
 export interface SetOpts {
@@ -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) {
@@ -118,13 +118,13 @@ function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, is
                 this.maybeAutoSave();
             }
         },
-        reset() {
+        revertChanges() {
             if (!computed) {
                 this.set(this.originalValue, { resetting: true });
             }
             this.touched = false;
         },
-        save() {
+        commitChanges() {
             if (is_plain_object_1.isPlainObject(this.originalValue)) {
                 this.originalValue = mobx_1.toJS(this.value);
             }

package/dist/formState.test.js

@@ -452,7 +452,7 @@ describe("formState", () => {
         a1.set({ firstName: "first" });
         expect(maybeAutoSave).toBeCalledTimes(1);
         // When we reset
-        a1.reset();
+        a1.revertChanges();
         // We don't call blur again
         expect(maybeAutoSave).toBeCalledTimes(1);
     });
@@ -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({});
@@ -541,7 +559,7 @@ describe("formState", () => {
         a1.books.add({ title: "b3" });
         expect(a1.books.touched).toEqual(true);
         expect(a1.dirty).toBeTruthy();
-        a1.reset();
+        a1.revertChanges();
         expect(a1.firstName.value).toBe("a1");
         expect(a1.firstName.touched).toBeFalsy();
         expect(a1.lastName.value).toBe("aL1");
@@ -577,7 +595,7 @@ describe("formState", () => {
         // And the "readOnly=true" operation has "beat" the reset operation
         a1.readOnly = true;
         // When we reset
-        a1.reset();
+        a1.revertChanges();
         // Then it still works
         expect(a1.firstName.value).toBe("a1");
         expect(a1.firstName.touched).toBeFalsy();
@@ -607,15 +625,15 @@ describe("formState", () => {
         a1.books.rows[1].set({ title: "bb3" });
         // verify ValueFieldState is dirty, then save, then no longer dirty.
         expect(a1.firstName.dirty).toBeTruthy();
-        a1.firstName.save();
+        a1.firstName.commitChanges();
         expect(a1.firstName.dirty).toBeFalsy();
         // verify ListFieldState is dirty, then save, then no longer dirty.
         expect(a1.books.dirty).toBeTruthy();
-        a1.books.save();
+        a1.books.commitChanges();
         expect(a1.books.dirty).toBeFalsy();
         // Verify the remaining form is still dirty
         expect(a1.dirty).toBeTruthy();
-        a1.save();
+        a1.commitChanges();
         // Verify after save the whole form is no longer dirty.
         expect(a1.dirty).toBeFalsy();
     });
@@ -839,7 +857,7 @@ describe("formState", () => {
         expect(a.books.rows[1].readOnly).toBeFalsy();
         expect(a.books.rows[1].title.readOnly).toBeFalsy();
         // And reset does not blow up
-        a.reset();
+        a.revertChanges();
     });
     it("can set nested values when original null", () => {
         const a = createAuthorWithAddressInputState({ address: null });
@@ -894,7 +912,7 @@ describe("formState", () => {
         expect(formState.fullName.value).toEqual("first last");
         formState.firstName.value = "change";
         expect(formState.fullName.value).toEqual("change last");
-        formState.reset();
+        formState.revertChanges();
         expect(formState.firstName.value).toEqual("first");
     });
     it("can set computeds that have setters", () => {
@@ -907,7 +925,7 @@ describe("formState", () => {
         expect(formState.firstName.value).toEqual("Bob");
         formState.fullName.set("Fred Smith");
         expect(formState.firstName.value).toEqual("Fred");
-        formState.reset();
+        formState.revertChanges();
         expect(formState.firstName.value).toEqual("first");
     });
     it("can mark fields as read only", () => {
@@ -920,7 +938,7 @@ describe("formState", () => {
         expect(formState.fullName.readOnly).toEqual(true);
         formState.firstName.value = "change";
         expect(formState.fullName.value).toEqual("change last");
-        formState.reset();
+        formState.revertChanges();
         expect(formState.firstName.value).toEqual("first");
     });
     it("lets rules validate against other fields", () => {
@@ -1300,7 +1318,7 @@ describe("formState", () => {
         // Then the list state is dirty
         expect(a1.books.dirty).toBeTruthy();
         // When saving the form state
-        a1.save();
+        a1.commitChanges();
         // Then the list is no longer dirty
         expect(a1.books.dirty).toBeFalsy();
         // When adding a new book

package/dist/index.d.ts

@@ -5,3 +5,4 @@ export { FieldState } from "./fields/valueField";
 export { required, Rule } from "./rules";
 export { useFormState } from "./useFormState";
 export { useFormStates } from "./useFormStates";
+export * from "./AutoSaveStatus/index";

package/dist/index.js

@@ -1,4 +1,14 @@
 "use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    Object.defineProperty(o, k2, { enumerable: true, get: function() { return m[k]; } });
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.useFormStates = exports.useFormState = exports.required = exports.createObjectState = void 0;
 var objectField_1 = require("./fields/objectField");
@@ -9,3 +19,4 @@ var useFormState_1 = require("./useFormState");
 Object.defineProperty(exports, "useFormState", { enumerable: true, get: function () { return useFormState_1.useFormState; } });
 var useFormStates_1 = require("./useFormStates");
 Object.defineProperty(exports, "useFormStates", { enumerable: true, get: function () { return useFormStates_1.useFormStates; } });
+__exportStar(require("./AutoSaveStatus/index"), exports);

package/dist/useFormState.js

@@ -4,6 +4,7 @@ exports.useFormState = void 0;
 const is_plain_object_1 = require("is-plain-object");
 const react_1 = require("react");
 const objectField_1 = require("./fields/objectField");
+const AutoSaveStatus_1 = require("./AutoSaveStatus/index");
 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
@@ -17,6 +18,7 @@ let pendingAutoSave = false;
  */
 function useFormState(opts) {
     const { config, init, addRules, readOnly = false, loading, autoSave } = opts;
+    const autoSaveStatusContext = AutoSaveStatus_1.useAutoSaveStatus();
     // Use a ref so our memo'ized `onBlur` always see the latest value
     const autoSaveRef = react_1.useRef(autoSave);
     autoSaveRef.current = autoSave;
@@ -37,6 +39,7 @@ function useFormState(opts) {
             // Don't use canSave() because we don't want to set touched for all the fields
             if (autoSaveRef.current && form.dirty && form.valid && !isAutoSaving) {
                 isAutoSaving = "queued";
+                let maybeError;
                 // We use setTimeout as a cheap way to wait until the end of the current event listener
                 setTimeout(async () => {
                     try {
@@ -44,10 +47,16 @@ function useFormState(opts) {
                         // user's autoSave function itself wants to call a .set.
                         const promise = autoSaveRef.current(form);
                         isAutoSaving = "in-flight";
+                        autoSaveStatusContext.triggerAutoSave();
                         await promise;
                     }
+                    catch (e) {
+                        maybeError = String(e);
+                        throw e;
+                    }
                     finally {
                         isAutoSaving = false;
+                        autoSaveStatusContext.resolveAutoSave(maybeError === null || maybeError === void 0 ? void 0 : maybeError.toString());
                         if (pendingAutoSave) {
                             pendingAutoSave = false;
                             // Push out the follow-up by 1 tick to allow refreshes to happen to potentially

package/dist/useFormState.test.js

@@ -3,11 +3,14 @@ Object.defineProperty(exports, "__esModule", { value: true });
 const jsx_runtime_1 = require("react/jsx-runtime");
 const rtl_utils_1 = require("@homebound/rtl-utils");
 const react_1 = require("@testing-library/react");
+const react_hooks_1 = require("@testing-library/react-hooks");
 const mobx_1 = require("mobx");
 const mobx_react_1 = require("mobx-react");
 const react_2 = require("react");
 const FormStateApp_1 = require("./FormStateApp");
 const rules_1 = require("./rules");
+const AutoSaveStatus_1 = require("./AutoSaveStatus/index");
+const AutoSaveStatusProvider_1 = require("./AutoSaveStatus/AutoSaveStatusProvider");
 const useFormState_1 = require("./useFormState");
 describe("useFormState", () => {
     it("calls init.map if init.input is defined", async () => {
@@ -499,6 +502,32 @@ describe("useFormState", () => {
         // Then the form is marked as not loading
         expect(r.loading()).toHaveTextContent("false");
     });
+    it("updates AutoSaveStatusProvider when autoSaving", async () => {
+        const config = { firstName: { type: "value" } };
+        const { result } = react_hooks_1.renderHook(() => ({
+            fs: useFormState_1.useFormState({ config, autoSave: async () => { } }),
+            autoSave: AutoSaveStatus_1.useAutoSaveStatus(),
+        }), {
+            wrapper: ({ children }) => (jsx_runtime_1.jsx(AutoSaveStatus_1.AutoSaveStatusProvider, { children: jsx_runtime_1.jsx(mobx_react_1.Observer, { children: () => jsx_runtime_1.jsx(jsx_runtime_1.Fragment, { children: children }, void 0) }, void 0) }, void 0)),
+        });
+        expect(result.current.autoSave.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.IDLE);
+        // When we invoke a change and autoSave fires
+        react_hooks_1.act(() => {
+            result.current.fs.set({ firstName: "test" });
+        });
+        react_hooks_1.act(() => {
+            // useFormState has a setTimeout(..., 0) that needs to run
+            jest.advanceTimersToNextTimer();
+        });
+        expect(result.current.autoSave.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.SAVING);
+        // Idk why this needs to be async but it doesn't work otherwise
+        await react_hooks_1.act(async () => {
+            jest.runAllTimers();
+        });
+        // Then we expect AutoSaveStatus to be notiied of Doneness
+        expect(result.current.autoSave.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.DONE);
+        jest.clearAllTimers();
+    });
 });
 const authorConfig = {
     id: { type: "value" },

package/dist/useFormStates.js

@@ -4,6 +4,7 @@ exports.useFormStates = void 0;
 const react_1 = require("react");
 const objectField_1 = require("./fields/objectField");
 const utils_1 = require("./utils");
+const AutoSaveStatus_1 = require("./AutoSaveStatus/index");
 function useFormStates(opts) {
     const { config, autoSave, getId, map, addRules, readOnly = false } = opts;
     const objectStateCache = react_1.useMemo(() => ({}), 
@@ -18,6 +19,7 @@ function useFormStates(opts) {
     // Use a ref b/c we're memod
     const readOnlyRef = react_1.useRef(readOnly);
     readOnlyRef.current = readOnly;
+    const autoSaveStatusContext = AutoSaveStatus_1.useAutoSaveStatus();
     const getFormState = react_1.useCallback((input, opts = {}) => {
         const existing = objectStateCache[getId(input)];
         let form = existing === null || existing === void 0 ? void 0 : existing[0];
@@ -29,16 +31,23 @@ function useFormStates(opts) {
                     pending.add(form);
                     return;
                 }
+                let maybeError;
                 try {
                     isAutoSaving = true;
+                    autoSaveStatusContext.triggerAutoSave();
                     // See if we have any reactions that want to run (i.e. added by addRules hooks)
                     await new Promise((resolve) => setTimeout(resolve, 0));
                     // If a reaction re-queued our form during the ^ wait, remove it
                     pending.delete(form);
                     await autoSaveRef.current(form);
                 }
+                catch (e) {
+                    maybeError = String(e);
+                    throw e;
+                }
                 finally {
                     isAutoSaving = false;
+                    autoSaveStatusContext.resolveAutoSave(maybeError);
                     if (pending.size > 0) {
                         const first = pending.values().next().value;
                         pending.delete(first);

package/dist/useFormStates.test.js

@@ -2,11 +2,15 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const jsx_runtime_1 = require("react/jsx-runtime");
 const rtl_utils_1 = require("@homebound/rtl-utils");
+const react_hooks_1 = require("@testing-library/react-hooks");
 const mobx_1 = require("mobx");
+const mobx_react_1 = require("mobx-react");
 const react_1 = require("react");
 const FormStateApp_1 = require("./FormStateApp");
 const rules_1 = require("./rules");
 const useFormStates_1 = require("./useFormStates");
+const AutoSaveStatus_1 = require("./AutoSaveStatus/index");
+const AutoSaveStatusProvider_1 = require("./AutoSaveStatus/AutoSaveStatusProvider");
 describe("useFormStates", () => {
     it("can lazily create form states", async () => {
         const autoSave = jest.fn();
@@ -218,6 +222,28 @@ describe("useFormStates", () => {
         // Then it's not read only
         expect(r.firstName()).toHaveAttribute("data-readonly", "false");
     });
+    it("notifies AutoSaveStatusProvider of updates", async () => {
+        const { result } = react_hooks_1.renderHook(() => ({
+            fs: useFormStates_1.useFormStates({ config, autoSave: async () => { }, getId: (o) => o.id }),
+            autoSave: AutoSaveStatus_1.useAutoSaveStatus(),
+        }), {
+            wrapper: ({ children }) => (jsx_runtime_1.jsx(AutoSaveStatus_1.AutoSaveStatusProvider, { children: jsx_runtime_1.jsx(mobx_react_1.Observer, { children: () => jsx_runtime_1.jsx(jsx_runtime_1.Fragment, { children: children }, void 0) }, void 0) }, void 0)),
+        });
+        expect(result.current.autoSave.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.IDLE);
+        react_hooks_1.act(() => {
+            result.current.fs.getFormState({ id: "a:1" }).set({ firstName: "test" });
+        });
+        react_hooks_1.act(() => {
+            // useFormStates has a setTimeout(..., 0) that needs to trigger
+            jest.advanceTimersToNextTimer();
+        });
+        expect(result.current.autoSave.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.SAVING);
+        await react_hooks_1.act(async () => {
+            jest.runAllTimers();
+        });
+        expect(result.current.autoSave.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.DONE);
+        jest.clearAllTimers();
+    });
 });
 const config = {
     id: { type: "value" },

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.12.0",
+  "version": "2.15.0",
   "author": "Homebound",
   "license": "MIT",
   "main": "dist/index.js",
@@ -51,6 +51,7 @@
     "@testing-library/dom": "^8.11.3",
     "@testing-library/jest-dom": "^5.16.2",
     "@testing-library/react": "^12.1.2",
+    "@testing-library/react-hooks": "^8.0.0",
     "@tsconfig/recommended": "^1.0.1",
     "@types/jest": "^26.0.20",
     "@types/react": "^16.14.5",