@homebound/form-state 2.5.1 → 2.7.0

package/README.md

@@ -1,9 +1,54 @@
 # form-state
 
-Push release.
+form-state is a headless form state management library, built on top of mobx.
+
+It acts as a buffer between the canonical data/entity (i.e. the server-side data, or local Redux/GraphQL/etc. cache data) and the user's WIP data/entity that is being actively mutated in form fields.
+
+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)
+* 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
+* Building a wire payload that has only changed fields
+  * Handles children, i.e. a `author: { books: [...} }` will include only changed books if necessary
+
+# 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 />`)
+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:
+
+* The input type
+  * (Hrm, in retrospect "input" is an unfortunate term b/c that is what GraphQL uses for its mutation types, i.e. `input SaveAuthorInput`...we should consider changing this).
+* The form type
+* The ...third type...
+
+And then provides an API/DSL for managing the mapping between each of these in a standard/conventional manner. 
+
+
+Admittedly (and hopefully, b/c it makes the code simpler), the differences between each of these types can often be small, i.e.:
+
+* The input type might have `{ author: { book: { id: "b:1" } }` but the mutation wants `{ author: { bookId: "b:1" } }`
+* ...have other examples...
+
+These are usually simple/mechanistic changes, but nonetheless just some boilerplate that form-state provides conventions for.
+
+# Basic Usage
+
+See the [sample](https://github.com/homebound-team/form-state/blob/main/src/FormStateApp.tsx).
 
 # Todo
 
 - Add conditional readonly logic, like `{ type: "field", readOnlyIf: i => i.isInternal.value }`
 
 - Add `omitFromValue` so we can have two fields, `book.author.id` / `book.author.name`, where `book.author.name` is used for showing the author name, but `book.author.id` is the only field that is submitted to the server on mutation (maybe pair this with `Ref` based mutations)
+
+- Undo/redo would in theory be neat and easy to do on top of the existing infra

package/dist/formState.d.ts

@@ -87,6 +87,23 @@ export interface SetOpts {
     /** Whether this `set` should trigger an auto-save; defaults to true. */
     autoSave?: boolean;
 }
+/** Internal `.set` opts for conditionally that form-state internally percolates. */
+interface InternalSetOpts extends SetOpts {
+    /** `resetting` is the code calling `.reset()` to revert to original values. */
+    resetting?: boolean;
+    /** `refreshing` is when `useFormState` sees a new value. */
+    refreshing?: boolean;
+}
+export interface FieldStateInternal<T, V> extends FieldState<T, V> {
+    set(value: V, opts?: InternalSetOpts): void;
+    _isIdKey: boolean;
+    _isDeleteKey: boolean;
+    _isReadOnlyKey: boolean;
+    _focused: boolean;
+}
+export declare type ObjectStateInternal<T, P = any> = ObjectState<T, P> & {
+    set(value: P, opts?: InternalSetOpts): void;
+};
 /** Form state for list of children, i.e. `U` is a `Book` in a form with a `books: Book[]`. */
 export interface ListFieldState<T, U> extends Omit<FieldState<T, U[]>, "originalValue"> {
     readonly rows: ReadonlyArray<ObjectState<U>>;

package/dist/formState.js

@@ -431,10 +431,22 @@ function newListFieldState(parentInstance, parentState, key, rules, listConfig,
         },
         get changedValue() {
             const result = [];
-            const pushAll = listConfig.update !== "incremental";
+            const hasOpKey = Object.keys(listConfig.config).includes("op");
+            const hasLegacyOpKey = Object.keys(listConfig.config).some((key) => key === "delete" || key === "remove");
+            const incremental = listConfig.update === "incremental" ||
+                // Implicitly enable incremental mode if we see an op key
+                (listConfig.update === undefined && (hasOpKey || hasLegacyOpKey));
+            const exhaustive = !incremental;
             this.rows.forEach((r) => {
-                if (pushAll || r.dirty) {
-                    result.push(r.changedValue);
+                var _a;
+                var _b;
+                if (exhaustive || r.dirty || r.isNewEntity) {
+                    const changed = r.changedValue;
+                    // Ensure we have an `op: include` key, following https://joist-orm.io/docs/features/partial-update-apis
+                    if (incremental && hasOpKey) {
+                        (_a = (_b = changed).op) !== null && _a !== void 0 ? _a : (_b.op = "include");
+                    }
+                    result.push(changed);
                 }
             });
             return result;
@@ -512,7 +524,7 @@ function newListFieldState(parentInstance, parentState, key, rules, listConfig,
             this.rows.forEach((r) => {
                 r.save();
             });
-            originalCopy = parentInstance[key];
+            originalCopy = [...(parentInstance[key] || [])];
             _tick.value++;
         },
         ensureSet() {

package/dist/formState.test.js

@@ -979,6 +979,81 @@ describe("formState", () => {
             books: [{ id: "b:1", title: "t1b" }],
         });
     });
+    it("uses the op key as a hint to use incremental list behavior", () => {
+        // Given an author
+        const formState = formState_1.createObjectState({
+            id: { type: "value" },
+            // And the books collection is not explicitly marked as incremental
+            books: {
+                type: "list",
+                config: {
+                    id: { type: "value" },
+                    title: { type: "value", rules: [formState_1.required] },
+                    // But it does have an op key
+                    op: { type: "value" },
+                },
+            },
+        }, {
+            id: "a:1",
+            firstName: "f",
+            books: [
+                // And the books start out as included
+                { id: "b:1", title: "t1", op: "include" },
+                { id: "b:2", title: "t2", op: "include" },
+            ],
+        });
+        // And initially nothing is changed
+        expect(formState.changedValue).toEqual({ id: "a:1" });
+        // When we delete the 1st book
+        formState.books.rows[0].op.value = "delete";
+        // Then only the 1st book is included
+        expect(formState.changedValue).toEqual({
+            id: "a:1",
+            books: [{ id: "b:1", op: "delete" }],
+        });
+    });
+    it("defaults the incremental op key to included when not set", () => {
+        // Given an author
+        const formState = formState_1.createObjectState({
+            id: { type: "value" },
+            // And the books collection is not explicitly marked as incremental
+            books: {
+                type: "list",
+                config: {
+                    id: { type: "value" },
+                    title: { type: "value", rules: [formState_1.required] },
+                    // But it does have an op key
+                    op: { type: "value" },
+                },
+            },
+        }, {
+            id: "a:1",
+            firstName: "f",
+            books: [
+                // And no op keys are initially set
+                { id: "b:1", title: "t1" },
+                { id: "b:2", title: "t2" },
+            ],
+        });
+        // And initially nothing is changed
+        expect(formState.changedValue).toEqual({ id: "a:1" });
+        // When we delete the 1st book
+        formState.books.rows[0].op.value = "delete";
+        // And add a 3rd book
+        formState.books.add({ title: "t3" });
+        // Then the 3rd book doesn't have an explicit op yet
+        expect(formState.books.rows[2].op.value).toBeUndefined();
+        // But when we create changedValue
+        expect(formState.changedValue).toEqual({
+            id: "a:1",
+            books: [
+                // Then the deleted book is included
+                { id: "b:1", op: "delete" },
+                // And the 3rd book is included w/the `op: include` flag added
+                { title: "t3", op: "include" },
+            ],
+        });
+    });
     it("can observe value changes", () => {
         const formState = formState_1.createObjectState(authorWithBooksConfig, { firstName: "f" });
         let ticks = 0;
@@ -1145,6 +1220,23 @@ describe("formState", () => {
         expect(formState.books.rows[1].isNewEntity).toBeTruthy();
         expect(formState.books.isNewEntity).toBeFalsy();
     });
+    it("can properly evaluate dirty lists after calling 'save'", () => {
+        // Given an empty list state
+        const a1 = createAuthorInputState({ books: [] });
+        expect(a1.books.dirty).toBeFalsy();
+        // When adding a book
+        a1.books.add({ title: "t2" });
+        // Then the list state is dirty
+        expect(a1.books.dirty).toBeTruthy();
+        // When saving the form state
+        a1.save();
+        // Then the list is no longer dirty
+        expect(a1.books.dirty).toBeFalsy();
+        // When adding a new book
+        a1.books.add({ title: "t3" });
+        // The list is again dirty
+        expect(a1.books.dirty).toBeTruthy();
+    });
 });
 class ObservableObject {
     constructor() {

package/dist/formStateDomain.d.ts

@@ -26,6 +26,7 @@ export interface BookInput {
     classification?: DeweyDecimalClassification;
     delete?: boolean | null | undefined;
     isPublished?: boolean;
+    op?: "include" | "delete" | "remove";
 }
 export interface DeweyDecimalClassification {
     number: string;

package/dist/useFormStates.d.ts

@@ -2,8 +2,17 @@ import { ObjectConfig, ObjectState } from "./formState";
 export declare type ObjectStateCache<T, I> = Record<string, [ObjectState<T>, I]>;
 declare type UseFormStatesOpts<T, I> = {
     config: ObjectConfig<T>;
+    /** Fired for each individual `ObjectState` when it's had a value change. */
     autoSave?: (state: ObjectState<T>) => Promise<void>;
+    /**
+     * 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;
+    /** Given an input to `getObjectState`, returns the identity value that we'll cache that value's form state on. */
     getId: (v: I) => string;
+    /** Maps an input to `getObjectState` to the actual form shape `T`. */
     map?: (input: Exclude<I, null | undefined>) => T;
 };
 export declare function useFormStates<T, I>(opts: UseFormStatesOpts<T, I>): {

package/dist/useFormStates.js

@@ -5,7 +5,7 @@ const react_1 = require("react");
 const formState_1 = require("./formState");
 const utils_1 = require("./utils");
 function useFormStates(opts) {
-    const { config, autoSave, getId, map } = opts;
+    const { config, autoSave, getId, map, addRules } = opts;
     const objectStateCache = react_1.useMemo(() => ({}), [config]);
     // Keep track of ObjectStates that triggered auto-save when a save was already in progress.
     const pendingAutoSaves = react_1.useRef([]);
@@ -33,18 +33,20 @@ function useFormStates(opts) {
     return {
         getObjectState: (input) => {
             const existing = objectStateCache[getId(input)];
-            const form = existing
-                ? existing[0]
-                : formState_1.createObjectState(config, utils_1.initValue(config, map ? { map, input } : 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), {
                     maybeAutoSave: () => maybeAutoSave(form),
                 });
-            // If it didn't exist, then add to the cache.
-            if (!existing) {
+                if (addRules) {
+                    addRules(form);
+                }
                 objectStateCache[getId(input)] = [form, input];
             }
             // If the source of truth changed, then update the existing state and return it.
             if (existing && existing[1] !== input) {
-                existing[0].set(utils_1.initValue(config, map ? { map, input } : input), { refreshing: true });
+                form.set(utils_1.initValue(config, map ? { map, input } : input), { refreshing: true });
                 existing[1] = input;
             }
             return form;

package/dist/useFormStates.test.js

@@ -133,4 +133,25 @@ describe("useFormStates", () => {
         // Then the two form-states are no longer equal.
         expect(r.statesEqual()).toHaveTextContent("false");
     });
+    it("calls addRules once per form state", async () => {
+        // Given a user wants to use addRules
+        const addRules = jest.fn();
+        function TestComponent() {
+            const config = { id: { type: "value" }, firstName: { type: "value" } };
+            const { getObjectState } = useFormStates_1.useFormStates({
+                config,
+                addRules,
+                getId: (o) => o.id,
+            });
+            return (jsx_runtime_1.jsxs("div", { children: [jsx_runtime_1.jsx(ChildComponent, { os: getObjectState({ id: "a:1", firstName: "Brandon" }) }, void 0),
+                    jsx_runtime_1.jsx(ChildComponent, { os: getObjectState({ id: "a:1", firstName: "Brandon" }) }, void 0)] }, void 0));
+        }
+        // When we render
+        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
+        // Then addRules was only called once
+        expect(addRules).toHaveBeenCalledTimes(1);
+    });
 });
+function ChildComponent({ os }) {
+    return jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "firstName" }, { children: os.firstName.value }), void 0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homebound/form-state",
-  "version": "2.5.1",
+  "version": "2.7.0",
   "author": "Homebound",
   "license": "MIT",
   "main": "dist/index.js",
@@ -41,6 +41,7 @@
   "devDependencies": {
     "@babel/core": "^7.13.1",
     "@homebound/rtl-utils": "^2.59.2",
+    "@semantic-release/exec": "^5.0.0",
     "@semantic-release/git": "^9.0.0",
     "@storybook/addon-essentials": "^6.2.9",
     "@storybook/addon-info": "^5.3.21",