@homebound/form-state 2.29.0 → 2.30.0

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

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/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/package.json

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