@homebound/form-state 2.26.3 → 2.26.5

package/README.md

@@ -23,6 +23,10 @@ It also keeps track of low-level form UX details like:
   - Supports collections of children, i.e. a `author: { books: [...} }` will include only changed books if necessary
   - 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
 
+# Basic Usage
+
+See our in-repo [sample app](https://github.com/homebound-team/form-state/blob/main/src/FormStateApp.tsx).
+
 # Main Features
 
 There are two main reasons why form-state exists:
@@ -90,19 +94,70 @@ Admittedly (and hopefully, b/c it makes the code simpler), the differences betwe
 
 These are usually simple/mechanistic changes, but nonetheless just some boilerplate that form-state provides conventions for.
 
-# Basic Usage
+# Other Features
 
-See the [sample](https://github.com/homebound-team/form-state/blob/main/src/FormStateApp.tsx).
+## Incremental changedValue/dirty Management
 
-# Todo
+In general, we have two types of forms:
 
-- Add conditional readonly logic, like `{ type: "field", readOnlyIf: i => i.isInternal.value }`
+- `autoSave` forms
+- `submit` forms
 
-- Add `omitFromValue` so we can have two fields, `book.author.id` / `book.author.name`, where `book.author.name` is used for showing the author name, but `book.author.id` is the only field that is submitted to the server on mutation (maybe pair this with `Ref` based mutations)
+### autoSave forms
 
-- Undo/redo would in theory be neat and easy to do on top of the existing infra
+For auto save forms, the expectation is that you should:
+
+- Pass `useFormState` an `init.input` and `init.map` that updates the form-state from the initial GraphQL request & any cache updates
+- Pass `useFormState` an `autoSave` lambda that calls your GraphQL mutation, using `changedValue`.
+- Have your `save` mutation response return the acked/updated entity/fragment
+
+  ```ts
+  autoSave: async () => {
+    const input = formState.changedValue;
+    await saveAuthor(input);
+  };
+  ```
+
+With these in place, we will correctly handle interleaved edits/saves, i.e.:
+
+1. User changes `{ firstName: bob }`
+2. We submit `{ id: 1, firstName: bob }` to the backend
+3. While waiting for the response, the user sets `{ lastName: smith }`
+4. The GraphQL mutation acks that `{ id: 1, firstName: bob }` is committed
+5. The `init.map` updates `formState` to realize `firstName` is no longer dirty, but `lastName` keeps its WIP change
+6. formState will trigger a 2nd `autoSave` for just the `lastName` change
+
+### Submit forms
+
+For submit forms, the expectation is that you should:
+
+- Pass `useFormState` an `init.input` and `init.map` that updates the form-state from the initial GraphQL request & any cache updates
+- In your `onClick` lambda, use `formState.changedValue` to call your GraphQL mutation
+- Have your `save` mutation response return the acked/updated entity/fragment
 
-# Features
+If you do this, you should not have to call `commitChanges` manually, because code like:
+
+```ts
+  onClick: async () => {
+    const input = formState.changedValue;
+    await saveAuthor(input);
+    // checks if formState.dirty is true before closing
+    closeModal();
+  };
+```
+
+Will "just work" because the control flow will be:
+
+- User changes `{ firstName: bob }` and clicks Submit
+- `onClick` runs and we submit `{ id: 1, firstName: bob }` to `saveAuthor`
+- _Before_ the `await` promise resolves, the GraphQL response of `saveAuthor { ...AuthorFragment }` will:
+  - Update the apollo cache
+  - Re-render the `AuthorEditor` component with the new data
+  - Call `init.map` to update `formState` with the new data
+  - Realize the `firstName` is no longer dirty
+- When `closeModal` runs, no "You have unsaved changes?" will appear
+
+Basically, in a correctly-setup form, you should never have to call `commitChanges` manually, and doing so risks losing edits that the user made while any saves (either auto save or submit save) were in-flight.
 
 ## Fragments
 
@@ -148,6 +203,14 @@ const form = useFormState({
 });
 ```
 
+# Todo
+
+- Add conditional readonly logic, like `{ type: "field", readOnlyIf: i => i.isInternal.value }`
+
+- Add `omitFromValue` so we can have two fields, `book.author.id` / `book.author.name`, where `book.author.name` is used for showing the author name, but `book.author.id` is the only field that is submitted to the server on mutation (maybe pair this with `Ref` based mutations)
+
+- Undo/redo would in theory be neat and easy to do on top of the existing infra
+
 # 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/fields/valueField.js

@@ -100,7 +100,8 @@ function newValueFieldState(parentCopy, parentInstance, parentState, key, rules,
             if (this.readOnly && !opts.resetting && !opts.refreshing) {
                 throw new Error(`${String(key)} is currently readOnly`);
             }
-            if (opts.refreshing && this.dirty && this.value !== value) {
+            const isAckingUnset = this.value === null && (value === null || value === undefined);
+            if (opts.refreshing && this.dirty && this.value !== value && !isAckingUnset) {
                 // 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 no longer dirty.

package/dist/formState.test.js

@@ -735,6 +735,13 @@ describe("formState", () => {
         expect(a1.firstName.value).toBeNull();
         expect(a1.originalValue.firstName).toBe("asdf");
         expect(a1.firstName.dirty).toBeTruthy();
+        // And when the server acks as null
+        a1.set({ firstName: undefined }, { refreshing: true });
+        // Then it's no longer dirty
+        expect(a1.firstName.dirty).toBe(false);
+        expect(a1.firstName.originalValue).toBe(undefined);
+        expect(a1.firstName.value).toBe(undefined);
+        expect(a1.changedValue).toEqual({});
     });
     it("initializes null values to be undefined", () => {
         // Given a property that is initially set to null

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 export { f } from "./configBuilders";
 export { type FragmentField } from "./fields/fragmentField";
 export { type ListFieldState } from "./fields/listField";
-export { createObjectState, type Fragment, type ObjectState, type fragment } from "./fields/objectField";
+export { createObjectState, type Fragment, type ObjectState, fragment } from "./fields/objectField";
 export { type FieldState, type ValueAdapter } from "./fields/valueField";
 export { required, type Rule } from "./rules";
 export { useFormState } from "./useFormState";

package/dist/index.js

@@ -1,10 +1,11 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.useFormStates = exports.useFormState = exports.required = exports.createObjectState = exports.f = void 0;
+exports.useFormStates = exports.useFormState = exports.required = exports.fragment = 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; } });
+Object.defineProperty(exports, "fragment", { enumerable: true, get: function () { return objectField_1.fragment; } });
 var rules_1 = require("./rules");
 Object.defineProperty(exports, "required", { enumerable: true, get: function () { return rules_1.required; } });
 var useFormState_1 = require("./useFormState");

package/package.json

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