@homebound/form-state 2.11.0 → 2.12.0

package/dist/useFormState.d.ts

@@ -1,5 +1,20 @@
 import { ObjectConfig } from "./config";
 import { ObjectState } from "./fields/objectField";
+export declare type Query<I> = {
+    data: I;
+    loading: boolean;
+    error?: any;
+};
+export declare type InputAndMap<T, I> = {
+    input: I;
+    map: (input: Exclude<I, null | undefined>) => T;
+    ifUndefined?: T;
+};
+export declare type QueryAndMap<T, I> = {
+    query: Query<I>;
+    map: (input: Exclude<I, null | undefined>) => T;
+    ifUndefined?: T;
+};
 export declare type UseFormStateOpts<T, I> = {
     /** The form configuration, should be a module-level const or useMemo'd. */
     config: ObjectConfig<T>;
@@ -20,11 +35,7 @@ export declare type UseFormStateOpts<T, I> = {
      * only call `init.map` if it's set, otherwise we'll use `init.ifDefined` or `{}`, saving you
      * from having to null check within your `init.map` function.
      */
-    init?: T | {
-        input: I;
-        map: (input: Exclude<I, null | undefined>) => T;
-        ifUndefined?: T;
-    };
+    init?: T | InputAndMap<T, I> | QueryAndMap<T, I>;
     /**
      * A hook to add custom, cross-field validation rules that can be difficult to setup directly in the config DSL.
      *
@@ -33,6 +44,13 @@ export declare type UseFormStateOpts<T, I> = {
     addRules?: (state: ObjectState<T>) => void;
     /** Whether the form should be read only, when changed it won't re-create the whole form. */
     readOnly?: boolean;
+    /**
+     * Whether the form is loading.
+     *
+     * Note that we also will infer loading from `init.input === undefined` or `init.query.loading`,
+     * so you only need to set this directly if you're not using either of those conventions.
+     */
+    loading?: boolean;
     /**
      * Fired when the form should auto-save, i.e. after a) blur and b) all fields are valid.
      *

package/dist/useFormState.js

@@ -16,7 +16,7 @@ let pendingAutoSave = false;
  * Creates a formState instance for editing in a form.
  */
 function useFormState(opts) {
-    const { config, init, addRules, readOnly = false, autoSave } = opts;
+    const { config, init, addRules, readOnly = false, loading, autoSave } = opts;
     // Use a ref so our memo'ized `onBlur` always see the latest value
     const autoSaveRef = react_1.useRef(autoSave);
     autoSaveRef.current = autoSave;
@@ -25,7 +25,7 @@ function useFormState(opts) {
     const [firstInitValue] = react_1.useState(() => utils_1.initValue(config, init));
     const isWrappingMobxProxy = !is_plain_object_1.isPlainObject(firstInitValue);
     // If they're using init.input, useMemo on it (and it might be an array), otherwise allow the identity of init be unstable
-    const dep = init && "input" in init && "map" in init ? (Array.isArray(init.input) ? init.input : [init.input]) : [];
+    const dep = utils_1.isInput(init) ? makeArray(init.input) : utils_1.isQuery(init) ? [init.query.data, init.query.loading] : [];
     const form = react_1.useMemo(() => {
         function maybeAutoSave() {
             if (isAutoSaving === "in-flight") {
@@ -62,9 +62,7 @@ function useFormState(opts) {
         const value = firstRunRef.current ? firstInitValue : utils_1.initValue(config, init);
         const form = objectField_1.createObjectState(config, value, { maybeAutoSave });
         form.readOnly = readOnly;
-        if (init && "input" in init && !("ifUndefined" in init)) {
-            form.loading = init.input === undefined;
-        }
+        setLoading(form, opts);
         // The identity of `addRules` is not stable, but assume that it is for better UX.
         (addRules || (() => { }))(form);
         firstRunRef.current = true;
@@ -83,15 +81,34 @@ function useFormState(opts) {
             firstRunRef.current = false;
             return;
         }
-        if (init && "input" in init && !("ifUndefined" in init)) {
-            form.loading = init.input === undefined;
-        }
+        setLoading(form, opts);
         form.set(utils_1.initValue(config, init), { refreshing: true });
     }, [form, ...dep]);
     // Use useEffect so that we don't touch the form.init proxy during a render
     react_1.useEffect(() => {
         form.readOnly = readOnly;
-    }, [form, readOnly]);
+        if (loading !== undefined) {
+            form.loading = loading;
+        }
+    }, [form, readOnly, loading]);
     return form;
 }
 exports.useFormState = useFormState;
+function setLoading(form, opts) {
+    const { loading, init } = opts;
+    if (loading !== undefined) {
+        // Prefer the explicit/top-level opts.loading if it's set
+        form.loading = loading;
+    }
+    else if (utils_1.isInput(init) && !init.ifUndefined) {
+        // Otherwise, check for `init.input`
+        form.loading = init.input === undefined;
+    }
+    else if (utils_1.isQuery(init)) {
+        // Or `query.loading`
+        form.loading = init.query.loading;
+    }
+}
+function makeArray(input) {
+    return Array.isArray(input) ? input : [input];
+}

package/dist/useFormState.test.js

@@ -454,6 +454,21 @@ describe("useFormState", () => {
         expect(autoSaveStub).toBeCalledTimes(1);
         expect(autoSaveStub).toBeCalledWith({ id: "a:1", firstName: "first", lastName: "first" });
     });
+    it("sets loading if opts.loading is true", async () => {
+        const config = { firstName: { type: "value" } };
+        function TestComponent({ loading }) {
+            const form = useFormState_1.useFormState({ config, loading });
+            return jsx_runtime_1.jsx(mobx_react_1.Observer, { children: () => jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "loading" }, { children: String(form.loading) }), void 0) }, void 0);
+        }
+        // And we initially pass in `init.query.loading: true`
+        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, { loading: true }, void 0));
+        // Then the form is marked as loading
+        expect(r.loading()).toHaveTextContent("true");
+        // And when the query is not loading
+        await r.rerender(jsx_runtime_1.jsx(TestComponent, { loading: false }, void 0));
+        // Then the form is marked as not loading
+        expect(r.loading()).toHaveTextContent("false");
+    });
     it("sets loading if input.data is undefined", async () => {
         const config = { firstName: { type: "value" } };
         function TestComponent({ data }) {
@@ -464,11 +479,26 @@ describe("useFormState", () => {
         const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, { data: undefined }, void 0));
         // Then the form is marked as loading
         expect(r.loading()).toHaveTextContent("true");
-        // And when the data is loading
+        // And when the data is no longer undefined
         await r.rerender(jsx_runtime_1.jsx(TestComponent, { data: { firstName: "first" } }, void 0));
         // Then the form is marked as not loading
         expect(r.loading()).toHaveTextContent("false");
     });
+    it("sets loading if query.loading is true", async () => {
+        const config = { firstName: { type: "value" } };
+        function TestComponent({ loading, data }) {
+            const form = useFormState_1.useFormState({ config, init: { query: { data, loading, error: null }, map: (d) => d } });
+            return jsx_runtime_1.jsx(mobx_react_1.Observer, { children: () => jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "loading" }, { children: String(form.loading) }), void 0) }, void 0);
+        }
+        // And we initially pass in `init.query.loading: true`
+        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, { loading: true, data: undefined }, void 0));
+        // Then the form is marked as loading
+        expect(r.loading()).toHaveTextContent("true");
+        // And when the query is not loading
+        await r.rerender(jsx_runtime_1.jsx(TestComponent, { loading: false, data: { firstName: "first" } }, void 0));
+        // Then the form is marked as not loading
+        expect(r.loading()).toHaveTextContent("false");
+    });
 });
 const authorConfig = {
     id: { type: "value" },

package/dist/utils.d.ts

@@ -1,4 +1,5 @@
 import { ObjectConfig } from "./config";
+import { InputAndMap, QueryAndMap, UseFormStateOpts } from "./useFormState";
 export declare type Builtin = Date | Function | Uint8Array | string | number | boolean;
 export declare type Primitive = undefined | null | boolean | string | number | Function | Date | {
     toJSON(): any;
@@ -11,6 +12,8 @@ export declare function fail(message?: string): never;
 export declare function assertNever(x: never): never;
 /** Introspects the `init` prop to see if has a `map` function/etc. and returns the form value. */
 export declare function initValue<T>(config: ObjectConfig<T>, init: any): T;
+export declare function isInput<T, I>(init: UseFormStateOpts<T, I>["init"]): init is InputAndMap<T, I>;
+export declare function isQuery<T, I>(init: UseFormStateOpts<T, I>["init"]): init is QueryAndMap<T, I>;
 /**
  * Picks ony fields out of `instance` that are in the `formConfig`.
  *

package/dist/utils.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.hasToJSON = exports.areEqual = exports.isEmpty = exports.isNotUndefined = exports.pickFields = exports.initValue = exports.assertNever = exports.fail = void 0;
+exports.hasToJSON = exports.areEqual = exports.isEmpty = exports.isNotUndefined = exports.pickFields = exports.isQuery = exports.isInput = exports.initValue = exports.assertNever = exports.fail = void 0;
 const fast_deep_equal_1 = __importDefault(require("fast-deep-equal"));
 const is_plain_object_1 = require("is-plain-object");
 const mobx_1 = require("mobx");
@@ -17,14 +17,27 @@ function assertNever(x) {
 exports.assertNever = assertNever;
 /** Introspects the `init` prop to see if has a `map` function/etc. and returns the form value. */
 function initValue(config, init) {
-    const initValue = init && "input" in init && "map" in init
-        ? init.input
-            ? init.map(init.input)
-            : init.ifUndefined || {}
-        : init || {};
-    return pickFields(config, initValue);
+    let value;
+    if (isInput(init)) {
+        value = init.input ? init.map(init.input) : init.ifUndefined;
+    }
+    else if (isQuery(init)) {
+        value = init.query.data ? init.map(init.query.data) : init.ifUndefined;
+    }
+    else {
+        value = init;
+    }
+    return pickFields(config, value !== null && value !== void 0 ? value : {});
 }
 exports.initValue = initValue;
+function isInput(init) {
+    return !!init && "input" in init && "map" in init;
+}
+exports.isInput = isInput;
+function isQuery(init) {
+    return !!init && "query" in init && "map" in init;
+}
+exports.isQuery = isQuery;
 /**
  * Picks ony fields out of `instance` that are in the `formConfig`.
  *

package/package.json

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