@homebound/form-state 2.27.3 → 2.29.0

package/dist/config.d.ts

@@ -28,6 +28,8 @@ export type ValueFieldConfig<V> = {
     isDeleteKey?: boolean;
     /** If true, the entity that contains this value will be treated as read only. */
     isReadOnlyKey?: boolean;
+    /** If true, we ignore field in dirty checks. */
+    isLocalOnly?: boolean;
     /**
      * Marks a field as being backed by a mobx class computed field.
      *

package/dist/configBuilders.d.ts

@@ -47,6 +47,8 @@ export declare class ValueFieldConfigBuilder<V> {
     req(): this;
     /** Marks the field as read only. */
     readOnly(): this;
+    /** Marks the field as local only. */
+    localOnly(): this;
     /** Appends `rules` to the field's validation rules. */
     rules(rules: Rule<V | null | undefined>[]): this;
     /** Marks the field as computed. */

package/dist/configBuilders.js

@@ -63,6 +63,11 @@ class ValueFieldConfigBuilder {
         this.config.readOnly = true;
         return this;
     }
+    /** Marks the field as local only. */
+    localOnly() {
+        this.config.isLocalOnly = true;
+        return this;
+    }
     /** Appends `rules` to the field's validation rules. */
     rules(rules) {
         var _a;

package/dist/fields/deepEquals.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.deepEquals = deepEquals;
+const temporal_1 = require("../temporal");
 /**
  * Our own `deepEquals` because either `fast-deep-equals` or `dequal` or etc actually
  * handle cyclic data structures, despite ChatGTP's assertions/hallucinations.
@@ -8,6 +9,9 @@ exports.deepEquals = deepEquals;
  * Ported from https://github.com/KoryNunn/cyclic-deep-equal which is ISC.
  */
 function deepEquals(a, b, visited = new Set()) {
+    const temporalEquals = (0, temporal_1.areSupportedTemporalValuesEqual)(a, b);
+    if (temporalEquals !== undefined)
+        return temporalEquals;
     const aType = typeof a;
     if (aType !== typeof b)
         return false;
@@ -16,6 +20,11 @@ function deepEquals(a, b, visited = new Set()) {
             return true;
         return a === b;
     }
+    if (hasToJSON(a) || hasToJSON(b)) {
+        const a1 = hasToJSON(a) ? a.toJSON() : a;
+        const b1 = hasToJSON(b) ? b.toJSON() : b;
+        return deepEquals(a1, b1, visited);
+    }
     if (Array.isArray(a) !== Array.isArray(b))
         return false;
     const aKeys = Object.keys(a), bKeys = Object.keys(b);
@@ -39,3 +48,6 @@ function deepEquals(a, b, visited = new Set()) {
     }
     return equal;
 }
+function hasToJSON(o) {
+    return !!(o && typeof o === "object" && "toJSON" in o);
+}

package/dist/fields/fragmentField.js

@@ -16,6 +16,7 @@ function newFragmentField(parentInstance, key) {
         _isIdKey: false,
         _isDeleteKey: false,
         _isReadOnlyKey: false,
+        _isLocalOnly: false,
         touched: false,
         valid: true,
         readOnly: true,

package/dist/fields/listField.js

@@ -207,8 +207,11 @@ parentInstance, parentState, key, rules, listConfig, config, strictOrder, maybeA
                 const contentKeys = Object.entries(config.config)
                     .filter(([key, cfg]) => key !== idKey && cfg.type === "value")
                     .map(([key]) => key);
-                const hashByContent = (item) => (0, object_hash_1.default)(Object.fromEntries(Object.entries(item).filter(([key]) => contentKeys.includes(key))));
-                const hashById = (item) => (idKey && item[idKey]) || hashByContent(item);
+                const hashByContent = (item) => hashValue((0, utils_1.normalizeHashValue)(Object.fromEntries(Object.entries(item).filter(([key]) => contentKeys.includes(key)))));
+                const hashById = (item) => {
+                    const idValue = idKey ? item[idKey] : undefined;
+                    return idValue === undefined ? hashByContent(item) : idValue;
+                };
                 const currentById = (0, utils_1.groupBy)(currentItems, hashById);
                 const incomingById = (0, utils_1.groupBy)(incomingItems, hashById);
                 // If our local instance doesn't assign in id, when we get results back from the server, strip
@@ -347,3 +350,6 @@ parentInstance, parentState, key, rules, listConfig, config, strictOrder, maybeA
     (0, mobx_1.reaction)(() => proxy.rows.map((r) => r.value), () => _childTick.value++);
     return proxy;
 }
+function hashValue(value) {
+    return (0, object_hash_1.default)(value);
+}

package/dist/fields/objectField.js

@@ -50,7 +50,7 @@ function newObjectState(config, parentState, parentInstance, parentListState, in
                 // Default the id key to "id" unless some other field has isIdKey set
                 (key === "id" &&
                     !("isIdKey" in config) && // Allow setting `isIdKey=false`
-                    !Object.entries(objectConfig).some(([other, c]) => other !== key && c.isIdKey)), config.isDeleteKey || false, config.isReadOnlyKey || false, (_a = config.computed) !== null && _a !== void 0 ? _a : 
+                    !Object.entries(objectConfig).some(([other, c]) => other !== key && c.isIdKey)), config.isDeleteKey || false, config.isReadOnlyKey || false, config.isLocalOnly || 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);
         }
