@homebound/form-state 2.8.0 → 2.10.0

package/dist/FormStateApp.d.ts

@@ -1,2 +1,6 @@
 /// <reference types="react" />
+import { FieldState } from "./index";
 export declare function FormStateApp(): JSX.Element;
+export declare function TextField(props: {
+    field: FieldState<any, string | null | undefined>;
+}): JSX.Element;

package/dist/FormStateApp.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.FormStateApp = void 0;
+exports.TextField = exports.FormStateApp = void 0;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const mobx_react_1 = require("mobx-react");
 const index_1 = require("./index");
@@ -91,3 +91,4 @@ function TextField(props) {
                                     jsx_runtime_1.jsx("td", Object.assign({ "data-testid": `${field.key}_errors` }, { children: field.errors }), void 0),
                                     jsx_runtime_1.jsx("td", Object.assign({ "data-testid": `${field.key}_original` }, { children: field.originalValue }), void 0)] }, void 0) }, void 0)] }), void 0)] }, void 0)) }, void 0));
 }
+exports.TextField = TextField;

package/dist/formState.js

@@ -24,10 +24,10 @@ exports.required = mobx_1.action(({ value: v }) => {
  */
 function createObjectState(config, instance, opts = {}) {
     const noop = () => { };
-    return newObjectState(config, undefined, instance, undefined, opts.maybeAutoSave || noop);
+    return newObjectState(config, undefined, undefined, instance, undefined, opts.maybeAutoSave || noop);
 }
 exports.createObjectState = createObjectState;
-function newObjectState(config, parentState, instance, key, maybeAutoSave) {
+function newObjectState(config, parentState, parentListState, 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.
@@ -52,7 +52,7 @@ function newObjectState(config, parentState, instance, key, maybeAutoSave) {
             if (!instance[key]) {
                 instance[key] = {};
             }
-            field = newObjectState(config.config, getObjectState, instance[key], key, maybeAutoSave);
+            field = newObjectState(config.config, getObjectState, undefined, instance[key], key, maybeAutoSave);
         }
         else {
             throw new Error("Unsupported");
@@ -93,12 +93,13 @@ function newObjectState(config, parentState, instance, key, maybeAutoSave) {
             getFields(this).forEach((f) => (f.touched = touched));
         },
         get readOnly() {
-            return this._readOnly || this._considerReadOnly();
+            return (this._readOnly ||
+                this._considerReadOnly() ||
+                (parentState && parentState().readOnly) ||
+                !!(parentListState === null || parentListState === void 0 ? void 0 : parentListState.readOnly));
         },
         set readOnly(readOnly) {
             this._readOnly = readOnly;
-            // Use this.readOnly so we can _considerReadOnly
-            getFields(this).forEach((f) => (f.readOnly = this.readOnly));
         },
         get valid() {
             return getFields(this).every((f) => f.valid);
@@ -197,8 +198,6 @@ function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, is
     const field = {
         key,
         touched: false,
-        /** Configuration readOnly state. Mostly used to determine original state. */
-        _configReadOnly: readOnly,
         /** Current readOnly value. */
         _readOnly: readOnly || false,
         _focused: false,
@@ -219,25 +218,13 @@ function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, is
         get dirty() {
             return !areEqual(this.originalValue, this.value);
         },
+        /** Returns whether this field is readOnly, although if our parent is readOnly then it trumps. */
         get readOnly() {
-            return this._readOnly;
+            return parentState().readOnly || this._readOnly;
         },
-        /**
-         * Field readOnly is only opinionated when set.
-         * - When set to true from FormObject, accept change since true is higher priority.
-         * - When set to false from FormObject, use original (`_configReadOnly`) value.
-         */
+        /** Sets the field readOnly, but `v` will still be or-d with the parent's readOnly state. */
         set readOnly(v) {
-            if (this._configReadOnly === undefined) {
-                this._readOnly = v;
-                return;
-            }
-            if (v) {
-                this._readOnly = v;
-            }
-            else {
-                this._readOnly = this._configReadOnly || false;
-            }
+            this._readOnly = v;
         },
         // For primitive fields, the changed value is just the value.
         get changedValue() {
@@ -356,11 +343,10 @@ function newListFieldState(parentInstance, parentState, key, rules, listConfig,
         _focused: false,
         _readOnly: false,
         get readOnly() {
-            return this._readOnly;
+            return this._readOnly || parentState().readOnly;
         },
         set readOnly(readOnly) {
             this._readOnly = readOnly;
-            this.rows.forEach((r) => (r.readOnly = readOnly));
         },
         set value(v) {
             this.set(v);
@@ -401,7 +387,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, maybeAutoSave);
+                    childState = newObjectState(config, parentState, list, child, undefined, maybeAutoSave);
                     rowMap.set(child, childState);
                 }
                 return childState;

package/dist/formState.test.js

@@ -686,6 +686,42 @@ describe("formState", () => {
         // Then expect form
         expect(formState.title.readOnly).toBeTruthy();
     });
+    it("has an object-level readOnly=true override field-level readOnly=false", () => {
+        // Given a top-level object
+        const a1 = createAuthorInputState({
+            firstName: "a1",
+            lastName: "aL1",
+            books: [{ title: "b1", classification: formStateDomain_1.dd100 }],
+        });
+        // And it is read-only
+        a1.readOnly = true;
+        // Then it's fields are read-only
+        const fields = [a1, a1.firstName, a1.books, a1.books.rows[0].title, a1.books.rows[0].classification];
+        fields.forEach((f) => expect(f.readOnly).toBeTruthy());
+        // And even if a specific field tries to _not_ be read-only,
+        // i.e. due to a more granular business rule that happens to
+        // be allowed right now
+        a1.firstName.readOnly = false;
+        // Then the field-level rule is ignored, and it's still treated as read-only
+        expect(a1.firstName.readOnly).toBeTruthy();
+    });
+    it("has an field-level readOnly=true override object-level readOnly=false", () => {
+        // Given a top-level object
+        const a1 = createAuthorInputState({
+            firstName: "a1",
+            lastName: "aL1",
+            books: [{ title: "b1", classification: formStateDomain_1.dd100 }],
+        });
+        // And the top-level form is explicitly set to read-only=false
+        a1.readOnly = false;
+        // Then it's fields are not read-only
+        const fields = [a1, a1.firstName, a1.books, a1.books.rows[0].title, a1.books.rows[0].classification];
+        fields.forEach((f) => expect(f.readOnly).toBeFalsy());
+        // But when one of the fields opts in to readOnly
+        a1.firstName.readOnly = true;
+        // Then the field-level rule is respected
+        expect(a1.firstName.readOnly).toBeTruthy();
+    });
     it("canSave returns dirty and touches", () => {
         const a1 = formState_1.createObjectState({
             firstName: { type: "value", rules: [formState_1.required] },

package/dist/useFormState.js

@@ -12,7 +12,6 @@ let isAutoSaving = false;
 // `pendingAutoSave` is a flag for determining if we need to immediately call `maybeAutoSave` again after the initial Promise finishes
 // This could happen if a field triggers auto-save while another field's auto-save is already in progress.
 let pendingAutoSave = false;
-let timerId;
 /**
  * Creates a formState instance for editing in a form.
  */
@@ -39,7 +38,7 @@ function useFormState(opts) {
             if (autoSaveRef.current && form.dirty && form.valid && !isAutoSaving) {
                 isAutoSaving = "queued";
                 // We use setTimeout as a cheap way to wait until the end of the current event listener
-                timerId = setTimeout(async () => {
+                setTimeout(async () => {
                     try {
                         // We technically don't flip to in-flight until after the call in case the
                         // user's autoSave function itself wants to call a .set.

package/dist/useFormState.test.js

@@ -3,8 +3,10 @@ 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 mobx_1 = require("mobx");
 const mobx_react_1 = require("mobx-react");
 const react_2 = require("react");
+const FormStateApp_1 = require("./FormStateApp");
 const formState_1 = require("./formState");
 const useFormState_1 = require("./useFormState");
 describe("useFormState", () => {
@@ -425,6 +427,33 @@ describe("useFormState", () => {
         expect(autoSaveStub).toBeCalledWith({ id: "a:1", firstName: "Foo" });
         expect(autoSaveStub).toBeCalledWith({ id: "a:1", lastName: "Bar" });
     });
+    it("calls autoSave with results of calculations in addRules", async () => {
+        const autoSaveStub = jest.fn();
+        const config = {
+            id: { type: "value" },
+            firstName: { type: "value" },
+            lastName: { type: "value" },
+        };
+        // Given a component that is using autoSave
+        function TestComponent() {
+            const fs = useFormState_1.useFormState({
+                config,
+                addRules(fs) {
+                    // And also has calculated values
+                    mobx_1.reaction(() => fs.firstName.value, (curr) => (fs.lastName.value = curr));
+                },
+                autoSave: (fs) => autoSaveStub(fs.changedValue),
+                init: { id: "a:1" },
+            });
+            return jsx_runtime_1.jsx(FormStateApp_1.TextField, { field: fs.firstName }, void 0);
+        }
+        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
+        // When the user sets one field
+        await rtl_utils_1.typeAndWait(r.firstName, "first");
+        // Then we only called autoSave once
+        expect(autoSaveStub).toBeCalledTimes(1);
+        expect(autoSaveStub).toBeCalledWith({ id: "a:1", firstName: "first", lastName: "first" });
+    });
 });
 const authorConfig = {
     id: { type: "value" },

package/dist/useFormStates.d.ts

@@ -34,8 +34,15 @@ declare type UseFormStatesOpts<T, I> = {
      * Does not need to be stable/useMemo'd.
      */
     map?: (input: Exclude<I, null | undefined>) => T;
+    /**
+     * Sets all `ObjectState`s to readOnly.
+     */
+    readOnly?: boolean;
 };
-export declare function useFormStates<T, I>(opts: UseFormStatesOpts<T, I>): {
-    getFormState: (input: I) => ObjectState<T>;
+declare type UseFormStatesHook<T, I> = {
+    getFormState: (input: I, opts?: {
+        readOnly?: boolean;
+    }) => ObjectState<T>;
 };
+export declare function useFormStates<T, I = T>(opts: UseFormStatesOpts<T, I>): UseFormStatesHook<T, I>;
 export {};

package/dist/useFormStates.js

@@ -5,37 +5,48 @@ const react_1 = require("react");
 const formState_1 = require("./formState");
 const utils_1 = require("./utils");
 function useFormStates(opts) {
-    const { config, autoSave, getId, map, addRules } = opts;
+    const { config, autoSave, getId, map, addRules, readOnly = false } = opts;
     const objectStateCache = react_1.useMemo(() => ({}), 
     // Force resetting the cache if config changes
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [config]);
     // Keep track of ObjectStates that triggered auto-save when a save was already in progress.
-    const pendingAutoSaves = react_1.useRef([]);
+    const pendingAutoSaves = react_1.useRef(new Set());
     // Use a ref so our memo'ized `autoSave` always see the latest value
     const autoSaveRef = react_1.useRef(autoSave);
     autoSaveRef.current = autoSave;
-    async function maybeAutoSave(form) {
-        if (isAutoSaving && !pendingAutoSaves.current.includes(form)) {
-            pendingAutoSaves.current.push(form);
-        }
-        // 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;
-                await autoSaveRef.current(form);
-            }
-            finally {
-                isAutoSaving = false;
-                if (pendingAutoSaves.current.length > 0) {
-                    await maybeAutoSave(pendingAutoSaves.current.shift());
+    // Use a ref b/c we're memod
+    const readOnlyRef = react_1.useRef(readOnly);
+    readOnlyRef.current = readOnly;
+    const getFormState = react_1.useCallback((input, opts = {}) => {
+        const existing = objectStateCache[getId(input)];
+        let form = existing === null || existing === void 0 ? void 0 : existing[0];
+        async function maybeAutoSave(form) {
+            // Don't use canSave() because we don't want to set touched for all the fields
+            if (autoSaveRef.current && form.dirty && form.valid) {
+                const { current: pending } = pendingAutoSaves;
+                if (isAutoSaving) {
+                    pending.add(form);
+                    return;
+                }
+                try {
+                    isAutoSaving = true;
+                    // 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);
+                }
+                finally {
+                    isAutoSaving = false;
+                    if (pending.size > 0) {
+                        const first = pending.values().next().value;
+                        pending.delete(first);
+                        await maybeAutoSave(first);
+                    }
                 }
             }
         }
-    }
-    const getFormState = react_1.useCallback((input) => {
-        const existing = objectStateCache[getId(input)];
-        let form = existing === null || existing === void 0 ? void 0 : existing[0];
         // If it didn't exist, then add to the cache.
         if (!form) {
             form = formState_1.createObjectState(config, utils_1.initValue(config, map ? { map, input } : input), {
@@ -51,6 +62,7 @@ function useFormStates(opts) {
             form.set(utils_1.initValue(config, map ? { map, input } : input), { refreshing: true });
             existing[1] = input;
         }
+        form.readOnly = readOnlyRef.current || !!opts.readOnly;
         return form;
     }, 
     // Allow the user to not stable-ize getId, map, addRules, and autoSave

package/dist/useFormStates.test.js

@@ -2,8 +2,10 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 const jsx_runtime_1 = require("react/jsx-runtime");
 const rtl_utils_1 = require("@homebound/rtl-utils");
+const mobx_1 = require("mobx");
 const react_1 = require("react");
 const formState_1 = require("./formState");
+const FormStateApp_1 = require("./FormStateApp");
 const useFormStates_1 = require("./useFormStates");
 describe("useFormStates", () => {
     it("can lazily create form states", async () => {
@@ -99,10 +101,9 @@ describe("useFormStates", () => {
         rtl_utils_1.click(r.focusSetAndSaveField2());
         // Awaits the promises for all methods triggered above
         await rtl_utils_1.wait();
-        // Then expect the auto save to only have been called three times. Once with each set of changedValues.
-        expect(autoSaveStub).toBeCalledTimes(3);
-        expect(autoSaveStub).toBeCalledWith({ id: "a:1", firstName: "Foo" });
-        expect(autoSaveStub).toBeCalledWith({ id: "a:1", lastName: "Bar" });
+        // Then expect the auto save to only have been called two times. Once with each set of changedValues.
+        expect(autoSaveStub).toBeCalledTimes(2);
+        expect(autoSaveStub).toBeCalledWith({ id: "a:1", firstName: "Foo", lastName: "Bar" });
         expect(autoSaveStub).toBeCalledWith({ id: "a:2", lastName: "Bar" });
     });
     it("clears out cache if configuration changes", async () => {
@@ -151,7 +152,78 @@ describe("useFormStates", () => {
         // Then addRules was only called once
         expect(addRules).toHaveBeenCalledTimes(1);
     });
+    it("calls autoSave with results of calculations in addRules", async () => {
+        // Given a user wants to use auto save
+        const autoSave = jest.fn();
+        function TestComponent() {
+            const { getFormState } = useFormStates_1.useFormStates({
+                config,
+                getId: (o) => o.id,
+                addRules(fs) {
+                    // And they have a reactive true that calculates last name
+                    mobx_1.reaction(() => fs.firstName.value, (curr) => {
+                        fs.lastName.set(curr);
+                    });
+                },
+                async autoSave(fs) {
+                    autoSave(fs.changedValue);
+                },
+            });
+            return jsx_runtime_1.jsx(FormStateApp_1.TextField, { field: getFormState({ id: "a:1", firstName: "Brandon" }).firstName }, void 0);
+        }
+        // When we render
+        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
+        // And update the firstName
+        await rtl_utils_1.typeAndWait(r.firstName(), "first");
+        // Then autoSave was called once with both input+calc'd values
+        expect(autoSave).toHaveBeenCalledTimes(1);
+        expect(autoSave).toHaveBeenCalledWith({ id: "a:1", firstName: "first", lastName: "first" });
+    });
+    it("can set readOnly via the hook opt", async () => {
+        // Given a test component
+        function TestComponent({ readOnly }) {
+            const { getFormState } = useFormStates_1.useFormStates({
+                config,
+                getId: (o) => o.id,
+                // And it passes readOnly directly to useFormStates
+                readOnly,
+            });
+            return jsx_runtime_1.jsx(ChildComponent, { os: getFormState({ id: "a:1", firstName: "Brandon" }) }, void 0);
+        }
+        // When we render
+        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, { readOnly: true }, void 0));
+        // Then it's read only
+        expect(r.firstName()).toHaveAttribute("data-readonly", "true");
+        // And when we rerender
+        await r.rerender(jsx_runtime_1.jsx(TestComponent, { readOnly: false }, void 0));
+        // Then it's not read only
+        expect(r.firstName()).toHaveAttribute("data-readonly", "false");
+    });
+    it("can set readOnly via the getFormState function", async () => {
+        // Given a test component
+        function TestComponent({ readOnly }) {
+            const { getFormState } = useFormStates_1.useFormStates({
+                config,
+                getId: (o) => o.id,
+            });
+            // And it passes readOnly directly to getFormState
+            return jsx_runtime_1.jsx(ChildComponent, { os: getFormState({ id: "a:1", firstName: "Brandon" }, { readOnly }) }, void 0);
+        }
+        // When we render
+        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, { readOnly: true }, void 0));
+        // Then it's read only
+        expect(r.firstName()).toHaveAttribute("data-readonly", "true");
+        // And when we rerender
+        await r.rerender(jsx_runtime_1.jsx(TestComponent, { readOnly: false }, void 0));
+        // Then it's not read only
+        expect(r.firstName()).toHaveAttribute("data-readonly", "false");
+    });
 });
+const config = {
+    id: { type: "value" },
+    firstName: { type: "value" },
+    lastName: { type: "value" },
+};
 function ChildComponent({ os }) {
-    return jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "firstName" }, { children: os.firstName.value }), void 0);
+    return (jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "firstName", "data-readonly": os.firstName.readOnly }, { children: os.firstName.value }), void 0));
 }

package/package.json

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