@homebound/form-state 2.9.1 → 2.11.0

package/dist/config.d.ts

@@ -0,0 +1,66 @@
+import { ObjectState } from "./fields/objectField";
+import { Rule } from "./rules";
+import { Builtin } from "./utils";
+/**
+ * Config rules for each field in `T` that we're editing in a form.
+ *
+ * Basically every field is either a value/primitive or a list, and this `ObjectConfig` lets
+ * the caller define field-specific behavior, i.e. validation rules.
+ */
+export declare type ObjectConfig<T> = {
+    [P in keyof OmitIf<T, Function>]: T[P] extends Array<infer U> | null | undefined ? U extends Builtin ? ValueFieldConfig<T, T[P]> : ListFieldConfig<T, U> : ValueFieldConfig<T, T[P]> | ObjectFieldConfig<T[P]>;
+};
+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. */
+export declare type ValueFieldConfig<T, V> = {
+    type: "value";
+    rules?: Rule<T, V | null | undefined>[];
+    /**
+     * If true, marks this field as the id, which will be used for things like "always include in changedValue".
+     *
+     * Defaults to true for fields named `id`.
+     */
+    isIdKey?: boolean;
+    /** If true, and this value is used on an entity in a list, the entity won't count towards the list validity. */
+    isDeleteKey?: boolean;
+    /** If true, the entity that contains this value will be treated as read only. */
+    isReadOnlyKey?: boolean;
+    /**
+     * Marks a field as being backed by a mobx class computed field.
+     *
+     * Note that it might still be settable (some computed have setters), but we do
+     * exclude from the `reset` operation, i.e. we assume resetting other non-computed fields
+     * will effectively reset this field as well.
+     */
+    computed?: boolean;
+    /** Marks a field as being initially read-only, i.e. `field.readOnly = true/false` can change this default. */
+    readOnly?: boolean;
+};
+/** Field configuration for list values, i.e. `U` is `Book` in a form with `books: Book[]`. */
+export declare type ListFieldConfig<T, U> = {
+    type: "list";
+    /** Rules that can run on the full list of children. */
+    rules?: Rule<T, readonly ObjectState<U>[]>[];
+    /** Config for each child's form state, i.e. each book. */
+    config: ObjectConfig<U>;
+    /**
+     * What the server-side update behavior is for this collection.
+     *
+     * When exhaustive, we include all rows in `changedValue` so that we
+     * don't orhan unchanged rows.
+     *
+     * When incremental, we only include changed rows in `changedValue`.
+     *
+     * Defaults to `exhaustive` b/c that is the safest and also Joist's
+     * default behavior.
+     */
+    update?: "exhaustive" | "incremental";
+};
+export declare type ObjectFieldConfig<U> = {
+    type: "object";
+    /** Config for the child's form state, i.e. each book. */
+    config: ObjectConfig<U>;
+};
+export {};

package/dist/config.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/fields/listField.d.ts

