@homebound/form-state 2.2.10 → 2.3.0

package/dist/FormStateApp.js

@@ -3,9 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.FormStateApp = void 0;
 const jsx_runtime_1 = require("react/jsx-runtime");
 const mobx_react_1 = require("mobx-react");
-const formState_1 = require("./formState");
+const index_1 = require("./index");
 function FormStateApp() {
-    const formState = formState_1.useFormState({
+    const formState = index_1.useFormState({
         config: formConfig,
         // Simulate getting the initial form state back from a server call
         init: {
@@ -60,13 +60,13 @@ function FormStateApp() {
 exports.FormStateApp = FormStateApp;
 // Configure the fields/behavior for AuthorInput's fields
 const formConfig = {
-    firstName: { type: "value", rules: [formState_1.required] },
-    lastName: { type: "value", rules: [formState_1.required], readOnly: true },
+    firstName: { type: "value", rules: [index_1.required] },
+    lastName: { type: "value", rules: [index_1.required], readOnly: true },
     books: {
         type: "list",
         rules: [({ value: list }) => ((list || []).length === 0 ? "Empty" : undefined)],
         config: {
-            title: { type: "value", rules: [formState_1.required] },
+            title: { type: "value", rules: [index_1.required] },
         },
     },
 };

package/dist/formState.d.ts

@@ -1,47 +1,3 @@
-export declare type UseFormStateOpts<T, I> = {
-    /** The form configuration, should be a module-level const or useMemo'd. */
-    config: ObjectConfig<T>;
-    /**
-     * Provides the form's initial value.
-     *
-     * User's can either:
-     *
-     * - Provide no initial value (don't set `init` at all)
-     * - Provide an initial value that already matches the form type `T` (i.e. set `init: data`)
-     * - Provide an initial value from an object that _almost_ matches the form type `T`,
-     *   but needs to be mapped from it's input type `I` to the form type
-     *   (i.e. set `init: { input: data, map: (data) => ...}`).
-     *
-     * The value of using the 3rd option is that: a) we internally `useMemo` on the identity of the
-     * `init.input` (i.e. a response from an Apollo hook) and don't require the `map` function
-     * to have a stable identity, and also b) we will null-check/undefined-check `init.input` and
-     * only call `init.map` if it's set, otherwise we'll use `init.ifDefined` or `{}`, saving you
-     * from having to null check within your `init.map` function.
-     */
-    init?: T | {
-        input: I;
-        map: (input: Exclude<I, null | undefined>) => T;
-        ifUndefined?: T;
-    };
-    /**
-     * 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;
-    /** Whether the form should be read only, when changed it won't re-create the whole form. */
-    readOnly?: boolean;
-    /**
-     * Fired when the form should auto-save, i.e. after a) blur and b) all fields are valid.
-     *
-     * Does not need to be stable/useMemo'd.
-     */
-    autoSave?: (state: ObjectState<T>) => void;
-};
-/**
- * Creates a formState instance for editing in a form.
- */
-export declare function useFormState<T, I>(opts: UseFormStateOpts<T, I>): ObjectState<T>;
 /**
  * Wraps a given input/on-the-wire type `T` for editing in a form.
  *
@@ -69,7 +25,7 @@ export declare function useFormState<T, I>(opts: UseFormStateOpts<T, I>): Object
  */
 export declare type ObjectState<T, P = any> = FieldStates<T> & FieldState<P, T> & {
     /** Sets the state of fields in `state`. */
-    set(state: Partial<T>): void;
+    set(state: Partial<T>, opts?: SetOpts): void;
     /** Returns whether the object can be saved, i.e. is valid, but also as a side-effect marks touched. */
     canSave(): boolean;
 };
@@ -118,12 +74,17 @@ export interface FieldState<T, V> {
     focus(): void;
     /** Blur essentially touches the field. */
     blur(): void;
-    set(value: V): void;
+    set(value: V, opts?: SetOpts): void;
     /** Reverts back to the original value and resets dirty/touched. */
     reset(): void;
     /** Accepts the current changed value (if any) as the original and resets dirty/touched. */
     save(): void;
 }
+/** Public options for our `set` command. */
+export interface SetOpts {
+    /** Whether this `set` should trigger an auto-save; defaults to true. */
+    autoSave?: boolean;
+}
 /** 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>>;
@@ -143,7 +104,7 @@ declare type OmitIf<Base, Condition> = Pick<Base, {
     [Key in keyof Base]: Base[Key] extends Condition ? never : Key;
 }[keyof Base]>;
 /** Field configuration for primitive values, i.e. strings/numbers/Dates/user-defined types. */
-declare type ValueFieldConfig<T, V> = {
+export declare type ValueFieldConfig<T, V> = {
     type: "value";
     rules?: Rule<T, V | null | undefined>[];
     /**
@@ -168,7 +129,7 @@ declare type ValueFieldConfig<T, V> = {
     readOnly?: boolean;
 };
 /** Field configuration for list values, i.e. `U` is `Book` in a form with `books: Book[]`. */
-declare type ListFieldConfig<T, U> = {
+export declare type ListFieldConfig<T, U> = {
     type: "list";
     /** Rules that can run on the full list of children. */
     rules?: Rule<T, readonly ObjectState<U>[]>[];
@@ -187,7 +148,7 @@ declare type ListFieldConfig<T, U> = {
      */
     update?: "exhaustive" | "incremental";
 };
-declare type ObjectFieldConfig<U> = {
+export declare type ObjectFieldConfig<U> = {
     type: "object";
     /** Config for the child's form state, i.e. each book. */
     config: ObjectConfig<U>;
@@ -202,18 +163,6 @@ declare type ObjectFieldConfig<U> = {
 export declare function createObjectState<T>(config: ObjectConfig<T>, instance: T, opts?: {
     onBlur?: () => void;
 }): ObjectState<T>;
-/**
- * Picks ony fields out of `instance` that are in the `formConfig`.
- *
- * This is useful for creating a form input from a GraphQL query result,
- * but ignoring extra data in the query that we don't want/need in the form.
- *
- * (Especially because the form.value will become our mutation's input type
- * that goes on the wire, we don't want superfluous data in it.)
- */
-export declare function pickFields<T, I>(formConfig: ObjectConfig<T>, instance: I): {
-    [K in keyof T]: K extends keyof I ? I[K] : never;
-};
 declare type Primitive = undefined | null | boolean | string | number | Function | Date | {
     toJSON(): any;
 };

package/dist/formState.js

@@ -3,64 +3,11 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.pickFields = exports.createObjectState = exports.required = exports.useFormState = void 0;
+exports.createObjectState = exports.required = void 0;
 const fast_deep_equal_1 = __importDefault(require("fast-deep-equal"));
-const is_plain_object_1 = __importDefault(require("is-plain-object"));
+const is_plain_object_1 = require("is-plain-object");
 const mobx_1 = require("mobx");
-const react_1 = require("react");
 const utils_1 = require("./utils");
-/**
- * Creates a formState instance for editing in a form.
- */
-function useFormState(opts) {
-    const { config, init, addRules, readOnly = false, autoSave } = opts;
-    // Use a ref so our memo'ized `onBlur` always see the latest value
-    const autoSaveRef = react_1.useRef(autoSave);
-    autoSaveRef.current = autoSave;
-    const firstRunRef = 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] = react_1.useState(() => initValue(config, init));
-    const isWrappingMobxProxy = !is_plain_object_1.default(firstInitValue);
-    // If they're using init.input, useMemo on it (and it might be an array), otherwise allow the identity of init be unstable
-    const dep = init && "input" in init && "map" in init ? (Array.isArray(init.input) ? init.input : [init.input]) : [];
-    const form = react_1.useMemo(() => {
-        function onBlur() {
-            // Don't use canSave() because we don't want to set touched for all of the field
-            if (autoSaveRef.current && form.dirty && form.valid) {
-                autoSaveRef.current(form);
-            }
-        }
-        const value = firstRunRef.current ? firstInitValue : initValue(config, init);
-        const form = createObjectState(config, value, { onBlur });
-        form.readOnly = readOnly;
-        // The identity of `addRules` is not stable, but assume that it is for better UX.
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-        (addRules || (() => { }))(form);
-        firstRunRef.current = true;
-        return form;
-    }, 
-    // For this useMemo, we (almost) never re-run so that we can have a stable `form` identity across query refreshes.
-    // eslint-disable-next-line react-hooks/exhaustive-deps
-    [config, ...(isWrappingMobxProxy ? dep : [])]);
-    // We use useEffect so that any mutations to the proxies, which will call `setState`s on any observers to
-    // queue their components' render), don't happen during our render, per https://fb.me/setstate-in-render.
-    react_1.useEffect(() => {
-        // Ignore the 1st run b/c our 1st useMemo already initialized `form` with the current `init` value.
-        // Also for mobx proxies, we recreate a new form-state every time init changes, so that our
-        // fields fundamentally pointing to the right proxy. So just defer to the ^ useMemo.
-        if (firstRunRef.current || isWrappingMobxProxy) {
-            firstRunRef.current = false;
-            return;
-        }
-        form.set(initValue(config, init), { refreshing: true });
-    }, [form, ...dep]);
-    // Use useEffect so that we don't touch the form.init proxy during a render
-    react_1.useEffect(() => {
-        form.readOnly = readOnly;
-    }, [form, readOnly]);
-    return form;
-}
-exports.useFormState = useFormState;
 /** A rule that validates `value` is not `undefined`, `null`, or empty string. */
 // We pre-emptively make this a mobx action so that it's identity doesn't change when proxy-ified
 // and breaks our ability to do `rules.some(r => r === required)`.
@@ -241,7 +188,7 @@ function newObjectState(config, parentState, instance, key, onBlur) {
 function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, isDeleteKey, isReadOnlyKey, computed, readOnly, onBlur) {
     // keep a copy here for reference equality
     const value = parentInstance[key];
-    let _originalValue = value === null ? undefined : is_plain_object_1.default(value) ? mobx_1.toJS(value) : value;
+    let _originalValue = value === null ? undefined : is_plain_object_1.isPlainObject(value) ? mobx_1.toJS(value) : value;
     // 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 = mobx_1.observable({ value: 1 });
@@ -343,6 +290,7 @@ function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, is
             const coerceEmptyList = value && value instanceof Array && value.length === 0 && isEmpty(this.originalValue);
             const newValue = keepNull ? null : isEmpty(value) || coerceEmptyList ? undefined : value;
             // Set the value on our parent object
+            const changed = !areEqual(newValue, this.value);
             parentInstance[key] = newValue;
             _tick.value++;
             if (opts.refreshing) {
@@ -350,7 +298,7 @@ function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, is
             }
             // If we're being set programmatically, i.e. we don't currently have focus,
             // call blur to trigger any auto-saves.
-            if (!this._focused && !opts.refreshing && !opts.resetting && this.dirty) {
+            if (!this._focused && !opts.refreshing && !opts.resetting && this.dirty && changed && opts.autoSave !== false) {
                 this.blur();
             }
         },
@@ -361,7 +309,7 @@ function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, is
             this.touched = false;
         },
         save() {
-            if (is_plain_object_1.default(this.originalValue)) {
+            if (is_plain_object_1.isPlainObject(this.originalValue)) {
                 this.originalValue = mobx_1.toJS(this.value);
             }
             else {
@@ -590,7 +538,7 @@ function isEmpty(value) {
  *
  */
 function areEqual(a, b) {
-    if (is_plain_object_1.default(a)) {
+    if (is_plain_object_1.isPlainObject(a)) {
         return fast_deep_equal_1.default(mobx_1.toJS(a), mobx_1.toJS(b));
     }
     if (hasToJSON(a) || hasToJSON(b)) {
@@ -606,59 +554,3 @@ function areEqual(a, b) {
 function hasToJSON(o) {
     return !!(o && typeof o === "object" && "toJSON" in o);
 }
-/**
- * Picks ony fields out of `instance` that are in the `formConfig`.
- *
- * This is useful for creating a form input from a GraphQL query result,
- * but ignoring extra data in the query that we don't want/need in the form.
- *
- * (Especially because the form.value will become our mutation's input type
- * that goes on the wire, we don't want superfluous data in it.)
- */
-function pickFields(formConfig, instance) {
-    // If the caller is using classes, i.e. with their own custom observable behavior, then just use as-is
-    if (!is_plain_object_1.default(instance)) {
-        return instance;
-    }
-    return Object.fromEntries(Object.entries(formConfig).map(([key, _keyConfig]) => {
-        const keyConfig = _keyConfig;
-        const value = instance[key];
-        if (keyConfig.type === "object") {
-            if (value) {
-                return [key, pickFields(keyConfig.config, value)];
-            }
-            else {
-                return [key, value];
-            }
-        }
-        else if (keyConfig.type === "list") {
-            if (mobx_1.isObservable(value)) {
-                // If we hit an observable array, leave it as the existing proxy so the our
-                // ListFieldState will react to changes in the original array.
-                return [key, value];
-            }
-            else if (value) {
-                return [key, value.map((u) => pickFields(keyConfig.config, u))];
-            }
-            else {
-                return [key, value];
-            }
-        }
-        else if (keyConfig.type === "value") {
-            return [key, value];
-        }
-        else {
-            return utils_1.assertNever(keyConfig);
-        }
-    }));
-}
-exports.pickFields = pickFields;
-/** Introspects the `init` prop to see if has a `map` function/etc. and returns the form value. */
-function initValue(config, init) {
-    const initValue = init && "input" in init && "map" in init
-        ? init.input
-            ? init.map(init.input)
-            : init.ifUndefined || {}
-        : init || {};
-    return pickFields(config, initValue);
-}