@homebound/form-state 2.22.5 → 2.23.0

package/dist/config.d.ts

@@ -65,6 +65,8 @@ export type ListFieldConfig<U> = {
 };
 export type ObjectFieldConfig<U> = {
     type: "object";
+    /** Marks an object as a reference, which means we'll only include it's `id` in `changedValue` output. */
+    reference?: boolean;
     /** Config for the child's form state, i.e. each book. */
     config: ObjectConfig<U>;
 };

package/dist/configBuilders.d.ts

@@ -1,4 +1,4 @@
-import { FragmentFieldConfig, ListFieldConfig, ObjectConfig, ValueFieldConfig } from "./config";
+import { FragmentFieldConfig, ListFieldConfig, ObjectConfig, ObjectFieldConfig, ValueFieldConfig } from "./config";
 import { Fragment, ObjectState } from "./fields/objectField";
 import { Rule } from "./rules";
 import { Builtin, OmitIf } from "./utils";
@@ -14,8 +14,12 @@ export declare const f: {
     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 shortcut for creating a child object with a single `id` key. */
+    reference<V_1 extends {
+        id?: unknown;
+    }>(fields?: ObjectConfigBuilderFields<V_1> | undefined): ObjectConfigBuilder<V_1>;
     /** A shorthand for creating a computed value. */
-    computed<V_1>(): ValueFieldConfigBuilder<V_1>;
+    computed<V_2>(): ValueFieldConfigBuilder<V_2>;
 };
 /**
  * Defines the fields that should be passed into `f.object({ ... })` for fhe form type `T`.
@@ -33,7 +37,8 @@ export interface FragmentFieldConfigBuilder {
 export declare class ObjectConfigBuilder<T> {
     private config;
     constructor(fields: ObjectConfigBuilderFields<T>);
-    build(): ObjectConfig<T>;
+    ref(): this;
+    build(): ObjectFieldConfig<T>;
 }
 /** Provides a fluent DSL for building up a value's config. */
 export declare class ValueFieldConfigBuilder<V> {

package/dist/configBuilders.js

@@ -8,7 +8,7 @@ const rules_1 = require("./rules");
 exports.f = {
     /** Creates the top-level config for a form, like an author or book. */
     config(fields) {
-        return new ObjectConfigBuilder(fields).build();
+        return new ObjectConfigBuilder(fields).build().config;
     },
     /** Creates the config DSL for an object, like an author or book. */
     object(fields) {
@@ -22,6 +22,10 @@ exports.f = {
     value() {
         return new ValueFieldConfigBuilder();
     },
+    /** A shortcut for creating a child object with a single `id` key. */
+    reference(fields) {
+        return exports.f.object({ id: exports.f.value(), ...fields }).ref();
+    },
     /** A shorthand for creating a computed value. */
     computed() {
         return this.value().computed();
@@ -30,11 +34,15 @@ exports.f = {
 /** Provides a fluent DSL for building up an object's config. */
 class ObjectConfigBuilder {
     constructor(fields) {
-        this.config = {};
+        this.config = { type: "object", config: {} };
         for (const [key, value] of Object.entries(fields)) {
-            this.config[key] = value.build();
+            this.config.config[key] = value.build();
         }
     }
+    ref() {
+        this.config.reference = true;
+        return this;
+    }
     build() {
         return this.config;
     }

package/dist/configBuilders.test.d.ts

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

package/dist/configBuilders.test.js

@@ -0,0 +1,65 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const configBuilders_1 = require("./configBuilders");
+describe("config", () => {
+    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("supports nested objects", () => {
+        const config = configBuilders_1.f.config({
+            id: configBuilders_1.f.value(),
+            address: configBuilders_1.f.object({ id: configBuilders_1.f.value() }),
+        });
+        expect(config).toMatchInlineSnapshot(`
+      {
+        "address": {
+          "config": {
+            "id": {
+              "rules": [],
+              "type": "value",
+            },
+          },
+          "type": "object",
+        },
+        "id": {
+          "rules": [],
+          "type": "value",
+        },
+      }
+    `);
+    });
+    it("supports Reference alias", () => {
+        const config = configBuilders_1.f.config({
+            id: configBuilders_1.f.value(),
+            address: configBuilders_1.f.reference({ name: configBuilders_1.f.value() }),
+        });
+        expect(config).toMatchInlineSnapshot(`
+      {
+        "address": {
+          "config": {
+            "id": {
+              "rules": [],
+              "type": "value",
+            },
+            "name": {
+              "rules": [],
+              "type": "value",
+            },
+          },
+          "reference": true,
+          "type": "object",
+        },
+        "id": {
+          "rules": [],
+          "type": "value",
+        },
+      }
+    `);
+    });
+});

package/dist/fields/listField.d.ts

@@ -1,4 +1,4 @@
-import { ListFieldConfig, ObjectConfig } from "../config";
+import { ListFieldConfig, ObjectFieldConfig } from "../config";
 import { ObjectState } from "./objectField";
 import { FieldState } from "./valueField";
 import { Rule } from "../rules";
@@ -8,4 +8,4 @@ export interface ListFieldState<U> extends FieldState<U[]> {
     add(value: U, index?: number): void;
     remove(indexOrValue: number | U): void;
 }
-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>;
+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: ObjectFieldConfig<U>, strictOrder: boolean, maybeAutoSave: () => void): ListFieldState<U>;

package/dist/fields/listField.js

@@ -41,7 +41,7 @@ function newListFieldState(parentCopy, parentInstance, parentState, key, rules,
         }
         // If we didn't have an existing child, just make a new object state
         if (!childState) {
-            childState = (0, objectField_1.newObjectState)(config, parentState, list, child, undefined, maybeAutoSave);
+            childState = (0, objectField_1.newObjectState)(config, parentState, undefined, list, child, undefined, maybeAutoSave);
             rowMap.set(child, childState);
         }
         return childState;
@@ -181,7 +181,8 @@ function newListFieldState(parentCopy, parentInstance, parentState, key, rules,
         },
         add(value, spliceIndex) {
             // This is called by the user, so value should be a non-proxy value we should keep
-            const childState = (0, objectField_1.createObjectState)(config, value, { maybeAutoSave });
+            const childState = getOrCreateChildState(value);
+            // const childState = createObjectState(config, value, { maybeAutoSave }) as ObjectStateInternal<U>;
             rowMap.set(value, childState);
             this.ensureSet();
             this.value.splice(typeof spliceIndex === "number" ? spliceIndex : this.value.length, 0, childState.value);

package/dist/fields/objectField.d.ts

@@ -1,4 +1,4 @@
-import { ObjectConfig } from "../config";
+import { ObjectConfig, ObjectFieldConfig } from "../config";
 import { FragmentField } from "./fragmentField";
 import { ListFieldState } from "./listField";
 import { FieldState, InternalSetOpts, SetOpts } from "./valueField";
@@ -57,5 +57,6 @@ type FieldStates<T> = {
 export declare function createObjectState<T>(config: ObjectConfig<T>, instance: T, opts?: {
     maybeAutoSave?: () => void;
 }): ObjectState<T>;
-export declare function newObjectState<T, P = any>(config: ObjectConfig<T>, parentState: (() => ObjectState<P>) | undefined, parentListState: FieldState<any> | undefined, instance: T, key: keyof T | undefined, maybeAutoSave: () => void): ObjectState<T>;
+/** A more internal version of `createObjectState`. */
+export declare function newObjectState<T, P = any>(config: ObjectFieldConfig<T>, parentState: (() => ObjectState<P>) | undefined, parentInstance: P | undefined, parentListState: FieldState<any> | undefined, instance: T, key: keyof T | undefined, maybeAutoSave: () => void): ObjectState<T>;
 export {};

package/dist/fields/objectField.js

@@ -20,10 +20,11 @@ exports.fragment = fragment;
  */
 function createObjectState(config, instance, opts = {}) {
     const noop = () => { };
-    return newObjectState(config, undefined, undefined, instance, undefined, opts.maybeAutoSave || noop);
+    return newObjectState({ type: "object", config }, undefined, undefined, undefined, instance, undefined, opts.maybeAutoSave || noop);
 }
 exports.createObjectState = createObjectState;
-function newObjectState(config, parentState, parentListState, instance, key, maybeAutoSave) {
+/** A more internal version of `createObjectState`. */
+function newObjectState(config, parentState, parentInstance, parentListState, instance, key, maybeAutoSave) {
     // This is what we return, but we only know it's value until we call `observable`, so
     // we create a mutable variable to capture it so that we can create fields/call their
     // constructors and give them a way to access it later.
@@ -38,8 +39,8 @@ function newObjectState(config, parentState, parentListState, instance, key, may
     // 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]) => {
+    const objectConfig = config.config;
+    const fieldStates = Object.entries(objectConfig).map(([_key, _config]) => {
         var _a, _b, _c, _d;
         const key = _key;
         const config = _config;
@@ -53,26 +54,26 @@ function newObjectState(config, parentState, parentListState, instance, key, may
             ((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)(originalCopy, instance, getObjectState, key, config.rules || [], config, config.config, (_d = config.strictOrder) !== null && _d !== void 0 ? _d : true, maybeAutoSave);
+            field = (0, listField_1.newListFieldState)(originalCopy, instance, getObjectState, key, config.rules || [], config, { type: "object", config: config.config }, (_d = config.strictOrder) !== null && _d !== void 0 ? _d : true, maybeAutoSave);
         }
         else if (config.type === "object") {
             if (!instance[key]) {
                 instance[key] = {};
             }
-            field = newObjectState(config.config, getObjectState, undefined, instance[key], key, maybeAutoSave);
+            field = newObjectState(config, getObjectState, instance, undefined, instance[key], key, maybeAutoSave);
         }
         else if (config.type === "fragment") {
             field = (0, fragmentField_1.newFragmentField)(instance, key);
         }
         else {
-            throw new Error("Unsupported");
+            throw new Error(`Invalid type value ${config.type}`);
         }
         return [key, field];
     });
     // 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 = (0, mobx_1.observable)({ value: 1 });
-    const fieldNames = Object.keys(config);
+    const fieldNames = Object.keys(objectConfig);
     function getFields(proxyThis) {
         return fieldNames.map((name) => proxyThis[name]);
     }
@@ -87,6 +88,7 @@ function newObjectState(config, parentState, parentListState, instance, key, may
             this.set(value);
         },
         // private
+        _kind: "object",
         _readOnly: false,
         _loading: false,
         _considerDeleted() {
@@ -128,7 +130,7 @@ function newObjectState(config, parentState, parentListState, instance, key, may
             return getFields(this).flatMap((f) => f.errors.map((e) => `${f.key}: ${e}`));
         },
         get dirty() {
-            return getFields(this).some((f) => f.dirty);
+            return getFields(this).some((f) => f.dirty) || this.isUnset();
         },
         get isNewEntity() {
             const idField = getFields(this).find((f) => f._isIdKey);
@@ -148,6 +150,13 @@ function newObjectState(config, parentState, parentListState, instance, key, may
             if (this.readOnly && !opts.resetting && !opts.refreshing) {
                 throw new Error(`${String(key) || "formState"} is currently readOnly`);
             }
+            // Restore our instance if we're being reset
+            if (value && this.isUnset())
+                parentInstance[key] = instance;
+            // Delete our instance if we're being unset
+            if (!value && parentInstance)
+                parentInstance[key] = undefined;
+            // Otherwise just copy over the fields
             getFields(this).forEach((field) => {
                 if (value && typeof value === "object" && field.key in value) {
                     field.set(value[field.key], opts);
@@ -165,17 +174,27 @@ function newObjectState(config, parentState, parentListState, instance, key, may
         // Create a result that is only populated with changed keys
         get changedValue() {
             const result = {};
+            // If we're a child, like `author.address` that was unset, return null
+            if (this.isUnset()) {
+                // If we're a reference, always return `{ id: ... }` for easy binding
+                const idField = getFields(this).find((f) => f._isIdKey);
+                if (idField && config.reference)
+                    return { id: null };
+                // Otherwise mark the whole child as gone
+                return null;
+            }
             getFields(this).forEach((f) => {
                 if (f._computed)
                     return;
+                // References only include the id key below
+                if (config.reference)
+                    return;
                 if (f.dirty ||
                     // If the caller used useFormState.ifUndefined to provide some default values, then those keys may not
                     // look dirty, but if we're new we should include them anyway.
-                    (this.isNewEntity &&
-                        // Unless they're undefined anyway
-                        f.value !== undefined &&
-                        // And unless they're empty sub-objects
-                        !(f.value instanceof Object && Object.entries(f.changedValue).length === 0))) {
+                    (this.isNewEntity && f._kind === "value" && f.value !== undefined) ||
+                    // And unless they're empty sub-objects
+                    (this.isNewEntity && f._kind === "object" && Object.entries(f.changedValue).length > 0)) {
                     result[f.key] = f.changedValue;
                 }
             });
@@ -200,6 +219,9 @@ function newObjectState(config, parentState, parentListState, instance, key, may
             // If the otherIdValue is undefined, it's a new entity so can't be the same as us
             return otherIdValue !== undefined && otherIdValue === ourIdValue;
         },
+        isUnset() {
+            return !!parentInstance && parentInstance[key] === undefined;
+        },
     };
     proxy = (0, mobx_1.makeAutoObservable)(obj, {
         // Use custom equality on `value` that is _never_ equals. This sounds weird, but

package/dist/fields/valueField.js

@@ -17,6 +17,7 @@ function newValueFieldState(parentCopy, parentInstance, parentState, key, rules,
         /** Current readOnly value. */
         _readOnly: readOnly || false,
         _loading: false,
+        _kind: "value",
         // Expose so computed can be skipped in changedValue
         _computed: computed,
         _focused: false,

package/dist/formState.test.js

@@ -957,24 +957,6 @@ describe("formState", () => {
         // Then the formState saw it
         expect(lastLength).toEqual(2);
     });
-    it("supports observable objects with helper methods", () => {
-        const config = {
-            firstName: { type: "value" },
-            lastName: { type: "value" },
-            fullName: { type: "value", computed: true },
-        };
-        // 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" },
@@ -1087,6 +1069,89 @@ describe("formState", () => {
         // because this might trigger creating a throw-away entity
         expect(formState.changedValue).toEqual({ firstName: "f" });
     });
+    it("changedValue includes new entity nested fields", () => {
+        // Given a new author with an address FK
+        const formState = (0, objectField_1.createObjectState)(authorWithAddressFkConfig, {
+            firstName: "f",
+            address: { id: "add:1" },
+        });
+        // Then changedValue includes the reference to the FK
+        expect(formState.changedValue).toEqual({
+            firstName: "f",
+            address: { id: "add:1" },
+        });
+    });
+    it("changedValue includes new entity nested fields with multiple keys", () => {
+        // Given a new author with an address FK
+        const formState = (0, objectField_1.createObjectState)(authorWithAddressFkConfig, { firstName: "f" });
+        formState.address.set({ id: "add:1", street: "Main St" });
+        // Then changedValue includes the reference to the FK
+        expect(formState.changedValue).toEqual({
+            firstName: "f",
+            address: { id: "add:1", street: "Main St" },
+        });
+    });
+    it("changedValue includes deleted nested fields", () => {
+        var _a;
+        // Given a new author with an address FK
+        const formState = (0, objectField_1.createObjectState)(configBuilders_1.f.config({
+            id: configBuilders_1.f.value(),
+            firstName: configBuilders_1.f.value(),
+            // And address is a reference
+            address: configBuilders_1.f.reference(),
+        }), { id: "a:1", firstName: "f", address: { id: "add:1" } });
+        // When the address is unset
+        formState.address.set(undefined);
+        // Then the field is dirty and will be removed in changedValue
+        expect(formState.address.dirty).toBe(true);
+        expect(formState.dirty).toBe(true);
+        expect(formState.changedValue).toEqual({
+            id: "a:1",
+            address: { id: null },
+        });
+        // So that we can do a binding like
+        const addressId = (_a = formState.changedValue.address) === null || _a === void 0 ? void 0 : _a.id;
+        expect(addressId).toBeNull();
+        // And when we're restored to the same value
+        formState.address.set({ id: "add:1" });
+        // Then it's back to not being dirty
+        expect(formState.address.dirty).toBe(false);
+        expect(formState.dirty).toBe(false);
+        // And when we're changed to a different address
+        formState.address.set({ id: "add:2" });
+        // Then we're dirty again
+        expect(formState.changedValue).toEqual({
+            id: "a:1",
+            address: { id: "add:2" },
+        });
+    });
+    it("changedValue includes deleted nested fields with a name", () => {
+        // Given a new author with an address FK
+        const formState = (0, objectField_1.createObjectState)(configBuilders_1.f.config({
+            id: configBuilders_1.f.value(),
+            firstName: configBuilders_1.f.value(),
+            address: configBuilders_1.f.reference({ street: configBuilders_1.f.value() }),
+        }), { id: "a:1", firstName: "f", address: { id: "add:1", street: "Main St" } });
+        // Initially both id and street can be bound to the UI
+        expect(formState.address.id.value).toBe("add:1");
+        expect(formState.address.street.value).toBe("Main St");
+        // When the address is unset
+        formState.address.set(undefined);
+        // Then the field is dirty and will be removed in changedValue
+        expect(formState.address.dirty).toBe(true);
+        // And our changedValue only includes the id
+        expect(formState.changedValue).toEqual({
+            id: "a:1",
+            address: { id: null },
+        });
+        // And when we're changed to a new address
+        formState.address.set({ id: "add:2", street: "Side St" });
+        // Then we see oly the id come back in changedValue
+        expect(formState.changedValue).toEqual({
+            id: "a:1",
+            address: { id: "add:2" },
+        });
+    });
     it("changedValue skips effectively empty nested fields", () => {
         // Given a new author with an address object
         const formState = (0, objectField_1.createObjectState)(authorWithAddressConfig, {
@@ -1620,6 +1685,19 @@ const authorWithAddressConfig = {
         },
     },
 };
+const authorWithAddressFkConfig = {
+    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" },
+        },
+    },
+};
 const authorWithAddressAndBooksConfig = configBuilders_1.f.config({
     id: configBuilders_1.f.value(),
     firstName: configBuilders_1.f.value(),

package/dist/formStateDomain.d.ts

@@ -18,6 +18,7 @@ export interface AuthorInput {
     favoriteColors?: Color[] | null;
 }
 export interface AuthorAddress {
+    id?: string | null;
     street?: string | null;
     city?: string | null;
 }

package/package.json

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