@homebound/form-state 2.15.3 → 2.16.0

package/README.md

@@ -5,27 +5,69 @@
 
 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 acts as a buffer between the canonical data (i.e. the server-side data, or your app's GraphQL/Redux/etc. global store) and the user's WIP data that is being actively mutated in form fields (which is "too chatty"/WIP to store in the global store).
 
 It also keeps track of low-level form UX details like:
 
-* Which form fields are dirty
-* Which form fields are valid/invalid
-* Which form 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)
-* Queueing auto-saves if one is already in-flight
-  * Auto-saves in a table with per-row forms will serialize to avoid cross-child write conflicts on the backend
-* Not over-writing the user's WIP/actively-focused field when auto-saved data refreshes 
-* Building a wire payload that has only changed fields
-  * `form.changedValue` will return the entity `id` + only changed fields to faciliate doing partial update APIs
-  * Supports collections of children, i.e. a `author: { books: [...} }` will include only changed books if necessary
-  * Child collections can be either exhausive (if any child changes, submit them all) or incremental (only include changed children), to match the backend endpoint's semantics
+- Which form fields are dirty
+- Which form fields are valid/invalid
+- Which form 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)
+- Queueing auto-saves if one is already in-flight
+  - Auto-saves in a table with per-row forms will serialize to avoid cross-child write conflicts on the backend
+- Not over-writing the user's WIP/actively-focused field when auto-saved data refreshes
+- Building a wire payload that has only changed fields
+  - `form.changedValue` will return the entity `id` + only changed fields to faciliate doing partial update APIs
+  - Supports collections of children, i.e. a `author: { books: [...} }` will include only changed books if necessary
+  - Child collections can be either exhausive (if any child changes, submit them all) or incremental (only include changed children), to match the backend endpoint's semantics
 
-# The Three Type/Shapes Mental Model
+# Main Features
 