@@ -0,0 +1,11 @@
+import { ListFieldConfig, ObjectConfig } from "../config";
+import { ObjectState } from "./objectField";
+import { FieldState } from "./valueField";
+import { Rule } from "../rules";
+/** 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>>;
+    add(value: U, index?: number): void;
+    remove(indexOrValue: number | U): void;
+}
+export declare function newListFieldState<T, K extends keyof T, U>(parentInstance: T, parentState: () => ObjectState<T>, key: K, rules: Rule<T, readonly ObjectState<U>[]>[], listConfig: ListFieldConfig<T, U>, config: ObjectConfig<U>, maybeAutoSave: () => void): ListFieldState<T, U>;

package/dist/fields/listField.js

@@ -0,0 +1,212 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newListFieldState = void 0;
+const mobx_1 = require("mobx");
+const objectField_1 = require("./objectField");
+const rules_1 = require("../rules");
+const utils_1 = require("../utils");
+function newListFieldState(parentInstance, parentState, key, rules, listConfig, config, maybeAutoSave) {
+    // Keep a map of "item in the parent list" -> "that item's ObjectState"
+    const rowMap = new Map();
+    const _tick = mobx_1.observable({ value: 1 });
+    // this is for dirty checking, not object identity
+    let originalCopy = [...(parentInstance[key] || [])];
+    const list = {
+        key: key,
+        // Our fundamental state of wrapped Us
+        get value() {
+            return _tick.value > 0 ? parentInstance[key] : utils_1.fail();
+        },
+        _focused: false,
+        _readOnly: false,
+        _loading: false,
+        get readOnly() {
+            return this._readOnly || parentState().readOnly;
+        },
+        set readOnly(readOnly) {
+            this._readOnly = readOnly;
+        },
+        get loading() {
+            return this._loading || parentState().loading;
+        },
+        set loading(loading) {
+            this._loading = loading;
+        },
+        set value(v) {
+            this.set(v);
+        },
+        get dirty() {
+            return this.rows.some((r) => r.dirty) || this.hasNewItems();
+        },
+        get required() {
+            return this.rules.some((rule) => rule === rules_1.required);
+        },
+        get isNewEntity() {
+            return parentState().isNewEntity;
+        },
+        // private
+        hasNewItems() {
+            const [current, original] = [this.value || [], originalCopy || []];
+            // Instead of relying on just object identities, we look up each child's state
+            // in rowMap, because we already dedup/check object identity (i.e. look for id fields)
+            // when create object states.
+            const a = current.every((e) => {
+                const state = rowMap.get(e);
+                return original.some((e) => rowMap.get(e) === state);
+            });
+            const b = original.every((e) => {
+                const state = rowMap.get(e);
+                return current.some((e) => rowMap.get(e) === state);
+            });
+            const isSame = a && b;
+            return !isSame;
+        },
+        // And we can derive each value's ObjectState wrapper as needed from the rowMap cache
+        get rows() {
+            // It's unclear why we need to access _tick.value here, b/c calling `this.value` should
+            // transitively register us as a dependency on it
+            if (_tick.value < 0)
+                utils_1.fail();
+            return (this.value || []).map((child) => {
+                // Because we're reading from this.value, child will be the proxy version
+                let childState = rowMap.get(child);
+                if (!childState) {
+                    childState = objectField_1.newObjectState(config, parentState, list, child, undefined, maybeAutoSave);
+                    rowMap.set(child, childState);
+                }
+                return childState;
+            });
+        },
+        // TODO Should this be true when all rows are touched?
+        get touched() {
+            return this.rows.some((r) => r.touched) || this.hasNewItems();
+        },
+        set touched(touched) {
+            this.rows.forEach((r) => (r.touched = touched));
+        },
+        rules,
+        get valid() {
+            const value = this.rows;
+            // TODO Passing `originalCopy || []` is probably not 100% right
+            const opts = { value, key: key, originalValue: originalCopy || [], object: parentState() };
+            const collectionValid = this.rules.every((r) => r(opts) === undefined);
+            const entriesValid = this.rows.filter((r) => !r._considerDeleted()).every((r) => r.valid);
+            return collectionValid && entriesValid;
+        },
+        get errors() {
+            if (_tick.value < 0)
+                utils_1.fail();
+            const opts = { value: this.rows, key: key, originalValue: originalCopy || [], object: parentState() };
+            return this.rules.map((r) => r(opts)).filter(utils_1.isNotUndefined);
+        },
+        get changedValue() {
+            const result = [];
+            const hasOpKey = Object.keys(listConfig.config).includes("op");
+            const hasLegacyOpKey = Object.keys(listConfig.config).some((key) => key === "delete" || key === "remove");
+            const incremental = listConfig.update === "incremental" ||
+                // Implicitly enable incremental mode if we see an op key
+                (listConfig.update === undefined && (hasOpKey || hasLegacyOpKey));
+            const exhaustive = !incremental;
+            this.rows.forEach((r) => {
+                var _a;
+                var _b;
+                if (exhaustive || r.dirty || r.isNewEntity) {
+                    const changed = r.changedValue;
+                    // Ensure we have an `op: include` key, following https://joist-orm.io/docs/features/partial-update-apis
+                    if (incremental && hasOpKey) {
+                        (_a = (_b = changed).op) !== null && _a !== void 0 ? _a : (_b.op = "include");
+                    }
+                    result.push(changed);
+                }
+            });
+            return result;
+        },
+        focus() {
+            this._focused = true;
+        },
+        blur() {
+            this._focused = false;
+            this.maybeAutoSave();
+        },
+        maybeAutoSave() {
+            this.touched = true;
+            maybeAutoSave();
+        },
+        set(values, opts = {}) {
+            if (this.readOnly && !opts.resetting && !opts.refreshing) {
+                throw new Error(`${key} is currently readOnly`);
+            }
+            // We should be passed values that are non-proxies.
+            parentInstance[key] = values.map((value) => {
+                let childState = rowMap.get(value);
+                if (!childState) {
+                    // Look for an existing child (requires having an id key configured)
+                    for (const [, otherState] of rowMap.entries()) {
+                        if (otherState.isSameEntity(value)) {
+                            otherState.set(value, opts);
+                            rowMap.set(value, otherState);
+                            return otherState.value;
+                        }
+                    }
+                    // If we didn't have an existing child, just make a new object state
+                    childState = objectField_1.createObjectState(config, value, { maybeAutoSave });
+                    rowMap.set(value, childState);
+                }
+                // Return the already-observable'd value so that our `parent.value[key] = values` doesn't re-proxy things
+                return childState.value;
+            });
+            // Reset originalCopy so that our dirty checks have the right # of rows.
+            if (opts.refreshing) {
+                originalCopy = [...(parentInstance[key] || [])];
+            }
+            _tick.value++;
+        },
+        add(value, spliceIndex) {
+            // This is called by the user, so value should be a non-proxy value we should keep
+            const childState = objectField_1.createObjectState(config, value, { maybeAutoSave });
+            rowMap.set(value, childState);
+            this.ensureSet();
+            this.value.splice(typeof spliceIndex === "number" ? spliceIndex : this.value.length, 0, childState.value);
+            _tick.value++;
+            maybeAutoSave();
+        },
+        remove(indexOrValue) {
+            this.ensureSet();
+            if (typeof indexOrValue === "number") {
+                this.value.splice(indexOrValue, 1);
+            }
+            else {
+                const index = this.value.findIndex((v) => v === indexOrValue);
+                if (index > -1) {
+                    this.value.splice(index, 1);
+                }
+            }
+            _tick.value++;
+            maybeAutoSave();
+        },
+        reset() {
+            if (originalCopy) {
+                this.set(originalCopy, { resetting: true });
+                this.rows.forEach((r) => r.reset());
+            }
+        },
+        save() {
+            this.rows.forEach((r) => {
+                r.save();
+            });
+            originalCopy = [...(parentInstance[key] || [])];
+            _tick.value++;
+        },
+        ensureSet() {
+            if (!parentInstance[key]) {
+                parentInstance[key] = [];
+            }
+            _tick.value++;
+        },
+    };
+    return mobx_1.makeAutoObservable(list, {
+        // See other makeAutoObservable comment
+        value: mobx_1.computed({ equals: () => false }),
+    });
+}
+exports.newListFieldState = newListFieldState;

package/dist/fields/objectField.d.ts

@@ -0,0 +1,54 @@
+import { ObjectConfig } from "../config";
+import { ListFieldState } from "./listField";
+import { FieldState, InternalSetOpts, SetOpts } from "./valueField";
+import { Builtin } from "../utils";
+/**
+ * Wraps a given input/on-the-wire type `T` for editing in a form.
+ *
+ * We basically mimic every field in `T` (i.e. `firstName`, `lastName`, etc.) but decorate them
+ * with form-specific state like `touched`, `dirty`, `errors`, etc.
+ *
+ * The intent is that, after ensuring all fields are `valid`/etc., callers can take the
+ * result of this `objectState.value` (or `objectState.originalValue` for the non-proxy version) and
+ * have exactly the on-the-wire type `T` that they need to submit to the backend, without doing the
+ * manual mapping of "data that was in the form controls" into "data that the backend wants".
+ *
+ * Note that this can be hierarchical by having by having a field of `ListFieldState` that
+ * themselves each wrap an `ObjectState`, i.e.:
+ *
+ * ```
+ * ObjectState for author
+ *   - firstName: FieldState
+ *   - lastName: FieldState
+ *   - rows: ListFieldState
+ *     - [0]: ObjectState for book 1
+ *       - title: FieldState
+ *     - [1]: ObjectState for book 2
+ *       - title: FieldState
+ * ```
+ */
+export declare type ObjectState<T, P = any> = FieldStates<T> & FieldState<P, T> & {
+    /** Sets the state of fields in `state`. */
+    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;
+};
+export declare type ObjectStateInternal<T, P = any> = ObjectState<T, P> & {
+    set(value: P, opts?: InternalSetOpts): void;
+};
+/** For a given input type `T`, decorate each field into the "field state" type that holds our form-relevant state, i.e. valid/touched/etc. */
+declare type FieldStates<T> = {
+    [K in keyof T]-?: T[K] extends Array<infer U> | null | undefined ? [U] extends [Builtin] ? FieldState<T, T[K]> : ListFieldState<T, U> : T[K] extends Builtin | null | undefined ? FieldState<T, T[K]> : ObjectState<T[K], T>;
+};
+/**
+ * Creates a new `ObjectState` for a given form object `T` given config rules in `config`.
+ *
+ * The returned `ObjectState` can be used in a mobx `useLocalObservable` to drive an
+ * interactive form that tracks the current valid/touched/etc. state of both each
+ * individual fields as well as the top-level form/object itself.
+ */
+export declare function createObjectState<T>(config: ObjectConfig<T>, instance: T, opts?: {
+    maybeAutoSave?: () => void;
+}): ObjectState<T>;
+export declare function newObjectState<T, P = any>(config: ObjectConfig<T>, parentState: (() => ObjectState<P>) | undefined, parentListState: FieldState<any, any> | undefined, instance: T, key: keyof T | undefined, maybeAutoSave: () => void): ObjectState<T, P>;
+export {};

