@homebound/form-state 2.9.0 → 2.10.1

package/dist/formState.js

@@ -1,573 +0,0 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.createObjectState = exports.required = void 0;
-const fast_deep_equal_1 = __importDefault(require("fast-deep-equal"));
-const is_plain_object_1 = require("is-plain-object");
-const mobx_1 = require("mobx");
-const utils_1 = require("./utils");
-/** 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)`.
-exports.required = mobx_1.action(({ value: v }) => {
-    const isEmptyString = typeof v === "string" ? v.trim() === "" : false;
-    return v !== undefined && v !== null && !isEmptyString ? undefined : "Required";
-});
-/**
- * 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 driven 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, instance, undefined, opts.maybeAutoSave || noop);
-}
-exports.createObjectState = createObjectState;
-function newObjectState(config, parentState, 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 = 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 = 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, 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,
-        _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();
-        },
-        set readOnly(readOnly) {
-            this._readOnly = readOnly;
-            // Use this.readOnly so we can _considerReadOnly
-            getFields(this).forEach((f) => (f.readOnly = this.readOnly));
-        },
-        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;
-}
-function newValueFieldState(parentInstance, parentState, key, rules, isIdKey, isDeleteKey, isReadOnlyKey, computed, readOnly, maybeAutoSave) {
-    // keep a copy here for reference equality
-    const value = parentInstance[key];
-    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 });
-    const _originalValueTick = mobx_1.observable({ value: 1 });
-    const field = {
-        key,
-        touched: false,
-        /** Configuration readOnly state. Mostly used to determine original state. */
-        _configReadOnly: readOnly,
-        /** Current readOnly value. */
-        _readOnly: readOnly || false,
-        _focused: false,
-        _isIdKey: isIdKey,
-        _isDeleteKey: isDeleteKey,
-        _isReadOnlyKey: isReadOnlyKey,
-        rules,
-        get value() {
-            const value = _tick.value > 0 ? parentInstance[key] : utils_1.fail();
-            // Re-create the `keepNull` logic on sets but for our initial read where our
-            // originalValue is null (empty) but we want to expose it as undefined for
-            // consistency of "empty-ness" to our UI components.
-            return value === null && isEmpty(_originalValue) ? undefined : value;
-        },
-        set value(v) {
-            this.set(v);
-        },
-        get dirty() {
-            return !areEqual(this.originalValue, this.value);
-        },
-        get readOnly() {
-            return this._readOnly;
-        },
-        /**
-         * Field readOnly is only opinionated when set.
-         * - When set to true from FormObject, accept change since true is higher priority.
-         * - When set to false from FormObject, use original (`_configReadOnly`) value.
-         */
-        set readOnly(v) {
-            if (this._configReadOnly === undefined) {
-                this._readOnly = v;
-                return;
-            }
-            if (v) {
-                this._readOnly = v;
-            }
-            else {
-                this._readOnly = this._configReadOnly || false;
-            }
-        },
-        // For primitive fields, the changed value is just the value.
-        get changedValue() {
-            return this.value;
-        },
-        get valid() {
-            const opts = { value: this.value, key: key, originalValue: this.originalValue, object: parentState() };
-            return this.rules.every((r) => r(opts) === undefined);
-        },
-        get errors() {
-            const opts = { value: this.value, key: key, originalValue: this.originalValue, object: parentState() };
-            return this.rules.map((r) => r(opts)).filter(isNotUndefined);
-        },
-        get required() {
-            return this.rules.some((rule) => rule === exports.required);
-        },
-        get isNewEntity() {
-            return parentState().isNewEntity;
-        },
-        focus() {
-            this._focused = true;
-        },
-        blur() {
-            this.maybeAutoSave();
-            this._focused = false;
-        },
-        maybeAutoSave() {
-            // Now that the user is done editing the field (note maybe w/o blurring, i.e. if they hit enter), we sneak in some trim logic
-            this.maybeTrim();
-            // touched is readonly, but we're allowed to change it
-            this.touched = true;
-            maybeAutoSave();
-        },
-        set(value, opts = {}) {
-            if (this.readOnly && !opts.resetting && !opts.refreshing) {
-                throw new Error(`${key} is currently readOnly`);
-            }
-            if (opts.refreshing && this.dirty && this.value !== value) {
-                // 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 not longer dirty.
-                return;
-            }
-            else if (computed && (opts.resetting || opts.refreshing)) {
-                // Computeds can't be either reset or refreshed
-                return;
-            }
-            // If the user has deleted/emptied a value that was originally set, keep it as `null`
-            // so that our partial update to the backend correctly unsets it.
-            const keepNull = !isEmpty(this.originalValue) && isEmpty(value);
-            // If a list of primitives was originally undefined, coerce `[]` to `undefined`
-            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) {
-                this.originalValue = newValue;
-            }
-            // 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 && changed && opts.autoSave !== false) {
-                this.maybeAutoSave();
-            }
-        },
-        reset() {
-            if (!computed) {
-                this.set(this.originalValue, { resetting: true });
-            }
-            this.touched = false;
-        },
-        save() {
-            if (is_plain_object_1.isPlainObject(this.originalValue)) {
-                this.originalValue = mobx_1.toJS(this.value);
-            }
-            else {
-                this.originalValue = this.value;
-            }
-            this.touched = false;
-        },
-        get originalValue() {
-            // A dummy check to for reactivity around our non-proxy value
-            return _originalValueTick.value > -1 ? _originalValue : _originalValue;
-        },
-        set originalValue(v) {
-            _originalValue = v;
-            _originalValueTick.value++;
-        },
-        maybeTrim() {
-            if (typeof this.value === "string") {
-                let newValue = this.value.trim();
-                if (newValue === "") {
-                    newValue = undefined;
-                }
-                if (newValue !== this.value) {
-                    this.set(newValue);
-                }
-            }
-        },
-    };
-    return field;
-}
-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,
-        get readOnly() {
-            return this._readOnly;
-        },
-        set readOnly(readOnly) {
-            this._readOnly = readOnly;
-            this.rows.forEach((r) => (r.readOnly = readOnly));
-        },
-        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 === exports.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 = newObjectState(config, parentState, 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(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 = 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 = 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 }),
-    });
-}
-function isNotUndefined(value) {
-    return value !== undefined;
-}
-function isEmpty(value) {
-    return value === undefined || value === null || value === "";
-}
-/**
- * An equals that does deep-ish equality.
- *
- * We only do non-identity equals for:
- *
- * - "plain" objects that have no custom prototype/i.e. are object literals
- * - objects that implement `toJSON`
- *
- */
-function areEqual(a, b) {
-    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)) {
-        const a1 = hasToJSON(a) ? a.toJSON() : a;
-        const b1 = hasToJSON(b) ? b.toJSON() : b;
-        return fast_deep_equal_1.default(a1, b1);
-    }
-    if (a && b && a instanceof Array && b instanceof Array) {
-        return fast_deep_equal_1.default(a, b);
-    }
-    return a === b;
-}
-function hasToJSON(o) {
-    return !!(o && typeof o === "object" && "toJSON" in o);
-}