@homebound/form-state 2.20.1 → 2.22.0

package/README.md

@@ -5,7 +5,7 @@
 
 form-state is a headless form state management library, built on top of mobx.
 
-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 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 push back into global stores).
 
 It also keeps track of low-level form UX details like:
 
@@ -21,7 +21,7 @@ It also keeps track of low-level form UX details like:
 - 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
+  - Child collections can be either exhaustive (if any child changes, submit them all) or incremental (only include changed children), to match the backend endpoint's semantics
 
 # Main Features
 
@@ -37,16 +37,17 @@ The core abstraction that `form-state` provides is a `FieldState` interface that
 ```ts
 // Very simplified example
 interface FieldState {
-  value: V
-  errors: string[]
-  valid: boolean
-  touched: boolean
+  // Can be used to read & write the value bound into the form field
+  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:
+This facilitates the "gold standard" of form DX, which is "one line per form field", i.e:
 
 ```tsx
 function AuthorEditorComponent() {
@@ -124,14 +125,14 @@ 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 >
+  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();
@@ -147,7 +148,6 @@ const form = useFormState({
 });
 ```
 
-
 # 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).

package/dist/FormStateApp.js

@@ -33,17 +33,15 @@ function FormStateApp() {
 }
 exports.FormStateApp = FormStateApp;
 // Configure the fields/behavior for AuthorInput's fields
-const formConfig = {
-    firstName: { type: "value", rules: [index_1.required] },
-    lastName: { type: "value", rules: [index_1.required], readOnly: true },
-    books: {
-        type: "list",
-        rules: [({ value: list }) => ((list || []).length === 0 ? "Empty" : undefined)],
-        config: {
-            title: { type: "value", rules: [index_1.required] },
-        },
-    },
-};
+const formConfig = index_1.f.config({
+    firstName: index_1.f.value().req(),
+    lastName: index_1.f.value().readOnly(),
+    books: index_1.f
+        .list({
+        title: index_1.f.value().req(),
+    })
+        .rule(({ value }) => (value.length === 0 ? "Empty" : undefined)),
+});
 function TextField(props) {
     const { field } = props;
     // Somewhat odd: input won't update unless we use <Observer>, even though our

package/dist/config.d.ts

@@ -1,6 +1,6 @@
 import { Fragment, ObjectState } from "./fields/objectField";
 import { Rule } from "./rules";
-import { Builtin } from "./utils";
+import { Builtin, OmitIf } from "./utils";
 /**
  * Config rules for each field in `T` that we're editing in a form.
  *
@@ -8,17 +8,14 @@ import { Builtin } from "./utils";
  * the caller define field-specific behavior, i.e. validation rules.
  */
 export type ObjectConfig<T> = {
-    [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]>;
+    [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[P]> : ListFieldConfig<U> : ValueFieldConfig<T[P]> | ObjectFieldConfig<T[P]>;
 };
-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 type FragmentFieldConfig = {
     type: "fragment";
 };
 /** Field configuration for primitive values, i.e. strings/numbers/Dates/user-defined types. */
-export type ValueFieldConfig<T, V> = {
+export type ValueFieldConfig<V> = {
     type: "value";
     rules?: Rule<V | null | undefined>[];
     /**
@@ -45,7 +42,7 @@ export type ValueFieldConfig<T, V> = {
     strictOrder?: false;
 };
 /** Field configuration for list values, i.e. `U` is `Book` in a form with `books: Book[]`. */
-export type ListFieldConfig<T, U> = {
+export type ListFieldConfig<U> = {
     type: "list";
     /** Rules that can run on the full list of children. */
     rules?: Rule<readonly ObjectState<U>[]>[];
@@ -71,4 +68,3 @@ export type ObjectFieldConfig<U> = {
     /** Config for the child's form state, i.e. each book. */
     config: ObjectConfig<U>;
 };
-export {};

package/dist/configBuilders.d.ts

@@ -0,0 +1,60 @@
+import { FragmentFieldConfig, ListFieldConfig, ObjectConfig, ValueFieldConfig } from "./config";
+import { Fragment, ObjectState } from "./fields/objectField";
+import { Rule } from "./rules";
+import { Builtin, OmitIf } from "./utils";
+/**
+ * Provides a Zod-ish API for building form configs.
+ */
+export declare const f: {
+    /** Creates the top-level config for a form, like an author or book. */
+    config<T>(fields: ObjectConfigBuilderFields<T>): ObjectConfig<T>;
+    /** Creates the config DSL for an object, like an author or book. */
+    object<T_1>(fields: ObjectConfigBuilderFields<T_1>): ObjectConfigBuilder<T_1>;
+    /** Creates the config DSL for an list of objects, like an author's list of books. */
+    list<U>(fields: ObjectConfigBuilderFields<U>): ListFieldConfigBuilder<U>;
+    /** Creates the config DSL for a primitive value, like a first name or phone number. */
+    value<V>(): ValueFieldConfigBuilder<V>;
+    /** A shorthand for creating a computed value. */
+    computed<V_1>(): ValueFieldConfigBuilder<V_1>;
+};
+/**
+ * Defines the fields that should be passed into `f.object({ ... })` for fhe form type `T`.
+ *
+ * This is basically a map of `key` in `T` to `f.value()`, `f.list()`, or `f.object()`
+ * DSL objects that define the runtime structure/fields of the form.
+ */
+export type ObjectConfigBuilderFields<T> = {
+    [P in keyof OmitIf<T, Function>]: T[P] extends Fragment<infer V> ? FragmentFieldConfigBuilder : T[P] extends Array<infer U> | null | undefined ? U extends Builtin ? ValueFieldConfigBuilder<T[P]> : ListFieldConfigBuilder<U> : ValueFieldConfigBuilder<T[P]> | ObjectConfigBuilder<T[P]>;
+};
+export interface FragmentFieldConfigBuilder {
+    build(): FragmentFieldConfig;
+}
+/** Provides a fluent DSL for building up an object's config. */
+export declare class ObjectConfigBuilder<T> {
+    private config;
+    constructor(fields: ObjectConfigBuilderFields<T>);
+    build(): ObjectConfig<T>;
+}
+/** Provides a fluent DSL for building up a value's config. */
+export declare class ValueFieldConfigBuilder<V> {
+    private config;
+    /** Marks the field as required. */
+    req(): this;
+    /** Marks the field as read only. */
+    readOnly(): this;
+    /** Appends `rules` to the field's validation rules. */
+    rules(rules: Rule<V | null | undefined>[]): this;
+    /** Marks the field as computed. */
+    computed(): this;
+    build(): ValueFieldConfig<V>;
+}
+/** Provides a fluent DSL for building up a list's config. */
+export declare class ListFieldConfigBuilder<U> {
+    private config;
+    constructor(fields: ObjectConfigBuilderFields<U>);
+    /** Appends `rule` to the field's validation rules. */
+    rule(rule: Rule<readonly ObjectState<U>[]>): this;
+    /** Appends `rules` to the field's validation rules. */
+    rules(rules: Rule<readonly ObjectState<U>[]>[]): this;
+    build(): ListFieldConfig<U>;
+}

package/dist/configBuilders.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ListFieldConfigBuilder = exports.ValueFieldConfigBuilder = exports.ObjectConfigBuilder = exports.f = void 0;
+const rules_1 = require("./rules");
+/**
+ * Provides a Zod-ish API for building form configs.
+ */
+exports.f = {
+    /** Creates the top-level config for a form, like an author or book. */
+    config(fields) {
+        return new ObjectConfigBuilder(fields).build();
+    },
+    /** Creates the config DSL for an object, like an author or book. */
+    object(fields) {
+        return new ObjectConfigBuilder(fields);
+    },
+    /** Creates the config DSL for an list of objects, like an author's list of books. */
+    list(fields) {
+        return new ListFieldConfigBuilder(fields);
+    },
+    /** Creates the config DSL for a primitive value, like a first name or phone number. */
+    value() {
+        return new ValueFieldConfigBuilder();
+    },
+    /** A shorthand for creating a computed value. */
+    computed() {
+        return this.value().computed();
+    },
+};
+/** Provides a fluent DSL for building up an object's config. */
+class ObjectConfigBuilder {
+    constructor(fields) {
+        this.config = {};
+        for (const [key, value] of Object.entries(fields)) {
+            this.config[key] = value.build();
+        }
+    }
+    build() {
+        return this.config;
+    }
+}
+exports.ObjectConfigBuilder = ObjectConfigBuilder;
+/** Provides a fluent DSL for building up a value's config. */
+class ValueFieldConfigBuilder {
+    constructor() {
+        this.config = { type: "value", rules: [] };
+    }
+    /** Marks the field as required. */
+    req() {
+        this.config.rules = [rules_1.required];
+        return this;
+    }
+    /** Marks the field as read only. */
+    readOnly() {
+        this.config.readOnly = true;
+        return this;
+    }
+    /** Appends `rules` to the field's validation rules. */
+    rules(rules) {
+        var _a;
+        var _b;
+        ((_a = (_b = this.config).rules) !== null && _a !== void 0 ? _a : (_b.rules = [])).push(...rules);
+        return this;
+    }
+    /** Marks the field as computed. */
+    computed() {
+        this.config.computed = true;
+        return this;
+    }
+    build() {
+        return this.config;
+    }
+}
+exports.ValueFieldConfigBuilder = ValueFieldConfigBuilder;
+/** Provides a fluent DSL for building up a list's config. */
+class ListFieldConfigBuilder {
+    constructor(fields) {
+        const config = {};
+        for (const [key, value] of Object.entries(fields)) {
+            config[key] = value.build();
+        }
+        this.config = { type: "list", rules: [], config };
+    }
+    /** Appends `rule` to the field's validation rules. */
+    rule(rule) {
+        var _a;
+        var _b;
+        ((_a = (_b = this.config).rules) !== null && _a !== void 0 ? _a : (_b.rules = [])).push(rule);
+        return this;
+    }
+    /** Appends `rules` to the field's validation rules. */
+    rules(rules) {
+        var _a;
+        var _b;
+        ((_a = (_b = this.config).rules) !== null && _a !== void 0 ? _a : (_b.rules = [])).push(...rules);
+        return this;
+    }
+    build() {
+        return this.config;
+    }
+}
+exports.ListFieldConfigBuilder = ListFieldConfigBuilder;

package/dist/fields/listField.d.ts

@@ -3,9 +3,9 @@ import { ObjectState } from "./objectField";
 import { FieldState } from "./valueField";
 import { Rule } from "../rules";
 /** Form state for list of children, i.e. `U` is a `Book` in a form with a `books: Book[]`. */
-export interface ListFieldState<U> extends Omit<FieldState<U[]>, "originalValue"> {
+export interface ListFieldState<U> extends FieldState<U[]> {
     readonly rows: ReadonlyArray<ObjectState<U>>;
     add(value: U, index?: number): void;
     remove(indexOrValue: number | U): void;
 }
-export declare function newListFieldState<T, K extends keyof T, U>(parentInstance: T, parentState: () => ObjectState<T>, key: K, rules: Rule<readonly ObjectState<U>[]>[], listConfig: ListFieldConfig<T, U>, config: ObjectConfig<U>, strictOrder: boolean, maybeAutoSave: () => void): ListFieldState<U>;
+export declare function newListFieldState<T, K extends keyof T, U>(parentCopy: T, parentInstance: T, parentState: () => ObjectState<T>, key: K, rules: Rule<readonly ObjectState<U>[]>[], listConfig: ListFieldConfig<U>, config: ObjectConfig<U>, strictOrder: boolean, maybeAutoSave: () => void): ListFieldState<U>;

package/dist/fields/listField.js

@@ -5,13 +5,20 @@ const mobx_1 = require("mobx");
 const objectField_1 = require("./objectField");
 const rules_1 = require("../rules");
 const utils_1 = require("../utils");
-function newListFieldState(parentInstance, parentState, key, rules, listConfig, config, strictOrder, maybeAutoSave) {
+function newListFieldState(parentCopy, parentInstance, parentState, key, rules, listConfig, config, strictOrder, maybeAutoSave) {
+    var _a;
     // Keep a map of "item in the parent list" -> "that item's ObjectState"
     const rowMap = new Map();
     const _tick = (0, mobx_1.observable)({ value: 1 });
+    const _originalValueTick = (0, mobx_1.observable)({ value: 1 });
     const _childTick = (0, mobx_1.observable)({ value: 1 });
-    // this is for dirty checking, not object identity
-    let originalCopy = [...(parentInstance[key] || [])];
+    // When child rows don't have ids (i.e. for new rows that aren't saved yet), we need an id-less
+    // "clone <-> current" map to tell if we're dirty or not, i.e. whether `parentInstance[key]` has
+    // drifted from `parentCopy[key]`
+    const copyMap = new Map();
+    ((_a = parentCopy[key]) !== null && _a !== void 0 ? _a : []).forEach((copy, i) => {
+        copyMap.set(copy, parentInstance[key][i]);
+    });
     const list = {
         key: key,
         // Our fundamental state of wrapped Us
@@ -46,22 +53,19 @@ function newListFieldState(parentInstance, parentState, key, rules, listConfig,
             return parentState().isNewEntity;
         },
         // private
+        /** Returns whether a row has been added/removed. */
         hasChanged() {
-            const [current, original] = [this.value || [], originalCopy || []];
-            if (current.length !== original.length) {
+            const [current, original] = [this.value || [], this.originalValue];
+            if (current.length !== original.length)
                 return true;
-            }
             if (strictOrder) {
-                return original.some((e, idx) => {
-                    const originalState = rowMap.get(e);
-                    const currentState = rowMap.get(current[idx]);
-                    return originalState !== currentState;
-                });
+                // With strict order, every copy[i] === original[i] must be true
+                return original.some((e, idx) => current[idx] !== copyMap.get(e));
+            }
+            else {
+                // With loose order, we just want every copy to still have its original somewhere
+                return !original.every((e) => current.includes(copyMap.get(e)));
             }
-            return !original.every((e) => {
-                const state = rowMap.get(e);
-                return current.some((e) => rowMap.get(e) === state);
-            });
         },
         // And we can derive each value's ObjectState wrapper as needed from the rowMap cache
         get rows() {
@@ -92,7 +96,7 @@ function newListFieldState(parentInstance, parentState, key, rules, listConfig,
         get valid() {
             const value = this.rows;
             // TODO Passing `originalCopy || []` is probably not 100% right
-            const opts = { value, key: key, originalValue: originalCopy || [], object: parentState() };
+            const opts = { value, key: key, originalValue: this.originalValue, object: parentState() };
             const collectionValid = this.rules.every((r) => r(opts) === undefined);
             const entriesValid = this.rows.filter((r) => !r._considerDeleted()).every((r) => r.valid);
             return collectionValid && entriesValid;
@@ -100,7 +104,7 @@ function newListFieldState(parentInstance, parentState, key, rules, listConfig,
         get errors() {
             if (_tick.value < 0)
                 (0, utils_1.fail)();
-            const opts = { value: this.rows, key: key, originalValue: originalCopy || [], object: parentState() };
+            const opts = { value: this.rows, key: key, originalValue: this.originalValue, object: parentState() };
             return this.rules.map((r) => r(opts)).filter(utils_1.isNotUndefined);
         },
         get changedValue() {
@@ -143,6 +147,11 @@ function newListFieldState(parentInstance, parentState, key, rules, listConfig,
             // We should be passed values that are non-proxies.
             parentInstance[key] = values.map((value) => {
                 let childState = rowMap.get(value);
+                // If we're being reverted to our originalValue, i.e. values is actually
+                // a list of copies, use the copyMap to recover our child states
+                if (!childState && copyMap.has(value)) {
+                    childState = rowMap.get(copyMap.get(value));
+                }
                 if (!childState) {
                     // Look for an existing child (requires having an id key configured)
                     for (const [, otherState] of rowMap.entries()) {
@@ -159,11 +168,12 @@ function newListFieldState(parentInstance, parentState, key, rules, listConfig,
                 // Return the already-observable'd value so that our `parent.value[key] = values` doesn't re-proxy things
                 return childState.value;
             });
+            // Make sure to tick first so that `setOriginalValue` sees the latest `rows`
+            _tick.value++;
             // Reset originalCopy so that our dirty checks have the right # of rows.
             if (opts.refreshing) {
-                originalCopy = [...(parentInstance[key] || [])];
+                this.setOriginalValue();
             }
-            _tick.value++;
         },
         add(value, spliceIndex) {
             // This is called by the user, so value should be a non-proxy value we should keep
@@ -189,16 +199,31 @@ function newListFieldState(parentInstance, parentState, key, rules, listConfig,
             maybeAutoSave();
         },
         revertChanges() {
-            if (originalCopy) {
-                this.set(originalCopy, { resetting: true });
-                this.rows.forEach((r) => r.revertChanges());
-            }
+            this.set(this.originalValue, { resetting: true });
+            this.rows.forEach((r) => r.revertChanges());
+            this.touched = false;
         },
         commitChanges() {
+            // Tell each child ObjectState to have its fields commit into its parentCopy
             this.rows.forEach((r) => r.commitChanges());
-            originalCopy = [...(parentInstance[key] || [])];
+            this.setOriginalValue();
+            this.touched = false;
             _tick.value++;
         },
+        get originalValue() {
+            // A dummy check to for reactivity around our non-proxy value
+            const value = _originalValueTick.value > -1 ? parentCopy[key] : parentCopy[key];
+            return value !== null && value !== void 0 ? value : [];
+        },
+        // This should only be called when value === originalValue
+        setOriginalValue() {
+            // Use the rows' originalValues to update the parentCopy
+            parentCopy[key] = this.rows.map((r) => r.originalValue);
+            parentCopy[key].forEach((copy, i) => {
+                copyMap.set(copy, parentInstance[key][i]);
+            });
+            _originalValueTick.value++;
+        },
         ensureSet() {
             if (!parentInstance[key]) {
                 parentInstance[key] = [];

package/dist/fields/objectField.d.ts

@@ -36,6 +36,7 @@ export type ObjectState<T> = FieldStates<T> & FieldState<T> & {
 };
 export type ObjectStateInternal<T> = ObjectState<T> & {
     set(value: T, opts?: InternalSetOpts): void;
+    isSameEntity(other: T): boolean;
 };
 declare const fragmentSym: unique symbol;
 export type Fragment<V> = V & {

package/dist/fields/objectField.js

@@ -34,20 +34,26 @@ function newObjectState(config, parentState, parentListState, instance, key, may
         }
         return proxy;
     }
+    // We directly mutate `instance` as the user edits the form, so keep a deep copy of the POJO.
+    // If the user passed us `instance` that was a mobx store/class, this originalValue won't really
+    // be a true match (i.e. pass instanceof), but it should be good enough
+    const originalCopy = (0, utils_1.deepClone)(instance);
     const objectConfig = config;
     const fieldStates = Object.entries(config).map(([_key, _config]) => {
-        var _a, _b;
+        var _a, _b, _c, _d;
         const key = _key;
         const config = _config;
         let field;
         if (config.type === "value") {
-            field = (0, valueField_1.newValueFieldState)(instance, getObjectState, key, config.rules || [], config.isIdKey ||
+            field = (0, valueField_1.newValueFieldState)(originalCopy, instance, getObjectState, key, config.rules || [], config.isIdKey ||
                 // Default the id key to "id" unless some other field has isIdKey set
                 (key === "id" &&
-                    !Object.entries(objectConfig).some(([other, c]) => other !== key && c.isIdKey)), config.isDeleteKey || false, config.isReadOnlyKey || false, config.computed || false, config.readOnly || false, (_a = config.strictOrder) !== null && _a !== void 0 ? _a : true, maybeAutoSave);
+                    !Object.entries(objectConfig).some(([other, c]) => other !== key && c.isIdKey)), config.isDeleteKey || false, config.isReadOnlyKey || false, (_a = config.computed) !== null && _a !== void 0 ? _a : 
+            // If instance is a mobx class, we can detect computeds as they won't be enumerable
+            ((0, mobx_1.isObservable)(instance) ? !(key in originalCopy) : false), (_b = config.readOnly) !== null && _b !== void 0 ? _b : false, (_c = config.strictOrder) !== null && _c !== void 0 ? _c : true, maybeAutoSave);
         }
         else if (config.type === "list") {
-            field = (0, listField_1.newListFieldState)(instance, getObjectState, key, config.rules || [], config, config.config, (_b = config.strictOrder) !== null && _b !== void 0 ? _b : true, maybeAutoSave);
+            field = (0, listField_1.newListFieldState)(originalCopy, instance, getObjectState, key, config.rules || [], config, config.config, (_d = config.strictOrder) !== null && _d !== void 0 ? _d : true, maybeAutoSave);
         }
         else if (config.type === "object") {
             if (!instance[key]) {
@@ -176,7 +182,8 @@ function newObjectState(config, parentState, parentListState, instance, key, may
             return result;
         },
         get originalValue() {
-            return instance;
+            getFields(proxy).map((f) => f.originalValue);
+            return originalCopy;
         },
         // An internal helper method to see if `other` is for "the same entity" as our current row
         isSameEntity(other) {
@@ -184,7 +191,9 @@ function newObjectState(config, parentState, parentListState, instance, key, may
             if (!idField) {
                 return false;
             }
-            return this[idField.key].value === other[idField.key];
+            // If the otherIdValue is undefined, it's a new entity so can't be the same as us
+            const otherIdValue = other[idField.key];
+            return otherIdValue !== undefined && otherIdValue === this[idField.key].value;
         },
     };
     proxy = (0, mobx_1.makeAutoObservable)(obj, {
@@ -193,6 +202,7 @@ function newObjectState(config, parentState, parentListState, instance, key, may
         // to mobx this looks like the value never changes, and it will never invoke observers
         // even with our tick-based hacks.
         value: (0, mobx_1.computed)({ equals: () => false }),
+        originalValue: (0, mobx_1.computed)({ equals: () => false }),
     });
     // Any time a field changes, percolate that change up to us
     (0, mobx_1.reaction)(() => getFields(proxy).map((f) => f.value), () => _tick.value++);

package/dist/fields/valueField.d.ts

@@ -11,7 +11,9 @@ import { Rule } from "../rules";
  * i.e. text boxes, can always be cleared out/deleted.
  */
 export interface FieldState<V> {
+    /** The key in the parent object, i.e. `firstName` in `author: { firstName: string }`. */
     readonly key: string;
+    /** The current value of the field. */
     value: V;
     readonly originalValue: V;
     touched: boolean;
@@ -69,4 +71,4 @@ export interface FieldStateInternal<T, V> extends FieldState<V> {
     _isReadOnlyKey: boolean;
     _focused: boolean;
 }
-export declare function newValueFieldState<T, K extends keyof T>(parentInstance: T, parentState: () => ObjectState<T>, key: K, rules: Rule<T[K] | null | undefined>[], isIdKey: boolean, isDeleteKey: boolean, isReadOnlyKey: boolean, computed: boolean, readOnly: boolean, strictOrder: boolean, maybeAutoSave: () => void): FieldState<T[K] | null | undefined>;
+export declare function newValueFieldState<T, K extends keyof T>(parentCopy: T, parentInstance: T, parentState: () => ObjectState<T>, key: K, rules: Rule<T[K] | null | undefined>[], isIdKey: boolean, isDeleteKey: boolean, isReadOnlyKey: boolean, computed: boolean, readOnly: boolean, strictOrder: boolean, maybeAutoSave: () => void): FieldState<T[K] | null | undefined>;

package/dist/fields/valueField.js

@@ -6,10 +6,7 @@ const mobx_1 = require("mobx");
 const proxies_1 = require("../proxies");
 const rules_1 = require("../rules");
 const utils_1 = require("../utils");
-function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, isDeleteKey, isReadOnlyKey, computed, readOnly, strictOrder, maybeAutoSave) {
-    // keep a copy here for reference equality
-    const value = parentInstance[key];
-    let _originalValue = value === null ? undefined : (0, is_plain_object_1.isPlainObject)(value) ? (0, mobx_1.toJS)(value) : value;
+function newValueFieldState(parentCopy, parentInstance, parentState, key, rules, isIdKey, isDeleteKey, isReadOnlyKey, computed, readOnly, strictOrder, maybeAutoSave) {
     // Because we read/write the value directly back into parentInstance[key],
     // which itself is not a proxy, we use this as our "value changed" trigger.
     const _tick = (0, mobx_1.observable)({ value: 1 });
@@ -31,7 +28,7 @@ function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, is
             // Re-create the `keepNull` logic on sets but for our initial read where our
             // originalValue is null (empty) but we want to expose it as undefined for
             // consistency of "empty-ness" to our UI components.
-            return value === null && (0, utils_1.isEmpty)(_originalValue) ? undefined : value;
+            return value === null && (0, utils_1.isEmpty)(parentCopy[key]) ? undefined : value;
         },
         set value(v) {
             this.set(v);
@@ -94,7 +91,7 @@ function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, is
             if (opts.refreshing && this.dirty && this.value !== value) {
                 // Ignore incoming values if we have changes (this.dirty) unless our latest change (this.value)
                 // matches the incoming value (value), b/c if it does we should accept it and reset originalValue
-                // so that we're not longer dirty.
+                // so that we're no longer dirty.
                 return;
             }
             else if (computed && (opts.resetting || opts.refreshing)) {
@@ -140,12 +137,14 @@ function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, is
         },
         get originalValue() {
             // A dummy check to for reactivity around our non-proxy value
-            const value = _originalValueTick.value > -1 ? _originalValue : _originalValue;
+            const value = _originalValueTick.value > -1 ? parentCopy[key] : parentCopy[key];
             // Re-create the `keepNull` logic so that `.value` === `.originalValue`
             return value === null ? undefined : value;
         },
         set originalValue(v) {
-            _originalValue = v;
+            const canSkip = v === undefined && !(key in parentCopy);
+            if (!canSkip)
+                parentCopy[key] = v;
             _originalValueTick.value++;
         },
         maybeTrim() {

package/dist/formState.test.d.ts

@@ -1 +1,11 @@
-export {};
+export declare class ObservableObject {
+    firstName: string | undefined;
+    lastName: string | undefined;
+    age?: number | undefined;
+    constructor();
+    get fullName(): string;
+    set fullName(fullName: string);
+    toInput(): {
+        firstName: string | undefined;
+    };
+}

package/dist/formState.test.js

@@ -1,55 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.ObservableObject = void 0;
 const mobx_1 = require("mobx");
+const configBuilders_1 = require("./configBuilders");
 const objectField_1 = require("./fields/objectField");
 const formStateDomain_1 = require("./formStateDomain");
 const rules_1 = require("./rules");
-describe("mobx behavior", () => {
-    it("mobx batches if in actions", () => {
-        const a = (0, mobx_1.observable)({ name: "a1" });
-        const b = (0, mobx_1.observable)({ name: "b1" });
-        const map = new mobx_1.ObservableMap();
-        map.set("a", a);
-        map.set("b", b);
-        let runs = 0;
-        (0, mobx_1.autorun)(() => {
-            noop([...map.values()].filter((v) => v.name.includes("1")));
-            runs++;
-        });
-        expect(runs).toBe(1);
-        // When we change both a and b
-        (0, mobx_1.runInAction)(() => {
-            a.name = "a11";
-            b.name = "b2";
-        });
-        // Then the reaction waited and only ran once
-        expect(runs).toBe(2);
-    });
-    it("mobx can watch undefined keys", () => {
-        const a = new ObservableObject();
-        const b = new ObservableObject();
-        const map = new mobx_1.ObservableMap();
-        map.set("a", a);
-        map.set("b", b);
-        let runs = 0;
-        (0, mobx_1.autorun)(() => {
-            noop([...map.values()].map((a) => a.age));
-            runs++;
-        });
-        expect(runs).toBe(1);
-        b.age = 1;
-        expect(runs).toBe(2);
-    });
-    it("mobx lists maintain observable identity", () => {
-        // given a parent observable
-        const a = (0, mobx_1.observable)({ list: [] });
-        // if we observable-ize a value being pushing it on the list
-        const c1 = (0, mobx_1.observable)({});
-        a.list.push(c1);
-        // then we get identify equality on the list lookups
-        expect(a.list[0] === c1).toEqual(true);
-    });
-});
 describe("formState", () => {
     it("can create a simple object", () => {
         const a = (0, objectField_1.createObjectState)({ title: { type: "value", rules: [rules_1.required] } }, {});
@@ -156,7 +112,8 @@ describe("formState", () => {
         const a1 = { firstName: "a1" };
         const state = createAuthorInputState(a1);
         state.firstName.set("a2");
-        expect(state.originalValue === a1).toEqual(true);
+        expect(state.value === a1).toEqual(true);
+        expect(state.originalValue !== a1).toEqual(true);
         expect(a1.firstName).toEqual("a2");
     });
     it("maintains object identity of lists", () => {
@@ -166,11 +123,11 @@ describe("formState", () => {
         const state = createAuthorInputState(a1);
         const b2 = { title: "t2" };
         state.books.add(b2);
-        expect(state.originalValue.books === a1.books).toEqual(true);
+        expect(state.value.books === a1.books).toEqual(true);
         expect(state.books.value.length).toEqual(2);
         expect((_a = a1.books) === null || _a === void 0 ? void 0 : _a.length).toEqual(2);
-        expect(state.books.rows[0].originalValue === b1).toEqual(true);
-        expect(state.books.rows[1].originalValue === b2).toEqual(true);
+        expect(state.books.rows[0].value === b1).toEqual(true);
+        expect(state.books.rows[1].value === b2).toEqual(true);
         expect(a1.books[1] === b2).toEqual(true);
     });
     it("can add items anywhere within a list", () => {
@@ -185,14 +142,14 @@ describe("formState", () => {
         });
         const b2 = { title: "t2" };
         state.books.add(b2, 0);
-        expect(state.books.rows[0].originalValue === b2).toEqual(true);
-        expect(state.books.rows[1].originalValue === b1).toEqual(true);
+        expect(state.books.rows[0].value === b2).toEqual(true);
+        expect(state.books.rows[1].value === b1).toEqual(true);
         expect(ticks).toEqual(2);
         const b3 = { title: "t3" };
         state.books.add(b3, 1);
-        expect(state.books.rows[0].originalValue === b2).toEqual(true);
-        expect(state.books.rows[1].originalValue === b3).toEqual(true);
-        expect(state.books.rows[2].originalValue === b1).toEqual(true);
+        expect(state.books.rows[0].value === b2).toEqual(true);
+        expect(state.books.rows[1].value === b3).toEqual(true);
+        expect(state.books.rows[2].value === b1).toEqual(true);
         expect(ticks).toEqual(3);
     });
     it("list value can observe changes", () => {
@@ -208,6 +165,34 @@ describe("formState", () => {
         state.books.add({ title: "t2" }, 0);
         expect(ticks).toEqual(2);
     });
+    it("list originalValue can observe changes", () => {
+        const b1 = { title: "t1" };
+        const a1 = { firstName: "a1", books: [b1] };
+        const state = createAuthorInputState(a1);
+        let books;
+        let ticks = 0;
+        (0, mobx_1.autorun)(() => {
+            books = state.books.originalValue;
+            ticks++;
+        });
+        state.books.add({ title: "t2" }, 0);
+        expect(ticks).toEqual(1);
+        state.commitChanges();
+        expect(ticks).toEqual(2);
+    });
+    it("state originalValue can observe changes", () => {
+        const a1 = { firstName: "a1", books: [] };
+        const state = createAuthorInputState(a1);
+        let ticks = 0;
+        (0, mobx_1.autorun)(() => {
+            noop(state.originalValue);
+            ticks++;
+        });
+        state.books.add({ title: "t2" }, 0);
+        expect(ticks).toEqual(1);
+        state.commitChanges();
+        expect(ticks).toEqual(2);
+    });
     it("maintains unknown fields", () => {
         // Given the form is not directly editing id fields
         const config = {
@@ -221,9 +206,8 @@ describe("formState", () => {
         state.firstName.set("a2");
         state.books.add({ title: "t2" });
         // When we get back the originalValue
-        const a2 = state.originalValue;
         // Then it has the ids and the new values
-        expect(a2).toMatchObject({
+        expect(state.value).toMatchObject({
             id: "1",
             books: [{ id: "2", title: "t1" }, { title: "t2" }],
         });
@@ -644,8 +628,8 @@ describe("formState", () => {
             firstName: "a1",
             lastName: "aL1",
             books: [
-                { title: "b1", classification: formStateDomain_1.dd100 },
-                { title: "b2", classification: formStateDomain_1.dd100 },
+                { id: "b:1", title: "b1", classification: formStateDomain_1.dd100 },
+                { id: "b:2", title: "b2", classification: formStateDomain_1.dd100 },
             ],
         });
         // And some values have been changed
@@ -722,7 +706,7 @@ describe("formState", () => {
         a1.firstName.value = "";
         // Then we keep it as null
         expect(a1.firstName.value).toBeNull();
-        expect(a1.originalValue.firstName).toBeNull();
+        expect(a1.originalValue.firstName).toBe("asdf");
         expect(a1.firstName.dirty).toBeTruthy();
     });
     it("initializes null values to be undefined", () => {
@@ -968,6 +952,15 @@ describe("formState", () => {
         // Throw away assertion, test is making sure ^ line compiles
         expect(config).toBeDefined();
     });
+    it("supports observable objects with helper methods in the config DSL", () => {
+        const config = configBuilders_1.f.config({
+            firstName: configBuilders_1.f.value(),
+            lastName: configBuilders_1.f.value(),
+            fullName: configBuilders_1.f.computed(),
+        });
+        // Throw away assertion, test is making sure ^ line compiles
+        expect(config).toBeDefined();
+    });
     it("can reset observable objects with computeds", () => {
         const formState = (0, objectField_1.createObjectState)({
             firstName: { type: "value" },
@@ -1111,6 +1104,45 @@ describe("formState", () => {
             id: "a:1",
             books: [{ id: "b:1", title: "t1b" }, { id: "b:2" }],
         });
+        // And add a 3rd new book
+        formState.books.add({ title: "t3" });
+        // Then we get the author id (for updates) and all 3 books
+        expect(formState.changedValue).toEqual({
+            id: "a:1",
+            books: [{ id: "b:1", title: "t1b" }, { id: "b:2" }, { title: "t3" }],
+        });
+        // And we can still get the original value
+        expect(formState.originalValue).toEqual({
+            id: "a:1",
+            firstName: "f",
+            books: [
+                { id: "b:1", title: "t1" },
+                { id: "b:2", title: "t2" },
+            ],
+        });
+        // And the books.originalValue as well
+        expect(formState.books.originalValue).toEqual([
+            { id: "b:1", title: "t1" },
+            { id: "b:2", title: "t2" },
+        ]);
+        // And when we commit changes
+        formState.commitChanges();
+        // Then our originalValue reflects the commit
+        expect(formState.originalValue).toEqual({
+            id: "a:1",
+            firstName: "f",
+            books: [
+                { id: "b:1", title: "t1b" },
+                { id: "b:2", title: "t2" },
+                { id: undefined, title: "t3" },
+            ],
+        });
+        // And the books.originalValue as well
+        expect(formState.books.originalValue).toEqual([
+            { id: "b:1", title: "t1b" },
+            { id: "b:2", title: "t2" },
+            { title: "t3" },
+        ]);
     });
     it("can return only changed but incremental list fields", () => {
         // Given an author
@@ -1512,19 +1544,17 @@ class ObservableObject {
         return { firstName: this.firstName };
     }
 }
-const authorWithBooksConfig = {
-    id: { type: "value" },
-    firstName: { type: "value" },
-    lastName: { type: "value" },
-    books: {
-        type: "list",
-        config: {
-            id: { type: "value" },
-            title: { type: "value", rules: [rules_1.required] },
-            classification: { type: "value" },
-        },
-    },
-};
+exports.ObservableObject = ObservableObject;
+const authorWithBooksConfig = configBuilders_1.f.config({
+    id: configBuilders_1.f.value(),
+    firstName: configBuilders_1.f.value(),
+    lastName: configBuilders_1.f.value(),
+    books: configBuilders_1.f.list({
+        id: configBuilders_1.f.value(),
+        title: configBuilders_1.f.value().req(),
+        classification: configBuilders_1.f.value(),
+    }),
+});
 function createAuthorInputState(input, maybeAutoSave) {
     return (0, objectField_1.createObjectState)(authorWithBooksConfig, input, { maybeAutoSave });
 }
@@ -1540,27 +1570,42 @@ const authorWithAddressConfig = {
         },
     },
 };
-const authorWithAddressAndBooksConfig = {
-    id: { type: "value" },
-    firstName: { type: "value" },
-    lastName: { type: "value" },
-    address: {
-        type: "object",
-        config: {
-            id: { type: "value" },
-            street: { type: "value", rules: [rules_1.required] },
-            city: { type: "value" },
-        },
-    },
-    books: {
-        type: "list",
-        config: {
-            id: { type: "value" },
-            title: { type: "value", rules: [rules_1.required] },
-            classification: { type: "value" },
-        },
-    },
-};
+const authorWithAddressAndBooksConfig = configBuilders_1.f.config({
+    id: configBuilders_1.f.value(),
+    firstName: configBuilders_1.f.value(),
+    lastName: configBuilders_1.f.value(),
+    address: configBuilders_1.f.object({
+        id: configBuilders_1.f.value(),
+        street: configBuilders_1.f.value().rules([rules_1.required]),
+        city: configBuilders_1.f.value(),
+    }),
+    books: configBuilders_1.f.list({
+        id: configBuilders_1.f.value(),
+        title: configBuilders_1.f.value(),
+        classification: configBuilders_1.f.value(),
+    }),
+});
+// const authorWithAddressAndBooksConfig: ObjectConfig<AuthorInput> = {
+//   id: { type: "value" },
+//   firstName: { type: "value" },
+//   lastName: { type: "value" },
+//   address: {
+//     type: "object",
+//     config: {
+//       id: { type: "value" },
+//       street: { type: "value", rules: [required] },
+//       city: { type: "value" },
+//     },
+//   },
+//   books: {
+//     type: "list",
+//     config: {
+//       id: { type: "value" },
+//       title: { type: "value", rules: [required] },
+//       classification: { type: "value" },
+//     },
+//   },
+// };
 function createAuthorWithAddressInputState(input) {
     return (0, objectField_1.createObjectState)(authorWithAddressConfig, input);
 }

package/dist/index.d.ts

@@ -1,4 +1,5 @@
 export { ObjectConfig } from "./config";
+export { f } from "./configBuilders";
 export { ListFieldState } from "./fields/listField";
 export { ObjectState, createObjectState } from "./fields/objectField";
 export { FieldState, ValueAdapter } from "./fields/valueField";

package/dist/index.js

@@ -1,6 +1,8 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useFormStates = exports.useFormState = exports.required = exports.createObjectState = void 0;
+exports.useFormStates = exports.useFormState = exports.required = exports.createObjectState = exports.f = void 0;
+var configBuilders_1 = require("./configBuilders");
+Object.defineProperty(exports, "f", { enumerable: true, get: function () { return configBuilders_1.f; } });
 var objectField_1 = require("./fields/objectField");
 Object.defineProperty(exports, "createObjectState", { enumerable: true, get: function () { return objectField_1.createObjectState; } });
 var rules_1 = require("./rules");

package/dist/mobx-behavior.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/mobx-behavior.test.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const mobx_1 = require("mobx");
+const formState_test_1 = require("./formState.test");
+describe("mobx behavior", () => {
+    it("mobx batches if in actions", () => {
+        const a = (0, mobx_1.observable)({ name: "a1" });
+        const b = (0, mobx_1.observable)({ name: "b1" });
+        const map = new mobx_1.ObservableMap();
+        map.set("a", a);
+        map.set("b", b);
+        let runs = 0;
+        (0, mobx_1.autorun)(() => {
+            noop([...map.values()].filter((v) => v.name.includes("1")));
+            runs++;
+        });
+        expect(runs).toBe(1);
+        // When we change both a and b
+        (0, mobx_1.runInAction)(() => {
+            a.name = "a11";
+            b.name = "b2";
+        });
+        // Then the reaction waited and only ran once
+        expect(runs).toBe(2);
+    });
+    it("mobx can watch undefined keys", () => {
+        const a = new formState_test_1.ObservableObject();
+        const b = new formState_test_1.ObservableObject();
+        const map = new mobx_1.ObservableMap();
+        map.set("a", a);
+        map.set("b", b);
+        let runs = 0;
+        (0, mobx_1.autorun)(() => {
+            noop([...map.values()].map((a) => a.age));
+            runs++;
+        });
+        expect(runs).toBe(1);
+        b.age = 1;
+        expect(runs).toBe(2);
+    });
+    it("mobx lists maintain observable identity", () => {
+        // given a parent observable
+        const a = (0, mobx_1.observable)({ list: [] });
+        // if we observable-ize a value being pushing it on the list
+        const c1 = (0, mobx_1.observable)({});
+        a.list.push(c1);
+        // then we get identify equality on the list lookups
+        expect(a.list[0] === c1).toEqual(true);
+    });
+});
+function noop(t) { }

package/dist/stackoverlfow.d.ts

@@ -0,0 +1,17 @@
+declare const c: {
+    value<V>(): ValueConfig<V>;
+};
+type Config<T> = {
+    [P in keyof T]: ValueConfig<T[P]>;
+};
+declare function config<T>(object: Config<T>): void;
+interface ValueConfig<V> {
+    req(): ValueConfig<V>;
+    readOnly(): ValueConfig<V>;
+    validate(fn: (value: V) => boolean): ValueConfig<V>;
+}
+type Author = {
+    name: string;
+    address: string;
+    city: string;
+};

package/dist/stackoverlfow.js

@@ -0,0 +1,17 @@
+"use strict";
+// Create a Zod-style fluent DSL for building config
+const c = {
+    value() {
+        return null;
+    },
+};
+function config(object) { }
+// Try and configure the author
+config({
+    // correctly inferred as c.value<string> --> ValueConfig<string>
+    name: c.value(),
+    // inferred only as c.value<unknown> --> ValueConfig<unknown>
+    address: c.value().req(),
+    // compile error, v is implicitly typed as any
+    city: c.value().validate((v) => v.length > 0),
+});

package/dist/useFormStates.js

@@ -64,7 +64,9 @@ 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), { refreshing: true });
+            form.set((0, utils_1.initValue)(config, map ? { map, input } : input), {
+                refreshing: true,
+            });
             existing[1] = input;
         }
         form.readOnly = readOnlyRef.current || !!opts.readOnly;

package/dist/utils.d.ts

@@ -8,6 +8,9 @@ export type Primitive = undefined | null | boolean | string | number | Function
 export type DeepRequired<T> = T extends Primitive ? T : {
     [P in keyof Required<T>]: T[P] extends Array<infer U> ? Array<DeepRequired<U>> : T[P] extends ReadonlyArray<infer U2> ? ReadonlyArray<DeepRequired<U2>> : DeepRequired<T[P]>;
 };
+export type OmitIf<Base, Condition> = Pick<Base, {
+    [Key in keyof Base]: Base[Key] extends Condition ? never : Key;
+}[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. */
@@ -41,3 +44,5 @@ export declare function areEqual<T>(a?: T, b?: T, strictOrder?: boolean): boolea
 export declare function hasToJSON(o?: unknown): o is {
     toJSON(): void;
 };
+/** Make a clone of `obj`, but only recurse into POJOs and Arrays...and stores. */
+export declare function deepClone<T>(obj: T, map?: WeakMap<WeakKey, any>): T;

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.isQuery = exports.isInput = exports.initValue = exports.assertNever = exports.fail = void 0;
+exports.deepClone = 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");
@@ -126,3 +126,18 @@ function hasToJSON(o) {
     return !!(o && typeof o === "object" && "toJSON" in o);
 }
 exports.hasToJSON = hasToJSON;
+/** Make a clone of `obj`, but only recurse into POJOs and Arrays...and stores. */
+function deepClone(obj, map = new WeakMap()) {
+    if (obj && typeof obj === "object" && ((0, is_plain_object_1.isPlainObject)(obj) || Array.isArray(obj) || (0, mobx_1.isObservable)(obj))) {
+        if (map.has(obj))
+            return map.get(obj);
+        const result = Array.isArray(obj) ? [] : {};
+        map.set(obj, result);
+        Object.assign(result, ...Object.keys(obj).map((key) => ({ [key]: deepClone(obj[key], map) })));
+        return result;
+    }
+    else {
+        return obj;
+    }
+}
+exports.deepClone = deepClone;

package/package.json

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