@homebound/form-state 2.13.0 → 2.15.1

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 { AutoSaveStatus, AutoSaveStatusContext, AutoSaveStatusProvider } from "./AutoSaveStatusProvider";
+export { useAutoSaveStatus } from "./useAutoSaveStatus";

package/dist/AutoSaveStatus/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.useAutoSaveStatus = exports.AutoSaveStatusProvider = exports.AutoSaveStatusContext = exports.AutoSaveStatus = void 0;
+var AutoSaveStatusProvider_1 = require("./AutoSaveStatusProvider");
+Object.defineProperty(exports, "AutoSaveStatus", { enumerable: true, get: function () { return AutoSaveStatusProvider_1.AutoSaveStatus; } });
+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/config.d.ts

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

package/dist/fields/objectField.js

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

package/dist/fields/valueField.d.ts

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

package/dist/fields/valueField.js

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

package/dist/formState.test.js

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

package/dist/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.13.0",
+  "version": "2.15.1",
   "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",