@homebound/form-state 2.6.0 → 2.7.0

package/README.md

@@ -1,9 +1,54 @@
 # form-state
 
-Push release.
+form-state is a headless form state management library, built on top of mobx.
+
+It acts as a buffer between the canonical data/entity (i.e. the server-side data, or local Redux/GraphQL/etc. cache data) and the user's WIP data/entity that is being actively mutated in form fields.
+
+It also keeps track of low-level form UX details like:
+
+* Which form fields are dirty
+* Which forms fields are valid/invalid
+* Which forms fields are touched (i.e. don't show validation errors for untouched fields)
+* Enabling/disabling buttons/form UX based on the overall form-wide state
+* Submitting the form should touch (validate) all fields
+* Auto-saving the form when appropriate (i.e. not on keystroke, but after blur/leaving the field)
+* Queue and debounce auto-saves if one is already in-flight
+* Building a wire payload that has only changed fields
+  * Handles children, i.e. a `author: { books: [...} }` will include only changed books if necessary
+
+# The Three Type/Shapes Mental Model
+
+In general when working with forms (e.g. not just form-state), there are three types/shapes of data involved:
+
+1. The input data/shape from the server (i.e. a GraphQL/REST query)
+2. The form data/shape that is being reactively bound to form fields (i.e. used as `<TextField value=form.firstName onChange=(v) => form.firstName = v />`)
+3. The mutation data/shape that will submit the change to the server (i.e. the GraphQL mutation/REST POST)
+
+form-state generally refers to each of these shapes as:
+
+* The input type
+  * (Hrm, in retrospect "input" is an unfortunate term b/c that is what GraphQL uses for its mutation types, i.e. `input SaveAuthorInput`...we should consider changing this).
+* The form type
+* The ...third type...
+
+And then provides an API/DSL for managing the mapping between each of these in a standard/conventional manner. 
+
+
+Admittedly (and hopefully, b/c it makes the code simpler), the differences between each of these types can often be small, i.e.:
+
+* The input type might have `{ author: { book: { id: "b:1" } }` but the mutation wants `{ author: { bookId: "b:1" } }`
+* ...have other examples...
+
+These are usually simple/mechanistic changes, but nonetheless just some boilerplate that form-state provides conventions for.
+
+# Basic Usage
+
+See the [sample](https://github.com/homebound-team/form-state/blob/main/src/FormStateApp.tsx).
 
 # 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

package/dist/formState.d.ts

@@ -87,6 +87,23 @@ export interface SetOpts {
     /** Whether this `set` should trigger an auto-save; defaults to true. */
     autoSave?: boolean;
 }
+/** Internal `.set` opts for conditionally that form-state internally percolates. */
+interface InternalSetOpts extends SetOpts {
+    /** `resetting` is the code calling `.reset()` to revert to original values. */
+    resetting?: boolean;
+    /** `refreshing` is when `useFormState` sees a new value. */
+    refreshing?: boolean;
+}
+export interface FieldStateInternal<T, V> extends FieldState<T, V> {
+    set(value: V, opts?: InternalSetOpts): void;
+    _isIdKey: boolean;
+    _isDeleteKey: boolean;
+    _isReadOnlyKey: boolean;
+    _focused: boolean;
+}
+export declare type ObjectStateInternal<T, P = any> = ObjectState<T, P> & {
+    set(value: P, opts?: InternalSetOpts): void;
+};
 /** Form state for list of children, i.e. `U` is a `Book` in a form with a `books: Book[]`. */
 export interface ListFieldState<T, U> extends Omit<FieldState<T, U[]>, "originalValue"> {
     readonly rows: ReadonlyArray<ObjectState<U>>;

package/dist/useFormStates.d.ts

@@ -2,8 +2,17 @@ import { ObjectConfig, ObjectState } from "./formState";
 export declare type ObjectStateCache<T, I> = Record<string, [ObjectState<T>, I]>;
 declare type UseFormStatesOpts<T, I> = {
     config: ObjectConfig<T>;
+    /** Fired for each individual `ObjectState` when it's had a value change. */
     autoSave?: (state: ObjectState<T>) => Promise<void>;
+    /**
+     * A hook to add custom, cross-field validation rules that can be difficult to setup directly in the config DSL.
+     *
+     * Does not need to be stable/useMemo'd.
+     */
+    addRules?: (state: ObjectState<T>) => void;
+    /** Given an input to `getObjectState`, returns the identity value that we'll cache that value's form state on. */
     getId: (v: I) => string;
+    /** Maps an input to `getObjectState` to the actual form shape `T`. */
     map?: (input: Exclude<I, null | undefined>) => T;
 };
 export declare function useFormStates<T, I>(opts: UseFormStatesOpts<T, I>): {

package/dist/useFormStates.js

@@ -5,7 +5,7 @@ const react_1 = require("react");
 const formState_1 = require("./formState");
 const utils_1 = require("./utils");
 function useFormStates(opts) {
-    const { config, autoSave, getId, map } = opts;
+    const { config, autoSave, getId, map, addRules } = opts;
     const objectStateCache = react_1.useMemo(() => ({}), [config]);
     // Keep track of ObjectStates that triggered auto-save when a save was already in progress.
     const pendingAutoSaves = react_1.useRef([]);
@@ -33,18 +33,20 @@ function useFormStates(opts) {
     return {
         getObjectState: (input) => {
             const existing = objectStateCache[getId(input)];
-            const form = existing
-                ? existing[0]
-                : formState_1.createObjectState(config, utils_1.initValue(config, map ? { map, input } : input), {
+            let form = existing === null || existing === void 0 ? void 0 : existing[0];
+            // If it didn't exist, then add to the cache.
+            if (!form) {
+                form = formState_1.createObjectState(config, utils_1.initValue(config, map ? { map, input } : input), {
                     maybeAutoSave: () => maybeAutoSave(form),
                 });
-            // If it didn't exist, then add to the cache.
-            if (!existing) {
+                if (addRules) {
+                    addRules(form);
+                }
                 objectStateCache[getId(input)] = [form, input];
             }
             // If the source of truth changed, then update the existing state and return it.
             if (existing && existing[1] !== input) {
-                existing[0].set(utils_1.initValue(config, map ? { map, input } : input), { refreshing: true });
+                form.set(utils_1.initValue(config, map ? { map, input } : input), { refreshing: true });
                 existing[1] = input;
             }
             return form;

package/dist/useFormStates.test.js

@@ -133,4 +133,25 @@ describe("useFormStates", () => {
         // Then the two form-states are no longer equal.
         expect(r.statesEqual()).toHaveTextContent("false");
     });
+    it("calls addRules once per form state", async () => {
+        // Given a user wants to use addRules
+        const addRules = jest.fn();
+        function TestComponent() {
+            const config = { id: { type: "value" }, firstName: { type: "value" } };
+            const { getObjectState } = useFormStates_1.useFormStates({
+                config,
+                addRules,
+                getId: (o) => o.id,
+            });
+            return (jsx_runtime_1.jsxs("div", { children: [jsx_runtime_1.jsx(ChildComponent, { os: getObjectState({ id: "a:1", firstName: "Brandon" }) }, void 0),
+                    jsx_runtime_1.jsx(ChildComponent, { os: getObjectState({ id: "a:1", firstName: "Brandon" }) }, void 0)] }, void 0));
+        }
+        // When we render
+        const r = await rtl_utils_1.render(jsx_runtime_1.jsx(TestComponent, {}, void 0));
+        // Then addRules was only called once
+        expect(addRules).toHaveBeenCalledTimes(1);
+    });
 });
+function ChildComponent({ os }) {
+    return jsx_runtime_1.jsx("div", Object.assign({ "data-testid": "firstName" }, { children: os.firstName.value }), void 0);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@homebound/form-state",
-  "version": "2.6.0",
+  "version": "2.7.0",
   "author": "Homebound",
   "license": "MIT",
   "main": "dist/index.js",
@@ -41,6 +41,7 @@
   "devDependencies": {
     "@babel/core": "^7.13.1",
     "@homebound/rtl-utils": "^2.59.2",
+    "@semantic-release/exec": "^5.0.0",
     "@semantic-release/git": "^9.0.0",
     "@storybook/addon-essentials": "^6.2.9",
     "@storybook/addon-info": "^5.3.21",