@homebound/form-state 2.23.2 → 2.24.0

package/dist/FormStateApp.js

@@ -9,11 +9,13 @@ function FormStateApp() {
         config: formConfig,
         // Simulate getting the initial form state back from a server call
         init: {
-            firstName: "a1",
-            books: [...Array(2)].map((_, i) => ({
-                title: `b${i}`,
-                classification: { number: `10${i + 1}`, category: `Test Category ${i}` },
-            })),
+            input: {
+                firstName: "a1",
+                books: [...Array(2)].map((_, i) => ({
+                    title: `b${i}`,
+                    classification: { number: `10${i + 1}`, category: `Test Category ${i}` },
+                })),
+            },
         },
         addRules(state) {
             state.lastName.rules.push(() => {

package/dist/useFormState.d.ts

@@ -7,7 +7,7 @@ export type Query<I> = {
 };
 export type InputAndMap<T, I> = {
     input: I;
-    map: (input: Exclude<I, null | undefined>) => T;
+    map?: (input: Exclude<I, null | undefined>) => T;
     ifUndefined?: T;
 };
 export type QueryAndMap<T, I> = {
@@ -15,6 +15,12 @@ export type QueryAndMap<T, I> = {
     map: (input: Exclude<I, null | undefined>) => T;
     ifUndefined?: T;
 };
+/**
+ * The opts has for `useFormState`.
+ *
+ * @typeparam T the form type, which is usually as close as possible to your *GraphQL input*
+ * @typeparam I the *form input* type, which is usually the *GraphQL output* type, i.e. the type of the response from your GraphQL query
+ */
 export type UseFormStateOpts<T, I> = {
     /** The form configuration, should be a module-level const or useMemo'd. */
     config: ObjectConfig<T>;
@@ -35,7 +41,7 @@ export 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 | InputAndMap<T, I> | QueryAndMap<T, I>;
+    init?: 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.
      *

package/dist/useFormState.test.js

@@ -83,28 +83,6 @@ describe("useFormState", () => {
         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] = (0, react_2.useState)(0);
-            const form = (0, useFormState_1.useFormState)({
-                config,
-                // That's using a raw init value
-                init: { firstName: "bob" },
-            });
-            return ((0, jsx_runtime_1.jsxs)("div", { children: [(0, 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);
-                        } }), (0, jsx_runtime_1.jsx)("div", { "data-testid": "firstName", children: form.firstName.value })] }));
-        }
-        const r = await (0, rtl_utils_1.render)((0, jsx_runtime_1.jsx)(TestComponent, {}));
-        expect(r.firstName).toHaveTextContent("bob");
-        (0, 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" } };
@@ -154,7 +132,7 @@ describe("useFormState", () => {
             };
             // And we start out with data1
             const [data, setData] = (0, react_2.useState)(data1);
-            const form = (0, useFormState_1.useFormState)({ config, init: { input: data, map: (d) => d } });
+            const form = (0, useFormState_1.useFormState)({ config, init: { input: data } });
             function makeLocalChanges() {
                 form.firstName.value = "local";
                 form.address.street.value = "local";
@@ -222,7 +200,7 @@ describe("useFormState", () => {
             const [data, setData] = (0, react_2.useState)(data1);
             const form = (0, useFormState_1.useFormState)({
                 config,
-                init: { input: data, map: (d) => d },
+                init: { input: data },
                 // And the form is read only
                 readOnly: true,
             });
@@ -318,7 +296,7 @@ describe("useFormState", () => {
             const data2 = { books: [{ title: "Title 1" }] };
             const form = (0, useFormState_1.useFormState)({
                 config: authorWithBooksConfig,
-                init: { input: data, map: (d) => d, ifUndefined: { books: [] } },
+                init: { input: data, ifUndefined: { books: [] } },
                 autoSave,
             });
             return ((0, jsx_runtime_1.jsx)(mobx_react_1.Observer, { children: () => ((0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("button", { "data-testid": "refreshData", onClick: () => setData(data2) }), (0, jsx_runtime_1.jsx)("button", { "data-testid": "add", onClick: () => form.books.add({ title: "New Book" }) }), (0, jsx_runtime_1.jsx)("button", { "data-testid": "blurBookOne", onClick: () => focusAndBlur(form.books.rows[0].title) }), (0, jsx_runtime_1.jsx)("button", { "data-testid": "blurBookTwo", onClick: () => focusAndBlur(form.books.rows[1].title) })] })) }));
@@ -349,7 +327,7 @@ describe("useFormState", () => {
             const data = { firstName: "f1", lastName: "f1" };
             const form = (0, useFormState_1.useFormState)({
                 config,
-                init: data,
+                init: { input: data },
                 // And there is reactive business logic in the `autoSave` method
                 async autoSave(state) {
                     state.lastName.set("l2");
@@ -372,7 +350,7 @@ describe("useFormState", () => {
             const data = { firstName: "f1", lastName: "f1" };
             const form = (0, useFormState_1.useFormState)({
                 config,
-                init: data,
+                init: { input: data },
                 autoSave: (form) => autoSave(form.changedValue),
             });
             return ((0, jsx_runtime_1.jsx)("div", { children: (0, jsx_runtime_1.jsx)("button", { "data-testid": "set", onClick: () => {
@@ -453,7 +431,7 @@ describe("useFormState", () => {
                     (0, mobx_1.reaction)(() => fs.firstName.value, (curr) => (fs.lastName.value = curr));
                 },
                 autoSave: (fs) => autoSaveStub(fs.changedValue),
-                init: { id: "a:1" },
+                init: { input: { id: "a:1" } },
             });
             return (0, jsx_runtime_1.jsx)(FormStateApp_1.TextField, { field: fs.firstName });
         }
@@ -482,7 +460,7 @@ describe("useFormState", () => {
     it("sets loading if input.data is undefined", async () => {
         const config = { firstName: { type: "value" } };
         function TestComponent({ data }) {
-            const form = (0, useFormState_1.useFormState)({ config, init: { input: data, map: (d) => d } });
+            const form = (0, useFormState_1.useFormState)({ config, init: { input: data } });
             return (0, jsx_runtime_1.jsx)(mobx_react_1.Observer, { children: () => (0, jsx_runtime_1.jsx)("div", { "data-testid": "loading", children: String(form.loading) }) });
         }
         // And we initially pass in `init.input: undefined`
@@ -546,7 +524,7 @@ describe("useFormState", () => {
             const config = authorConfig;
             const form = (0, useFormState_1.useFormState)({
                 config,
-                init: { firstName: "f1", lastName: "f1" },
+                init: { input: { firstName: "f1", lastName: "f1" } },
                 autoSave: async (form) => {
                     autoSave(form.changedValue);
                     // And the autoSave functions erroneously calls commitChanges

package/dist/useFormStates.d.ts

@@ -1,6 +1,12 @@
 import { ObjectConfig } from "./config";
 import { ObjectState } from "./fields/objectField";
 export type ObjectStateCache<T, I> = Record<string, [ObjectState<T>, I]>;
+/**
+ * The opts has for `useFormStates`.
+ *
+ * @typeparam T the form type, which is usually as close as possible to your *GraphQL input*
+ * @typeparam I the *form input* type, which is usually the *GraphQL output* type, i.e. the type of the response from your GraphQL query
+ */
 type UseFormStatesOpts<T, I> = {
     /**
      * The config to use for each form state.
@@ -45,5 +51,18 @@ type UseFormStatesHook<T, I> = {
         readOnly?: boolean;
     }) => ObjectState<T>;
 };
+/**
+ * A hook to manage many "mini-forms" on a single page, typically one form per row
+ * in a table.
+ *
+ * This hook basically provides the page/table with a cache, so each table row naively ask "what's
+ * the form state for this given row's data?" and get back a new-or-existing `ObjectState` instance
+ * that, if already existing, still has any of the user's WIP changes.
+ *
+ * Each mini-form/row can have its own autoSave calls, independent of the other rows.
+ *
+ * @typeparam T the form type, which is usually as close as possible to your *GraphQL input*
+ * @typeparam I the *form input* type, which is usually the *GraphQL output* type, i.e. the type of the response from your GraphQL query
+ */
 export declare function useFormStates<T, I = T>(opts: UseFormStatesOpts<T, I>): UseFormStatesHook<T, I>;
 export {};

package/dist/useFormStates.js

@@ -4,6 +4,19 @@ exports.useFormStates = void 0;
 const react_1 = require("react");
 const objectField_1 = require("./fields/objectField");
 const utils_1 = require("./utils");
+/**
+ * A hook to manage many "mini-forms" on a single page, typically one form per row
+ * in a table.
+ *
+ * This hook basically provides the page/table with a cache, so each table row naively ask "what's
+ * the form state for this given row's data?" and get back a new-or-existing `ObjectState` instance
+ * that, if already existing, still has any of the user's WIP changes.
+ *
+ * Each mini-form/row can have its own autoSave calls, independent of the other rows.
+ *
+ * @typeparam T the form type, which is usually as close as possible to your *GraphQL input*
+ * @typeparam I the *form input* type, which is usually the *GraphQL output* type, i.e. the type of the response from your GraphQL query
+ */
 function useFormStates(opts) {
     const { config, autoSave, getId, map, addRules, readOnly = false } = opts;
     const objectStateCache = (0, react_1.useMemo)(() => ({}), 
@@ -54,7 +67,7 @@ function useFormStates(opts) {
         }
         // If it didn't exist, then add to the cache.
         if (!form) {
-            form = (0, objectField_1.createObjectState)(config, (0, utils_1.initValue)(config, map ? { map, input } : input), {
+            form = (0, objectField_1.createObjectState)(config, (0, utils_1.initValue)(config, { map, input }), {
                 maybeAutoSave: () => maybeAutoSave(form),
             });
             if (addRules) {
@@ -64,7 +77,7 @@ function useFormStates(opts) {
         }
         // If the source of truth changed, then update the existing state and return it.
         if (existing && existing[1] !== input) {
-            form.set((0, utils_1.initValue)(config, map ? { map, input } : input), {
+            form.set((0, utils_1.initValue)(config, { map, input }), {
                 refreshing: true,
             });
             existing[1] = input;

package/dist/utils.d.ts

@@ -13,7 +13,7 @@ export type OmitIf<Base, Condition> = Pick<Base, {
 }[keyof Base]>;
 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. */
+/** Introspects the `init` prop to see if it 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>;

package/dist/utils.js

@@ -15,23 +15,27 @@ function assertNever(x) {
     throw new Error("Unexpected object: " + x);
 }
 exports.assertNever = assertNever;
-/** Introspects the `init` prop to see if has a `map` function/etc. and returns the form value. */
+/** Introspects the `init` prop to see if it has a `map` function/etc. and returns the form value. */
 function initValue(config, init) {
     let value;
     if (isInput(init)) {
-        value = init.input ? init.map(init.input) : init.ifUndefined;
+        value = init.input ? (init.map ? init.map(init.input) : init.input) : init.ifUndefined;
     }
     else if (isQuery(init)) {
         value = init.query.data ? init.map(init.query.data) : init.ifUndefined;
     }
+    else if (init === undefined) {
+        // allow completely undefined init
+    }
     else {
-        value = init;
+        throw new Error("init must have an input or query key");
     }
+    // Given our form config, pick out only the subset of fields out of `value` (unless it's a mobx class)
     return pickFields(config, value !== null && value !== void 0 ? value : {});
 }
 exports.initValue = initValue;
 function isInput(init) {
-    return !!init && typeof init === "object" && "input" in init && "map" in init;
+    return !!init && typeof init === "object" && "input" in init;
 }
 exports.isInput = isInput;
 function isQuery(init) {

package/package.json

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