@homebound/form-state 2.28.0 → 2.30.0

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/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

@@ -178,16 +178,18 @@ function newObjectState(config, parentState, parentInstance, parentListState, in
         revertChanges() {
             getFields(this).forEach((f) => f.revertChanges());
         },
-        // Saves all current values into _originalValue
+        // Saves all current values into _originalValue.
+        // Deprecated: use formState.update(ackedServerValue) so saved changes are audited field-by-field.
         commitChanges() {
             if (this._isAutoSaving) {
                 // `commitChanges` will mark all WIP changes as committed, which might drop changes if there
                 // is an auto-save in-flight, and the user made more changes, that are waiting for their turn
                 // on the next auto-save request.
                 //
-                // Instead of doing a form-wide "all changes are committed", instead autosave forms should use
-                // init.map/input to have the server's latest results updated within the form, which will then
-                // selectively "un-dirty"/commit the just-saved data, but keep the "still-dirty" WIP data alone.
+                // Instead of doing a form-wide "all changes are committed", autosave forms should use
+                // formState.update(ackedServerValue), or init.map/input, to apply the server's latest results
+                // within the form. That selectively "un-dirty"/commits the just-saved data, but keeps the
+                // "still-dirty" WIP data alone.
                 throw new Error("When using autoSave, you should not manually call commitChanges, instead have init.map/input update the form state");
             }
             // asdf
@@ -251,7 +253,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

@@ -37,7 +37,13 @@ export interface FieldState<V> {
     set(value: V, opts?: SetOpts): void;
     /** Reverts back to the original value and resets dirty/touched. */
     revertChanges(): void;
-    /** Accepts the current changed value (if any) as the original and resets dirty/touched. */
+    /**
+     * Accepts the current changed value (if any) as the original and resets dirty/touched.
+     *
+     * @deprecated Use `formState.update(ackedServerValue)` instead. `commitChanges` marks all current
+     * changes as saved, which risks discarding a user's in-flight edits. Updating from the server ack gives
+     * form-state a field-by-field audit of which changes were successfully saved.
+     */
     commitChanges(): void;
     /** Creates a new FieldState with a transformation of the value, i.e. string to int, or feet to inches. */
     adapt<V2>(adapter: ValueAdapter<V, V2>): FieldState<V2>;

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/useFormState.d.ts

@@ -1,5 +1,5 @@
-import { ObjectConfig } from "./config";
-import { ObjectState } from "./fields/objectField";
+import { type ObjectConfig } from "./config";
+import { type ObjectState } from "./fields/objectField";
 export type Query<I> = {
     data: I;
     loading: boolean;
@@ -65,7 +65,18 @@ export type UseFormStateOpts<T, I> = {
      */
     autoSave?: (state: ObjectState<T>) => Promise<unknown>;
 };
+export type FormObjectState<T, I> = ObjectState<T> & {
+    /**
+     * Refreshes the form with a server-acked value, i.e. `form.update(savedAuthor)`.
+     *
+     * This is intended for save callbacks that need `form.dirty` to become `false` immediately, before the
+     * normal query/cache refresh has a chance to rerender `useFormState`. Pass the value returned by the
+     * server so the form can map it through `init.map` and then do a field-by-field refresh of only the
+     * changes the server has acknowledged.
+     */
+    update(input: Exclude<I, null | undefined>): void;
+};
 /**
  * Creates a formState instance for editing in a form.
  */
-export declare function useFormState<T, I>(opts: UseFormStateOpts<T, I>): ObjectState<T>;
+export declare function useFormState<T, I>(opts: UseFormStateOpts<T, I>): FormObjectState<T, I>;

package/dist/useFormState.js

@@ -20,6 +20,9 @@ function useFormState(opts) {
     // Use a ref so our memo'ized `onBlur` always see the latest value
     const autoSaveRef = (0, react_1.useRef)(autoSave);
     autoSaveRef.current = autoSave;
+    // Use a ref so our memo'ized `update` always sees the latest init/map
+    const initRef = (0, react_1.useRef)(init);
+    initRef.current = init;
     const firstRunRef = (0, react_1.useRef)(true);
     // This is a little weird, but we need to know ahead of time, before the form useMemo, if we're working with classes/mobx proxies
     const [firstInitValue] = (0, react_1.useState)(() => (0, utils_1.initValue)(config, init));
@@ -86,6 +89,17 @@ function useFormState(opts) {
         }
         const value = firstRunRef.current ? firstInitValue : (0, utils_1.initValue)(config, init);
         const form = (0, objectField_1.createObjectState)(config, value, { maybeAutoSave });
+        form.update = function update(input) {
+            const init = initRef.current;
+            const updateInit = (0, utils_1.isInput)(init)
+                ? { ...init, input }
+                : (0, utils_1.isQuery)(init)
+                    ? { input, map: init.map, ifUndefined: init.ifUndefined }
+                    : { input };
+            form.set((0, utils_1.initValue)(config, updateInit), {
+                refreshing: true,
+            });
+        };
         form.readOnly = readOnly;
         setLoading(form, opts);
         // The identity of `addRules` is not stable, but assume that it is for better UX.

package/dist/useFormState.test.js

@@ -243,6 +243,49 @@ describe("useFormState", () => {
         // Then we accept it
         expect(r.firstName.textContent).toEqual("F2");
     });
+    it("can immediately update from a server ack before init input rerenders", async () => {
+        const config = {
+            firstName: { type: "value" },
+            lastName: { type: "value" },
+        };
+        const initialAuthor = { legalFirstName: "First", legalLastName: "Last" };
+        const savedAuthor = { legalFirstName: "Saved", legalLastName: "Author" };
+        function TestComponent() {
+            const form = (0, useFormState_1.useFormState)({
+                config,
+                init: { input: initialAuthor, map: mapServerAuthor },
+            });
+            function makeLocalChanges() {
+                form.firstName.set("Saved");
+                form.lastName.set("Author");
+            }
+            function saveWithoutUpdating() {
+                noop(form.changedValue);
+            }
+            function saveAndUpdate() {
+                noop(form.changedValue);
+                form.update(savedAuthor);
+            }
+            return ((0, jsx_runtime_1.jsx)(mobx_react_1.Observer, { children: () => ((0, jsx_runtime_1.jsxs)("div", { children: [(0, jsx_runtime_1.jsx)("div", { "data-testid": "firstName", children: form.firstName.value }), (0, jsx_runtime_1.jsx)("div", { "data-testid": "lastName", children: form.lastName.value }), (0, jsx_runtime_1.jsx)("div", { "data-testid": "dirty", children: String(form.dirty) }), (0, jsx_runtime_1.jsx)("button", { "data-testid": "makeLocalChanges", onClick: makeLocalChanges }), (0, jsx_runtime_1.jsx)("button", { "data-testid": "saveWithoutUpdating", onClick: saveWithoutUpdating }), (0, jsx_runtime_1.jsx)("button", { "data-testid": "saveAndUpdate", onClick: saveAndUpdate })] })) }));
+        }
+        const r = await (0, rtl_utils_1.render)((0, jsx_runtime_1.jsx)(TestComponent, {}));
+        expect(r.firstName.textContent).toEqual("First");
+        expect(r.lastName.textContent).toEqual("Last");
+        expect(r.dirty.textContent).toEqual("false");
+        (0, rtl_utils_1.click)(r.makeLocalChanges);
+        expect(r.firstName.textContent).toEqual("Saved");
+        expect(r.lastName.textContent).toEqual("Author");
+        expect(r.dirty.textContent).toEqual("true");
+        (0, rtl_utils_1.click)(r.saveWithoutUpdating);
+        expect(r.dirty.textContent).toEqual("true");
+        (0, rtl_utils_1.click)(r.saveAndUpdate);
+        expect(r.firstName.textContent).toEqual("Saved");
+        expect(r.lastName.textContent).toEqual("Author");
+        expect(r.dirty.textContent).toEqual("false");
+        function mapServerAuthor(input) {
+            return { firstName: input.legalFirstName, lastName: input.legalLastName };
+        }
+    });
     it("can accept new data while read only", async () => {
         // Given a component
         function TestComponent() {

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.28.0",
+  "version": "2.30.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",