-In general when working with forms (e.g. not just form-state), there are three types/shapes of data involved:
+There are two main reasons why form-state exists:
+
+1. Provide a `FieldState` interface for component libraries
+2. Match the "three shapes" mental model of our forms
+
+## FieldState Interface & "One-Line" Forms
+
+The core abstraction that `form-state` provides is a `FieldState` interface that looks like:
+
+```ts
+// Very simplified example
+interface FieldState {
+  value: V
+  errors: string[]
+  valid: boolean
+  touched: boolean
+}
+```
+
+Which combines all the logical aspects of "a single form field" into a single object/prop.
+
+This facilitates the "gold standard" of form libraries, which is "one line per form field", i.e:
+
+```tsx
+function AuthorEditorComponent() {
+  const author = useFormState(() => /* ... */ );
+  return (
+    <FormLines>
+      <BoundTextField field={author.firstName} />
+      <BoundTextField field={author.lastName} />
+      <BoundSelectField field={author.city} options={...cities...} />
+    </FormLines>
+  )
+}
+```
+
+Besides great developer ergonomics (low boilerplate, very DRY code), this approach also provides a very consistent UI/UX for users, because all forms get the highly-polish behavior of `BoundTextField` for free.
+
+(See the `BoundTextField` in [Beam](https://github.com/homebound-team/beam) for an actual implementation of this approach.)
+
+## The Three Shapes Mental Model
+
+In general when working with any forms (i.e. 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} />`)
@@ -33,18 +75,17 @@ In general when working with forms (e.g. not just form-state), there are three t
 
 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. 
+- 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...
+- 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.
 
@@ -60,7 +101,54 @@ See the [sample](https://github.com/homebound-team/form-state/blob/main/src/Form
 
 - Undo/redo would in theory be neat and easy to do on top of the existing infra
 
-# Internal Implementation
+# Features
+
+## Fragments
+
+Normally, form-state expects all fields in the form to be inputs to the GraphQL mutation/wire call. For example, the `author.firstName` field will always be submitted to the `saveAuthor` mutation (albeit with `author.changedValue` you can have `firstName` conditionally included).
+
+However, sometimes there is "other data" that your UX needs to render the form, which is not strictly a form field, but would be handy for the data to "just be on the form" anyway, as you're passing it in around code.
+
+A stereotypical example of this is GraphQL fragments, where an `AuthorFragment` might have a lot of misc read-only info that you want to display next to/within your form, but is not technically editable.
+
+In form-state, you can model with as a `Fragment`, which is set up as:
+
+```ts
+// Your input type, likely generated from GraphQL mutation
+type AuthorInput = { firstName?: string };
+
+// Your wire data likely from your page's GraphQL query to get
+// the author to edit + also "misc other data"
+type AuthorFragment = { firstName: string; miscOtherData: {} };
+
+// For your page's form state, add-in the "extra data"
+type AuthorForm = AuthorInput & {
+  // The `Fragment` type tells form-state this is not a regular form field
+  data: Fragment<AuthorFragment >
+};
+
+// Tell the form config the "fragment" is not a real field
+const config: ObjectConfig<AuthorForm> = {
+  firstName: { type: "value", rules: [require] },
+  data: { type: "fragment" },
+}
+
+// Now in the component...
+const data = useGraphQLQuery();
+const form = useFormState({
+  config,
+  init: {
+    input: data,
+    map: (d) => ({
+      firstName: data.author.firstName,
+      data: fragment(data),
+    }),
+  },
+});
+```
+
+
+# Internal Implementation Notes
 
 form-state keeps the "actual data" (basically a POJO of your form data) separate from the "mobx proxies that track reactivity" (the `ObjectState` interface with `.get` / `.set` / `.errors` other methods).
 
@@ -69,6 +157,3 @@ This works well b/c the "actual data" returned from `ObjectState.value` or `Fiel
 However, it does mean that form-state internally uses a few "that looks odd" tricks like `_tick.value++` to ensure code like `formState.value.firstName` will be reactive, even though the `.firstName` is not actually a proxy access (but doing `formState.firstName.value` would be).
 
 (To be clear, both `formState.firstName.value` and `formState.value.firstName` return the same value, and also have the same reactivity semantics, this is just noting that form-state's internals need to do a few extra tricks to get the latter to be reactive.)
-
-
-

package/dist/config.d.ts

@@ -1,4 +1,4 @@
-import { ObjectState } from "./fields/objectField";
+import { Fragment, ObjectState } from "./fields/objectField";
 import { Rule } from "./rules";
 import { Builtin } from "./utils";
 /**
@@ -8,11 +8,15 @@ import { Builtin } from "./utils";
  * the caller define field-specific behavior, i.e. validation rules.
  */
 export declare type ObjectConfig<T> = {
-    [P in keyof OmitIf<T, Function>]: T[P] extends Array<infer U> | null | undefined ? U extends Builtin ? ValueFieldConfig<T, T[P]> : ListFieldConfig<T, U> : ValueFieldConfig<T, T[P]> | ObjectFieldConfig<T[P]>;
+    [P in keyof OmitIf<T, Function>]: T[P] extends Fragment<infer V> ? FragmentFieldConfig : T[P] extends Array<infer U> | null | undefined ? U extends Builtin ? ValueFieldConfig<T, T[P]> : ListFieldConfig<T, U> : ValueFieldConfig<T, T[P]> | ObjectFieldConfig<T[P]>;
 };
 declare type OmitIf<Base, Condition> = Pick<Base, {
     [Key in keyof Base]: Base[Key] extends Condition ? never : Key;
 }[keyof Base]>;
+/** Field configuration for an opaque value that we don't actually want to include. */
+export declare type FragmentFieldConfig = {
+    type: "fragment";
+};
 /** Field configuration for primitive values, i.e. strings/numbers/Dates/user-defined types. */
 export declare type ValueFieldConfig<T, V> = {
     type: "value";

package/dist/fields/fragmentField.d.ts

@@ -0,0 +1,4 @@
+export interface FragmentField<V> {
+    value: V;
+}
+export declare function newFragmentField<T, K extends keyof T>(parentInstance: T, key: K): FragmentField<T[K]>;

package/dist/fields/fragmentField.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newFragmentField = void 0;
+const mobx_1 = require("mobx");
+const utils_1 = require("../utils");
+function newFragmentField(parentInstance, key) {
+    // We always return the same `instance` field from our `value` method, but
+    // we want to pretend that it's observable, so use a tick to force it.
+    const _tick = mobx_1.observable({ value: 1 });
+    // We steal the fragment from our parent, so that it doesn't
+    // accidentally end up on the wire
+    let value = parentInstance[key];
+    delete parentInstance[key];
+    const obj = {
+        get value() {
+            _tick.value > 0 || utils_1.fail();
+            return value;
+        },
+        set value(v) {
+            value = v;
+            _tick.value++;
+        },
+    };
+    return mobx_1.makeAutoObservable(obj, { value: false });
+}
+exports.newFragmentField = newFragmentField;

package/dist/fields/objectField.d.ts

@@ -1,4 +1,5 @@
 import { ObjectConfig } from "../config";
+import { FragmentField } from "./fragmentField";
 import { ListFieldState } from "./listField";
 import { FieldState, InternalSetOpts, SetOpts } from "./valueField";
 import { Builtin } from "../utils";
@@ -36,9 +37,14 @@ export declare type ObjectState<T, P = any> = FieldStates<T> & FieldState<P, T>
 export declare type ObjectStateInternal<T, P = any> = ObjectState<T, P> & {
     set(value: P, opts?: InternalSetOpts): void;
 };
+declare const fragmentSym: unique symbol;
+export declare type Fragment<V> = V & {
+    [fragmentSym]: true;
+};
+export declare function fragment<V>(value: V): Fragment<V>;
 /** For a given input type `T`, decorate each field into the "field state" type that holds our form-relevant state, i.e. valid/touched/etc. */
 declare type FieldStates<T> = {
-    [K in keyof T]-?: T[K] extends Array<infer U> | null | undefined ? [U] extends [Builtin] ? FieldState<T, T[K]> : ListFieldState<T, U> : T[K] extends Builtin | null | undefined ? FieldState<T, T[K]> : ObjectState<T[K], T>;
+    [K in keyof T]-?: T[K] extends Fragment<infer V> ? FragmentField<V> : T[K] extends Array<infer U> | null | undefined ? [U] extends [Builtin] ? FieldState<T, T[K]> : ListFieldState<T, U> : T[K] extends Builtin | null | undefined ? FieldState<T, T[K]> : ObjectState<T[K], T>;
 };
 /**
  * Creates a new `ObjectState` for a given form object `T` given config rules in `config`.

package/dist/fields/objectField.js

@@ -1,10 +1,16 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.newObjectState = exports.createObjectState = void 0;
+exports.newObjectState = exports.createObjectState = exports.fragment = void 0;
 const mobx_1 = require("mobx");
+const fragmentField_1 = require("./fragmentField");
 const listField_1 = require("./listField");
 const valueField_1 = require("./valueField");
 const utils_1 = require("../utils");
+const fragmentSym = Symbol("fragment");
+function fragment(value) {
+    return value;
+}
+exports.fragment = fragment;
 /**
  * Creates a new `ObjectState` for a given form object `T` given config rules in `config`.
  *
@@ -45,6 +51,9 @@ function newObjectState(config, parentState, parentListState, instance, key, may
             }
             field = newObjectState(config.config, getObjectState, undefined, instance[key], key, maybeAutoSave);
         }
+        else if (config.type === "fragment") {
+            field = fragmentField_1.newFragmentField(instance, key);
+        }
         else {
             throw new Error("Unsupported");
         }

package/dist/fields/valueField.js

@@ -101,7 +101,7 @@ function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, is
             }
             // If the user has deleted/emptied a value that was originally set, keep it as `null`
             // so that our partial update to the backend correctly unsets it.
-            const keepNull = !utils_1.isEmpty(this.originalValue) && utils_1.isEmpty(value);
+            const keepNull = !utils_1.isEmpty(this.originalValue) && utils_1.isEmpty(value) && !opts.refreshing;
             // If a list of primitives was originally undefined, coerce `[]` to `undefined`
             const coerceEmptyList = value && value instanceof Array && value.length === 0 && utils_1.isEmpty(this.originalValue);
             const newValue = keepNull ? null : utils_1.isEmpty(value) || coerceEmptyList ? undefined : value;
@@ -135,7 +135,9 @@ function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, is
         },
         get originalValue() {
             // A dummy check to for reactivity around our non-proxy value
-            return _originalValueTick.value > -1 ? _originalValue : _originalValue;
+            const value = _originalValueTick.value > -1 ? _originalValue : _originalValue;
+            // Re-create the `keepNull` logic so that `.value` === `.originalValue`
+            return value === null ? undefined : value;
         },
         set originalValue(v) {
             _originalValue = v;

package/dist/formState.test.js

@@ -1338,6 +1338,41 @@ describe("formState", () => {
         // The list is again dirty
         expect(a1.books.dirty).toBeTruthy();
     });
+    describe("fragments", () => {
+        it("ignores changes within fragments", () => {
+            const a = objectField_1.createObjectState({ title: { type: "value" }, data: { type: "fragment" } }, { title: "b1", data: objectField_1.fragment({ foo: "1" }) });
+            let numCalcs = 0;
+            mobx_1.autorun(() => {
+                numCalcs++;
+                noop(a.value);
+            });
+            expect(a.data.value).toEqual({ foo: "1" });
+            expect(mobx_1.isObservable(a.data.value)).toBe(false);
+            expect(numCalcs).toEqual(1);
+            a.data.value = { foo: "2" };
+            expect(numCalcs).toEqual(2);
+            a.data.value.foo = "3";
+            expect(numCalcs).toEqual(2);
+        });
+        it("ignores fragments in changedValue", () => {
+            const a = objectField_1.createObjectState({ title: { type: "value" }, data: { type: "fragment" } }, { title: "b1", data: objectField_1.fragment({ foo: "1" }) });
+            a.title.value = "b2";
+            a.data.value = objectField_1.fragment({ foo: "2" });
+            expect(a.changedValue).toMatchInlineSnapshot(`
+        Object {
+          "title": "b2",
+        }
+      `);
+        });
+        it("ignores fragments in value", () => {
+            const a = objectField_1.createObjectState({ title: { type: "value" }, data: { type: "fragment" } }, { title: "b1", data: objectField_1.fragment({ foo: "1" }) });
+            expect(a.value).toMatchInlineSnapshot(`
+        Object {
+          "title": "b1",
+        }
+      `);
+        });
+    });
 });
 class ObservableObject {
     constructor() {
@@ -1409,3 +1444,4 @@ const authorWithAddressAndBooksConfig = {
 function createAuthorWithAddressInputState(input) {
     return objectField_1.createObjectState(authorWithAddressConfig, input);
 }
+function noop(t) { }

package/dist/useFormState.js

@@ -91,6 +91,12 @@ function useFormState(opts) {
             return;
         }
         setLoading(form, opts);
+        // Note: maybe someday we want to watch the `id` value and notice if it's changing (i.e. 2 -> 3),
+        // and treat this more as a reset than a refresh, b/c the id changing means it's probably
+        // not "the cache refreshed after a mutation save" but "the cache changed b/c of changing
+        // rows in the table that our side panel's form has open/is focused on" (which ideally would
+        // be treated as a full component remount by having an `key` field somewhere in the parent
+        // component, but it's unlikely the user will always remember to do this).
         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

package/dist/useFormState.test.js

@@ -528,6 +528,41 @@ describe("useFormState", () => {
         expect(result.current.autoSave.status).toBe(AutoSaveStatusProvider_1.AutoSaveStatus.DONE);
         jest.clearAllTimers();
     });
+    it("treats the id changing as a whole new entity instead of a delete", async () => {
+        const config = { firstName: { type: "value" } };
+        function TestComponent() {
+            // Given an initial author a1
+            const [author, setAuthor] = react_2.useState({ id: "a:1", firstName: "a1" });
+            const form = useFormState_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": "value" }, { children: String(form.firstName.value) }), void 0),
+                        jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "dirty" }, { children: String(form.firstName.dirty) }), void 0),
+                        jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "originalValue" }, { children: String(form.firstName.originalValue) }), void 0),
+                        jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "objectValue" }, { children: String(form.value.firstName) }), void 0),
+                        jsx_runtime_1.jsx("div", { "data-testid": "a1", onClick: () => setAuthor({ id: "a:1", firstName: "a1" }) }, void 0),
+                        jsx_runtime_1.jsx("div", { "data-testid": "a2", onClick: () => setAuthor({ id: "a:2", firstName: undefined }) }, void 0)] }, void 0)) }, void 0));
+        }
+        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
+        // And the value is initially a1/and not dirty
+        expect(r.value()).toHaveTextContent("a1");
+        expect(r.dirty()).toHaveTextContent("false");
+        expect(r.originalValue()).toHaveTextContent("a1");
+        expect(r.objectValue()).toHaveTextContent("a1");
+        // When we switch to a completely separate author
+        rtl_utils_1.click(r.a2);
+        // Then it switches to the next author
+        expect(r.value()).toHaveTextContent("undefined");
+        // And the field is not dirty (which had been the case before this bug fix)
+        expect(r.dirty()).toHaveTextContent("false");
+        expect(r.originalValue()).toHaveTextContent("undefined");
+        expect(r.objectValue()).toHaveTextContent("undefined");
+        // And when we switch back to the original author
+        rtl_utils_1.click(r.a1);
+        // It again restores the value and does not think an edit was WIP
+        expect(r.value()).toHaveTextContent("a1");
+        expect(r.dirty()).toHaveTextContent("false");
+        expect(r.originalValue()).toHaveTextContent("a1");
+        expect(r.objectValue()).toHaveTextContent("a1");
+    });
 });
 const authorConfig = {
     id: { type: "value" },

package/dist/utils.d.ts

@@ -35,7 +35,7 @@ export declare function isEmpty(value: any): boolean;
  *
  * - "plain" objects that have no custom prototype/i.e. are object literals
  * - objects that implement `toJSON`
- *
+ * - arrays
  */
 export declare function areEqual<T>(a?: T, b?: T, strictOrder?: boolean): boolean;
 export declare function hasToJSON(o?: unknown): o is {

package/dist/utils.js

@@ -100,7 +100,7 @@ exports.isEmpty = isEmpty;
  *
  * - "plain" objects that have no custom prototype/i.e. are object literals
  * - objects that implement `toJSON`
- *
+ * - arrays
  */
 function areEqual(a, b, strictOrder) {
     if (is_plain_object_1.isPlainObject(a)) {
@@ -117,7 +117,7 @@ function areEqual(a, b, strictOrder) {
         }
         if (a.length !== b.length)
             return false;
-        return a.every((a1) => b.some((b1) => fast_deep_equal_1.default(a1, b1)));
+        return a.every((a1) => b.some((b1) => areEqual(a1, b1)));
     }
     return a === b;
 }

package/package.json

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