package/dist/fields/objectField.js

@@ -0,0 +1,187 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.newObjectState = exports.createObjectState = void 0;
+const mobx_1 = require("mobx");
+const listField_1 = require("./listField");
+const valueField_1 = require("./valueField");
+const utils_1 = require("../utils");
+/**
+ * Creates a new `ObjectState` for a given form object `T` given config rules in `config`.
+ *
+ * The returned `ObjectState` can be used in a mobx `useLocalObservable` to drive an
+ * interactive form that tracks the current valid/touched/etc. state of both each
+ * individual fields as well as the top-level form/object itself.
+ */
+function createObjectState(config, instance, opts = {}) {
+    const noop = () => { };
+    return newObjectState(config, undefined, undefined, instance, undefined, opts.maybeAutoSave || noop);
+}
+exports.createObjectState = createObjectState;
+function newObjectState(config, parentState, parentListState, instance, key, maybeAutoSave) {
+    // This is what we return, but we only know it's value until we call `observable`, so
+    // we create a mutable variable to capture it so that we can create fields/call their
+    // constructors and give them a way to access it later.
+    let proxy = undefined;
+    function getObjectState() {
+        if (!proxy) {
+            throw new Error("Race condition");
+        }
+        return proxy;
+    }
+    const fieldStates = Object.entries(config).map(([_key, _config]) => {
+        const key = _key;
+        const config = _config;
+        let field;
+        if (config.type === "value") {
+            field = valueField_1.newValueFieldState(instance, getObjectState, key, config.rules || [], config.isIdKey || key === "id", config.isDeleteKey || false, config.isReadOnlyKey || false, config.computed || false, config.readOnly || false, maybeAutoSave);
+        }
+        else if (config.type === "list") {
+            field = listField_1.newListFieldState(instance, getObjectState, key, config.rules || [], config, config.config, maybeAutoSave);
+        }
+        else if (config.type === "object") {
+            if (!instance[key]) {
+                instance[key] = {};
+            }
+            field = newObjectState(config.config, getObjectState, undefined, instance[key], key, maybeAutoSave);
+        }
+        else {
+            throw new Error("Unsupported");
+        }
+        return [key, field];
+    });
+    // We always return the same `instance` field from our `value` method, but
+    // we want to pretend that it's observable, so use a tick to force it.
+    const _tick = mobx_1.observable({ value: 1 });
+    const fieldNames = Object.keys(config);
+    function getFields(proxyThis) {
+        return fieldNames.map((name) => proxyThis[name]);
+    }
+    const obj = {
+        ...Object.fromEntries(fieldStates),
+        key,
+        get value() {
+            _tick.value > 0 || utils_1.fail();
+            return instance;
+        },
+        set value(value) {
+            this.set(value);
+        },
+        // private
+        _readOnly: false,
+        _loading: false,
+        _considerDeleted() {
+            const deleteField = getFields(this).find((f) => f._isDeleteKey);
+            return !!(deleteField === null || deleteField === void 0 ? void 0 : deleteField.value);
+        },
+        _considerReadOnly() {
+            const readOnlyField = getFields(this).find((f) => f._isReadOnlyKey);
+            return !!(readOnlyField === null || readOnlyField === void 0 ? void 0 : readOnlyField.value);
+        },
+        get touched() {
+            return getFields(this).some((f) => f.touched);
+        },
+        set touched(touched) {
+            getFields(this).forEach((f) => (f.touched = touched));
+        },
+        get readOnly() {
+            return (this._readOnly ||
+                this._considerReadOnly() ||
+                (parentState && parentState().readOnly) ||
+                !!(parentListState === null || parentListState === void 0 ? void 0 : parentListState.readOnly));
+        },
+        set readOnly(readOnly) {
+            this._readOnly = readOnly;
+        },
+        get loading() {
+            return this._loading || (parentState && parentState().loading) || !!(parentListState === null || parentListState === void 0 ? void 0 : parentListState.loading);
+        },
+        set loading(loading) {
+            this._loading = loading;
+        },
+        get valid() {
+            return getFields(this).every((f) => f.valid);
+        },
+        get errors() {
+            return getFields(this).flatMap((f) => f.errors.map((e) => `${f.key}: ${e}`));
+        },
+        get dirty() {
+            return getFields(this).some((f) => f.dirty);
+        },
+        get isNewEntity() {
+            const idField = getFields(this).find((f) => f._isIdKey);
+            // If we're a line item w/o an immediate id field, look in our parent
+            if (!idField && parentState) {
+                return parentState().isNewEntity;
+            }
+            // If there is no id field, assume we're not new
+            return idField !== undefined && (idField.value === null || idField.value === undefined);
+        },
+        canSave() {
+            this.touched = true;
+            return this.valid;
+        },
+        // Accepts new values in bulk, i.e. when setting the form initial state from the backend.
+        set(value, opts = {}) {
+            if (this.readOnly && !opts.resetting && !opts.refreshing) {
+                throw new Error(`${key || "formState"} is currently readOnly`);
+            }
+            getFields(this).forEach((field) => {
+                if (field.key in value) {
+                    field.set(value[field.key], opts);
+                }
+            });
+        },
+        // Resets all fields back to their original values
+        reset() {
+            getFields(this).forEach((f) => f.reset());
+        },
+        // Saves all current values into _originalValue
+        save() {
+            getFields(this).forEach((f) => f.save());
+        },
+        // Create a result that is only populated with changed keys
+        get changedValue() {
+            const result = {};
+            getFields(this).forEach((f) => {
+                if (f.dirty ||
+                    // If the caller used useFormState.ifUndefined to provide some default values, then those keys may not
+                    // look dirty, but if we're new we should include them anyway.
+                    (this.isNewEntity &&
+                        // Unless they're undefined anyway
+                        f.value !== undefined &&
+                        // And unless they're empty sub-objects
+                        !(f.value instanceof Object && Object.entries(f.changedValue).length === 0))) {
+                    result[f.key] = f.changedValue;
+                }
+            });
+            // Ensure we always have the id for updates to work
+            const idField = getFields(this).find((f) => f._isIdKey);
+            if (idField && idField.value !== undefined) {
+                result[idField.key] = idField.value;
+            }
+            return result;
+        },
+        get originalValue() {
+            return instance;
+        },
+        // An internal helper method to see if `other` is for "the same entity" as our current row
+        isSameEntity(other) {
+            const idField = getFields(this).find((f) => f._isIdKey);
+            if (!idField) {
+                return false;
+            }
+            return this[idField.key].value === other[idField.key];
+        },
+    };
+    proxy = mobx_1.makeAutoObservable(obj, {
+        // Use custom equality on `value` that is _never_ equals. This sounds weird, but
+        // because our `value` is always the same `instance` that was passed to `newObjectState`,
+        // to mobx this looks like the value never changes, and it will never invoke observers
+        // even with our tick-based hacks.
+        value: mobx_1.computed({ equals: () => false }),
+    });
+    // Any time a field changes, percolate that change up to us
+    mobx_1.reaction(() => getFields(proxy).map((f) => f.value), () => _tick.value++);
+    return proxy;
+}
+exports.newObjectState = newObjectState;

