@homebound/form-state 2.2.8 → 2.2.12

package/dist/formState.test.js

@@ -1,10 +1,6 @@
 "use strict";
 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 mobx_react_1 = require("mobx-react");
-const react_1 = require("react");
 const formStateDomain_1 = require("./formStateDomain");
 const formState_1 = require("./formState");
 describe("formState", () => {
@@ -117,6 +113,19 @@ describe("formState", () => {
         expect(state.books.rows[2].originalValue === b1).toEqual(true);
         expect(ticks).toEqual(3);
     });
+    it("list value can observe changes", () => {
+        const b1 = { title: "t1" };
+        const a1 = { firstName: "a1", books: [b1] };
+        const state = createAuthorInputState(a1);
+        let books;
+        let ticks = 0;
+        mobx_1.autorun(() => {
+            books = state.books.value;
+            ticks++;
+        });
+        state.books.add({ title: "t2" }, 0);
+        expect(ticks).toEqual(2);
+    });
     it("maintains unknown fields", () => {
         // Given the form is not directly editing id fields
         const config = {
@@ -321,7 +330,7 @@ describe("formState", () => {
         a1.books.remove(0);
         expect(a1.dirty).toBeFalsy();
     });
-    it("it calls onBlur when adding or removing to a list", () => {
+    it("calls onBlur when adding or removing to a list", () => {
         const onBlur = jest.fn();
         const a1 = createAuthorInputState({ books: [] }, onBlur);
         expect(a1.books.dirty).toBeFalsy();
@@ -331,6 +340,60 @@ describe("formState", () => {
         expect(a1.dirty).toBeFalsy();
         expect(onBlur).toBeCalledTimes(2);
     });
+    it("calls onBlur when programmatically setting a value", () => {
+        const onBlur = jest.fn();
+        // Given an author listening for blur
+        const a1 = createAuthorInputState({ books: [{}] }, onBlur);
+        // When we programmatically set a field that isn't focused
+        a1.firstName.value = "first";
+        // Then we call onBlur
+        expect(onBlur).toBeCalledTimes(1);
+        // And when we set a nested value
+        a1.books.rows[0].title.value = "title";
+        // Then we called onBlur again
+        expect(onBlur).toBeCalledTimes(2);
+    });
+    it("defers calling onBlur when setting a bound value", () => {
+        const onBlur = jest.fn();
+        // Given an author listening for blur
+        const a1 = createAuthorInputState({ books: [{}] }, onBlur);
+        // And the field is focused
+        a1.firstName.focus();
+        // When we we set the field
+        a1.firstName.value = "first";
+        // Then we don't call onBlur
+        expect(onBlur).toBeCalledTimes(0);
+    });
+    it("skips onBlur when refreshing", () => {
+        const onBlur = jest.fn();
+        // Given an author listening for blur
+        const a1 = createAuthorInputState({ books: [{}] }, onBlur);
+        // When we programmatically set a field that isn't focused
+        a1.set({ firstName: "first" }, { refreshing: true });
+        // Then we don't call onBlur
+        expect(onBlur).toBeCalledTimes(0);
+    });
+    it("skips onBlur when resetting", () => {
+        const onBlur = jest.fn();
+        // Given an author listening for blur
+        const a1 = createAuthorInputState({ books: [{}] }, onBlur);
+        // And we called onBlur once
+        a1.set({ firstName: "first" });
+        expect(onBlur).toBeCalledTimes(1);
+        // When we reset
+        a1.reset();
+        // We don't call blur again
+        expect(onBlur).toBeCalledTimes(1);
+    });
+    it("skips onBlur when not dirty", () => {
+        const onBlur = jest.fn();
+        // Given an author listening for blur
+        const a1 = createAuthorInputState({ firstName: "first", books: [{}] }, onBlur);
+        // When we programmatically set a field to it's existing valued
+        a1.firstName.value = "first";
+        // Then we don't call onBlur
+        expect(onBlur).toBeCalledTimes(0);
+    });
     it("knows list of primitives are dirty", () => {
         const a1 = formState_1.createObjectState({ favoriteColors: { type: "value" } }, {});
         expect(a1.favoriteColors.dirty).toBeFalsy();
@@ -654,74 +717,6 @@ describe("formState", () => {
       }
     `);
     });
-    it("can pick a value field", () => {
-        const a = formState_1.pickFields(
-        //
-        { firstName: { type: "value" } }, { firstName: "a", b: "ignored" });
-        expect(a).toMatchInlineSnapshot(`
-      Object {
-        "firstName": "a",
-      }
-    `);
-    });
-    it("can pick an unset object fields", () => {
-        const a = formState_1.pickFields(authorWithAddressConfig, { firstName: "a", b: "ignored" });
-        expect(a).toMatchInlineSnapshot(`
-      Object {
-        "address": undefined,
-        "firstName": "a",
-        "id": undefined,
-        "lastName": undefined,
-      }
-    `);
-    });
-    it("can pick a set object field", () => {
-        const a = formState_1.pickFields(authorWithAddressConfig, { firstName: "a", b: "ignored", address: {} });
-        expect(a).toMatchInlineSnapshot(`
-      Object {
-        "address": Object {
-          "city": undefined,
-          "street": undefined,
-        },
-        "firstName": "a",
-        "id": undefined,
-        "lastName": undefined,
-      }
-    `);
-    });
-    it("can pick an unset list field", () => {
-        const a = formState_1.pickFields(authorWithBooksConfig, { firstName: "a", b: "ignored" });
-        expect(a).toMatchInlineSnapshot(`
-      Object {
-        "books": undefined,
-        "firstName": "a",
-        "id": undefined,
-        "lastName": undefined,
-      }
-    `);
-    });
-    it("can pick a set list field", () => {
-        const a = formState_1.pickFields(authorWithBooksConfig, { firstName: "a", b: "ignored", books: [{}] });
-        expect(a).toMatchInlineSnapshot(`
-      Object {
-        "books": Array [
-          Object {
-            "classification": undefined,
-            "id": undefined,
-            "title": undefined,
-          },
-        ],
-        "firstName": "a",
-        "id": undefined,
-        "lastName": undefined,
-      }
-    `);
-    });
-    it("can pick a set observable list field", () => {
-        const books = mobx_1.observable([]);
-        const a = formState_1.pickFields(authorWithBooksConfig, { firstName: "a", b: "ignored", books });
-        expect(mobx_1.isObservable(a.books)).toEqual(true);
-    });
     it("can wrap an existing list observable", () => {
         // Given an array observable that is already created
         const b1 = { title: "b1" };
@@ -951,6 +946,7 @@ describe("formState", () => {
     it("trims string values on blur", () => {
         const formState = formState_1.createObjectState(authorWithBooksConfig, { firstName: "f", lastName: "l" });
         // Given the user is typing with spaces
+        formState.firstName.focus();
         formState.firstName.set("f ");
         // And we initially keep the space
         expect(formState.firstName.value).toEqual("f ");
@@ -962,6 +958,7 @@ describe("formState", () => {
     it("trims empty values to undefined on blur", () => {
         const formState = formState_1.createObjectState(authorWithBooksConfig, { firstName: "f", lastName: "l" });
         // Given the user is typing with only spaces
+        formState.firstName.focus();
         formState.firstName.set(" ");
         // And we initially keep the space
         expect(formState.firstName.value).toEqual(" ");
@@ -1013,113 +1010,6 @@ describe("formState", () => {
         a.address.set({ street: "123", city: "nyc" });
         expect(a.value).toEqual({ address: { street: "123", city: "nyc" } });
     });
-    it("calls init.map if init.input is defined", async () => {
-        // Given a component
-        function TestComponent() {
-            const config = { firstName: { type: "value" } };
-            // And we have query data that may or may not be defined
-            const data = Math.random() >= 0 ? { firstName: "bob" } : undefined;
-            // Then the lambda is passed the "de-undefined" data
-            const form = formState_1.useFormState({
-                config,
-                init: { input: data, map: (d) => ({ firstName: d.firstName }) },
-            });
-            return jsx_runtime_1.jsx("div", { children: form.firstName.value }, void 0);
-        }
-        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
-        expect(r.baseElement).toHaveTextContent("bob");
-    });
-    it("memoizes on init.input being an array", async () => {
-        const config = { firstName: { type: "value" } };
-        function TestComponent() {
-            const [, setTick] = react_1.useState(0);
-            const form = formState_1.useFormState({
-                config,
-                init: { input: ["a", "b"], map: ([a, b]) => ({ firstName: a + b }) },
-            });
-            const onClick = () => [form.firstName.set("fred"), setTick(1)];
-            return (jsx_runtime_1.jsxs("div", { children: [jsx_runtime_1.jsx("button", { "data-testid": "change", onClick: onClick }, void 0),
-                    jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "firstName" }, { children: form.firstName.value }), void 0)] }, void 0));
-        }
-        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
-        expect(r.firstName()).toHaveTextContent("ab");
-        rtl_utils_1.click(r.change);
-        expect(r.firstName()).toHaveTextContent("fred");
-    });
-    it("uses default if init.input is undefined", async () => {
-        // Given a component
-        function TestComponent() {
-            const config = { firstName: { type: "value" } };
-            // And we have query data that may or may not be defined (but is actually undefined)
-            const data = Math.random() >= 0 ? undefined : { firstName: "bob" };
-            const form = formState_1.useFormState({
-                config,
-                init: { input: data, map: (d) => ({ firstName: d.firstName }) },
-            });
-            return jsx_runtime_1.jsx("div", { children: form.firstName.value }, void 0);
-        }
-        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
-        // Then we init.map wasn't called, and we used {} instead
-        expect(r.baseElement.textContent).toEqual("");
-    });
-    it("uses custom init.ifUndefined if init.input is undefined", async () => {
-        // Given a component
-        function TestComponent() {
-            const config = {
-                id: { type: "value" },
-                firstName: { type: "value" },
-            };
-            // And we have query data that may or may not be defined (but is actually undefined)
-            const data = Math.random() >= 0 ? undefined : { firstName: "bob" };
-            const form = formState_1.useFormState({
-                config,
-                // And we pass `ifUndefined`
-                init: {
-                    input: data,
-                    map: (d) => ({ firstName: d.firstName }),
-                    ifUndefined: { firstName: "default" },
-                },
-            });
-            return (jsx_runtime_1.jsxs("div", { children: [jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "firstName" }, { children: form.firstName.value }), void 0),
-                    jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "changedValue" }, { children: JSON.stringify(form.changedValue) }), void 0)] }, void 0));
-        }
-        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
-        // Then we use the ifUndefined value
-        expect(r.firstName.textContent).toEqual("default");
-        expect(r.changedValue.textContent).toEqual(JSON.stringify({ firstName: "default" }));
-    });
-    it("uses init if set as a value", async () => {
-        const config = { firstName: { type: "value" } };
-        function TestComponent() {
-            const [, setTick] = react_1.useState(0);
-            const form = formState_1.useFormState({
-                config,
-                // That's using a raw init value
-                init: { firstName: "bob" },
-            });
-            return (jsx_runtime_1.jsxs("div", { children: [jsx_runtime_1.jsx("button", { "data-testid": "change", onClick: () => {
-                            // When that value changes
-                            form.firstName.set("fred");
-                            // And also we re-render the component
-                            setTick(1);
-                        } }, void 0),
-                    jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "firstName" }, { children: form.firstName.value }), void 0)] }, void 0));
-        }
-        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
-        expect(r.firstName()).toHaveTextContent("bob");
-        rtl_utils_1.click(r.change);
-        // Then the change didn't get dropped due to init being unstable
-        expect(r.firstName()).toHaveTextContent("fred");
-    });
-    it("doesn't required an init value", async () => {
-        function TestComponent() {
-            const config = { firstName: { type: "value" } };
-            const form = formState_1.useFormState({ config });
-            return jsx_runtime_1.jsx("div", { children: form.firstName.value }, void 0);
-        }
-        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
-        expect(r.baseElement.textContent).toEqual("");
-    });
     it("provides isNewEntity", () => {
         // Given an author without an id
         const formState = formState_1.createObjectState(authorWithAddressConfig, {
@@ -1171,218 +1061,6 @@ describe("formState", () => {
         expect(formState.books.rows[1].isNewEntity).toBeTruthy();
         expect(formState.books.isNewEntity).toBeFalsy();
     });
-    it("keeps local changed values when a query refreshes", async () => {
-        // Given a component
-        function TestComponent() {
-            const config = authorWithAddressAndBooksConfig;
-            // And we have two sets of data
-            const data1 = {
-                id: "a:1",
-                firstName: "f1",
-                lastName: "l1",
-                address: { id: "address:1", street: "s1", city: "c1" },
-                books: [
-                    { id: "b:1", title: "a1" },
-                    { id: "b:2", title: "b1" },
-                ],
-            };
-            const data2 = {
-                id: "a:1",
-                firstName: "f2",
-                lastName: "l2",
-                address: { id: "address:1", street: "s2", city: "c2" },
-                books: [
-                    { id: "b:1", title: "a2" },
-                    { id: "b:2", title: "b2" },
-                    { id: "b:3", title: "b3" },
-                ],
-            };
-            // Eventually our local values are saved
-            const data3 = {
-                id: "a:1",
-                firstName: "local",
-                lastName: "l2",
-                address: { id: "address:1", street: "local", city: "c2" },
-                books: [
-                    { id: "b:1", title: "local" },
-                    { id: "b:2", title: "b2" },
-                    { id: "b:3", title: "b3" },
-                ],
-            };
-            // And we start out with data1
-            const [data, setData] = react_1.useState(data1);
-            const form = formState_1.useFormState({ config, init: { input: data, map: (d) => d } });
-            function makeLocalChanges() {
-                form.firstName.value = "local";
-                form.address.street.value = "local";
-                form.books.rows[0].title.value = "local";
-            }
-            return (jsx_runtime_1.jsx(mobx_react_1.Observer, { children: () => (jsx_runtime_1.jsxs("div", { children: [jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "firstName" }, { children: form.firstName.value }), void 0),
-                        jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "lastName" }, { children: form.lastName.value }), void 0),
-                        jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "street" }, { children: form.address.street.value }), void 0),
-                        jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "city" }, { children: form.address.city.value }), void 0),
-                        jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "title1" }, { children: form.books.rows[0].title.value }), void 0),
-                        jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "title2" }, { children: form.books.rows[1].title.value }), void 0),
-                        jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "booksLength" }, { children: form.books.rows.length }), void 0),
-                        jsx_runtime_1.jsx("button", { "data-testid": "makeLocalChanges", onClick: makeLocalChanges }, void 0),
-                        jsx_runtime_1.jsx("button", { "data-testid": "refreshData", onClick: () => setData(data2) }, void 0),
-                        jsx_runtime_1.jsx("button", { "data-testid": "saveData", onClick: () => setData(data3) }, void 0),
-                        jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "changedValue" }, { children: JSON.stringify(form.changedValue) }), void 0)] }, void 0)) }, void 0));
-        }
-        // And we start out with the initial query data
-        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
-        expect(r.firstName().textContent).toEqual("f1");
-        expect(r.street().textContent).toEqual("s1");
-        expect(r.title1().textContent).toEqual("a1");
-        // When we make some local changes
-        rtl_utils_1.click(r.makeLocalChanges);
-        // Then we see them
-        expect(r.firstName().textContent).toEqual("local");
-        expect(r.street().textContent).toEqual("local");
-        expect(r.title1().textContent).toEqual("local");
-        expect(JSON.parse(r.changedValue().textContent)).toEqual({
-            id: "a:1",
-            address: { id: "address:1", street: "local" },
-            books: [{ id: "b:1", title: "local" }, { id: "b:2" }],
-            firstName: "local",
-        });
-        // And when the new query is ran i.e. due to a cache refresh
-        rtl_utils_1.click(r.refreshData);
-        // Then we kept our local changes
-        expect(r.firstName().textContent).toEqual("local");
-        expect(r.street().textContent).toEqual("local");
-        expect(r.title1().textContent).toEqual("local");
-        // But we also see the new data for fields we have not changed
-        expect(r.lastName().textContent).toEqual("l2");
-        expect(r.city().textContent).toEqual("c2");
-        expect(r.title2().textContent).toEqual("b2");
-        expect(r.booksLength().textContent).toEqual("3");
-        expect(JSON.parse(r.changedValue().textContent)).toEqual({
-            id: "a:1",
-            address: { id: "address:1", street: "local" },
-            books: [{ id: "b:1", title: "local" }, { id: "b:2" }, { id: "b:3" }],
-            firstName: "local",
-        });
-        // And then when our mutation results come back
-        rtl_utils_1.click(r.saveData);
-        // Then changedValue doesn't show our local changes anymore
-        expect(JSON.parse(r.changedValue().textContent)).toEqual({
-            id: "a:1",
-        });
-    });
-    it("useFormState can accept new data while read only", async () => {
-        // Given a component
-        function TestComponent() {
-            const config = authorWithAddressAndBooksConfig;
-            // And we have two sets of data
-            const data1 = {
-                firstName: "f1",
-                address: { street: "s1" },
-                books: [{ title: "a1" }],
-            };
-            const data2 = {
-                firstName: "f2",
-                address: { street: "s2" },
-                books: [{ title: "a2" }],
-            };
-            // And we start out with data1
-            const [data, setData] = react_1.useState(data1);
-            const form = formState_1.useFormState({
-                config,
-                init: { input: data, map: (d) => d },
-                // And the form is read only
-                readOnly: true,
-            });
-            return (jsx_runtime_1.jsx(mobx_react_1.Observer, { children: () => (jsx_runtime_1.jsxs("div", { children: [jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "firstName" }, { children: form.firstName.value }), void 0),
-                        jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "street" }, { children: form.address.street.value }), void 0),
-                        jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "title1" }, { children: form.books.rows[0].title.value }), void 0),
-                        jsx_runtime_1.jsx("button", { "data-testid": "refreshData", onClick: () => setData(data2) }, void 0)] }, void 0)) }, void 0));
-        }
-        // And we start out with the initial query data
-        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
-        expect(r.firstName().textContent).toEqual("f1");
-        expect(r.street().textContent).toEqual("s1");
-        expect(r.title1().textContent).toEqual("a1");
-        // When the new query is ran i.e. due to a cache refresh
-        rtl_utils_1.click(r.refreshData);
-        // Then we see the latest data
-        expect(r.firstName().textContent).toEqual("f2");
-        expect(r.street().textContent).toEqual("s2");
-        expect(r.title1().textContent).toEqual("a2");
-    });
-    it("useFormState can accept new data with computed fields", async () => {
-        // Given a component
-        function TestComponent() {
-            // And it's using a class/mobx proxy as the basis for the data
-            class AuthorRow {
-                constructor(firstName, lastName) {
-                    this.firstName = firstName;
-                    this.lastName = lastName;
-                }
-                get fullName() {
-                    return this.firstName + " " + this.lastName;
-                }
-            }
-            // And we have two sets of data
-            const data1 = { firstName: "f1", lastName: "l1" };
-            const data2 = { firstName: "f2", lastName: "l2" };
-            // And we start out with data1
-            const [data, setData] = react_1.useState(data1);
-            const author = react_1.useMemo(() => new AuthorRow(data.firstName, data.lastName), [data]);
-            const config = react_1.useMemo(() => ({
-                firstName: { type: "value" },
-                lastName: { type: "value" },
-                fullName: { type: "value", computed: true },
-            }), []);
-            const form = formState_1.useFormState({ config, init: { input: author, map: (a) => a } });
-            return (jsx_runtime_1.jsx(mobx_react_1.Observer, { children: () => (jsx_runtime_1.jsxs("div", { children: [jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "firstName" }, { children: form.firstName.value }), void 0),
-                        jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "fullName" }, { children: form.fullName.value }), void 0),
-                        jsx_runtime_1.jsx("button", { "data-testid": "refreshData", onClick: () => setData(data2) }, void 0)] }, void 0)) }, void 0));
-        }
-        // And we start out with the initial query data
-        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
-        expect(r.firstName().textContent).toEqual("f1");
-        expect(r.fullName().textContent).toEqual("f1 l1");
-        // When the new query is ran i.e. due to a cache refresh
-        rtl_utils_1.click(r.refreshData);
-        expect(r.firstName().textContent).toEqual("f2");
-        expect(r.fullName().textContent).toEqual("f2 l2");
-    });
-    it("can trigger auto save for fields in list that were initially undefined", async () => {
-        const autoSave = jest.fn();
-        // Given a component
-        function TestComponent() {
-            // When the data is initially undefined
-            const [data, setData] = react_1.useState();
-            const data2 = { books: [{ title: "Title 1" }] };
-            const form = formState_1.useFormState({
-                config: authorWithBooksConfig,
-                init: { input: data, map: (d) => d, ifUndefined: { books: [] } },
-                autoSave,
-            });
-            return (jsx_runtime_1.jsx(mobx_react_1.Observer, { children: () => (jsx_runtime_1.jsxs("div", { children: [jsx_runtime_1.jsx("button", { "data-testid": "refreshData", onClick: () => setData(data2) }, void 0),
-                        jsx_runtime_1.jsx("button", { "data-testid": "add", onClick: () => form.books.add({ title: "New Book" }) }, void 0),
-                        jsx_runtime_1.jsx("button", { "data-testid": "blurBookOne", onClick: () => form.books.rows[0].title.blur() }, void 0),
-                        jsx_runtime_1.jsx("button", { "data-testid": "blurBookTwo", onClick: () => form.books.rows[1].title.blur() }, void 0)] }, void 0)) }, void 0));
-        }
-        // Given a formState with `onBlur` set
-        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
-        // When the data/child is now available
-        rtl_utils_1.click(r.refreshData);
-        // And the field is blurred
-        rtl_utils_1.click(r.blurBookOne);
-        // Then we don't auto-save because nothing has changed
-        expect(autoSave).toBeCalledTimes(0);
-        // And when adding a new book
-        rtl_utils_1.click(r.add);
-        // We autoSave the new row right away (because we don't have any validation rules
-        // that say the new row can't be empty)
-        expect(autoSave).toBeCalledTimes(1);
-        // And the new book is blurred
-        rtl_utils_1.click(r.blurBookTwo);
-        // Then we auto save again
-        expect(autoSave).toBeCalledTimes(2);
-    });
 });
 class ObservableObject {
     constructor() {

package/dist/index.d.ts

@@ -1 +1,2 @@
-export { createObjectState, FieldState, ListFieldState, ObjectConfig, ObjectState, required, Rule, useFormState, } from "./formState";
+export { createObjectState, FieldState, ListFieldState, ObjectConfig, ObjectState, required, Rule, } from "./formState";
+export { useFormState } from "./useFormState";

package/dist/index.js

@@ -4,4 +4,5 @@ exports.useFormState = exports.required = exports.createObjectState = void 0;
 var formState_1 = require("./formState");
 Object.defineProperty(exports, "createObjectState", { enumerable: true, get: function () { return formState_1.createObjectState; } });
 Object.defineProperty(exports, "required", { enumerable: true, get: function () { return formState_1.required; } });
-Object.defineProperty(exports, "useFormState", { enumerable: true, get: function () { return formState_1.useFormState; } });
+var useFormState_1 = require("./useFormState");
+Object.defineProperty(exports, "useFormState", { enumerable: true, get: function () { return useFormState_1.useFormState; } });

package/dist/useFormState.d.ts

@@ -0,0 +1,57 @@
+import { ObjectConfig, ObjectState } from "./formState";
+export declare type UseFormStateOpts<T, I> = {
+    /** The form configuration, should be a module-level const or useMemo'd. */
+    config: ObjectConfig<T>;
+    /**
+     * Provides the form's initial value.
+     *
+     * User's can either:
+     *
+     * - Provide no initial value (don't set `init` at all)
+     * - Provide an initial value that already matches the form type `T` (i.e. set `init: data`)
+     * - Provide an initial value from an object that _almost_ matches the form type `T`,
+     *   but needs to be mapped from it's input type `I` to the form type
+     *   (i.e. set `init: { input: data, map: (data) => ...}`).
+     *
+     * The value of using the 3rd option is that: a) we internally `useMemo` on the identity of the
+     * `init.input` (i.e. a response from an Apollo hook) and don't require the `map` function
+     * to have a stable identity, and also b) we will null-check/undefined-check `init.input` and
+     * 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;
+    };
+    /**
+     * A hook to add custom, cross-field validation rules that can be difficult to setup directly in the config DSL.
+     *
+     * Does not need to be stable/useMemo'd.
+     */
+    addRules?: (state: ObjectState<T>) => void;
+    /** Whether the form should be read only, when changed it won't re-create the whole form. */
+    readOnly?: boolean;
+    /**
+     * Fired when the form should auto-save, i.e. after a) blur and b) all fields are valid.
+     *
+     * Does not need to be stable/useMemo'd.
+     */
+    autoSave?: (state: ObjectState<T>) => void;
+};
+/**
+ * Creates a formState instance for editing in a form.
+ */
+export declare function useFormState<T, I>(opts: UseFormStateOpts<T, I>): ObjectState<T>;
+/**
+ * Picks ony fields out of `instance` that are in the `formConfig`.
+ *
+ * This is useful for creating a form input from a GraphQL query result,
+ * but ignoring extra data in the query that we don't want/need in the form.
+ *
+ * (Especially because the form.value will become our mutation's input type
+ * that goes on the wire, we don't want superfluous data in it.)
+ */
+export declare function pickFields<T, I>(formConfig: ObjectConfig<T>, instance: I): {
+    [K in keyof T]: K extends keyof I ? I[K] : never;
+};