@@ -138,7 +138,7 @@ function newObjectState(config, parentState, parentInstance, parentListState, in
             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 && !f._isLocalOnly) ||
                 // `isUnset` checks if our `parent[key] === undefined`, which can mean "surely we're dirty",
                 // but as long as we've got some keys actually set
                 (this.isUnset() && !(0, utils_1.areEqual)(this.value, {})));
@@ -212,6 +212,9 @@ function newObjectState(config, parentState, parentInstance, parentListState, in
                 // References only include the id key below
                 if (config.reference)
                     return;
+                // Ignore local-only fields
+                if (f._isLocalOnly)
+                    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.
@@ -248,7 +251,7 @@ function newObjectState(config, parentState, parentInstance, parentListState, in
             const ourIdValue = idField.value;
             const otherIdValue = other[idField.key];
             // If the otherIdValue is undefined, it's a new entity so can't be the same as us
-            return otherIdValue !== undefined && otherIdValue === ourIdValue;
+            return otherIdValue !== undefined && (0, utils_1.areEqual)(otherIdValue, ourIdValue);
         },
         isUnset() {
             return !!parentInstance && parentInstance[key] === undefined;

package/dist/fields/valueField.d.ts

@@ -70,5 +70,6 @@ export interface FieldStateInternal<T, V> extends FieldState<V> {
     _isIdKey: boolean;
     _isDeleteKey: boolean;
     _isReadOnlyKey: boolean;
+    _isLocalOnly: boolean;
 }
-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>;
+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, isLocalOnly: boolean, computed: boolean, readOnly: boolean, strictOrder: boolean, maybeAutoSave: () => void): FieldState<T[K] | null | undefined>;

package/dist/fields/valueField.js

@@ -6,7 +6,7 @@ const mobx_1 = require("mobx");
 const proxies_1 = require("../proxies");
 const rules_1 = require("../rules");
 const utils_1 = require("../utils");
-function newValueFieldState(parentCopy, parentInstance, parentState, key, rules, isIdKey, isDeleteKey, isReadOnlyKey, computed, readOnly, strictOrder, maybeAutoSave) {
+function newValueFieldState(parentCopy, parentInstance, parentState, key, rules, isIdKey, isDeleteKey, isReadOnlyKey, isLocalOnly, 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,6 +31,7 @@ function newValueFieldState(parentCopy, parentInstance, parentState, key, rules,
         _isIdKey: isIdKey,
         _isDeleteKey: isDeleteKey,
         _isReadOnlyKey: isReadOnlyKey,
+        _isLocalOnly: isLocalOnly,
         rules,
         get value() {
             // If we're wrapping a mobx store, then we'll get reactivity from parentInstance[key]

package/dist/formState.test.js

@@ -640,6 +640,33 @@ describe("formState", () => {
         a1.books.remove(0);
         expect(a1.dirty).toBeFalsy();
     });
+    it("can ignore isLocalOnly fields as not dirty", () => {
+        // Given we have an `isPublished` field that is marked as local only
+        const config = {
+            id: { type: "value" },
+            books: {
+                type: "list",
+                config: {
+                    id: { type: "value" },
+                    isPublished: { type: "value", isLocalOnly: true },
+                },
+            },
+        };
+        // And it starts out true
+        const a1 = (0, objectField_1.createObjectState)(config, {
+            id: "a:1",
+            books: [{ id: "b:1", isPublished: true }],
+        });
+        // When we change the value to false
+        a1.books.rows[0].isPublished.value = false;
+        // Then the field itself is dirty
+        expect(a1.books.rows[0].isPublished.dirty).toBe(true);
+        // But object is not
+        expect(a1.dirty).toBe(false);
+        expect(a1.books.dirty).toBe(false);
+        // And we don't include it in changedValue
+        expect(a1.changedValue).toEqual({ id: "a:1" });
+    });
     it("handles list fields with duplicate ids", () => {
         // Given an author that incorrectly has duplicate books
         const a1 = createAuthorInputState({

package/dist/temporal.d.ts

@@ -0,0 +1,6 @@
+import { type Temporal } from "temporal-polyfill";
+export type SupportedTemporal = Temporal.PlainDate | Temporal.ZonedDateTime;
+/** Detects the Temporal value types that form-state treats as builtins. */
+export declare function isSupportedTemporal(value: unknown): value is SupportedTemporal;
+/** Compares supported Temporal values with Temporal's `.equals(...)` semantics. */
+export declare function areSupportedTemporalValuesEqual(a: unknown, b: unknown): boolean | undefined;

package/dist/temporal.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSupportedTemporal = isSupportedTemporal;
+exports.areSupportedTemporalValuesEqual = areSupportedTemporalValuesEqual;
+// Use Temporal's well-known tags for runtime detection instead of `instanceof` because this
+// library can receive values from native Temporal, a polyfill, another copy of a polyfill,
+// or another realm. Tag checks are stable across those boundaries, while `instanceof` is not.
+const temporalPlainDateTag = "Temporal.PlainDate";
+const temporalZonedDateTimeTag = "Temporal.ZonedDateTime";
+/** Detects the Temporal value types that form-state treats as builtins. */
+function isSupportedTemporal(value) {
+    if (!value || typeof value !== "object") {
+        return false;
+    }
+    const record = value;
+    return (isSupportedTemporalTag(record[Symbol.toStringTag]) &&
+        typeof record.equals === "function" &&
+        typeof record.toJSON === "function");
+}
+/** Compares supported Temporal values with Temporal's `.equals(...)` semantics. */
+function areSupportedTemporalValuesEqual(a, b) {
+    const aIsTemporal = isSupportedTemporal(a);
+    const bIsTemporal = isSupportedTemporal(b);
+    if (!aIsTemporal && !bIsTemporal) {
+        return undefined;
+    }
+    if (!aIsTemporal || !bIsTemporal || a[Symbol.toStringTag] !== b[Symbol.toStringTag]) {
+        return false;
+    }
+    return a.equals(b);
+}
+function isSupportedTemporalTag(value) {
+    return value === temporalPlainDateTag || value === temporalZonedDateTimeTag;
+}

package/dist/temporal.test.d.ts

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

package/dist/temporal.test.js

@@ -0,0 +1,97 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const temporal_polyfill_1 = require("temporal-polyfill");
+const configBuilders_1 = require("./configBuilders");
+const objectField_1 = require("./fields/objectField");
+describe("Temporal support", () => {
+    it("treats equal Temporal value fields as unchanged", () => {
+        const form = (0, objectField_1.createObjectState)(temporalValueConfig, {
+            publishedOn: temporal_polyfill_1.Temporal.PlainDate.from("2026-04-17"),
+            scheduledAt: temporal_polyfill_1.Temporal.ZonedDateTime.from("2026-04-17T09:00:00-04:00[America/New_York]"),
+        });
+        form.publishedOn.set(temporal_polyfill_1.Temporal.PlainDate.from("2026-04-17"));
+        form.scheduledAt.set(temporal_polyfill_1.Temporal.ZonedDateTime.from("2026-04-17T09:00:00-04:00[America/New_York]"));
+        expect(form.publishedOn.dirty).toBe(false);
+        expect(form.scheduledAt.dirty).toBe(false);
+        expect(form.dirty).toBe(false);
+    });
+    it("tracks dirty nested object fields with Temporal values", () => {
+        const form = (0, objectField_1.createObjectState)(temporalObjectConfig, {
+            details: {
+                dueOn: temporal_polyfill_1.Temporal.PlainDate.from("2026-04-17"),
+                startsAt: temporal_polyfill_1.Temporal.ZonedDateTime.from("2026-04-17T09:00:00-04:00[America/New_York]"),
+            },
+        });
+        form.details.dueOn.set(temporal_polyfill_1.Temporal.PlainDate.from("2026-04-17"));
+        form.details.startsAt.set(temporal_polyfill_1.Temporal.ZonedDateTime.from("2026-04-17T09:00:00-04:00[America/New_York]"));
+        expect(form.details.dirty).toBe(false);
+        expect(form.dirty).toBe(false);
+        form.details.startsAt.set(temporal_polyfill_1.Temporal.ZonedDateTime.from("2026-04-18T09:00:00-04:00[America/New_York]"));
+        expect(form.details.startsAt.dirty).toBe(true);
+        expect(form.details.dirty).toBe(true);
+        expect(form.dirty).toBe(true);
+        form.details.revertChanges();
+        expect(form.details.startsAt.dirty).toBe(false);
+        expect(form.details.dirty).toBe(false);
+        expect(form.dirty).toBe(false);
+    });
+    it("supports list row hashing for Temporal.ZonedDateTime values", () => {
+        var _a;
+        const form = (0, objectField_1.createObjectState)(temporalListConfig, { events: [], milestones: [] });
+        expect(() => {
+            form.events.add({ startsAt: temporal_polyfill_1.Temporal.ZonedDateTime.from("2026-04-17T09:00:00-04:00[America/New_York]") });
+        }).not.toThrow();
+        expect(form.events.dirty).toBe(true);
+        const ackedRow = {
+            id: "event:1",
+            startsAt: temporal_polyfill_1.Temporal.ZonedDateTime.from("2026-04-17T09:00:00-04:00[America/New_York]"),
+        };
+        expect(() => form.set({ events: [ackedRow] }, { refreshing: true })).not.toThrow();
+        expect(form.events.dirty).toBe(false);
+        expect(form.events.value[0].id).toEqual("event:1");
+        expect((_a = form.events.rows[0].startsAt.value) === null || _a === void 0 ? void 0 : _a.equals(ackedRow.startsAt)).toBe(true);
+        form.events.rows[0].startsAt.set(temporal_polyfill_1.Temporal.ZonedDateTime.from("2026-04-18T09:00:00-04:00[America/New_York]"));
+        expect(form.events.rows[0].startsAt.dirty).toBe(true);
+        expect(form.events.dirty).toBe(true);
+        expect(() => form.events.remove(0)).not.toThrow();
+        expect(form.events.value).toEqual([]);
+    });
+    it("supports list row hashing for Temporal.PlainDate values", () => {
+        var _a;
+        const form = (0, objectField_1.createObjectState)(temporalListConfig, { events: [], milestones: [] });
+        expect(() => {
+            form.milestones.add({ dueOn: temporal_polyfill_1.Temporal.PlainDate.from("2026-04-17") });
+        }).not.toThrow();
+        expect(form.milestones.dirty).toBe(true);
+        const ackedRow = { id: "milestone:1", dueOn: temporal_polyfill_1.Temporal.PlainDate.from("2026-04-17") };
+        expect(() => form.set({ milestones: [ackedRow] }, { refreshing: true })).not.toThrow();
+        expect(form.milestones.dirty).toBe(false);
+        expect(form.milestones.value[0].id).toEqual("milestone:1");
+        expect((_a = form.milestones.rows[0].dueOn.value) === null || _a === void 0 ? void 0 : _a.equals(ackedRow.dueOn)).toBe(true);
+        form.milestones.rows[0].dueOn.set(temporal_polyfill_1.Temporal.PlainDate.from("2026-04-18"));
+        expect(form.milestones.rows[0].dueOn.dirty).toBe(true);
+        expect(form.milestones.dirty).toBe(true);
+        expect(() => form.milestones.remove(0)).not.toThrow();
+        expect(form.milestones.value).toEqual([]);
+    });
+});
+const temporalValueConfig = configBuilders_1.f.config({
+    publishedOn: configBuilders_1.f.value(),
+    scheduledAt: configBuilders_1.f.value(),
+});
+const temporalObjectConfig = configBuilders_1.f.config({
+    details: configBuilders_1.f.object({
+        dueOn: configBuilders_1.f.value(),
+        startsAt: configBuilders_1.f.value(),
+    }),
+});
+const temporalListConfig = configBuilders_1.f.config({
+    events: configBuilders_1.f.list({
+        id: configBuilders_1.f.value(),
+        startsAt: configBuilders_1.f.value(),
+    }),
+    milestones: configBuilders_1.f.list({
+        id: configBuilders_1.f.value(),
+        dueOn: configBuilders_1.f.value(),
+    }),
+});

package/dist/utils.d.ts

@@ -1,6 +1,7 @@
 import { ObjectConfig } from "./config";
+import { type SupportedTemporal } from "./temporal";
 import { InputAndMap, QueryAndMap, UseFormStateOpts } from "./useFormState";
-export type Builtin = Date | Function | Uint8Array | string | number | boolean;
+export type Builtin = Date | Function | SupportedTemporal | Uint8Array | string | number | boolean;
 export type Primitive = undefined | null | boolean | string | number | Function | Date | {
     toJSON(): any;
 };
@@ -44,6 +45,8 @@ export declare function areEqual<T>(a?: T, b?: T, strictOrder?: boolean): boolea
 export declare function hasToJSON(o?: unknown): o is {
     toJSON(): void;
 };
+/** Normalizes values into stable object-hash-safe data using our existing `toJSON` semantics. */
+export declare function normalizeHashValue(value: unknown, seen?: WeakMap<object, unknown>): unknown;
 /** 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;
 export declare function groupBy<T, Y = T, K = string>(list: readonly T[], fn: (x: T) => K, valueFn?: (x: T) => Y): Map<K, Y[]>;

package/dist/utils.js

@@ -10,11 +10,13 @@ exports.isNotUndefined = isNotUndefined;
 exports.isEmpty = isEmpty;
 exports.areEqual = areEqual;
 exports.hasToJSON = hasToJSON;
+exports.normalizeHashValue = normalizeHashValue;
 exports.deepClone = deepClone;
 exports.groupBy = groupBy;
 const is_plain_object_1 = require("is-plain-object");
 const mobx_1 = require("mobx");
 const deepEquals_1 = require("./fields/deepEquals");
+const temporal_1 = require("./temporal");
 function fail(message) {
     throw new Error(message || "Failed");
 }
@@ -110,6 +112,10 @@ function isEmpty(value) {
  * - arrays
  */
 function areEqual(a, b, strictOrder) {
+    const temporalEquals = (0, temporal_1.areSupportedTemporalValuesEqual)(a, b);
+    if (temporalEquals !== undefined) {
+        return temporalEquals;
+    }
     if ((0, is_plain_object_1.isPlainObject)(a)) {
         return (0, deepEquals_1.deepEquals)((0, mobx_1.toJS)(a), (0, mobx_1.toJS)(b));
     }
@@ -131,6 +137,33 @@ function areEqual(a, b, strictOrder) {
 function hasToJSON(o) {
     return !!(o && typeof o === "object" && "toJSON" in o);
 }
+/** Normalizes values into stable object-hash-safe data using our existing `toJSON` semantics. */
+function normalizeHashValue(value, seen = new WeakMap()) {
+    if (hasToJSON(value)) {
+        return normalizeHashValue(value.toJSON(), seen);
+    }
+    if (Array.isArray(value)) {
+        if (seen.has(value)) {
+            return seen.get(value);
+        }
+        const result = [];
+        seen.set(value, result);
+        value.forEach((entry) => result.push(normalizeHashValue(entry, seen)));
+        return result;
+    }
+    if (value && typeof value === "object" && (0, is_plain_object_1.isPlainObject)(value)) {
+        if (seen.has(value)) {
+            return seen.get(value);
+        }
+        const result = {};
+        seen.set(value, result);
+        Object.entries(value).forEach(([key, entry]) => {
+            result[key] = normalizeHashValue(entry, seen);
+        });
+        return result;
+    }
+    return value;
+}
 /** 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))) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homebound/form-state",
-  "version": "2.27.3",
+  "version": "2.29.0",
   "author": "Homebound",
   "license": "MIT",
   "main": "dist/index.js",
@@ -32,7 +32,8 @@
   "dependencies": {
     "@types/object-hash": "^3.0.6",
     "is-plain-object": "^5.0.0",
-    "object-hash": "^3.0.0"
+    "object-hash": "^3.0.0",
+    "temporal-polyfill": "^0.3.2"
   },
   "peerDependencies": {
     "mobx": ">=6",