package/dist/fields/valueField.d.ts

@@ -0,0 +1,59 @@
+import { ObjectState } from "./objectField";
+import { Rule } from "../rules";
+/**
+ * Form state for a primitive field in the form, i.e. its value but also touched/validation/etc. state.
+ *
+ * This API also provides hooks for form elements to call into, i.e. `blur()` and `set(...)` that will
+ * update the field state and re-render, i.e. when including in an `ObjectState`-typed literal that is
+ * an mobx `useLocalObservable`/observable.
+ *
+ * Note that `V` will always have `null | undefined` added to it by `FieldStates`, b/c most form fields
+ * i.e. text boxes, can always be cleared out/deleted.
+ */
+export interface FieldState<T, V> {
+    readonly key: string;
+    value: V;
+    readonly originalValue: V;
+    touched: boolean;
+    readOnly: boolean;
+    loading: boolean;
+    readonly required: boolean;
+    readonly dirty: boolean;
+    readonly valid: boolean;
+    readonly isNewEntity: boolean;
+    rules: Rule<T, V>[];
+    readonly errors: string[];
+    /** Returns a subset of V with only the changed values. Currently not observable. */
+    readonly changedValue: V;
+    /** Focuses the field. Disables changes from `ObjectState.set` calls. */
+    focus(): void;
+    /** Blur marks the field as touched and triggers an auto-save. */
+    blur(): void;
+    /** Triggers an auto-save; the caller (i.e. useFormState) should still dirty & valid check. */
+    maybeAutoSave(): 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;
+}
+/** Internal `.set` opts for conditionally that form-state internally percolates. */
+export 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 function newValueFieldState<T, K extends keyof T>(parentInstance: T, parentState: () => ObjectState<T>, key: K, rules: Rule<T, T[K] | null | undefined>[], isIdKey: boolean, isDeleteKey: boolean, isReadOnlyKey: boolean, computed: boolean, readOnly: boolean, maybeAutoSave: () => void): FieldState<T, T[K] | null | undefined>;